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

Merge pull request #1269 from antmicro/dev_database 

Extend the Database section of the documentation
This commit is contained in:
Tomasz Michalak 2020-05-20 09:50:36 +02:00 committed by GitHub
parent acb6210a76 4e13706c00
commit 316461a42d
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
22 changed files with 1441 additions and 325 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

16
docs/architecture/index.rst Normal file
View File

@ -0,0 +1,16 @@
============================
Xilinx 7-series Architecture
============================
.. toctree::
:maxdepth: 1
overview
configuration
bitstream_format
interconnect
dram_configuration
glossary
reference
code_of_conduct
updating_the_docs

5
docs/db_dev_process/fuzzers/index.rst
View File

@ -1,10 +1,11 @@
Fuzzers
=======
Fuzzers are things that generate a design, feed it to Vivado, and look at the resulting bitstream to make some conclusion.
Fuzzers are a set of tests which generate a design, feed it to Vivado, and look at the resulting bitstream to make some conclusion.
This is how the contents of the database are generated.
The general idea behind fuzzers is to pick some element in the device (say a block RAM or IOB) to target.
If you picked the IOB (no one is working on that yet), you'd write a design that is implemented in a specific IOB.
If you picked the IOB, you'd write a design that is implemented in a specific IOB.
Then you'd create a program that creates variations of the design (called specimens) that vary the design parameters, for example, changing the configuration of a single pin.
A lot of this program is TCL that runs inside Vivado to change the design parameters, because it is a bit faster to load in one Verilog model and use TCL to replicate it with varying inputs instead of having different models and loading them individually.

14
docs/db_dev_process/index.rst Normal file
View File

@ -0,0 +1,14 @@
============================
Database Development Process
============================
.. toctree::
:maxdepth: 1
readme
contributing
new_fuzzer
fuzzers/index
minitests/index
parts

162
docs/db_dev_process/new_fuzzer.rst Normal file
View File

@ -0,0 +1,162 @@
Adding New Fuzzer
=================
This chapter describes how to create a new fuzzer using a DSP as an example target primitive.
The files that are generated with such fuzzer have been described in more detail in the :doc:`Database<../dev_database/index>` chapter.
The process of creating a new fuzzer consists of two elements, namely base address calculation and feature fuzzing.
Base Address Calculation
------------------------
The base address calculation is based on segmatching (statistical
constraint solver) the base addresses. A similar technique is used in
most fuzzers for solving configuration bits.
Methodology
+++++++++++
In this technique all IP blocks are changed in parallel. This means that
log(N, 2) bitstreams are required instead of N to get the same number of
base addresses. However, as part of this conversion, address propagation
is also generally discouraged. So it is also recommended to toggle bits
in all IP blocks in a column, not just one. In the CLB case, this means
that every single CLB tile gets one bit set to a random value. If there
are 4 CLB CMT columns in the ROI, this means we'd randomly set 4 * 50
bits in every bitstream. With 200 bits, it takes minimum floor(log(200,
2)) => 8 bitstreams (specimens) to solve all of them.
Calculating the base address
++++++++++++++++++++++++++++
#. Find a tilegrid fuzzer to copy, e.g. "dsp"
#. Enter your copied directory
#. Edit `top.py`
a. Refer to the `Xilinx 7 Series Library guide <https://www.xilinx.com/support/documentation/sw_manuals/xilinx2012_2/ug953-vivado-7series-libraries.pdf>`_ and/or Vivado layout to understand the primitive you need to instantiate
b. Find a single bit parameter that can be easily toggled, such as a clock inverter or a bulk configuration bit
c. Find the correct site type in gen_sites()
d. Instantiate the correct verilog library macro in top
e. LOC it, if necessary. It's necessary to LOC it if there is more than one
#. Run make, and look at Vivado's output. Especially if you took shortcuts instantiating your macro (ex: not connecting critical ports) you may need to add DRC waivers to generate.tcl
#. Inspect the ``build/segbits_tilegrid.tdb`` to observe bit addresses, for example ``DSP_L_X22Y0.DWORD:0.DFRAME:1b 0040171B_000_01``
#. The ``DFRAME`` etc entries are deltas to convert this feature offset to the base address for the tile
#. We will fix them in the subsequent step
#. Correct Makefile's ``GENERATE_ARGS`` to make it the section base address instead of a specific bit in that memory region
#. Align address to 0x80: 0x0040171B => --dframe 1B to yield a base address of 0x00401700
#. Correct word offset. This is harder since it requires some knowledge of how and where the IP block memory is as a whole
i. If there is only one tile of this type in the DSP column:
start by assuming it occupies the entire address range.
In this step add a delta to make the word offset 0 (--dword 0) and later indicate that it occupies 101 words (all of them)
ii. If there are multiple: compare the delta between adjacent tiles to get the pitch.
This should give an upper bound on the address size.
Make a guess with that in mind and you may have to correct it later when you have better information.
#. Align bits to 0: 1 => --dbit 1
#. Run ``make clean && make``
#. Verify ``build/segbits_tilegrid.tdb`` now looks resolved
#. Ex: ``DSP_L_X22Y0.DWORD:0.DFRAME:1b 0040171B_000_01``
#. In this case there were several DSP48 sites per DSP column
#. Find the number of frames for your tile
#. Run ``$XRAY_BLOCKWIDTH build/specimen_001/design.bit``
#. Find the base address you used above i.e. we used ``0x00401700``, so use ``0x00401700: 0x1B`` (0x1C => 28)
#. This information is in the part YAML file, but is not as easy to read
#. Return to the main tilegrid directory
#. Edit ``tilegrid/add_tdb.py``
#. Find ``tdb_fns`` and add an entry for your tile type e.g. ``(dsp/build/segbits_tilegrid.tdb", 28, 10)``
#. This is declared to be 28 frames wide and occupy 10 words per tile in the DSP column
#. Run ``make`` in the tilegrid directory
#. Look at ``build/tilegrid.json``
#. Observe your base address(es) have been inserted (look for bits ``CLB_IO_CLK`` entry in the ``DSP_L_*`` tiles)
Feature Fuzzing
---------------
The general idea behind fuzzers is to pick some element in the device (say a block RAM or IOB) to target and write a design that is implemented in a specific element.
Next, we need to create variations of the design (called specimens) that vary the design parameters, for example, changing the configuration of a single pin and process them in Vivado in order to obtain the respective bitstreams.
Finally, by looking at all the resulting specimens, the information which bits in which frame correspond to a particular choice in the design can be correlated.
Looking at the implemented design in Vivado with "Show Routing Resources" turned on is quite helpful in understanding what all choices exist.
Fuzzer structure
++++++++++++++++
Typically a fuzzer directory consists of a mixture of makefiles, bash,
python and tcl scripts. Many of the scripts are shared among fuzzers and
only some of them have to be modified when working on a new fuzzer.
- Makefile and a number of sub-makefiles contain various targets that
have to be run in order to run the fuzzer and commit the results
to the final database. The most important ones are:
- *run* - run the fuzzer to generate the netlist, create
bitstreams in Vivado, solve the bits and update the final
database with the newly calculated results.
- *database -* run the fuzzer without updating the final database
The changes usually done in the Makefile concern various script
parameters, like number of specimen, regular expressions for inclusion
or exclusion list of features to be calculated or maximal number of
iterations the fuzzer should try to solve the bits for.
- *top.py* - Python script used to generate the verilog netlist which
will be used by the fuzzer for all Vivado runs.
- *generate.tcl -* tcl script used by Vivado to read the base verilog
design, if necessary tweak some properties and write out the
specimen bitstreams
- *generate.py -* Python script that reads the generated bitstream and
takes a parameterized description of the design (usually in the
form of a csv file) in order to produce a file with information
about which features are enabled and which are disabled in a given
segment.
Creating the fuzzer
+++++++++++++++++++
1. Open the *top.py* script and modify the content of the top module by
instantiating a DSP primitive and specifying some parameters. Use
LOC and DONT_TOUCH attributes to avoid some design optimization
since the netlists are in many cases very artificial.
2. Make sure the *top.py* script generates apart from the top.v
netlist, a csv file with the values of parameters used in the
generated netlist.
3. Modify the *generate.tcl* script to read the netlist generated in
step 1, apply, if necessary, some parameters from the csv file
generated in step 2 and write out the bitstream
4. Modify the *generate.py* script to insert the tags, which signify
whether a feature is disabled or enabled in a site, based on the
csv parameters file generated in step 1

15
docs/dev_database/common/index.rst Normal file
View File

@ -0,0 +1,15 @@
=====================
Common database files
=====================
This section contains a description of :term:`database <Database>` files
that are common for all Xilinx series 7 chip architectures.
.. toctree::
:maxdepth: 1
segbits
site_type
tile_type
ppips
mask

104
docs/dev_database/common/mask.rst Normal file
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 an additional ``mask_<tile>.<bus_name>.db``
related to that bus.
For 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 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 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.
Example
-------
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 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 an 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>`.

66
docs/dev_database/common/ppips.rst Normal file
View File

@ -0,0 +1,66 @@
===========
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 appear as standard
:term:`PIPs <PIP>` in the Vivado tool, but they do not have actual configuration
bit pattern in segbits files (they are not configurable).
The *ppips files* contains the information which `PIPs <PIP>` do not have
configuration bits, which allows the tools to not generat error in that situation.
On the other hand this information is used to indicate that the connection
between wires is always on.
Naming convention
-----------------
The naming scheme for the PPIPs files is the following::
ppips_<tile>.db
For 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, the naming convention is
similar to the one in the Vivado tool, which allows for quick identification of their role in the FPGA chip.

119
docs/dev_database/common/segbits.rst Normal file
View File

@ -0,0 +1,119 @@
=============
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.
Besides the features provided in this file that can be enabled,
the FPGA chip also has the default configuration. Due to that sometimes there
is no need for affecting the default configuration.
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.
Example 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 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, 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
--------------------------
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 of the *LSB LUT* for the *ALUT* in
the *SLICEL_X0* within a *CLBLL_L tile.*
Example
-------
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
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
<...>
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, 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
will be configured with pull-up.

122
docs/dev_database/common/site_type.rst Normal file
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
Example 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

270
docs/dev_database/common/tile_type.rst Normal file
View File

@ -0,0 +1,270 @@
===============
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,
its :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
Example 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": [
"<FAST_MIN>",
"<FAST_MAX>",
"<SLOW_MIN>",
"<SLOW_MAX>"
],
"in_cap": "<IN_CAPACITANCE>",
"res": "<RESISTANCE>"
},
"dst_wire": "<WIRE_NAME>",
"is_directional": "<BOOL>",
"is_pass_transistor": <BOOL>,
"is_pseudo": "0",
"src_to_dst": {
"delay": [
"<FAST_MIN>",
"<FAST_MAX>",
"<SLOW_MIN>",
"<SLOW_MAX>"
],
"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": [
"<FAST_MIN>",
"<FAST_MAX>",
"<SLOW_MIN>",
"<SLOW_MAX>"
],
"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 its 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`` - a four-element list, which contain information about the delay of pins.
First two elements are related to the *fast corner* of the technological process,
the second two elements to the *slow corner*. The first element of the pair
is the minimum value of the corner, the second describes the maximum value.
They are given in us (nanoseconds).
- ``in_cap`` - the input capacitance of the :term:`PIP <PIP>` in uF (microfarads).
- ``res`` - the resistance of the :term:`PIP <PIP>` in mΩ (miliohms).
- ``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 in uF (microfarads).
- ``delay`` - a four-element list, which contain information about the delay of pins.
First two elements are related to the *fast corner* of the technological process,
the second two elements to the *slow corner*. The first element of the pair
is the minimum value of the corner, the second describes the maximum value.
They are given in us (nanoseconds).
- ``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 in uF (microfarads)
- ``res`` - wire resistance in mΩ (miliohms).
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"
},
<...>
}

34
docs/dev_database/description.rst Normal file
View File

@ -0,0 +1,34 @@
===========
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 the `Architecture Definitions`_ project
to produce a bitstream for the chosen 7-Series FPGA chip.
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
Files common for whole 7-Series family:
- ``mask_*``
- ``ppips_*``
- ``segbits_*``
- ``site_type_*``
- ``tile_type_*``
- ``timings/*``
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:
- ``package_pins.csv``
- ``part.json``
- ``part.yaml``
- ``tileconn.json``
- ``tilegrid.json``

13
docs/dev_database/index.rst Normal file
View File

@ -0,0 +1,13 @@
========
Database
========
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
description
common/index
part_specific/index

14
docs/dev_database/part_specific/index.rst Normal file
View File

@ -0,0 +1,14 @@
============================
Part specific database files
============================
This section contains a description of :term:`database <Database>` files that
are part (chip) specific:
.. toctree::
: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"
}
}

80
docs/dev_database/part_specific/tileconn.rst Normal file
View File

@ -0,0 +1,80 @@
=============
tileconn file
=============
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.
File format
-----------
The file contains one large list::
[
{
"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
{
"grid_deltas": [
0,
1
],
"tile_types": [
"CLBLL_L",
"HCLK_CLB"
],
"wire_pairs": [
[
"CLBLL_LL_CIN",
"HCLK_CLB_COUT0_L"
],
[
"CLBLL_L_CIN",
"HCLK_CLB_COUT1_L"
]
]
}
Interpreted as:
- 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

140
docs/dev_database/part_specific/tilegrid.rst Normal file
View File

@ -0,0 +1,140 @@
=============
tilegrid file
=============
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.
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.
File format
-----------
The file consists of the entries describing every :term:`tile <Tile>` in
the FPGA chip. The file is of the form::
{
"<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
"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:
- :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 :term:`frame <Frame>` loads
- Located in :term:`clock region <Clock region>` ``X0Y2``
- Located at row 1, column 43
- Contains two :term:`sites <Site>`, both of which are SLICEL
- Is a ``CLBLL_L`` type :term:`tile <Tile>`
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.

144
docs/format/db.rst
View File

@ -1,144 +0,0 @@
.db Files
=========
Introduction
------------
This section documents how prjxray represents the bitstream database. The databases are plain text files, using either simple line-based syntax or JSON. The databases are located in `database/<device_class>/`. The `settings.sh` file contains some configurations used by the tools that generate the database, including the region of interest (ROI, see [[Glossary]]).
These ".db" files come in two common flavors:
* `segbits_*.db`_: encodes bitstream bits
* `mask_*.db`_: which bits are used by a segment? Probably needs to be converted to tile
Also note: .rdb (raw db) is a convention for a non-expanded .db file (see below)
Segment bit positions
---------------------
Bit positions within a segment are written using the following notation: A two digit decimal number followed by an underscore followed by a two digit decimal number. For example `26_47`.
The first number indicates the frame address relative to the base frame address for the segment and ranges from `00` to `35` for Atrix-7 CLB segments.
The second number indicates the bit position width.
.. warning:: FIXME: Expand this section. We've had a couple questions around this, probably good to get a complete description of this that we can point people too. This is probably a good place to talk about tile grid and how it applies to segbit.
segbits_*.db
------------
Tag files document the meaning of individual configuration bits or bit pattern. They contain one line for each pattern. The first word (sequence of non-whitespace characters) in that line is the *configuration tag*, the remaining words in the line is the list of bits for that pattern. A bit prefixed with a `!` marks a bit that must be cleared, a bit not prefixed with a `!` marks a bit that must be set.
No configuration tag may include the bit pattern for another tag as subset. If it does then this is an indicator that there is an incorrect entry in the database. Usually this either means that a tag has additional bits in their pattern that should not be there, or that `!<bit>` entries are missing for one or more tags.
These are created by segmatch to describe bitstream IP encoding.
Example lines:
* CLB.SLICE_X0.DFF.ZINI 31_58
* For feature CLB.SLICE_X0.DFF.ZINI
* Frame: 31
* Word: 58 // 32 = 1
* Mask: 1 << (58 % 32) = 0x04000000
* To set an actual bitstream location, you will need to adjust frame and word by their tile base addresses
* CLBLL_L.SLICEL_X0.AOUTMUX.A5Q !30_06 !30_08 !30_11 30_07
* A multi bit entry. Bit 30_06 should be cleared to use this feature
* INT_L.BYP_BOUNCE5.BYP_ALT5 always
* A pseudo pip: feaure always active => no bits required
* CLBLL_L.OH_NO.BAD.SOLVE <const0>
* Internal only
* Candidate bits exist, but they've only ever been set to 0
* CLBLL_L.OH_NO.BAD.SOLVE <const1>
* Internal only
* Candidate bits exist, but they've only ever been set to 1
* INT.FAN_ALT4.SS2END0 <m1 2> 18_09 25_08
* Internal only
* segmatch -m (min tag value occurrences) was given, but occurrences are below this threshold
* ie INT.FAN_ALT4.SS2END0 occcured twice, but this is below the acceptable level (say 5)
* INT.FAN_ALT4.SS2END0 <M 6 8> 18_09 25_08
* Internal only
* segmatch -M (min tag occurrences) was given, but total occurrences are below this threshold
* First value (6) is present=1, second value (8) is present=0
* Say -M 15, but there are 6 + 8 = 14 samples, below the acceptable threshold
Related tools:
* segmatch: solves symbolic constraints on a bitstream to produce symbol bitmasks
* dbfixup.py: internal tool that expands multi-bit encodings (ex: one hot) into groups. For example:
* .rdb file with one hot: BRAM.RAMB18_Y1.WRITE_WIDTH_A_18 27_267
* .db: file expanded: BRAM.RAMB18_Y1.WRITE_WIDTH_A_18 !27_268 !27_269 27_267
* parsedb.py: valides that a database is fully and consistently solved
* Optionally outputs to canonical form
* Ex: complains if const0 entries exist
* Ex: complains if symbols are duplicated (such as after a mergedb after rename)
* mergedb.sh: adds new bit entries to an existing db
* Ex: CLB is solved by first solving LUT bits, and then solving FF bits
Interconnect :term:`PIP <pip>` Tags
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Tags for interconnect :term:`PIPs <pip>` are stored in the `segbits_int_l.db` and `segbits_int_r.db` database files.
Tags that enable interconnect :term:`PIPs <pip>` have the following syntax: `<tile_type>.<destination_wire>.<source_wire>`.
The `<tile_type>` may be `INT_L` or `INT_R`. The destination and source wires are wire names in that tile type. For example, consider the following entry in `segbits_int_l.db`: `INT_L.NL1BEG1.NN6END2 07_32 12_33`
.. warning:: FIXME: This is probably a good place to reference tileconn as the documentation that explains how wires are connected outside of switchboxes (which is what pips document).
This means that the bits `07_32` and `12_33` must be set in the segment to drive the value from the wire `NN6END2` to the wire `NL1BEG1`.
CLB Configurations Tags
^^^^^^^^^^^^^^^^^^^^^^^
Tags for CLB tiles use a dot-separated hierarchy for their tag names. For example the tag `CLBLL_L.SLICEL_X0.ALUT.INIT[00]` documents the bit position of the LSB LUT init bit for the ALUT for the slice with even X coordinate within a `CLBLL_L` tile. (There are 4 LUTs in a slice: ALUT, BLUT, CLUT, and DLUT. And there are two slices in a CLB tile: One with an even X coordinate using the `SLICEL_X0` namespace for tags, and one with an odd X coordinate using the `SLICEL_X1` namespace for tags.)
ppips_*.db
----------
Pseudo :term:`PIPs <pip>` are :term:`PIPs <pip>` in the Vivado tool, but do not have actual bit pattern. The `ppips_*.db` files contain information on pseudo-:term:`PIPs <pip>`. Those files contain one entry per pseudo-PIP, each with one of the following three tags: `always`, `default` or `hint`. The tag `always` is used for pseudo-:term:`PIPs <pip>` that are actually always-on, i.e. that are permanent connections between two wires. The tag `default` is used for pseudo-:term:`PIPs <pip>` that represent the default behavior if no other driver has been configured for the destination net (all `default` pseudo-:term:`PIPs <pip>` connect to the `VCC_WIRE` net). And the tag `hint` is used for :term:`PIPs <pip>` 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.
mask_*.db
---------
These are just simple bit lists
Example line: bit 01_256
See previous section for number meaning
For each segment type there is a mask file `mask_<seg_type>.db` that contains one line for each bit that has been observed being set in any of the example designs generated during generation of the database. The lines simply contain the keyword `bit` followed by the bit position. This database is used to identify unused bits in the configuration segments.
.bits example
-------------
Say entry is: bit_0002050b_002_05
2 step process:
* Decode which segment
* Decode which bit within that segment
We have:
* Frame address 0x0002050b (hex)
* Word #: 2 (decimal, 0-99)
* Bit #: 5 (decimal, 0-31)
The CLB tile and the associated interconnect switchbox tile are configured together as a segment. However, configuration data is grouped by segment column rather than tile column. First, note this segment consists of 36 frames. Second, note there are 100 32 bit words per frame (+ 1 for checksum => 101 actual). Each segment takes 2 of those words meaning 50 segments (ie 50 CLB tiles + 50 interconnect tiles) are effected per frame. This means that the smallest unit that can be fully configured is a group of 50 CLB tile + switchbox tile segments taking 4 * 36 * 101 = 14544 bytes. Finally, note segment columns are aligned to 0x80 addresses (which easily fits the 36 required frames).
tilegrid.json defines addresses more precisely. Taking 0x0002050b, the frame base address is 0x0002050b & 0xFFFFFF80 => 0x00020500. The frame offset is 0x0002050b & 0x7F => 0x0B => 11.
So in summary:
* Frame base address: 0x00020500
* Frame offset: 0x0B (11)
* Frame word #: 2
* Frame word bit #: 5
So, with this in mind, we have frame base address 0x00020500 and word # 2. This maps to tilegrid.json entry SEG_CLBLL_L_X12Y101 (has "baseaddr": ["0x00020600", 2]). This also yields "type": "clbll_l" meaning we are configuring a CLBLL_L.
.. warning:: FIXME: This example is out of date with the new tilegrid format, should update it.
Looking at segbits_clbll_l.db, we need to look up the bit at segment column 11, offset at bit 5. However, this is not present, so we fall back to segbits_int_l.db. This yields a few entries related to EL1BEG (ex: INT_L.EL1BEG_N3.EL1END0 11_05 13_05).

154
docs/format/tile.rst
View File

@ -1,154 +0,0 @@
.json Files
===========
Introduction
------------
This section documents how prjxray represents FPGA fabric. Its primarily composed of two files:
* tilegrid.json: list of tiles and how they appear in the bitstream
* tileconn.json: how tiles are connected together
General notes:
* prjxray created names are generally lowercase, while Vivado created names are generally uppercase
* _l and _r entries are generally identical, but probably represent different physical IP block layouts
tilegrid.json
-------------
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.
tiles
#####
Each entry has the following fields:
* 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
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"
}
Interpreted as:
* 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
tileconn.json
-------------
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.
.. 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:
* 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
Sample entry:
.. code-block:: javascript
{
"grid_deltas": [
0,
1
],
"tile_types": [
"CLBLL_L",
"HCLK_CLB"
],
"wire_pairs": [
[
"CLBLL_LL_CIN",
"HCLK_CLB_COUT0_L"
],
[
"CLBLL_L_CIN",
"HCLK_CLB_COUT1_L"
]
]
}
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
* A global clock tile is feeding into slice carry chain inputs

6
docs/getting.rst Normal file
View File

@ -0,0 +1,6 @@
===============
Getting Started
===============
.. toctree::
db_dev_process/readme

45
docs/index.rst
View File

@ -1,10 +1,6 @@
.. Project X-Ray documentation master file, created by
sphinx-quickstart on Mon Feb 5 11:04:37 2018.
You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive.
Welcome to Project X-Ray
=========================================
=============
Project X-Ray
=============
`Project X-Ray`_ documents the `Xilinx`_ 7-Series FPGA architecture to enable
development of open-source tools. Our goal is to provide sufficient information
@ -15,31 +11,30 @@ to develop a free and open Verilog to bitstream toolchain for these devices.
.. toctree::
:maxdepth: 2
:caption: Xilinx 7-series Architecture
:caption: Introduction
architecture/overview
architecture/configuration
architecture/bitstream_format
architecture/interconnect
architecture/dram_configuration
architecture/glossary
architecture/reference
architecture/code_of_conduct
architecture/updating_the_docs
introduction
.. toctree::
:maxdepth: 2
:caption: Getting Started
getting
.. toctree::
:maxdepth: 2
:caption: Xilinx 7-Series Architecture
architecture/index
.. toctree::
:maxdepth: 2
:caption: Database Development Process
db_dev_process/readme
db_dev_process/contributing
db_dev_process/fuzzers/index
db_dev_process/minitests/index
db_dev_process/parts
db_dev_process/index
.. toctree::
:maxdepth: 2
:caption: Output File Formats
:caption: Output Formats
format/db
format/tile
dev_database/index

67
docs/introduction.rst Normal file
View File

@ -0,0 +1,67 @@
============
Introduction
============
`Project X-Ray`_ documents the `Xilinx`_ 7-Series FPGA architecture to enable
the development of open-source tools. Our goal is to provide sufficient information
to develop a free and open Verilog to bitstream toolchain for these devices.
The project is a part of SymbiFlow Toolchain. `SymbiFlow`_ uses the obtained
information about the chip in `Architecture Definitions`_ project, which
allows for creating bitstreams for many architectures including 7-Series devices.
Collected information
---------------------
To allow the usage of Xilinx FPGAs in SymbiFlow toolchain we collect some
important data about the Xilinx chips. The needed information includes:
- Architecture description:
* chip internals
* timings
- Bitstream format:
* metadata (i.e. header, crc)
* configuration bits
Final results are stored in the database which is further used by the
`Architecture Definitions`_ project. The whole database is described in
the dedicated :doc:`chapter <dev_database/index>`.
Methodology
-----------
The most important element of the project are fuzzers - scripts responsible
for obtaining information about the chips. Their name comes from the fact that
they use a similar idea to `Fuzz testing`_. Firstly, they generate a huge
amount of designs in which the examined chip property is either enabled or
disabled. By comparing the differences in the final bitstream obtained
from vendor tools, we can detect relations between bits in the bitstream and
provided functionalities.
However, some of the fuzzers works differently, i.e. they just creating
the database structure, the whole idea is similar and rely on the output produced
by the vendor tools.
All fuzzers are described in the dedicated :doc:`chapter <db_dev_process/fuzzers/index>`.
.. _Fuzz testing: https://en.wikipedia.org/wiki/Fuzzing
Important Parts
---------------
The important parts of the `Project X-Ray` are:
- *minitests* - designs that can be viewed by a human in Vivado to better
understand how to generate more useful designs.
- *experiments* - similar to *minitests* except for the fact that they are only
useful for a short time.
- *tools & libs* - they convert the resulting bitstreams into various formats.
- *utils* - tools that are used but still require some testing
.. _Project X-Ray: https://github.com/SymbiFlow/prjxray
.. _Xilinx: http://www.xilinx.com/
.. _SymbiFlow: https://symbiflow.readthedocs.io/
.. _Architecture Definitions: https://github.com/SymbiFlow/symbiflow-arch-defs