From 1b296ea876677e62ebb2642e80f63ee7951e35ae Mon Sep 17 00:00:00 2001 From: Robert Winkler Date: Mon, 2 Mar 2020 14:05:09 +0100 Subject: [PATCH] New structure of project documentation Signed-off-by: Robert Winkler --- docs/architecture/index.rst | 16 +++++++++ docs/db_dev_process/index.rst | 13 +++++++ docs/format/index.rst | 8 +++++ docs/getting.rst | 6 ++++ docs/index.rst | 45 +++++++++++------------ docs/introduction.rst | 67 +++++++++++++++++++++++++++++++++++ 6 files changed, 130 insertions(+), 25 deletions(-) create mode 100644 docs/architecture/index.rst create mode 100644 docs/db_dev_process/index.rst create mode 100644 docs/format/index.rst create mode 100644 docs/getting.rst create mode 100644 docs/introduction.rst diff --git a/docs/architecture/index.rst b/docs/architecture/index.rst new file mode 100644 index 00000000..9701bdf0 --- /dev/null +++ b/docs/architecture/index.rst @@ -0,0 +1,16 @@ +============================ +Xilinx 7-series Architecture +============================ + +.. toctree:: + :maxdepth: 1 + + overview + configuration + bitstream_format + interconnect + dram_configuration + glossary + reference + code_of_conduct + updating_the_docs diff --git a/docs/db_dev_process/index.rst b/docs/db_dev_process/index.rst new file mode 100644 index 00000000..9fab0542 --- /dev/null +++ b/docs/db_dev_process/index.rst @@ -0,0 +1,13 @@ +============================ +Database Development Process +============================ + +.. toctree:: + :maxdepth: 1 + + readme + contributing + fuzzers/index + minitests/index + parts + diff --git a/docs/format/index.rst b/docs/format/index.rst new file mode 100644 index 00000000..6f1fd211 --- /dev/null +++ b/docs/format/index.rst @@ -0,0 +1,8 @@ +============ +Output Files +============ + +.. toctree:: + + db + tile.rst diff --git a/docs/getting.rst b/docs/getting.rst new file mode 100644 index 00000000..0f7848de --- /dev/null +++ b/docs/getting.rst @@ -0,0 +1,6 @@ +=============== +Getting Started +=============== + +.. toctree:: + db_dev_process/readme diff --git a/docs/index.rst b/docs/index.rst index a933d114..b6654438 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,10 +1,6 @@ -.. Project X-Ray documentation master file, created by - sphinx-quickstart on Mon Feb 5 11:04:37 2018. - You can adapt this file completely to your liking, but it should at least - contain the root `toctree` directive. - -Welcome to Project X-Ray -========================================= +============= +Project X-Ray +============= `Project X-Ray`_ documents the `Xilinx`_ 7-Series FPGA architecture to enable development of open-source tools. Our goal is to provide sufficient information @@ -15,31 +11,30 @@ to develop a free and open Verilog to bitstream toolchain for these devices. .. toctree:: :maxdepth: 2 - :caption: Xilinx 7-series Architecture + :caption: Introduction - architecture/overview - architecture/configuration - architecture/bitstream_format - architecture/interconnect - architecture/dram_configuration - architecture/glossary - architecture/reference - architecture/code_of_conduct - architecture/updating_the_docs + introduction + +.. toctree:: + :maxdepth: 2 + :caption: Getting Started + + getting + +.. toctree:: + :maxdepth: 2 + :caption: Xilinx 7-Series Architecture + + architecture/index .. toctree:: :maxdepth: 2 :caption: Database Development Process - db_dev_process/readme - db_dev_process/contributing - db_dev_process/fuzzers/index - db_dev_process/minitests/index - db_dev_process/parts + db_dev_process/index .. toctree:: :maxdepth: 2 - :caption: Output File Formats + :caption: Output Formats - format/db - format/tile + format/index diff --git a/docs/introduction.rst b/docs/introduction.rst new file mode 100644 index 00000000..88c5b026 --- /dev/null +++ b/docs/introduction.rst @@ -0,0 +1,67 @@ +============ +Introduction +============ + +`Project X-Ray`_ documents the `Xilinx`_ 7-Series FPGA architecture to enable +the development of open-source tools. Our goal is to provide sufficient information +to develop a free and open Verilog to bitstream toolchain for these devices. + +The project is a part of SymbiFlow Toolchain. `SymbiFlow`_ uses the obtained +information about the chip in `Architecture Definitions`_ project, which +allows for creating bitstreams for many architectures including 7-Series devices. + +Collected information +--------------------- + +To allow the usage of Xilinx FPGAs in SymbiFlow toolchain we collect some +important data about the Xilinx chips. The needed information includes: + + - Architecture description: + + * chip internals + * timings + + - Bitstream format: + + * metadata (i.e. header, crc) + * configuration bits + +Final results are stored in the database which is further used by the +`Architecture Definitions`_ project. The whole database is described in +the dedicated :doc:`chapter `. + +Methodology +----------- + +The most important element of the project are fuzzers - scripts responsible +for obtaining information about the chips. Their name comes from the fact that +they use a similar idea to `Fuzz testing`_. Firstly, they generate a huge +amount of designs in which the examined chip property is either enabled or +disabled. By comparing the differences in the final bitstream obtained +from vendor tools, we can detect relations between bits in the bitstream and +provided functionalities. + +However, some of the fuzzers works differently, i.e. they just creating +the database structure, the whole idea is similar and rely on the output produced +by the vendor tools. + +All fuzzers are described in the dedicated :doc:`chapter `. + +.. _Fuzz testing: https://en.wikipedia.org/wiki/Fuzzing + +Important Parts +--------------- + +The important parts of the `Project X-Ray` are: + + - *minitests* - designs that can be viewed by a human in Vivado to better + understand how to generate more useful designs. + - *experiments* - similar to *minitests* except for the fact that they are only + useful for a short time. + - *tools & libs* - they convert the resulting bitstreams into various formats. + - *utils* - tools that are used but still require some testing + +.. _Project X-Ray: https://github.com/SymbiFlow/prjxray +.. _Xilinx: http://www.xilinx.com/ +.. _SymbiFlow: https://symbiflow.readthedocs.io/ +.. _Architecture Definitions: https://github.com/SymbiFlow/symbiflow-arch-defs