From cd7bcf4875c56cc9454e13cc566d898af0a5a13f Mon Sep 17 00:00:00 2001 From: Tim 'mithro' Ansell Date: Thu, 4 Apr 2019 10:07:59 -0700 Subject: [PATCH 1/9] docs: Fixing headers levels. Signed-off-by: Tim 'mithro' Ansell --- docs/architecture/dram_configuration.rst | 19 +++++++++++-------- 1 file changed, 11 insertions(+), 8 deletions(-) diff --git a/docs/architecture/dram_configuration.rst b/docs/architecture/dram_configuration.rst index 19c0bf31..2bdbe2f3 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. @@ -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. From 487b28c43bb8288788aabacee1ca1dca7c14c8c2 Mon Sep 17 00:00:00 2001 From: Tim 'mithro' Ansell Date: Thu, 4 Apr 2019 10:08:39 -0700 Subject: [PATCH 2/9] docs: Fix arch-defs header. Signed-off-by: Tim 'mithro' Ansell --- docs/db_dev_process/overview.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/db_dev_process/overview.rst b/docs/db_dev_process/overview.rst index 049b6efb..7647e663 100644 --- a/docs/db_dev_process/overview.rst +++ b/docs/db_dev_process/overview.rst @@ -1,8 +1,8 @@ Overview ========= -SymbiFlow/symbiflow-arch-defs -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +`SymbiFlow Architecture Definitions `_ +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ This is where we describe the logical components in a device to VPR. * VtR stands for `Verilog to Routing `_, From 31ef5df168cff83cfb610642e5ce2e3cb7a13ce3 Mon Sep 17 00:00:00 2001 From: Tim 'mithro' Ansell Date: Thu, 4 Apr 2019 10:09:24 -0700 Subject: [PATCH 3/9] docs: Whitespace cleanup. Signed-off-by: Tim 'mithro' Ansell --- docs/architecture/dram_configuration.rst | 2 +- docs/db_dev_process/overview.rst | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/architecture/dram_configuration.rst b/docs/architecture/dram_configuration.rst index 2bdbe2f3..642f1c9d 100644 --- a/docs/architecture/dram_configuration.rst +++ b/docs/architecture/dram_configuration.rst @@ -30,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 | diff --git a/docs/db_dev_process/overview.rst b/docs/db_dev_process/overview.rst index 7647e663..2e9e2247 100644 --- a/docs/db_dev_process/overview.rst +++ b/docs/db_dev_process/overview.rst @@ -8,7 +8,7 @@ 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 ^^^^^^^ From 326860d634fbf5f3ee5ba4397970eeb1db4d20ac Mon Sep 17 00:00:00 2001 From: Tim 'mithro' Ansell Date: Thu, 4 Apr 2019 10:11:50 -0700 Subject: [PATCH 4/9] docs: Add database file format doc to TOC. Signed-off-by: Tim 'mithro' Ansell --- docs/index.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/index.rst b/docs/index.rst index d9b51b79..a90089f1 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -33,4 +33,5 @@ to develop a free and open Verilog to bitstream toolchain for these devices. :maxdepth: 2 :caption: Output File Formats + format/db format/tile From 0c0068697ae35326fb898be330cc385d1d927e73 Mon Sep 17 00:00:00 2001 From: Tim 'mithro' Ansell Date: Thu, 4 Apr 2019 10:17:28 -0700 Subject: [PATCH 5/9] docs: Fix header levels for format section. Signed-off-by: Tim 'mithro' Ansell --- docs/format/db.rst | 17 ++++++++++------- docs/format/tile.rst | 24 ++++++++++++------------ 2 files changed, 22 insertions(+), 19 deletions(-) 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..ff80a0cd 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,23 +14,23 @@ 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 @@ -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,8 +77,6 @@ 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 @@ -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. From ac97aa6f5ce42dc2e16b5b0ca8a4c19c19f5e77a Mon Sep 17 00:00:00 2001 From: Tim 'mithro' Ansell Date: Thu, 4 Apr 2019 10:21:07 -0700 Subject: [PATCH 6/9] docs: JSON highlighter doesn't exist, use Javascript instead. Signed-off-by: Tim 'mithro' Ansell --- docs/format/tile.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/format/tile.rst b/docs/format/tile.rst index ff80a0cd..980325ce 100644 --- a/docs/format/tile.rst +++ b/docs/format/tile.rst @@ -36,7 +36,7 @@ Each entry has the following fields: Sample entry: -.. code-block:: json +.. code-block:: javascript "SEG_CLBLL_L_X16Y149": { "baseaddr": [ @@ -79,7 +79,7 @@ Each entry has the following fields: Sample entry: -.. code-block:: json +.. code-block:: javascript "CLBLL_L_X16Y149": { "grid_x": 43, @@ -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": [ From eedeee16cbf7399bb5dfe4ffb331f98cbc7b7dfb Mon Sep 17 00:00:00 2001 From: Tim 'mithro' Ansell Date: Thu, 4 Apr 2019 11:15:53 -0700 Subject: [PATCH 7/9] docs: Import README add give fuzzers structures. Signed-off-by: Tim 'mithro' Ansell --- docs/Makefile | 18 +-- docs/db_dev_process/fuzzers/005-tilegrid.md | 1 - .../{overview.rst => parts.rst} | 103 ++++++++++++++---- docs/db_dev_process/readme.md | 1 + docs/index.rst | 5 +- 5 files changed, 98 insertions(+), 30 deletions(-) delete mode 120000 docs/db_dev_process/fuzzers/005-tilegrid.md rename docs/db_dev_process/{overview.rst => parts.rst} (60%) create mode 120000 docs/db_dev_process/readme.md 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/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 2e9e2247..63ac0929 100644 --- a/docs/db_dev_process/overview.rst +++ b/docs/db_dev_process/parts.rst @@ -1,17 +1,6 @@ -Overview -========= - -`SymbiFlow Architecture Definitions `_ -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -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/index.rst b/docs/index.rst index a90089f1..af8a9c47 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -24,10 +24,11 @@ to develop a free and open Verilog to bitstream toolchain for these devices. architecture/glossary .. toctree:: - :maxdepth: 2 + :maxdepth: 1 :caption: Database Development Process - db_dev_process/overview + db_dev_process/readme + db_dev_process/parts .. toctree:: :maxdepth: 2 From 51f62b8f0b867a95b997629cdb0a19d7d398d48c Mon Sep 17 00:00:00 2001 From: Tim 'mithro' Ansell Date: Thu, 4 Apr 2019 11:26:23 -0700 Subject: [PATCH 8/9] docs: Go back to 2 levels. Signed-off-by: Tim 'mithro' Ansell --- docs/index.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/index.rst b/docs/index.rst index af8a9c47..33975ebe 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -24,7 +24,7 @@ to develop a free and open Verilog to bitstream toolchain for these devices. architecture/glossary .. toctree:: - :maxdepth: 1 + :maxdepth: 2 :caption: Database Development Process db_dev_process/readme From 9872943486ae150de10a1813ff455dbc28152073 Mon Sep 17 00:00:00 2001 From: Tim 'mithro' Ansell Date: Thu, 4 Apr 2019 11:26:53 -0700 Subject: [PATCH 9/9] docs: Adding missing _static directory. Signed-off-by: Tim 'mithro' Ansell --- docs/_static/.keepme | 0 1 file changed, 0 insertions(+), 0 deletions(-) create mode 100644 docs/_static/.keepme diff --git a/docs/_static/.keepme b/docs/_static/.keepme new file mode 100644 index 00000000..e69de29b