From e9dc708d66210150f600ba684ceb0fb95193d9c1 Mon Sep 17 00:00:00 2001 From: tangxifan Date: Tue, 19 Jan 2021 19:44:44 -0700 Subject: [PATCH 1/3] [Doc] Group file format documentation into a unified section --- docs/source/manual/arch_lang/fabric_key.rst | 149 +---------------- .../file_formats/architecture_bitstream.rst | 100 ++++++++++++ .../manual/file_formats/fabric_bitstream.rst | 108 +++++++++++++ .../source/manual/file_formats/fabric_key.rst | 151 ++++++++++++++++++ docs/source/manual/file_formats/index.rst | 7 + .../file_formats/pin_constraints_file.rst | 4 +- .../repack_design_constraints.rst | 6 +- .../fabric_dependent_bitstream.rst | 93 +---------- .../fpga_bitstream/generic_bitstream.rst | 95 +---------- docs/source/manual/fpga_bitstream/index.rst | 2 - .../fpga_bitstream_commands.rst | 2 +- 11 files changed, 376 insertions(+), 341 deletions(-) create mode 100644 docs/source/manual/file_formats/architecture_bitstream.rst create mode 100644 docs/source/manual/file_formats/fabric_bitstream.rst create mode 100644 docs/source/manual/file_formats/fabric_key.rst rename docs/source/manual/{fpga_bitstream => file_formats}/repack_design_constraints.rst (91%) diff --git a/docs/source/manual/arch_lang/fabric_key.rst b/docs/source/manual/arch_lang/fabric_key.rst index 81a45fa37..ebf6a3153 100644 --- a/docs/source/manual/arch_lang/fabric_key.rst +++ b/docs/source/manual/arch_lang/fabric_key.rst @@ -27,151 +27,4 @@ A fabric key can be achieved in the following ways: File Format ``````````` -A fabric key follows an XML format. As shown in the following XML code, the key file includes the organization of configurable blocks in the top-level FPGA fabric. - -Configurable Region -^^^^^^^^^^^^^^^^^^^ - -The top-level FPGA fabric can consist of several configurable regions, where a region may contain one or multiple configurable blocks. Each configurable region can be configured independently and in parrallel. - -.. option:: - - - ``id`` indicates the unique id of a configurable region in the fabric. - - .. warning:: The id must start from zero! - - .. note:: The number of regions defined in the fabric key must be consistent with the number of regions defined in the configuration protocol of architecture description. (See details in :ref:`config_protocol`). - -The following example shows how to define multiple configuration regions in the fabric key. - -.. code-block:: xml - - - - - - - - - - - - - - - - - - - - - - - - - - -Configurable Block -^^^^^^^^^^^^^^^^^^^ - -Each configurable block is defined as a key. There are two ways to define a key, either with alias or with name and value. - -.. option:: - - - ``id`` indicates the sequence of the configurable memory block in the top-level FPGA fabric. - - - ``name`` indicates the module name of the configurable memory block. This property becomes optional when ``alias`` is defined. - - - ``value`` indicates the instance id of the configurable memory block in the top-level FPGA fabric. This property becomes optional when ``alias`` is defined. - - - ``alias`` indicates the instance name of the configurable memory block in the top-level FPGA fabric. If a valid alias is specified, the ``name`` and ``value`` are not required. - -.. warning:: For fast loading of fabric key, strongly recommend to use pairs ``name`` and ``alias`` or ``name`` and ``value`` in the fabric key file. Using only ``alias`` may cause long parsing time for fabric key. - -The following is an example of a fabric key generate by OpenFPGA for a 2 :math:`\times` 2 FPGA. -This key contains only ``alias`` which is easy to craft. - -.. code-block:: xml - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -The following shows another example of a fabric key generate by OpenFPGA for a 2 :math:`\times` 2 FPGA. -This key contains only ``name`` and ``value`` which is fast to parse. - -.. code-block:: xml - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +See details in :ref:`file_formats_fabric_key` diff --git a/docs/source/manual/file_formats/architecture_bitstream.rst b/docs/source/manual/file_formats/architecture_bitstream.rst new file mode 100644 index 000000000..e6cf892f6 --- /dev/null +++ b/docs/source/manual/file_formats/architecture_bitstream.rst @@ -0,0 +1,100 @@ +.. _file_formats_architecture_bitstream: + +Architecture Bitstream (.xml) +----------------------------- + +OpenFPGA can output the generic bitstream to an XML format, which is easy to debug. As shown in the following XML code, configuration bits are organized block by block, where each block could be a LUT, a routing multiplexer `etc`. Each ``bitstream_block`` includes the following information: + + - ``name`` represents the instance name which you can find in the fabric netlists + + - ``hierarchy_level`` represents the depth of this block in the hierarchy of the FPGA fabric. It always starts from 0 as the root. + + - ``hierarchy`` represents the location of this block in FPGA fabric. + The hierachy includes the full hierarchy of this block + + - ``instance`` denotes the instance name which you can find in the fabric netlists + + - ``level`` denotes the depth of the block in the hierarchy + + - ``input_nets`` represents the path ids and net names that are mapped to the inputs of block. Unused inputs will be tagged as ``unmapped`` which is a reserved word of OpenFPGA. Path id corresponds the selected ``path_id`` in the ```` node. + + - ``output_nets`` represents the path ids and net names that are mapped to the outputs of block. Unused outputs will be tagged as ``unmapped`` which is a reserved word OpenFPGA. + + - ``bitstream`` represents the configuration bits affiliated to this block. + + - ``path_id`` denotes the index of inputs which is propagated to the output. Note that smallest valid index starts from zero. Only routing multiplexers have the path index. Unused routing multiplexer will not have a ``path_id`` of ``-1``, which allows bitstream assembler to freely find the best path in terms of Quality of Results (QoR). A used routing multiplexer should have a zero or positive ``path_id``. + + - ``bit`` denotes a single configuration bit under this block. It contains \ + + - ``memory_port`` the memory port name which you can find in the fabric netlists by following the hierarchy. + + - ``value`` a binary value which is the configuration bit assigned to the memory port. + +.. code-block:: xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/source/manual/file_formats/fabric_bitstream.rst b/docs/source/manual/file_formats/fabric_bitstream.rst new file mode 100644 index 000000000..ce321cc81 --- /dev/null +++ b/docs/source/manual/file_formats/fabric_bitstream.rst @@ -0,0 +1,108 @@ +.. _file_formats_fabric_bitstream: + +Fabric-dependent Bitstream +-------------------------- + +.. _file_formats_fabric_bitstream_plain_text: + +Plain text (.txt) +~~~~~~~~~~~~~~~~~ + +This file format is designed to be directly loaded to an FPGA fabric. +It does not include any comments but only bitstream. + +The information depends on the type of configuration procotol. + +.. option:: vanilla + + A line consisting of ``0`` | ``1`` + +.. option:: scan_chain + + A line consisting of ``0`` | ``1`` + +.. option:: memory_bank + + Multiple lines will be included, each of which is organized as
. + Note that due to the use of Bit-Line and Word-Line decoders, every two lines are paired. + The first line represents the Bit-Line address and configuration bit. + The second line represents the Word-Line address and configuration bit. + For example + + .. code-block:: xml + + + + + + ... + + + +.. option:: frame_based + + Multiple lines will be included, each of which is organized as
. + Note that the address may include don't care bit which is denoted as ``x``. + OpenFPGA automatically convert don't care bit to logic ``0`` when generating testbenches. + For example + + .. code-block:: xml + + + + ... + + + +.. _file_formats_fabric_bitstream_xml: + +XML (.xml) +~~~~~~~~~~ + +This file format is designed to generate testbenches using external tools, e.g., CocoTB. + +In principle, the file consist a number of XML node ````, each bit contains the following attributes: + +- ``id``: The unique id of the configuration bit in the fabric bitstream. + +- ``value``: The configuration bit value. + +- ``path`` represents the location of this block in FPGA fabric, i.e., the full path in the hierarchy of FPGA fabric. + +A quick example: + +.. code-block:: xml + + + + +Other information may depend on the type of configuration procotol. + +.. option:: memory_bank + + - ``bl``: Bit line address information + + - ``wl``: Word line address information + + A quick example: + + .. code-block:: xml + + + + + + +.. option:: frame_based + + - ``frame``: frame address information + + .. note:: Frame address may include don't care bit which is denoted as ``x``. + + A quick example: + + .. code-block:: xml + + + + diff --git a/docs/source/manual/file_formats/fabric_key.rst b/docs/source/manual/file_formats/fabric_key.rst new file mode 100644 index 000000000..f87cf1b2e --- /dev/null +++ b/docs/source/manual/file_formats/fabric_key.rst @@ -0,0 +1,151 @@ +.. _file_formats_fabric_key: + +Fabric Key (.xml) +~~~~~~~~~~~~~~~~~ + +A fabric key follows an XML format. As shown in the following XML code, the key file includes the organization of configurable blocks in the top-level FPGA fabric. + +Configurable Region +^^^^^^^^^^^^^^^^^^^ + +The top-level FPGA fabric can consist of several configurable regions, where a region may contain one or multiple configurable blocks. Each configurable region can be configured independently and in parrallel. + +.. option:: + + - ``id`` indicates the unique id of a configurable region in the fabric. + + .. warning:: The id must start from zero! + + .. note:: The number of regions defined in the fabric key must be consistent with the number of regions defined in the configuration protocol of architecture description. (See details in :ref:`config_protocol`). + +The following example shows how to define multiple configuration regions in the fabric key. + +.. code-block:: xml + + + + + + + + + + + + + + + + + + + + + + + + + + +Configurable Block +^^^^^^^^^^^^^^^^^^^ + +Each configurable block is defined as a key. There are two ways to define a key, either with alias or with name and value. + +.. option:: + + - ``id`` indicates the sequence of the configurable memory block in the top-level FPGA fabric. + + - ``name`` indicates the module name of the configurable memory block. This property becomes optional when ``alias`` is defined. + + - ``value`` indicates the instance id of the configurable memory block in the top-level FPGA fabric. This property becomes optional when ``alias`` is defined. + + - ``alias`` indicates the instance name of the configurable memory block in the top-level FPGA fabric. If a valid alias is specified, the ``name`` and ``value`` are not required. + +.. warning:: For fast loading of fabric key, strongly recommend to use pairs ``name`` and ``alias`` or ``name`` and ``value`` in the fabric key file. Using only ``alias`` may cause long parsing time for fabric key. + +The following is an example of a fabric key generate by OpenFPGA for a 2 :math:`\times` 2 FPGA. +This key contains only ``alias`` which is easy to craft. + +.. code-block:: xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +The following shows another example of a fabric key generate by OpenFPGA for a 2 :math:`\times` 2 FPGA. +This key contains only ``name`` and ``value`` which is fast to parse. + +.. code-block:: xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/source/manual/file_formats/index.rst b/docs/source/manual/file_formats/index.rst index b8aea88ed..698bf2253 100644 --- a/docs/source/manual/file_formats/index.rst +++ b/docs/source/manual/file_formats/index.rst @@ -12,3 +12,10 @@ OpenFPGA widely uses XML format for interchangable files pin_constraints_file + repack_design_constraints + + architecture_bitstream + + fabric_bitstream + + fabric_key diff --git a/docs/source/manual/file_formats/pin_constraints_file.rst b/docs/source/manual/file_formats/pin_constraints_file.rst index d810f5ffe..c2a71c596 100644 --- a/docs/source/manual/file_formats/pin_constraints_file.rst +++ b/docs/source/manual/file_formats/pin_constraints_file.rst @@ -1,7 +1,7 @@ .. _file_format_pin_constraints_file: -Pin Constraints File --------------------- +Pin Constraints File (.xml) +--------------------------- The *Pin Constraints File* (PCF) aims to create pin binding between an implementation and an FPGA fabric diff --git a/docs/source/manual/fpga_bitstream/repack_design_constraints.rst b/docs/source/manual/file_formats/repack_design_constraints.rst similarity index 91% rename from docs/source/manual/fpga_bitstream/repack_design_constraints.rst rename to docs/source/manual/file_formats/repack_design_constraints.rst index ea2079a12..5771123c2 100644 --- a/docs/source/manual/fpga_bitstream/repack_design_constraints.rst +++ b/docs/source/manual/file_formats/repack_design_constraints.rst @@ -1,7 +1,7 @@ -.. _fpga_bitstream_repack_design_constraints: +.. _file_formats_repack_design_constraints: -Repack Design Constraints -------------------------- +Repack Design Constraints (.xml) +-------------------------------- An example of design constraints is shown as follows. diff --git a/docs/source/manual/fpga_bitstream/fabric_dependent_bitstream.rst b/docs/source/manual/fpga_bitstream/fabric_dependent_bitstream.rst index 5bdb91145..767b384f3 100644 --- a/docs/source/manual/fpga_bitstream/fabric_dependent_bitstream.rst +++ b/docs/source/manual/fpga_bitstream/fabric_dependent_bitstream.rst @@ -13,98 +13,9 @@ The fabric bitsteam can be outputted in different file format in terms of usage. Plain Text File Format ``````````````````````` -This file format is designed to be directly loaded to an FPGA fabric. -It does not include any comments but only bitstream. - -The information depends on the type of configuration procotol. - -.. option:: vanilla - - A line consisting of ``0`` | ``1`` - -.. option:: scan_chain - - A line consisting of ``0`` | ``1`` - -.. option:: memory_bank - - Multiple lines will be included, each of which is organized as
. - Note that due to the use of Bit-Line and Word-Line decoders, every two lines are paired. - The first line represents the Bit-Line address and configuration bit. - The second line represents the Word-Line address and configuration bit. - For example - - .. code-block:: xml - - - - - - ... - - - -.. option:: frame_based - - Multiple lines will be included, each of which is organized as
. - Note that the address may include don't care bit which is denoted as ``x``. - OpenFPGA automatically convert don't care bit to logic ``0`` when generating testbenches. - For example - - .. code-block:: xml - - - - ... - +See details in :ref:`file_formats_fabric_bitstream_plain_text` XML File Format ``````````````` -This file format is designed to generate testbenches using external tools, e.g., CocoTB. - -In principle, the file consist a number of XML node ````, each bit contains the following attributes: - -- ``id``: The unique id of the configuration bit in the fabric bitstream. - -- ``value``: The configuration bit value. - -- ``path`` represents the location of this block in FPGA fabric, i.e., the full path in the hierarchy of FPGA fabric. - -A quick example: - -.. code-block:: xml - - - - -Other information may depend on the type of configuration procotol. - -.. option:: memory_bank - - - ``bl``: Bit line address information - - - ``wl``: Word line address information - - A quick example: - - .. code-block:: xml - - - - - - -.. option:: frame_based - - - ``frame``: frame address information - - .. note:: Frame address may include don't care bit which is denoted as ``x``. - - A quick example: - - .. code-block:: xml - - - - +See details in :ref:`file_formats_fabric_bitstream_xml` diff --git a/docs/source/manual/fpga_bitstream/generic_bitstream.rst b/docs/source/manual/fpga_bitstream/generic_bitstream.rst index a434096bc..59bd1c123 100644 --- a/docs/source/manual/fpga_bitstream/generic_bitstream.rst +++ b/docs/source/manual/fpga_bitstream/generic_bitstream.rst @@ -18,97 +18,4 @@ This can be regarded as a raw bitstream used for File Format ``````````` -OpenFPGA can output the generic bitstream to an XML format, which is easy to debug. As shown in the following XML code, configuration bits are organized block by block, where each block could be a LUT, a routing multiplexer `etc`. Each ``bitstream_block`` includes the following information: - - ``name`` represents the instance name which you can find in the fabric netlists - - - ``hierarchy_level`` represents the depth of this block in the hierarchy of the FPGA fabric. It always starts from 0 as the root. - - - ``hierarchy`` represents the location of this block in FPGA fabric. - The hierachy includes the full hierarchy of this block - - - ``instance`` denotes the instance name which you can find in the fabric netlists - - - ``level`` denotes the depth of the block in the hierarchy - - - ``input_nets`` represents the path ids and net names that are mapped to the inputs of block. Unused inputs will be tagged as ``unmapped`` which is a reserved word of OpenFPGA. Path id corresponds the selected ``path_id`` in the ```` node. - - - ``output_nets`` represents the path ids and net names that are mapped to the outputs of block. Unused outputs will be tagged as ``unmapped`` which is a reserved word OpenFPGA. - - - ``bitstream`` represents the configuration bits affiliated to this block. - - - ``path_id`` denotes the index of inputs which is propagated to the output. Note that smallest valid index starts from zero. Only routing multiplexers have the path index. Unused routing multiplexer will not have a ``path_id`` of ``-1``, which allows bitstream assembler to freely find the best path in terms of Quality of Results (QoR). A used routing multiplexer should have a zero or positive ``path_id``. - - - ``bit`` denotes a single configuration bit under this block. It contains \ - - - ``memory_port`` the memory port name which you can find in the fabric netlists by following the hierarchy. - - - ``value`` a binary value which is the configuration bit assigned to the memory port. - -.. code-block:: xml - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +See details in :ref:`file_formats_architecture_bitstream` diff --git a/docs/source/manual/fpga_bitstream/index.rst b/docs/source/manual/fpga_bitstream/index.rst index 0c12ec85e..e30f89354 100644 --- a/docs/source/manual/fpga_bitstream/index.rst +++ b/docs/source/manual/fpga_bitstream/index.rst @@ -12,5 +12,3 @@ FPGA-Bitstream can generate two types of bitstreams: generic_bitstream fabric_dependent_bitstream - - repack_design_constraints diff --git a/docs/source/manual/openfpga_shell/openfpga_commands/fpga_bitstream_commands.rst b/docs/source/manual/openfpga_shell/openfpga_commands/fpga_bitstream_commands.rst index ddd1841bc..05b89a112 100644 --- a/docs/source/manual/openfpga_shell/openfpga_commands/fpga_bitstream_commands.rst +++ b/docs/source/manual/openfpga_shell/openfpga_commands/fpga_bitstream_commands.rst @@ -21,7 +21,7 @@ Repack's functionality are in the following aspects: Apply design constraints from an external file. Normally, repack takes the net mapping from VPR packing and routing results. Alternatively, repack can accept the design constraints, in particular, net remapping, from an XML-based design constraint description. - See details in :ref:`fpga_bitstream_repack_design_constraints`. + See details in :ref:`file_formats_repack_design_constraints`. .. warning:: Design constraints are designed to help repacker to identify which clock net to be mapped to which pin, so that multi-clock benchmarks can be correctly implemented, in the case that VPR may not have sufficient vision on clock net mapping. **Try not to use design constraints to remap any other types of nets!!!** From 977ff52cb1ada7d1dd73bf5ab34042cccc991535 Mon Sep 17 00:00:00 2001 From: tangxifan Date: Tue, 19 Jan 2021 20:26:38 -0700 Subject: [PATCH 2/3] [Doc] Format openfpga command documentation by using option views --- .../fpga_bitstream_commands.rst | 55 +++--- .../openfpga_commands/fpga_sdc_commands.rst | 158 ++++++++++++------ .../fpga_verilog_commands.rst | 69 ++++++-- .../openfpga_commands/setup_commands.rst | 109 +++++++++--- 4 files changed, 273 insertions(+), 118 deletions(-) diff --git a/docs/source/manual/openfpga_shell/openfpga_commands/fpga_bitstream_commands.rst b/docs/source/manual/openfpga_shell/openfpga_commands/fpga_bitstream_commands.rst index 05b89a112..d2461b5ef 100644 --- a/docs/source/manual/openfpga_shell/openfpga_commands/fpga_bitstream_commands.rst +++ b/docs/source/manual/openfpga_shell/openfpga_commands/fpga_bitstream_commands.rst @@ -14,46 +14,61 @@ Repack's functionality are in the following aspects: - It re-routes all the nets by considering the programmable interconnects in physical modes **only**. -.. note:: This must be done before bitstream generator and testbench generation. Strongly recommend it is done after all the fix-up have been applied + .. note:: This must be done before bitstream generator and testbench generation. Strongly recommend it is done after all the fix-up have been applied -.. option:: --design_constraints - - Apply design constraints from an external file. - Normally, repack takes the net mapping from VPR packing and routing results. - Alternatively, repack can accept the design constraints, in particular, net remapping, from an XML-based design constraint description. - See details in :ref:`file_formats_repack_design_constraints`. - -.. warning:: Design constraints are designed to help repacker to identify which clock net to be mapped to which pin, so that multi-clock benchmarks can be correctly implemented, in the case that VPR may not have sufficient vision on clock net mapping. **Try not to use design constraints to remap any other types of nets!!!** - -.. option:: --verbose - - Show verbose log + .. option:: --design_constraints + + Apply design constraints from an external file. + Normally, repack takes the net mapping from VPR packing and routing results. + Alternatively, repack can accept the design constraints, in particular, net remapping, from an XML-based design constraint description. + See details in :ref:`file_formats_repack_design_constraints`. + + .. warning:: Design constraints are designed to help repacker to identify which clock net to be mapped to which pin, so that multi-clock benchmarks can be correctly implemented, in the case that VPR may not have sufficient vision on clock net mapping. **Try not to use design constraints to remap any other types of nets!!!** + + .. option:: --verbose + + Show verbose log build_architecture_bitstream ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Decode VPR implementing results to an fabric-independent bitstream database - - ``--read_file`` Read the fabric-independent bitstream from an XML file. When this is enabled, bitstream generation will NOT consider VPR results. + .. option:: --read_file - - ``--write_file`` Output the fabric-independent bitstream to an XML file + Read the fabric-independent bitstream from an XML file. When this is enabled, bitstream generation will NOT consider VPR results. See details at :ref:`file_formats_architecture_bitstream`. + + .. option:: --write_file + + Output the fabric-independent bitstream to an XML file. See details at :ref:`file_formats_architecture_bitstream`. - - ``--verbose`` Show verbose log + .. option:: --verbose + + Show verbose log build_fabric_bitstream ~~~~~~~~~~~~~~~~~~~~~~ Build a sequence for every configuration bits in the bitstream database for a specific FPGA fabric - - ``--verbose`` Show verbose log + .. option:: --verbose + + Show verbose log write_fabric_bitstream ~~~~~~~~~~~~~~~~~~~~~~ Output the fabric bitstream database to a specific file format - - ``--file`` or ``-f`` Output the fabric bitstream to an plain text file (only 0 or 1) + .. option:: --file or -f - - ``--format`` Specify the file format [``plain_text`` | ``xml``]. By default is ``plain_text``. + Output the fabric bitstream to an plain text file (only ``0`` or ``1``) - - ``--verbose`` Show verbose log + .. option:: --format + + Specify the file format [``plain_text`` | ``xml``]. By default is ``plain_text``. + See file formats in :ref:`file_formats_fabric_bitstream_xml` and :ref:`file_formats_fabric_bitstream_plain_text`. + + .. option:: --verbose + + Show verbose log diff --git a/docs/source/manual/openfpga_shell/openfpga_commands/fpga_sdc_commands.rst b/docs/source/manual/openfpga_shell/openfpga_commands/fpga_sdc_commands.rst index f5f0b83af..732353c2a 100644 --- a/docs/source/manual/openfpga_shell/openfpga_commands/fpga_sdc_commands.rst +++ b/docs/source/manual/openfpga_shell/openfpga_commands/fpga_sdc_commands.rst @@ -8,77 +8,127 @@ write_pnr_sdc Write the SDC files for PnR backend - - ``--file`` or ``-f`` Specify the output directory for SDC files - - - ``--hierarchical`` Output SDC files without full path in hierarchy - - - ``--flatten_names`` Use flatten names (no wildcards) in SDC files - - - ``--time_unit`` Specify a time unit to be used in SDC files. Acceptable values are string: ``as`` | ``fs`` | ``ps`` | ``ns`` | ``us`` | ``ms`` | ``ks`` | ``Ms``. By default, we will consider second (``s``). - - - ``--output_hierarchy`` Output hierarchy of Multiple-Instance-Blocks(MIBs) to plain text file. This is applied to constrain timing for grids, Switch Blocks and Connection Blocks. - - .. note:: Valid only when ``compress_routing`` is enabled in ``build_fabric`` - - - ``--constrain_global_port`` Constrain all the global ports of FPGA fabric. - - - ``--constrain_non_clock_global_port`` Constrain all the non-clock global ports as clocks ports of FPGA fabric - - .. note:: ``constrain_global_port`` will treat these global ports in Clock Tree Synthesis (CTS), in purpose of balancing the delay to each sink. Be carefull to enable ``constrain_non_clock_global_port``, this may significanly increase the runtime of CTS as it is supposed to be routed before any other nets. This may cause routing congestion as well. - - - ``--constrain_grid`` Constrain all the grids of FPGA fabric - - - ``--constrain_sb`` Constrain all the switch blocks of FPGA fabric - - - ``--constrain_cb`` Constrain all the connection blocks of FPGA fabric - - - ``--constrain_configurable_memory_outputs`` Constrain all the outputs of configurable memories of FPGA fabric - - - ``--constrain_routing_multiplexer_outputs`` Constrain all the outputs of routing multiplexer of FPGA fabric - - - ``--constrain_switch_block_outputs`` Constrain all the outputs of switch blocks of FPGA fabric - - - ``--constrain_zero_delay_paths`` Constrain all the zero-delay paths in FPGA fabric - - .. note:: Zero-delay path may cause errors in some PnR tools as it is considered illegal + .. option:: --file or -f + + Specify the output directory for SDC files + For example, ``--file /temp/pnr_sdc`` + + .. option:: --hierarchical + + Output SDC files without full path in hierarchy + + .. option:: --flatten_names + + Use flatten names (no wildcards) in SDC files + + .. option:: --time_unit + + Specify a time unit to be used in SDC files. Acceptable values are string: ``as`` | ``fs`` | ``ps`` | ``ns`` | ``us`` | ``ms`` | ``ks`` | ``Ms``. By default, we will consider second (``s``). + + + .. option:: --output_hierarchy + + Output hierarchy of Multiple-Instance-Blocks(MIBs) to plain text file. This is applied to constrain timing for grids, Switch Blocks and Connection Blocks. + + .. note:: Valid only when ``compress_routing`` is enabled in ``build_fabric`` + + .. option:: --constrain_global_port + + Constrain all the global ports of FPGA fabric. + + .. option:: --constrain_non_clock_global_port + + Constrain all the non-clock global ports as clocks ports of FPGA fabric + + .. note:: ``constrain_global_port`` will treat these global ports in Clock Tree Synthesis (CTS), in purpose of balancing the delay to each sink. Be carefull to enable ``constrain_non_clock_global_port``, this may significanly increase the runtime of CTS as it is supposed to be routed before any other nets. This may cause routing congestion as well. + + .. option:: --constrain_grid + + Constrain all the grids of FPGA fabric + + .. option:: --constrain_sb + + Constrain all the switch blocks of FPGA fabric + + .. option:: --constrain_cb + + Constrain all the connection blocks of FPGA fabric + + .. option:: --constrain_configurable_memory_outputs + + Constrain all the outputs of configurable memories of FPGA fabric + + .. option:: --constrain_routing_multiplexer_outputs + + Constrain all the outputs of routing multiplexer of FPGA fabric + + .. option:: --constrain_switch_block_outputs + + Constrain all the outputs of switch blocks of FPGA fabric + + .. option:: --constrain_zero_delay_paths + + Constrain all the zero-delay paths in FPGA fabric + + .. note:: Zero-delay path may cause errors in some PnR tools as it is considered illegal + + .. option:: --verbose + + Enable verbose output - - ``--verbose`` Enable verbose output - write_configuration_chain_sdc ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Write the SDC file to constrain the timing for configuration chain. The timing constraints will always start from the first output (Q) of a Configuration Chain Flip-flop (CCFF) and ends at the inputs of the next CCFF in the chain. Note that Qb of CCFF will not be constrained! - - ``--file`` or ``-f`` Specify the output SDC file - - - ``--time_unit`` Specify a time unit to be used in SDC files. Acceptable values are string: ``as`` | ``fs`` | ``ps`` | ``ns`` | ``us`` | ``ms`` | ``ks`` | ``Ms``. By default, we will consider second (``s``). - + .. option:: --file or -f - - ``--max_delay`` Specify the maximum delay to be used. The timing value should follow the time unit defined in this command. - - - ``--min_delay`` Specify the minimum delay to be used. The timing value should follow the time unit defined in this command. - - .. note:: - Only applicable when configuration chain is used as configuration protocol + Specify the output SDC file. For example, ``--file cc_chain.sdc`` + + .. option:: --time_unit + + Specify a time unit to be used in SDC files. Acceptable values are string: ``as`` | ``fs`` | ``ps`` | ``ns`` | ``us`` | ``ms`` | ``ks`` | ``Ms``. By default, we will consider second (``s``). + + .. option:: --max_delay + + Specify the maximum delay to be used. The timing value should follow the time unit defined in this command. + + .. option:: --min_delay + + Specify the minimum delay to be used. The timing value should follow the time unit defined in this command. + + .. note:: Only applicable when configuration chain is used as configuration protocol write_sdc_disable_timing_configure_ports ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Write the SDC file to disable timing for configure ports of programmable modules. The SDC aims to break the combinational loops across FPGAs and avoid false path timing to be visible to timing analyzers - - ``--file`` or ``-f`` Specify the output SDC file - - - ``--flatten_names`` Use flatten names (no wildcards) in SDC files - - - ``--verbose`` Show verbose log + .. option:: --file or -f + + Specify the output SDC file. For example, ``--file disable_config_timing.sdc``. + + .. option:: --flatten_names + + Use flatten names (no wildcards) in SDC files + + .. option:: --verbose + + Show verbose log write_analysis_sdc ~~~~~~~~~~~~~~~~~~ Write the SDC to run timing analysis for a mapped FPGA fabric - - ``--file`` or ``-f`` Specify the output directory for SDC files - - - ``--flatten_names`` Use flatten names (no wildcards) in SDC files + .. option:: --file or -f - - ``--time_unit`` Specify a time unit to be used in SDC files. Acceptable values are string: ``as`` | ``fs`` | ``ps`` | ``ns`` | ``us`` | ``ms`` | ``ks`` | ``Ms``. By default, we will consider second (``s``). + Specify the output directory for SDC files. For example, ``--file counter_sta_analysis.sdc`` + + .. option:: --flatten_names + + Use flatten names (no wildcards) in SDC files + + .. option:: --time_unit + + Specify a time unit to be used in SDC files. Acceptable values are string: ``as`` | ``fs`` | ``ps`` | ``ns`` | ``us`` | ``ms`` | ``ks`` | ``Ms``. By default, we will consider second (``s``). diff --git a/docs/source/manual/openfpga_shell/openfpga_commands/fpga_verilog_commands.rst b/docs/source/manual/openfpga_shell/openfpga_commands/fpga_verilog_commands.rst index 0c5137b91..162a4e0a0 100644 --- a/docs/source/manual/openfpga_shell/openfpga_commands/fpga_verilog_commands.rst +++ b/docs/source/manual/openfpga_shell/openfpga_commands/fpga_verilog_commands.rst @@ -8,43 +8,78 @@ write_fabric_verilog Write the Verilog netlist for FPGA fabric based on module graph - - ``--file`` or ``-f`` Specify the output directory for the Verilog netlists + .. option:: --file or -f - - ``--explicit_port_mapping`` Use explicit port mapping when writing the Verilog netlists + Specify the output directory for the Verilog netlists. For example, ``--file /temp/fabric_netlist/`` - - ``--include_timing`` Output timing information to Verilog netlists for primitive modules + .. option:: --explicit_port_mapping + + Use explicit port mapping when writing the Verilog netlists + + .. option:: --include_timing + + Output timing information to Verilog netlists for primitive modules - - ``--include_signal_init`` Output signal initialization to Verilog netlists for primitive modules + .. option:: --include_signal_init - - ``--support_icarus_simulator`` Output Verilog netlists with syntax that iVerilog simulatorcan accept + Output signal initialization to Verilog netlists for primitive modules - - ``--print_user_defined_template`` Output a template Verilog netlist for all the user-defined ``circuit models`` in :ref:`circuit_library`. This aims to help engineers to check what is the port sequence required by top-level Verilog netlists + .. option:: --support_icarus_simulator + + Output Verilog netlists with syntax that iVerilog simulatorcan accept - - ``--verbose`` Show verbose log + .. option:: --print_user_defined_template + + Output a template Verilog netlist for all the user-defined ``circuit models`` in :ref:`circuit_library`. This aims to help engineers to check what is the port sequence required by top-level Verilog netlists + + .. option:: --verbose + + Show verbose log write_verilog_testbench ~~~~~~~~~~~~~~~~~~~~~~~ Write the Verilog testbench for FPGA fabric - - ``--file`` or ``-f`` The output directory for all the testbench netlists. We suggest the use of same output directory as fabric Verilog netlists + .. option:: --file or -f + + The output directory for all the testbench netlists. We suggest the use of same output directory as fabric Verilog netlists. For example, ``--file /temp/testbench`` - - ``--fabric_netlist_file_path`` Specify the fabric Verilog file if they are not in the same directory as the testbenches to be generated. If not specified, OpenFPGA will assume that the fabric netlists are the in the same directory as testbenches and assign default names. + .. option:: --fabric_netlist_file_path - - ``--reference_benchmark_file_path`` Must specify the reference benchmark Verilog file if you want to output any testbenches + Specify the fabric Verilog file if they are not in the same directory as the testbenches to be generated. If not specified, OpenFPGA will assume that the fabric netlists are the in the same directory as testbenches and assign default names. For example, ``--file /temp/fabric/fabric_netlists.v`` - - ``--pin_constraints_file`` specify the *Pin Constraints File* (PCF) if you want to custom stimulus in testbenches. Strongly recommend for multi-clock simulations. See detailed file format about :ref:`file_format_pin_constraints_file`. + .. option:: --reference_benchmark_file_path - - ``--fast_configuration`` Enable fast configuration phase for the top-level testbench in order to reduce runtime of simulations. It is applicable to configuration chain, memory bank and frame-based configuration protocols. For configuration chain, when enabled, the zeros at the head of the bitstream will be skipped. For memory bank and frame-based, when enabled, all the zero configuration bits will be skipped. So ensure that your memory cells can be correctly reset to zero with a reset signal. + Must specify the reference benchmark Verilog file if you want to output any testbenches. For example, ``--reference_benchmark_file_path /temp/benchmark/counter_post_synthesis.v`` + + .. option:: --pin_constraints_file + + Specify the *Pin Constraints File* (PCF) if you want to custom stimulus in testbenches. For example, ``pin_constraints_file pin_constraints.xml`` + Strongly recommend for multi-clock simulations. See detailed file format about :ref:`file_format_pin_constraints_file`. + + .. option:: --fast_configuration + + Enable fast configuration phase for the top-level testbench in order to reduce runtime of simulations. It is applicable to configuration chain, memory bank and frame-based configuration protocols. For configuration chain, when enabled, the zeros at the head of the bitstream will be skipped. For memory bank and frame-based, when enabled, all the zero configuration bits will be skipped. So ensure that your memory cells can be correctly reset to zero with a reset signal. .. note:: If both reset and set ports are defined in the circuit modeling for programming, OpenFPGA will pick the one that will bring largest benefit in speeding up configuration. - - ``--print_top_testbench`` Enable top-level testbench which is a full verification including programming circuit and core logic of FPGA + .. option:: --print_top_testbench - - ``--print_formal_verification_top_netlist`` Generate a top-level module which can be used in formal verification + Enable top-level testbench which is a full verification including programming circuit and core logic of FPGA - - ``--print_preconfig_top_testbench`` Enable pre-configured top-level testbench which is a fast verification skipping programming phase + .. option:: --print_formal_verification_top_netlist - - ``--print_simulation_ini`` Output an exchangeable simulation ini file, which is needed only when you need to interface different HDL simulators using openfpga flow-run scripts + Generate a top-level module which can be used in formal verification - - ``--explicit_port_mapping`` Use explicit port mapping when writing the Verilog netlists + .. option:: --print_preconfig_top_testbench + + Enable pre-configured top-level testbench which is a fast verification skipping programming phase + + .. option:: --print_simulation_ini + + Output an exchangeable simulation ini file, which is needed only when you need to interface different HDL simulators using openfpga flow-run scripts. For example, ``--print_simulation_ini /temp/testbench/sim.ini`` + + .. option:: --explicit_port_mapping + + Use explicit port mapping when writing the Verilog netlists diff --git a/docs/source/manual/openfpga_shell/openfpga_commands/setup_commands.rst b/docs/source/manual/openfpga_shell/openfpga_commands/setup_commands.rst index 2d628117a..dd4798753 100644 --- a/docs/source/manual/openfpga_shell/openfpga_commands/setup_commands.rst +++ b/docs/source/manual/openfpga_shell/openfpga_commands/setup_commands.rst @@ -8,56 +8,83 @@ read_openfpga_arch Read the XML file about architecture description (see details in :ref:`arch_generality`) - - ``--file`` or ``-f`` Specify the file name + .. option:: --file or -f + + Specify the file name. For example, ``--file openfpga_arch.xml`` - - ``--verbose`` Show verbose log + .. option:: --verbose + + Show verbose log write_openfpga_arch ~~~~~~~~~~~~~~~~~~~ Write the OpenFPGA XML architecture file to a file - - ``--file`` or ``-f`` Specify the file name + .. option:: --file or -f + + Specify the file name. For example, ``--file arch_echo.xml`` - - ``--verbose`` Show verbose log + .. option:: --verbose + + Show verbose log read_openfpga_simulation_setting ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Read the XML file about simulation settings (see details in :ref:`simulation_setting`) - - ``--file`` or ``-f`` Specify the file name + .. option:: --file or -f + + Specify the file name. For example, ``--file auto_simulation_setting.xml`` - - ``--verbose`` Show verbose log + .. option:: --verbose + + Show verbose log write_openfpga_simulation_setting ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Write the OpenFPGA XML simulation settings to a file - - ``--file`` or ``-f`` Specify the file name + .. option:: --file or -f + + Specify the file name. For example, ``--file auto_simulation_setting_echo.xml`` - - ``--verbose`` Show verbose log + .. option:: --verbose + + Show verbose log link_openfpga_arch ~~~~~~~~~~~~~~~~~~ Annotate the OpenFPGA architecture to VPR data base - - ``--activity_file`` Specify the signal activity file + .. option:: --activity_file - - ``--sort_gsb_chan_node_in_edges`` Sort the edges for the routing tracks in General Switch Blocks (GSBs). Strongly recommand to turn this on for uniquifying the routing modules + Specify the signal activity file. For example, ``--activity_file counter.act`` - - ``--verbose`` Show verbose log + .. option:: --sort_gsb_chan_node_in_edges + + Sort the edges for the routing tracks in General Switch Blocks (GSBs). Strongly recommand to turn this on for uniquifying the routing modules + + .. option:: --verbose + + Show verbose log write_gsb_to_xml ~~~~~~~~~~~~~~~~ Write the internal structure of General Switch Blocks (GSBs) across a FPGA fabric, including the interconnection between the nodes and node-level details, to XML files - - ``--file`` or ``-f`` Specify the output directory of the XML files. Each GSB will be written to an indepedent XML file + .. option:: --file or -f - - ``--verbose`` Show verbose log + Specify the output directory of the XML files. Each GSB will be written to an indepedent XML file + For example, ``--file /temp/gsb_output`` + + .. option:: --verbose + + Show verbose log .. note:: This command is used to help users to study the difference between GSBs @@ -69,9 +96,13 @@ check_netlist_naming_conflict .. warning:: This command may be deprecated in future when it is merged to VPR upstream - - ``--fix`` Apply fix-up to the names that violate the syntax + .. option:: --fix - - ``--report <.xml>`` Report the naming fix-up to a log file + Apply fix-up to the names that violate the syntax + + .. option:: --report + + Report the naming fix-up to an XML-based log file. For example, ``--report rename.xml`` pb_pin_fixup ~~~~~~~~~~~~ @@ -81,7 +112,9 @@ pb_pin_fixup .. warning:: This command may be deprecated in future when it is merged to VPR upstream - - ``--verbose`` Show verbose log + .. option:: --verbose + + Show verbose log lut_truth_table_fixup ~~~~~~~~~~~~~~~~~~~~~ @@ -90,7 +123,9 @@ lut_truth_table_fixup .. warning:: This command may be deprecated in future when it is merged to VPR upstream - - ``--verbose`` Show verbose log + .. option:: --verbose + + Show verbose log .. _cmd_build_fabric: @@ -99,21 +134,35 @@ build_fabric Build the module graph. - - ``--compress_routing`` Enable compression on routing architecture modules. Strongly recommend this as it will minimize the number of routing modules to be outputted. It can reduce the netlist size significantly. + .. option:: --compress_routing + + Enable compression on routing architecture modules. Strongly recommend this as it will minimize the number of routing modules to be outputted. It can reduce the netlist size significantly. - - ``--duplicate_grid_pin`` Enable pin duplication on grid modules. This is optional unless ultra-dense layout generation is needed + .. option:: --duplicate_grid_pin - - ``--load_fabric_key `` Load an external fabric key from an XML file. + Enable pin duplication on grid modules. This is optional unless ultra-dense layout generation is needed - - ``--generate_fabric_key`` Generate a fabric key in a random way + .. option:: --load_fabric_key - - ``--write_fabric_key `` Output current fabric key to an XML file + Load an external fabric key from an XML file. For example, ``--load_fabric_key fpga_2x2.xml`` See details in :ref:`file_formats_fabric_key`. - - ``--frame_view`` Create only frame views of the module graph. When enabled, top-level module will not include any nets. This option is made for save runtime and memory. + .. option:: --generate_fabric_key + + Generate a fabric key in a random way + + .. option:: --write_fabric_key . + + Output current fabric key to an XML file. For example, ``--load_fabric_key fpga_2x2.xml`` See details in :ref:`file_formats_fabric_key`. + + .. option:: --frame_view + + Create only frame views of the module graph. When enabled, top-level module will not include any nets. This option is made for save runtime and memory. .. warning:: Recommend to turn the option on when bitstream generation is the only purpose of the flow. Do not use it when you need generate netlists! - - ``--verbose`` Show verbose log + .. option:: --verbose + + Show verbose log .. note:: This is a must-run command before launching FPGA-Verilog, FPGA-Bitstream, FPGA-SDC and FPGA-SPICE @@ -122,10 +171,16 @@ write_fabric_hierarchy Write the hierarchy of FPGA fabric graph to a plain-text file - - ``--file`` or ``-f`` Specify the file name to write the hierarchy. + .. option:: --file or -f + + Specify the file name to write the hierarchy. - - ``--depth`` Specify at which depth of the fabric module graph should the writer stop outputting. The root module start from depth 0. For example, if you want a two-level hierarchy, you should specify depth as 1. + .. option:: --depth - - ``--verbose`` Show verbose log + Specify at which depth of the fabric module graph should the writer stop outputting. The root module start from depth 0. For example, if you want a two-level hierarchy, you should specify depth as 1. + + .. option:: --verbose + + Show verbose log .. note:: This file is designed for hierarchical PnR flow, which requires the tree of Multiple-Instanced-Blocks (MIBs). From 815468ac6544553d5ba5a559facc3066f3babd81 Mon Sep 17 00:00:00 2001 From: tangxifan Date: Wed, 20 Jan 2021 09:20:51 -0700 Subject: [PATCH 3/3] [Doc] Add shortcut to call pin constraint option to documentation --- .../openfpga_commands/fpga_verilog_commands.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/source/manual/openfpga_shell/openfpga_commands/fpga_verilog_commands.rst b/docs/source/manual/openfpga_shell/openfpga_commands/fpga_verilog_commands.rst index 162a4e0a0..675d00d6c 100644 --- a/docs/source/manual/openfpga_shell/openfpga_commands/fpga_verilog_commands.rst +++ b/docs/source/manual/openfpga_shell/openfpga_commands/fpga_verilog_commands.rst @@ -53,9 +53,9 @@ write_verilog_testbench Must specify the reference benchmark Verilog file if you want to output any testbenches. For example, ``--reference_benchmark_file_path /temp/benchmark/counter_post_synthesis.v`` - .. option:: --pin_constraints_file + .. option:: --pin_constraints_file or -pcf - Specify the *Pin Constraints File* (PCF) if you want to custom stimulus in testbenches. For example, ``pin_constraints_file pin_constraints.xml`` + Specify the *Pin Constraints File* (PCF) if you want to custom stimulus in testbenches. For example, ``-pin_constraints_file pin_constraints.xml`` Strongly recommend for multi-clock simulations. See detailed file format about :ref:`file_format_pin_constraints_file`. .. option:: --fast_configuration