From 1b296ea876677e62ebb2642e80f63ee7951e35ae Mon Sep 17 00:00:00 2001 From: Robert Winkler Date: Mon, 2 Mar 2020 14:05:09 +0100 Subject: [PATCH 1/7] New structure of project documentation Signed-off-by: Robert Winkler --- docs/architecture/index.rst | 16 +++++++++ docs/db_dev_process/index.rst | 13 +++++++ docs/format/index.rst | 8 +++++ docs/getting.rst | 6 ++++ docs/index.rst | 45 +++++++++++------------ docs/introduction.rst | 67 +++++++++++++++++++++++++++++++++++ 6 files changed, 130 insertions(+), 25 deletions(-) create mode 100644 docs/architecture/index.rst create mode 100644 docs/db_dev_process/index.rst create mode 100644 docs/format/index.rst create mode 100644 docs/getting.rst create mode 100644 docs/introduction.rst diff --git a/docs/architecture/index.rst b/docs/architecture/index.rst new file mode 100644 index 00000000..9701bdf0 --- /dev/null +++ b/docs/architecture/index.rst @@ -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 diff --git a/docs/db_dev_process/index.rst b/docs/db_dev_process/index.rst new file mode 100644 index 00000000..9fab0542 --- /dev/null +++ b/docs/db_dev_process/index.rst @@ -0,0 +1,13 @@ +============================ +Database Development Process +============================ + +.. toctree:: + :maxdepth: 1 + + readme + contributing + fuzzers/index + minitests/index + parts + diff --git a/docs/format/index.rst b/docs/format/index.rst new file mode 100644 index 00000000..6f1fd211 --- /dev/null +++ b/docs/format/index.rst @@ -0,0 +1,8 @@ +============ +Output Files +============ + +.. toctree:: + + db + tile.rst diff --git a/docs/getting.rst b/docs/getting.rst new file mode 100644 index 00000000..0f7848de --- /dev/null +++ b/docs/getting.rst @@ -0,0 +1,6 @@ +=============== +Getting Started +=============== + +.. toctree:: + db_dev_process/readme diff --git a/docs/index.rst b/docs/index.rst index a933d114..b6654438 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -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 + format/index diff --git a/docs/introduction.rst b/docs/introduction.rst new file mode 100644 index 00000000..88c5b026 --- /dev/null +++ b/docs/introduction.rst @@ -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 `. + +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 `. + +.. _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 From e8ff146443057dcdc9762d244cdc02b55bfdfbcd Mon Sep 17 00:00:00 2001 From: Robert Winkler Date: Mon, 2 Mar 2020 16:57:42 +0100 Subject: [PATCH 2/7] 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 --- docs/dev_database/common/index.rst | 15 ++ docs/dev_database/common/mask.rst | 104 ++++++++ docs/dev_database/common/ppips.rst | 62 +++++ docs/dev_database/common/segbits.rst | 117 +++++++++ docs/dev_database/common/site_type.rst | 122 +++++++++ docs/dev_database/common/tile_type.rst | 259 +++++++++++++++++++ docs/dev_database/description.rst | 36 +++ docs/dev_database/index.rst | 13 + docs/dev_database/part_specific/index.rst | 12 + docs/dev_database/part_specific/tileconn.rst | 50 ++++ docs/dev_database/part_specific/tilegrid.rst | 101 ++++++++ docs/format/db.rst | 144 ----------- docs/format/index.rst | 8 - docs/format/tile.rst | 154 ----------- docs/index.rst | 2 +- docs/introduction.rst | 2 +- 16 files changed, 893 insertions(+), 308 deletions(-) create mode 100644 docs/dev_database/common/index.rst create mode 100644 docs/dev_database/common/mask.rst create mode 100644 docs/dev_database/common/ppips.rst create mode 100644 docs/dev_database/common/segbits.rst create mode 100644 docs/dev_database/common/site_type.rst create mode 100644 docs/dev_database/common/tile_type.rst create mode 100644 docs/dev_database/description.rst create mode 100644 docs/dev_database/index.rst create mode 100644 docs/dev_database/part_specific/index.rst create mode 100644 docs/dev_database/part_specific/tileconn.rst create mode 100644 docs/dev_database/part_specific/tilegrid.rst delete mode 100644 docs/format/db.rst delete mode 100644 docs/format/index.rst delete mode 100644 docs/format/tile.rst diff --git a/docs/dev_database/common/index.rst b/docs/dev_database/common/index.rst new file mode 100644 index 00000000..85454563 --- /dev/null +++ b/docs/dev_database/common/index.rst @@ -0,0 +1,15 @@ +============================= +Files Common for Architecture +============================= + +This section contains a description of :term:`database ` files +that are common for a whole chip architecture. + +.. toctree:: + :maxdepth: 2 + + mask + ppips + segbits + site_type + tile_type diff --git a/docs/dev_database/common/mask.rst b/docs/dev_database/common/mask.rst new file mode 100644 index 00000000..497b479b --- /dev/null +++ b/docs/dev_database/common/mask.rst @@ -0,0 +1,104 @@ +========== +mask files +========== + +The *mask files* are generated for every FPGA :term:`tile ` type. They store +the information, which bits in the bitstream can configure the given +:term:`tile ` type. + +Naming convention +----------------- + +The naming scheme for the mask files is the following:: + + mask_.db + +Note that auxiliary ``mask_.origin_info.db`` files +provide additional information about the :term:`fuzzer `, +which produced the :term:`database ` file. This file is optional. + +Every :term:`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 ` can also be +configured by another bus it has additional ``mask_..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 ` type. Each entry inside the file is of the form:: + + bit _ + +This means that the :term:`tile ` can be configured by bit located in the +:term:`frame ` at the address `` + ``, +at position `` + ``. Information about ```` +and ```` 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 `:: + + <...> + 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 ` can be +configured by the bit located in the :term:`frame ` at the address +`` + 0x01``, at position `` + 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 ```` can be found as a argument of the *"baseaddr"* key +and for *CLBLL_L_X2Y0* :term:`tile ` it is equal to ``0x00400100``. The ```` +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 ` address:: + + 0x00400100 + 0x01 = 0x00400101 + +Located at the bit position:: + + 0x0 + 0x2 = 0x2 + +More about the configuration process and the meaning of the :term:`frame ` +can be found in the :doc:`Configuration Section <../../architecture/configuration>`. diff --git a/docs/dev_database/common/ppips.rst b/docs/dev_database/common/ppips.rst new file mode 100644 index 00000000..e93dfa0a --- /dev/null +++ b/docs/dev_database/common/ppips.rst @@ -0,0 +1,62 @@ +=========== +ppips files +=========== + +The *ppips files* are generated for every FPGA :term:`tile ` type. +They store the information about the pseudo-PIPs, inside the tile. + +Programable Interconnect point (:term:`PIP `) is a connection inside the +:term:`tile ` that can be enabled or disabled. Pseudo PIPs appears as standard +:term:`PIPs ` 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_.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::: + + + +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 ```` 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. diff --git a/docs/dev_database/common/segbits.rst b/docs/dev_database/common/segbits.rst new file mode 100644 index 00000000..ebdf2a68 --- /dev/null +++ b/docs/dev_database/common/segbits.rst @@ -0,0 +1,117 @@ +============= +segbits files +============= + +The *segbits files* are generated for every FPGA :term:`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 `. +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_.db + +Note that auxiliary ``segbits_.origin_info.db`` files +provide additional information about the :term:`fuzzer `, which produced the +:term:`database ` file. This file is optional. + +Every :term:`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 ` can also be configured +by another bus, it has additional ``segbits_..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:: + + + +where: + + - ```` is of the form ``.`` + - ```` is the list of bits. Each bit is of the form + ``_``. 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 ```` names for interconnect :term:`PIPs ` are stored in the +``segbits_int_l.db`` and ``segbits_int_r.db`` database files. The features that +enable interconnect :term:`PIPs ` have the following syntax:: + + ... + +For example, consider the following entry in ``segbits_int_l.db``:: + + INT_L.NL1BEG1.NN6END2 07_32 12_33 + +CLBs +^^^^ +The ```` 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 `:: + + <...> + 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, ```` name is connected with its functionality. +In example, ``LIOB33.IOB_Y0.PULLTYPE.PULLUP`` means that in the LIOB33 +:term:`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. diff --git a/docs/dev_database/common/site_type.rst b/docs/dev_database/common/site_type.rst new file mode 100644 index 00000000..19f697bd --- /dev/null +++ b/docs/dev_database/common/site_type.rst @@ -0,0 +1,122 @@ +=============== +site_type files +=============== + +The *site_type files* are generated for every FPGA +:term:`site ` type. They store the information about the pins and +:term:`PIPs ` of the :term:`site `. + +Naming convention +----------------- + +The naming scheme for the :term:`site ` type files is the following:: + + site_type_.json + +Exemplary files: + + - ``site_type_IDELAYE2.json`` + - ``site_type_PLLE2_ADV.json`` + - ``site_type_SLICEL.json`` + +File format +----------- + +The :term:`site ` type files are JSON files with the following scheme:: + + { + "site_pins": { + "": { + "direction": "" + }, + <...> + }, + "site_pips": { + "": { + "from_pin": "", + "to_pin": "" + } + }, + "type": "" + } + +where: + + - ** - specifies the :term:`site ` pin name + - ** - specifies the :term:`site ` :term:`pip ` name + - ** - is a direction of a pin (either **IN** or **OUT**) + - ** - specifies the :term:`site ` type + + +The ``"site_pins"`` section describes the input pins of a :term:`site ` +and its directions. The ``"site_pips"`` describes the :term:`PIPs ` +inside the :term:`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 `. + +.. _Xilinx documentation: https://www.xilinx.com/support/documentation/user_guides/ug474_7Series_CLB.pdf#page=20 diff --git a/docs/dev_database/common/tile_type.rst b/docs/dev_database/common/tile_type.rst new file mode 100644 index 00000000..69d74f7e --- /dev/null +++ b/docs/dev_database/common/tile_type.rst @@ -0,0 +1,259 @@ +=============== +tile_type files +=============== + +The *tile_type files* are generated for every FPGA :term:`tile ` +type. They store the information about the :term:`tile ` configuration, +it's :term:`PIPs `, :term:`sites `, wires and their properties. + +Naming convention +----------------- + +The naming scheme for the segbits files is the following:: + + tile_type_.json + +Exemplary files: + + - ``tile_type_INT_L.json`` + - ``tile_type_BRAM_L.json`` + - ``tile_type_HCLK_CLB.json`` + +File format +----------- + +The :term:`tile ` type files are JSON files with the following shape:: + + { + "pips": { + "": { + "can_invert":' "", + "dst_to_src": { + "delay": [ + "", + "", + "", + "" + ], + "in_cap": "", + "res": "" + }, + "dst_wire": "", + "is_directional": "", + "is_pass_transistor": , + "is_pseudo": "0", + "src_to_dst": { + "delay": [ + "", + "", + "", + "" + ], + "in_cap": "", + "res": "" + }, + "src_wire": "" + }, + }, + "sites": [ + { + "name": "", + "prefix": "", + "site_pins": { + "": { + "cap": "", + "delay": [ + "", + "", + "", + "" + ], + "wire": "" + }, + <...> + ], + "tile_type": "", + "wires": { + "": { + "cap": "", + "res": "" + }, + <...> + }, + } + +"pips" section +^^^^^^^^^^^^^^ + +The "pips" section describes all :term:`PIPs ` in the :term:`tile `. +Every :term:`PIP ` has it's 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 ` 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 ` + - ``"res"`` - the resistance of the :term:`PIP `. + +- ``dst_wire`` - the destination wire name + +- ``is_directional`` - contains the information whether :term:`PIP ` is directional. + +- ``is_pass_transisstor`` - contains the information whether :term:`PIP ` acts + as a pass transistor + +- ``is_pseudo`` - contains the information whether :term:`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 ` in the :term:`tile `. +Every :term:`site ` may be characterized by the following attributes: + +- ``"name"`` - location in the :term:`tile ` grid + +- ``"prefix"`` - the type of the :term:`site ` + +- ``"site_pins"`` - describes the pins that belong to the :term:`site `. + Every pin has it's 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 `. +Every wire has it's 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" + }, + <...> + } diff --git a/docs/dev_database/description.rst b/docs/dev_database/description.rst new file mode 100644 index 00000000..e4c5ac6d --- /dev/null +++ b/docs/dev_database/description.rst @@ -0,0 +1,36 @@ +=========== +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 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//``. 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. + +.. _Architecture Definitions: https://github.com/SymbiFlow/symbiflow-arch-defs + +Files common for whole 7-Series family: + + - ``mask_*`` + - ``ppips_*`` + - ``segbits_*`` + - ``site_type_*`` + - ``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*. + +Files specific for the particular FPGA part: + + - ``package_pins.csv`` + - ``part.json`` + - ``part.yaml`` + - ``tileconn.json`` + - ``tilegrid.json`` diff --git a/docs/dev_database/index.rst b/docs/dev_database/index.rst new file mode 100644 index 00000000..5d1d63ee --- /dev/null +++ b/docs/dev_database/index.rst @@ -0,0 +1,13 @@ +======== +Database +======== + +This section documents how prjxray represents the bitstream database. +The databases are plain text files, using either simple line-based syntax or JSON. + +.. toctree:: + :maxdepth: 2 + + description + common/index + part_specific/index diff --git a/docs/dev_database/part_specific/index.rst b/docs/dev_database/part_specific/index.rst new file mode 100644 index 00000000..2d2c6efe --- /dev/null +++ b/docs/dev_database/part_specific/index.rst @@ -0,0 +1,12 @@ +=================== +Part Specific Files +=================== + +This section contains a description of :term:`database ` files that +are part (chip) specific: + +.. toctree:: + :maxdepth: 2 + + tilegrid + tileconn diff --git a/docs/dev_database/part_specific/tileconn.rst b/docs/dev_database/part_specific/tileconn.rst new file mode 100644 index 00000000..f597c949 --- /dev/null +++ b/docs/dev_database/part_specific/tileconn.rst @@ -0,0 +1,50 @@ +============= +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. + +.. 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 diff --git a/docs/dev_database/part_specific/tilegrid.rst b/docs/dev_database/part_specific/tilegrid.rst new file mode 100644 index 00000000..8ebdd920 --- /dev/null +++ b/docs/dev_database/part_specific/tilegrid.rst @@ -0,0 +1,101 @@ +============= +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. + +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 diff --git a/docs/format/db.rst b/docs/format/db.rst deleted file mode 100644 index 4b43c9ec..00000000 --- a/docs/format/db.rst +++ /dev/null @@ -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//`. 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 `!` 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 - * Internal only - * Candidate bits exist, but they've only ever been set to 0 - * CLBLL_L.OH_NO.BAD.SOLVE - * Internal only - * Candidate bits exist, but they've only ever been set to 1 - * INT.FAN_ALT4.SS2END0 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 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 ` Tags -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Tags for interconnect :term:`PIPs ` are stored in the `segbits_int_l.db` and `segbits_int_r.db` database files. - -Tags that enable interconnect :term:`PIPs ` have the following syntax: `..`. - -The `` 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 ` are :term:`PIPs ` in the Vivado tool, but do not have actual bit pattern. The `ppips_*.db` files contain information on pseudo-:term:`PIPs `. 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 ` that are actually always-on, i.e. that are permanent connections between two wires. The tag `default` is used for pseudo-:term:`PIPs ` that represent the default behavior if no other driver has been configured for the destination net (all `default` pseudo-:term:`PIPs ` connect to the `VCC_WIRE` net). And the tag `hint` is used for :term:`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. - -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_.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). - - diff --git a/docs/format/index.rst b/docs/format/index.rst deleted file mode 100644 index 6f1fd211..00000000 --- a/docs/format/index.rst +++ /dev/null @@ -1,8 +0,0 @@ -============ -Output Files -============ - -.. toctree:: - - db - tile.rst diff --git a/docs/format/tile.rst b/docs/format/tile.rst deleted file mode 100644 index 8ac196e7..00000000 --- a/docs/format/tile.rst +++ /dev/null @@ -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 - diff --git a/docs/index.rst b/docs/index.rst index b6654438..192e93bb 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -37,4 +37,4 @@ to develop a free and open Verilog to bitstream toolchain for these devices. :maxdepth: 2 :caption: Output Formats - format/index + dev_database/index diff --git a/docs/introduction.rst b/docs/introduction.rst index 88c5b026..c2b26fcf 100644 --- a/docs/introduction.rst +++ b/docs/introduction.rst @@ -28,7 +28,7 @@ important data about the Xilinx chips. The needed information includes: 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 `. +the dedicated :doc:`chapter `. Methodology ----------- From 39813be4cb94a9806a47352b7a0a03fe5fbe4e5e Mon Sep 17 00:00:00 2001 From: Tomasz Michalak Date: Tue, 10 Mar 2020 14:15:01 +0100 Subject: [PATCH 3/7] Add small fixes to the database documentation Signed-off-by: Tomasz Michalak --- docs/dev_database/common/index.rst | 12 +- docs/dev_database/common/mask.rst | 20 ++-- docs/dev_database/common/ppips.rst | 11 +- docs/dev_database/common/segbits.rst | 20 ++-- docs/dev_database/common/site_type.rst | 2 +- docs/dev_database/common/tile_type.rst | 44 +++---- docs/dev_database/description.rst | 16 ++- docs/dev_database/index.rst | 4 +- docs/dev_database/part_specific/index.rst | 6 +- docs/dev_database/part_specific/tileconn.rst | 6 +- docs/dev_database/part_specific/tilegrid.rst | 115 ++++++------------- 11 files changed, 106 insertions(+), 150 deletions(-) diff --git a/docs/dev_database/common/index.rst b/docs/dev_database/common/index.rst index 85454563..221c253d 100644 --- a/docs/dev_database/common/index.rst +++ b/docs/dev_database/common/index.rst @@ -1,15 +1,15 @@ -============================= -Files Common for Architecture -============================= +===================== +Common database files +===================== This section contains a description of :term:`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 diff --git a/docs/dev_database/common/mask.rst b/docs/dev_database/common/mask.rst index 497b479b..47743fc5 100644 --- a/docs/dev_database/common/mask.rst +++ b/docs/dev_database/common/mask.rst @@ -2,8 +2,8 @@ mask files ========== -The *mask files* are generated for every FPGA :term:`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 ` type. +They store the information which bits in the bitstream can configure the given :term:`tile ` type. Naming convention @@ -19,11 +19,11 @@ which produced the :term:`database ` file. This file is optional. Every :term:`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 ` can also be -configured by another bus it has additional ``mask_..db`` +The default bus is called ``CLB_IO_CLK``. +If the :term:`tile ` can also be configured by another bus, it has an additional ``mask_..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 ` type. Each entry inside the file is of the form:: bit _ -This means that the :term:`tile ` can be configured by bit located in the +This means that the :term:`tile ` can be configured by a bit located in the :term:`frame ` at the address `` + ``, at position `` + ``. Information about ```` and ```` can be taken from part specific ``tilegrid.json`` file. @@ -45,13 +45,13 @@ and ```` 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 `:: <...> 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 ` at the address `` + 0x01``, at position `` + 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": { diff --git a/docs/dev_database/common/ppips.rst b/docs/dev_database/common/ppips.rst index e93dfa0a..4d51d929 100644 --- a/docs/dev_database/common/ppips.rst +++ b/docs/dev_database/common/ppips.rst @@ -5,8 +5,8 @@ ppips files The *ppips files* are generated for every FPGA :term:`tile ` type. They store the information about the pseudo-PIPs, inside the tile. -Programable Interconnect point (:term:`PIP `) is a connection inside the -:term:`tile ` that can be enabled or disabled. Pseudo PIPs appears as standard +Programable Interconnect Point (:term:`PIP `) is a connection inside the +:term:`tile ` that can be enabled or disabled. Pseudo PIPs appear as standard :term:`PIPs ` 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_.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 ```` 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 ```` 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. diff --git a/docs/dev_database/common/segbits.rst b/docs/dev_database/common/segbits.rst index ebdf2a68..8037868c 100644 --- a/docs/dev_database/common/segbits.rst +++ b/docs/dev_database/common/segbits.rst @@ -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 `:: +Below there is a part of the ``segbits_liob33_l.db`` file for the *artix7* +architecture. The file describes the *CLBLL* :term:`tile `:: <...> LIOB33.IOB_Y0.IBUFDISABLE.I 38_82 @@ -102,15 +100,15 @@ architecture. The file describes *CLBLL* :term:`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, ```` name is connected with its functionality. -In example, ``LIOB33.IOB_Y0.PULLTYPE.PULLUP`` means that in the LIOB33 +Generally, the ```` name is linked with its functionality. +For example, ``LIOB33.IOB_Y0.PULLTYPE.PULLUP`` means that in the LIOB33 :term:`tile `, in IOB_Y0 site the *pull type* will be set to *PULLUP*. This simply means that all pins belonging to this particular IOB diff --git a/docs/dev_database/common/site_type.rst b/docs/dev_database/common/site_type.rst index 19f697bd..103c3120 100644 --- a/docs/dev_database/common/site_type.rst +++ b/docs/dev_database/common/site_type.rst @@ -13,7 +13,7 @@ The naming scheme for the :term:`site ` type files is the following:: site_type_.json -Exemplary files: +Example files: - ``site_type_IDELAYE2.json`` - ``site_type_PLLE2_ADV.json`` diff --git a/docs/dev_database/common/tile_type.rst b/docs/dev_database/common/tile_type.rst index 69d74f7e..c609501f 100644 --- a/docs/dev_database/common/tile_type.rst +++ b/docs/dev_database/common/tile_type.rst @@ -4,7 +4,7 @@ tile_type files The *tile_type files* are generated for every FPGA :term:`tile ` type. They store the information about the :term:`tile ` configuration, -it's :term:`PIPs `, :term:`sites `, wires and their properties. +its :term:`PIPs `, :term:`sites `, wires and their properties. Naming convention ----------------- @@ -13,7 +13,7 @@ The naming scheme for the segbits files is the following:: tile_type_.json -Exemplary files: +Example files: - ``tile_type_INT_L.json`` - ``tile_type_BRAM_L.json`` @@ -86,18 +86,18 @@ The :term:`tile ` type files are JSON files with the following shape:: ^^^^^^^^^^^^^^ The "pips" section describes all :term:`PIPs ` in the :term:`tile `. -Every :term:`PIP ` has it's name - ``""`` and may be +Every :term:`PIP ` has its 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 ` 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 ` - - ``"res"`` - the resistance of the :term:`PIP `. + - ``delay`` - four-element list, which contain information about the delays. + - ``in_cap`` - the input capacitance of the :term:`PIP ` + - ``res`` - the resistance of the :term:`PIP `. - ``dst_wire`` - the destination wire name @@ -118,37 +118,37 @@ characterized by the following attributes: The "sites" section describes all :term:`sites ` in the :term:`tile `. Every :term:`site ` may be characterized by the following attributes: -- ``"name"`` - location in the :term:`tile ` grid +- ``name`` - location in the :term:`tile ` grid -- ``"prefix"`` - the type of the :term:`site ` +- ``prefix`` - the type of the :term:`site ` -- ``"site_pins"`` - describes the pins that belong to the :term:`site `. - Every pin has it's name - ``""`` and may be described +- ``site_pins`` - describes the pins that belong to the :term:`site `. + Every pin has it's 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 `. -Every wire has it's name - ``""`` and may be characterized +Every wire has it's 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 diff --git a/docs/dev_database/description.rst b/docs/dev_database/description.rst index e4c5ac6d..55553bb0 100644 --- a/docs/dev_database/description.rst +++ b/docs/dev_database/description.rst @@ -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//``. 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//``. +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: diff --git a/docs/dev_database/index.rst b/docs/dev_database/index.rst index 5d1d63ee..5c75ab95 100644 --- a/docs/dev_database/index.rst +++ b/docs/dev_database/index.rst @@ -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 diff --git a/docs/dev_database/part_specific/index.rst b/docs/dev_database/part_specific/index.rst index 2d2c6efe..95b06d80 100644 --- a/docs/dev_database/part_specific/index.rst +++ b/docs/dev_database/part_specific/index.rst @@ -1,6 +1,6 @@ -=================== -Part Specific Files -=================== +============================ +Part specific database files +============================ This section contains a description of :term:`database ` files that are part (chip) specific: diff --git a/docs/dev_database/part_specific/tileconn.rst b/docs/dev_database/part_specific/tileconn.rst index f597c949..a0b54a59 100644 --- a/docs/dev_database/part_specific/tileconn.rst +++ b/docs/dev_database/part_specific/tileconn.rst @@ -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 diff --git a/docs/dev_database/part_specific/tilegrid.rst b/docs/dev_database/part_specific/tilegrid.rst index 8ebdd920..2cb7d8a7 100644 --- a/docs/dev_database/part_specific/tilegrid.rst +++ b/docs/dev_database/part_specific/tilegrid.rst @@ -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. + From 028aa6173c932ecc771dbabca5d2e1db9291170c Mon Sep 17 00:00:00 2001 From: Tomasz Michalak Date: Mon, 9 Mar 2020 14:07:47 +0100 Subject: [PATCH 4/7] Add dsp fuzzer creation description Signed-off-by: Tomasz Michalak --- docs/db_dev_process/fuzzers/index.rst | 5 +- docs/db_dev_process/index.rst | 1 + docs/db_dev_process/new_fuzzer.rst | 164 ++++++++++++++++++++++++++ 3 files changed, 168 insertions(+), 2 deletions(-) create mode 100644 docs/db_dev_process/new_fuzzer.rst diff --git a/docs/db_dev_process/fuzzers/index.rst b/docs/db_dev_process/fuzzers/index.rst index fe6f8599..65a4183c 100644 --- a/docs/db_dev_process/fuzzers/index.rst +++ b/docs/db_dev_process/fuzzers/index.rst @@ -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. diff --git a/docs/db_dev_process/index.rst b/docs/db_dev_process/index.rst index 9fab0542..c66b5d45 100644 --- a/docs/db_dev_process/index.rst +++ b/docs/db_dev_process/index.rst @@ -7,6 +7,7 @@ Database Development Process readme contributing + new_fuzzer fuzzers/index minitests/index parts diff --git a/docs/db_dev_process/new_fuzzer.rst b/docs/db_dev_process/new_fuzzer.rst new file mode 100644 index 00000000..1e389726 --- /dev/null +++ b/docs/db_dev_process/new_fuzzer.rst @@ -0,0 +1,164 @@ +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 `_ 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`` dsd a + + #. 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. +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. + +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 From e851ca7bc742090473d61d2d9964ba4ac28b18e5 Mon Sep 17 00:00:00 2001 From: Tomasz Michalak Date: Thu, 12 Mar 2020 14:39:34 +0100 Subject: [PATCH 5/7] Apply review comments to new fuzzer chapter Signed-off-by: Tomasz Michalak --- docs/db_dev_process/new_fuzzer.rst | 16 +++++++--------- 1 file changed, 7 insertions(+), 9 deletions(-) diff --git a/docs/db_dev_process/new_fuzzer.rst b/docs/db_dev_process/new_fuzzer.rst index 1e389726..7953ddd4 100644 --- a/docs/db_dev_process/new_fuzzer.rst +++ b/docs/db_dev_process/new_fuzzer.rst @@ -21,9 +21,9 @@ 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 +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. +2)) => 8 bitstreams (specimens) to solve all of them. Calculating the base address ++++++++++++++++++++++++++++ @@ -86,9 +86,9 @@ Calculating the base address #. Return to the main tilegrid directory -#. Edit ``tilegrid/add_tdb.py`` dsd a +#. 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)`` + #. 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 @@ -102,10 +102,8 @@ 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. -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. - -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. +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 @@ -148,7 +146,7 @@ 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 + 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 From 368fba8316f014e5cc5a2a5b687f2d4df7f84c48 Mon Sep 17 00:00:00 2001 From: Robert Winkler Date: Fri, 20 Mar 2020 18:01:32 +0100 Subject: [PATCH 6/7] Apply review comments to database description Signed-off-by: Robert Winkler --- docs/dev_database/common/index.rst | 4 +- docs/dev_database/common/mask.rst | 30 +++++----- docs/dev_database/common/ppips.rst | 15 +++-- docs/dev_database/common/segbits.rst | 26 ++++---- docs/dev_database/common/site_type.rst | 22 +++---- docs/dev_database/common/tile_type.rst | 83 +++++++++++++++----------- 6 files changed, 100 insertions(+), 80 deletions(-) diff --git a/docs/dev_database/common/index.rst b/docs/dev_database/common/index.rst index 221c253d..939999e8 100644 --- a/docs/dev_database/common/index.rst +++ b/docs/dev_database/common/index.rst @@ -2,11 +2,11 @@ Common database files ===================== -This section contains a description of :term:`database ` files +This section contains a description of :term:`database ` files that are common for all Xilinx series 7 chip architectures. .. toctree:: - :maxdepth: 2 + :maxdepth: 1 segbits site_type diff --git a/docs/dev_database/common/mask.rst b/docs/dev_database/common/mask.rst index 47743fc5..92a74540 100644 --- a/docs/dev_database/common/mask.rst +++ b/docs/dev_database/common/mask.rst @@ -2,9 +2,9 @@ mask files ========== -The *mask files* are generated for every FPGA :term:`tile ` type. +The *mask files* are generated for every FPGA :term:`tile ` type. They store the information which bits in the bitstream can configure the given -:term:`tile ` type. +:term:`tile ` type. Naming convention ----------------- @@ -14,13 +14,13 @@ The naming scheme for the mask files is the following:: mask_.db Note that auxiliary ``mask_.origin_info.db`` files -provide additional information about the :term:`fuzzer `, -which produced the :term:`database ` file. This file is optional. +provide additional information about the :term:`fuzzer `, +which produced the :term:`database ` file. This file is optional. -Every :term:`tile ` is configured at least by one of three configurational +Every :term:`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 ` can also be configured by another bus, it has an additional ``mask_..db`` +If the :term:`tile ` can also be configured by another bus, it has an additional ``mask_..db`` related to that bus. For example: @@ -33,12 +33,12 @@ File format ----------- The file consists of records that describe the configuration bits for -the particular :term:`tile ` type. Each entry inside the file is of the form:: +the particular :term:`tile ` type. Each entry inside the file is of the form:: bit _ -This means that the :term:`tile ` can be configured by a bit located in the -:term:`frame ` at the address `` + ``, +This means that the :term:`tile ` can be configured by a bit located in the +:term:`frame ` at the address `` + ``, at position `` + ``. Information about ```` and ```` can be taken from part specific ``tilegrid.json`` file. @@ -46,7 +46,7 @@ Example ------- Below there is a part of artix7 ``mask_clbll_l.db`` file describing a FPGA *CLBLL* -:term:`tile `:: +:term:`tile `:: <...> bit 00_61 @@ -57,8 +57,8 @@ Below there is a part of artix7 ``mask_clbll_l.db`` file describing a FPGA *CLBL bit 01_02 <...> -The line ``bit 01_02`` means that the *CLBL_LL* :term:`tile ` can be -configured by the bit located in the :term:`frame ` at the address +The line ``bit 01_02`` means that the *CLBL_LL* :term:`tile ` can be +configured by the bit located in the :term:`frame ` at the address `` + 0x01``, at position `` + 0x2``. The ``tilegrid.json`` is a file specific to a given chip package. @@ -85,14 +85,14 @@ For *xc7a35tcpg236-1* we can find an exemplary *CLBLL_L* entry:: }, The ```` can be found as a argument of the *"baseaddr"* key -and for *CLBLL_L_X2Y0* :term:`tile ` it is equal to ``0x00400100``. The ```` +and for *CLBLL_L_X2Y0* :term:`tile ` it is equal to ``0x00400100``. The ```` 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 ` address:: +:term:`frame ` address:: 0x00400100 + 0x01 = 0x00400101 @@ -100,5 +100,5 @@ Located at the bit position:: 0x0 + 0x2 = 0x2 -More about the configuration process and the meaning of the :term:`frame ` +More about the configuration process and the meaning of the :term:`frame ` can be found in the :doc:`Configuration Section <../../architecture/configuration>`. diff --git a/docs/dev_database/common/ppips.rst b/docs/dev_database/common/ppips.rst index 4d51d929..567f9fd0 100644 --- a/docs/dev_database/common/ppips.rst +++ b/docs/dev_database/common/ppips.rst @@ -2,13 +2,18 @@ ppips files =========== -The *ppips files* are generated for every FPGA :term:`tile ` type. +The *ppips files* are generated for every FPGA :term:`tile ` type. They store the information about the pseudo-PIPs, inside the tile. -Programable Interconnect Point (:term:`PIP `) is a connection inside the -:term:`tile ` that can be enabled or disabled. Pseudo PIPs appear as standard -:term:`PIPs ` in the Vivado tool, but they do not have actual configuration -bit pattern (they are not configurable). +Programable Interconnect Point (:term:`PIP `) is a connection inside the +:term:`tile ` that can be enabled or disabled. Pseudo PIPs appear as standard +:term:`PIPs ` 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 ` 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 ----------------- diff --git a/docs/dev_database/common/segbits.rst b/docs/dev_database/common/segbits.rst index 8037868c..e8380da0 100644 --- a/docs/dev_database/common/segbits.rst +++ b/docs/dev_database/common/segbits.rst @@ -2,12 +2,16 @@ segbits files ============= -The *segbits files* are generated for every FPGA :term:`tile ` type. +The *segbits files* are generated for every FPGA :term:`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 `. +that are responsible for enabling different features inside the :term:`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 ----------------- @@ -16,17 +20,17 @@ The naming scheme for the segbits files is the following:: segbits_.db Note that auxiliary ``segbits_.origin_info.db`` files -provide additional information about the :term:`fuzzer `, which produced the -:term:`database ` file. This file is optional. +provide additional information about the :term:`fuzzer `, which produced the +:term:`database ` file. This file is optional. -Every :term:`tile ` is configured at least by one of three configurational buses +Every :term:`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 ` can also be configured +The default bus is called ``CLB_IO_CLK``. If the :term:`tile ` can also be configured by another bus, it has additional ``segbits_..db`` related to that bus. -Exemplary files: +Example files: - ``segbits_dsp_r.db`` - ``segbits_bram_l.db`` (configured with default ``CLB_IO_CLK`` bus) @@ -59,9 +63,9 @@ Feature naming conventions PIPs ^^^^ -The ```` names for interconnect :term:`PIPs ` are stored in the +The ```` names for interconnect :term:`PIPs ` are stored in the ``segbits_int_l.db`` and ``segbits_int_r.db`` database files. The features that -enable interconnect :term:`PIPs ` have the following syntax:: +enable interconnect :term:`PIPs ` have the following syntax:: ... @@ -84,7 +88,7 @@ Example ------- Below there is a part of the ``segbits_liob33_l.db`` file for the *artix7* -architecture. The file describes the *CLBLL* :term:`tile `:: +architecture. The file describes the *CLBLL* :term:`tile `:: <...> LIOB33.IOB_Y0.IBUFDISABLE.I 38_82 @@ -109,7 +113,7 @@ bit ``!38_92`` and setting bits ``38_94`` and ``39_93``. Generally, the ```` name is linked with its functionality. For example, ``LIOB33.IOB_Y0.PULLTYPE.PULLUP`` means that in the LIOB33 -:term:`tile `, +:term:`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. diff --git a/docs/dev_database/common/site_type.rst b/docs/dev_database/common/site_type.rst index 103c3120..7604b369 100644 --- a/docs/dev_database/common/site_type.rst +++ b/docs/dev_database/common/site_type.rst @@ -3,13 +3,13 @@ site_type files =============== The *site_type files* are generated for every FPGA -:term:`site ` type. They store the information about the pins and -:term:`PIPs ` of the :term:`site `. +:term:`site ` type. They store the information about the pins and +:term:`PIPs ` of the :term:`site `. Naming convention ----------------- -The naming scheme for the :term:`site ` type files is the following:: +The naming scheme for the :term:`site ` type files is the following:: site_type_.json @@ -22,7 +22,7 @@ Example files: File format ----------- -The :term:`site ` type files are JSON files with the following scheme:: +The :term:`site ` type files are JSON files with the following scheme:: { "site_pins": { @@ -42,15 +42,15 @@ The :term:`site ` type files are JSON files with the following scheme:: where: - - ** - specifies the :term:`site ` pin name - - ** - specifies the :term:`site ` :term:`pip ` name + - ** - specifies the :term:`site ` pin name + - ** - specifies the :term:`site ` :term:`pip ` name - ** - is a direction of a pin (either **IN** or **OUT**) - - ** - specifies the :term:`site ` type + - ** - specifies the :term:`site ` type -The ``"site_pins"`` section describes the input pins of a :term:`site ` -and its directions. The ``"site_pips"`` describes the :term:`PIPs ` -inside the :term:`site ` and which wires they can connect. +The ``"site_pins"`` section describes the input pins of a :term:`site ` +and its directions. The ``"site_pips"`` describes the :term:`PIPs ` +inside the :term:`site ` and which wires they can connect. Example ------- @@ -117,6 +117,6 @@ architecture:: "type": "SLICEL" } -Compare the description with the `Xilinx documentation`_ of that :term:`site `. +Compare the description with the `Xilinx documentation`_ of that :term:`site `. .. _Xilinx documentation: https://www.xilinx.com/support/documentation/user_guides/ug474_7Series_CLB.pdf#page=20 diff --git a/docs/dev_database/common/tile_type.rst b/docs/dev_database/common/tile_type.rst index c609501f..e904a455 100644 --- a/docs/dev_database/common/tile_type.rst +++ b/docs/dev_database/common/tile_type.rst @@ -2,9 +2,9 @@ tile_type files =============== -The *tile_type files* are generated for every FPGA :term:`tile ` -type. They store the information about the :term:`tile ` configuration, -its :term:`PIPs `, :term:`sites `, wires and their properties. +The *tile_type files* are generated for every FPGA :term:`tile ` +type. They store the information about the :term:`tile ` configuration, +its :term:`PIPs `, :term:`sites `, wires and their properties. Naming convention ----------------- @@ -22,7 +22,7 @@ Example files: File format ----------- -The :term:`tile ` type files are JSON files with the following shape:: +The :term:`tile ` type files are JSON files with the following shape:: { "pips": { @@ -30,10 +30,10 @@ The :term:`tile ` type files are JSON files with the following shape:: "can_invert":' "", "dst_to_src": { "delay": [ - "", - "", - "", - "" + "", + "", + "", + "" ], "in_cap": "", "res": "" @@ -44,10 +44,10 @@ The :term:`tile ` type files are JSON files with the following shape:: "is_pseudo": "0", "src_to_dst": { "delay": [ - "", - "", - "", - "" + "", + "", + "", + "" ], "in_cap": "", "res": "" @@ -63,10 +63,10 @@ The :term:`tile ` type files are JSON files with the following shape:: "": { "cap": "", "delay": [ - "", - "", - "", - "" + "", + "", + "", + "" ], "wire": "" }, @@ -85,28 +85,34 @@ The :term:`tile ` type files are JSON files with the following shape:: "pips" section ^^^^^^^^^^^^^^ -The "pips" section describes all :term:`PIPs ` in the :term:`tile `. -Every :term:`PIP ` has its name - ``""`` and may be +The "pips" section describes all :term:`PIPs ` in the :term:`tile `. +Every :term:`PIP ` has its 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 ` has an inverter on it's output or not. + It defines whether the :term:`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 ` - - ``res`` - the resistance of the :term:`PIP `. + - ``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 ` in uF (microfarads). + + - ``res`` - the resistance of the :term:`PIP ` in mΩ (miliohms). - ``dst_wire`` - the destination wire name -- ``is_directional`` - contains the information whether :term:`PIP ` is directional. +- ``is_directional`` - contains the information whether :term:`PIP ` is directional. -- ``is_pass_transisstor`` - contains the information whether :term:`PIP ` acts +- ``is_pass_transisstor`` - contains the information whether :term:`PIP ` acts as a pass transistor -- ``is_pseudo`` - contains the information whether :term:`PIP ` is a pseudo-PIP +- ``is_pseudo`` - contains the information whether :term:`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 @@ -115,19 +121,25 @@ characterized by the following attributes: "sites" section: ^^^^^^^^^^^^^^^^ -The "sites" section describes all :term:`sites ` in the :term:`tile `. -Every :term:`site ` may be characterized by the following attributes: +The "sites" section describes all :term:`sites ` in the :term:`tile `. +Every :term:`site ` may be characterized by the following attributes: -- ``name`` - location in the :term:`tile ` grid +- ``name`` - location in the :term:`tile ` grid -- ``prefix`` - the type of the :term:`site ` +- ``prefix`` - the type of the :term:`site ` -- ``site_pins`` - describes the pins that belong to the :term:`site `. +- ``site_pins`` - describes the pins that belong to the :term:`site `. Every pin has it's name - ```` and may be described by the following attributes: - - ``cap`` - pin capacitance - - ``delay`` - pin delay + - ``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 @@ -139,18 +151,17 @@ Every :term:`site ` may be characterized by the following attributes: "wires" section ^^^^^^^^^^^^^^^ -The "wires" section describes the wires located in the :term:`tile `. +The "wires" section describes the wires located in the :term:`tile `. Every wire has it's name - ```` and may be characterized by the following attributes: -- ``cap`` - wire capacitance -- ``res`` - wire resistance +- ``cap`` - wire capacitance in uF (microfarads) +- ``res`` - wire resistance in mΩ (miliohms). Other ^^^^^ - ``tile_type`` - indicates the type of the tile - Example ------- From 4e13706c004d3324ce9e2e30bf78335ad31966a5 Mon Sep 17 00:00:00 2001 From: Robert Winkler Date: Tue, 19 May 2020 13:47:39 +0200 Subject: [PATCH 7/7] 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 --- docs/dev_database/part_specific/index.rst | 6 +- .../part_specific/package_pins.rst | 30 ++++ docs/dev_database/part_specific/part.rst | 146 ++++++++++++++++++ docs/dev_database/part_specific/tileconn.rst | 46 +++++- docs/dev_database/part_specific/tilegrid.rst | 128 ++++++++++++--- 5 files changed, 321 insertions(+), 35 deletions(-) create mode 100644 docs/dev_database/part_specific/package_pins.rst create mode 100644 docs/dev_database/part_specific/part.rst diff --git a/docs/dev_database/part_specific/index.rst b/docs/dev_database/part_specific/index.rst index 95b06d80..7c3ae47a 100644 --- a/docs/dev_database/part_specific/index.rst +++ b/docs/dev_database/part_specific/index.rst @@ -2,11 +2,13 @@ Part specific database files ============================ -This section contains a description of :term:`database ` files that +This section contains a description of :term:`database ` files that are part (chip) specific: .. toctree:: - :maxdepth: 2 + :maxdepth: 1 tilegrid tileconn + part + package_pins diff --git a/docs/dev_database/part_specific/package_pins.rst b/docs/dev_database/part_specific/package_pins.rst new file mode 100644 index 00000000..0f14be09 --- /dev/null +++ b/docs/dev_database/part_specific/package_pins.rst @@ -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 ` to which the pin belongs +- ``tile`` - The :term:`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 ` in ``RIOB33_X43Y97`` :term:`tile ` +has ``IO_L1N_T0_AD4N_35`` function. diff --git a/docs/dev_database/part_specific/part.rst b/docs/dev_database/part_specific/part.rst new file mode 100644 index 00000000..856cc8ef --- /dev/null +++ b/docs/dev_database/part_specific/part.rst @@ -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 ` that +are available for the given configurational :term:`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": { + "" : { + "configuration_buses": { + "": { + "configurational_columns": { + "": { + "frame_count": + } + <...> + } + } + <...> + } + } + <...> + } + }, + "top": { + "rows": { + "" : { + "configuration_buses": { + "": { + "configurational_columns": { + "": { + "frame_count": + } + <...> + } + } + <...> + } + } + <...> + } + }, + } + }, + "idcode" : , + "iobanks" : { + "": ", + <...> + } + } + +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 ` - ``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 `. The particular row of the + global :term:`clock regions ` is indicated by the ````. + 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 ````. + + There are many :term:`columns ` connected to a single bus. Each column + is described by appropriate ```` entry which contains the + information about the number of frames (````) 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 (````) and + their position in the FPGA grid (````). + +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" + } + } diff --git a/docs/dev_database/part_specific/tileconn.rst b/docs/dev_database/part_specific/tileconn.rst index a0b54a59..cf84c6c4 100644 --- a/docs/dev_database/part_specific/tileconn.rst +++ b/docs/dev_database/part_specific/tileconn.rst @@ -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": [ + , + + ], + "tile_types": [ + "", + "" + ], + "wire_pairs": [ + [ + "", + "" + ], + <...> + ], + }, + <...> + ] + +Each entry has the following fields: + +- ``grid_deltas`` - indicates the position (````, ````) of + the source tile relative to the destination_file +- ``tile_types`` - contains the information about both + ```` and ```` +- ``wire_pairs`` - contains the names of both + ```` and ```` + +Example +------- .. code-block:: javascript diff --git a/docs/dev_database/part_specific/tilegrid.rst b/docs/dev_database/part_specific/tilegrid.rst index 2cb7d8a7..0f133f01 100644 --- a/docs/dev_database/part_specific/tilegrid.rst +++ b/docs/dev_database/part_specific/tilegrid.rst @@ -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 ` in the device. +This information is used at various stages of the flow i.e. for +:term:`database ` generation or creating a :term:`bitstream `. +The most important parts of the file are related to :term:`frame ` addressing +within the :term:`bitstream `, grid and :term:`clock region ` +location, list of underlying :term:`sites `, or the type of the +:term:`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 ` in +the FPGA chip. The file is of the form:: -Sample entry: + { + "": { + "bits": { + "": { + "baseaddr": ", + "frames": 28, + "offset": 97, + "words": 2 + }, + <...> + }, + "clock_region": , + "grid_x": , + "grid_y": , + "pin_functions": { + ": "", + <...> + }, + "prohibited_sites": [ + "", + <...> + ], + "sites": { + "": , + <...> + }, + "type": "INT_R" + } + +The ```` indicates the name of the :term:`tile ` described +in the entry. The naming convention matches Vivado. + +Each :term:`tile ` entry in the file has the following fields: + +- ``"bits"`` - contains the data related to :term:`tile ` configuration over + the ````. There are three types of the configuration + buses in 7-Series FPGAs: ``CLB_IO_CLK``, ``BLOCK_RAM`` and ``CFG_CLB``. + Every ```` has the following fields: + + - ``baseaddr`` - Basic address of the configuration :term:`frame `. + Every configuration :term:`frame ` consist of 101 of 32bit + :term:`words `. Note that a single :term:`frame ` usually configures + a bunch of :term:`tiles ` connected to the single configuration bus. + + - ``"frames"`` - Number of :term:`frames ` that can configure the + :term:`tile `. + + - ``offset`` - How many words of offset is present in the :term:`frame ` + before the first :term:`word ` that configures the :term:`tile `. + + - ``words`` - How many 32bit :term:`words ` configure the :term:`tile `. + +- ``clock_region`` - indicates to which :term:`clock region ` the + :term:`tile ` belongs to. + +- ``grid_x`` - :term:`tile ` column, increasing right + +- ``grid_y`` - :term:`tile ` row, increasing down + +- ``pin_functions`` - indicates the special functions of the :term:`tile ` pins. + Usually it is related to IOB blocks and indicates i.e. differential output pins. + +- ``prohibited_sites`` - Indicates which :term:`site ` types cannot be used + in the :term:`tile ` + +- ``sites`` - dictionary which contains information about the :term:`sites ` + which can be found inside the :term:`tile `. Every entry in + the dictionary contains the following information: + + - ``""`` - The unique name of the :term:`site ` inside + the :term:`tile `. + + - ``"`` - The type of the :term:`site ` + +- ``type`` - The type of the :term:`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 ` is named ``CLBLL_L_X16Y149`` +- :term:`Frame ` base address is ``0x00020800`` +- For each :term:`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 ` loads +- Located in :term:`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 `, both of which are SLICEL +- Is a ``CLBLL_L`` type :term:`tile ` -.. warning:: FIXME: We should cross link to how to use the base address and word offset. +More information about :term:`frames ` and the FPGA configuration can be found in the +:doc:`Configuration <../../architecture/configuration>` chapter. +Example of absolute :term:`frame ` address calculation can be found in the +:doc:`mask file <../common/mask>` chapter.