Rst docs conversion (#3496)

Rst docs conversion

1 files changed, 141 insertions, 0 deletions

diff --git a/docs/source/CHAPTER_Approach.rst b/docs/source/CHAPTER_Approach.rst
new file mode 100644
index 000000000..32980e788
--- /dev/null
+++ b/docs/source/CHAPTER_Approach.rst
@@ -0,0 +1,141 @@
+.. _chapter:approach:
+
+Approach
+========
+
+Yosys is a tool for synthesising (behavioural) Verilog HDL code to target
+architecture netlists. Yosys aims at a wide range of application domains and
+thus must be flexible and easy to adapt to new tasks. This chapter covers the
+general approach followed in the effort to implement this tool.
+
+Data- and control-flow
+----------------------
+
+The data- and control-flow of a typical synthesis tool is very similar to the
+data- and control-flow of a typical compiler: different subsystems are called in
+a predetermined order, each consuming the data generated by the last subsystem
+and generating the data for the next subsystem (see :numref:`Fig. %s
+<fig:approach_flow>`).
+
+.. figure:: ../images/approach_flow.*
+	:class: width-helper
+	:name: fig:approach_flow
+
+	General data- and control-flow of a synthesis tool
+
+The first subsystem to be called is usually called a frontend. It does not
+process the data generated by another subsystem but instead reads the user
+input—in the case of a HDL synthesis tool, the behavioural HDL code.
+
+The subsystems that consume data from previous subsystems and produce data for
+the next subsystems (usually in the same or a similar format) are called passes.
+
+The last subsystem that is executed transforms the data generated by the last
+pass into a suitable output format and writes it to a disk file. This subsystem
+is usually called the backend.
+
+In Yosys all frontends, passes and backends are directly available as commands
+in the synthesis script. Thus the user can easily create a custom synthesis flow
+just by calling passes in the right order in a synthesis script.
+
+Internal formats in Yosys
+-------------------------
+
+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.
+
+.. _sec:typusecase:
+
+Typical use case
+----------------
+
+The following example script may be used in a synthesis flow to convert the
+behavioural Verilog code from the input file design.v to a gate-level netlist
+synth.v using the cell library described by the Liberty file :
+
+.. code:: yoscrypt
+   :number-lines:
+
+   # read input file to internal representation
+   read_verilog design.v
+
+   # convert high-level behavioral parts ("processes") to d-type flip-flops and muxes
+   proc
+
+   # perform some simple optimizations
+   opt
+
+   # convert high-level memory constructs to d-type flip-flops and multiplexers
+   memory
+
+   # perform some simple optimizations
+   opt
+
+   # convert design to (logical) gate-level netlists
+   techmap
+
+   # perform some simple optimizations
+   opt
+
+   # map internal register types to the ones from the cell library
+   dfflibmap -liberty cells.lib
+
+   # use ABC to map remaining logic to cells from the cell library
+   abc -liberty cells.lib
+
+   # cleanup
+   opt
+
+   # write results to output file
+   write_verilog synth.v
+
+A detailed description of the commands available in Yosys can be found in
+:ref:`cmd_ref`.
+
+.. [1]
+   In Yosys the term pass is only used to refer to commands that operate on the
+   RTLIL data structure.