_sources/f4pga/Deprecated.rst.txt - symbiflow-docs - Git at Google

 .. _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 <Flows>`.

 .. 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 ➚ <https://docs.verilogtorouting.org/en/latest/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 "<top module name>.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
	.. _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 <Flows>`.

	.. 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 ➚ <https://docs.verilogtorouting.org/en/latest/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 "<top module name>.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