179 lines
8.3 KiB
ReStructuredText
179 lines
8.3 KiB
ReStructuredText
Understanding Toolchain Commands
|
|
=================================
|
|
|
|
This section provides valuable information on how each of the commands used to compile and build
|
|
designs in Symbiflow work. It is especially helpful for debugging or for using methods
|
|
other than a makefile to build your designs, such as a bash or python script.
|
|
|
|
The following describes the commands for running each of the steps for a full design flow
|
|
(synthesis, place and route, and generate bitstream) as well as giving a description of the most
|
|
common flags for those commands. If you would like a more detailed break down of how the design
|
|
flow for Symbiflow works take a look at the
|
|
`FPGA Design Flow page <https://symbiflow.readthedocs.io/en/latest/toolchain-desc/design-flow.html>`_.
|
|
|
|
.. note::
|
|
|
|
Files created by synthesis, implementation, and bitstream generation will be dumped into
|
|
the directory from which the command is run by default. To keep all of the files generated by
|
|
the toolchain separate from your design files, you might consider running the toolchain
|
|
commands in a separate directory from your design files.
|
|
|
|
|
|
|
|
Synthesis
|
|
----------
|
|
|
|
To synthesize your designs run the ``symbiflow_synth`` command. The command has the following
|
|
flags:
|
|
|
|
.. table:: symbiflow_synth
|
|
|
|
+------+---------------------------------------------------------------+
|
|
| Flag | Argument |
|
|
+======+===============================================================+
|
|
| -t | Defines the name for the top level module |
|
|
+------+---------------------------------------------------------------+
|
|
| -v | A list of paths to verilog files for the design |
|
|
+------+---------------------------------------------------------------+
|
|
| -d | FPGA family (i.e. artix7 or zynq7) |
|
|
+------+---------------------------------------------------------------+
|
|
| -p | The part number for the FPGA (i.e xc7a35tcsg324-1) |
|
|
+------+---------------------------------------------------------------+
|
|
| -x | Optional command: path to xdc files for design |
|
|
+------+---------------------------------------------------------------+
|
|
|
|
|
|
An example of how to run synthesis on a design containing two separate
|
|
verilog HDL files is below. The design is built for a basys3 board which comes from the artix7
|
|
family and uses the xc7a35tcpg236-1 chip.
|
|
|
|
.. code-block:: bash
|
|
|
|
symbiflow_synth -t top -v example.v top_example.v -d artix7 -p xc7a35tcpg236-1 -x design_constraint.xdc
|
|
|
|
Synthesis is carried out using the Yosys open source tool. ``symbiflow_synth`` generates
|
|
an .eblif file, a few verilog netlists that describe the gate level design for your project, and a log
|
|
file. For more information on Yosys and its relation to Symbiflow go to the
|
|
`Symbiflow-Yosys page <https://symbiflow.readthedocs.io/en/latest/toolchain-desc/yosys.html>`_.
|
|
|
|
.. note::
|
|
The build files generated by the toolchain (for example .eblif from synthesis, .net from
|
|
packing, .bit from generate bitstream) are named using the top module specified in
|
|
symbiflow_synth. For example if you specified ``switch_top`` as the top level module name
|
|
during synthesis using the ``-t`` flag, the build files generated by the toolchain would be
|
|
named switch_top.eblif, switch_top.net, etc.
|
|
|
|
|
|
Place and Route
|
|
----------------
|
|
|
|
The three steps for implementing a design are internally handled by the open source VPR
|
|
(Versatile Place and Route) tool. For more information go to
|
|
`the Symbiflow VPR page <https://symbiflow.readthedocs.io/en/latest/vtr-verilog-to-routing/doc/src/vpr/index.html>`_.
|
|
|
|
Pack
|
|
+++++
|
|
|
|
Packing is run by the ``symbiflow_pack`` command and generates several files containing
|
|
a pin usage report, a timing report, a log file, and a netlist. The various flags for the
|
|
pack command are as follows:
|
|
|
|
.. table:: symbiflow_pack
|
|
|
|
+------+--------------------------------------------------------------------+
|
|
| Flag | Argument |
|
|
+======+====================================================================+
|
|
| -e | Path to .eblif file generated by synthesis |
|
|
+------+--------------------------------------------------------------------+
|
|
| -d | Fabric definition for the board (i.e. xc7a100t_test) |
|
|
+------+--------------------------------------------------------------------+
|
|
| -s | Optional: SDC file path |
|
|
+------+--------------------------------------------------------------------+
|
|
|
|
Note that the -d option for this step (defining the fabric definition) is different
|
|
from the -d from synthesis (defining the FPGA family).
|
|
|
|
The following example runs packing on the basys3 board:
|
|
|
|
.. code-block:: bash
|
|
|
|
symbiflow_pack -e top.eblif -d xc7a35t_test
|
|
|
|
Place
|
|
++++++
|
|
|
|
Placement generates several files describing the location of design elements
|
|
as well as a log file. Placement is run using ``symbiflow_place`` which utilizes
|
|
the following flags:
|
|
|
|
.. table:: symbiflow_place
|
|
|
|
+------+----------------------------------------------------+
|
|
| Flag | Argument |
|
|
+======+====================================================+
|
|
| -e | Path to .eblif file generated by synthesis |
|
|
+------+----------------------------------------------------+
|
|
| -d | Fabric definition (xc7a50t_test) |
|
|
+------+----------------------------------------------------+
|
|
| -p | Optional: PCF file path |
|
|
+------+----------------------------------------------------+
|
|
| -n | Path to the .net file generated by pack step |
|
|
+------+----------------------------------------------------+
|
|
| -P | The part number for the FPGA (i.e xc7a35tcsg324-1) |
|
|
+------+----------------------------------------------------+
|
|
| -s | Optional: SDC file path |
|
|
+------+----------------------------------------------------+
|
|
|
|
For the basys3:
|
|
|
|
.. code-block:: bash
|
|
|
|
symbiflow_pack -e top.eblif -d xc7a35t_test -p design.pcf -n top.net -P xc7a35tcpg236-1 -s design.sdc
|
|
|
|
|
|
Route
|
|
++++++
|
|
|
|
Routing produces several timing reports as well as a post routing netlist and log file.
|
|
``symbiflow_route`` uses the -e, -d, and the optional -s flags. The arguments for these flags
|
|
are the same as in the placement step (.eblif, fabric definition, and SDC file path respectively).
|
|
The following is an example:
|
|
|
|
.. code-block:: bash
|
|
|
|
symbiflow_route -e top.eblif -d xc7a35t_test -s design.sdc
|
|
|
|
|
|
Generating Bitstream
|
|
----------------------
|
|
|
|
Generating the bitstream consists of two steps. First, run ``symbiflow_write_fasm`` to generate
|
|
the .fasm file used to create the bitstream. ``symbiflow_write_fasm`` uses the -e and -d flags
|
|
with the same arguments as the placing and routing steps (.eblif path, and fabric definition).
|
|
Second, run ``symbiflow_write_bitstream`` which has the following flags:
|
|
|
|
.. table:: symbiflow_write_bitstream
|
|
|
|
+------+-------------------------------------------------------+
|
|
| Flag | Argument |
|
|
+======+=======================================================+
|
|
| -d | FPGA family (i.e. artix7 or zynq7) |
|
|
+------+-------------------------------------------------------+
|
|
| -f | The path to the .fasm file generated in by write_fasm |
|
|
+------+-------------------------------------------------------+
|
|
| -p | The FPGA part number (i.e xc7a35tcsg324-1) |
|
|
+------+-------------------------------------------------------+
|
|
| -b | Name of the file to write the bitstream to |
|
|
+------+-------------------------------------------------------+
|
|
|
|
Notice that the specification for the part number is a lowercase ``-p`` instead of a capital
|
|
``-P`` as in the placement step. Also note that the ``-d`` in write_bitstream defines the FPGA
|
|
family instead of the fabric as in the write_fasm step.
|
|
|
|
The following example generates a bitstream file named example.bit for the basys3 board:
|
|
|
|
.. code-block:: bash
|
|
|
|
symbiflow_write_fasm -e top.eblif -d xc7a50t_test
|
|
symbiflow_write_bitstream -d artix7 -f top.fasm -p xc7a35tcpg236-1 -b example.bit
|