luke
/
prjxray
mirror of https://github.com/openXC7/prjxray.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Documentation of part specific files 

This commit adds description of part specific X-Ray database files:
- tilegrid.json
- tileconn.json
- part.yaml & part.json
- package_pins.csv

Signed-off-by: Robert Winkler <rwinkler@antmicro.com>
This commit is contained in:
Robert Winkler 2020-05-19 13:47:39 +02:00
parent 368fba8316
commit 4e13706c00
5 changed files with 321 additions and 35 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
docs/dev_database/part_specific/index.rst
View File

@ -2,11 +2,13 @@
Part specific database files
============================
This section contains a description of :term:`database <database>` files that
This section contains a description of :term:`database <Database>` files that
are part (chip) specific:
.. toctree::
:maxdepth: 2
:maxdepth: 1
tilegrid
tileconn
part
package_pins

30
docs/dev_database/part_specific/package_pins.rst Normal file
View File

@ -0,0 +1,30 @@
=================
package_pins file
=================
The ``package_pins.csv`` is a simple file that describes the pins of
the particular FPGA chip package.
File format
-----------
Every row in the file represents a single pin. Each of the pins
is characterized by:
- ``pin`` - The package pin name
- ``bank`` - The ID of *IO BANK* to which the pin is connected. It should match
with the data from the :doc:`part file<./part>`
- ``site`` - The :term:`site <Site>` to which the pin belongs
- ``tile`` - The :term:`tile <Tile>` to which the pin belongs
- ``pin_function`` - The function of the pin
Example
-------
.. code-block::
A1,35,IOB_X1Y97,RIOB33_X43Y97,IO_L1N_T0_AD4N_35
This line means that the pin ``A1`` which belongs to *IO BANK* ``35``,
of ``IOB_X1Y97`` :term:`site <Site>` in ``RIOB33_X43Y97`` :term:`tile <Tile>`
has ``IO_L1N_T0_AD4N_35`` function.

146
docs/dev_database/part_specific/part.rst Normal file
View File

@ -0,0 +1,146 @@
==========
part files
==========
Both the ``part.json`` and ``part.yaml`` files contain information about
the configuration resources of the FPGA chip. The files include information
about bus types and the number of :term:`frames <Frame>` that
are available for the given configurational :term:`column <Column>`.
Additionally, the file stores information about the device ID and
available *IO BANKS*.
File format
-----------
Both files contain the same information, but since the ``part.yaml`` is
less accessible, the description will be based on the ``part.json`` file.
The ``part.json`` file is of the following form::
{
"global_clock_regions": {
"bottom": {
"rows": {
"<ROW_NUMBER>" : {
"configuration_buses": {
"<CONFIGURATION_BUS>": {
"configurational_columns": {
"<COLUMN_NUMBER>": {
"frame_count": <FRAME_COUNT>
}
<...>
}
}
<...>
}
}
<...>
}
},
"top": {
"rows": {
"<ROW_NUMBER>" : {
"configuration_buses": {
"<CONFIGURATION_BUS>": {
"configurational_columns": {
"<COLUMN_NUMBER>": {
"frame_count": <FRAME_COUNT>
}
<...>
}
}
<...>
}
}
<...>
}
},
}
},
"idcode" : <IDCODE>,
"iobanks" : {
"<BANK_ID>": <BANK_POSITION>",
<...>
}
}
The file contains three main entries:
- ``"global_clock_regions"`` - Contains the information about the configurational
resources of the FPGA chip. The 7-Series FPGAs are divided into two
:term:`halves <Half>` - ``top`` and ``bottom``. This explains the origin of
those entries in the file.
Every half contains a few ``rows`` associated with
the global :term:`clock regions <Clock region>`. The particular row of the
global :term:`clock regions <Clock region>` is indicated by the ``<ROW_NUMBER>``.
Since every row can be configured by one of three configurational buses:
``CLK_IO_CLKB``, ``BLOCK_RAM`` or ``CFG_CLB``, the appropriate bus is indicated by
the ``<CONFIGURATION_BUS>``.
There are many :term:`columns <Column>` connected to a single bus. Each column
is described by appropriate ``<COLUMN_NUMBER>`` entry which contains the
information about the number of frames (``<FRAME_COUNT>``) which can be
used to configure the particular column.
- ``"idcode"`` - ID of the given chip package
- ``"iobanks"`` - a dictionary that contains the *IO Bank* ID (``<BANK_ID>``) and
their position in the FPGA grid (``<BANK_POSITION>``).
Examples
--------
.. code-block:: javascript
{
global_clock_regions": {
"bottom": {
"rows": {
"0": {
"configuration_buses": {
"BLOCK_RAM": {
"configuration_columns": {
"0": {
"frame_count": 128
},
"1": {
"frame_count": 128
},
"2": {
"frame_count": 128
}
}
},
"CLB_IO_CLK": {
"configuration_columns": {
"0": {
"frame_count": 42
},
"1": {
"frame_count": 30
},
"2": {
"frame_count": 36
},
<...>
}
}
<...>
},
},
"top" : {
<...>
}
},
"idcode": 56803475,
"iobanks": {
"0": "X1Y78",
"14": "X1Y26",
"15": "X1Y78",
"16": "X1Y130",
"34": "X113Y26",
"35": "X113Y78"
}
}

46
docs/dev_database/part_specific/tileconn.rst
View File

@ -2,22 +2,52 @@
tileconn file
=============
The file ``tileconn.json`` contains the information how the wires of neighboring
tiles are connected to each other. It contains one entry for each pair of tile
types, each containing a list of pairs of wires that belong to the same node.
The ``tileconn.json`` file contains the information on how the wires of
neighboring tiles are connected. It contains one entry for each pair of
tile types, each containing a list of pairs of wires that belong to the same node.
.. warning:: FIXME: This is a good place to add the tile wire, pip, site pin diagram.
This file documents how adjacent tile pairs are connected.
No directionality is given.
The file contains one large list. Each entry has the following fields:
File format
-----------
- ``grid_deltas`` - (x, y) delta going from source to destination tile
- ``tile_types`` - (source, destination) tile types
- ``wire_pairs`` - list of (source tile, destination tile) wire names
The file contains one large list::
Sample entry:
[
{
"grid_deltas": [
<DELTA_X>,
<DELTA_Y>
],
"tile_types": [
"<SOURCE_TILE>",
"<DESTINATION_TILE>"
],
"wire_pairs": [
[
"<SOURCE_TILE_WIRE>",
"<DESTINATION_FILE_WIRE>"
],
<...>
],
},
<...>
]
Each entry has the following fields:
- ``grid_deltas`` - indicates the position (``<DELTA_X>``, ``<DELTA_Y>``) of
the source tile relative to the destination_file
- ``tile_types`` - contains the information about both
``<SOURCE_TILE_TYPE>`` and ``<DESTINATION_TILE_TYPE>``
- ``wire_pairs`` - contains the names of both
``<SOURCE_TILE_WIRE>`` and ``<DESTINATION_TILE_WIRE>``
Example
-------
.. code-block:: javascript

128
docs/dev_database/part_specific/tilegrid.rst
View File

@ -2,27 +2,102 @@
tilegrid file
=============
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.
The ``tilegrid.json`` is a list of all :term:`tiles <Tile>` in the device.
This information is used at various stages of the flow i.e. for
:term:`database <Database>` generation or creating a :term:`bitstream <Bitstream>`.
The most important parts of the file are related to :term:`frame <Frame>` addressing
within the :term:`bitstream <Bitstream>`, grid and :term:`clock region <Clock region>`
location, list of underlying :term:`sites <Site>`, or the type of the
:term:`tile <Tile>` itself.
tiles
-----
Before diving into this section, it is advised to familiarize yourself with the
7-Series :doc:`Bitstream Format <../../architecture/bitstream_format>` chapter and
:doc:`Configuration <../../architecture/configuration>` chapter.
Each entry has the following fields:
File format
-----------
- ``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
- ``sites`` - dictionary of sites name: site type contained within tile
- ``type`` - Vivado given tile type
The file consists of the entries describing every :term:`tile <Tile>` in
the FPGA chip. The file is of the form::
Sample entry:
{
"<TILE_NAME>": {
"bits": {
"<CONFIGURATION_BUS>": {
"baseaddr": "<BASE_ADDR>,
"frames": 28,
"offset": 97,
"words": 2
},
<...>
},
"clock_region": <CLOCK_REGION>,
"grid_x": <GRID_X>,
"grid_y": <GRID_Y>,
"pin_functions": {
"<PIN_NAME">: "<PIN_FUNCTION>",
<...>
},
"prohibited_sites": [
"<SITE_TYPE>",
<...>
],
"sites": {
"<SITE_NAME>": <SITE_TYPE>,
<...>
},
"type": "INT_R"
}
The ``<TILE_NAME>`` indicates the name of the :term:`tile <Tile>` described
in the entry. The naming convention matches Vivado.
Each :term:`tile <Tile>` entry in the file has the following fields:
- ``"bits"`` - contains the data related to :term:`tile <Tile>` configuration over
the ``<CONFIGURATION_BUS>``. There are three types of the configuration
buses in 7-Series FPGAs: ``CLB_IO_CLK``, ``BLOCK_RAM`` and ``CFG_CLB``.
Every ``<CONFIGURATION_BUS>`` has the following fields:
- ``baseaddr`` - Basic address of the configuration :term:`frame <Frame>`.
Every configuration :term:`frame <Frame>` consist of 101 of 32bit
:term:`words <Word>`. Note that a single :term:`frame <Frame>` usually configures
a bunch of :term:`tiles <Tile>` connected to the single configuration bus.
- ``"frames"`` - Number of :term:`frames <Frame>` that can configure the
:term:`tile <Tile>`.
- ``offset`` - How many words of offset is present in the :term:`frame <Frame>`
before the first :term:`word <Word>` that configures the :term:`tile <Tile>`.
- ``words`` - How many 32bit :term:`words <Word>` configure the :term:`tile <Tile>`.
- ``clock_region`` - indicates to which :term:`clock region <Clock region>` the
:term:`tile <Tile>` belongs to.
- ``grid_x`` - :term:`tile <Tile>` column, increasing right
- ``grid_y`` - :term:`tile <Tile>` row, increasing down
- ``pin_functions`` - indicates the special functions of the :term:`tile <Tile>` pins.
Usually it is related to IOB blocks and indicates i.e. differential output pins.
- ``prohibited_sites`` - Indicates which :term:`site <Site>` types cannot be used
in the :term:`tile <Tile>`
- ``sites`` - dictionary which contains information about the :term:`sites <Site>`
which can be found inside the :term:`tile <Tile>`. Every entry in
the dictionary contains the following information:
- ``"<SITE_NAME>"`` - The unique name of the :term:`site <Site>` inside
the :term:`tile <Tile>`.
- ``"<SITE_TYPE>`` - The type of the :term:`site <Site>`
- ``type`` - The type of the :term:`tile <Tile>`
Examples
--------
.. code-block:: javascript
@ -48,15 +123,18 @@ Sample entry:
Interpreted as:
- Tile is named ``CLBLL_L_X16Y149``
- Frame base address is ``0x00020800``
- For each frame, skip the first 99 words loaded into FDRI
- :term:`Tile <Tile>` is named ``CLBLL_L_X16Y149``
- :term:`Frame <Frame>` base address is ``0x00020800``
- For each :term:`frame <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``
- It spans across 36 different :term:`frame <Frame>` loads
- Located in :term:`clock region <Clock region>` ``X0Y2``
- Located at row 1, column 43
- Contains two sites, both of which are SLICEL
- Is a ``CLBLL_L`` type tile
- Contains two :term:`sites <Site>`, both of which are SLICEL
- Is a ``CLBLL_L`` type :term:`tile <Tile>`
.. warning:: FIXME: We should cross link to how to use the base address and word offset.
More information about :term:`frames <Frame>` and the FPGA configuration can be found in the
:doc:`Configuration <../../architecture/configuration>` chapter.
Example of absolute :term:`frame <Frame>` address calculation can be found in the
:doc:`mask file <../common/mask>` chapter.