diff --git a/docs/source/yosys_internals/formats/rtlil_text.rst b/docs/source/appendix/rtlil_text.rst similarity index 98% rename from docs/source/yosys_internals/formats/rtlil_text.rst rename to docs/source/appendix/rtlil_text.rst index 8b5c10681..7febae2ed 100644 --- a/docs/source/yosys_internals/formats/rtlil_text.rst +++ b/docs/source/appendix/rtlil_text.rst @@ -223,8 +223,8 @@ Cells Declares a cell, with zero or more attributes, with the given identifier and type in the enclosing module. -Cells perform functions on input signals. See -:doc:`/yosys_internals/formats/cell_library` for a detailed list of cell types. +Cells perform functions on input signals. See :doc:`/cell_gate` and +:doc:`/cell_word` for a detailed list of cell types. .. code:: BNF diff --git a/docs/source/index.rst b/docs/source/index.rst index ce612f9b0..fbdd5ac6f 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -44,6 +44,7 @@ available, go to :ref:`commandindex`. :includehidden: appendix/primer + appendix/rtlil_text appendix/auxlibs appendix/auxprogs diff --git a/docs/source/yosys_internals/flow/overview.rst b/docs/source/yosys_internals/flow/overview.rst index b357e5b50..3effe462b 100644 --- a/docs/source/yosys_internals/flow/overview.rst +++ b/docs/source/yosys_internals/flow/overview.rst @@ -20,7 +20,7 @@ given in :doc:`/yosys_internals/formats/rtlil_rep`. There is also a text representation of the RTLIL data structure that can be parsed using the RTLIL Frontend which is described in -:doc:`/yosys_internals/formats/rtlil_text`. +:doc:`/appendix/rtlil_text`. The design data may then be transformed using a series of passes that all operate on the RTLIL representation of the design. diff --git a/docs/source/yosys_internals/formats/index.rst b/docs/source/yosys_internals/formats/index.rst index c187a8238..611370ebc 100644 --- a/docs/source/yosys_internals/formats/index.rst +++ b/docs/source/yosys_internals/formats/index.rst @@ -1,13 +1,59 @@ Internal formats ================ -.. todo:: brief overview for the internal formats index +Yosys uses two different internal formats. The first is used to store an +abstract syntax tree (AST) of a Verilog input file. This format is simply called +AST and is generated by the Verilog Frontend. This data structure is consumed by +a subsystem called AST Frontend [1]_. This AST Frontend then generates a design +in Yosys' main internal format, the +Register-Transfer-Level-Intermediate-Language (RTLIL) representation. It does +that by first performing a number of simplifications within the AST +representation and then generating RTLIL from the simplified AST data structure. + +The RTLIL representation is used by all passes as input and outputs. This has +the following advantages over using different representational formats between +different passes: + +- The passes can be rearranged in a different order and passes can be removed + or inserted. + +- Passes can simply pass-thru the parts of the design they don't change without + the need to convert between formats. In fact Yosys passes output the same + data structure they received as input and performs all changes in place. + +- All passes use the same interface, thus reducing the effort required to + understand a pass when reading the Yosys source code, e.g. when adding + additional features. + +The RTLIL representation is basically a netlist representation with the +following additional features: + +- An internal cell library with fixed-function cells to represent RTL datapath + and register cells as well as logical gate-level cells (single-bit gates and + registers). + +- Support for multi-bit values that can use individual bits from wires as well + as constant bits to represent coarse-grain netlists. + +- Support for basic behavioural constructs (if-then-else structures and + multi-case switches with a sensitivity list for updating the outputs). + +- Support for multi-port memories. + +The use of RTLIL also has the disadvantage of having a very powerful format +between all passes, even when doing gate-level synthesis where the more advanced +features are not needed. In order to reduce complexity for passes that operate +on a low-level representation, these passes check the features used in the input +RTLIL and fail to run when unsupported high-level constructs are used. In such +cases a pass that transforms the higher-level constructs to lower-level +constructs must be called from the synthesis script first. .. toctree:: - :maxdepth: 3 + :maxdepth: 3 - overview - rtlil_rep - rtlil_text - cell_library + rtlil_rep + +.. [1] + In Yosys the term pass is only used to refer to commands that operate on the + RTLIL data structure. diff --git a/docs/source/yosys_internals/formats/overview.rst b/docs/source/yosys_internals/formats/overview.rst deleted file mode 100644 index cbf5369bc..000000000 --- a/docs/source/yosys_internals/formats/overview.rst +++ /dev/null @@ -1,53 +0,0 @@ -Format overview -=============== - -Yosys uses two different internal formats. The first is used to store an -abstract syntax tree (AST) of a Verilog input file. This format is simply called -AST and is generated by the Verilog Frontend. This data structure is consumed by -a subsystem called AST Frontend [1]_. This AST Frontend then generates a design -in Yosys' main internal format, the -Register-Transfer-Level-Intermediate-Language (RTLIL) representation. It does -that by first performing a number of simplifications within the AST -representation and then generating RTLIL from the simplified AST data structure. - -The RTLIL representation is used by all passes as input and outputs. This has -the following advantages over using different representational formats between -different passes: - -- The passes can be rearranged in a different order and passes can be removed - or inserted. - -- Passes can simply pass-thru the parts of the design they don't change without - the need to convert between formats. In fact Yosys passes output the same - data structure they received as input and performs all changes in place. - -- All passes use the same interface, thus reducing the effort required to - understand a pass when reading the Yosys source code, e.g. when adding - additional features. - -The RTLIL representation is basically a netlist representation with the -following additional features: - -- An internal cell library with fixed-function cells to represent RTL datapath - and register cells as well as logical gate-level cells (single-bit gates and - registers). - -- Support for multi-bit values that can use individual bits from wires as well - as constant bits to represent coarse-grain netlists. - -- Support for basic behavioural constructs (if-then-else structures and - multi-case switches with a sensitivity list for updating the outputs). - -- Support for multi-port memories. - -The use of RTLIL also has the disadvantage of having a very powerful format -between all passes, even when doing gate-level synthesis where the more advanced -features are not needed. In order to reduce complexity for passes that operate -on a low-level representation, these passes check the features used in the input -RTLIL and fail to run when unsupported high-level constructs are used. In such -cases a pass that transforms the higher-level constructs to lower-level -constructs must be called from the synthesis script first. - -.. [1] - In Yosys the term pass is only used to refer to commands that operate on the - RTLIL data structure. \ No newline at end of file