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`.
2025-04-26 18:45:34 +00:00 · 2024-01-26 13:06:02 +13:00 · 2024-01-26 13:06:02 +13:00 · e2e7065590
commit e2e7065590
parent 4582ab59da
10 changed files with 259 additions and 273 deletions
--- a/docs/source/using_yosys/synthesis/extract.rst
+++ b/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