Hardware
/
f4pga
mirror of https://github.com/chipsalliance/f4pga.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #346 from antmicro/techmapping 

Add techmapping description
This commit is contained in:
Robert Winkler 2020-09-30 22:35:44 +02:00 committed by GitHub
parent 4d95bbdace 747740a6b1
commit 092969ea14
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
3 changed files with 287 additions and 12 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
requirements.txt
View File

@ -1,5 +1,6 @@
Sphinx==3.0.4 Sphinx==3.0.4
git+http://github.com/SymbiFlow/sphinx_materialdesign_theme.git@master#egg=sphinx_symbiflow_theme git+http://github.com/SymbiFlow/sphinx_materialdesign_theme.git@master#egg=sphinx_symbiflow_theme
git+http://github.com/SymbiFlow/sphinx-verilog-domain
sphinx-markdown-tables==0.0.12 sphinx-markdown-tables==0.0.12
breathe==4.18.1 breathe==4.18.1
symbolator==1.0.2 symbolator==1.0.2

3
source/conf.py
View File

@ -36,7 +36,8 @@ extensions = [
'sdcdomain', 'sdcdomain',
'archdomain', 'archdomain',
'rrgraphdomain', 'rrgraphdomain',
'recommonmark' 'recommonmark',
'sphinx_verilog_domain'
] ]
numfig = True numfig = True

295
source/toolchain-desc/yosys.rst
View File

@ -10,18 +10,18 @@ It is not necessary to call Yosys directly using the SymbiFlow
toolchain. Nevertheless, the following description, should provide toolchain. Nevertheless, the following description, should provide
sufficient introduction to Yosys usage inside the project. sufficient introduction to Yosys usage inside the project.
It is also a good starting point for a deeper understanding of the whole It is also a good starting point for a deeper understanding of the whole
Toolchain. toolchain.
Short description Short description
----------------- -----------------
Yosys consists of several subsystems. Most distinguishable are the Yosys consists of several subsystems. Most distinguishable are the
first and last one used in the synthesis process, called respectively first and last ones used in the synthesis process, called *frontend*
*frontend* and *backend*. Intermediate subsystems are called *passes*. and *backend* respectively. Intermediate subsystems are called *passes*.
The *frontend* is responsible for changing the Verilog input file into The *frontend* is responsible for changing the Verilog input file into
internal Yosys, representation which is common for all *passes* used an internal Yosys, representation which is common for all *passes* used
by the program. The *passes* are responsible for variety of optimizations by the program. The *passes* are responsible for a variety of optimizations
(``opt_``) and simplifications (``proc_``). (``opt_``) and simplifications (``proc_``).
Two *passes*, that are worth Two *passes*, that are worth
@ -29,7 +29,7 @@ to mention separately are ``ABC`` and ``techmap``. The first one optimizes
logic functions from the design and assigns obtained results into Look Up Tables logic functions from the design and assigns obtained results into Look Up Tables
(LUTs) of chosen width. The second mentioned *pass* - ``techmap`` (LUTs) of chosen width. The second mentioned *pass* - ``techmap``
is responsible for mapping the synthesized design from Yosys internal is responsible for mapping the synthesized design from Yosys internal
blocks to that located on FPGA chip including i.e. RAM, DSP and LUTs. blocks to the primitives used by the implementation tool.
Recommended synthesis flows for different FPGAs are combined into Recommended synthesis flows for different FPGAs are combined into
macros i.e. ``synth_ice40`` (for Lattice iCE40 FPGA) or ``synth_xilinx`` macros i.e. ``synth_ice40`` (for Lattice iCE40 FPGA) or ``synth_xilinx``
(for Xilinx 7-series FPGAs). (for Xilinx 7-series FPGAs).
@ -45,7 +45,7 @@ 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 in the scripts are responsible for preparing output file to match with the
expectations of other toolchain tools. expectations of other toolchain tools.
There is no need to change it even for big designs. There is no need to change it even for big designs.
Example of configuration script can be found below: An example configuration script can be found below:
.. code-block:: tcl .. code-block:: tcl
@ -60,15 +60,15 @@ Example of configuration script can be found below:
write_blif -attr -cname -param $::env(OUT_EBLIF) write_blif -attr -cname -param $::env(OUT_EBLIF)
write_verilog $::env(OUT_SYNTH_V) write_verilog $::env(OUT_SYNTH_V)
It can be seen that this script perform a platform-specific process of 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 synthesis, some optimization steps (``opt_`` commands), and writes the final file in
``.eblif`` and Verilog formats. Yosys synthesis configuration scripts are platform-specific ``.eblif`` and Verilog formats. Yosys synthesis configuration scripts are platform-specific
and can by found in ``<platform-dir>/yosys/synth.tcl`` and can by found in ``<platform-dir>/yosys/synth.tcl``
in `Symbiflow Architecture Definitions <https://github.com/SymbiFlow/symbiflow-arch-defs>`_ in the `Symbiflow Architecture Definitions <https://github.com/SymbiFlow/symbiflow-arch-defs>`_
repository. repository.
To understand performed operations it is worth to look at log file. Usually it To understand performed operations, view the log file. It is usually generated
is generated in the project build directory. It should be named ``top.eblif.log``. in the project build directory. It should be named ``top.eblif.log``.
Output analysis Output analysis
--------------- ---------------
@ -126,6 +126,279 @@ chosen platform:
The same structure is described by the ``.eblif`` file. The same structure is described by the ``.eblif`` file.
Technology mapping in SymbiFlow 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 SymbiFlow 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 SymbiFlow. By default, the SymbiFlow
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 SymbiFlow 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 SymbiFlow 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 More information
---------------- ----------------