docs: configuration addressing section and rough notes for others

Describes how frame addressing relates to physical chip structure. Rough
notes on how frames are loaded into the device and the packet format
used to operate that state machine.

Signed-off-by: Rick Altherr <kc8apf@kc8apf.net>

docs/architecture/bitstream_format.rst

@@ -0,0 +1,43 @@
+Bitstream format
+================
+
+.. todo::
+  Expand on rough notes
+
+* Specific byte pattern at beginning of file to allow hardware to determine
+  width of bus providing configuration data.
+* Rest of file is 32-bit big-endian words
+* All data before 32-bit synchronization word (0xAA995566) is ignored by
+  configuration state machine
+* Packetized format used to perform register reads/writes
+  * Three packet header types
+
+    * Type 0 packets exist only when performing zero-fill between rows
+    * Type 1 used for writes up to 4096 words
+    * Type 2 expands word count field to 27 bits by omitting register address
+    * Type 2 must always be proceeded by Type 1 which sets register address
+
+  * NOP packets are used for inserting required delays
+  * Most registers only accept 1 word of data
+  * Allowed register operations depends on interface used to send packets
+
+    * Writing LOUT via JTAG is treated as a bad command
+    * Single-frame FDRI writes via JTAG fail
+
+* CRC
+
+  * Calculated automatically from writes: register address and data written
+  * Expected value is written to CRC register
+  * If there is a mismatch, error is flagged in status register
+  * Writes to CRC register can be safely removed from a bitstream
+  * Alternatively, replace with write to command register to reset calculated
+    CRC value
+
+* Xilinx BIT header
+
+  * Additional information about how bitstream was generated
+  * Unofficially documented at
+    http://www.fpga-faq.com/FAQ_Pages/0026_Tell_me_about_bit_files.htm
+  * Really does require NULL-terminated Pascal strings
+  * Having this header is the distinction between .bin and .bit in Vivado
+  * Is ignored entirely by devices

docs/architecture/configuration.rst

@@ -0,0 +1,130 @@
+Configuration
+=============
+
+Within an FPGA, various memories (latches, block RAMs, distributed RAMs)
+contain the state of signal routing, :term:`BEL` configuration, and runtime
+storage. Configuration is the process of loading an initial state into all of
+these memories both to define the intended logic operations as well as set
+initial data for runtime memories. Note that the same mechanisms used for
+configuration are also capable of reading out the active state of these
+memories as well. This can be used to examine the contents of a block RAM or
+other memory at any point in the device's operation.
+
+Addressing
+----------------
+As described in :ref:`architecture_overview-label`, 7-Series FPGAs are constructed
+out of :term:`tiles <tile>` organized into :term:`clock domains <clock
+domain>`. Each tile contains a set of :term:`BELs <BEL>` and the memories used
+to configure them. Uniquely addressing each of these memories
+involves first identifying the :term:`horizontal clock row`, then the tile within
+that row, and finally the specific bit within the tile.
+
+:term:`Horizontal clock row` addressing follows the hierarchical structure described
+in :ref:`architecture_overview-label` with a single bit used to indicate top or bottom half
+and a 5-bit integer to encode the row number. Within the row, tiles are connected to
+one or more configuration busses depending on the type of tile and what configuration
+memories it contains. These busses are identified by a 3-bit integer:
+
++---------+-------------------+---------------------+
+| Address | Name              | Connected tile type |
++=========+===================+=====================+
+| 000     | CLB, I/O, CLB     | Interconnect (INT)  |
++---------+-------------------+---------------------+
+| 001     | Block RAM content | Block RAM (BRAM)    |
++---------+-------------------+---------------------+
+| 010     | CFG_CLB           | ???                 |
++---------+-------------------+---------------------+
+
+Within each bus, the connected tiles are organized into columns. A column roughly
+corresponds to a physical vertical line of tiles perpendicular to and centered over
+the horizontal clock row. Each column contains varying amounts of configuration data
+depending on the types of tiles attached to that column. Regardless of the amount,
+a column's configuration data is organized into a multiple of :term:`frames <frame>`.
+Each frame consists of 101 words with 100 words for the connected tiles and 1 word for
+the horizontal clock row. The 7-bit address used to identify a specific frame within
+the column is called the minor address.
+
+Putting all these pieces together, a 32-bit frame address is constructed:
+
++-----------------+-------+
+| Field           | Bits  |
++=================+=======+
+| Reserved        | 31:26 |
++-----------------+-------+
+| Bus             | 25:23 |
++-----------------+-------+
+| Top/Bottom Half | 22    |
++-----------------+-------+
+| Row             | 21:17 |
++-----------------+-------+
+| Column          | 16:7  |
++-----------------+-------+
+| Minor           | 6:0   |
++-----------------+-------+
+
+CLB, I/O, CLB
+^^^^^^^^^^^^^
+
+Columns on this bus are comprised of 50 directly-attached interconnect tiles with various
+kinds of tiles connected behind them. Frames are striped across the interconnect tiles
+with each tile receiving 2 words out of the frame. The number of frames in a column
+depends on the type of tiles connected behind the interconnect. For example, interconnect
+tiles always have 26 frames and a CLBL tile has an additional 12 frames so a column of CLBs
+will have 36 frames.
+
+Block RAM content
+^^^^^^^^^^^^^^^^^
+
+As the name says, this bus provides access to the Block RAM contents. Block RAM configuration
+data is accessed via the CLB, I/O, CLB bus. The mapping of frame words to memory locations is
+not currently understood.
+
+CFG_CLB
+^^^^^^^
+
+While mentioned in a few places, this bus type has not been seen in any bitstreams for Artix7
+so far.
+
+Loading sequence
+----------------------
+
+.. todo::
+
+  Expand on these rough notes.
+
+* Device is configured via a state machine controlled via a set of registers
+* CRC of register writes is checked against expected values to verify data
+  integrity during transmission.
+* Before writing frame data:
+
+  * IDCODE for configuration's target device is checked against actual device
+  * Watchdog timer is disabled
+  * Start-up sequence clock is selected and configured
+  * Start-up signal assertion timing is configured
+  * Interconnect is placed into Hi-Z state
+
+* Data is then written by:
+
+  * Loading a starting address
+  * Selecting the write configuration command
+  * Writing configuration data to data input register
+
+    * Writes must be in multiples of the frame size
+    * Multi-frame writes trigger autoincrementing of the frame address
+    * Autoincrement can be disabled via bit in COR1 register.
+    * At the end of a row, 2 frames of zeros must be inserted before data for the next row.
+
+* After the write has finished, the device is restarted by:
+
+  * Strobing a signal to activate IOB/CLB configuration flip-flops
+  * Reactivate interconnect
+  * Arms start-up sequence to run after desync
+  * Desynchronizes the device from the configuration port
+
+* Status register provides detail of start-up phases and which signals are asserted
+
+Other
+-----
+* ECC of frame data is contained in word 50 alongside horizontal clock row configuration
+* Loading will succeed even with incorrect ECC data
+* ECC is primarily used for runtime bit-flip detection

docs/architecture/glossary.rst

@@ -20,6 +20,11 @@ Glossary
     Contains configuration :term:`frames <frame>` as well as programming
     sequences and other commands required to load and activate same.
 
+  clock domain
+    Portion of a :term:`horizontal clock row` to one side of the global clock
+    spine. Often refers to :term:`tiles <tile>` that are associated with these
+    clocks.
+
   column
     Collection of :term:`tiles <tile>` physically organized as a vertical line.
 

docs/index.rst

@@ -18,4 +18,6 @@ to develop a free and open Verilog to bitstream toolchain for these devices.
    :caption: Xilinx 7-series Architecture
 
    architecture/overview
+   architecture/configuration
+   architecture/bitstream_format
    architecture/glossary