A collection of tools for Project Freedom projects
Project description
pfDevTools
A collection of tools for Project Freedom projects.
Copyright (c) 2023-present Didier Malenfant.
Installation
pfDevTools works on macOS, Linux and Windows.
You can install pfDevTools by typing the following in a terminal window:
pip install pf-dev-tools
See the pre-requisites section below for more info on installing pfDevTools dependencies.
pf Command
pfDevTools's main functionality is centered around the pf
command. It provides tools used for building openFPGA cores and will also eventually be used to build pfx roms.
Usage:
pf <options> command <arguments>
The following options are supported:
--help/-h - Show a help message.
--version/-v - Display the app's version.
--debug/-d - Enable extra debugging information.
clean
command
pf clean
Cleans the local project and deletes any intermediate build files. This should be executed in the same folder as the project's SConstruct
file.
clone
command
pf clone <url> <tag=name> dest_folder
Clones the repo found at url
, optionally at a given tag/branch named name
into the folder dest_folder
. 'url' does not need to be pre-fixed with https://
or post-fixed with .git
.
If url
is missing then github.com/DidierMalenfant/pfCoreTemplate
is used.
convert
command
pf convert src_filename dest_filename
Converts an image to the openFGPA binary format used for core images and author icons.
delete
command
pf delete core_name <dest_volume>
Deletes all core data (bitstream, images, icons, json files) for core named core_name
on volume <dest_volume>.
If dest_volume
is omitted then the command looks for the PF_CORE_INSTALL_VOLUME
environment variable. If this is not defined either then it defaults to /Volumes/POCKET
on macOS and errors out on other platforms.
If another implementation of the core is found then the Platforms files will be kept otherwise they are deleted too.
dryrun
command
pf dryrun
Simulate building the local project. This will give out information on what, if anything, needs to be rebuilt.
This should be executed in the same folder as the project's SConstruct
file.
eject
command
pf eject <dest_volume>
Ejects the volume at dest_volume
. This command is currently only supported on macOS. If dest_volume
is omitted then the command looks for the PF_CORE_INSTALL_VOLUME
environment variable. If this is not defined either then it defaults to /Volumes/POCKET
.
install
command
pf install zip_file <dest_volume>
Installs the packaged core contained in zip_file
onto volume dest_volume
.
If dest_volume
is omitted then the command looks for the PF_CORE_INSTALL_VOLUME
environment variable. If this is not defined either then it defaults to /Volumes/POCKET
on macOS and errors out on other platforms.
make command
pf make
Builds the local project.
This should be executed in the same folder as the project's SConstruct
file.
qfs command
pf qfs qsf_file <cpus=num> files...
Edits a Quartus qfs
project file to add files and set number of cpu for the project. Updates the qfs_file
by adding a list of Verilog .v
or .sv
files
, separated by spaces.
Optionally cpus
can set the number of cpu cores that the compilation process can use.
reverse command
pf reverse src_filename dest_filename
Reverses the bitstream file at src_filename
and writes it to dest_filename
.
Building an openFPGA core
pfDevTools provides an entire toolchain needed to compile openFPGA cores. The build systems is based on the SCons software construction tool which is entirely written in Python.
A typical makefile is named SConstruct
and for openFPGA projects can look as simple as this:
import pfDevTools
# -- We need pf-dev-tools version 1.x.x but at least 1.0.5.
pfDevTools.requires('1.0.5')
env = pfDevTools.SConsEnvironment()
env.OpenFPGACore('src/config.toml')
This will build, using pf make
, a packaged core file based on the toml
config file and the source code found in the src
folder.
All projects should contain at least one core/core_top.v
file at the root of their source tree. The content of this file should be based around Analogue's own core.top.v
file but you do not need to provide any other files or IP found in the core template. Those will be automatically brought in for you during the build.
Good examples of simple core projects can be found in the examples provided as part of the openFPGA tutorials.
The build environment can be customized by passing variables to the pfDevTools.SConsEnvironment()
method call like so:
env = pfDevTools.SConsEnvironment(PF_BUILD_FOLDER='MyBuildFolder', PF_SRC_FOLDER='MySrcFolder')
The following variables are currently supported:
PF_SRC_FOLDER
- Root folder for all the Verilog source files for the project. Defaults to the folder where thetoml
config [file]](#core-config-file-format) is located.PF_BUILD_FOLDER
- Folder where intermediate build files are created. Defaults to_build
.PF_CORE_TEMPLATE_REPO_URL
- Repo url to use instead of the default core template repo atgithub.com/DidierMalenfant/pfCoreTemplate
.PF_CORE_TEMPLATE_REPO_TAG
- Repo tag to use to clone the core template repo.PF_CORE_TEMPLATE_REPO_FOLDER
- Path to a local core template folder to copy instead of cloning a repo.- 'PF_NB_OF_CPUS_TO_USE' - Number of cpu cores that the compilation process can use in parallel.
- 'PF_ENABLE_OPTIMIZATION' - If set to 1 then the core will be compiled using
HIGH PERFORMANCE EFFORT
.
Core config file format
Core configuration is done via a single toml
file like this one:
[Platform]
name = "pfx-1"
image = "assets/pfx1-platform-image.png"
short_name = "pfx1"
category = "Fantasy"
description = "An open-source fantasy gaming console for the Analog Pocket."
info = "info.txt"
[Build]
version = "0.0.5"
[Author]
name = "dm"
icon = "assets/pfx1-core-author-icon.png"
url = "https://didier.malenfant.net/ProjectFreedom/"
[Hardware]
video_width = 400
video_height = 360
video_aspect_w = 10
video_aspect_h = 9
Fields supported in this file will be documented soon!
Pre-requisites
pfDevTools requires at least Python 3.10. Make sure you have a supported version of Python before proceeding.
It also uses the git command. If you're on macOS and Linux this should come already built in.
By default, pfDevTools uses a local install of Intel Quartus to build bitstream files on your machine. You just need to make sure that quartus_sh
is in your PATH
.
Since Quartus is only available on Windows or Linux, or if you want to easily use a different version of Quartus, you can define PF_DOCKER_IMAGE_NAME
in your environment (i.e. export PF_DOCKER_IMAGE_NAME=didiermalenfant/quartus:22.1-apple-silicon
) and the toolchain will switch to using docker instead. If you decide to use docker, you'll need to install Docker Desktop and to make sure the Docker Engine is running while building the core.
If you're running docker on an Apple Silicon Mac, also make sure that Use Virtualization framework
in Settings->General
and Use Rosetta for x86/amd64 emulation on Apple Silicon
in Settings->Features in development
are both enabled in docker's settings. This setting somehow turns itself off sometimes.
Installing Docker on Ubuntu Linux
Make sure that no other version of Docker are installed:
sudo apt-get remove docker docker-engine docker.io containerd runc
Add the docker repository:
sudo apt-get update
sudo apt-get install ca-certificates curl gnupg
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg
echo "deb [arch="$(dpkg --print-architecture)" signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \
"$(. /etc/os-release && echo "$VERSION_CODENAME")" stable" | \
sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
Install the Docker Engine:
sudo apt-get update
sudo apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
In order to be able to run docker
without sudo
, make sure the docker
group exists and add your user to it:
sudo groupadd docker
sudo usermod -aG docker $USER
newgrp docker
You can verify that the Docker Engine installation is successful by running the hello-world
image:
docker run hello-world
Trademarks
openFPGA and the openFPGA logo are trademarks of Analogue Enterprises Ltd. Quartus is a registered trademark of Intel.
This project is not affiliated, associated with, sponsored or supported by neither Analogue nor Intel.
License
pfDevTools is distributed under the terms of the GPLv3.0 or later license.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for pf_dev_tools-1.0.10-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | e105fed350a4bb7362eb6e9969bf030830ed27cf6b2917e6f1111500e07cec0b |
|
MD5 | d9d4b2e14b24e0c7453050e7054d4422 |
|
BLAKE2b-256 | ee26b7c0ed0e3a2f35f6fb535ee367e2158984dd1cef81d014255ad3a4e82353 |