From 3b498612cb9b70ae5844607698ffcb4dc2410c0b Mon Sep 17 00:00:00 2001 From: Tim 'mithro' Ansell Date: Sat, 27 Apr 2019 14:57:00 -0500 Subject: [PATCH 1/4] docs: Strip trailing space. Signed-off-by: Tim 'mithro' Ansell --- docs/architecture/glossary.rst | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/docs/architecture/glossary.rst b/docs/architecture/glossary.rst index 24b8839f..a4e5bdbc 100644 --- a/docs/architecture/glossary.rst +++ b/docs/architecture/glossary.rst @@ -25,13 +25,13 @@ Glossary * Basic BEL - A logic unit which does things. * Routing BEL - A unit which is statically configured at routing time. - + Bitstream Binary data that is directly loaded into an :term:`FPGA` to perform configuration. Contains configuration :term:`frames ` as well as programming sequences and other commands required to load and activate same. - + Block RAM Block RAM is inbuilt, configurable memory on an :term:`FPGA`, able to store more data than the :term:`flip flops `. The block RAM can function as @@ -42,7 +42,7 @@ Glossary CFA A carry or fast adder (CFA) is a logic element on the :term:`FPGA` that performs fast arithmetic operations. - + Clock A clock is a square-wave timing signal (50% on, 50% off) generated by an external oscillator and passed into the :term:`FPGA`. The clock frequency @@ -62,7 +62,7 @@ Glossary part of a :term:`horizontal clock row` to one side of the global :term:`clock spine`. The term also often refers to the :term:`tiles ` that are associated with these clocks. - + Clock region Portion of a device including up to 12 :term:`clock domains `. A clock region is situated to the left or right of the global clock spine, @@ -90,7 +90,7 @@ Glossary Fabric sub region FSR Another name for :term:`clock region`. - + Flip flop FF A flip flop (FF) is a logic element on the :term:`FPGA` that stores state. @@ -117,7 +117,7 @@ Glossary For example, in a logic column with 50 tiles, the first tile is configured with the first two words in each frame, the next tile with the next two words, and so on. - + Frame base address The first configuration frame address for a :term:`column`. A frame base address has always the 7 LSB bits cleared. @@ -135,7 +135,7 @@ Glossary You use a hardware definition language (HDL) to describe the behavior of an electronic circuit. Popular HDLs include Verilog (inspired by C) and VHDL (inspired by Ada). - + Horizontal clock row HROW Portion of a device including 12 horizontal :term:`clocks ` and the @@ -171,7 +171,7 @@ Glossary Place and route Place and route (PnR) is the process of taking logic and placing it into hardware logic elements on the :term:`FPGA`, and then routing the signals - between the placed elements. + between the placed elements. Region of interest ROI @@ -222,4 +222,4 @@ Glossary Word 32 bits stored in big-endian order. Fundamental unit of :term:`bitstream` - format. + format. From a1c629819c19d42d94b711a24834c0162fbbbbdc Mon Sep 17 00:00:00 2001 From: Tim 'mithro' Ansell Date: Sat, 27 Apr 2019 15:03:14 -0500 Subject: [PATCH 2/4] docs: Fixing the :term:`PIP` References. Signed-off-by: Tim 'mithro' Ansell --- docs/architecture/glossary.rst | 5 +++++ docs/architecture/interconnect.rst | 26 +++++++++++++------------- docs/format/db.rst | 10 +++++----- 3 files changed, 23 insertions(+), 18 deletions(-) diff --git a/docs/architecture/glossary.rst b/docs/architecture/glossary.rst index a4e5bdbc..d20375a8 100644 --- a/docs/architecture/glossary.rst +++ b/docs/architecture/glossary.rst @@ -147,6 +147,11 @@ Glossary One of the configurable input/output blocks that connect the :term:`FPGA` to external devices. + Interconnect tile + INT + An interconnect tile (`INT_L`, `INT_R`) is used to connect other tiles to + the fabric. It is also frequently called a switch box. + LUT A lookup table (LUT) is a logic element on the :term:`FPGA`. LUTs function as a ROM, apply combinatorial logic, and generate the output value for a diff --git a/docs/architecture/interconnect.rst b/docs/architecture/interconnect.rst index 1903d2e0..6743f3cf 100644 --- a/docs/architecture/interconnect.rst +++ b/docs/architecture/interconnect.rst @@ -1,30 +1,30 @@ -Interconnect :term:`PIP`s -========================= +Interconnect :term:`PIPs ` +=============================== -Fake :term:`PIP`s ------------------ +Fake :term:`PIPs ` +----------------------- -Some :term:`PIP`s are not "real", in the sense that no bit pattern in the bit-stream correspond to the PIP being used. This is the case for all the :term:`PIP`s in the switchbox in a CLB tile (ex: CLBLM_L_INTER): They either correspond to buffers that are always on (i.e. 1:1 connections such as `CLBLL_L.CLBLL_L_AQ->CLBLL_LOGIC_OUTS0`), or they correspond to permutations of LUT input signals, which is handled by changing the LUT init value accordingly, or they are used to "connect" two signals that are driven by the same signal from within the CLB. +Some :term:`PIPs ` are not "real", in the sense that no bit pattern in the bit-stream correspond to the PIP being used. This is the case for all the :term:`PIPs ` in the switchbox in a CLB tile (ex: CLBLM_L_INTER): They either correspond to buffers that are always on (i.e. 1:1 connections such as `CLBLL_L.CLBLL_L_AQ->CLBLL_LOGIC_OUTS0`), or they correspond to permutations of LUT input signals, which is handled by changing the LUT init value accordingly, or they are used to "connect" two signals that are driven by the same signal from within the CLB. FIXME: Check the above is true. The bit switchbox in an :term:`INT`s tile also contains a few 1:1 connections that are in fact always present and have no corresponding configuration bits. -Regular :term:`PIP`s --------------------- +Regular :term:`PIPs ` +-------------------------- -Regular :term:`PIP`s correspond to a bit pattern that is present in the bit stream when the PIP is used in the current design. There is a block of up to 10-ish bits for each destination signal. For each configuration (i.e. source net that can drive the destination) there is a pair of bits that is set. +Regular :term:`PIPs ` correspond to a bit pattern that is present in the bit stream when the PIP is used in the current design. There is a block of up to 10-ish bits for each destination signal. For each configuration (i.e. source net that can drive the destination) there is a pair of bits that is set. FIXME: Check if the above is true for PIPs outside of the INT switch box. -For example, when the bits 05_57 and 11_56 are set then SR1END3->SE2BEG3 is enabled, but when 08_56 and 11_56 are set then ER1END3->SE2BEG3 is enabled (in an :term:`INT_L`s tile paired with a CLBLL_L tile). A configuration in which all three bits are set is invalid. See `segbits_int_[lr].db` for a complete list of bit pattern for configuring :term:`PIP`s. +For example, when the bits 05_57 and 11_56 are set then SR1END3->SE2BEG3 is enabled, but when 08_56 and 11_56 are set then ER1END3->SE2BEG3 is enabled (in an :term:`INT_L`s tile paired with a CLBLL_L tile). A configuration in which all three bits are set is invalid. See `segbits_int_[lr].db` for a complete list of bit pattern for configuring :term:`PIPs `. VCC Drivers ----------- -The default state for a net is to be driven high. The :term:`PIP`s that drive a net from `VCC_WIRE` correspond to the "empty configuration" with no bits set. +The default state for a net is to be driven high. The :term:`PIPs ` that drive a net from `VCC_WIRE` correspond to the "empty configuration" with no bits set. -Bidirectional :term:`PIP`s --------------------------- +Bidirectional :term:`PIPs ` +-------------------------------- -Bidirectional :term:`PIP`s are used to stitch together long traces (LV*, LVB*). In case of bidirectional :term:`PIP`s there are two different configuration patterns, one for each direction. +Bidirectional :term:`PIPs ` are used to stitch together long traces (LV*, LVB*). In case of bidirectional :term:`PIPs ` there are two different configuration patterns, one for each direction. diff --git a/docs/format/db.rst b/docs/format/db.rst index e822777c..7cb85094 100644 --- a/docs/format/db.rst +++ b/docs/format/db.rst @@ -73,12 +73,12 @@ Related tools: * Ex: CLB is solved by first solving LUT bits, and then solving FF bits -Interconnect :term:`PIP` Tags -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Interconnect :term:`PIP ` Tags +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Tags for interconnect :term:`PIP`s are stored in the `segbits_int_l.db` and `segbits_int_r.db` database files. +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:`PIP`s have the following syntax: `..`. +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` @@ -96,7 +96,7 @@ Tags for CLB tiles use a dot-separated hierarchy for their tag names. For exampl ppips_*.db ---------- -Pseudo :term:`PIP`s are :term:`PIP`s in the Vivado tool, but do not have actual bit pattern. The `ppips_*.db` files contain information on pseudo-:term:`PIP`s. 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:`PIP`s that are actually always-on, i.e. that are permanent connections between two wires. The tag `default` is used for pseudo-:term:`PIP`s that represent the default behavior if no other driver has been configured for the destination net (all `default` pseudo-:term:`PIP`s connect to the `VCC_WIRE` net). And the tag `hint` is used for :term:`PIP`s 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. +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 --------- From 50139c524dfd8dd31418b57b24c3f626362c0457 Mon Sep 17 00:00:00 2001 From: Tim 'mithro' Ansell Date: Sat, 27 Apr 2019 15:09:46 -0500 Subject: [PATCH 3/4] docs: Adding warning to FIXMEs. Signed-off-by: Tim 'mithro' Ansell --- docs/architecture/interconnect.rst | 4 ++-- docs/format/db.rst | 6 +++--- docs/format/tile.rst | 4 ++-- 3 files changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/architecture/interconnect.rst b/docs/architecture/interconnect.rst index 6743f3cf..f6070750 100644 --- a/docs/architecture/interconnect.rst +++ b/docs/architecture/interconnect.rst @@ -6,7 +6,7 @@ Fake :term:`PIPs ` Some :term:`PIPs ` are not "real", in the sense that no bit pattern in the bit-stream correspond to the PIP being used. This is the case for all the :term:`PIPs ` in the switchbox in a CLB tile (ex: CLBLM_L_INTER): They either correspond to buffers that are always on (i.e. 1:1 connections such as `CLBLL_L.CLBLL_L_AQ->CLBLL_LOGIC_OUTS0`), or they correspond to permutations of LUT input signals, which is handled by changing the LUT init value accordingly, or they are used to "connect" two signals that are driven by the same signal from within the CLB. -FIXME: Check the above is true. +.. warning:: FIXME: Check the above is true. The bit switchbox in an :term:`INT`s tile also contains a few 1:1 connections that are in fact always present and have no corresponding configuration bits. @@ -15,7 +15,7 @@ Regular :term:`PIPs ` Regular :term:`PIPs ` correspond to a bit pattern that is present in the bit stream when the PIP is used in the current design. There is a block of up to 10-ish bits for each destination signal. For each configuration (i.e. source net that can drive the destination) there is a pair of bits that is set. -FIXME: Check if the above is true for PIPs outside of the INT switch box. +.. warning:: FIXME: Check if the above is true for PIPs outside of the INT switch box. For example, when the bits 05_57 and 11_56 are set then SR1END3->SE2BEG3 is enabled, but when 08_56 and 11_56 are set then ER1END3->SE2BEG3 is enabled (in an :term:`INT_L`s tile paired with a CLBLL_L tile). A configuration in which all three bits are set is invalid. See `segbits_int_[lr].db` for a complete list of bit pattern for configuring :term:`PIPs `. diff --git a/docs/format/db.rst b/docs/format/db.rst index 7cb85094..4b43c9ec 100644 --- a/docs/format/db.rst +++ b/docs/format/db.rst @@ -21,7 +21,7 @@ The first number indicates the frame address relative to the base frame address The second number indicates the bit position width. -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. +.. 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 @@ -82,7 +82,7 @@ Tags that enable interconnect :term:`PIPs ` have the following syntax: `` 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` -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). +.. 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`. @@ -136,7 +136,7 @@ So in summary: 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. -FIXME: This example is out of date with the new tilegrid format, should update it. +.. 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/tile.rst b/docs/format/tile.rst index 7903104e..8ac196e7 100644 --- a/docs/format/tile.rst +++ b/docs/format/tile.rst @@ -20,7 +20,7 @@ The file `tilegrid.json` contains lists of all tiles in the device and the confi 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. -FIXME: We should cross link to how to use the base address and word offset. +.. 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. @@ -111,7 +111,7 @@ 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. -FIXME: This is a good place to add the tile wire, pip, site pin diagram. +.. 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. From 85060dd1d64b3d223509975134c66f5008d320dd Mon Sep 17 00:00:00 2001 From: Tim 'mithro' Ansell Date: Sun, 28 Apr 2019 19:01:58 -0700 Subject: [PATCH 4/4] Fix the INT references. Signed-off-by: Tim 'mithro' Ansell --- docs/architecture/interconnect.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/architecture/interconnect.rst b/docs/architecture/interconnect.rst index f6070750..87ef675f 100644 --- a/docs/architecture/interconnect.rst +++ b/docs/architecture/interconnect.rst @@ -8,7 +8,7 @@ Some :term:`PIPs ` are not "real", in the sense that no bit pattern in the .. warning:: FIXME: Check the above is true. -The bit switchbox in an :term:`INT`s tile also contains a few 1:1 connections that are in fact always present and have no corresponding configuration bits. +The bit switchbox in an :term:`INTs ` tile also contains a few 1:1 connections that are in fact always present and have no corresponding configuration bits. Regular :term:`PIPs ` -------------------------- @@ -17,7 +17,7 @@ Regular :term:`PIPs ` correspond to a bit pattern that is present in the bi .. warning:: FIXME: Check if the above is true for PIPs outside of the INT switch box. -For example, when the bits 05_57 and 11_56 are set then SR1END3->SE2BEG3 is enabled, but when 08_56 and 11_56 are set then ER1END3->SE2BEG3 is enabled (in an :term:`INT_L`s tile paired with a CLBLL_L tile). A configuration in which all three bits are set is invalid. See `segbits_int_[lr].db` for a complete list of bit pattern for configuring :term:`PIPs `. +For example, when the bits 05_57 and 11_56 are set then SR1END3->SE2BEG3 is enabled, but when 08_56 and 11_56 are set then ER1END3->SE2BEG3 is enabled (in an :term:`INT_L `s tile paired with a CLBLL_L tile). A configuration in which all three bits are set is invalid. See `segbits_int_[lr].db` for a complete list of bit pattern for configuring :term:`PIPs `. VCC Drivers -----------