Apply review comments to database description

Signed-off-by: Robert Winkler <rwinkler@antmicro.com>

docs/dev_database/common/index.rst

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

docs/dev_database/common/mask.rst

@@ -2,9 +2,9 @@
 mask files
 ==========
 
-The *mask files* are generated for every FPGA :term:`tile <tile>` type.
+The *mask files* are generated for every FPGA :term:`tile <Tile>` type.
 They store the information which bits in the bitstream can configure the given
-:term:`tile <tile>` type.
+:term:`tile <Tile>` type.
 
 Naming convention
 -----------------
@@ -14,13 +14,13 @@ The naming scheme for the mask files is the following::
    mask_<tile>.db
 
 Note that auxiliary ``mask_<tile>.origin_info.db`` files
-provide additional information about the :term:`fuzzer <fuzzer>`,
+provide additional information about the :term:`fuzzer <Fuzzer>`,
-which produced the :term:`database <database>` file. This file is optional.
+which produced the :term:`database <Database>` file. This file is optional.
 
-Every :term:`tile <tile>` is configured at least by one of three configurational
+Every :term:`tile <Tile>` is configured at least by one of three configurational
 buses mentioned in the :doc:`Configuration Section <../../architecture/configuration>`.
 The default bus is called ``CLB_IO_CLK``.
-If the :term:`tile <tile>` can also be configured by another bus, it has an additional ``mask_<tile>.<bus_name>.db``
+If the :term:`tile <Tile>` can also be configured by another bus, it has an additional ``mask_<tile>.<bus_name>.db``
 related to that bus.
 
 For example:
@@ -33,12 +33,12 @@ File format
 -----------
 
 The file consists of records that describe the configuration bits for
-the particular :term:`tile <tile>` type. Each entry inside the file is of the form::
+the particular :term:`tile <Tile>` type. Each entry inside the file is of the form::
 
    bit <frame_address_offset>_<bit_position>
 
-This means that the :term:`tile <tile>` can be configured by a bit located in the
+This means that the :term:`tile <Tile>` can be configured by a bit located in the
-:term:`frame <frame>` at the address ``<base_frame_addr> + <frame_address_offset>``,
+:term:`frame <Frame>` at the address ``<base_frame_addr> + <frame_address_offset>``,
 at position ``<tile_offset> + <bit_position>``. Information about ``<base_frame_address>``
 and ``<tile_offset>`` can be taken from part specific ``tilegrid.json`` file.
 
@@ -46,7 +46,7 @@ Example
 -------
 
 Below there is a part of artix7 ``mask_clbll_l.db`` file describing a FPGA *CLBLL*
-:term:`tile <tile>`::
+:term:`tile <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 <tile>` can be
+The line ``bit 01_02`` means that the *CLBL_LL* :term:`tile <Tile>` can be
-configured by the bit located in the :term:`frame <frame>` at the address
+configured by the bit located in the :term:`frame <Frame>` at the address
 ``<base_frame_address> + 0x01``, at position ``<tile_offset> + 0x2``.
 
 The ``tilegrid.json`` is a file specific to a given chip package.
@@ -85,14 +85,14 @@ For *xc7a35tcpg236-1* we can find an exemplary *CLBLL_L* entry::
     },
 
 The ``<base_frame_addr>`` can be found as a argument of the *"baseaddr"* key
-and for *CLBLL_L_X2Y0* :term:`tile <tile>` it is equal to ``0x00400100``. The ``<tile_offset>``
+and for *CLBLL_L_X2Y0* :term:`tile <Tile>` it is equal to ``0x00400100``. The ``<tile_offset>``
 on the other hand is an argument of the *"offset"* key. Here it is equal to 0.
 
 Finally, we are able to compute the bit location associated with the
 ``bit 01_02`` entry.
 
 The configuration bit for this record can be found in the following
-:term:`frame <frame>` address::
+:term:`frame <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 <frame>`
+More about the configuration process and the meaning of the :term:`frame <Frame>`
 can be found in the :doc:`Configuration Section <../../architecture/configuration>`.

docs/dev_database/common/ppips.rst

@@ -2,13 +2,18 @@
 ppips files
 ===========
 
-The *ppips files* are generated for every FPGA :term:`tile <tile>` type.
+The *ppips files* are generated for every FPGA :term:`tile <Tile>` type.
 They store the information about the pseudo-PIPs, inside the tile.
 
-Programable Interconnect Point (:term:`PIP <pip>`) is a connection inside the
+Programable Interconnect Point (:term:`PIP <PIP>`) is a connection inside the
-:term:`tile <tile>` that can be enabled or disabled. Pseudo PIPs appear as standard
+:term:`tile <Tile>` that can be enabled or disabled. Pseudo PIPs appear as standard
-:term:`PIPs <pip>` in the Vivado tool, but they do not have actual configuration
+:term:`PIPs <PIP>` in the Vivado tool, but they do not have actual configuration
-bit pattern (they are not configurable).
+bit pattern in segbits files (they are not configurable).
+
+The *ppips files* contains the information which `PIPs <PIP>` do not have
+configuration bits, which allows the tools to not generat error in that situation.
+On the other hand this information is used to indicate that the connection
+between wires is always on.
 
 Naming convention
 -----------------

docs/dev_database/common/segbits.rst

@@ -2,12 +2,16 @@
 segbits files
 =============
 
-The *segbits files* are generated for every FPGA :term:`tile <tile>` type.
+The *segbits files* are generated for every FPGA :term:`tile <Tile>` type.
 They store the information about the combinations of bits in the bitstream
-that are responsible for enabling different features inside the :term:`tile <tile>`.
+that are responsible for enabling different features inside the :term:`tile <Tile>`.
 The features can be related to enabling some part of the primitive, setting some
 initial state of the block, configuring pin pull-up on output pins, etc.
 
+Besides the features provided in this file that can be enabled,
+the FPGA chip also has the default configuration. Due to that sometimes there
+is no need for affecting the default configuration.
+
 Naming convention
 -----------------
 
@@ -16,17 +20,17 @@ The naming scheme for the segbits files is the following::
    segbits_<tile>.db
 
 Note that auxiliary ``segbits_<tile>.origin_info.db`` files
-provide additional information about the :term:`fuzzer <fuzzer>`, which produced the
+provide additional information about the :term:`fuzzer <Fuzzer>`, which produced the
-:term:`database <database>` file. This file is optional.
+:term:`database <Database>` file. This file is optional.
 
-Every :term:`tile <tile>` is configured at least by one of three configurational buses
+Every :term:`tile <Tile>` is configured at least by one of three configurational buses
 mentioned in the :doc:`Configuration Section <../../architecture/configuration>`.
-The default bus is called ``CLB_IO_CLK``. If the :term:`tile <tile>` can also be configured
+The default bus is called ``CLB_IO_CLK``. If the :term:`tile <Tile>` can also be configured
 by another bus, it has additional ``segbits_<tile>.<bus_name>.db``
 related to that bus.
 
 
-Exemplary files:
+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 ``<feature>`` names for interconnect :term:`PIPs <pip>` are stored in the
+The ``<feature>`` names for interconnect :term:`PIPs <PIP>` are stored in the
 ``segbits_int_l.db`` and ``segbits_int_r.db`` database files. The features that
-enable interconnect :term:`PIPs <pip>` have the following syntax::
+enable interconnect :term:`PIPs <PIP>` have the following syntax::
 
  <tile_type>.<destination_wire>.<source_wire>.
 
@@ -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 <tile>`::
+architecture. The file describes the *CLBLL* :term:`tile <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 ``<feature>`` name is linked with its functionality.
 For example, ``LIOB33.IOB_Y0.PULLTYPE.PULLUP`` means that in the LIOB33
-:term:`tile <tile>`,
+:term:`tile <Tile>`,
 in IOB_Y0 site the *pull type* will be set to *PULLUP*.
 This simply means that all pins belonging to this particular IOB
 will be configured with pull-up.

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 <site>` type. They store the information about the pins and
+:term:`site <Site>` type. They store the information about the pins and
-:term:`PIPs <pip>` of the :term:`site <site>`.
+:term:`PIPs <PIP>` of the :term:`site <Site>`.
 
 Naming convention
 -----------------
 
-The naming scheme for the :term:`site <site>` type files is the following::
+The naming scheme for the :term:`site <Site>` type files is the following::
 
    site_type_<site>.json
 
@@ -22,7 +22,7 @@ Example files:
 File format
 -----------
 
-The :term:`site <site>` type files are JSON files with the following scheme::
+The :term:`site <Site>` type files are JSON files with the following scheme::
 
     {
         "site_pins": {
@@ -42,15 +42,15 @@ The :term:`site <site>` type files are JSON files with the following scheme::
 
 where:
 
-   - *<PIN_NAME>* - specifies the :term:`site <site>` pin name
+   - *<PIN_NAME>* - specifies the :term:`site <Site>` pin name
-   - *<PIP_NAME>* - specifies the :term:`site <site>` :term:`pip <pip>` name
+   - *<PIP_NAME>* - specifies the :term:`site <Site>` :term:`pip <PIP>` name
    - *<DIR>* - is a direction of a pin (either **IN** or **OUT**)
-   - *<TYPE>* - specifies the :term:`site <site>` type
+   - *<TYPE>* - specifies the :term:`site <Site>` type
 
 
-The ``"site_pins"`` section describes the input pins of a :term:`site <site>`
+The ``"site_pins"`` section describes the input pins of a :term:`site <Site>`
-and its directions. The ``"site_pips"`` describes the :term:`PIPs <pip>`
+and its directions. The ``"site_pips"`` describes the :term:`PIPs <PIP>`
-inside the :term:`site <site>` and which wires they can connect.
+inside the :term:`site <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 <site>`.
+Compare the description with the `Xilinx documentation`_ of that :term:`site <Site>`.
 
 .. _Xilinx documentation: https://www.xilinx.com/support/documentation/user_guides/ug474_7Series_CLB.pdf#page=20

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 <tile>`
+The *tile_type files* are generated for every FPGA :term:`tile <Tile>`
-type. They store the information about the :term:`tile <tile>` configuration,
+type. They store the information about the :term:`tile <Tile>` configuration,
-its :term:`PIPs <pip>`, :term:`sites <site>`, wires and their properties.
+its :term:`PIPs <PIP>`, :term:`sites <Site>`, wires and their properties.
 
 Naming convention
 -----------------
@@ -22,7 +22,7 @@ Example files:
 File format
 -----------
 
-The :term:`tile <tile>` type files are JSON files with the following shape::
+The :term:`tile <Tile>` type files are JSON files with the following shape::
 
    {
       "pips": {
@@ -30,10 +30,10 @@ The :term:`tile <tile>` type files are JSON files with the following shape::
             "can_invert":' "<BOOL>",
             "dst_to_src": {
                 "delay": [
-                    "<DEALY_VALUE>",
+                    "<FAST_MIN>",
-                    "<DELAY_VALUE>",
+                    "<FAST_MAX>",
-                    "<DELAY_VALUE>",
+                    "<SLOW_MIN>",
-                    "<DELAY_VALUE>"
+                    "<SLOW_MAX>"
                 ],
                 "in_cap": "<IN_CAPACITANCE>",
                 "res": "<RESISTANCE>"
@@ -44,10 +44,10 @@ The :term:`tile <tile>` type files are JSON files with the following shape::
             "is_pseudo": "0",
             "src_to_dst": {
                 "delay": [
-                    "<DELAY_VALUE>",
+                    "<FAST_MIN>",
-                    "<DELAY_VALUE>",
+                    "<FAST_MAX>",
-                    "<DELAY_VALUE>",
+                    "<SLOW_MIN>",
-                    "<DELAY_VALUE>"
+                    "<SLOW_MAX>"
                 ],
                 "in_cap": "<IN_CAPACITANCE>",
                 "res": "<RESISTANCE>"
@@ -63,10 +63,10 @@ The :term:`tile <tile>` type files are JSON files with the following shape::
                 "<SITE_PIN_NAME>": {
                     "cap": "<CAPACITY>",
                     "delay": [
-                        "<DELAY_VALUE>",
+                        "<FAST_MIN>",
-                        "<DELAY_VALUE>",
+                        "<FAST_MAX>",
-                        "<DELAY_VALUE>",
+                        "<SLOW_MIN>",
-                        "<DELAY_VALUE>"
+                        "<SLOW_MAX>"
                     ],
                     "wire": "<WIRE_NAME>"
                 },
@@ -85,28 +85,34 @@ The :term:`tile <tile>` type files are JSON files with the following shape::
 "pips" section
 ^^^^^^^^^^^^^^
 
-The "pips" section describes all :term:`PIPs <pip>` in the :term:`tile <tile>`.
+The "pips" section describes all :term:`PIPs <PIP>` in the :term:`tile <Tile>`.
-Every :term:`PIP <pip>` has its name - ``"<PIN_NAME>"`` and may be
+Every :term:`PIP <PIP>` has its name - ``"<PIN_NAME>"`` and may be
 characterized by the following attributes:
 
 - ``can_invert`` - takes a value which can be either **1** or **0**.
-  It defines whether the :term:`PIP <pip>` has an inverter on it's output or not.
+  It defines whether the :term:`PIP <PIP>` has an inverter on it's output or not.
 
 - ``dst_to_src`` - information about the connection in the direction
   from destination to source. It describes the following properties of the connection:
 
-   - ``delay`` - four-element list, which contain information about the delays.
+   - ``delay`` - a four-element list, which contain information about the delay of pins.
-   - ``in_cap`` - the input capacitance of the :term:`PIP <pip>`
+     First two elements are related to the *fast corner* of the technological process,
-   - ``res`` - the resistance of the :term:`PIP <pip>`.
+     the second two elements to the *slow corner*. The first element of the pair
+     is the minimum value of the corner, the second describes the maximum value.
+     They are given in us (nanoseconds).
+
+   - ``in_cap`` - the input capacitance of the :term:`PIP <PIP>` in uF (microfarads).
+
+   - ``res`` - the resistance of the :term:`PIP <PIP>` in mΩ (miliohms).
 
 - ``dst_wire`` - the destination wire name
 
-- ``is_directional`` - contains the information whether :term:`PIP <pip>` is directional.
+- ``is_directional`` - contains the information whether :term:`PIP <PIP>` is directional.
 
-- ``is_pass_transisstor`` - contains the information whether :term:`PIP <pip>` acts
+- ``is_pass_transisstor`` - contains the information whether :term:`PIP <PIP>` acts
   as a pass transistor
 
-- ``is_pseudo`` - contains the information whether :term:`PIP <pip>` is a pseudo-PIP
+- ``is_pseudo`` - contains the information whether :term:`PIP <PIP>` is a pseudo-PIP
 
 - ``src_to_dst`` - contains the information about the connection in the direction
   from source to destination. It is described by the same set of properties as
@@ -115,19 +121,25 @@ characterized by the following attributes:
 "sites" section:
 ^^^^^^^^^^^^^^^^
 
-The "sites" section describes all :term:`sites <site>` in the :term:`tile <tile>`.
+The "sites" section describes all :term:`sites <Site>` in the :term:`tile <Tile>`.
-Every :term:`site <site>` may be characterized by the following attributes:
+Every :term:`site <Site>` may be characterized by the following attributes:
 
-- ``name`` - location in the :term:`tile <tile>` grid
+- ``name`` - location in the :term:`tile <Tile>` grid
 
-- ``prefix`` - the type of the :term:`site <site>`
+- ``prefix`` - the type of the :term:`site <Site>`
 
-- ``site_pins`` - describes the pins that belong to the :term:`site <site>`.
+- ``site_pins`` - describes the pins that belong to the :term:`site <Site>`.
   Every pin has it's  name - ``<PIN_NAME>`` and may be described
   by the following attributes:
 
-   - ``cap`` - pin capacitance
+   - ``cap`` - pin capacitance in uF (microfarads).
-   - ``delay`` - pin delay
+
+   - ``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 <site>` may be characterized by the following attributes:
 "wires" section
 ^^^^^^^^^^^^^^^
 
-The "wires" section describes the wires located in the :term:`tile <tile>`.
+The "wires" section describes the wires located in the :term:`tile <Tile>`.
 Every wire has it's name - ``<WIRE_NAME>`` and may be characterized
 by the following attributes:
 
-- ``cap`` - wire capacitance
+- ``cap`` - wire capacitance in uF (microfarads)
-- ``res`` - wire resistance
+- ``res`` - wire resistance in mΩ (miliohms).
 
 Other
 ^^^^^
 - ``tile_type`` - indicates the type of the tile
 
-
 Example
 -------