mirror of https://github.com/openXC7/prjxray.git
Add small fixes to the database documentation
Signed-off-by: Tomasz Michalak <tmichalak@antmicro.com>
This commit is contained in:
Tomasz Michalak
Robert Winkler
parent
e8ff146443
commit
39813be4cb
|
|
@ -1,15 +1,15 @@
|
|||
=============================
|
||||
Files Common for Architecture
|
||||
=============================
|
||||
=====================
|
||||
Common database files
|
||||
=====================
|
||||
|
||||
This section contains a description of :term:`database <database>` files
|
||||
that are common for a whole chip architecture.
|
||||
that are common for all Xilinx series 7 chip architectures.
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
mask
|
||||
ppips
|
||||
segbits
|
||||
site_type
|
||||
tile_type
|
||||
ppips
|
||||
mask
|
||||
|
|
|
|||
|
|
@ -2,8 +2,8 @@
|
|||
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
|
||||
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
|
||||
|
|
@ -19,11 +19,11 @@ 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``
|
||||
The default bus is called ``CLB_IO_CLK``.
|
||||
If the :term:`tile <tile>` can also be configured by another bus, it has an additional ``mask_<tile>.<bus_name>.db``
|
||||
related to that bus.
|
||||
|
||||
In example:
|
||||
For example:
|
||||
|
||||
- ``mask_dsp_r.db``
|
||||
- ``mask_bram_l.db`` (configured with default ``CLB_IO_CLK`` bus)
|
||||
|
|
@ -32,12 +32,12 @@ In example:
|
|||
File format
|
||||
-----------
|
||||
|
||||
The file consist of the records that describes configuration bits for
|
||||
The file consists of records that describe the 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
|
||||
This means that the :term:`tile <tile>` can be configured by a 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.
|
||||
|
|
@ -45,13 +45,13 @@ 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*
|
||||
Below there is a part of artix7 ``mask_clbll_l.db`` file describing a FPGA *CLBLL*
|
||||
:term:`tile <tile>`::
|
||||
|
||||
<...>
|
||||
bit 00_61
|
||||
bit 00_62
|
||||
bit_00_63
|
||||
bit 00_63
|
||||
bit 01_00
|
||||
bit 01_01
|
||||
bit 01_02
|
||||
|
|
@ -62,7 +62,7 @@ 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::
|
||||
For *xc7a35tcpg236-1* we can find an exemplary *CLBLL_L* entry::
|
||||
|
||||
"CLBLL_L_X2Y0": {
|
||||
"bits": {
|
||||
|
|
|
|||
|
|
@ -5,8 +5,8 @@ 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
|
||||
Programable Interconnect Point (:term:`PIP <pip>`) is a connection inside the
|
||||
:term:`tile <tile>` that can be enabled or disabled. Pseudo PIPs appear as standard
|
||||
:term:`PIPs <pip>` in the Vivado tool, but they do not have actual configuration
|
||||
bit pattern (they are not configurable).
|
||||
|
||||
|
|
@ -17,7 +17,7 @@ The naming scheme for the PPIPs files is the following::
|
|||
|
||||
ppips_<tile>.db
|
||||
|
||||
In example:
|
||||
For example:
|
||||
|
||||
- ``ppips_dsp_l.db``
|
||||
- ``ppips_clbll_l.db``
|
||||
|
|
@ -57,6 +57,5 @@ Below there is a part of artix7 ``ppips_clbll_l.db`` file::
|
|||
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.
|
||||
The ``<ppip_location>`` name is arbitrary. However, the naming convention is
|
||||
similar to the one in the Vivado tool, which allows for quick identification of their role in the FPGA chip.
|
||||
|
|
|
|||
|
|
@ -35,7 +35,7 @@ Exemplary files:
|
|||
File format
|
||||
-----------
|
||||
|
||||
The file consists of the lines, containing the information about the feature
|
||||
The file consists of lines containing the information about the feature
|
||||
and the list of bits that should be enabled/disabled to provide the feature's
|
||||
functionality::
|
||||
|
||||
|
|
@ -49,10 +49,8 @@ where:
|
|||
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.
|
||||
The names of the features are arbitrary. However, the naming convention allows for quick identifaction of the functionality that is being configured.
|
||||
The feature names are used during the generation of the :doc:`FASM <../../../../fasm/docs/specification>` file.
|
||||
|
||||
|
||||
Feature naming conventions
|
||||
|
|
@ -79,14 +77,14 @@ For example::
|
|||
|
||||
CLBLL_L.SLICEL_X0.ALUT.INIT[00]
|
||||
|
||||
This entry documents the initialization bits the *LSB LUT* for the *ALUT* in
|
||||
This entry documents the initialization bits of 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>`::
|
||||
Below there is a part of the ``segbits_liob33_l.db`` file for the *artix7*
|
||||
architecture. The file describes the *CLBLL* :term:`tile <tile>`::
|
||||
|
||||
<...>
|
||||
LIOB33.IOB_Y0.IBUFDISABLE.I 38_82
|
||||
|
|
@ -102,15 +100,15 @@ architecture. The file describes *CLBLL* :term:`tile <tile>`::
|
|||
LIOB33.IOB_Y0.PULLTYPE.PULLUP !38_92 38_94 39_93
|
||||
<...>
|
||||
|
||||
In example, the line::
|
||||
For 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
|
||||
Generally, the ``<feature>`` name is linked with its functionality.
|
||||
For 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
|
||||
|
|
|
|||
|
|
@ -13,7 +13,7 @@ The naming scheme for the :term:`site <site>` type files is the following::
|
|||
|
||||
site_type_<site>.json
|
||||
|
||||
Exemplary files:
|
||||
Example files:
|
||||
|
||||
- ``site_type_IDELAYE2.json``
|
||||
- ``site_type_PLLE2_ADV.json``
|
||||
|
|
|
|||
|
|
@ -4,7 +4,7 @@ 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.
|
||||
its :term:`PIPs <pip>`, :term:`sites <site>`, wires and their properties.
|
||||
|
||||
Naming convention
|
||||
-----------------
|
||||
|
|
@ -13,7 +13,7 @@ The naming scheme for the segbits files is the following::
|
|||
|
||||
tile_type_<tile>.json
|
||||
|
||||
Exemplary files:
|
||||
Example files:
|
||||
|
||||
- ``tile_type_INT_L.json``
|
||||
- ``tile_type_BRAM_L.json``
|
||||
|
|
@ -86,18 +86,18 @@ The :term:`tile <tile>` type files are JSON files with the following shape::
|
|||
^^^^^^^^^^^^^^
|
||||
|
||||
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
|
||||
Every :term:`PIP <pip>` has its name - ``"<PIN_NAME>"`` and may be
|
||||
characterized by the following attributes:
|
||||
|
||||
- ``"can_invert"`` - takes a value which can be either **1** or **0**.
|
||||
- ``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
|
||||
- ``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>`.
|
||||
- ``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
|
||||
|
||||
|
|
@ -118,37 +118,37 @@ characterized by the following attributes:
|
|||
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
|
||||
- ``name`` - location in the :term:`tile <tile>` grid
|
||||
|
||||
- ``"prefix"`` - the type of the :term:`site <site>`
|
||||
- ``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
|
||||
- ``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
|
||||
- ``cap`` - pin capacitance
|
||||
- ``delay`` - pin delay
|
||||
- ``wire`` - wire associated with the pin
|
||||
|
||||
- ``"type"`` - indicates the type of the site
|
||||
- ``type`` - indicates the type of the site
|
||||
|
||||
- ``"x_coord"`` - describes *x* coordinate of the site position inside the tile
|
||||
- ``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
|
||||
- ``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
|
||||
Every wire has it's name - ``<WIRE_NAME>`` and may be characterized
|
||||
by the following attributes:
|
||||
|
||||
- ``"cap"`` - wire capacitance
|
||||
- ``"res"`` - wire resistance
|
||||
- ``cap`` - wire capacitance
|
||||
- ``res`` - wire resistance
|
||||
|
||||
Other
|
||||
^^^^^
|
||||
- ``"tile_type"`` - indicates the type of the tile
|
||||
- ``tile_type`` - indicates the type of the tile
|
||||
|
||||
|
||||
Example
|
||||
|
|
|
|||
|
|
@ -4,14 +4,13 @@ Description
|
|||
|
||||
The main goal of the X-Ray Project is to provide information
|
||||
about Xilinx 7-Series FPGA internals. All obtained chip data is stored in
|
||||
the project's database and is used by `Architecture Definitions`_ project
|
||||
to prepare bitstream for the chosen 7-Series FPGA chip.
|
||||
the project's database and is used by the `Architecture Definitions`_ project
|
||||
to produce a bitstream for the chosen 7-Series FPGA chip.
|
||||
|
||||
The database is generated by the fuzzers and is located in the ``database``
|
||||
directory. Each supported chip architecture has its own set of files, they
|
||||
are located in ``database/<device_arch>/``. Although the database
|
||||
is huge it consists only of a few file types. Some of them are common
|
||||
for whole 7-Series architecture, but some of them are part-specific.
|
||||
The database files are generated by the :doc:`fuzzers <../db_dev_process/fuzzers/index>` and are located in the ``database``
|
||||
directory. Each supported chip architecture has its own set of files, which are located in ``database/<device_arch>/``.
|
||||
The database can be quite huge, however it consists only of a few file types.
|
||||
Some of them are common for the whole 7-Series architecture, but some of them are part specific.
|
||||
|
||||
.. _Architecture Definitions: https://github.com/SymbiFlow/symbiflow-arch-defs
|
||||
|
||||
|
|
@ -24,8 +23,7 @@ Files common for whole 7-Series family:
|
|||
- ``tile_type_*``
|
||||
- ``timings/*``
|
||||
|
||||
Some files are specific to a given part and are located in a separate directory.
|
||||
The directory is named from the FPGA part name i.e *xc7a35tcpg236-1* or *xc7a50tfgg484-1*.
|
||||
The files specific to a given part are located in a separate directory which is named after the FPGA part name i.e *xc7a35tcpg236-1* or *xc7a50tfgg484-1*.
|
||||
|
||||
Files specific for the particular FPGA part:
|
||||
|
||||
|
|
|
|||
|
|
@ -2,8 +2,8 @@
|
|||
Database
|
||||
========
|
||||
|
||||
This section documents how prjxray represents the bitstream database.
|
||||
The databases are plain text files, using either simple line-based syntax or JSON.
|
||||
This section documents how the bitstream database is represented in project X-Ray.
|
||||
The database is a collection of plain text files, using either simple line-based syntax or JSON format.
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
===================
|
||||
Part Specific Files
|
||||
===================
|
||||
============================
|
||||
Part specific database files
|
||||
============================
|
||||
|
||||
This section contains a description of :term:`database <database>` files that
|
||||
are part (chip) specific:
|
||||
|
|
|
|||
|
|
@ -44,7 +44,7 @@ Sample entry:
|
|||
|
||||
Interpreted as:
|
||||
|
||||
- Use when a CLBLL_L is above a HCLK_CLB (ie pointing south from CLBLL_L)
|
||||
- Connect CLBLL_L.CLBLL_LL_CIN to HCLK_CLB.HCLK_CLB_COUT0_L
|
||||
- Connect CLBLL_L.CLBLL_L_CIN to HCLK_CLB.HCLK_CLB_COUT1_L
|
||||
- Use when a ``CLBLL_L`` is above a ``HCLK_CLB`` (i.e. pointing south from ``CLBLL_L``)
|
||||
- Connect ``CLBLL_L.CLBLL_LL_CIN`` to ``HCLK_CLB.HCLK_CLB_COUT0_L``
|
||||
- Connect ``CLBLL_L.CLBLL_L_CIN`` to ``HCLK_CLB.HCLK_CLB_COUT1_L``
|
||||
- A global clock tile is feeding into slice carry chain inputs
|
||||
|
|
|
|||
|
|
@ -2,79 +2,23 @@
|
|||
tilegrid file
|
||||
=============
|
||||
|
||||
The file ``tilegrid.json`` contains lists of all tiles in the device and the
|
||||
configuration segments formed by those tiles. It also documents the membership
|
||||
relationship of tiles and segments.
|
||||
|
||||
For each segment this contains the configuration frame base address, and the
|
||||
word offset within the frames, as well as the number of frames for the segment
|
||||
and number of occupied words in each frame.
|
||||
|
||||
.. warning:: FIXME: We should cross link to how to use the base address and word offset.
|
||||
|
||||
For each tile this file contains the tile type, grid X/Y coordinates for the tile,
|
||||
and sites (slices) within the tile. This section assumes you are already
|
||||
familiar with the 7 series bitstream format.
|
||||
|
||||
This file contains two elements:
|
||||
|
||||
- segments: each entry lists sections of the bitstream that encode part of one or more tiles
|
||||
- tiles: cores
|
||||
|
||||
segments
|
||||
--------
|
||||
|
||||
Segments are a prjxray concept. Each entry has the following fields:
|
||||
|
||||
- ``baseaddr`` - a tuple of (base address, inter-frame offset)
|
||||
- ``frames`` - how many frames are required to make a complete segment
|
||||
- ``words`` - number of inter-frame words required for a complete segment
|
||||
- ``tiles`` - which tiles reference this segment
|
||||
- ``type`` - prjxray given segment type
|
||||
|
||||
Sample entry:
|
||||
|
||||
.. code-block:: javascript
|
||||
|
||||
"SEG_CLBLL_L_X16Y149": {
|
||||
"baseaddr": [
|
||||
"0x00020800",
|
||||
99
|
||||
],
|
||||
"frames": 36,
|
||||
"tiles": [
|
||||
"CLBLL_L_X16Y149",
|
||||
"INT_L_X16Y149"
|
||||
],
|
||||
"type": "clbll_l",
|
||||
"words": 2
|
||||
}
|
||||
|
||||
Interpreted as:
|
||||
|
||||
- Segment is named SEG_CLBLL_L_X16Y149
|
||||
- Frame base address is 0x00020800
|
||||
- For each frame, skip the first 99 words loaded into FDRI
|
||||
- Since its 2 FDRI words out of possible 101, its the last 2 words
|
||||
- It spans across 36 different frame loads
|
||||
- The data in this segment is used by two different tiles: CLBLL_L_X16Y149, INT_L_X16Y149
|
||||
|
||||
Historical note:
|
||||
|
||||
In the original encoding, a segment was a collection of tiles that were encoded together.
|
||||
For example, a CLB is encoded along with a nearby switch.
|
||||
However, some tiles, such as BRAM, are much more complex. For example,
|
||||
the configuration and data are stored in seperate parts of the bitstream.
|
||||
The BRAM itself also spans multiple tiles and has multiple switchboxes.
|
||||
The ``tilegrid.json`` is a list of all tiles in the device.
|
||||
Each entry contains information related to the specific tile which is used at various stages of the database generation or bitstream creation.
|
||||
The most important parts of the data are related to frame addressing within the bitstream, grid and clock region location, list of underlying sites or the type of the tile itself.
|
||||
Before diving into this section it is advised to familiarize yourself with the 7 series :doc:`bitstream format <../../architecture/bitstream_format>` chapter.
|
||||
|
||||
tiles
|
||||
-----
|
||||
|
||||
Each entry has the following fields:
|
||||
|
||||
- ``baseaddr`` - a tuple of (base address, inter-frame offset)
|
||||
- ``frames`` - how many frames are required to make a complete segment
|
||||
- ``offset`` - offset of the configuration word within the frame
|
||||
- ``words`` - number of inter-frame words required for a complete segment
|
||||
- ``clock_regions`` - the name of the clock region the tile resides in
|
||||
- ``grid_x`` - tile column, increasing right
|
||||
- ``grid_y`` - tile row, increasing down
|
||||
- ``segment`` - the primary segment providing bitstream configuration
|
||||
- ``sites`` - dictionary of sites name: site type contained within tile
|
||||
- ``type`` - Vivado given tile type
|
||||
|
||||
|
|
@ -82,20 +26,37 @@ Sample entry:
|
|||
|
||||
.. code-block:: javascript
|
||||
|
||||
"CLBLL_L_X16Y149": {
|
||||
"grid_x": 43,
|
||||
"grid_y": 1,
|
||||
"segment": "SEG_CLBLL_L_X16Y149",
|
||||
"sites": {
|
||||
"SLICE_X24Y149": "SLICEL",
|
||||
"SLICE_X25Y149": "SLICEL"
|
||||
},
|
||||
"type": "CLBLL_L"
|
||||
}
|
||||
"CLBLL_L_X16Y149": {
|
||||
"bits": {
|
||||
"CLB_IO_CLK": {
|
||||
"baseaddr": "0x00020800",
|
||||
"frames": 36,
|
||||
"offset": 99,
|
||||
"words": 2
|
||||
}
|
||||
},
|
||||
"clock_region": "X0Y2",
|
||||
"grid_x": 43,
|
||||
"grid_y": 1,
|
||||
"pin_functions": {},
|
||||
"sites": {
|
||||
"SLICE_X24Y149": "SLICEL",
|
||||
"SLICE_X25Y149": "SLICEL"
|
||||
},
|
||||
"type": "CLBLL_L"
|
||||
}
|
||||
|
||||
Interpreted as:
|
||||
|
||||
- Tile is named ``CLBLL_L_X16Y149``
|
||||
- Frame base address is ``0x00020800``
|
||||
- For each frame, skip the first 99 words loaded into FDRI
|
||||
- Since it's 2 FDRI words out of possible 101, it's the last 2 words
|
||||
- It spans across 36 different frame loads
|
||||
- Located in clock region ``X0Y2``
|
||||
- Located at row 1, column 43
|
||||
- Is configured by segment SEG_CLBLL_L_X16Y149
|
||||
- Contains two sites, both of which are SLICEL
|
||||
- A CLBLL_L type tile
|
||||
- Is a ``CLBLL_L`` type tile
|
||||
|
||||
.. warning:: FIXME: We should cross link to how to use the base address and word offset.
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue