Hardware/f4pga
1
0
Fork 0
mirror of https://github.com/chipsalliance/f4pga.git synced 2025-01-03 03:43:37 -05:00
Code Issues Projects Releases Packages Wiki Activity

Add SymbiFlow toolchain description

Browse source 
Describe the synthesis and place and route process.
Add short description of Yosys synthesis tool.

Signed-off-by: Robert Winkler <rwinkler@internships.antmicro.com>
This commit is contained in:
Robert Winkler 2019-09-03 14:23:34 +02:00 committed by Tomasz Michalak
parent 6808082757
commit c73f9c8c96
7 changed files with 481 additions and 1 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

1
source/images/toolchain-flow.svg Normal file
View file

File diff suppressed because one or more lines are too long
Side by side

After

Width:  |  Height:  |  Size: 114 KiB

1
source/index.rst
View file

@ -7,6 +7,7 @@ SymbiFlow documentation
introduction introduction
fasm-specification fasm-specification
toolchain-desc
symbiflow-arch-defs/docs/source/index symbiflow-arch-defs/docs/source/index
prjxray/docs/index prjxray/docs/index
prjtrellis/docs/index prjtrellis/docs/index

2
source/symbiflow-arch-defs

@ -1 +1 @@
Subproject commit 9c494d1f43f87330d7eb3a7e6063f39b0933722b Subproject commit f25b843cd5fd28807a74188302d197db17119ea0

13
source/toolchain-desc.rst Normal file
View file

@ -0,0 +1,13 @@
Toolchain description
=====================
This section provides a description of the Symbiflow toolchain
as well as the basic concepts of the FPGA design flow.
.. toctree::
:maxdepth: 3
symbiflow-arch-defs/docs/source/getting-started
toolchain-desc/design-flow
toolchain-desc/yosys
toolchain-desc/vpr

159
source/toolchain-desc/design-flow.rst Normal file
View file

@ -0,0 +1,159 @@
FPGA Design Flow
================
SymbiFlow is an end-to-end FPGA synthesis toolchain, because of that it provides
all the necessary tools to convert input Verilog design into a final bitstream.
It is simple to use however, the whole synthesis and implementation process
is not trivial.
The final bitstream format depends on the used platform.
What's more, every platform has different resources and even if some of them
provide similar functionality, they can be implemented in a different way.
In order to be able to match all that variety of possible situations,
the creation of the final bitstream is divided into few steps.
SymbiFlow uses different programs to create the bitstream and is
responsible for their proper integration. The procedure of converting
Verilog file into the bitstream is described in the next sections.
.. figure:: ../images/toolchain-flow.svg
:align: center
Symbiflow Toolchain design flow
Synthesis
---------
Synthesis is the process of converting input Verilog file into a netlist,
which describes the connections between different block available on the
desired FPGA chip. However, it is worth to notice that these are only
logical connections. So the synthesized model is only a draft of the final
design, made with the use of available resources.
RTL Generation
++++++++++++++
the input Verilog file is often really complicated. Usually it is written in
a way that it is hard to distinguish the digital circuit standing behind
the implemented functionality. Designers often use a so-called
*Behavioral Level* of abstraction, in their designs, which means that the whole
description is mostly event-driven. In Verilog, support for behavioral models
is made with use of ``always`` statements.
However, FPGA mostly consist of Look Up Tables (LUT) and flip-flops.
Look Up Tables implement only the functionality of logic gates.
Due to that, the synthesis process has to convert the complicated
Behavioral model to a simpler description.
Firstly, the design is described in terms of registers and logical operations.
This is the so-called *Register-Transfer Level* (*RTL*).
Secondly, in order to simplify the design even more, some complex logic is
rewritten in the way that the final result contain only logic gates
and registers. This model is on *Logical Gate level* of abstraction.
The process of simplification is quite complicated, because of that it often
demands additional simulations between mentioned steps to prove that the input
design is equivalent to its simplified form.
Technology mapping
++++++++++++++++++
FPGAs from different architectures may have different architecture. For example,
they may contain some complicated functional blocks (i.e. RAM, DSP blocks)
and even some of the basic blocks like LUT tables and flip-flops may vary
between chips. Because of that, there is a need to describe the final design
in terms of platform-specific resources. This is the next step in the process
of synthesis. The simplified description containing i.e. logic gates, flip-flops
and a few more complicated blocks like RAM is taken and used "general" blocks
are substituted with that physically located in the chosen FPGA.
The vendor-specific definitions of these blocks are often located
in a separate library.
Optimization
++++++++++++
Optimization is the key factor that allows to better utilize resources
of an FPGA. There are some universal situations in which the design
can be optimized, for example by substituting a bunch of logic gates
in terms of fewer, different gates. However, some operations can be performed
only after certain steps i.e. after technology mapping.
As a result, optimization is an integral part of most of the synthesis steps.
Synthesis in SymbiFlow
++++++++++++++++++++++
In the SymbiFlow toolchain synthesis is made with the use of Yosys,
that is able to perform all the mentioned steps and convert Verilog to netlist
description. The result of these steps is written to a file in ``.eblif``
format.
Place & Route
-------------
The Synthesis process results in an output containing logical elements
available on the desired FPGA chip with the specified connections between them.
However, it does not specify the physical layout of those elements in the
final design. The goal of the Place and Route (PnR) process is to take the
synthesized design and implement it into the target FPGA device. The PnR tool
needs to have information about the physical composition of the device, routing
paths between the different logical blocks and signal propagation timings.
The working flow of different PnR tools may vary, however, the process presented
below represents the typical one, adopted by most of these tools. Usually, it
consists of four steps - packing, placing, routing and analysis.
Packing
+++++++
In the first step, the tool collects and analyzes the primitives present
in the synthesized design (e.g. Flip-Flops, Muxes, Carry-chains, etc), and
organizes them in clusters, each one belonging to a physical tile of the device.
The PnR tool makes the best possible decision, based on the FPGA routing
resources and timings between different points in the chip.
Placing
+++++++
After having clustered all the various primitives into the physical tiles of the
device, the tool begins the placement process. This step consists in assigning a
physical location to every cluster generated in the packing stage. The choice of
the locations is based on the chosen algorithm and on the user's parameters, but
generally, the final goal is to find the best placement that allows the routing
step to find more optimal solutions.
Routing
+++++++
Routing is one of the most demanding tasks of the the whole process.
All possible connections between the placed blocks and the information on
the signals propagation timings, form a complex graph.
The tool tries to find the optimal path connecting all the placed
clusters using the information provided in the routing graph. Once all the nets
have been routed, an output file containing the implemented design is produced.
Analysis
++++++++
This last step usually checks the whole design in terms of timings and power
consumption.
Place & Route in SymbiFlow
++++++++++++++++++++++++++
The SymbiFlow 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.
Bitstream translation
---------------------
The routing process results in an output file specifying the used blocks
and routing paths. It contains the resources that needs to be instantiated
on the FPGA chip, however, the output format is not understood
by the FPGA chip itself.
In the last step, the description of the chip is translated into
the appropriate format, suitable for the chosen FPGA.
That final file contains instructions readable by the configuration block of
the desired chip.
Documenting the bitstream format for different FPGA chips is one of the
most important tasks in the SymbiFlow Project!

170
source/toolchain-desc/vpr.rst Normal file
View file

@ -0,0 +1,170 @@
Versatile Place and Route
=========================
Versatile Place and Route (VPR) is an open-source CAD tool that
implements different placing and routing algorithms for FPGAs. It can be used
to prepare a description of a complete chip configuration
from a given logic design.
As its input, the VPR takes the netlist specified in the `BLIF
file format <https://docs.verilogtorouting.org/en/latest/_downloads/773c1e1024574545e6f692e46935cee0/blif.pdf>`_
and `architecture definition <https://docs.verilogtorouting.org/en/latest/tutorials/arch/#arch-tutorial>`_
in the XML file. The whole process of generating configuration is described in
`FPGA Design Flow <./design-flow.html>`_. One of the most important goals of
the SymbiFlow Toolchain is to provide accurate `architecture definitions
<../symbiflow-arch-defs/docs/source/index.html>`__ that are needed in the
Place and Route process.
Summary
-------
The Place and Route process in VPR consists of a few steps:
- Packing (combining primitives into complex logic blocks)
- Placing (placement of complex block inside FPGA)
- Routing (planning interconnections between blocks)
- Analysis
Each of these steps provides additional configuration options that can be used
for customizing the whole process. Detailed description is avaliable on the
project website in the `VPR section <https://vtr.readthedocs.io/en/latest/vpr/>`_ of the VTR documentation.
Packing
-------
The packing algorithm tries to combine primitive logic blocks into groups,
called Complex Logic Blocks. The results from the packing process are written
into a ``.net`` file. It contains a description of complex blocks with their
inputs, outputs, used clocks and relations to other signals.
It can be useful in analyzing how VPR packs primitives together.
A detailed description of the ``.net`` file format can be found in the `VPR documentation
<https://vtr.readthedocs.io/en/latest/vpr/file_formats/#packed-netlist-format-net>`_.
Placing
-------
This step assigns a location to the Complex Logic Block onto the FPGA.
The output from this step is written in the ``.place`` file, which contains
the physical location of the blocks from the ``.net`` file.
The File has the following format:
.. code-block:: bash
block_name x y subblock_number
where ``x`` and ``y`` are positions in VPR grid and ``block_name`` comes from
the ``.net`` file.
Example placing file:
.. code-block::
Netlist_File: top.net Netlist_ID: SHA256:ce5217d251e04301759ee5a8f55f67c642de435b6c573148b67c19c5e054c1f9
Array size: 149 x 158 logic blocks
#block name x y subblk block number
#---------- -- -- ------ ------------
$auto$alumacc.cc:474:replace_alu$24.slice[1].carry4_full 53 32 0 #0
$auto$alumacc.cc:474:replace_alu$24.slice[2].carry4_full 53 31 0 #1
$auto$alumacc.cc:474:replace_alu$24.slice[3].carry4_full 53 30 0 #2
$auto$alumacc.cc:474:replace_alu$24.slice[4].carry4_full 53 29 0 #3
$auto$alumacc.cc:474:replace_alu$24.slice[5].carry4_full 53 28 0 #4
$auto$alumacc.cc:474:replace_alu$24.slice[6].carry4_part 53 27 0 #5
$auto$alumacc.cc:474:replace_alu$24.slice[0].carry4_1st_full 53 33 0 #6
out:LD7 9 5 0 #7
clk 42 26 0 #8
$false 35 26 0 #9
Detailed description of the ``.place`` file format can be found in the `VPR documentation
<https://vtr.readthedocs.io/en/latest/vpr/file_formats/#placement-file-format-place>`_.
Routing
-------
This step connects the placed Complex Logic Blocks together,
according to the netlist specifications and the routing resources
of the FPGA chip. The description of the routing resources is
provided in the `architecture definition file
<https://docs.verilogtorouting.org/en/latest/arch/reference/#arch-reference>`__.
Starting from the architecture definition, VPR generates the Resource
Routing Graph. SymbiFlow provides a complete graph file for each architecture.
This `precompiled` file can be directly injected into the routing process.
The output from this step is written into ``.route`` file.
The file describes each connection from input to its output through
different routing resources of FPGA. Each net starts with a ``SOURCE`` node and
ends in a ``SINK`` node. The node name describes the kind of routing resource.
The pair of numbers in round brackets provides information on the (x, y)
resource location on the VPR grid. The additional field provides information
for a specific kind of node.
Example routing file may look similar:
.. code-block::
Placement_File: top.place Placement_ID: SHA256:88d45f0bf7999e3f9331cdfd3497d0028be58ffa324a019254c2ae7b4f5bfa7a
Array size: 149 x 158 logic blocks.
Routing:
Net 0 (counter[4])
Node: 203972 SOURCE (53,32) Class: 40 Switch: 0
Node: 204095 OPIN (53,32) Pin: 40 BLK-TL-SLICEL.CQ[0] Switch: 189
Node: 1027363 CHANY (52,32) Track: 165 Switch: 7
Node: 601704 CHANY (52,32) Track: 240 Switch: 161
Node: 955959 CHANY (52,32) to (52,33) Track: 90 Switch: 130
Node: 955968 CHANY (52,32) Track: 238 Switch: 128
Node: 955976 CHANY (52,32) Track: 230 Switch: 131
Node: 601648 CHANY (52,32) Track: 268 Switch: 7
Node: 1027319 CHANY (52,32) Track: 191 Switch: 183
Node: 203982 IPIN (53,32) Pin: 1 BLK-TL-SLICEL.A2[0] Switch: 0
Node: 203933 SINK (53,32) Class: 1 Switch: -1
Net 1 ($auto$alumacc.cc:474:replace_alu$24.O[6])
...
A detailed description of the ``.route`` file format can be found in the `VPR documentation
<https://vtr.readthedocs.io/en/latest/vpr/file_formats/#routing-file-format-route>`_.
FASM file
---------
SymbiFlow makes use of an additional tool provided by VPR, called
`genfasm <https://docs.verilogtorouting.org/en/latest/utils/fasm/>`_.
In fact, genfasm translates the routed design into a FASM format file.
This file provides the description of the implemented design in terms of
features that need to be enabled or disabled in the FPGA chip.
These changes are made with respect to the default FPGA configuration.
Due to that, empty FASM file sets the FPGA to the default configuration.
FASM file contains lines in the format:
.. code-block::
YYYY.XXXXX [A:B] = C
which corresponds respectively to the feature ID, feature address
and the feature value. The feature ID unambiguously describes the location of
the resource that needs to be modified. Within this resource, may exists several
bits that determine its behaviour. The feature address specifies the set of bits
in the resource that will be changed to the chosen feature value.
Example of a FASM line:
.. code-block::
CLBLM_R_X41Y31.SLICEL_X1.ALUT.INIT[63:32]=32'b11110000111100001111000011110000
will initialize the bits ``[63:32]`` of ``ALUT.INIT`` feature, located in the
``SLICEL_X1`` of the ``CLBLM_R_X41Y31`` tile with the
``32'b11110000111100001111000011110000`` value.
It is worth to mention that only the feature ID is necessary and setting feature
value to ``0`` means that feature has a default setting not that it is disabled.
A detailed description of FASM file format used in SymbiFlow could be found
in the `FASM specification <../used-standards/fasm-specification.html>`_.

136
source/toolchain-desc/yosys.rst Normal file
View file

@ -0,0 +1,136 @@
Yosys
=====
Yosys is a Free and Open Source Verilog HDL synthesis tool. It was designed
to be highly extensible and multiplatform. In SymbiFlow 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 the SymbiFlow
toolchain. 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 one used in the synthesis process, called respectively
*frontend* and *backend*. Intermediate subsystems are called *passes*.
The *frontend* is responsible for changing the Verilog input file into
internal Yosys, representation which is common for all *passes* used
by the program. The *passes* are responsible for 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 that located on FPGA chip including i.e. RAM, DSP and LUTs.
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. Symbiflow 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.
Example of 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 perform 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 `Symbiflow Architecture Definitions <https://github.com/SymbiFlow/symbiflow-arch-defs>`_
repository.
To understand performed operations it is worth to look at log file. Usually it
is 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.
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.