diff --git a/docs/Makefile b/docs/Makefile
index bd71d27c..7f638e50 100644
--- a/docs/Makefile
+++ b/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
diff --git a/docs/_static/.keepme b/docs/_static/.keepme
new file mode 100644
index 00000000..e69de29b
diff --git a/docs/architecture/dram_configuration.rst b/docs/architecture/dram_configuration.rst
index 19c0bf31..642f1c9d 100644
--- a/docs/architecture/dram_configuration.rst
+++ b/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.
diff --git a/docs/db_dev_process/fuzzers/005-tilegrid.md b/docs/db_dev_process/fuzzers/005-tilegrid.md
deleted file mode 120000
index 6e65a4da..00000000
--- a/docs/db_dev_process/fuzzers/005-tilegrid.md
+++ /dev/null
@@ -1 +0,0 @@
-../../../fuzzers/005-tilegrid/README.md
\ No newline at end of file
diff --git a/docs/db_dev_process/overview.rst b/docs/db_dev_process/parts.rst
similarity index 60%
rename from docs/db_dev_process/overview.rst
rename to docs/db_dev_process/parts.rst
index 049b6efb..63ac0929 100644
--- a/docs/db_dev_process/overview.rst
+++ b/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 `_,
-* VPR stands for VtR Place and Route.
-* VtR also has its own synthesis tool called ODIN-II, but we are using `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).
diff --git a/docs/db_dev_process/readme.md b/docs/db_dev_process/readme.md
new file mode 120000
index 00000000..fe840054
--- /dev/null
+++ b/docs/db_dev_process/readme.md
@@ -0,0 +1 @@
+../../README.md
\ No newline at end of file
diff --git a/docs/format/db.rst b/docs/format/db.rst
index 6c5885f4..fd6a7e71 100644
--- a/docs/format/db.rst
+++ b/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
diff --git a/docs/format/tile.rst b/docs/format/tile.rst
index 767b2cfe..980325ce 100644
--- a/docs/format/tile.rst
+++ b/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": [
diff --git a/docs/index.rst b/docs/index.rst
index d9b51b79..33975ebe 100644
--- a/docs/index.rst
+++ b/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