Dev

.github/workflows/docs.yml

@@ -0,0 +1,26 @@
+name: 'docs'
+
+on:
+ push:
+ paths:
+ - 'docs/**'
+ - 'pyfpga/project.py'
+ branches:
+ - main
+ - dev
+
+jobs:
+ docs:
+ runs-on: ubuntu-latest
+ steps:
+ - name: Checkout repository
+ uses: actions/checkout@v4
+ - name: Install dependencies
+ run: pip install . && pip install sphinx sphinx-rtd-theme
+ - name: Build documentation
+ run: make docs
+ - name: Deploy to GitHub Pages
+ uses: peaceiris/actions-gh-pages@v4
+ with:
+ github_token: ${{ secrets.GITHUB_TOKEN }}
+ publish_dir: docs/build/html

.github/workflows/lint.yml

@@ -7,13 +7,9 @@ jobs:
  lint:
  runs-on: ubuntu-latest
  steps:
- - uses: actions/checkout@v2
+ - name: Checkout repository
+ uses: actions/checkout@v4
  - name: Install dependencies
- run: |
- pip install pycodestyle
- pip install pylint
- pip install .
- - name: Lint
- run: |
- pycodestyle fpga examples test
- pylint fpga
+ run: pip install pycodestyle pylint
+ - name: Run linters
+ run: make lint

.github/workflows/test.yml

@@ -5,28 +5,29 @@ on:
 
 jobs:
  test:
- runs-on: ubuntu-latest
  strategy:
  matrix:
- python-version: [3.6, 3.7, 3.8, 3.9]
+ os: ['ubuntu', 'windows']
+ pyver: ['3.8', '3.9', '3.10', '3.11', '3.12']
+ exclude:
+ - os: 'windows'
+ pyver: '3.8'
+ - os: 'windows'
+ pyver: '3.9'
+ - os: 'windows'
+ pyver: '3.10'
+ - os: 'windows'
+ pyver: '3.11'
+ runs-on: ${{ matrix.os }}-latest
+ name: ${{ matrix.os }} | ${{ matrix.pyver }}
  steps:
- - uses: actions/checkout@v2
- - name: Set up Python ${{ matrix.python-version }}
- uses: actions/setup-python@v2
+ - name: Checkout repository
+ uses: actions/checkout@v4
+ - name: Set up Python ${{ matrix.pyver }}
+ uses: actions/setup-python@v5
  with:
- python-version: ${{ matrix.python-version }}
+ python-version: ${{ matrix.pyver }}
  - name: Install dependencies
- run: |
- pip install pytest
- pip install .
- - name: Pull container images
- run: |
- docker pull hdlc/prjtrellis
- docker pull hdlc/ghdl:yosys
- docker pull hdlc/icestorm
- docker pull hdlc/nextpnr:ecp5
- docker pull hdlc/nextpnr:ice40
- - name: Test
- run: |
- pytest
- make -C examples
+ run: pip install . && pip install pytest
+ - name: Run tests
+ run: make test

.gitignore

@@ -1,6 +1,5 @@
 *build
 ignore*
+results
 venv
 __pycache__
-*.egg-info
-_theme

Makefile

@@ -1,11 +1,24 @@
 #!/usr/bin/make
 
-check:
- pycodestyle fpga examples test
- pylint -s n fpga
+.PHONY: docs
+
+all: docs lint test
+
+docs:
+ cd docs; make html
+
+lint:
+ pycodestyle pyfpga examples tests
+ pylint -s n pyfpga
  git diff --check --cached
- pytest test
+
+test:
+ pytest
+ cd examples/projects && bash regress.sh --notool
 
 clean:
  py3clean .
- rm -fr build .pytest_cache
+ rm -fr docs/build
+ rm -fr .pytest_cache
+ rm -fr `find . -name results`
+ rm -fr `find . -name __pycache__`

README.md

@@ -1,132 +1,77 @@
 # PyFPGA [![License](https://img.shields.io/badge/License-GPL--3.0-darkgreen?style=flat-square)](LICENSE)
 
-![GDHL](https://img.shields.io/badge/GHDL-last-brightgreen.svg?style=flat-square)
-![icestorm](https://img.shields.io/badge/icestorm-last-brightgreen.svg?style=flat-square)
-![nextpnr](https://img.shields.io/badge/nextpnr-last-brightgreen.svg?style=flat-square)
-![prjtrellis](https://img.shields.io/badge/prjtrellis-last-brightgreen.svg?style=flat-square)
-![Yosys](https://img.shields.io/badge/Yosys-last-brightgreen.svg?style=flat-square)
-
+![Diamond](https://img.shields.io/badge/Diamond-3.13-blue.svg?style=flat-square)
 ![ISE](https://img.shields.io/badge/ISE-14.7-blue.svg?style=flat-square)
-![Libero](https://img.shields.io/badge/Libero--Soc-12.2-blue.svg?style=flat-square)
-![Quartus](https://img.shields.io/badge/Quartus--Prime-19.1-blue.svg?style=flat-square)
-![Vivado](https://img.shields.io/badge/Vivado-2019.2-blue.svg?style=flat-square)
-
-PyFPGA is a **Python** Class for **vendor-independent FPGA development**.
-It allows using **a single project file** and **programmatically** executing
-**synthesis**, **implementation**, generation of **bitstream** and/or
-**transference** to supported boards.
+![Libero](https://img.shields.io/badge/Libero--Soc-2024.1-blue.svg?style=flat-square)
+![Quartus](https://img.shields.io/badge/Quartus--Prime-23.1-blue.svg?style=flat-square)
+![Vivado](https://img.shields.io/badge/Vivado-2022.1-blue.svg?style=flat-square)
 
-- The workflow is command-line centric.
-- It's friendly with *Version Control Systems* and *Continuous Integration* (CI).
-- Allows reproducibility and repeatability.
-- Consumes fewer system resources than GUI based workflows.
+![Openflow](https://img.shields.io/badge/Openflow-GHDL%20%7C%20Yosys%20%7C%20nextpnr%20%7C%20icestorm%20%7C%20prjtrellis-darkgreen.svg?style=flat-square)
 
-Create your custom FPGA Tool using a workflow tailored to your needs!
+PyFPGA is an abstraction layer for working with FPGA development tools in a vendor-agnostic, programmatic way. It is a Python package that provides:
+* One **class** per supported tool for **project creation**, **synthesis**, **place and route**, **bitstream generation**, and **programming**.
+* A set of **command-line helpers** for simple projects or quick evaluations.
 
-> **WARNING:** (2022-05-15) PyFPGA is in the process of being strongly rewritten/simplified.
-> Most changes are internal, but the API (`Project` class) will change.
+With PyFPGA, you can create your own FPGA development workflow tailored to your needs!
 
-## Usage
+Some of its benefits are:
+* It provides a unified API between tools/devices.
+* It's **Version Control Systems** and **Continuous Integration** friendly.
+* It ensures reproducibility and repeatability.
+* It consumes fewer system resources than GUI-based workflows.
 
-A minimal example of how to use PyFPGA:
+## Basic example
 
 ```py
-from fpga import Project
+from pyfpga import Vivado
 
-# Specify the backend tool and an optional project name
-prj = Project('vivado', 'example')
-
-# Set the device/part
+prj = Vivado('example')
 prj.set_part('xc7z010-1-clg400')
-
-# Add HDL sources to the project
-prj.add_files('location1/*.v')
-prj.add_files('location2/top.v')
-
-# Optionally add constraint files to the project
-prj.add_files('location3/example.xdc')
-
-# Set the top-level unit name
+prj.add_vlog('location1/*.v')
+prj.add_vlog('location2/top.v')
+prj.add_cons('location3/example.xdc')
 prj.set_top('Top')
-
-# Generate the bitstream running the tool
-prj.generate()
+prj.make()
 ```
 
-Now, you can read the [docs](https://pyfpga.github.io/pyfpga/) or find
-more examples in subdir [examples](examples).
+The next steps are to read the [docs](https://pyfpga.github.io/pyfpga) or take a look at [examples](examples).
 
-The API implemented by the `Project class` provides:
+## Support
 
-- A constructor where the TOOL must be specified and an optional PROJECT NAME can be indicated
-- Methods to set the target device PART, to add multiple HDL, Constraint and Tcl files to the
- project (in case of VHDL an optional PACKAGE NAME can be specified) and to specify the TOP-LEVEL
-- Methods to specify a different OUTPUT directory or get some project configurations
-- Methods to generate a bitstream and transfer it to a device (running the selected EDA Tool)
-- The capability of specifying an optimization strategy (area, power or speed) when the bitstream
- is generated
-- A method to add Verilog Included File directories
-- A method to specify generics/parameters values
-- Methods to add Tcl commands in up to six different parts of the Flow (workaround for not yet
- implemented features)
-- Optional logging capabilities which include the display of the Tool Execution Time
+PyFPGA is a Python package developed having GNU/Linux platform on mind, but it should run well on any POSIX-compatible OS, and probably others!
+If you encounter compatibility issues, please inform us via the [issues](https://github.com/PyFPGA/pyfpga/issues) tracker.
 
-## Support
+For a comprehensive list of supported tools, features and limitations, please refer to the [tools support](https://pyfpga.github.io/pyfpga/tools.html) page.
 
-PyFPGA is a Python 3 package, which is developed on Debian GNU/Linux.
-It should run on any other POSIX compatible OS and probably also on different OS.
-Should you achieve either success of failure on non-POSIX systems, please let us know through the
-[issue](https://github.com/PyFPGA/pyfpga/issues) tracker.
-
-- The whole development flow (from reading HDL and constraint sources to producing a bitstream)
- can be performed with ISE (Xilinx), Vivado (Xilinx), Quarts Prime (Intel/Altera), Libero-SoC
- (Microsemi) and/or with open-source tools.
-- GDHL (`--synth`) allows converting VHDL sources into a VHDL 1993 netlist.
-- Yosys allows synthesising Verilog and VHDL (using `ghdl-yosys-plugin`) and supports multiple
- output formats: JSON, Verilog, EDIF, etc.
- - nextpnr can be used for implementation of JSON netlists.
- - Also, ISE and Vivado are supported for implementation of Verilog netlists.
-- Transferring bitstreams and programming devices:
- - ISE (Impact) can be used for programming FPGAs and/or memories (BPI and SPI) through JTAG.
- - Vivado, Quartus and iceprog (IceStorm, for ice40 devices) can be used to programming FPGAs.
- - Programming with Libero-SoC and programming ECP5 devices (prjtrellis, openocd) is not yet
- supported.
-
-**Notes:**
-
-- The open-source tools are supported trough container images from the
-[ghdl/docker](https://github.com/ghdl/docker) project, so
-[Docker](https://www.docker.com/) ~~or [Podman](https://podman.io/)~~ must be
-installed. The same workflow can be used in CI services.
-- ISE, Libero-Soc, Quartus Prime and Vivado, must be ready to be executed from
-the terminal (installed and well configured).
+> **NOTE:**
+> PyFPGA assumes that the underlying tools required for operation are ready to be executed from the running terminal.
+> This includes having the tools installed, properly configured and licensed (when needed).
 
 ## Installation
 
-PyFPGA requires Python `>=3.6`. For now, it's only available as a git repository
-hosted on GitHub. It can be installed with pip:
+PyFPGA requires Python>=3.8.
+
+At the moment, it's only available as a git repository hosted on GitHub. It can be installed with pip:
 
 ```
 pip install 'git+https://github.com/PyFPGA/pyfpga#egg=pyfpga'
 ```
 
-> On GNU/Linux, installing pip packages on the system requires `sudo`.
-> Alternatively, use `--local` for installing PyFPGA in your HOME.
-
-You can get a copy of the repository either through git clone or downloading a
-tarball/zipfile:
+Alternatively, you can get a copy of the repository either through git clone or downloading a tarball/zipfile, and then:
 
 ```
 git clone https://github.com/PyFPGA/pyfpga.git
 cd pyfpga
+pip install -e .
 ```
 
-Then, use pip from the root of the repo:
+> With `-e` (`--editable`) your application is installed into site-packages via a kind of symlink.
+> That allows pulling changes through git or changing the branch, avoiding the need to reinstall the package.
 
-```
-pip install -e .
-```
+## Similar projects
 
-> With `-e` (`--editable`) your application is installed into site-packages via
-> a kind of symlink. That allows pulling changes through git or changing the
-> branch, without the need to reinstall the package.
+* [edalize](https://github.com/olofk/edalize): an abstraction library for interfacing EDA tools.
+* [Hdlmake](https://ohwr.org/project/hdl-make): tool for generating multi-purpose makefiles for FPGA projects.
+* HDL On Git ([Hog](https://gitlab.com/hog-cern/Hog)): a set of Tcl/Shell scripts plus a suitable methodology to handle HDL designs in a GitLab repository.
+* IPbus Builder ([IPBB](https://github.com/ipbus/ipbb)): a tool for streamlining the synthesis, implementation and simulation of modular firmware projects over multiple platforms.
+* [tsfpga](https://github.com/tsfpga/tsfpga): a flexible and scalable development platform for modern FPGA projects.