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.