Merge branch 'dev' into implements-options

.github/workflows/docs.yml

@@ -2,8 +2,11 @@ name: 'docs'
 
 on:
  push:
+ paths:
+ - 'docs/**'
  branches:
-# - main
+ - main
+ - dev
 
 jobs:
  docs:
@@ -19,4 +22,4 @@ jobs:
  uses: peaceiris/actions-gh-pages@v4
  with:
  github_token: ${{ secrets.GITHUB_TOKEN }}
- publish_dir: docs/_build/html
+ publish_dir: docs/build/html

Makefile

@@ -2,6 +2,8 @@
 
 .PHONY: docs
 
+all: docs lint test
+
 docs:
  cd docs; make html
 
@@ -15,11 +17,7 @@ test:
 
 clean:
  py3clean .
- cd docs; make clean
- rm -fr build .pytest_cache
-
-submodule-init:
- git submodule update --init --recursive
-
-submodule-update:
- cd examples/resources; git checkout main; git pull
+ rm -fr docs/build
+ rm -fr .pytest_cache
+ rm -fr `find . -name results`
+ rm -fr `find . -name __pycache__`

docs/Makefile

@@ -1,7 +1,7 @@
 SPHINXOPTS ?=
 SPHINXBUILD ?= sphinx-build
 SOURCEDIR = .
-BUILDDIR = _build
+BUILDDIR = build
 HELPERS = $(BUILDDIR)/hdl2bit $(BUILDDIR)/prj2bit $(BUILDDIR)/bitprog
 
 help:

docs/basic.rst

@@ -4,15 +4,17 @@ Basic usage
 Project Configuration
 ---------------------
 
-The first steps involve importing the necessary module to support the desired tool and instantiating the corresponding *class*:
+The first steps involve importing the necessary module to support the desired tool and instantiating the corresponding ``class``:
 
 .. code-block:: python
 
  from pyfpga.vivado import Vivado
 
  prj = Vivado('PRJNAME', odir='OUTDIR')
 
-In the example, we are using Vivado, specifying the optional parameter *project name* (*tool name* if omitted) and *output directory* (*results* by default).
+In the example, we are using Vivado, specifying the optional parameters
+``project name`` (``tool name`` if omitted) and ``output directory``
+(``results`` by default).
 
 Next step is to specify the target FPGA device:
 
@@ -32,9 +34,8 @@ HDL source files are added using one of the following methods:
  prj.add_vlog('PATH_TO_FILES_GLOB_COMPATIBLE')
  prj.add_slog('PATH_TO_FILES_GLOB_COMPATIBLE')
 
-In these methods, you provide a path to the files. The path can include wildcards (like `*.vhdl`), allowing you to match multiple files at once.
-
-For `add_vhdl`, you can also optionally specify a library name where the files will be included.
+In these methods, you provide a path to the files. The path can include wildcards (like ``*.vhdl``), allowing you to match multiple files at once.
+In case of ``add_vhdl``, you can also optionally specify a library name where the files will be included.
 
 .. note::
 
@@ -43,6 +44,15 @@ For `add_vhdl`, you can also optionally specify a library name where the files w
  .. _glob: https://docs.python.org/3/library/glob.html
  .. _Path: https://docs.python.org/3/library/pathlib.html
 
+.. hint::
+
+ Files are processed in the order they are added. If a file is specified more than once,
+ it is removed from its previous position and placed at the end of the list.
+ This allows you to ensure that a file is processed after others when necessary
+ (e.g., placing a top-level at the end) or to customize options
+ (e.g., removing a VHDL library specification in case of a top-level)
+ when multiple files are added using a wildcard.
+
 Generics/parameters can be specified with:
 
 .. code-block:: python
@@ -82,7 +92,8 @@ After configuring the project, you can run the following to generate a bitstream
 
  prj.make()
 
-By default, this method performs *project creation*, *synthesis*, *place and route*, and *bitstream generation*.
+By default, this method performs **project creation**, **synthesis**, **place and route**,
+and **bitstream generation**.
 However, you can optionally specify both the initial and final stages, as follows:
 
 .. code-block:: python
@@ -100,7 +111,8 @@ However, you can optionally specify both the initial and final stages, as follow
 
 .. note::
 
- After executing this method, you will find the file `<TOOL>.tcl` (or `sh` in some cases) in the output directory.
+ After executing this method, you will find the file ``<TOOL>.tcl``
+ (``<TOOL>.sh`` in some cases) in the output directory.
  For debugging purposes, if things do not work as expected, you can review this file.
 
 Bitstream programming
@@ -112,13 +124,14 @@ The final step is programming the FPGA:
 
  prj.prog('BITSTREAM', 'POSITION')
 
-Both `BITSTREAM` and `POSITION` are optional.
-If `BITSTREAM` is not specified, PyFPGA will attempt to discover it based on project information.
-The `POSITION` parameter is not always required (depends on the tool being used).
+Both ``BITSTREAM`` and ``POSITION`` are optional.
+If ``BITSTREAM`` is not specified, PyFPGA will attempt to discover it based on project information.
+The ``POSITION`` parameter is not always required (depends on the tool being used).
 
 .. note::
 
- After executing this method, you will find the file `<TOOL>prog.tcl` (or `sh` in some cases) in the output directory.
+ After executing this method, you will find the file ``<TOOL>prog.tcl``
+ (``<TOOL>-prog.sh`` in some cases) in the output directory.
  For debugging purposes, if things do not work as expected, you can review this file.
 
 Debugging

docs/conf.py

@@ -8,8 +8,8 @@
 # -- Project information -----------------------------------------------------
 
 project = 'PyFPGA'
-copyright = '2024, Rodrigo Alejandro Melo'
-author = 'Rodrigo Alejandro Melo'
+copyright = '2016-2024, PyFPGA Project'
+author = 'PyFPGA contributors'
 
 # -- General configuration ---------------------------------------------------
 
@@ -31,9 +31,9 @@
  'repositoy': ('https://github.com/PyFPGA/pyfpga/tree/main/%s', None)
 }
 
-exclude_patterns = ['_build', 'wip']
+exclude_patterns = ['build']
 
 # -- Options for HTML output -------------------------------------------------
 
 html_theme = 'sphinx_rtd_theme'
-html_static_path = ['_static']
+html_static_path = ['images']

docs/extending.rst

@@ -1,40 +1,76 @@
 Extending
 =========
 
-1. Add support for the new tool:
+.. note::
 
-.. code-block:: python
+ All <TOOL> classes inherit from ``Project`` (``project.py``).
+
+This is a guide on how to add support for a new TOOL.
+
+Add support for the new tool
+----------------------------
+
+.. code-block:: bash
 
  pyfpga/templates/<NEWTOOL>.jinja
  pyfpga/templates/<NEWTOOL>-prog.jinja
  pyfpga/<NEWTOOL>.py
+ pyfpga/factory.py # UPDATE
+ pyfpga/helpers/prj2bit.py # UPDATE
 
-2. Include the new tool on Factory:
+Add tests and a tool mock-up
+----------------------------
 
-.. code-block:: python
+.. code-block:: bash
 
- pyfpga/factory.py
+ tests/test_tools.py # UPDATE
+ tests/support.py # UPDATE if exceptions are needed
+ tests/mocks/<NEWCOMMAND>
 
-3. Add tests and a tool mock-up:
+Add examples
+------------
 
-.. code-block:: python
+.. code-block:: bash
 
- tests/test_tools.py
- tests/mocks/<NEWTOOL_EXECUTABLE>
+ examples/sources/cons/<NEWBOARD>/timing.<EXT>
+ examples/sources/cons/<NEWBOARD>/clk.<EXT>
+ examples/sources/cons/<NEWBOARD>/led.<EXT>
+ examples/projects/<NEWTOOL>.py
+ examples/projects/regress.sh # UPDATE
+ examples/helpers/<NEWTOOL>.sh
+ examples/hooks/<NEWTOOL>.py # OPTIONAL
 
-4. Updated the project's documentation:
+Verify the code
+---------------
 
-.. code-block:: python
+Run it at the root of the repo.
 
- README.md
- docs
+.. code-block:: bash
 
-5. [OPTIONAL] Add examples:
+ make docs
+ make lint
+ make test
 
-.. code-block:: python
+.. tip::
 
- examples/sources/cons/<NEWBOARD>/timing.<EXT>
- examples/sources/cons/<NEWBOARD>/clk.<EXT>
- examples/sources/cons/<NEWBOARD>/led.<EXT>
- examples/projects/<NEWTOOL>.py
- examples/hooks/<NEWTOOL>.py
+ You can simply run ``make`` to perform all the operations.
+ Running ``make clean`` will remove all the generated files.
+
+Verify the functionality
+------------------------
+
+.. code-block:: bash
+
+ cd examples/projects/
+ bash regress.sh <NEWTOOL>
+ cd ../../tests/
+ python3 support.py --tool <NEWTOOL>
+
+Updated the documentation
+-------------------------
+
+.. code-block:: bash
+
+ README.md
+ docs/intro.rst
+ docs/tools.rst

docs/helpers.rst

@@ -4,14 +4,14 @@ Helpers
 hdl2bit
 -------
 
-.. literalinclude:: _build/hdl2bit
+.. literalinclude:: build/hdl2bit
 
 prj2bit
 -------
 
-.. literalinclude:: _build/prj2bit
+.. literalinclude:: build/prj2bit
 
 bitprog
 -------
 
-.. literalinclude:: _build/bitprog
+.. literalinclude:: build/bitprog

docs/images/Makefile

@@ -0,0 +1,15 @@
+#!/usr/bin/make
+
+FILES = $(wildcard *.dot)
+FILES := $(basename $(FILES))
+FILES := $(addsuffix .svg,$(FILES))
+
+ODIR = .
+
+vpath %.svg $(ODIR)
+
+%.svg: %.dot
+ @mkdir -p $(ODIR)
+ dot -Tsvg $< -o $(ODIR)/$@
+
+all: $(FILES)

docs/images/openflow.dot

@@ -0,0 +1,28 @@
+digraph openflow {
+ graph [ranksep=0.25];
+ node [shape = doublecircle];
+ node [shape = rectangle];
+ GHDL "ghdl-yosys-plugin" Yosys "nextpnr-ice40" "nextpnr-ecp5" icetime icepack iceprog eccpack;
+ node [shape = note ];
+ VHDL Verilog;
+ node [shape = box3d ];
+ ice40;
+ node [shape = oval];
+ "bit-ice40" [label=".bit"];
+ "bit-ecp5" [label=".bit"];
+ VHDL -> {GHDL "ghdl-yosys-plugin"};
+ GHDL -> "ghdl-yosys-plugin";
+ "ghdl-yosys-plugin" -> Yosys;
+ Verilog -> Yosys;
+ Yosys -> ".json";
+ ".json" -> {"nextpnr-ice40" "nextpnr-ecp5"};
+ "nextpnr-ice40" -> ".asc";
+ "nextpnr-ecp5" -> ".config";
+ ".asc" -> {icetime icepack};
+ icepack -> "bit-ice40";
+ "bit-ice40" -> iceprog;
+ iceprog -> ice40;
+ ".config" -> eccpack;
+ eccpack -> "bit-ecp5";
+ {rank = same; GHDL ; "ghdl-yosys-plugin"; Yosys;}
+}