From c73f9c8c9639b08f609453f9e1c9127c4c9702e5 Mon Sep 17 00:00:00 2001 From: Robert Winkler Date: Tue, 3 Sep 2019 14:23:34 +0200 Subject: [PATCH] Add SymbiFlow toolchain description Describe the synthesis and place and route process. Add short description of Yosys synthesis tool. Signed-off-by: Robert Winkler --- source/images/toolchain-flow.svg | 1 + source/index.rst | 1 + source/symbiflow-arch-defs | 2 +- source/toolchain-desc.rst | 13 ++ source/toolchain-desc/design-flow.rst | 159 ++++++++++++++++++++++++ source/toolchain-desc/vpr.rst | 170 ++++++++++++++++++++++++++ source/toolchain-desc/yosys.rst | 136 +++++++++++++++++++++ 7 files changed, 481 insertions(+), 1 deletion(-) create mode 100644 source/images/toolchain-flow.svg create mode 100644 source/toolchain-desc.rst create mode 100644 source/toolchain-desc/design-flow.rst create mode 100644 source/toolchain-desc/vpr.rst create mode 100644 source/toolchain-desc/yosys.rst diff --git a/source/images/toolchain-flow.svg b/source/images/toolchain-flow.svg new file mode 100644 index 0000000..1355658 --- /dev/null +++ b/source/images/toolchain-flow.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/source/index.rst b/source/index.rst index 3348b9f..0d107f1 100644 --- a/source/index.rst +++ b/source/index.rst @@ -7,6 +7,7 @@ SymbiFlow documentation introduction fasm-specification + toolchain-desc symbiflow-arch-defs/docs/source/index prjxray/docs/index prjtrellis/docs/index diff --git a/source/symbiflow-arch-defs b/source/symbiflow-arch-defs index 9c494d1..f25b843 160000 --- a/source/symbiflow-arch-defs +++ b/source/symbiflow-arch-defs @@ -1 +1 @@ -Subproject commit 9c494d1f43f87330d7eb3a7e6063f39b0933722b +Subproject commit f25b843cd5fd28807a74188302d197db17119ea0 diff --git a/source/toolchain-desc.rst b/source/toolchain-desc.rst new file mode 100644 index 0000000..669a4e1 --- /dev/null +++ b/source/toolchain-desc.rst @@ -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 diff --git a/source/toolchain-desc/design-flow.rst b/source/toolchain-desc/design-flow.rst new file mode 100644 index 0000000..d17f337 --- /dev/null +++ b/source/toolchain-desc/design-flow.rst @@ -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! diff --git a/source/toolchain-desc/vpr.rst b/source/toolchain-desc/vpr.rst new file mode 100644 index 0000000..f8c375e --- /dev/null +++ b/source/toolchain-desc/vpr.rst @@ -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 `_ +and `architecture definition `_ +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 `_ 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 +`_. + +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 +`_. + +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 +`__. +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 +`_. + +FASM file +--------- + +SymbiFlow makes use of an additional tool provided by VPR, called +`genfasm `_. +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>`_. diff --git a/source/toolchain-desc/yosys.rst b/source/toolchain-desc/yosys.rst new file mode 100644 index 0000000..de70a6b --- /dev/null +++ b/source/toolchain-desc/yosys.rst @@ -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 ``/yosys/synth.tcl`` +in `Symbiflow Architecture Definitions `_ +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 +`_ , 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.