From e0086c7513cac583d0a85ca5409aef92eaaeda18 Mon Sep 17 00:00:00 2001 From: Unai Martinez-Corral Date: Thu, 4 Aug 2022 05:25:44 +0200 Subject: [PATCH] docs: move 'understanding' from f4pga-examples as 'f4pga/Deprecated' Signed-off-by: Unai Martinez-Corral --- docs/f4pga/Deprecated.rst | 194 ++++++++++++++++++++++++++++++++++++++ docs/f4pga/index.rst | 2 + docs/flows/f4pga.rst | 2 + docs/flows/index.rst | 2 + docs/index.rst | 1 + 5 files changed, 201 insertions(+) create mode 100644 docs/f4pga/Deprecated.rst diff --git a/docs/f4pga/Deprecated.rst b/docs/f4pga/Deprecated.rst new file mode 100644 index 0000000..d7df40f --- /dev/null +++ b/docs/f4pga/Deprecated.rst @@ -0,0 +1,194 @@ +.. _Understanding: + +Understanding the (deprecated) flow +################################### + +.. IMPORTANT:: + This section describes the usage of the now deprecated ``symbiflow_*`` entrypoints/wrappers. + It is provided for backwards compatibility, so that users of the *old* flow can keep using it. + However, it is recommended for new users to use the approach explained in :ref:`pyF4PGA`. + +This section provides valuable information on how each of the commands used to compile and build +designs in F4PGA 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 F4PGA works take a look at the :ref:`Design Flows section `. + +.. 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 F4PGA go to :ref:`Flows:F4PGA:Yosys`. + +.. 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 `VPR ➚ `__. + +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. + +.. warning:: + + If you change the name of the output for your bitstream to something other than top.bit then the + openFPGALoader command used in the examples would need to change too. For example if I used + ``-b my_module_top`` in symbiflow_write_bitstream then my openFPGALoader command would change to: + + .. code-block:: bash + + openFPGALoader -b $OFL_BOARD my_module_top.bit + + Note that the only part of the command that changes is ".bit;" + +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 diff --git a/docs/f4pga/index.rst b/docs/f4pga/index.rst index baf587d..3bde79a 100644 --- a/docs/f4pga/index.rst +++ b/docs/f4pga/index.rst @@ -1,3 +1,5 @@ +.. _pyF4PGA: + Overview ######## diff --git a/docs/flows/f4pga.rst b/docs/flows/f4pga.rst index 20073d2..fb7c275 100644 --- a/docs/flows/f4pga.rst +++ b/docs/flows/f4pga.rst @@ -8,6 +8,8 @@ In the F4PGA toolchain synthesis is made with the use of Yosys, that is able to convert HDL to netlist description. The result of these steps is written to a file in ``.eblif`` format. +.. _Flows:F4PGA:Yosys: + Yosys ===== diff --git a/docs/flows/index.rst b/docs/flows/index.rst index 6afae87..e245d66 100644 --- a/docs/flows/index.rst +++ b/docs/flows/index.rst @@ -1,3 +1,5 @@ +.. _Flows: + Introduction ============ diff --git a/docs/index.rst b/docs/index.rst index 683973d..37e697a 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -27,6 +27,7 @@ The project aims to design tools that are highly extendable and multiplatform. f4pga/Usage f4pga/modules/index f4pga/DevNotes + f4pga/Deprecated .. toctree::