Merge pull request #757 from mithro/import-wiki

Importing remaining wiki contents

docs/architecture/interconnect.rst

@@ -0,0 +1,30 @@
+Interconnect :term:`PIP`s
+=========================
+
+Fake :term:`PIP`s
+-----------------
+
+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.
+
+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:`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.
+
+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.
+
+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.
+
+Bidirectional :term:`PIP`s
+--------------------------
+
+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.

docs/architecture/reference.rst

@@ -0,0 +1,75 @@
+References
+==========
+
+Xilinx documents one should be familiar with:
+---------------------------------------------
+
+### UG470: 7 Series FPGAs Configuration User Guide
+
+https://www.xilinx.com/support/documentation/user_guides/ug470_7Series_Config.pdf
+
+*Chapter 5: Configuration Details* contains a good description of the overall
+bit-stream format. (See section "Bitstream Composition" and following.)
+
+### UG912: Vivado Design Suite Properties Reference Guide
+
+http://www.xilinx.com/support/documentation/sw_manuals/xilinx2017_3/ug912-vivado-properties.pdf
+
+Contains an excellent description of the in-memory data structures and
+associated properties Vivado uses to describe the design and the chip. The TCL
+interface provides a convenient interface to access this information.
+
+### UG903: Vivado Design Suite User Guide: Using Constraints
+
+http://www.xilinx.com/support/documentation/sw_manuals/xilinx2017_3/ug903-vivado-using-constraints.pdf
+
+The fuzzers generate designs (HDL + Constraints) that use many physical
+contraints constraints (placement and routing) to produce bit-streams with
+exactly the desired features. It helps to learn about the available constraints
+before starting to write fuzzers.
+
+### UG901: Vivado Design Suite User Guide: Synthesis
+
+http://www.xilinx.com/support/documentation/sw_manuals/xilinx2017_3/ug901-vivado-synthesis.pdf
+
+*Chapter 2: Synthesis Attributes* contains an overview of the Verilog
+attributes that can be used to control Vivado Synthesis. Many of them
+are useful for writing fuzzer designs. There is some natural overlap
+with UG903.
+
+### UG909: Vivado Design Suite User Guide: Partial Reconfiguration
+
+https://www.xilinx.com/support/documentation/sw_manuals/xilinx2017_3/ug909-vivado-partial-reconfiguration.pdf
+
+Among other things this UG contains some valuable information on how to constrain a design in a way so that the items inside a pblock are strictly separate from the items outside that pblock.
+
+### UG474: 7 Series FPGAs Configurable Logic Block
+
+https://www.xilinx.com/support/documentation/user_guides/ug474_7Series_CLB.pdf
+
+Describes the capabilities of a CLB, the most important non-interconnect resource of a Xilinx FPGA.
+
+Other documentation that might be of use:
+-----------------------------------------
+
+Doc of .bit container file format:
+http://www.pldtool.com/pdf/fmt_xilinxbit.pdf
+
+Open-Source Bitstream Generation for FPGAs, Ritesh K Soni, Master Thesis:
+https://vtechworks.lib.vt.edu/bitstream/handle/10919/51836/Soni_RK_T_2013.pdf
+
+VTR-to-Bitstream, Eddie Hung:
+https://eddiehung.github.io/vtb.html
+
+From the bitstream to the netlist, Jean-Baptiste Note and Éric Rannaud:
+http://www.fabienm.eu/flf/wp-content/uploads/2014/11/Note2008.pdf
+
+Wolfgang Spraul's Spartan-6 (xc6slx9) project:
+https://github.com/Wolfgang-Spraul/fpgatools
+
+Marek Vasut's Typhoon Cyclone IV project:
+http://git.bfuser.eu/?p=marex/typhoon.git
+
+XDL generator/imported for Vivado:
+https://github.com/byuccl/tincr
+

docs/format/db.rst

@@ -4,7 +4,7 @@
 Introduction
 ------------
 
-This section documents how prjxray represents the bitstream database
+This section documents how prjxray represents the bitstream database. The databases are plain text files, using either simple line-based syntax or JSON. The databases are located in `database/<device_class>/`. The `settings.sh` file contains some configurations used by the tools that generate the database, including the region of interest (ROI, see [[Glossary]]).
 
 These ".db" files come in two common flavors:
  * `segbits_*.db`_: encodes bitstream bits
@@ -12,10 +12,25 @@ These ".db" files come in two common flavors:
 
 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.
+
+FIXME: Expand this section. We've had a couple questions around this, probably good to get a complete description of this that we can point people too. This is probably a good place to talk about tile grid and how it applies to segbit.
+
 
 segbits_*.db
 ------------
 
+Tag files document the meaning of individual configuration bits or bit pattern. They contain one line for each pattern. The first word (sequence of non-whitespace characters) in that line is the *configuration tag*, the remaining words in the line is the list of bits for that pattern. A bit prefixed with a `!` marks a bit that must be cleared, a bit not prefixed with a `!` marks a bit that must be set.
+
+No configuration tag may include the bit pattern for another tag as subset. If it does then this is an indicator that there is an incorrect entry in the database. Usually this either means that a tag has additional bits in their pattern that should not be there, or that `!<bit>` entries are missing for one or more tags.
+
 These are created by segmatch to describe bitstream IP encoding.
 
 Example lines:
@@ -37,11 +52,11 @@ Example lines:
    * Candidate bits exist, but they've only ever been set to 1
  * INT.FAN_ALT4.SS2END0 <m1 2> 18_09 25_08
    * Internal only
-   * segmatch -m (min tag value occurances) was given, but occurances are below this threshold
+   * segmatch -m (min tag value occurrences) was given, but occurrences are below this threshold
    * ie INT.FAN_ALT4.SS2END0 occcured twice, but this is below the acceptable level (say 5)
  * INT.FAN_ALT4.SS2END0 <M 6 8> 18_09 25_08
    * Internal only
-   * segmatch -M (min tag occurances) was given, but total occurances are below this threshold
+   * 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
 
@@ -58,6 +73,31 @@ Related tools:
    * Ex: CLB is solved by first solving LUT bits, and then solving FF bits
 
 
+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 that enable interconnect :term:`PIP`s have the following syntax: `<tile_type>.<destination_wire>.<source_wire>`.
+
+The `<tile_type>` may be `INT_L` or `INT_R`. The destination and source wires are wire names in that tile type. For example, consider the following entry in `segbits_int_l.db`: `INT_L.NL1BEG1.NN6END2 07_32 12_33`
+
+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:`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.
+
 mask_*.db
 ---------
 
@@ -67,3 +107,38 @@ Example line: bit 01_256
 
 See previous section for number meaning
 
+For each segment type there is a mask file `mask_<seg_type>.db` that contains one line for each bit that has been observed being set in any of the example designs generated during generation of the database. The lines simply contain the keyword `bit` followed by the bit position. This database is used to identify unused bits in the configuration segments.
+
+
+.bits example
+-------------
+
+Say entry is: bit_0002050b_002_05
+
+2 step process:
+* Decode which segment
+* Decode which bit within that segment
+
+We have:
+* Frame address 0x0002050b (hex)
+* Word #: 2 (decimal, 0-99)
+* Bit #: 5 (decimal, 0-31)
+
+The CLB tile and the associated interconnect switchbox tile are configured together as a segment. However, configuration data is grouped by segment column rather than tile column. First, note this segment consists of 36 frames. Second, note there are 100 32 bit words per frame (+ 1 for checksum => 101 actual). Each segment takes 2 of those words meaning 50 segments (ie 50 CLB tiles + 50 interconnect tiles) are effected per frame. This means that the smallest unit that can be fully configured is a group of 50 CLB tile + switchbox tile segments taking 4 * 36 * 101 = 14544 bytes. Finally, note segment columns are aligned to 0x80 addresses (which easily fits the 36 required frames).
+
+tilegrid.json defines addresses more precisely. Taking 0x0002050b, the frame base address is 0x0002050b & 0xFFFFFF80 => 0x00020500. The frame offset is 0x0002050b & 0x7F => 0x0B => 11.
+
+So in summary:
+* Frame base address: 0x00020500
+* Frame offset: 0x0B (11)
+* Frame word #: 2
+* Frame word bit #: 5
+
+So, with this in mind, we have frame base address 0x00020500 and word # 2. This maps to tilegrid.json entry SEG_CLBLL_L_X12Y101 (has "baseaddr": ["0x00020600", 2]). This also yields "type": "clbll_l" meaning we are configuring a CLBLL_L.
+
+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).
+
+

docs/format/tile.rst

@@ -16,6 +16,14 @@ General notes:
 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.
+
+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:
@@ -101,6 +109,10 @@ Interpreted as:
 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.
+
 This file documents how adjacent tile pairs are connected.
 No directionality is given.
 

docs/index.rst

@@ -20,8 +20,10 @@ to develop a free and open Verilog to bitstream toolchain for these devices.
    architecture/overview
    architecture/configuration
    architecture/bitstream_format
+   architecture/interconnect
    architecture/dram_configuration
    architecture/glossary
+   architecture/reference
 
 .. toctree::
    :maxdepth: 2