riscv
/
OpenFPGA
mirror of https://github.com/lnis-uofu/OpenFPGA.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

[Doc] Group file format documentation into a unified section

This commit is contained in:
tangxifan 2021-01-19 19:44:44 -07:00
parent 3f80a26172
commit e9dc708d66
11 changed files with 376 additions and 341 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

149
docs/source/manual/arch_lang/fabric_key.rst
View File

@ -27,151 +27,4 @@ A fabric key can be achieved in the following ways:
File Format 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. See details in :ref:`file_formats_fabric_key`
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:: <region id="<int>"/>
- ``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
<fabric_key>
<region id="0">
<key id="0" name="grid_io_bottom" value="0" alias="grid_io_bottom_1__0_"/>
<key id="1" name="grid_io_right" value="0" alias="grid_io_right_2__1_"/>
<key id="2" name="sb_1__1_" value="0" alias="sb_1__1_"/>
</region>
<region id="1">
<key id="3" name="cbx_1__1_" value="0" alias="cbx_1__1_"/>
<key id="4" name="grid_io_top" value="0" alias="grid_io_top_1__2_"/>
<key id="5" name="sb_0__1_" value="0" alias="sb_0__1_"/>
</region>
<region id="2">
<key id="6" name="sb_0__0_" value="0" alias="sb_0__0_"/>
<key id="7" name="cby_0__1_" value="0" alias="cby_0__1_"/>
<key id="8" name="grid_io_left" value="0" alias="grid_io_left_0__1_"/>
</region>
<region id="3">
<key id="9" name="sb_1__0_" value="0" alias="sb_1__0_"/>
<key id="10" name="cbx_1__0_" value="0" alias="cbx_1__0_"/>
<key id="11" name="cby_1__1_" value="0" alias="cby_1__1_"/>
<key id="12" name="grid_clb" value="0" alias="grid_clb_1__1_"/>
</region>
</fabric_key>
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:: <key id="<int>" alias="<string>" name="<string>" value="<int>"/>
- ``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
<fabric_key>
<region id="0">
<key id="0" alias="sb_2__2_"/>
<key id="1" alias="grid_clb_2_2"/>
<key id="2" alias="sb_0__1_"/>
<key id="3" alias="cby_0__1_"/>
<key id="4" alias="grid_clb_2_1"/>
<key id="5" alias="grid_io_left_0_1"/>
<key id="6" alias="sb_1__0_"/>
<key id="7" alias="sb_1__1_"/>
<key id="8" alias="cbx_2__1_"/>
<key id="9" alias="cby_1__2_"/>
<key id="10" alias="grid_io_right_3_2"/>
<key id="11" alias="cbx_2__0_"/>
<key id="12" alias="cby_1__1_"/>
<key id="13" alias="grid_io_right_3_1"/>
<key id="14" alias="grid_io_bottom_1_0"/>
<key id="15" alias="cby_2__1_"/>
<key id="16" alias="sb_2__1_"/>
<key id="17" alias="cbx_1__0_"/>
<key id="18" alias="grid_clb_1_2"/>
<key id="19" alias="cbx_1__2_"/>
<key id="20" alias="cbx_2__2_"/>
<key id="21" alias="sb_2__0_"/>
<key id="22" alias="sb_1__2_"/>
<key id="23" alias="cby_0__2_"/>
<key id="24" alias="sb_0__0_"/>
<key id="25" alias="grid_clb_1_1"/>
<key id="26" alias="cby_2__2_"/>
<key id="27" alias="grid_io_top_2_3"/>
<key id="28" alias="sb_0__2_"/>
<key id="29" alias="grid_io_bottom_2_0"/>
<key id="30" alias="cbx_1__1_"/>
<key id="31" alias="grid_io_top_1_3"/>
<key id="32" alias="grid_io_left_0_2"/>
</region>
</fabric_key>
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
<fabric_key>
<region id="0">
<key id="0" name="sb_2__2_" value="0"/>
<key id="1" name="grid_clb" value="3"/>
<key id="2" name="sb_0__1_" value="0"/>
<key id="3" name="cby_0__1_" value="0"/>
<key id="4" name="grid_clb" value="2"/>
<key id="5" name="grid_io_left" value="0"/>
<key id="6" name="sb_1__0_" value="0"/>
<key id="7" name="sb_1__1_" value="0"/>
<key id="8" name="cbx_1__1_" value="1"/>
<key id="9" name="cby_1__1_" value="1"/>
<key id="10" name="grid_io_right" value="1"/>
<key id="11" name="cbx_1__0_" value="1"/>
<key id="12" name="cby_1__1_" value="0"/>
<key id="13" name="grid_io_right" value="0"/>
<key id="14" name="grid_io_bottom" value="0"/>
<key id="15" name="cby_2__1_" value="0"/>
<key id="16" name="sb_2__1_" value="0"/>
<key id="17" name="cbx_1__0_" value="0"/>
<key id="18" name="grid_clb" value="1"/>
<key id="19" name="cbx_1__2_" value="0"/>
<key id="20" name="cbx_1__2_" value="1"/>
<key id="21" name="sb_2__0_" value="0"/>
<key id="22" name="sb_1__2_" value="0"/>
<key id="23" name="cby_0__1_" value="1"/>
<key id="24" name="sb_0__0_" value="0"/>
<key id="25" name="grid_clb" value="0"/>
<key id="26" name="cby_2__1_" value="1"/>
<key id="27" name="grid_io_top" value="1"/>
<key id="28" name="sb_0__2_" value="0"/>
<key id="29" name="grid_io_bottom" value="1"/>
<key id="30" name="cbx_1__1_" value="0"/>
<key id="31" name="grid_io_top" value="0"/>
<key id="32" name="grid_io_left" value="1"/>
</region>
</fabric_key>

100
docs/source/manual/file_formats/architecture_bitstream.rst Normal file
View File

@ -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 ``<bitstream>`` 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
<bitstream_block name="fpga_top" hierarchy_level="0">
<!-- Bitstream block of a 4-input Look-Up Table in a Configurable Logic Block (CLB) -->
<bitstream_block name="grid_clb_1_1" hierarchy_level="1">
<bitstream_block name="logical_tile_clb_mode_clb__0" hierarchy_level="2">
<bitstream_block name="logical_tile_clb_mode_default__fle_0" hierarchy_level="3">
<bitstream_block name="logical_tile_clb_mode_default__fle_mode_n1_lut4__ble4_0" hierarchy_level="4">
<bitstream_block name="logical_tile_clb_mode_default__fle_mode_n1_lut4__ble4_mode_default__lut4_0" hierarchy_level="5">
<bitstream_block name="lut4_config_latch_mem" hierarchy_level="6">
<hierarchy>
<instance level="0" name="fpga_top"/>
<instance level="1" name="grid_clb_1_1"/>
<instance level="2" name="logical_tile_clb_mode_clb__0"/>
<instance level="3" name="logical_tile_clb_mode_default__fle_0"/>
<instance level="4" name="logical_tile_clb_mode_default__fle_mode_n1_lut4__ble4_0"/>
<instance level="5" name="logical_tile_clb_mode_default__fle_mode_n1_lut4__ble4_mode_default__lut4_0"/>
<instance level="6" name="lut4_config_latch_mem"/>
</hierarchy>
<bitstream>
<bit memory_port="mem_out[0]" value="0"/>
<bit memory_port="mem_out[1]" value="0"/>
<bit memory_port="mem_out[2]" value="0"/>
<bit memory_port="mem_out[3]" value="0"/>
<bit memory_port="mem_out[4]" value="0"/>
<bit memory_port="mem_out[5]" value="0"/>
<bit memory_port="mem_out[6]" value="0"/>
<bit memory_port="mem_out[7]" value="0"/>
<bit memory_port="mem_out[8]" value="0"/>
<bit memory_port="mem_out[9]" value="0"/>
<bit memory_port="mem_out[10]" value="0"/>
<bit memory_port="mem_out[11]" value="0"/>
<bit memory_port="mem_out[12]" value="0"/>
<bit memory_port="mem_out[13]" value="0"/>
<bit memory_port="mem_out[14]" value="0"/>
<bit memory_port="mem_out[15]" value="0"/>
</bitstream>
</bitstream_block>
</bitstream_block>
</bitstream_block>
</bitstream_block>
</bitstream_block>
</bitstream_block>
<!-- More bitstream blocks -->
<!-- Bitstream block of a 2-input routing multiplexer in a Switch Block (SB) -->
<bitstream_block name="sb_0__2_" hierarchy_level="1">
<bitstream_block name="mem_right_track_0" hierarchy_level="2">
<hierarchy>
<instance level="0" name="fpga_top"/>
<instance level="1" name="sb_0__2_"/>
<instance level="2" name="mem_right_track_0"/>
</hierarchy>
<input_nets>
<path id="0" net_name="unmapped"/>
<path id="1" net_name="unmapped"/>
</input_nets>
<output_nets>
<path id="0" net_name="unmapped"/>
</output_nets>
<bitstream path_id="-1">
<bit memory_port="mem_out[0]" value="0"/>
<bit memory_port="mem_out[1]" value="0"/>
</bitstream>
</bitstream_block>
</bitstream_block>
</bitstream_block>

108
docs/source/manual/file_formats/fabric_bitstream.rst Normal file
View File

@ -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 <address><space><bit>.
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
<bitline_address> <bit_value>
<wordline_address> <bit_value>
<bitline_address> <bit_value>
<wordline_address> <bit_value>
...
<bitline_address> <bit_value>
<wordline_address> <bit_value>
.. option:: frame_based
Multiple lines will be included, each of which is organized as <address><space><bit>.
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
<frame_address> <bit_value>
<frame_address> <bit_value>
...
<frame_address> <bit_value>
.. _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 ``<bit>``, 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
<bit id="0" value="1" path="fpga_top.grid_clb_1__2_.logical_tile_clb_mode_clb__0.mem_fle_9_in_5.mem_out[0]"/>
</bit>
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
<bit id="0" value="1" path="fpga_top.grid_clb_1__2_.logical_tile_clb_mode_clb__0.mem_fle_9_in_5.mem_out[0]"/>
<bl address="000000"/>
<wl address="000000"/>
</bit>
.. 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
<bit id="0" value="1" path="fpga_top.grid_clb_1__2_.logical_tile_clb_mode_clb__0.mem_fle_9_in_5.mem_out[0]"/>
<frame address="0001000x00000x01"/>
</bit>

151
docs/source/manual/file_formats/fabric_key.rst Normal file
View File

@ -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:: <region id="<int>"/>
- ``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
<fabric_key>
<region id="0">
<key id="0" name="grid_io_bottom" value="0" alias="grid_io_bottom_1__0_"/>
<key id="1" name="grid_io_right" value="0" alias="grid_io_right_2__1_"/>
<key id="2" name="sb_1__1_" value="0" alias="sb_1__1_"/>
</region>
<region id="1">
<key id="3" name="cbx_1__1_" value="0" alias="cbx_1__1_"/>
<key id="4" name="grid_io_top" value="0" alias="grid_io_top_1__2_"/>
<key id="5" name="sb_0__1_" value="0" alias="sb_0__1_"/>
</region>
<region id="2">
<key id="6" name="sb_0__0_" value="0" alias="sb_0__0_"/>
<key id="7" name="cby_0__1_" value="0" alias="cby_0__1_"/>
<key id="8" name="grid_io_left" value="0" alias="grid_io_left_0__1_"/>
</region>
<region id="3">
<key id="9" name="sb_1__0_" value="0" alias="sb_1__0_"/>
<key id="10" name="cbx_1__0_" value="0" alias="cbx_1__0_"/>
<key id="11" name="cby_1__1_" value="0" alias="cby_1__1_"/>
<key id="12" name="grid_clb" value="0" alias="grid_clb_1__1_"/>
</region>
</fabric_key>
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:: <key id="<int>" alias="<string>" name="<string>" value="<int>"/>
- ``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
<fabric_key>
<region id="0">
<key id="0" alias="sb_2__2_"/>
<key id="1" alias="grid_clb_2_2"/>
<key id="2" alias="sb_0__1_"/>
<key id="3" alias="cby_0__1_"/>
<key id="4" alias="grid_clb_2_1"/>
<key id="5" alias="grid_io_left_0_1"/>
<key id="6" alias="sb_1__0_"/>
<key id="7" alias="sb_1__1_"/>
<key id="8" alias="cbx_2__1_"/>
<key id="9" alias="cby_1__2_"/>
<key id="10" alias="grid_io_right_3_2"/>
<key id="11" alias="cbx_2__0_"/>
<key id="12" alias="cby_1__1_"/>
<key id="13" alias="grid_io_right_3_1"/>
<key id="14" alias="grid_io_bottom_1_0"/>
<key id="15" alias="cby_2__1_"/>
<key id="16" alias="sb_2__1_"/>
<key id="17" alias="cbx_1__0_"/>
<key id="18" alias="grid_clb_1_2"/>
<key id="19" alias="cbx_1__2_"/>
<key id="20" alias="cbx_2__2_"/>
<key id="21" alias="sb_2__0_"/>
<key id="22" alias="sb_1__2_"/>
<key id="23" alias="cby_0__2_"/>
<key id="24" alias="sb_0__0_"/>
<key id="25" alias="grid_clb_1_1"/>
<key id="26" alias="cby_2__2_"/>
<key id="27" alias="grid_io_top_2_3"/>
<key id="28" alias="sb_0__2_"/>
<key id="29" alias="grid_io_bottom_2_0"/>
<key id="30" alias="cbx_1__1_"/>
<key id="31" alias="grid_io_top_1_3"/>
<key id="32" alias="grid_io_left_0_2"/>
</region>
</fabric_key>
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
<fabric_key>
<region id="0">
<key id="0" name="sb_2__2_" value="0"/>
<key id="1" name="grid_clb" value="3"/>
<key id="2" name="sb_0__1_" value="0"/>
<key id="3" name="cby_0__1_" value="0"/>
<key id="4" name="grid_clb" value="2"/>
<key id="5" name="grid_io_left" value="0"/>
<key id="6" name="sb_1__0_" value="0"/>
<key id="7" name="sb_1__1_" value="0"/>
<key id="8" name="cbx_1__1_" value="1"/>
<key id="9" name="cby_1__1_" value="1"/>
<key id="10" name="grid_io_right" value="1"/>
<key id="11" name="cbx_1__0_" value="1"/>
<key id="12" name="cby_1__1_" value="0"/>
<key id="13" name="grid_io_right" value="0"/>
<key id="14" name="grid_io_bottom" value="0"/>
<key id="15" name="cby_2__1_" value="0"/>
<key id="16" name="sb_2__1_" value="0"/>
<key id="17" name="cbx_1__0_" value="0"/>
<key id="18" name="grid_clb" value="1"/>
<key id="19" name="cbx_1__2_" value="0"/>
<key id="20" name="cbx_1__2_" value="1"/>
<key id="21" name="sb_2__0_" value="0"/>
<key id="22" name="sb_1__2_" value="0"/>
<key id="23" name="cby_0__1_" value="1"/>
<key id="24" name="sb_0__0_" value="0"/>
<key id="25" name="grid_clb" value="0"/>
<key id="26" name="cby_2__1_" value="1"/>
<key id="27" name="grid_io_top" value="1"/>
<key id="28" name="sb_0__2_" value="0"/>
<key id="29" name="grid_io_bottom" value="1"/>
<key id="30" name="cbx_1__1_" value="0"/>
<key id="31" name="grid_io_top" value="0"/>
<key id="32" name="grid_io_left" value="1"/>
</region>
</fabric_key>

7
docs/source/manual/file_formats/index.rst
View File

@ -12,3 +12,10 @@ OpenFPGA widely uses XML format for interchangable files
pin_constraints_file pin_constraints_file
repack_design_constraints
architecture_bitstream
fabric_bitstream
fabric_key

4
docs/source/manual/file_formats/pin_constraints_file.rst
View File

@ -1,7 +1,7 @@
.. _file_format_pin_constraints_file: .. _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 The *Pin Constraints File* (PCF) aims to create pin binding between an implementation and an FPGA fabric

6
docs/source/manual/fpga_bitstream/repack_design_constraints.rst → docs/source/manual/file_formats/repack_design_constraints.rst
View File

@ -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. An example of design constraints is shown as follows.

93
docs/source/manual/fpga_bitstream/fabric_dependent_bitstream.rst
View File

@ -13,98 +13,9 @@ The fabric bitsteam can be outputted in different file format in terms of usage.
Plain Text File Format Plain Text File Format
``````````````````````` ```````````````````````
This file format is designed to be directly loaded to an FPGA fabric. See details in :ref:`file_formats_fabric_bitstream_plain_text`
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 <address><space><bit>.
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
<bitline_address> <bit_value>
<wordline_address> <bit_value>
<bitline_address> <bit_value>
<wordline_address> <bit_value>
...
<bitline_address> <bit_value>
<wordline_address> <bit_value>
.. option:: frame_based
Multiple lines will be included, each of which is organized as <address><space><bit>.
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
<frame_address> <bit_value>
<frame_address> <bit_value>
...
<frame_address> <bit_value>
XML File Format XML File Format
``````````````` ```````````````
This file format is designed to generate testbenches using external tools, e.g., CocoTB. See details in :ref:`file_formats_fabric_bitstream_xml`
In principle, the file consist a number of XML node ``<bit>``, 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
<bit id="0" value="1" path="fpga_top.grid_clb_1__2_.logical_tile_clb_mode_clb__0.mem_fle_9_in_5.mem_out[0]"/>
</bit>
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
<bit id="0" value="1" path="fpga_top.grid_clb_1__2_.logical_tile_clb_mode_clb__0.mem_fle_9_in_5.mem_out[0]"/>
<bl address="000000"/>
<wl address="000000"/>
</bit>
.. 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
<bit id="0" value="1" path="fpga_top.grid_clb_1__2_.logical_tile_clb_mode_clb__0.mem_fle_9_in_5.mem_out[0]"/>
<frame address="0001000x00000x01"/>
</bit>

95
docs/source/manual/fpga_bitstream/generic_bitstream.rst
View File

@ -18,97 +18,4 @@ This can be regarded as a raw bitstream used for
File Format 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: See details in :ref:`file_formats_architecture_bitstream`
- ``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 ``<bitstream>`` 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
<bitstream_block name="fpga_top" hierarchy_level="0">
<!-- Bitstream block of a 4-input Look-Up Table in a Configurable Logic Block (CLB) -->
<bitstream_block name="grid_clb_1_1" hierarchy_level="1">
<bitstream_block name="logical_tile_clb_mode_clb__0" hierarchy_level="2">
<bitstream_block name="logical_tile_clb_mode_default__fle_0" hierarchy_level="3">
<bitstream_block name="logical_tile_clb_mode_default__fle_mode_n1_lut4__ble4_0" hierarchy_level="4">
<bitstream_block name="logical_tile_clb_mode_default__fle_mode_n1_lut4__ble4_mode_default__lut4_0" hierarchy_level="5">
<bitstream_block name="lut4_config_latch_mem" hierarchy_level="6">
<hierarchy>
<instance level="0" name="fpga_top"/>
<instance level="1" name="grid_clb_1_1"/>
<instance level="2" name="logical_tile_clb_mode_clb__0"/>
<instance level="3" name="logical_tile_clb_mode_default__fle_0"/>
<instance level="4" name="logical_tile_clb_mode_default__fle_mode_n1_lut4__ble4_0"/>
<instance level="5" name="logical_tile_clb_mode_default__fle_mode_n1_lut4__ble4_mode_default__lut4_0"/>
<instance level="6" name="lut4_config_latch_mem"/>
</hierarchy>
<bitstream>
<bit memory_port="mem_out[0]" value="0"/>
<bit memory_port="mem_out[1]" value="0"/>
<bit memory_port="mem_out[2]" value="0"/>
<bit memory_port="mem_out[3]" value="0"/>
<bit memory_port="mem_out[4]" value="0"/>
<bit memory_port="mem_out[5]" value="0"/>
<bit memory_port="mem_out[6]" value="0"/>
<bit memory_port="mem_out[7]" value="0"/>
<bit memory_port="mem_out[8]" value="0"/>
<bit memory_port="mem_out[9]" value="0"/>
<bit memory_port="mem_out[10]" value="0"/>
<bit memory_port="mem_out[11]" value="0"/>
<bit memory_port="mem_out[12]" value="0"/>
<bit memory_port="mem_out[13]" value="0"/>
<bit memory_port="mem_out[14]" value="0"/>
<bit memory_port="mem_out[15]" value="0"/>
</bitstream>
</bitstream_block>
</bitstream_block>
</bitstream_block>
</bitstream_block>
</bitstream_block>
</bitstream_block>
<!-- More bitstream blocks -->
<!-- Bitstream block of a 2-input routing multiplexer in a Switch Block (SB) -->
<bitstream_block name="sb_0__2_" hierarchy_level="1">
<bitstream_block name="mem_right_track_0" hierarchy_level="2">
<hierarchy>
<instance level="0" name="fpga_top"/>
<instance level="1" name="sb_0__2_"/>
<instance level="2" name="mem_right_track_0"/>
</hierarchy>
<input_nets>
<path id="0" net_name="unmapped"/>
<path id="1" net_name="unmapped"/>
</input_nets>
<output_nets>
<path id="0" net_name="unmapped"/>
</output_nets>
<bitstream path_id="-1">
<bit memory_port="mem_out[0]" value="0"/>
<bit memory_port="mem_out[1]" value="0"/>
</bitstream>
</bitstream_block>
</bitstream_block>
</bitstream_block>

2
docs/source/manual/fpga_bitstream/index.rst
View File

@ -12,5 +12,3 @@ FPGA-Bitstream can generate two types of bitstreams:
generic_bitstream generic_bitstream
fabric_dependent_bitstream fabric_dependent_bitstream
repack_design_constraints

2
docs/source/manual/openfpga_shell/openfpga_commands/fpga_bitstream_commands.rst
View File

@ -21,7 +21,7 @@ Repack's functionality are in the following aspects:
Apply design constraints from an external file. Apply design constraints from an external file.
Normally, repack takes the net mapping from VPR packing and routing results. 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. 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!!!** .. 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!!!**