Docs: some restructure of advanced section

- Filling out index descriptions for `using_yosys` and `using_yosys/synthesis`.
- To discourage skipping over these index pages, the toctree in
  `using_yosys/index` is hidden and instead has inline links to the two
  subsections.
- Tidying todos.
- Moves technology mapping to `techmap_synth`, leaving the techmap by example in
  the internals section. `yosys_flows` gets split up, with the coarse-grain
  intro replaced by `synthesis/index`, the extract pass moving to
  `synthesis/extract` and model checking to `more_scripting/model_checking`.

docs/source/using_yosys/synthesis/cell_libs.rst

@@ -73,8 +73,6 @@ Coarse-grain representation
 Logic gate mapping
 ~~~~~~~~~~~~~~~~~~
 
-.. TODO:: comment on similarities and/or differences with example_synth
-
 .. literalinclude:: /code_examples/intro/counter.ys
    :language: yoscrypt
    :lines: 14-15
@@ -89,8 +87,6 @@ Logic gate mapping
 Mapping to hardware
 ~~~~~~~~~~~~~~~~~~~
 
-.. todo:: are we recalling or is this new information
-
 For this example, we are using a Liberty file to describe a cell library which
 our internal cell library will be mapped to:
 

docs/source/using_yosys/synthesis/extract.rst

@@ -0,0 +1,228 @@
+The extract pass
+----------------
+
+- Like the :cmd:ref:`techmap` pass, the :cmd:ref:`extract` pass is called with a
+  map file. It compares the circuits inside the modules of the map file with the
+  design and looks for sub-circuits in the design that match any of the modules
+  in the map file.
+- If a match is found, the :cmd:ref:`extract` pass will replace the matching
+  subcircuit with an instance of the module from the map file.
+- In a way the :cmd:ref:`extract` pass is the inverse of the techmap pass.
+
+.. todo:: add/expand supporting text, also mention custom pattern matching and
+   pmgen
+
+Example code can be found in ``docs/source/code_examples/macc/``.
+
+.. literalinclude:: /code_examples/macc/macc_simple_test.ys
+    :language: yoscrypt
+    :lines: 1-2
+
+.. figure:: /_images/code_examples/macc/macc_simple_test_00a.*
+    :class: width-helper
+    
+    before :cmd:ref:`extract`
+
+.. literalinclude:: /code_examples/macc/macc_simple_test.ys
+    :language: yoscrypt
+    :lines: 6
+
+.. figure:: /_images/code_examples/macc/macc_simple_test_00b.*
+    :class: width-helper
+    
+    after :cmd:ref:`extract`
+
+.. literalinclude:: /code_examples/macc/macc_simple_test.v
+   :language: verilog
+   :caption: ``macc_simple_test.v``
+
+.. literalinclude:: /code_examples/macc/macc_simple_xmap.v
+   :language: verilog
+   :caption: ``macc_simple_xmap.v``
+
+.. literalinclude:: /code_examples/macc/macc_simple_test_01.v
+   :language: verilog
+   :caption: ``macc_simple_test_01.v``
+
+.. figure:: /_images/code_examples/macc/macc_simple_test_01a.*
+    :class: width-helper
+
+.. figure:: /_images/code_examples/macc/macc_simple_test_01b.*
+    :class: width-helper
+
+.. literalinclude:: /code_examples/macc/macc_simple_test_02.v
+   :language: verilog
+   :caption: ``macc_simple_test_02.v``
+
+.. figure:: /_images/code_examples/macc/macc_simple_test_02a.*
+    :class: width-helper
+
+.. figure:: /_images/code_examples/macc/macc_simple_test_02b.*
+    :class: width-helper
+
+The wrap-extract-unwrap method
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Often a coarse-grain element has a constant bit-width, but can be used to
+implement operations with a smaller bit-width. For example, a 18x25-bit multiplier
+can also be used to implement 16x20-bit multiplication.
+
+A way of mapping such elements in coarse grain synthesis is the
+wrap-extract-unwrap method:
+
+wrap
+  Identify candidate-cells in the circuit and wrap them in a cell with a
+  constant wider bit-width using :cmd:ref:`techmap`. The wrappers use the same
+  parameters as the original cell, so the information about the original width
+  of the ports is preserved. Then use the :cmd:ref:`connwrappers` command to
+  connect up the bit-extended in- and outputs of the wrapper cells.
+
+extract
+  Now all operations are encoded using the same bit-width as the coarse grain
+  element. The :cmd:ref:`extract` command can be used to replace circuits with
+  cells of the target architecture.
+
+unwrap
+  The remaining wrapper cell can be unwrapped using :cmd:ref:`techmap`.
+
+Example: DSP48_MACC
+~~~~~~~~~~~~~~~~~~~
+
+This section details an example that shows how to map MACC operations of
+arbitrary size to MACC cells with a 18x25-bit multiplier and a 48-bit adder
+(such as the Xilinx DSP48 cells).  Source code can be found in
+``docs/source/code_examples/macc/``.
+
+Preconditioning: ``macc_xilinx_swap_map.v``
+
+Make sure ``A`` is the smaller port on all multipliers
+
+.. todo:: add/expand supporting text
+
+.. literalinclude:: /code_examples/macc/macc_xilinx_swap_map.v
+   :language: verilog
+   :caption: ``macc_xilinx_swap_map.v``
+
+Wrapping multipliers: ``macc_xilinx_wrap_map.v``
+
+.. literalinclude:: /code_examples/macc/macc_xilinx_wrap_map.v
+   :language: verilog
+   :lines: 1-46
+   :caption: ``macc_xilinx_wrap_map.v``
+
+Wrapping adders: ``macc_xilinx_wrap_map.v``
+
+.. literalinclude:: /code_examples/macc/macc_xilinx_wrap_map.v
+   :language: verilog
+   :lines: 48-89
+   :caption: ``macc_xilinx_wrap_map.v``
+
+Extract: ``macc_xilinx_xmap.v``
+
+.. literalinclude:: /code_examples/macc/macc_xilinx_xmap.v
+   :language: verilog
+   :caption: ``macc_xilinx_xmap.v``
+
+... simply use the same wrapping commands on this module as on the design to
+create a template for the :cmd:ref:`extract` command.
+
+Unwrapping multipliers: ``macc_xilinx_unwrap_map.v``
+
+.. literalinclude:: /code_examples/macc/macc_xilinx_unwrap_map.v
+   :language: verilog
+   :lines: 1-30
+   :caption: ``$__mul_wrapper`` module in ``macc_xilinx_unwrap_map.v``
+
+Unwrapping adders: ``macc_xilinx_unwrap_map.v``
+
+.. literalinclude:: /code_examples/macc/macc_xilinx_unwrap_map.v
+   :language: verilog
+   :lines: 32-61
+   :caption: ``$__add_wrapper`` module in ``macc_xilinx_unwrap_map.v``
+
+.. literalinclude:: /code_examples/macc/macc_xilinx_test.v
+   :language: verilog
+   :lines: 1-6
+   :caption: ``test1`` of ``macc_xilinx_test.v``
+
+.. figure:: /_images/code_examples/macc/macc_xilinx_test1a.*
+    :class: width-helper
+
+.. figure:: /_images/code_examples/macc/macc_xilinx_test1b.*
+    :class: width-helper
+
+.. literalinclude:: /code_examples/macc/macc_xilinx_test.v
+   :language: verilog
+   :lines: 8-13
+   :caption: ``test2`` of ``macc_xilinx_test.v``
+
+.. figure:: /_images/code_examples/macc/macc_xilinx_test2a.*
+    :class: width-helper
+
+.. figure:: /_images/code_examples/macc/macc_xilinx_test2b.*
+    :class: width-helper
+
+Wrapping in ``test1``:
+
+.. figure:: /_images/code_examples/macc/macc_xilinx_test1b.*
+    :class: width-helper
+
+.. literalinclude:: /code_examples/macc/macc_xilinx_test.ys
+    :language: yoscrypt
+    :start-after: part c
+    :end-before: end part c
+
+.. figure:: /_images/code_examples/macc/macc_xilinx_test1c.*
+    :class: width-helper
+
+Wrapping in ``test2``:
+
+.. figure:: /_images/code_examples/macc/macc_xilinx_test2b.*
+    :class: width-helper
+
+.. literalinclude:: /code_examples/macc/macc_xilinx_test.ys
+    :language: yoscrypt
+    :start-after: part c
+    :end-before: end part c
+
+.. figure:: /_images/code_examples/macc/macc_xilinx_test2c.*
+    :class: width-helper
+
+Extract in ``test1``:
+
+.. figure:: /_images/code_examples/macc/macc_xilinx_test1c.*
+    :class: width-helper
+
+.. literalinclude:: /code_examples/macc/macc_xilinx_test.ys
+    :language: yoscrypt
+    :start-after: part d
+    :end-before: end part d
+
+.. figure:: /_images/code_examples/macc/macc_xilinx_test1d.*
+    :class: width-helper
+
+Extract in ``test2``:
+
+.. figure:: /_images/code_examples/macc/macc_xilinx_test2c.*
+    :class: width-helper
+
+.. literalinclude:: /code_examples/macc/macc_xilinx_test.ys
+    :language: yoscrypt
+    :start-after: part d
+    :end-before: end part d
+
+.. figure:: /_images/code_examples/macc/macc_xilinx_test2d.*
+    :class: width-helper
+
+Unwrap in ``test2``:
+
+.. figure:: /_images/code_examples/macc/macc_xilinx_test2d.*
+    :class: width-helper
+
+.. literalinclude:: /code_examples/macc/macc_xilinx_test.ys
+    :language: yoscrypt
+    :start-after: part e
+    :end-before: end part e
+
+.. figure:: /_images/code_examples/macc/macc_xilinx_test2e.*
+    :class: width-helper

docs/source/using_yosys/synthesis/index.rst

@@ -1,7 +1,24 @@
 Synthesis in detail
 -------------------
 
-.. todo:: brief overview for the synthesis index
+Synthesis can generally be broken down into coarse-grain synthesis, and
+fine-grain synthesis.  We saw this in :doc:`/getting_started/example_synth`
+where a design was loaded and elaborated and then went through a series of
+coarse-grain optimizations before being mapped to hard blocks and fine-grain
+cells.  Most commands in Yosys will target either coarse-grain representation or
+fine-grain representation, with only a select few compatible with both states.
+
+Commands such as :cmd:ref:`proc`, :cmd:ref:`fsm`, and :cmd:ref:`memory` rely on
+the additional information in the coarse-grain representation, along with a
+number of optimizations such as :cmd:ref:`wreduce`, :cmd:ref:`share`, and
+:cmd:ref:`alumacc`.  :cmd:ref:`opt` provides optimizations which are useful in
+both states, while :cmd:ref:`techmap` is used to convert coarse-grain cells
+to the corresponding fine-grain representation.
+
+Single-bit cells (logic gates, FFs) as well as LUTs, half-adders, and
+full-adders make up the bulk of the fine-grain representation and are necessary
+for commands such as :cmd:ref:`abc`\ /:cmd:ref:`abc9`, :cmd:ref:`simplemap`,
+:cmd:ref:`dfflegalize`, and :cmd:ref:`memory_map`.
 
 .. toctree::
    :maxdepth: 3
@@ -12,6 +29,7 @@ Synthesis in detail
    memory
    opt
    techmap_synth
+   extract
    abc
    cell_libs
 

docs/source/using_yosys/synthesis/synth.rst

@@ -1,6 +1,8 @@
 Synth commands
 --------------
 
+.. todo:: comment on common ``synth_*`` options, like ``-run``
+
 Packaged ``synth_*`` commands
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 

docs/source/using_yosys/synthesis/techmap_synth.rst

@@ -1,4 +1,107 @@
-techmap_synth
--------------
+Technology mapping 
+==================
 
-.. TODO:: techmap_synth
+.. todo:: less academic, check text is coherent
+
+Previous chapters outlined how HDL code is transformed into an RTL netlist. The
+RTL netlist is still based on abstract coarse-grain cell types like arbitrary
+width adders and even multipliers. This chapter covers how an RTL netlist is
+transformed into a functionally equivalent netlist utilizing the cell types
+available in the target architecture.
+
+Technology mapping is often performed in two phases. In the first phase RTL
+cells are mapped to an internal library of single-bit cells (see
+:ref:`sec:celllib_gates`). In the second phase this netlist of internal gate
+types is transformed to a netlist of gates from the target technology library.
+
+When the target architecture provides coarse-grain cells (such as block ram or
+ALUs), these must be mapped to directly form the RTL netlist, as information on
+the coarse-grain structure of the design is lost when it is mapped to bit-width
+gate types.
+
+Cell substitution
+-----------------
+
+The simplest form of technology mapping is cell substitution, as performed by
+the techmap pass. This pass, when provided with a Verilog file that implements
+the RTL cell types using simpler cells, simply replaces the RTL cells with the
+provided implementation.
+
+When no map file is provided, techmap uses a built-in map file that maps the
+Yosys RTL cell types to the internal gate library used by Yosys. The curious
+reader may find this map file as `techlibs/common/techmap.v` in the Yosys source
+tree.
+
+Additional features have been added to techmap to allow for conditional mapping
+of cells (see :doc:`/cmd/techmap`). This can for example be useful if the target
+architecture supports hardware multipliers for certain bit-widths but not for
+others.
+
+A usual synthesis flow would first use the techmap pass to directly map some RTL
+cells to coarse-grain cells provided by the target architecture (if any) and
+then use techmap with the built-in default file to map the remaining RTL cells
+to gate logic.
+
+Subcircuit substitution
+-----------------------
+
+Sometimes the target architecture provides cells that are more powerful than the
+RTL cells used by Yosys. For example a cell in the target architecture that can
+calculate the absolute-difference of two numbers does not match any single RTL
+cell type but only combinations of cells.
+
+For these cases Yosys provides the extract pass that can match a given set of
+modules against a design and identify the portions of the design that are
+identical (i.e. isomorphic subcircuits) to any of the given modules. These
+matched subcircuits are then replaced by instances of the given modules.
+
+The extract pass also finds basic variations of the given modules, such as
+swapped inputs on commutative cell types.
+
+In addition to this the extract pass also has limited support for frequent
+subcircuit mining, i.e. the process of finding recurring subcircuits in the
+design. This has a few applications, including the design of new coarse-grain
+architectures :cite:p:`intersynthFdlBookChapter`.
+
+The hard algorithmic work done by the extract pass (solving the isomorphic
+subcircuit problem and frequent subcircuit mining) is performed using the
+SubCircuit library that can also be used stand-alone without Yosys (see
+:ref:`sec:SubCircuit`).
+
+.. _sec:techmap_extern:
+
+Gate-level technology mapping
+-----------------------------
+
+.. todo:: newer techmap libraries appear to be largely ``.v`` instead of ``.lib``
+
+On the gate-level the target architecture is usually described by a "Liberty
+file". The Liberty file format is an industry standard format that can be used
+to describe the behaviour and other properties of standard library cells .
+
+Mapping a design utilizing the Yosys internal gate library (e.g. as a result of
+mapping it to this representation using the techmap pass) is performed in two
+phases.
+
+First the register cells must be mapped to the registers that are available on
+the target architectures. The target architecture might not provide all
+variations of d-type flip-flops with positive and negative clock edge,
+high-active and low-active asynchronous set and/or reset, etc. Therefore the
+process of mapping the registers might add additional inverters to the design
+and thus it is important to map the register cells first.
+
+Mapping of the register cells may be performed by using the dfflibmap pass. This
+pass expects a Liberty file as argument (using the -liberty option) and only
+uses the register cells from the Liberty file.
+
+Secondly the combinational logic must be mapped to the target architecture. This
+is done using the external program ABC via the abc pass by using the -liberty
+option to the pass. Note that in this case only the combinatorial cells are used
+from the cell library.
+
+Occasionally Liberty files contain trade secrets (such as sensitive timing
+information) that cannot be shared freely. This complicates processes such as
+reporting bugs in the tools involved. When the information in the Liberty file
+used by Yosys and ABC are not part of the sensitive information, the additional
+tool yosys-filterlib (see :ref:`sec:filterlib`) can be used to strip the
+sensitive information from the Liberty file.