From de1bc377c46f6d464c5e0ee00d34786abdc564bc Mon Sep 17 00:00:00 2001 From: Unai Martinez-Corral Date: Wed, 9 Mar 2022 02:47:32 +0100 Subject: [PATCH 1/9] docs/conf: add ExtLinks Signed-off-by: Unai Martinez-Corral --- docs/conf.py | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/docs/conf.py b/docs/conf.py index 3906f48b2..4302418c8 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -43,6 +43,7 @@ release = '' # The full version, including alpha/beta/rc tags. extensions = [ + 'sphinx.ext.extlinks', 'sphinx.ext.intersphinx', 'sphinx_verilog_domain' ] @@ -140,3 +141,14 @@ "prjxray": ("https://f4pga.readthedocs.io/projects/prjxray/en/latest/", None), "vtr": ("https://docs.verilogtorouting.org/en/latest/", None), } + +# -- Sphinx.Ext.ExtLinks ----------------------------------------------------------------------------------------------- + +extlinks = { + 'wikipedia': ('https://en.wikipedia.org/wiki/%s', 'wikipedia:'), + 'gh': ('https://github.com/%s', 'gh:'), + 'ghsharp': ('https://github.com/chipsalliance/f4pga/issues/%s', '#'), + 'ghissue': ('https://github.com/chipsalliance/f4pga/issues/%s', 'issue #'), + 'ghpull': ('https://github.com/chipsalliance/f4pga/pull/%s', 'pull request #'), + 'ghsrc': ('https://github.com/chipsalliance/f4pga/blob/master/%s', '') +} From 4bb5d816f3c9a02aa31a7af16aa09310ade214d6 Mon Sep 17 00:00:00 2001 From: Unai Martinez-Corral Date: Sun, 13 Mar 2022 07:26:03 +0100 Subject: [PATCH 2/9] docs/gitignore: update Signed-off-by: Unai Martinez-Corral --- docs/.gitignore | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/.gitignore b/docs/.gitignore index 17fc96307..5a49d6376 100644 --- a/docs/.gitignore +++ b/docs/.gitignore @@ -1,2 +1,3 @@ /_build/ /env/ +/status.inc From 5427bfdaf61df8ae8e51b868c0097f9228f60fd3 Mon Sep 17 00:00:00 2001 From: Unai Martinez-Corral Date: Tue, 15 Mar 2022 22:49:03 +0100 Subject: [PATCH 3/9] docs/getting-started: update refs Signed-off-by: Unai Martinez-Corral --- docs/getting-started.rst | 16 ++++++++++------ docs/index.rst | 3 --- 2 files changed, 10 insertions(+), 9 deletions(-) diff --git a/docs/getting-started.rst b/docs/getting-started.rst index 0f9819da0..38ea1c72c 100644 --- a/docs/getting-started.rst +++ b/docs/getting-started.rst @@ -5,12 +5,16 @@ To begin using F4PGA, you might want to take a look at the tutorials below, whic They will guide you through the process of using the toolchain, explaining how to generate and load a bitstream into your FPGA. -* User guide and examples how to use the toolchain: +* `Examples ➚ `__ (for users) - * `Examples ➚ `__ (for users) - * `Architecture Definitions ➚ `__ (for developers) +* `Architecture Definitions ➚ `__ (for developers) -* Other resources: - - * `X-Ray Quickstart ➚ `__ * `F4PGA Architectures Visualizer ➚ `__ + + * `Project X-Ray ➚ `__ + + * `X-Ray Quickstart ➚ `__ + + * `Project Trellis ➚ `__ + + * `Project Icestorm ➚ `__ diff --git a/docs/index.rst b/docs/index.rst index 50189ca69..81a687dbc 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -34,9 +34,6 @@ The project aim is to design tools that are highly extendable and multiplatform. yosys VPR ➚ - Architecture Definitions ➚ - Project X-Ray ➚ - Project Trellis ➚ .. toctree:: :caption: Contributing From eb948d0b8bd886fb9344931ab5943a19fe4e57d7 Mon Sep 17 00:00:00 2001 From: Unai Martinez-Corral Date: Tue, 15 Mar 2022 22:57:37 +0100 Subject: [PATCH 4/9] docs: use extlinks Signed-off-by: Unai Martinez-Corral --- docs/community.rst | 4 ++-- docs/getting-started.rst | 2 +- docs/how.rst | 22 ++++++++++------------ docs/yosys.rst | 16 +++++++--------- 4 files changed, 20 insertions(+), 24 deletions(-) diff --git a/docs/community.rst b/docs/community.rst index 50d3dd362..af7703496 100644 --- a/docs/community.rst +++ b/docs/community.rst @@ -31,9 +31,9 @@ Communication Souces ====== -* `github.com/chipsalliance `__ +* :gh:`github.com/chipsalliance ` -* `github.com/F4PGA `__ +* :gh:`github.com/F4PGA ` .. _Contributing: diff --git a/docs/getting-started.rst b/docs/getting-started.rst index 38ea1c72c..3da526298 100644 --- a/docs/getting-started.rst +++ b/docs/getting-started.rst @@ -17,4 +17,4 @@ your FPGA. * `Project Trellis ➚ `__ - * `Project Icestorm ➚ `__ + * :gh:`Project Icestorm ➚ ` diff --git a/docs/how.rst b/docs/how.rst index ab5735307..f29abfe5e 100644 --- a/docs/how.rst +++ b/docs/how.rst @@ -33,14 +33,13 @@ Thus, F4PGA serves as an umbrella project for several activities, the central 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. -Those definitions and serve as input to backend tools like -`nextpnr `_ and -`Verilog to Routing `_, and frontend tools -like `Yosys `_. They are created within separate -collaborating projects targeting different FPGAs - :doc:`Project X-Ray -` for Xilinx 7-Series, `Project IceStorm -`_ for Lattice iCE40 and :doc:`Project Trellis -` for Lattice ECP5 FPGAs. +Those definitions and serve as input to backend tools like :gh:`nextpnr ` and `Verilog to Routing `_, +and frontend tools like `Yosys `_. +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 .. figure:: _static/images/parts.svg @@ -50,7 +49,7 @@ To prepare a working bitstream for a particular FPGA chip, the toolchain goes th * First, a description of the FPGA chip is created with the information from the relevant bitstream documentation project. - This part is done within the `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. @@ -61,9 +60,8 @@ To prepare a working bitstream for a particular FPGA chip, the toolchain goes th * 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 `nextpnr `__ or `Verilog to Routing `__. + To do that, F4PGA uses either :gh:`nextpnr ` or `Verilog to Routing :gh:`. * Finally, the design properties are translated into a set of features available in the given FPGA chip. - These features are saved in the `fasm format `__, which is developed as part of - F4PGA. + 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. diff --git a/docs/yosys.rst b/docs/yosys.rst index da95de1cd..3e29ef40d 100644 --- a/docs/yosys.rst +++ b/docs/yosys.rst @@ -57,15 +57,13 @@ An example configuration script can be found below: write_blif -attr -cname -param $::env(OUT_EBLIF) write_verilog $::env(OUT_SYNTH_V) -It can be seen that this script performs a platform-specific process of -synthesis, some optimization steps (``opt_`` commands), and writes the final file in -``.eblif`` and Verilog formats. Yosys synthesis configuration scripts are platform-specific -and can by found in ``/yosys/synth.tcl`` -in the `F4PGA Architecture Definitions `_ -repository. - -To understand performed operations, view the log file. It is usually generated -in the project build directory. It should be named ``top.eblif.log``. +It can be seen that this script performs a platform-specific process of synthesis, some optimization steps (``opt_`` +commands), and writes the final file in ``.eblif`` and Verilog formats. +Yosys synthesis configuration scripts are platform-specific and can by found in ``/yosys/synth.tcl`` in +the :gh:`F4PGA Architecture Definitions ` repository. + +To understand performed operations, view the log file. +It is usually generated in the project build directory. It should be named ``top.eblif.log``. Output analysis --------------- From f64a62082fd96c6a0a06267afe6d4f7ca7b7305e Mon Sep 17 00:00:00 2001 From: Unai Martinez-Corral Date: Tue, 15 Mar 2022 23:09:50 +0100 Subject: [PATCH 5/9] docs: move yosys and vpr into flows/f4pga Signed-off-by: Unai Martinez-Corral --- docs/flows/f4pga.rst | 416 ++++++++++++++++++++++++++++++++++++++++++- docs/index.rst | 6 - docs/yosys.rst | 404 ----------------------------------------- 3 files changed, 414 insertions(+), 412 deletions(-) delete mode 100644 docs/yosys.rst diff --git a/docs/flows/f4pga.rst b/docs/flows/f4pga.rst index 7caa1bec1..e9cc622b3 100644 --- a/docs/flows/f4pga.rst +++ b/docs/flows/f4pga.rst @@ -2,14 +2,426 @@ In F4PGA ######## Synthesis -========= +********* In the F4PGA toolchain synthesis is made with the use of Yosys, that is able to perform all the mentioned steps and convert HDL to netlist description. The result of these steps is written to a file in ``.eblif`` format. +Yosys +===== + +Yosys is a Free and Open Source Verilog HDL synthesis tool. +It was designed to be highly extensible and multiplatform. +In F4PGA toolchain, it is responsible for the whole synthesis process described in `FPGA Design Flow <./design-flow.html>`_ + +It is not necessary to call Yosys directly using F4PGA. +Nevertheless, the following description, should provide sufficient introduction to Yosys usage inside the project. +It is also a good starting point for a deeper understanding of the whole toolchain. + +Short description +----------------- + +Yosys consists of several subsystems. Most distinguishable are the first and last ones used in the synthesis process, +called *frontend* and *backend* respectively. +Intermediate subsystems are called *passes*. + +The *frontend* is responsible for changing the Verilog input file into an internal Yosys, representation which is common +for all *passes* used by the program. +The *passes* are responsible for a variety of optimizations (``opt_``) and simplifications (``proc_``). + +Two *passes*, that are worth to mention separately are ``ABC`` and ``techmap``. +The first one optimizes logic functions from the design and assigns obtained results into Look Up Tables (LUTs) of +chosen width. +The second mentioned *pass* - ``techmap`` is responsible for mapping the synthesized design from Yosys internal blocks +to the primitives used by the implementation tool. +Recommended synthesis flows for different FPGAs are combined into macros i.e. ``synth_ice40`` (for Lattice iCE40 FPGA) +or ``synth_xilinx`` (for Xilinx 7-series FPGAs). + +The *backend* on the other hand, is responsible for converting internal Yosys representation into one of the +standardized formats. +F4PGA uses ``.eblif`` as its output file format. + +Usage in Toolchain +------------------ + +All operations performed by Yosys are written in ``.tcl`` script. Commands used +in the scripts are responsible for preparing output file to match with the +expectations of other toolchain tools. +There is no need to change it even for big designs. +An example configuration script can be found below: + +.. code-block:: tcl + + yosys -import + + synth_ice40 -nocarry + + opt_expr -undriven + opt_clean + + setundef -zero -params + write_blif -attr -cname -param $::env(OUT_EBLIF) + write_verilog $::env(OUT_SYNTH_V) + +It can be seen that this script performs a platform-specific process of synthesis, some optimization steps (``opt_`` +commands), and writes the final file in ``.eblif`` and Verilog formats. +Yosys synthesis configuration scripts are platform-specific and can by found in ``/yosys/synth.tcl`` in +the :gh:`F4PGA Architecture Definitions ` repository. + +To understand performed operations, view the log file. +It is usually generated in the project build directory. It should be named ``top.eblif.log``. + +Output analysis +--------------- + +Input file: + +.. code-block:: verilog + + module top ( + input clk, + output LD7, + ); + localparam BITS = 1; + localparam LOG2DELAY = 25; + + reg [BITS+LOG2DELAY-1:0] counter = 0; + always @(posedge clk) begin + counter <= counter + 1; + end + + assign {LD7} = counter >> LOG2DELAY; + endmodule + + +after synthesis is described only with use of primitives appropriate for +chosen platform: + +.. code-block:: verilog + + module top(clk, LD7); + wire [25:0] _000_; + wire _001_; + + ... + + FDRE_ZINI #( + .IS_C_INVERTED(1'h0), + .ZINI(1'h1) + ) _073_ ( + .C(clk), + .CE(_012_), + .D(_000_[0]), + .Q(counter[0]), + .R(_013_) + ); + + ... + + SR_GND _150_ ( + .GND(_062_) + ); + assign _003_[25:0] = _000_; + assign counter[25] = LD7; + endmodule + +The same structure is described by the ``.eblif`` file. + + +Technology mapping in F4PGA toolchain +------------------------------------- + +.. _Xilinx 7 Series FPGAs Clocking Resources User Guide: https://www.xilinx.com/support/documentation/user_guides/ug472_7Series_Clocking.pdf#page=38 +.. _VTR FPGA Architecture Description: https://docs.verilogtorouting.org/en/latest/arch/ +.. _techmap section in the Yosys Manual: http://www.clifford.at/yosys/files/yosys_manual.pdf#page=153 + +It is important to understand the connection between the synthesis and +implementation tools used in the F4PGA toolchain. As mentioned before, +synthesis tools like Yosys take the design description from the source files +and convert them into a netlist that consists of the primitives used by +the implementation tool. Usually, to support multiple implementation tools, +an additional intermediate representation of FPGA primitives is provided. +The process of translating the primitives from the synthesis +tool’s internal representation to the specific primitives used in the +implementation tools is called technology mapping (or techmapping). + +Technology mapping for VPR +-------------------------- + +As mentioned before, VPR is one of the implementation tools (often referred to +as Place & Route or P&R tools) used in F4PGA. By default, the F4PGA +toolchain uses it during bitstream generation for, i.e., Xilinx 7-Series +devices. Since the architecture models for this FPGA family were created from +scratch, appropriate techmaps were needed to instruct Yosys on translating +the primitives to the versions compatible with VPR. + +The clock buffers used in the 7-Series devices are a good example for explaining +the techmapping process. Generally, as stated in the +`Xilinx 7 Series FPGAs Clocking Resources User Guide`_, a designer has various +buffer types that they can use in designs: + +- ``BUFGCTRL`` +- ``BUFG`` +- ``BUFGCE`` +- ``BUFGCE_1`` +- ``BUFGMUX`` +- ``BUFGMUX_1`` +- ``BUFGMUX_CTRL`` + +Nevertheless, the actual chips consist only of the ``BUFGCTRL`` primitives, +which are the most universal and can function as other clock buffer +primitives from the Xilinx manual. Because of that, only one architecture model +is required for VPR. The rest of the primitives is mapped to this general +buffer during the techmapping process. The model of ``BUFGCTRL`` primitive used +by VPR is called ``BUFGCTR_VPR`` (More information about the architecture +modeling in VPR can be found in the `VTR FPGA Architecture Description`_). + +Support for particular primitive in VTR consist of two files: + +- Model XML (``xxx.model.xml``) - Contains general information about + the module's input and output ports and their relations. + +- Physical Block XML (``xxx.pb_type.xml``) - Describes the actual layout of the + primitive, with information about the timings, internal connections, etc. + +Below you can see the pb_type XML for ``BUFGCTRL_VPR`` primitive: + +.. code-block:: xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + ZPRESELECT_I0 = ZPRESELECT_I0 + ZPRESELECT_I1 = ZPRESELECT_I1 + IS_IGNORE0_INVERTED = IS_IGNORE0_INVERTED + IS_IGNORE1_INVERTED = IS_IGNORE1_INVERTED + ZINV_CE0 = ZINV_CE0 + ZINV_CE1 = ZINV_CE1 + ZINV_S0 = ZINV_S0 + ZINV_S1 = ZINV_S1 + + + + + + + + + + + + + + + + + + IN_USE + + + + + +A correctly prepared techmap for any VPR model contains a declaration of +the module that should be substituted. Inside the module declaration, one +should provide a necessary logic and instantiate another module that +will substitute its original version. Additionally, all equations within +a techmap that are not used directly in a module instantiation should evaluate +to a constant value. Therefore most of the techmaps use additional constant +parameters to modify the signals attached to the instantiated module. + +Here is a piece of a techmap, which instructs Yosys to convert +a ``BUFG`` primitive to the ``BUFGCTRL_VPR``. In this case, the techmaping process +consists of two steps. Firstly, the techmap shows how to translate the ``BUFG`` +primitive to the ``BUFGCTRL``. Then how to translate the ``BUFGCTRL`` to +the ``BUFGCTRL_VPR``: + +.. code-block:: verilog + + module BUFG ( + input I, + output O + ); + + BUFGCTRL _TECHMAP_REPLACE_ ( + .O(O), + .CE0(1'b1), + .CE1(1'b0), + .I0(I), + .I1(1'b1), + .IGNORE0(1'b0), + .IGNORE1(1'b1), + .S0(1'b1), + .S1(1'b0) + ); + endmodule + + module BUFGCTRL ( + output O, + input I0, input I1, + input S0, input S1, + input CE0, input CE1, + input IGNORE0, input IGNORE1 + ); + + parameter [0:0] INIT_OUT = 1'b0; + parameter [0:0] PRESELECT_I0 = 1'b0; + parameter [0:0] PRESELECT_I1 = 1'b0; + parameter [0:0] IS_IGNORE0_INVERTED = 1'b0; + parameter [0:0] IS_IGNORE1_INVERTED = 1'b0; + parameter [0:0] IS_CE0_INVERTED = 1'b0; + parameter [0:0] IS_CE1_INVERTED = 1'b0; + parameter [0:0] IS_S0_INVERTED = 1'b0; + parameter [0:0] IS_S1_INVERTED = 1'b0; + + parameter _TECHMAP_CONSTMSK_IGNORE0_ = 0; + parameter _TECHMAP_CONSTVAL_IGNORE0_ = 0; + parameter _TECHMAP_CONSTMSK_IGNORE1_ = 0; + parameter _TECHMAP_CONSTVAL_IGNORE1_ = 0; + parameter _TECHMAP_CONSTMSK_CE0_ = 0; + parameter _TECHMAP_CONSTVAL_CE0_ = 0; + parameter _TECHMAP_CONSTMSK_CE1_ = 0; + parameter _TECHMAP_CONSTVAL_CE1_ = 0; + parameter _TECHMAP_CONSTMSK_S0_ = 0; + parameter _TECHMAP_CONSTVAL_S0_ = 0; + parameter _TECHMAP_CONSTMSK_S1_ = 0; + parameter _TECHMAP_CONSTVAL_S1_ = 0; + + localparam [0:0] INV_IGNORE0 = ( + _TECHMAP_CONSTMSK_IGNORE0_ == 1 && + _TECHMAP_CONSTVAL_IGNORE0_ == 0 && + IS_IGNORE0_INVERTED == 0); + localparam [0:0] INV_IGNORE1 = ( + _TECHMAP_CONSTMSK_IGNORE1_ == 1 && + _TECHMAP_CONSTVAL_IGNORE1_ == 0 && + IS_IGNORE1_INVERTED == 0); + localparam [0:0] INV_CE0 = ( + _TECHMAP_CONSTMSK_CE0_ == 1 && + _TECHMAP_CONSTVAL_CE0_ == 0 && + IS_CE0_INVERTED == 0); + localparam [0:0] INV_CE1 = ( + _TECHMAP_CONSTMSK_CE1_ == 1 && + _TECHMAP_CONSTVAL_CE1_ == 0 && + IS_CE1_INVERTED == 0); + localparam [0:0] INV_S0 = ( + _TECHMAP_CONSTMSK_S0_ == 1 && + _TECHMAP_CONSTVAL_S0_ == 0 && + IS_S0_INVERTED == 0); + localparam [0:0] INV_S1 = ( + _TECHMAP_CONSTMSK_S1_ == 1 && + _TECHMAP_CONSTVAL_S1_ == 0 && + IS_S1_INVERTED == 0); + + BUFGCTRL_VPR #( + .INIT_OUT(INIT_OUT), + .ZPRESELECT_I0(PRESELECT_I0), + .ZPRESELECT_I1(PRESELECT_I1), + .IS_IGNORE0_INVERTED(!IS_IGNORE0_INVERTED ^ INV_IGNORE0), + .IS_IGNORE1_INVERTED(!IS_IGNORE1_INVERTED ^ INV_IGNORE1), + .ZINV_CE0(!IS_CE0_INVERTED ^ INV_CE0), + .ZINV_CE1(!IS_CE1_INVERTED ^ INV_CE1), + .ZINV_S0(!IS_S0_INVERTED ^ INV_S0), + .ZINV_S1(!IS_S1_INVERTED ^ INV_S1) + ) _TECHMAP_REPLACE_ ( + .O(O), + .CE0(CE0 ^ INV_CE0), + .CE1(CE1 ^ INV_CE1), + .I0(I0), + .I1(I1), + .IGNORE0(IGNORE0 ^ INV_IGNORE0), + .IGNORE1(IGNORE1 ^ INV_IGNORE1), + .S0(S0 ^ INV_S0), + .S1(S1 ^ INV_S1) + ); + + endmodule + +.. note:: + + All F4PGA techmaps for Xilinx 7-Series devices use special inverter + logic that converts constant 0 signals at the BEL to constant-1 signals + at the site. This behavior is desired since VCC is the default signal in + 7-Series and US/US+ devices. The presented solution matches the conventions + used by the vendor tools and gives the opportunity to validate generated + bitstreams with fasm2bels and Vivado. + +Yosys provides special techmapping naming conventions for wires, +parameters, and modules. The special names that start with ``_TECHMAP_`` +can be used to force certain behavior during the techmapping process. +Currently, the following special names are used in F4PGA techmaps: + +- ``_TECHMAP_REPLACE_`` is used as a name for an instantiated module, which will + replace the one used in the original design. This special name causes + the instantiated module to inherit the name and all attributes + from the module that is being replaced. + +- ``_TECHMAP_CONSTMSK__`` and ``_TECHMAP_CONSTVAL__`` + are used together as names of parameters. The ``_TECHMAP_CONSTMASK__`` + has a length of the input signal. Its bits take the value 1 if + the corresponding signal bit has a constant value, or 0 otherwise. + The ``_TECHMAP_CONSTVAL__`` bits store the actual constant signal + values when the ``_TECHMAP_CONSTMASK__`` is equal to 1. + +More information about special wire, parameter, and module names can be found in +`techmap section in the Yosys Manual`_. + +.. note:: + + Techmapping can be used not only to change the names of the primitives + but primarily to match the port declarations and express the logic behind + the primitive substitution: + + .. verilog:module:: module BUFG (output O, input I) + + .. verilog:module:: module BUFGCTRL (output O, input CE0, input CE1, input I0, input I1, input IGNORE0, input IGNORE1, input S0, input S1) + +More information +---------------- + +Additional information about Yosys can be found on the `Yosys Project Website +`_ , or in `Yosys Manual +`_. You can also compile +one of the tests described in Getting Started section and watch the log file +to understand which operations are performed by Yosys. + Place & Route -============= +************* The F4PGA Project uses two different tools for the PnR process - ``nextpnr`` and ``Versatile Place and Route`` (VPR). Both of them write their final result to a file in the ``.fasm`` format. + +VPR +=== + +See `VPR ➚ `__. + +nextpnr +======= + +See :gh:`nextpnr ➚ `. diff --git a/docs/index.rst b/docs/index.rst index 81a687dbc..5c73ad367 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -29,12 +29,6 @@ The project aim is to design tools that are highly extendable and multiplatform. FPGA Assembly (FASM) ➚ -.. toctree:: - :caption: Other - - yosys - VPR ➚ - .. toctree:: :caption: Contributing diff --git a/docs/yosys.rst b/docs/yosys.rst deleted file mode 100644 index 3e29ef40d..000000000 --- a/docs/yosys.rst +++ /dev/null @@ -1,404 +0,0 @@ -Yosys -===== - -Yosys is a Free and Open Source Verilog HDL synthesis tool. -It was designed to be highly extensible and multiplatform. -In F4PGA toolchain, it is responsible for the whole synthesis process described in `FPGA Design Flow <./design-flow.html>`_ - -It is not necessary to call Yosys directly using F4PGA. -Nevertheless, the following description, should provide sufficient introduction to Yosys usage inside the project. -It is also a good starting point for a deeper understanding of the whole toolchain. - -Short description ------------------ - -Yosys consists of several subsystems. Most distinguishable are the -first and last ones used in the synthesis process, called *frontend* -and *backend* respectively. Intermediate subsystems are called *passes*. - -The *frontend* is responsible for changing the Verilog input file into -an internal Yosys, representation which is common for all *passes* used -by the program. The *passes* are responsible for a variety of optimizations -(``opt_``) and simplifications (``proc_``). - -Two *passes*, that are worth -to mention separately are ``ABC`` and ``techmap``. The first one optimizes -logic functions from the design and assigns obtained results into Look Up Tables -(LUTs) of chosen width. The second mentioned *pass* - ``techmap`` -is responsible for mapping the synthesized design from Yosys internal -blocks to the primitives used by the implementation tool. -Recommended synthesis flows for different FPGAs are combined into -macros i.e. ``synth_ice40`` (for Lattice iCE40 FPGA) or ``synth_xilinx`` -(for Xilinx 7-series FPGAs). - -The *backend* on the other hand, is responsible for converting internal Yosys representation into one of the -standardized formats. -F4PGA uses ``.eblif`` as its output file format. - -Usage in Toolchain ------------------- - -All operations performed by Yosys are written in ``.tcl`` script. Commands used -in the scripts are responsible for preparing output file to match with the -expectations of other toolchain tools. -There is no need to change it even for big designs. -An example configuration script can be found below: - -.. code-block:: tcl - - yosys -import - - synth_ice40 -nocarry - - opt_expr -undriven - opt_clean - - setundef -zero -params - write_blif -attr -cname -param $::env(OUT_EBLIF) - write_verilog $::env(OUT_SYNTH_V) - -It can be seen that this script performs a platform-specific process of synthesis, some optimization steps (``opt_`` -commands), and writes the final file in ``.eblif`` and Verilog formats. -Yosys synthesis configuration scripts are platform-specific and can by found in ``/yosys/synth.tcl`` in -the :gh:`F4PGA Architecture Definitions ` repository. - -To understand performed operations, view the log file. -It is usually generated in the project build directory. It should be named ``top.eblif.log``. - -Output analysis ---------------- - -Input file: - -.. code-block:: verilog - - module top ( - input clk, - output LD7, - ); - localparam BITS = 1; - localparam LOG2DELAY = 25; - - reg [BITS+LOG2DELAY-1:0] counter = 0; - always @(posedge clk) begin - counter <= counter + 1; - end - - assign {LD7} = counter >> LOG2DELAY; - endmodule - - -after synthesis is described only with use of primitives appropriate for -chosen platform: - -.. code-block:: verilog - - module top(clk, LD7); - wire [25:0] _000_; - wire _001_; - - ... - - FDRE_ZINI #( - .IS_C_INVERTED(1'h0), - .ZINI(1'h1) - ) _073_ ( - .C(clk), - .CE(_012_), - .D(_000_[0]), - .Q(counter[0]), - .R(_013_) - ); - - ... - - SR_GND _150_ ( - .GND(_062_) - ); - assign _003_[25:0] = _000_; - assign counter[25] = LD7; - endmodule - -The same structure is described by the ``.eblif`` file. - - -Technology mapping in F4PGA toolchain -------------------------------------- - -.. _Xilinx 7 Series FPGAs Clocking Resources User Guide: https://www.xilinx.com/support/documentation/user_guides/ug472_7Series_Clocking.pdf#page=38 -.. _VTR FPGA Architecture Description: https://docs.verilogtorouting.org/en/latest/arch/ -.. _techmap section in the Yosys Manual: http://www.clifford.at/yosys/files/yosys_manual.pdf#page=153 - -It is important to understand the connection between the synthesis and -implementation tools used in the F4PGA toolchain. As mentioned before, -synthesis tools like Yosys take the design description from the source files -and convert them into a netlist that consists of the primitives used by -the implementation tool. Usually, to support multiple implementation tools, -an additional intermediate representation of FPGA primitives is provided. -The process of translating the primitives from the synthesis -tool’s internal representation to the specific primitives used in the -implementation tools is called technology mapping (or techmapping). - -Technology mapping for VPR --------------------------- - -As mentioned before, VPR is one of the implementation tools (often referred to -as Place & Route or P&R tools) used in F4PGA. By default, the F4PGA -toolchain uses it during bitstream generation for, i.e., Xilinx 7-Series -devices. Since the architecture models for this FPGA family were created from -scratch, appropriate techmaps were needed to instruct Yosys on translating -the primitives to the versions compatible with VPR. - -The clock buffers used in the 7-Series devices are a good example for explaining -the techmapping process. Generally, as stated in the -`Xilinx 7 Series FPGAs Clocking Resources User Guide`_, a designer has various -buffer types that they can use in designs: - -- ``BUFGCTRL`` -- ``BUFG`` -- ``BUFGCE`` -- ``BUFGCE_1`` -- ``BUFGMUX`` -- ``BUFGMUX_1`` -- ``BUFGMUX_CTRL`` - -Nevertheless, the actual chips consist only of the ``BUFGCTRL`` primitives, -which are the most universal and can function as other clock buffer -primitives from the Xilinx manual. Because of that, only one architecture model -is required for VPR. The rest of the primitives is mapped to this general -buffer during the techmapping process. The model of ``BUFGCTRL`` primitive used -by VPR is called ``BUFGCTR_VPR`` (More information about the architecture -modeling in VPR can be found in the `VTR FPGA Architecture Description`_). - -Support for particular primitive in VTR consist of two files: - -- Model XML (``xxx.model.xml``) - Contains general information about - the module's input and output ports and their relations. - -- Physical Block XML (``xxx.pb_type.xml``) - Describes the actual layout of the - primitive, with information about the timings, internal connections, etc. - -Below you can see the pb_type XML for ``BUFGCTRL_VPR`` primitive: - -.. code-block:: xml - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - ZPRESELECT_I0 = ZPRESELECT_I0 - ZPRESELECT_I1 = ZPRESELECT_I1 - IS_IGNORE0_INVERTED = IS_IGNORE0_INVERTED - IS_IGNORE1_INVERTED = IS_IGNORE1_INVERTED - ZINV_CE0 = ZINV_CE0 - ZINV_CE1 = ZINV_CE1 - ZINV_S0 = ZINV_S0 - ZINV_S1 = ZINV_S1 - - - - - - - - - - - - - - - - - - IN_USE - - - - - -A correctly prepared techmap for any VPR model contains a declaration of -the module that should be substituted. Inside the module declaration, one -should provide a necessary logic and instantiate another module that -will substitute its original version. Additionally, all equations within -a techmap that are not used directly in a module instantiation should evaluate -to a constant value. Therefore most of the techmaps use additional constant -parameters to modify the signals attached to the instantiated module. - -Here is a piece of a techmap, which instructs Yosys to convert -a ``BUFG`` primitive to the ``BUFGCTRL_VPR``. In this case, the techmaping process -consists of two steps. Firstly, the techmap shows how to translate the ``BUFG`` -primitive to the ``BUFGCTRL``. Then how to translate the ``BUFGCTRL`` to -the ``BUFGCTRL_VPR``: - -.. code-block:: verilog - - module BUFG ( - input I, - output O - ); - - BUFGCTRL _TECHMAP_REPLACE_ ( - .O(O), - .CE0(1'b1), - .CE1(1'b0), - .I0(I), - .I1(1'b1), - .IGNORE0(1'b0), - .IGNORE1(1'b1), - .S0(1'b1), - .S1(1'b0) - ); - endmodule - - module BUFGCTRL ( - output O, - input I0, input I1, - input S0, input S1, - input CE0, input CE1, - input IGNORE0, input IGNORE1 - ); - - parameter [0:0] INIT_OUT = 1'b0; - parameter [0:0] PRESELECT_I0 = 1'b0; - parameter [0:0] PRESELECT_I1 = 1'b0; - parameter [0:0] IS_IGNORE0_INVERTED = 1'b0; - parameter [0:0] IS_IGNORE1_INVERTED = 1'b0; - parameter [0:0] IS_CE0_INVERTED = 1'b0; - parameter [0:0] IS_CE1_INVERTED = 1'b0; - parameter [0:0] IS_S0_INVERTED = 1'b0; - parameter [0:0] IS_S1_INVERTED = 1'b0; - - parameter _TECHMAP_CONSTMSK_IGNORE0_ = 0; - parameter _TECHMAP_CONSTVAL_IGNORE0_ = 0; - parameter _TECHMAP_CONSTMSK_IGNORE1_ = 0; - parameter _TECHMAP_CONSTVAL_IGNORE1_ = 0; - parameter _TECHMAP_CONSTMSK_CE0_ = 0; - parameter _TECHMAP_CONSTVAL_CE0_ = 0; - parameter _TECHMAP_CONSTMSK_CE1_ = 0; - parameter _TECHMAP_CONSTVAL_CE1_ = 0; - parameter _TECHMAP_CONSTMSK_S0_ = 0; - parameter _TECHMAP_CONSTVAL_S0_ = 0; - parameter _TECHMAP_CONSTMSK_S1_ = 0; - parameter _TECHMAP_CONSTVAL_S1_ = 0; - - localparam [0:0] INV_IGNORE0 = ( - _TECHMAP_CONSTMSK_IGNORE0_ == 1 && - _TECHMAP_CONSTVAL_IGNORE0_ == 0 && - IS_IGNORE0_INVERTED == 0); - localparam [0:0] INV_IGNORE1 = ( - _TECHMAP_CONSTMSK_IGNORE1_ == 1 && - _TECHMAP_CONSTVAL_IGNORE1_ == 0 && - IS_IGNORE1_INVERTED == 0); - localparam [0:0] INV_CE0 = ( - _TECHMAP_CONSTMSK_CE0_ == 1 && - _TECHMAP_CONSTVAL_CE0_ == 0 && - IS_CE0_INVERTED == 0); - localparam [0:0] INV_CE1 = ( - _TECHMAP_CONSTMSK_CE1_ == 1 && - _TECHMAP_CONSTVAL_CE1_ == 0 && - IS_CE1_INVERTED == 0); - localparam [0:0] INV_S0 = ( - _TECHMAP_CONSTMSK_S0_ == 1 && - _TECHMAP_CONSTVAL_S0_ == 0 && - IS_S0_INVERTED == 0); - localparam [0:0] INV_S1 = ( - _TECHMAP_CONSTMSK_S1_ == 1 && - _TECHMAP_CONSTVAL_S1_ == 0 && - IS_S1_INVERTED == 0); - - BUFGCTRL_VPR #( - .INIT_OUT(INIT_OUT), - .ZPRESELECT_I0(PRESELECT_I0), - .ZPRESELECT_I1(PRESELECT_I1), - .IS_IGNORE0_INVERTED(!IS_IGNORE0_INVERTED ^ INV_IGNORE0), - .IS_IGNORE1_INVERTED(!IS_IGNORE1_INVERTED ^ INV_IGNORE1), - .ZINV_CE0(!IS_CE0_INVERTED ^ INV_CE0), - .ZINV_CE1(!IS_CE1_INVERTED ^ INV_CE1), - .ZINV_S0(!IS_S0_INVERTED ^ INV_S0), - .ZINV_S1(!IS_S1_INVERTED ^ INV_S1) - ) _TECHMAP_REPLACE_ ( - .O(O), - .CE0(CE0 ^ INV_CE0), - .CE1(CE1 ^ INV_CE1), - .I0(I0), - .I1(I1), - .IGNORE0(IGNORE0 ^ INV_IGNORE0), - .IGNORE1(IGNORE1 ^ INV_IGNORE1), - .S0(S0 ^ INV_S0), - .S1(S1 ^ INV_S1) - ); - - endmodule - -.. note:: - - All F4PGA techmaps for Xilinx 7-Series devices use special inverter - logic that converts constant 0 signals at the BEL to constant-1 signals - at the site. This behavior is desired since VCC is the default signal in - 7-Series and US/US+ devices. The presented solution matches the conventions - used by the vendor tools and gives the opportunity to validate generated - bitstreams with fasm2bels and Vivado. - -Yosys provides special techmapping naming conventions for wires, -parameters, and modules. The special names that start with ``_TECHMAP_`` -can be used to force certain behavior during the techmapping process. -Currently, the following special names are used in F4PGA techmaps: - -- ``_TECHMAP_REPLACE_`` is used as a name for an instantiated module, which will - replace the one used in the original design. This special name causes - the instantiated module to inherit the name and all attributes - from the module that is being replaced. - -- ``_TECHMAP_CONSTMSK__`` and ``_TECHMAP_CONSTVAL__`` - are used together as names of parameters. The ``_TECHMAP_CONSTMASK__`` - has a length of the input signal. Its bits take the value 1 if - the corresponding signal bit has a constant value, or 0 otherwise. - The ``_TECHMAP_CONSTVAL__`` bits store the actual constant signal - values when the ``_TECHMAP_CONSTMASK__`` is equal to 1. - -More information about special wire, parameter, and module names can be found in -`techmap section in the Yosys Manual`_. - -.. note:: - - Techmapping can be used not only to change the names of the primitives - but primarily to match the port declarations and express the logic behind - the primitive substitution: - - .. verilog:module:: module BUFG (output O, input I) - - .. verilog:module:: module BUFGCTRL (output O, input CE0, input CE1, input I0, input I1, input IGNORE0, input IGNORE1, input S0, input S1) - -More information ----------------- - -Additional information about Yosys can be found on the `Yosys Project Website -`_ , or in `Yosys Manual -`_. You can also compile -one of the tests described in Getting Started section and watch the log file -to understand which operations are performed by Yosys. From 894b7369f21784685730a4ced306f8b27836210e Mon Sep 17 00:00:00 2001 From: Unai Martinez-Corral Date: Tue, 15 Mar 2022 23:29:10 +0100 Subject: [PATCH 6/9] docs: add Glossary Signed-off-by: Unai Martinez-Corral --- docs/glossary.rst | 7 +++++++ docs/index.rst | 10 ++++++++++ 2 files changed, 17 insertions(+) create mode 100644 docs/glossary.rst diff --git a/docs/glossary.rst b/docs/glossary.rst new file mode 100644 index 000000000..62ae5314e --- /dev/null +++ b/docs/glossary.rst @@ -0,0 +1,7 @@ +Glossary +######## + +.. glossary:: + + File + A representation of a physical file. diff --git a/docs/index.rst b/docs/index.rst index 5c73ad367..69fec9194 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -7,6 +7,7 @@ Think of it as the GCC of FPGAs. The project aim is to design tools that are highly extendable and multiplatform. + .. toctree:: :caption: About F4PGA @@ -15,6 +16,7 @@ The project aim is to design tools that are highly extendable and multiplatform. status getting-started + .. toctree:: :caption: Design Flows @@ -24,13 +26,21 @@ The project aim is to design tools that are highly extendable and multiplatform. flows/bitstream flows/f4pga + .. toctree:: :caption: Specifications FPGA Assembly (FASM) ➚ + .. toctree:: :caption: Contributing contributing/building-docs contributing/venv + + +.. toctree:: + :caption: Appendix + + glossary From 9d2c99de6a51e37ce59e6e61c7799472fedced05 Mon Sep 17 00:00:00 2001 From: Unai Martinez-Corral Date: Tue, 15 Mar 2022 23:30:59 +0100 Subject: [PATCH 7/9] docs: add hero image Signed-off-by: Unai Martinez-Corral --- docs/_static/images/hero.svg | 1 + docs/index.rst | 8 +++++--- 2 files changed, 6 insertions(+), 3 deletions(-) create mode 100644 docs/_static/images/hero.svg diff --git a/docs/_static/images/hero.svg b/docs/_static/images/hero.svg new file mode 100644 index 000000000..92c154a40 --- /dev/null +++ b/docs/_static/images/hero.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/docs/index.rst b/docs/index.rst index 69fec9194..7a9b230f9 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,11 +1,13 @@ FOSS Flows For FPGA ################### -F4PGA is an Open Source HDL-to-Bitstream FPGA synthesis solution, currently targeting Xilinx 7-Series, Lattice iCE40 and -Lattice ECP5 FPGAs. +F4PGA is an Open Source solution for Hardware Description Language (HDL) to Bitstream FPGA synthesis, currently +targeting Xilinx 7-Series, Lattice iCE40 and Lattice ECP5 FPGAs. Think of it as the GCC of FPGAs. +The project aims to design tools that are highly extendable and multiplatform. -The project aim is to design tools that are highly extendable and multiplatform. +.. image:: _static/images/hero.svg + :align: center .. toctree:: From a08f724030ae6cf31aac2c3120bfa5fdc6352263 Mon Sep 17 00:00:00 2001 From: Unai Martinez-Corral Date: Tue, 15 Mar 2022 23:39:30 +0100 Subject: [PATCH 8/9] docs: add references through sphinxcontrib-bibtex Signed-off-by: Unai Martinez-Corral --- docs/conf.py | 6 +- docs/index.rst | 1 + docs/references.rst | 8 ++ docs/refs.bib | 232 ++++++++++++++++++++++++++++++++++++++++++ docs/requirements.txt | 3 +- 5 files changed, 248 insertions(+), 2 deletions(-) create mode 100644 docs/references.rst create mode 100644 docs/refs.bib diff --git a/docs/conf.py b/docs/conf.py index 4302418c8..557060990 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -45,9 +45,13 @@ extensions = [ 'sphinx.ext.extlinks', 'sphinx.ext.intersphinx', - 'sphinx_verilog_domain' + 'sphinx_verilog_domain', + 'sphinxcontrib.bibtex', ] +bibtex_default_style = 'plain' +bibtex_bibfiles = ['refs.bib'] + numfig = True templates_path = ['_templates'] diff --git a/docs/index.rst b/docs/index.rst index 7a9b230f9..fb3c296ba 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -46,3 +46,4 @@ The project aims to design tools that are highly extendable and multiplatform. :caption: Appendix glossary + references diff --git a/docs/references.rst b/docs/references.rst new file mode 100644 index 000000000..456331297 --- /dev/null +++ b/docs/references.rst @@ -0,0 +1,8 @@ +.. _References: + +References +########## + +.. bibliography:: + :notcited: + :labelprefix: R diff --git a/docs/refs.bib b/docs/refs.bib new file mode 100644 index 000000000..160527875 --- /dev/null +++ b/docs/refs.bib @@ -0,0 +1,232 @@ +@Online{verilator, + author = {Snyder, Wilson and {contributors}}, + title = {{Verilator, FOSS tool which converts Verilog to a cycle-accurate behavioral model in C++ or SystemC}}, + url = {https://www.veripool.org/verilator/}, + year = {2003}, +} + +@InProceedings{wolf13, + author = {Wolf, Clifford and Glaser, Johann}, + title = {{A Free Verilog Synthesis Suite}}, + booktitle = {Proceedings of Austrochip 2013}, + year = {2013}, + url = {https://yosyshq.net/yosys/} +} + +@Online{gh:yosys, + author = {Wolf, Claire and {contributors}}, + title = {{Yosys Open SYnthesis Suite}}, + url = {https://github.com/YosysHQ/yosys}, +} + +@Online{gh:symbiyosys, + author = {Wolf, Claire and {contributors}}, + title = {{SymbiYosys: front-end for Yosys-based formal verification flows}}, + url = {https://github.com/YosysHQ/SymbiYosys}, +} + +@Online{gh:nextpnr, + author = {gatecat and {contributors}}, + title = {{nextpnr: portable FPGA place and route tool}}, + url = {https://github.com/YosysHQ/nextpnr}, +} + +@Online{gh:gtkwave, + author = {Bybell, Tony and {contributors}}, + title = {{GTKWave: a is a fully featured GTK+ based wave viewer for Unix, Win32, and Mac OSX}}, + url = {https://github.com/gtkwave/gtkwave}, + year = {1998}, +} + +@Online{gh:ghdl, + author = {Gingold, Tristan and {contributors}}, + title = {{GHDL: open-source analyzer, compiler, simulator and (experimental) synthesizer for VHDL}}, + url = {https://github.com/ghdl/ghdl}, + month = {Sep}, + year = {2003}, +} + +@Online{gh:ghdl-yosys-plugin, + author = {Gingold, Tristan and {contributors}}, + title = {{ghdl-yosys-plugin: VHDL synthesis (based on ghdl and yosys)}}, + url = {https://github.com/ghdl/ghdl-yosys-plugin}, + year = {2017}, +} + +@Online{sphinx, + author = {Brandl, Georg and KOMIYA, Takeshi and {contributors}}, + year = {2007}, + title = {{Sphinx, Python Documentation Generator}}, + url = {https://www.sphinx-doc.org}, +} + +@Online{verible, + author = {Fang, David and Zeller, Henner and {contributors}}, + year = {2019}, + title = {{Verible, a suite of SystemVerilog developer tools, including a parser, style-linter, and formatter}}, + url = {https://chipsalliance.github.io/verible/}, +} + +@Online{surelog, + author = {Dargelas, Alain and Zeller, Henner and {contributors}}, + year = {2019}, + title = {{Surelog, SystemVerilog 2017 Pre-processor, Parser, Elaborator, UHDM Compiler}}, + url = {https://github.com/alainmarcel/Surelog/}, +} + +@inproceedings{dargelas20, + title = {{Universal Hardware Data Model}}, + author = {Dargelas, Alain and Zeller, Henner}, + booktitle = {Workshop on Open-Source EDA Technology 2020 (WOSET)}, + year = {2020}, + month = {10}, + url = {https://woset-workshop.github.io/PDFs/2020/a10.pdf} +} + +@Online{iverilog, + author={Williams, Stephen and {contributors}}, + title={{Icarus Verilog, a Verilog simulation and synthesis tool}}, + url={http://iverilog.icarus.com/} +} + +@InProceedings{ansell20, + author = {Ansell, Tim and Saligane, Mehdi}, + booktitle = {2020 IEEE/ACM International Conference On Computer Aided Design (ICCAD)}, + title = {{The Missing Pieces of Open Design Enablement: A Recent History of Google Efforts : Invited Paper}}, + year = {2020}, + pages = {1-8}, + url = {https://dl.acm.org/doi/abs/10.1145/3400302.3415736} +} + +@Online{gcc, + author = {Stallman, Richard and {contributors}}, + year = {1987}, + title = {{GCC, the GNU Compiler Collection}}, + url = {http://gcc.gnu.org/}, + month = {May}, +} + +@Online{gdb, + author = {Stallman, Richard and {GNU Project}}, + year = {1986}, + title = {{GDB: The GNU Project Debugger}}, + url = {https://www.gnu.org/software/gdb/}, +} + +@Online{llvm, + author = { + Adve, Vikram and + Lattner, Chris and + {LLVM Developer Group} + }, + title = {{LLVM Project, a collection of modular and reusable compiler and toolchain technologies}}, + url = {https://www.llvm.org/}, + year = {2003}, +} + +@Online{gh:wavedrom, + author = {Chapyzhenka, Aliaksei and {contributors}}, + title = {{Wavedrom, digital timing diagram rendering engine}}, + url = {https://github.com/wavedrom/wavedrom}, + year = {2014}, +} + +@Online{symbolator, + author = {Thibedeau, Kevin}, + title = {{Symbolator, a component diagramming tool for VHDL and Verilog}}, + url = {https://kevinpt.github.io/symbolator}, +} + +@InProceedings{rovinski20, + author={ + Rovinski, Austin and + Ajayi, Tutu and + Kim, Minsoo and + Wang, Guanru and + Saligane, Mehdi + }, + booktitle={2020 IEEE/ACM International Conference On Computer Aided Design (ICCAD)}, + title={{Bridging Academic Open-Source EDA to Real-World Usability}}, + year={2020}, + pages={1-7}, + url={https://dl.acm.org/doi/10.1145/3400302.3415734} +} + +@Article{murray20micro, + author={ + Murray, Kevin E. and + Elgammal, Mohamed A. and + Betz, Vaughn and + Ansell, Tim and + Rothman, Keith and + Comodi, Alessandro + }, + journal={IEEE Micro}, + title={{SymbiFlow and VPR: An Open-Source Design Flow for Commercial and Novel FPGAs}}, + year={2020}, + volume={40}, + number={4}, + pages={49-57}, + doi={10.1109/MM.2020.2998435} +} + +@Article{murray20acm, + author = { + Murray, Kevin E. and + Petelin, Oleg and + Zhong, Sheng and + Wang, Jia Min and + Eldafrawy, Mohamed and + Legault, Jean-Philippe and + Sha, Eugene and + Graham, Aaron G. and + Wu, Jean and + Walker, Matthew J. P. and + Zeng, Hanqing and + Patros, Panagiotis and + Luu, Jason and + Kent, Kenneth B. and + Betz, Vaughn + }, + title = {{VTR 8: High-Performance CAD and Customizable FPGA Architecture Modelling}}, + year = {2020}, + issue_date = {June 2020}, + publisher = {Association for Computing Machinery}, + address = {New York, NY, USA}, + volume = {13}, + number = {2}, + issn = {1936-7406}, + url = {https://doi.org/10.1145/3388617}, + doi = {10.1145/3388617}, + abstract = {Developing Field-programmable Gate Array (FPGA) architectures is challenging due to +the competing requirements of various application domains and changing manufacturing +process technology. This is compounded by the difficulty of fairly evaluating FPGA +architectural choices, which requires sophisticated high-quality Computer Aided Design +(CAD) tools to target each potential architecture. This article describes version +8.0 of the open source Verilog to Routing (VTR) project, which provides such a design +flow. VTR 8 expands the scope of FPGA architectures that can be modelled, allowing +VTR to target and model many details of both commercial and proposed FPGA architectures. +The VTR design flow also serves as a baseline for evaluating new CAD algorithms. It +is therefore important, for both CAD algorithm comparisons and the validity of architectural +conclusions, that VTR produce high-quality circuit implementations. VTR 8 significantly +improves optimization quality (reductions of 15% minimum routable channel width, 41% +wirelength, and 12% critical path delay), run-time (5.3\texttimes{} faster) and memory footprint +(3.3\texttimes{} lower). Finally, we demonstrate VTR is run-time and memory footprint efficient, +while producing circuit implementations of reasonable quality compared to highly-tuned +architecture-specific industrial tools—showing that architecture generality, good +implementation quality, and run-time efficiency are not mutually exclusive goals.}, + journal = {ACM Trans. Reconfigurable Technol. Syst.}, + month = may, + articleno = {9}, + numpages = {55}, + keywords = {electronic design automation (EDA), Computer aided design (CAD), versatile place and route (VPR), verilog to routing (VTR), routing, placement, packing, field programmable gate array (FPGA)} +} + +@InProceedings{kahng20, + author={Kahng, Andrew B.}, + booktitle={2020 IFIP/IEEE 28th International Conference on Very Large Scale Integration (VLSI-SOC)}, + title={{Open-Source EDA: If We Build It, Who Will Come?}}, + year={2020}, + pages={1-6}, + doi={10.1109/VLSI-SOC46417.2020.9344073} +} diff --git a/docs/requirements.txt b/docs/requirements.txt index 325f714a0..db20c0940 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -1,4 +1,5 @@ -Sphinx==3.0.4 +sphinx +sphinxcontrib-bibtex http://github.com/SymbiFlow/sphinx_symbiflow_theme/archive/chips.zip#sphinx-symbiflow-theme http://github.com/SymbiFlow/sphinx-verilog-domain/archive/master.zip#sphinx-verilog-domain tabulate From 243cc590ffb20e32e3c46aabd51758091225896e Mon Sep 17 00:00:00 2001 From: Unai Martinez-Corral Date: Tue, 15 Mar 2022 23:45:29 +0100 Subject: [PATCH 9/9] docs: mv contributing development Signed-off-by: Unai Martinez-Corral --- docs/{contributing => development}/building-docs.rst | 0 docs/{contributing => development}/venv.rst | 0 docs/index.rst | 6 +++--- 3 files changed, 3 insertions(+), 3 deletions(-) rename docs/{contributing => development}/building-docs.rst (100%) rename docs/{contributing => development}/venv.rst (100%) diff --git a/docs/contributing/building-docs.rst b/docs/development/building-docs.rst similarity index 100% rename from docs/contributing/building-docs.rst rename to docs/development/building-docs.rst diff --git a/docs/contributing/venv.rst b/docs/development/venv.rst similarity index 100% rename from docs/contributing/venv.rst rename to docs/development/venv.rst diff --git a/docs/index.rst b/docs/index.rst index fb3c296ba..bcedf9716 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -36,10 +36,10 @@ The project aims to design tools that are highly extendable and multiplatform. .. toctree:: - :caption: Contributing + :caption: Development - contributing/building-docs - contributing/venv + development/building-docs + development/venv .. toctree::