From b200a0e6cd4930b7a9317f9e20196f04a435bb64 Mon Sep 17 00:00:00 2001 From: Unai Martinez-Corral Date: Wed, 16 Mar 2022 01:13:02 +0100 Subject: [PATCH 1/2] docs/how: update Signed-off-by: Unai Martinez-Corral --- docs/_static/images/EDA.svg | 708 ++++++- docs/_static/images/parts.svg | 3251 ++++++++++++++++++++++++++++++++- docs/conf.py | 1 + docs/how.rst | 85 +- 4 files changed, 4001 insertions(+), 44 deletions(-) diff --git a/docs/_static/images/EDA.svg b/docs/_static/images/EDA.svg index ec4b1fa..371174e 100644 --- a/docs/_static/images/EDA.svg +++ b/docs/_static/images/EDA.svg @@ -1 +1,707 @@ - \ No newline at end of file + + + + + + + + + + + + + + Hardware + +Description Languages + + + + + + + + + + + + + + + + + + + + + + + + + Synthesis tools + + + + + + + + + + + + + + + + + + + + + + + + + + + + FPGA tools + + + + + + + + + + + + + + + + + + + + + + + ASIC tools + + + + + + + + + + + + + + + + + + + + + + + Verification, Testing and Simulation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Description + + + + + + + + + + + + + + + + + + + + + + + + + Frontend + + + + + + + + + + + + + + + + + + + + + + Backend + + + + + + + + + + + + + + + + + + + + + + Viewer does not support full SVG 1.1 + + + diff --git a/docs/_static/images/parts.svg b/docs/_static/images/parts.svg index 5d97c92..10d0c36 100644 --- a/docs/_static/images/parts.svg +++ b/docs/_static/images/parts.svg @@ -1 +1,3250 @@ - \ No newline at end of file + + + + + + + + + + + + + + + + + + + + + + + Yosys            +ABC              + + + + YosysABC + + + + + + + + + Verification, Testing and Simulation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Description + + + + + + + + + + + + + + + + + + + + + + + + + Frontend + + + + + + + + + + + + + + + + + + + + + + Backend + + + + + + + + + + + + + + + + + + + + + GHDL + + + + + + + + + + + + + + + + + + Surelog +UHDM + + + + + + + + + + + + + + + + + + + + + + + + + VHDL + + + + + + + + + + + + + + + + + + System Verilog + + + + + + + + + + + + + + + + + + + + + + + + + + + Verilog + + + + + + + + + + + + + + + + + + + + + + + + + + + Project IceStorm + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Project X-Ray + + + + + + + + + + + + + + + + + + + + + + + + + + Project U-Ray + + + + + + + + + + + + + + + + + + + + + + + + + + Project Trellis + + + + + + + + + + + + + + + + + + + + + + + + + + + + QuickLogic DB + + + + + + + + + + + + + + + + + + + + + + + + + + Project Apicula + + + + + + + + + + + + + + + + + + + + + + + + + + + + Project Oxide + + + + + + + + + + + + + + + + + + + + + + + + + + Verilog to Routing + + + + Verilog toRouting + + + + + + + + + nextpnr + + + + + + + + + + + + + + + + + + + + + Amaranth + + + + + + + + + + + + + + + + + + + + + + + + Architecture definitions + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Clash + + + + + + + + + + + + + + + + + + + SpinalHDL + + + + + + + + + + + + + + + + + + + + + + + Chisel + + + + + + + + + + + + + + + + + + + + BlueSpec + + + + + + + + + + + + + + + + + + + + + + migen/Litex + + + + + + + + + + + + + + + + + + + + + + + + + Silice + + + + + + + + + + + + + + + + + + + + Synthesijer + + + + + + + + + + + + + + + + + + + + + + + + + HLS + + + + + + + + + + + + + + + + + PipelineC + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Interchange logical netlist + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + FASM + + + + + + + + + + + + + + + + + + icepack + + + + + + + + + + + + + + + + + + + + + ecppack + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + RapidWright +(Vivado) + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Interchange physical netlist + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Viewer does not support full SVG 1.1 + + + diff --git a/docs/conf.py b/docs/conf.py index 5570609..281dd71 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -140,6 +140,7 @@ man_pages = [ intersphinx_mapping = { "python": ("https://docs.python.org/3/", None), "arch-defs": ("https://f4pga.readthedocs.io/projects/arch-defs/en/latest/", None), + "interchange": ("https://fpga-interchange-schema.readthedocs.io/", None), "fasm": ("https://fasm.readthedocs.io/en/latest/", None), "prjtrellis": ("https://prjtrellis.readthedocs.io/en/latest/", None), "prjxray": ("https://f4pga.readthedocs.io/projects/prjxray/en/latest/", None), diff --git a/docs/how.rst b/docs/how.rst index f29abfe..b66ca85 100644 --- a/docs/how.rst +++ b/docs/how.rst @@ -3,65 +3,66 @@ How it works To understand how F4PGA works, it is best to start with an overview of the general EDA tooling ecosystem and then proceed to see what the F4PGA project consists of. +For both ASIC- and FPGA-oriented EDA tooling, there are three major areas that the workflows need to cover: description, +frontend and backend. -EDA Tooling Ecosystem -===================== +.. image:: _static/images/EDA.svg + :align: center -For both ASIC- and FPGA-oriented EDA tooling, there are three major areas that -the workflow needs to cover: hardware description, frontend and backend. - -Hardware description languages are generally open, with both established HDLs -such as Verilog and VHDL and emerging software-inspired paradigms like -`Chisel `_, -`SpinalHDL `_ or -`Migen `_. -The major problem lies however in the front- and backend, where previously -there was no established standard, vendor-neutral tooling that would cover -all the necessary components for an end-to-end flow. - -This pertains both to ASIC and FPGA workflows, although F4PGA focuses -on the latter (some parts of F4PGA will also be useful in the former). - -.. figure:: _static/images/EDA.svg - -Project structure -================= +Hardware description languages are either established (such as Verilog and `VHDL ➚ `__) or +emerging software-inspired paradigms like +`Chisel ➚ `_, +`SpinalHDL ➚ `_, +`Migen ➚ `_, or +:gh:`Amaranth ➚ `. +Since early 2000s, free and open source tools allow simulating HDLs. +However, for several decades the major problem lied in the frontend and backend, where there was no established +standard vendor-neutral tooling that would cover all the necessary components for an end-to-end flow. +This pertains both to ASIC and FPGA workflows. +Although F4PGA focuses on the latter, some parts of F4PGA will also be useful in the former. To achieve F4PGA's goal of a complete FOSS FPGA toolchain, a number of tools and projects are necessary to provide all the needed components of an end-to-end flow. -Thus, F4PGA serves as an umbrella project for several activities, the central of which pertains to the creation of -so-called FPGA "architecture definitions", i.e. documentation of how specific FPGAs work internally. -More information can be found in the :doc:`F4PGA Architecture Definitions ` project. +The F4PGA toolchains consist of logic synthesis and implementation tools, as well as chip documentation projects for +chips of various vendors. +Thus, F4PGA serves as an umbrella project for several activities. -Those definitions and serve as input to backend tools like :gh:`nextpnr ` and `Verilog to Routing `_, -and frontend tools like `Yosys `_. +.. image:: _static/images/parts.svg + :align: center + +The central resources are the so-called FPGA "architecture definitions" (i.e. documentation of how specific FPGAs work +internally) and the "interchange schema" (for logical and physical netlists). +Those definitions serve as input to frontend and backend tools, such as +`Yosys ➚ `__, +:gh:`nextpnr ➚ ` and `Verilog to Routing ➚ `_. They are created within separate collaborating projects targeting different FPGAs: -* :doc:`Project X-Ray ` for Xilinx 7-Series -* `Project IceStorm ` for Lattice iCE40 -* :doc:`Project Trellis ` for Lattice ECP5 FPGAs +* :doc:`Project X-Ray ➚ ` for Xilinx 7-Series +* `Project IceStorm ➚ `__ for Lattice iCE40 +* :doc:`Project Trellis ➚ ` for Lattice ECP5 FPGAs -.. figure:: _static/images/parts.svg +More information can be found at :doc:`F4PGA Architecture Definitions ➚ ` and :doc:`FPGA Interchange ➚ `. -The F4PGA toolchain consists of logic synthesis and implementation tools, as well as chip documentation projects for -chips of various vendors. To prepare a working bitstream for a particular FPGA chip, the toolchain goes through the following stages: -* First, a description of the FPGA chip is created with the information from the relevant bitstream documentation +* A description of the FPGA chip is created with the information from the relevant bitstream documentation project. - This part is done within the :gh:`F4PGA Architecture Definitions `. + This part is done within the :gh:`F4PGA Architecture Definitions ➚ `. The project prepares information about the timings and resources available in the chip needed at the implementation stage, as well as techmaps for the synthesis tools. -* The second step is logic synthesis. - It is carried out in the Yosys framework, which expresses the input Verilog file by means of the block and connection - types available in the chosen chip. + .. NOTE:: + This stage is typically pre-built and installed as assets. + However, developers contributing to the bitstream documentation might build it. + +* Then, logic synthesis is carried out in the `Yosys ➚ `__ framework, which expresses the + user-provided hardware description by means of the block and connection types available in the chosen chip. * The next step is implementation. - Placement and routing tools put individual blocks from the synthesis description in the specific chip locations and - create paths between them. - To do that, F4PGA uses either :gh:`nextpnr ` or `Verilog to Routing :gh:`. + Placement and routing tools put individual blocks from the synthesis description in specific chip locations and create + paths between them. + To do that, F4PGA uses either :gh:`nextpnr ➚ ` or :gh:`Verilog to Routing ➚ `. * Finally, the design properties are translated into a set of features available in the given FPGA chip. - These features are saved in the :gh:`fasm format `, which is developed as part of F4PGA. - The fasm file is then translated to bitstream using the information from the bitstream documentation projects. + These features are saved in the :gh:`FASM format ➚ `, which is developed as part of F4PGA. + The FASM file is then translated to a bitstream, using the information from the bitstream documentation projects. From c978d0276b86adbb2966e24225bfb0003aad472f Mon Sep 17 00:00:00 2001 From: Unai Martinez-Corral Date: Wed, 16 Mar 2022 04:15:29 +0100 Subject: [PATCH 2/2] docs/glossary: update Signed-off-by: Unai Martinez-Corral --- docs/_static/images/flow.png | Bin 0 -> 10682 bytes docs/_static/images/step.png | Bin 0 -> 11200 bytes docs/_static/images/tool.png | Bin 0 -> 5495 bytes docs/community.rst | 2 + docs/glossary.rst | 127 ++++++++++++++++++++++++++++++++++- 5 files changed, 127 insertions(+), 2 deletions(-) create mode 100644 docs/_static/images/flow.png create mode 100644 docs/_static/images/step.png create mode 100644 docs/_static/images/tool.png diff --git a/docs/_static/images/flow.png b/docs/_static/images/flow.png new file mode 100644 index 0000000000000000000000000000000000000000..1f6e7bbbaff4032f9aee5eb535b8bed6ea50c269 GIT binary patch literal 10682 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 TK9g-glZhewR1r}sY2g1~QUAn$ literal 0 HcmV?d00001 diff --git a/docs/_static/images/step.png b/docs/_static/images/step.png new file mode 100644 index 0000000000000000000000000000000000000000..e63a904e7f79ca6a72e797b8f15ba6acbab62a9d GIT binary patch literal 11200 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
E7P+YO@qU;Hawt#|ySwlNs;~vs4 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 DM)7Dk literal 0 HcmV?d00001 diff --git a/docs/_static/images/tool.png b/docs/_static/images/tool.png new file mode 100644 index 0000000000000000000000000000000000000000..b6cfc4467c7e9cff18c98e87933bb2fd70405be8 GIT binary patch literal 5495 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 or + emerging software-inspired paradigms like + `Chisel ➚ `_, + `SpinalHDL ➚ `_, + `Migen ➚ `_, or + :gh:`Amaranth ➚ `. + + Tool + * A software application available as a CLI entrypoint, a shared library or an (interpreted) script. + + * Within :term:`f4pga `, a *tool* is a Python abstraction that wraps a software application: + + .. image:: _static/images/tool.png + :align: center + + Step + Within :term:`f4pga `, a *step* is a unit of execution, which is characterized by a set of + :term:`dependencies ` and a set of :term:`artifacts `, + and it is composable in a :term:`flow `. + *Steps* might wrap a single or multiple :term:`tools `. + + .. image:: _static/images/step.png + :align: center + + Flow + Within :term:`f4pga `, a *flow* is a :wikipedia:`directed graph ➚ ` of :term:`steps `, which + describes end-to-end sequences to achieve specific tasks. + A *flow* might used as a step within another *flow*. + In such cases, terms *subflow* or *partial flow* are used. + + .. image:: _static/images/flow.png + :align: center + + CLI + A :wikipedia:`Command-Line Interface (CLI) ➚ ` is an application that processes commands to + a computer program in the form of lines of text, typically interactively (through a terminal) or in batch mode + (through scripts). + Most of the applications used in F4PGA are meant to be used through CLIs. + Precisely, :term:`f4pga ` :term:`tools ` provide Python abstractions around the CLIs. + + Module + :ref:`The Python Tutorial » Modules ➚ ` are files containing Python statements and definitions + (variables, functions, clases,...). + The file name is the module name with the suffix ``.py`` appended. + + Within :term:`f4pga `, user-defined *modules* allow extending the built-in :term:`flows ` and + :term:`steps ` to achieve custom and/or complex tasks. + + Dependency + A *dependency* is a prerequisite to execute a :term:`f4pga ` :term:`step ` in a :term:`flow `. + *Dependencies* might be files (such as HDL sources, constraints, etc.), :term:`artifacts ` from previous + *steps* or :term:`tools `. + + Artifact + An *artifact* is a result produced by a :term:`step ` when executed. + Typically, *artifacts* are files and logs generated by the :term:`tools `. + However, within :term:`f4pga ` :term:`flows `, (meta)data can be passed across *steps* without saving + it to disk. + + Target + Within :term:`f4pga `, :term:`flows ` can have multiple leaf *steps*, producing different results off some + shared previous *steps*. + The *target* of a *flow* specifies which *steps* to execute in a run. + + F4PGA + + * *Uppercase*: + + * FOSS Flows For FPGA (F4PGA), the name of the project as a whole. + + * A Workgroup under the CHIPS Alliance. + See :ref:`Community`. + + * *Lowercase*: + + * Python package providing utilities. + + * The main CLI entrypoint provided by the Python package. + + Cache + Within :term:`f4pga `, the content of :term:`dependencies ` and :term:`artifacts ` can + be tracked to optimize consecutive executions of the same :term:`flow `. + The *cache* contains the :wikipedia:`hash ➚ ` of the assets. + + Resolution + Relations between :term:`f4pga ` :term:`steps `, :term:`dependencies ` and :term:`artifacts ` + can get complex easily. + On top of computing the topological sorting, :term:`f4pga ` checks the existence of the assets, and supports + displaying the status. + + Definition + Within :term:`f4pga `, a :term:`flow ` *definition* is the description of which :term:`steps ` + are to be executed and which :term:`dependencies ` and :term:`artifacts ` are to be passed + along. + + Constraints + Set of parameters that allow users to select/specify certain physical characteristics of the FPGA device, such as + the pins/pads or the logic standard to use. + + Project + A set of :term:`HDL` sources, constraints and other assets used in a hardware :term:`design ` or set of + designs. + + Design + Required :term:`HDL` sources, constraints and other assets to execute a :term:`flow ` and achieve a task. + + Configuration + Within :term:`f4pga `, a *project configuration* is the set of parameters needed for executing a + :term:`flow ` on a given :term:`design `. + The *configuration* might be provided through a Python API, or through a file using declarative format (such as JSON, + YAML, INI,...). + + Model + * *Project model*: a generic description of an EDA project, independent of vendor and tools. + It reflects multiple design variants, grouping of source files into file sets or linking testbenches to + components or subsystems in a design. + * *Simulation model*: :term:`HDL ` sources interpreted as programming languages by simulators, which can + generate interpeted or executable :term:`artifacts `. + + Toolchain + :wikipedia:`Toolchain ➚ ` is a generic term used to refer to a set of programming tools used + consecutively to perform a complex software development task.