Add description of architecture-specific database files to docs

This commit adds description of the following database files:
  - mask_*.db
  - ppips_*.db
  - segbits_*.db
  - site_type_*.db
  - tile_type_*.db

Signed-off-by: Robert Winkler <[email protected]>
This commit is contained in:
Robert Winkler
2020-05-19 14:14:29 +02:00
parent 1b296ea876
commit e8ff146443
16 changed files with 893 additions and 308 deletions
+15
View File
@@ -0,0 +1,15 @@
=============================
Files Common for Architecture
=============================
This section contains a description of :term:`database <database>` files
that are common for a whole chip architecture.
.. toctree::
:maxdepth: 2
mask
ppips
segbits
site_type
tile_type
+104
View File
@@ -0,0 +1,104 @@
==========
mask files
==========
The *mask files* are generated for every FPGA :term:`tile <tile>` type. They store
the information, which bits in the bitstream can configure the given
:term:`tile <tile>` type.
Naming convention
-----------------
The naming scheme for the mask files is the following::
mask_<tile>.db
Note that auxiliary ``mask_<tile>.origin_info.db`` files
provide additional information about the :term:`fuzzer <fuzzer>`,
which produced the :term:`database <database>` file. This file is optional.
Every :term:`tile <tile>` is configured at least by one of three configurational
buses mentioned in the :doc:`Configuration Section <../../architecture/configuration>`.
The default bus is called ``CLB_IO_CLK``. If the :term:`tile <tile>` can also be
configured by another bus it has additional ``mask_<tile>.<bus_name>.db``
related to that bus.
In example:
- ``mask_dsp_r.db``
- ``mask_bram_l.db`` (configured with default ``CLB_IO_CLK`` bus)
- ``mask_bram_l.block_ram.db`` (configured with ``BLOCK_RAM`` bus)
File format
-----------
The file consist of the records that describes configuration bits for
the particular :term:`tile <tile>` type. Each entry inside the file is of the form::
bit <frame_address_offset>_<bit_position>
This means that the :term:`tile <tile>` can be configured by bit located in the
:term:`frame <frame>` at the address ``<base_frame_addr> + <frame_address_offset>``,
at position ``<tile_offset> + <bit_position>``. Information about ``<base_frame_address>``
and ``<tile_offset>`` can be taken from part specific ``tilegrid.json`` file.
Example
-------
Below there is a part of artix7 ``mask_clbll_l.db`` file describing FPGA *CLBLL*
:term:`tile <tile>`::
<...>
bit 00_61
bit 00_62
bit_00_63
bit 01_00
bit 01_01
bit 01_02
<...>
The line ``bit 01_02`` means that the *CLBL_LL* :term:`tile <tile>` can be
configured by the bit located in the :term:`frame <frame>` at the address
``<base_frame_address> + 0x01``, at position ``<tile_offset> + 0x2``.
The ``tilegrid.json`` is a file specific to a given chip package.
For *xc7a35tcpg236-1* we can find exemplary *CLBLL_L* entry::
"CLBLL_L_X2Y0": {
"bits": {
"CLB_IO_CLK": {
"baseaddr": "0x00400100",
"frames": 36,
"offset": 0,
"words": 2
}
},
"clock_region": "X0Y0",
"grid_x": 10,
"grid_y": 155,
"pin_functions": {},
"sites": {
"SLICE_X0Y0": "SLICEL",
"SLICE_X1Y0": "SLICEL"
},
"type": "CLBLL_L"
},
The ``<base_frame_addr>`` can be found as a argument of the *"baseaddr"* key
and for *CLBLL_L_X2Y0* :term:`tile <tile>` it is equal to ``0x00400100``. The ``<tile_offset>``
on the other hand is an argument of the *"offset"* key. Here it is equal to 0.
Finally, we are able to compute the bit location associated with the
``bit 01_02`` entry.
The configuration bit for this record can be found in the following
:term:`frame <frame>` address::
0x00400100 + 0x01 = 0x00400101
Located at the bit position::
0x0 + 0x2 = 0x2
More about the configuration process and the meaning of the :term:`frame <frame>`
can be found in the :doc:`Configuration Section <../../architecture/configuration>`.
+62
View File
@@ -0,0 +1,62 @@
===========
ppips files
===========
The *ppips files* are generated for every FPGA :term:`tile <tile>` type.
They store the information about the pseudo-PIPs, inside the tile.
Programable Interconnect point (:term:`PIP <pip>`) is a connection inside the
:term:`tile <tile>` that can be enabled or disabled. Pseudo PIPs appears as standard
:term:`PIPs <pip>` in the Vivado tool, but they do not have actual configuration
bit pattern (they are not configurable).
Naming convention
-----------------
The naming scheme for the PPIPs files is the following::
ppips_<tile>.db
In example:
- ``ppips_dsp_l.db``
- ``ppips_clbll_l.db``
- ``ppips_bram_int_interface_l.db``
File format
-----------
The file contains one entry per pseudo-PIP, each with one of the following
three tags: ``always``, ``default`` or ``hint``. The entries are of the form:::
<ppip_location> <tag>
The tag ``always`` is used for pseudo-PIPs that are actually always-on, i.e.,
that are permanent connections between two wires.
The tag ``default`` is used for pseudo-PIPs that represent the default behavior
if no other driver has been configured for the destination net
(all default pseudo-PIPs connect to the VCC_WIRE net).
The tag ``hint`` is used for PIPs that are used by Vivado to tell the router
that two logic slice outputs drive the same value, i.e., behave like they
are connected as far as the routing process is concerned.
Example
-------
Below there is a part of artix7 ``ppips_clbll_l.db`` file::
<...>
CLBLL_L.CLBLL_L_A.CLBLL_L_A6 hint
CLBLL_L.CLBLL_L_AMUX.CLBLL_L_A hint
CLBLL_L.CLBLL_L_AX.CLBLL_BYP0 always
CLBLL_L.CLBLL_L_B.CLBLL_L_B1 hint
CLBLL_L.CLBLL_L_B.CLBLL_L_B2 hint
CLBLL_L.CLBLL_L_B.CLBLL_L_B3 hint
CLBLL_L.CLBLL_L_B.CLBLL_L_B4 hint
<...>
The ``<ppip_location>`` name is arbitrary. However, we named them in the convention
similar to the Vivado tool, which allows us to identify them quickly and provides
suggestions about their role in the FPGA chip.
+117
View File
@@ -0,0 +1,117 @@
=============
segbits files
=============
The *segbits files* are generated for every FPGA :term:`tile <tile>` type.
They store the information about the combinations of bits in the bitstream
that are responsible for enabling different features inside the :term:`tile <tile>`.
The features can be related to enabling some part of the primitive, setting some
initial state of the block, configuring pin pull-up on output pins, etc.
Naming convention
-----------------
The naming scheme for the segbits files is the following::
segbits_<tile>.db
Note that auxiliary ``segbits_<tile>.origin_info.db`` files
provide additional information about the :term:`fuzzer <fuzzer>`, which produced the
:term:`database <database>` file. This file is optional.
Every :term:`tile <tile>` is configured at least by one of three configurational buses
mentioned in the :doc:`Configuration Section <../../architecture/configuration>`.
The default bus is called ``CLB_IO_CLK``. If the :term:`tile <tile>` can also be configured
by another bus, it has additional ``segbits_<tile>.<bus_name>.db``
related to that bus.
Exemplary files:
- ``segbits_dsp_r.db``
- ``segbits_bram_l.db`` (configured with default ``CLB_IO_CLK`` bus)
- ``segbits_bram_l.block_ram.db`` (configured with ``BLOCK_RAM`` bus)
File format
-----------
The file consists of the lines, containing the information about the feature
and the list of bits that should be enabled/disabled to provide the feature's
functionality::
<feature> <bit_list>
where:
- ``<feature>`` is of the form ``<feature_name>.<feature_addr>``
- ``<bit_list>`` is the list of bits. Each bit is of the form
``<frame_address_offset>_<bit_possition>``. If the bit has the ``!``
mark in front of it, that means it should be set to **0** for feature configuration,
otherwise it should be set to **1**.
The names of the features are arbitrary. However, we named them in the convention,
which allows us to identify them quickly and provides suggestions
about the functionality that they provide. The feature names are used in the
fasm files generation.
Feature naming conventions
--------------------------
PIPs
^^^^
The ``<feature>`` names for interconnect :term:`PIPs <pip>` are stored in the
``segbits_int_l.db`` and ``segbits_int_r.db`` database files. The features that
enable interconnect :term:`PIPs <pip>` have the following syntax::
<tile_type>.<destination_wire>.<source_wire>.
For example, consider the following entry in ``segbits_int_l.db``::
INT_L.NL1BEG1.NN6END2 07_32 12_33
CLBs
^^^^
The ``<feature>`` names for CLB tiles use a dot-separated hierarchy.
For example::
CLBLL_L.SLICEL_X0.ALUT.INIT[00]
This entry documents the initialization bits the *LSB LUT* for the *ALUT* in
the *SLICEL_X0* within a *CLBLL_L tile.*
Example
-------
Below there is a part of ``segbits_liob33_l.db`` file for the *artix7*
architecture. The file describes *CLBLL* :term:`tile <tile>`::
<...>
LIOB33.IOB_Y0.IBUFDISABLE.I 38_82
LIOB33.IOB_Y0.IN_TERM.NONE !38_120 !38_122 !39_121 !39_123
LIOB33.IOB_Y0.IN_TERM.UNTUNED_SPLIT_40 38_120 38_122 39_121 39_123
LIOB33.IOB_Y0.IN_TERM.UNTUNED_SPLIT_50 38_120 38_122 !39_121 39_123
LIOB33.IOB_Y0.IN_TERM.UNTUNED_SPLIT_60 38_120 !38_122 !39_121 39_123
LIOB33.IOB_Y0.INTERMDISABLE.I 39_89
LIOB33.IOB_Y0.LVTTL.DRIVE.I24 38_64 !38_112 !38_118 38_126 39_65 39_117 39_119 !39_125 !39_127
LIOB33.IOB_Y0.PULLTYPE.KEEPER 38_92 38_94 !39_93
LIOB33.IOB_Y0.PULLTYPE.NONE !38_92 38_94 !39_93
LIOB33.IOB_Y0.PULLTYPE.PULLDOWN !38_92 !38_94 !39_93
LIOB33.IOB_Y0.PULLTYPE.PULLUP !38_92 38_94 39_93
<...>
In example, the line::
LIOB33.IOB_Y0.PULLTYPE.PULLUP !38_92 38_94 39_93
means that the feature ``LIOB33.IOB_Y0.PULLTYPE.PULLUP`` will be set by clearing
bit ``!38_92`` and setting bits ``38_94`` and ``39_93``.
Generally, ``<feature>`` name is connected with its functionality.
In example, ``LIOB33.IOB_Y0.PULLTYPE.PULLUP`` means that in the LIOB33
:term:`tile <tile>`,
in IOB_Y0 site the *pull type* will be set to *PULLUP*.
This simply means that all pins belonging to this particular IOB
will be configured with pull-up.
+122
View File
@@ -0,0 +1,122 @@
===============
site_type files
===============
The *site_type files* are generated for every FPGA
:term:`site <site>` type. They store the information about the pins and
:term:`PIPs <pip>` of the :term:`site <site>`.
Naming convention
-----------------
The naming scheme for the :term:`site <site>` type files is the following::
site_type_<site>.json
Exemplary files:
- ``site_type_IDELAYE2.json``
- ``site_type_PLLE2_ADV.json``
- ``site_type_SLICEL.json``
File format
-----------
The :term:`site <site>` type files are JSON files with the following scheme::
{
"site_pins": {
"<PIN_NAME>": {
"direction": "<DIR>"
},
<...>
},
"site_pips": {
"<PIP_NAME>": {
"from_pin": "<PIN_NAME>",
"to_pin": "<PIN_NAME>"
}
},
"type": "<TYPE>"
}
where:
- *<PIN_NAME>* - specifies the :term:`site <site>` pin name
- *<PIP_NAME>* - specifies the :term:`site <site>` :term:`pip <pip>` name
- *<DIR>* - is a direction of a pin (either **IN** or **OUT**)
- *<TYPE>* - specifies the :term:`site <site>` type
The ``"site_pins"`` section describes the input pins of a :term:`site <site>`
and its directions. The ``"site_pips"`` describes the :term:`PIPs <pip>`
inside the :term:`site <site>` and which wires they can connect.
Example
-------
Below there is a part of ``site_type_SLICEL.json`` file for the *artix7*
architecture::
{
"site_pins": {
"A": {
"direction": "OUT"
},
"A1": {
"direction": "IN"
},
"A2": {
"direction": "IN"
},
"A3": {
"direction": "IN"
},
"A4": {
"direction": "IN"
},
"A5": {
"direction": "IN"
},
"A6": {
"direction": "IN"
},
<...>
},
"site_pips": {
"A5FFMUX:IN_A": {
"from_pin": "IN_A",
"to_pin": "OUT"
},
"A5FFMUX:IN_B": {
"from_pin": "IN_B",
"to_pin": "OUT"
},
"A5LUT:A1": {
"from_pin": "A1",
"to_pin": "O5"
},
"A5LUT:A2": {
"from_pin": "A2",
"to_pin": "O5"
},
"A5LUT:A3": {
"from_pin": "A3",
"to_pin": "O5"
},
"A5LUT:A4": {
"from_pin": "A4",
"to_pin": "O5"
},
"A5LUT:A5": {
"from_pin": "A5",
"to_pin": "O5"
},
<...>
},
"type": "SLICEL"
}
Compare the description with the `Xilinx documentation`_ of that :term:`site <site>`.
.. _Xilinx documentation: https://www.xilinx.com/support/documentation/user_guides/ug474_7Series_CLB.pdf#page=20
+259
View File
@@ -0,0 +1,259 @@
===============
tile_type files
===============
The *tile_type files* are generated for every FPGA :term:`tile <tile>`
type. They store the information about the :term:`tile <tile>` configuration,
it's :term:`PIPs <pip>`, :term:`sites <site>`, wires and their properties.
Naming convention
-----------------
The naming scheme for the segbits files is the following::
tile_type_<tile>.json
Exemplary files:
- ``tile_type_INT_L.json``
- ``tile_type_BRAM_L.json``
- ``tile_type_HCLK_CLB.json``
File format
-----------
The :term:`tile <tile>` type files are JSON files with the following shape::
{
"pips": {
"<PIP_NAME>": {
"can_invert":' "<BOOL>",
"dst_to_src": {
"delay": [
"<DEALY_VALUE>",
"<DELAY_VALUE>",
"<DELAY_VALUE>",
"<DELAY_VALUE>"
],
"in_cap": "<IN_CAPACITANCE>",
"res": "<RESISTANCE>"
},
"dst_wire": "<WIRE_NAME>",
"is_directional": "<BOOL>",
"is_pass_transistor": <BOOL>,
"is_pseudo": "0",
"src_to_dst": {
"delay": [
"<DELAY_VALUE>",
"<DELAY_VALUE>",
"<DELAY_VALUE>",
"<DELAY_VALUE>"
],
"in_cap": "<IN_CAPACITANCE>",
"res": "<RESISTANCE>"
},
"src_wire": "<WIRE_NAME>"
},
},
"sites": [
{
"name": "<SITE_NAME>",
"prefix": "<SITE_PREFIX>",
"site_pins": {
"<SITE_PIN_NAME>": {
"cap": "<CAPACITY>",
"delay": [
"<DELAY_VALUE>",
"<DELAY_VALUE>",
"<DELAY_VALUE>",
"<DELAY_VALUE>"
],
"wire": "<WIRE_NAME>"
},
<...>
],
"tile_type": "<TILE_TYPE>",
"wires": {
"<WIRE_NAME>": {
"cap": "<WIRE_CAPACITY>",
"res": "<WIRE_RESISTANCE>"
},
<...>
},
}
"pips" section
^^^^^^^^^^^^^^
The "pips" section describes all :term:`PIPs <pip>` in the :term:`tile <tile>`.
Every :term:`PIP <pip>` has it's name - ``"<PIN_NAME>"`` and may be
characterized by the following attributes:
- ``"can_invert"`` - takes a value which can be either **1** or **0**.
It defines whether the :term:`PIP <pip>` has an inverter on it's output or not.
- ``dst_to_src"`` - information about the connection in the direction
from destination to source. It describes the following properties of the connection:
- ``"delay"`` - four-element list, which contain information about the delays.
- ``"in_cap"`` - the input capacitance of the :term:`PIP <pip>`
- ``"res"`` - the resistance of the :term:`PIP <pip>`.
- ``dst_wire`` - the destination wire name
- ``is_directional`` - contains the information whether :term:`PIP <pip>` is directional.
- ``is_pass_transisstor`` - contains the information whether :term:`PIP <pip>` acts
as a pass transistor
- ``is_pseudo`` - contains the information whether :term:`PIP <pip>` is a pseudo-PIP
- ``src_to_dst`` - contains the information about the connection in the direction
from source to destination. It is described by the same set of properties as
``dst_to_src`` section.
"sites" section:
^^^^^^^^^^^^^^^^
The "sites" section describes all :term:`sites <site>` in the :term:`tile <tile>`.
Every :term:`site <site>` may be characterized by the following attributes:
- ``"name"`` - location in the :term:`tile <tile>` grid
- ``"prefix"`` - the type of the :term:`site <site>`
- ``"site_pins"`` - describes the pins that belong to the :term:`site <site>`.
Every pin has it's name - ``"<PIN_NAME>"`` and may be described
by the following attributes:
- ``"cap"`` - pin capacitance
- ``"delay"`` - pin delay
- ``"wire"`` - wire associated with the pin
- ``"type"`` - indicates the type of the site
- ``"x_coord"`` - describes *x* coordinate of the site position inside the tile
- ``y_coord"`` - describes the *y* coordinate of the site position inside the tile
"wires" section
^^^^^^^^^^^^^^^
The "wires" section describes the wires located in the :term:`tile <tile>`.
Every wire has it's name - ``"<WIRE_NAME>"`` and may be characterized
by the following attributes:
- ``"cap"`` - wire capacitance
- ``"res"`` - wire resistance
Other
^^^^^
- ``"tile_type"`` - indicates the type of the tile
Example
-------
Below there is a part of ``tile_type_BRAM_L.json`` for the *artix7* architecture::
{
"pips": {
"BRAM_L.BRAM_ADDRARDADDRL0->>BRAM_FIFO18_ADDRATIEHIGH0": {
"can_invert": "0",
"dst_to_src": {
"delay": [
"0.038",
"0.046",
"0.111",
"0.134"
],
"in_cap": "0.000",
"res": "737.319"
},
"dst_wire": "BRAM_FIFO18_ADDRATIEHIGH0",
"is_directional": "1",
"is_pass_transistor": 0,
"is_pseudo": "0",
"src_to_dst": {
"delay": [
"0.038",
"0.046",
"0.111",
"0.134"
],
"in_cap": "0.000",
"res": "737.319"
},
"src_wire": "BRAM_ADDRARDADDRL0"
},
<...>
"BRAM_L.BRAM_IMUX12_1->BRAM_IMUX_ADDRARDADDRU8": {
"can_invert": "0",
"dst_to_src": {
"delay": null,
"in_cap": null,
"res": "0.000"
},
"dst_wire": "BRAM_IMUX_ADDRARDADDRU8",
"is_directional": "1",
"is_pass_transistor": 1,
"is_pseudo": "0",
"src_to_dst": {
"delay": null,
"in_cap": null,
"res": "0.000"
},
"src_wire": "BRAM_IMUX12_1"
},
<...>
},
"sites": [
{
"name": "X0Y0",
"prefix": "RAMB18",
"site_pins": {
"ADDRARDADDR0": {
"cap": "0.000",
"delay": [
"0.000",
"0.000",
"0.000",
"0.000"
],
"wire": "BRAM_FIFO18_ADDRARDADDR0"
},
<...>
"WRERR": {
"delay": [
"0.000",
"0.000",
"0.000",
"0.000"
],
"res": "860.0625",
"wire": "BRAM_RAMB18_WRERR"
},
<...>
},
"type": "RAMB18E1",
"x_coord": 0,
"y_coord": 1
}
],
"tile_type": "BRAM_L",
"wires": {
"BRAM_ADDRARDADDRL0": null,
"BRAM_ADDRARDADDRL1": null,
"BRAM_ADDRARDADDRL2": null,
"BRAM_ADDRARDADDRL3": null,
"BRAM_EE2A0_0": {
"cap": "60.430",
"res": "268.920"
},
<...>
"BRAM_EE2A0_1": {
"cap": "60.430",
"res": "268.920"
},
<...>
}