Merge pull request #756 from mithro/README-update

Lots of updates to documentation

docs/Makefile

@@ -23,17 +23,18 @@ fuzzers-links:
 	@cd db_dev_process/fuzzers; rm -f *.md
 	@cd db_dev_process/fuzzers; \
 		for i in ../../../fuzzers/*; do \
+			n=$$(basename $$i | sed -e's/^[0-9][0-9][0-9]-//'); \
 			if [ ! -d $$i ]; then \
 				continue; \
 			fi; \
 			if [ -e $$i/README.md ]; then \
 				echo "Linking $$i/README.md"; \
-				ln -s $$i/README.md $$(basename $$i).md; \
+				ln -s $$i/README.md $${n}.md; \
 			else \
 				echo "Missing $$i/README.md"; \
-				echo "# $$(basename $$i)" 	> $$(basename $$i).md; \
-				echo "" 			>> $$(basename $$i).md; \
-				echo "Missing README.md!" 	>> $$(basename $$i).md; \
+				echo "# $$n Fuzzer"		>  $${n}.md; \
+				echo "" 			>> $${n}.md; \
+				echo "Missing README.md!" 	>> $${n}.md; \
 			fi; \
 		done
 
@@ -41,17 +42,18 @@ minitests-links:
 	@cd db_dev_process/minitests; rm -f *.md
 	@cd db_dev_process/minitests; \
 		for i in ../../../minitests/*; do \
+			n=$$(basename $$i | sed -e's/^[0-9][0-9][0-9]-//'); \
 			if [ ! -d $$i ]; then \
 				continue; \
 			fi; \
 			if [ -e $$i/README.md ]; then \
 				echo "Linking $$i/README.md"; \
-				ln -s $$i/README.md $$(basename $$i).md; \
+				ln -s $$i/README.md $${n}.md; \
 			else \
 				echo "Missing $$i/README.md"; \
-				echo "# $$(basename $$i)" 	> $$(basename $$i).md; \
-				echo "" 			>> $$(basename $$i).md; \
-				echo "Missing README.md!" 	>> $$(basename $$i).md; \
+				echo "# $$n Minitest"		>  $${n}.md; \
+				echo "" 			>> $${n}.md; \
+				echo "Missing README.md!" 	>> $${n}.md; \
 			fi; \
 		done
 

docs/architecture/dram_configuration.rst

@@ -1,10 +1,13 @@
-DRAM configuration
-==================
+Distributed RAMs (DRAM / SLICEM)
+================================
 
 The SLICEM site can turn the 4 LUT6s into distributed RAMs.  There are a number of modes, each element is either a 64x1 or a 32x2 distributed RAM (DRAM).  The individual elements can be combined into either a 128x1 or 256x1 DRAM.
 
+Functions
+---------
+
 Modes
------
+~~~~~
 Some modes can be enabled at the single LUT level.  The following modes are:
 
 - 32x2 Single port (32x2S)
@@ -19,7 +22,7 @@ Some modes are SLICEM wide:
 - 256x1
 
 Ports
------
+~~~~~
 
 Each LUT element when operating in RAM mode is a DPRAM64.
 
@@ -27,7 +30,7 @@ Each LUT element when operating in RAM mode is a DPRAM64.
 | Port name  | Direction  | Width     | Description  |
 +============+============+===========+==============+
 | WA         | IN         | 8         | Write address|
-+------------+------------+-----------+--------------+ 
++------------+------------+-----------+--------------+
 | A          | IN         | 6         | Read address |
 +------------+------------+-----------+--------------+
 | DI         | IN         | 2         | Data input   |
@@ -42,7 +45,7 @@ Each LUT element when operating in RAM mode is a DPRAM64.
 +------------+------------+-----------+--------------+
 
 Configuration
-=============
+-------------
 
 The configuration for the DRAM is found in the following segbits:
 
@@ -64,7 +67,7 @@ In order to use DRAM in a SLICEM, the DLUT in the SLICEM must be a RAM (e.g. DLU
 In addition the DLUT can never be a dual port RAM because the write address lines for the DLUT are also the read address lines.
 
 Segbits for modes
------------------
+~~~~~~~~~~~~~~~~~
 
 The following table shows the features required for each mode type for each LUT.
 
@@ -95,7 +98,7 @@ The following table shows the features required for each mode type for each LUT.
 +------+------------+------------+------------+----------+
 
 Ports for modes
----------------
+~~~~~~~~~~~~~~~
 
 In each mode, how the ports are used vary.  The following table show the relationship between the LUT mode and ports.
 
@@ -127,7 +130,7 @@ In each mode, how the ports are used vary.  The following table show the relatio
 
 
 Techlib macros
---------------
+~~~~~~~~~~~~~~
 
 The tech library exposes the following aggregate modes, which are accomplished with the following combinations.
 

docs/db_dev_process/fuzzers/005-tilegrid.md

@@ -1 +0,0 @@
-../../../fuzzers/005-tilegrid/README.md

docs/db_dev_process/parts.rst

@@ -1,17 +1,6 @@
-Overview
-=========
-
-SymbiFlow/symbiflow-arch-defs
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-This is where we describe the logical components in a device to VPR.
-
-* VtR stands for `Verilog to Routing <https://verilogtorouting.org/>`_,
-* VPR stands for VtR Place and Route.
-* VtR also has its own synthesis tool called ODIN-II, but we are using `Yosys <https://github.com/YosysHQ/yosys>`_ instead of that.
-  
 
 Fuzzers
-^^^^^^^
+=======
 Fuzzers are things that generate a design, feed it to Vivado, and look at the resulting bitstream to make some conclusion.
 This is how the contents of the database are generated.
 
@@ -25,15 +14,95 @@ By looking at all the resulting specimens, you can correlate which bits in which
 
 Looking at the implemented design in Vivado with "Show Routing Resources" turned on is quite helpful in understanding what all choices exist.
 
+Configurable Logic Blocks (CLB)
+-------------------------------
+
+.. toctree::
+   :maxdepth: 1
+   :glob:
+
+   fuzzers/*clb*
+
+Block RAM (BRAM)
+----------------
+
+.. toctree::
+   :maxdepth: 1
+   :glob:
+
+   fuzzers/*bram*
+
+Input / Output (IOB)
+--------------------
+
+.. toctree::
+   :maxdepth: 1
+   :glob:
+
+   fuzzers/*iob*
+
+Clocking (CMT, PLL, BUFG, etc)
+------------------------------
+
+.. toctree::
+   :maxdepth: 1
+   :glob:
+
+   fuzzers/*clk*
+   fuzzers/*cmt*
+
+Programmable Interconnect Points (PIPs)
+---------------------------------------
+
+.. toctree::
+   :maxdepth: 1
+   :glob:
+
+   fuzzers/*int*
+   fuzzers/*pip*
+
+Hard Block Fuzzers
+------------------
+
+.. toctree::
+   :maxdepth: 1
+   :glob:
+
+   fuzzers/*xadc
+
+Grid and Wire
+-------------
+
+.. toctree::
+   :maxdepth: 1
+   :glob:
+
+   fuzzers/tilegrid
+   fuzzers/tileconn
+   fuzzers/ordered_wires
+   fuzzers/get_counts
+   fuzzers/dump_all
+
+Timing
+------
+
+.. toctree::
+   :maxdepth: 1
+   :glob:
+
+   fuzzers/timing
+
+All Fuzzers
+-----------
+
 .. toctree::
    :maxdepth: 1
-   :caption: Current Fuzzers
    :glob:
 
    fuzzers/*
 
 Minitests
-^^^^^^^^^
+=========
 
 Minitests are experiments to figure out how things work. They allow us to understand how to better write new fuzzers.
 
@@ -45,12 +114,8 @@ Minitests are experiments to figure out how things work. They allow us to unders
    minitests/*
 
 Tools
-^^^^^
+=====
 
 `SymbiFlow/prjxray/tools/`
 
 Here, you can find various programs to work with bitstreams, mainly to assist building fuzzers.
-
-SymbiFlow/prjxray/minitests/roi_harness
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-Shows how to use a bunch of tools together to patch an existing bitstream with hand-crafted FASM (FPGA assembler).

docs/db_dev_process/readme.md

@@ -0,0 +1 @@
+../../README.md

docs/format/db.rst

@@ -1,17 +1,20 @@
+.db Files
+=========
+
 Introduction
-================
+------------
 
 This section documents how prjxray represents the bitstream database
 
 These ".db" files come in two common flavors:
- * segbits_*.db: encodes bitstream bits
- * mask_*.db: which bits are used by a segment? Probably needs to be converted to tile
+ * `segbits_*.db`_: encodes bitstream bits
+ * `mask_*.db`_: which bits are used by a segment? Probably needs to be converted to tile
 
 Also note: .rdb (raw db) is a convention for a non-expanded .db file (see below)
 
 
-segbits
-================
+segbits_*.db
+------------
 
 These are created by segmatch to describe bitstream IP encoding.
 
@@ -55,8 +58,8 @@ Related tools:
    * Ex: CLB is solved by first solving LUT bits, and then solving FF bits
 
 
-mask
-================
+mask_*.db
+---------
 
 These are just simple bit lists
 

docs/format/tile.rst

@@ -1,5 +1,8 @@
+.json Files
+===========
+
 Introduction
-================
+------------
 
 This section documents how prjxray represents FPGA fabric. Its primarily composed of two files:
  * tilegrid.json: list of tiles and how they appear in the bitstream
@@ -11,29 +14,29 @@ General notes:
 
 
 tilegrid.json
-================
+-------------
 
 This section assumes you are already familiar with the 7 series bitstream format.
 
 This file contains two elements:
  * segments: each entry lists sections of the bitstream that encode part of one or more tiles
- * tiles: corres
+ * tiles: cores
 
-segments  
-################
+segments
+########
 
 Segments are a prjxray concept.
 
 Each entry has the following fields:
  * baseaddr: a tuple of (base address, inter-frame offset)
  * frames: how many frames are required to make a complete segment
- * words: number of inter-frame words requird for a complete segment
+ * words: number of inter-frame words required for a complete segment
  * tiles: which tiles reference this segment
  * type: prjxray given segment type
 
 Sample entry:
 
-.. code-block:: json
+.. code-block:: javascript
 
 	"SEG_CLBLL_L_X16Y149": {
 		"baseaddr": [
@@ -56,7 +59,7 @@ Interpreted as:
   * Since its 2 FDRI words out of possible 101, its the last 2 words
   * It spans across 36 different frame loads
   * The data in this segment is used by two different tiles: CLBLL_L_X16Y149, INT_L_X16Y149
-  
+
 Historical note:
 In the original encoding, a segment was a collection of tiles that were encoded together.
 For example, a CLB is encoded along with a nearby switch.
@@ -65,7 +68,7 @@ the configuration and data are stored in seperate parts of the bitstream.
 The BRAM itself also spans multiple tiles and has multiple switchboxes.
 
 tiles
-################
+#####
 
 Each entry has the following fields:
  * grid_x: tile column, increasing right
@@ -74,11 +77,9 @@ Each entry has the following fields:
  * sites: dictionary of sites name: site type contained within tile
  * type: Vivado given tile type
 
-
-
 Sample entry:
 
-.. code-block:: json
+.. code-block:: javascript
 
 	"CLBLL_L_X16Y149": {
 		"grid_x": 43,
@@ -97,9 +98,8 @@ Interpreted as:
  * Contains two sites, both of which are SLICEL
  * A CLBLL_L type tile
 
-
 tileconn.json
-================
+-------------
 
 This file documents how adjacent tile pairs are connected.
 No directionality is given.
@@ -111,7 +111,7 @@ The file contains one large list. Each entry has the following fields:
 
 Sample entry:
 
-.. code-block:: json
+.. code-block:: javascript
 
 	{
 		"grid_deltas": [

docs/index.rst

@@ -27,10 +27,12 @@ to develop a free and open Verilog to bitstream toolchain for these devices.
    :maxdepth: 2
    :caption: Database Development Process
 
-   db_dev_process/overview
+   db_dev_process/readme
+   db_dev_process/parts
 
 .. toctree::
    :maxdepth: 2
    :caption: Output File Formats
 
+   format/db
    format/tile