From 884517504ae47e331082f7999c673d9e6dda452c Mon Sep 17 00:00:00 2001 From: Unai Martinez-Corral Date: Tue, 9 Aug 2022 17:58:06 +0200 Subject: [PATCH] docs/f4pga: update Signed-off-by: Unai Martinez-Corral --- docs/f4pga/Deprecated.rst | 3 +- docs/f4pga/Status.rst | 71 +++++++++++++++++++-------------------- docs/f4pga/index.rst | 37 ++++++-------------- docs/references.rst | 8 +++++ 4 files changed, 56 insertions(+), 63 deletions(-) diff --git a/docs/f4pga/Deprecated.rst b/docs/f4pga/Deprecated.rst index d7df40f8b..ad634eef3 100644 --- a/docs/f4pga/Deprecated.rst +++ b/docs/f4pga/Deprecated.rst @@ -5,7 +5,8 @@ Understanding the (deprecated) flow .. IMPORTANT:: This section describes the usage of the now deprecated ``symbiflow_*`` entrypoints/wrappers. - It is provided for backwards compatibility, so that users of the *old* flow can keep using it. + It is provided for :gh:`backwards compatibility `, so + that users of the *old* flow can keep using it. However, it is recommended for new users to use the approach explained in :ref:`pyF4PGA`. This section provides valuable information on how each of the commands used to compile and build diff --git a/docs/f4pga/Status.rst b/docs/f4pga/Status.rst index 264435593..3273781db 100644 --- a/docs/f4pga/Status.rst +++ b/docs/f4pga/Status.rst @@ -1,52 +1,51 @@ Package capability status ######################### -* Architecture support: +* Supports incremental builds. - * Xilinx XC7 (**available** in main branch) +* Supports multiple configurations for a single project. - * Synthesis tool: yosys +* Provides a Python interface to ``F4PGA``, however there's no official API at the moment. - * PnR tool: VPR +Architectures and flows +======================= - * bitstream generation: yes (xcfasm) +Xilinx XC7 +---------- - * used in f4pga-examples: :gh:`yes ` +* Synthesis tool: yosys +* PnR tool: VPR +* bitstream generation: yes (xcfasm) +* used in f4pga-examples: :gh:`yes ` - * Quicklogic EOS-S3 (yosys+VPR flow) (**WIP**, see :ghsharp:`577`) +Quicklogic EOS-S3 +----------------- - * Synthesis tool: yosys +* Synthesis tool: yosys +* PnR tool: VPR +* bitstream generation: yes (qlfasm) +* analysis: ? +* used in f4pga-examples: no - * PnR tool: VPR +Lattice ICE40 +------------- - * bitstream generation: yes (qlfasm) +.. IMPORTANT:: + **WIP** :ghsharp:`585` - * analysis: ? +* Synthesis tool: yosys +* PnR tool: nextpnr +* bitstream generation: yes (icepack) +* used in f4pga-examples: no - * used in f4pga-examples: no +Quicklogic k4n8 +--------------- - * Lattice ICE40 (yosys+nextpnr flow) (**WIP**, see :ghsharp:`585`) +* Synthesis tool: yosys +* PnR tool: VPR +* bitstream generation: yes (qlf_fasm) +* used in f4pga-examples: no - * Synthesis tool: yosys - - * PnR tool: nextpnr - - * bitstream generation: yes (icepack) - - * used in f4pga-examples: no - - * Quicklogic k4n8 (Unverified, not officially supported. Might work after some tinkering.) - - * Synthesis tool: yosys - - * PnR tool: VPR - - * bitstream generation: yes (qlf_fasm) - - * used in f4pga-examples: no - -* Incremental builds support - -* Support for multiple configurations for a single project - -* Can be used as a python interface to _F4PGA_, however there's no official _API_ at the moment. +.. NOTE:: + Unverified, not officially supported. + Might work after some tinkering. diff --git a/docs/f4pga/index.rst b/docs/f4pga/index.rst index 4c95eb6cf..12950c370 100644 --- a/docs/f4pga/index.rst +++ b/docs/f4pga/index.rst @@ -9,7 +9,10 @@ The scope of Python F4PGA is threefold: * Provide a fine-grained *pythonic* interface to the tools and utilities available as either command-line interfaces (CLIs) or application proggraming interfaces (APIs) (either web or through shared libraries). -* Provide a CLI entrypoint covering the whole flows for end-users to produce bitstreams from HDL and/or software sources. + +* Provide a unified CLI front-end covering the whole flows for end-users to produce bitstreams from HDL and/or software sources. + It's meant as a future replacement of the deprecated ``symbiflow_*`` shell scripts. + * Provide a CLI entrypoint for developers contributing to bitstream documentation and testing (continuous integration). .. ATTENTION:: @@ -17,32 +20,14 @@ The scope of Python F4PGA is threefold: Therefore, it's still a *pre-alpha* and the codebase, commands and flows are subject to change. It is strongly suggested not to rely on Python F4PGA until this note is updated/removed. -This is the current in-development FPGA-oriented build system that's provided with f4pga. - -This package aims to provide a unified front-end for executing *verilog-to-bitstream* and -other flows for various FPGA platforms. It's meant as a future replacement of -``symbiflow_*`` shell scripts. - -It contains *EDA* tool wrappers that provide meta-data about the tools, utilities -related to tracking files and inspection of data used within the flows, scripts used by -tools within flows, a dependency resolution algorithm and flow templates for various devices. +``f4pga`` contains *EDA* tool wrappers that provide meta-data about the tools, utilities related to tracking files and +inspection of data used within the flows, scripts used by tools within flows, a dependency resolution algorithm and flow +templates for various devices. The basic usage requires creation of a ``flow.json`` file describing the FPGA-oriented project. -You can take -:gh:`one from the f4pga-examples repository ` -as a reference. Alternatively there's a way to configure a flow with command-line parameters only. - -Once you have your flow created, run ``f4pga build -f flow.json`` to build a default target. - -To learn more about the package and its usage, visit :doc:`Usage`. +See, for instance, example :gh:`xc7/counter_test/flow.json ➚ `. +Alternatively the flow can be configured through CLI arguments only. -References -========== +With a given flow configuration, run ``f4pga build -f flow.json`` builds the default target. -* :gh:`chipsalliance/fpga-tool-perf#390@issuecomment-1023487178 ` -* :ghsharp:`2225` -* :ghsharp:`2371` -* :ghsharp:`2455` -* `F4PGA GSoC 2022 project ideas: Generalization of wrapper scripts for installed F4PGA toolchain and making them OS agnostic `__ -* :gh:`FuseSoc ` | :gh:`Edalize ` -* `Electronic Design Automation Abstraction (EDA²) `__ +See :doc:`Usage` to learn more about ``f4pga``. diff --git a/docs/references.rst b/docs/references.rst index 456331297..d639a6750 100644 --- a/docs/references.rst +++ b/docs/references.rst @@ -6,3 +6,11 @@ References .. bibliography:: :notcited: :labelprefix: R + +f4pga +===== + +* :ghsharp:`530` +* `F4PGA GSoC 2022 project ideas: Generalization of wrapper scripts for installed F4PGA toolchain and making them OS agnostic `__ +* :gh:`FuseSoc ` | :gh:`Edalize ` +* `Electronic Design Automation Abstraction (EDA²) `__