docs: Improving docs after significant fuzzing

Signed-off-by: David Shah <davey1576@gmail.com>

docs/architecture/general_routing.rst

@@ -1,2 +1,32 @@
 General Routing
 ===============
+
+The ECP5's general routing is unidirectional and relatively straightforward. They are detailed below. The inputs and
+outputs of the routing inside tiles are:
+
+ - The inputs to BELs are named **A0**-**A7**, **B0**-**B7**, **C0**-**C7**, **D0**-**D7** (LUT inputs),
+   **M0**-**M7** ("miscellaneous" inputs for muxes and other functions); **LSR0** and **LSR1** (local set/reset);
+   **CLK0** and **CLK1** (clock) and **CE0**-**CE3** (clock enable), for logic tiles.
+
+ - The outputs are named **F0** to **F7** (LUT outputs) and **Q0** to **Q7** (FF outputs).
+
+ - CIB tiles have an identical routing configuration to logic tiles, regardless of what they connect to  - effectively,
+   the logic slices are replaced by the special function - however, all the netnames aboved are prefixed with **J**.
+   Fixed arcs connect the CIB signals to the signals inside the special function tile.
+
+Four types of routing resource are available:
+
+ - 8 ***X0** wires inside each tile (**H00L0x00**, **H00R0x00**, **V00T0x00**, and **V00B0x00**) do not leave a tile,
+   but can be driven from a variety of internal and external signals; and all of the horizontal or vertical signals
+   are inputs to all of the BEL input muxes.
+ - 8 **X1** "neighbour" wires originate, and terminate, in each tile (**H01E0x01**, **H01W0x00**, **V01S0x00** and
+   **V01N0x01**). These connect together adjacent tiles in the specified direction, and can be driven by any of the
+   LUT or FF outputs as well as a few other signals.
+ - 32 **X2** span-2 wires (**H02E0x01**, **H02W0x01**, **V02S0x01** and **V02N0x01**) originate in each tile, each
+   connecting to the two next tiles in a given direction.
+ - 16 **X6** span-6 wires (**H06E0x03**, **H06W0x03**, **V06S0x03** and **V06N0x03**) originate in each tile
+   connecting to two tiles, with a gap of 2 inbetween each, in a given direction.
+
+In all cases, wires can only be driven inside one tile. **X2** and **X6** inputs only drive muxes in tiles other than
+the tile they originate in; whereas **X0** and **X1** also "bounce back" internally (this being the very purpose of
+**X0** tiles).

docs/architecture/global_routing.rst

@@ -96,8 +96,7 @@ capability in them.
 
 The inputs to spine tiles from the quadrant's centre mux are named **qqPCLK0** through **qqPCLK15**.
 
-The outputs are named **LHPRX0000** through **LHPRX15000** for left side spine tiles, and **RHPRX0000** through
-**RHPRX1500** for right side spine tiles, which feed one row of TAP_DRIVEs.
+The outputs are named **VPTX0000** through **VPTX15000**, which feed a column of tap drives.
 
 TAP_DRIVE Tiles
 ---------------
@@ -110,9 +109,8 @@ about 20 tiles, 10 to the left and 10 to the right.
 Like spine tiles, TAP_DRIVE tiles have a 1:1 input-output mapping and only offer the ability to turn on/of buffers
 to save power.
 
-The inputs to the TAP_DRIVE tiles from the spine are named **HPRX0000** through **HPRX1500**. The outputs feeding
-tiles to the left are named **LVPTX0000** through **LVPTX1500**, and the outputs feeding tiles to the right are named
-**RVPTX0000** through **RVPTX1500**.
+The outputs are named **HPBX0000** through **HPBX15000**, with a net location on the left or right for the left or
+right outputs (signified as **L_** or **R_** in the Project Trellis database.
 
 Non-Clock Global Usage
 -----------------------
@@ -155,4 +153,4 @@ Not all globals can be used for all functions, the allowed usage depending on ne
 | 14     | Y   | Y   | Y   |       |
 +--------+-----+-----+-----+-------+
 | 15     | Y   | Y   | Y   |       |
-+--------+-----+-----+-----+-------+
++--------+-----+-----+-----+-------+

docs/db_dev_process/overview.rst

@@ -57,3 +57,56 @@ The NCL file contains information about the device, components and routing (rout
 this was from a LUT initialisation fuzzer, ${lut_func} will be replaced by a function corresponding to the LUT init bit
 to be fuzzed (NCL files require an expression for LUT initialisation, rather than a series of bits).
 
+Fuzzers
+--------
+
+There are three types of fuzzer in use in Project Trellis. They are routing fuzzers, non-routing fuzzers and
+meta-fuzzers.
+
+Routing fuzzers use the helper functions in ``util/fuzz/nonrouting.py``. These will generally follow the following
+algorithm:
+
+ - Use the Tcl API to discover all of the netnames at the target location
+
+ - Use the Tcl API to discover the arcs associated with those netnames
+
+ - Apply filters to remove netnames and/or arcs not applicable to the current fuzzer
+
+    - For example, when fuzzing a CIB_EBR you would ensure to include CIB signals but exclude EBR signals
+    - When fuzzing a EBR you would conversely filter out the CIB signals and include EBR signals.
+
+ - Create a reference "empty" bitstream
+
+ - For every arc discovered above:
+
+    - Create a bitstream containing the arc using a NCL file
+    - Compare the bitstream against the empty bitstream:
+
+       - If there was a change outside the tile(s) of interest, the arc is ignored
+       - If there was a change to any of the tile(s) of interest, add a configurable mux arc to the database of the
+         relevant tile
+       - If there was no change at all, add the arc as a fixed connection to the database of the first specified tile
+
+Note that routing fuzzers for special function tiles (such as PIO, EBR, etc) are primarily intended to find fixed
+connections to CIBs and within special functions rather than significant amounts of configurable routing, but the above
+algorithm is still used for consistency (and because it is not possible to know a priori whether an arc is configurable
+or fixed).
+
+Non-routing fuzzers are intended to fuzz configuration such as LUT initialisation, flip-flop settings or IO type. It is
+possible to fuzz either words or enums. Words are for settings that naturally comprise of one or more bits, such as
+LUT initialisation. Enums are for settings with multiple textual values.
+
+The algorithm for word settings is to create one bitstream for each word bit with that bit set, and compare to an all-zero
+bitstream to determine the change for that bit. These are also optionally compared against an empty bitstream with
+the setting/feature entirely missing to determine a default value, which is not always all-zeros.
+
+The algorithm for enum settings is to create bitstreams with all possible enum values, in each case storing the CRAM of
+all tiles of interest. These are then compared to determine the set of bits affected by the enum, and in each case
+the bit values for each possible enum value.
+
+Creating non-routing requires more work than routing fuzzers. The settings of interest, possible values, and how to
+create them in the Ncl or Verilog input must all be included in the fuzzer script.
+
+Finally meta-fuzzers do not do any fuzzing but perform other necessary manipulations on the database during the fuzzing
+flow. For example, these may copy config bits from one tile to other tile types which have identical configuration in
+order to reduce the time needed for fuzzing.