Merge pull request #532 from antmicro/umarcor/docs/appendix
docs: add Appendix (Glossary and References)
This commit is contained in:
Karol Gugala
GitHub
commit
3f08ecd9e7
|
|
@ -1,2 +1,3 @@
|
|||
/_build/
|
||||
/env/
|
||||
/status.inc
|
||||
|
|
|
|||
File diff suppressed because one or more lines are too long
|
After Width: | Height: | Size: 56 KiB |
|
|
@ -31,9 +31,9 @@ Communication
|
|||
Souces
|
||||
======
|
||||
|
||||
* `github.com/chipsalliance <https://github.com/chipsalliance/?q=f4pga>`__
|
||||
* :gh:`github.com/chipsalliance <chipsalliance/?q=f4pga>`
|
||||
|
||||
* `github.com/F4PGA <https://github.com/F4PGA>`__
|
||||
* :gh:`github.com/F4PGA <F4PGA>`
|
||||
|
||||
.. _Contributing:
|
||||
|
||||
|
|
|
|||
18
docs/conf.py
18
docs/conf.py
|
|
@ -43,10 +43,15 @@ version = ''
|
|||
release = '' # The full version, including alpha/beta/rc tags.
|
||||
|
||||
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']
|
||||
|
|
@ -140,3 +145,14 @@ intersphinx_mapping = {
|
|||
"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', '')
|
||||
}
|
||||
|
|
|
|||
|
|
@ -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 ``<platform-dir>/yosys/synth.tcl`` in
|
||||
the :gh:`F4PGA Architecture Definitions <SymbiFlow/f4pga-arch-defs>` 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
|
||||
|
||||
<!-- Model of BUFG group in BUFG_CLK_TOP/BOT -->
|
||||
<pb_type name="BLK-TL-BUFGCTRL" xmlns:xi="http://www.w3.org/2001/XInclude">
|
||||
<output name="O" num_pins="1"/>
|
||||
<input name="CE0" num_pins="1"/>
|
||||
<input name="CE1" num_pins="1"/>
|
||||
<clock name="I0" num_pins="1"/>
|
||||
<clock name="I1" num_pins="1"/>
|
||||
<input name="IGNORE0" num_pins="1"/>
|
||||
<input name="IGNORE1" num_pins="1"/>
|
||||
<input name="S0" num_pins="1"/>
|
||||
<input name="S1" num_pins="1"/>
|
||||
<mode name="EMPTY">
|
||||
<pb_type name="empty" blif_model=".latch" num_pb="1" />
|
||||
<interconnect />
|
||||
</mode>
|
||||
<mode name="BUFGCTRL">
|
||||
<pb_type name="BUFGCTRL_VPR" blif_model=".subckt BUFGCTRL_VPR" num_pb="1">
|
||||
<output name="O" num_pins="1"/>
|
||||
<input name="CE0" num_pins="1"/>
|
||||
<input name="CE1" num_pins="1"/>
|
||||
<clock name="I0" num_pins="1"/>
|
||||
<clock name="I1" num_pins="1"/>
|
||||
<input name="IGNORE0" num_pins="1"/>
|
||||
<input name="IGNORE1" num_pins="1"/>
|
||||
<input name="S0" num_pins="1"/>
|
||||
<input name="S1" num_pins="1"/>
|
||||
<metadata>
|
||||
<meta name="fasm_params">
|
||||
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
|
||||
</meta>
|
||||
</metadata>
|
||||
</pb_type>
|
||||
<interconnect>
|
||||
<direct name="O" input="BUFGCTRL_VPR.O" output="BLK-TL-BUFGCTRL.O"/>
|
||||
<direct name="CE0" input="BLK-TL-BUFGCTRL.CE0" output="BUFGCTRL_VPR.CE0"/>
|
||||
<direct name="CE1" input="BLK-TL-BUFGCTRL.CE1" output="BUFGCTRL_VPR.CE1"/>
|
||||
<direct name="I0" input="BLK-TL-BUFGCTRL.I0" output="BUFGCTRL_VPR.I0"/>
|
||||
<direct name="I1" input="BLK-TL-BUFGCTRL.I1" output="BUFGCTRL_VPR.I1"/>
|
||||
<direct name="IGNORE0" input="BLK-TL-BUFGCTRL.IGNORE0" output="BUFGCTRL_VPR.IGNORE0"/>
|
||||
<direct name="IGNORE1" input="BLK-TL-BUFGCTRL.IGNORE1" output="BUFGCTRL_VPR.IGNORE1"/>
|
||||
<direct name="S0" input="BLK-TL-BUFGCTRL.S0" output="BUFGCTRL_VPR.S0"/>
|
||||
<direct name="S1" input="BLK-TL-BUFGCTRL.S1" output="BUFGCTRL_VPR.S1"/>
|
||||
|
||||
</interconnect>
|
||||
<metadata>
|
||||
<meta name="fasm_features">
|
||||
IN_USE
|
||||
</meta>
|
||||
</metadata>
|
||||
</mode>
|
||||
</pb_type>
|
||||
|
||||
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_<port_name>_`` and ``_TECHMAP_CONSTVAL_<port_name>_``
|
||||
are used together as names of parameters. The ``_TECHMAP_CONSTMASK_<port_name>_``
|
||||
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_<port_name>_`` bits store the actual constant signal
|
||||
values when the ``_TECHMAP_CONSTMASK_<port_name>_`` 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
|
||||
<http://www.clifford.at/yosys/>`_ , or in `Yosys Manual
|
||||
<http://www.clifford.at/yosys/files/yosys_manual.pdf>`_. 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 ➚ <https://docs.verilogtorouting.org/en/latest/vpr/>`__.
|
||||
|
||||
nextpnr
|
||||
=======
|
||||
|
||||
See :gh:`nextpnr ➚ <f4pga/nextpnr>`.
|
||||
|
|
|
|||
|
|
@ -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 ➚ <https://f4pga-examples.readthedocs.io>`__ (for users)
|
||||
|
||||
* `Examples ➚ <https://f4pga-examples.readthedocs.io>`__ (for users)
|
||||
* `Architecture Definitions ➚ <https://f4pga.readthedocs.io/projects/arch-defs/en/latest/getting-started.html>`__ (for developers)
|
||||
* `Architecture Definitions ➚ <https://f4pga.readthedocs.io/projects/arch-defs/en/latest/getting-started.html>`__ (for developers)
|
||||
|
||||
* Other resources:
|
||||
* `F4PGA Architectures Visualizer ➚ <https://chipsalliance.github.io/f4pga-database-visualizer/>`__
|
||||
|
||||
* `Project X-Ray ➚ <https://f4pga.readthedocs.io/projects/prjxray/en/latest/>`__
|
||||
|
||||
* `X-Ray Quickstart ➚ <https://f4pga.readthedocs.io/projects/prjxray/en/latest/db_dev_process/readme.html#quickstart-guide>`__
|
||||
* `F4PGA Architectures Visualizer ➚ <https://chipsalliance.github.io/f4pga-database-visualizer/>`__
|
||||
|
||||
* `Project Trellis ➚ <https://prjtrellis.readthedocs.io/en/latest/>`__
|
||||
|
||||
* :gh:`Project Icestorm ➚ <f4pga/icestorm>`
|
||||
|
|
|
|||
|
|
@ -0,0 +1,7 @@
|
|||
Glossary
|
||||
########
|
||||
|
||||
.. glossary::
|
||||
|
||||
File
|
||||
A representation of a physical file.
|
||||
22
docs/how.rst
22
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 <arch-defs:index>` project.
|
||||
|
||||
Those definitions and serve as input to backend tools like
|
||||
`nextpnr <https://github.com/YosysHQ/nextpnr>`_ and
|
||||
`Verilog to Routing <https://verilogtorouting.org/>`_, and frontend tools
|
||||
like `Yosys <http://www.clifford.at/yosys/>`_. They are created within separate
|
||||
collaborating projects targeting different FPGAs - :doc:`Project X-Ray
|
||||
<prjxray:index>` for Xilinx 7-Series, `Project IceStorm
|
||||
<http://www.clifford.at/icestorm/>`_ for Lattice iCE40 and :doc:`Project Trellis
|
||||
<prjtrellis:index>` for Lattice ECP5 FPGAs.
|
||||
Those definitions and serve as input to backend tools like :gh:`nextpnr <YosysHQ/nextpnr>` and `Verilog to Routing <https://verilogtorouting.org/>`_,
|
||||
and frontend tools like `Yosys <http://www.clifford.at/yosys/>`_.
|
||||
They are created within separate collaborating projects targeting different FPGAs:
|
||||
|
||||
* :doc:`Project X-Ray <prjxray:index>` for Xilinx 7-Series
|
||||
* `Project IceStorm <http://www.clifford.at/icestorm/>` for Lattice iCE40
|
||||
* :doc:`Project Trellis <prjtrellis:index>` 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 <https://github.com/chipsalliance/f4pga-arch-defs>`__.
|
||||
This part is done within the :gh:`F4PGA Architecture Definitions <chipsalliance/f4pga-arch-defs>`.
|
||||
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 <https://github.com/YosysHQ/nextpnr>`__ or `Verilog to Routing <https://github.com/verilog-to-routing/vtr-verilog-to-routing>`__.
|
||||
To do that, F4PGA uses either :gh:`nextpnr <YosysHQ/nextpnr>` or `Verilog to Routing :gh:<verilog-to-routing/vtr-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 `fasm format <https://github.com/chipsalliance/fasm>`__, which is developed as part of
|
||||
F4PGA.
|
||||
These features are saved in the :gh:`fasm format <chipsalliance/fasm>`, which is developed as part of F4PGA.
|
||||
The fasm file is then translated to bitstream using the information from the bitstream documentation projects.
|
||||
|
|
|
|||
|
|
@ -1,11 +1,14 @@
|
|||
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.
|
||||
|
||||
.. image:: _static/images/hero.svg
|
||||
:align: center
|
||||
|
||||
The project aim is to design tools that are highly extendable and multiplatform.
|
||||
|
||||
.. toctree::
|
||||
:caption: About F4PGA
|
||||
|
|
@ -15,6 +18,7 @@ The project aim is to design tools that are highly extendable and multiplatform.
|
|||
status
|
||||
getting-started
|
||||
|
||||
|
||||
.. toctree::
|
||||
:caption: Design Flows
|
||||
|
||||
|
|
@ -24,22 +28,22 @@ The project aim is to design tools that are highly extendable and multiplatform.
|
|||
flows/bitstream
|
||||
flows/f4pga
|
||||
|
||||
|
||||
.. toctree::
|
||||
:caption: Specifications
|
||||
|
||||
FPGA Assembly (FASM) ➚ <https://fasm.readthedocs.io/en/latest/>
|
||||
|
||||
.. toctree::
|
||||
:caption: Other
|
||||
|
||||
yosys
|
||||
VPR ➚ <https://docs.verilogtorouting.org/en/latest/vpr/>
|
||||
Architecture Definitions ➚ <https://f4pga.readthedocs.io/projects/arch-defs/en/latest/>
|
||||
Project X-Ray ➚ <https://f4pga.readthedocs.io/projects/prjxray/en/latest/>
|
||||
Project Trellis ➚ <https://prjtrellis.readthedocs.io/en/latest/>
|
||||
|
||||
.. toctree::
|
||||
:caption: Contributing
|
||||
:caption: Development
|
||||
|
||||
contributing/building-docs
|
||||
contributing/venv
|
||||
development/building-docs
|
||||
development/venv
|
||||
|
||||
|
||||
.. toctree::
|
||||
:caption: Appendix
|
||||
|
||||
glossary
|
||||
references
|
||||
|
|
|
|||
|
|
@ -0,0 +1,8 @@
|
|||
.. _References:
|
||||
|
||||
References
|
||||
##########
|
||||
|
||||
.. bibliography::
|
||||
:notcited:
|
||||
:labelprefix: R
|
||||
|
|
@ -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}
|
||||
}
|
||||
|
|
@ -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
|
||||
|
|
|
|||
406
docs/yosys.rst
406
docs/yosys.rst
|
|
@ -1,406 +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 ``<platform-dir>/yosys/synth.tcl``
|
||||
in the `F4PGA Architecture Definitions <https://github.com/SymbiFlow/f4pga-arch-defs>`_
|
||||
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
|
||||
|
||||
<!-- Model of BUFG group in BUFG_CLK_TOP/BOT -->
|
||||
<pb_type name="BLK-TL-BUFGCTRL" xmlns:xi="http://www.w3.org/2001/XInclude">
|
||||
<output name="O" num_pins="1"/>
|
||||
<input name="CE0" num_pins="1"/>
|
||||
<input name="CE1" num_pins="1"/>
|
||||
<clock name="I0" num_pins="1"/>
|
||||
<clock name="I1" num_pins="1"/>
|
||||
<input name="IGNORE0" num_pins="1"/>
|
||||
<input name="IGNORE1" num_pins="1"/>
|
||||
<input name="S0" num_pins="1"/>
|
||||
<input name="S1" num_pins="1"/>
|
||||
<mode name="EMPTY">
|
||||
<pb_type name="empty" blif_model=".latch" num_pb="1" />
|
||||
<interconnect />
|
||||
</mode>
|
||||
<mode name="BUFGCTRL">
|
||||
<pb_type name="BUFGCTRL_VPR" blif_model=".subckt BUFGCTRL_VPR" num_pb="1">
|
||||
<output name="O" num_pins="1"/>
|
||||
<input name="CE0" num_pins="1"/>
|
||||
<input name="CE1" num_pins="1"/>
|
||||
<clock name="I0" num_pins="1"/>
|
||||
<clock name="I1" num_pins="1"/>
|
||||
<input name="IGNORE0" num_pins="1"/>
|
||||
<input name="IGNORE1" num_pins="1"/>
|
||||
<input name="S0" num_pins="1"/>
|
||||
<input name="S1" num_pins="1"/>
|
||||
<metadata>
|
||||
<meta name="fasm_params">
|
||||
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
|
||||
</meta>
|
||||
</metadata>
|
||||
</pb_type>
|
||||
<interconnect>
|
||||
<direct name="O" input="BUFGCTRL_VPR.O" output="BLK-TL-BUFGCTRL.O"/>
|
||||
<direct name="CE0" input="BLK-TL-BUFGCTRL.CE0" output="BUFGCTRL_VPR.CE0"/>
|
||||
<direct name="CE1" input="BLK-TL-BUFGCTRL.CE1" output="BUFGCTRL_VPR.CE1"/>
|
||||
<direct name="I0" input="BLK-TL-BUFGCTRL.I0" output="BUFGCTRL_VPR.I0"/>
|
||||
<direct name="I1" input="BLK-TL-BUFGCTRL.I1" output="BUFGCTRL_VPR.I1"/>
|
||||
<direct name="IGNORE0" input="BLK-TL-BUFGCTRL.IGNORE0" output="BUFGCTRL_VPR.IGNORE0"/>
|
||||
<direct name="IGNORE1" input="BLK-TL-BUFGCTRL.IGNORE1" output="BUFGCTRL_VPR.IGNORE1"/>
|
||||
<direct name="S0" input="BLK-TL-BUFGCTRL.S0" output="BUFGCTRL_VPR.S0"/>
|
||||
<direct name="S1" input="BLK-TL-BUFGCTRL.S1" output="BUFGCTRL_VPR.S1"/>
|
||||
|
||||
</interconnect>
|
||||
<metadata>
|
||||
<meta name="fasm_features">
|
||||
IN_USE
|
||||
</meta>
|
||||
</metadata>
|
||||
</mode>
|
||||
</pb_type>
|
||||
|
||||
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_<port_name>_`` and ``_TECHMAP_CONSTVAL_<port_name>_``
|
||||
are used together as names of parameters. The ``_TECHMAP_CONSTMASK_<port_name>_``
|
||||
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_<port_name>_`` bits store the actual constant signal
|
||||
values when the ``_TECHMAP_CONSTMASK_<port_name>_`` 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
|
||||
<http://www.clifford.at/yosys/>`_ , or in `Yosys Manual
|
||||
<http://www.clifford.at/yosys/files/yosys_manual.pdf>`_. 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.
|
||||
Loading…
Reference in New Issue