From a8b2525b08fead32c5205b7dea992450970ddbf0 Mon Sep 17 00:00:00 2001
From: Krystine Sherwin <93062060+KrystalDelusion@users.noreply.github.com>
Date: Tue, 5 Dec 2023 11:21:39 +1300
Subject: [PATCH] typical phases: Expand/split sections

More consistent indentation and section headings.
Convert yoscrypt blocks to lists of cmdrefs (so they link to the commands in question).
Also update said lists.
Add other common optimizations/mapping commands.
Remove example synth script in favour of the examples on the next page.
---
 .../source/getting_started/typical_phases.rst | 277 +++++++++---------
 1 file changed, 145 insertions(+), 132 deletions(-)

diff --git a/docs/source/getting_started/typical_phases.rst b/docs/source/getting_started/typical_phases.rst
index 2fce9215c..64f76cd4e 100644
--- a/docs/source/getting_started/typical_phases.rst
+++ b/docs/source/getting_started/typical_phases.rst
@@ -1,7 +1,13 @@
 Typical phases of a synthesis flow
 ----------------------------------
 
-.. todo:: expand text
+.. role:: yoscrypt(code)
+   :language: yoscrypt
+
+.. todo:: should e.g. :yoscrypt:`proc` and :yoscrypt:`memory` examples be 
+   included here (typical phases) or examples
+
+.. todo:: expand bullet points
 
 - Reading and elaborating the design
 - Higher-level synthesis and optimization
@@ -16,10 +22,11 @@ Typical phases of a synthesis flow
 - Map bit-level logic gates and registers to cell library
 - Write results to output file
 
-
 Reading the design
 ~~~~~~~~~~~~~~~~~~
 
+.. todo:: include ``read_verilog <<EOF`` when discussing how to read designs?
+
 .. code-block:: yoscrypt
 
     read_verilog file1.v
@@ -45,6 +52,13 @@ During design elaboration Yosys figures out how the modules are hierarchically
 connected. It also re-runs the AST parts of the Verilog frontend to create all
 needed variations of parametric modules.
 
+.. todo:: hierarchy without ``-top`` is bad
+   - resolve non-module-specific references (sub modules, interfaces et al)
+   - check sub modules exist, discarding unused
+   - set top attribute
+   - also mention failure modes
+   - also prep?
+
 .. code-block:: yoscrypt
 
     # simplest form. at least this version should be used after reading all input files
@@ -57,27 +71,31 @@ needed variations of parametric modules.
     hierarchy -check -top top_module
 
 
-The :cmd:ref:`proc` command
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Converting process blocks
+~~~~~~~~~~~~~~~~~~~~~~~~~
 
 The Verilog frontend converts ``always``-blocks to RTL netlists for the
-expressions and "processess" for the control- and memory elements.
+expressions and "processess" for the control- and memory elements. The
+:cmd:ref:`proc` command then transforms these "processess" to netlists of RTL
+multiplexer and register cells. It also is a macro command that calls the other
+``proc_*`` commands in a sensible order:
 
-The :cmd:ref:`proc` command transforms this "processess" to netlists of RTL
-multiplexer and register cells.
+#. :cmd:ref:`proc_clean` removes empty branches and processes.
+#. :cmd:ref:`proc_rmdead` removes unreachable branches.
+#. :cmd:ref:`proc_prune`
+#. :cmd:ref:`proc_init` special handling of "initial" blocks.
+#. :cmd:ref:`proc_arst` identifies modeling of async resets.
+#. :cmd:ref:`proc_rom`
+#. :cmd:ref:`proc_mux` converts decision trees to multiplexer networks.
+#. :cmd:ref:`proc_dlatch`
+#. :cmd:ref:`proc_dff` extracts registers from processes.
+#. :cmd:ref:`proc_memwr`
+#. :cmd:ref:`proc_clean` this should remove all the processes, provided all went
+   fine.
 
-The :cmd:ref:`proc` command is actually a macro-command that calls the following
-other commands:
-
-.. code-block:: yoscrypt
-
-    proc_clean      # remove empty branches and processes
-    proc_rmdead     # remove unreachable branches
-    proc_init       # special handling of "initial" blocks
-    proc_arst       # identify modeling of async resets
-    proc_mux        # convert decision trees to multiplexer networks
-    proc_dff        # extract registers from processes
-    proc_clean      # if all went fine, this should remove all the processes
+After all the ``proc_*`` commands, :yoscrypt:`opt_expr` is called. This can be
+disabled by calling :yoscrypt:`proc -noopt`.  For more information about
+:cmd:ref:`proc`, such as disabling certain sub commands, see :doc:`/cmd/proc`.
 
 Many commands can not operate on modules with "processess" in them. Usually a
 call to :cmd:ref:`proc` is the first command in the actual synthesis procedure
@@ -86,6 +104,8 @@ after design elaboration.
 Example
 ^^^^^^^
 
+.. todo:: describe ``proc`` images
+
 .. literalinclude:: /code_examples/synth_flow/proc_01.v
    :language: verilog
    :caption: ``docs/source/code_examples/synth_flow/proc_01.v``
@@ -95,10 +115,10 @@ Example
    :caption: ``docs/source/code_examples/synth_flow/proc_01.ys``
 
 .. figure:: /_images/code_examples/synth_flow/proc_01.*
-    :class: width-helper
+   :class: width-helper
 
 .. figure:: /_images/code_examples/synth_flow/proc_02.*
-    :class: width-helper
+   :class: width-helper
 
 .. literalinclude:: /code_examples/synth_flow/proc_02.v
    :language: verilog
@@ -109,7 +129,7 @@ Example
    :caption: ``docs/source/code_examples/synth_flow/proc_02.ys``
 
 .. figure:: /_images/code_examples/synth_flow/proc_03.*
-    :class: width-helper
+   :class: width-helper
 
 .. literalinclude:: /code_examples/synth_flow/proc_03.ys
    :language: yoscrypt
@@ -120,8 +140,8 @@ Example
    :caption: ``docs/source/code_examples/synth_flow/proc_03.v``
 
 
-The :cmd:ref:`opt` command
-~~~~~~~~~~~~~~~~~~~~~~~~~~
+Optimizations
+~~~~~~~~~~~~~
 
 The :cmd:ref:`opt` command implements a series of simple optimizations. It also
 is a macro command that calls other commands:
@@ -148,10 +168,12 @@ The command :cmd:ref:`clean` can be used as alias for :cmd:ref:`opt_clean`. And
     hierarchy; proc; opt; memory; opt_expr;; fsm;;
 
 Example
-^^^^^^^
+"""""""
+
+.. todo:: describe ``opt`` images
 
 .. figure:: /_images/code_examples/synth_flow/opt_01.*
-    :class: width-helper
+   :class: width-helper
 
 .. literalinclude:: /code_examples/synth_flow/opt_01.ys
    :language: yoscrypt
@@ -162,7 +184,7 @@ Example
    :caption: ``docs/source/code_examples/synth_flow/opt_01.v``
 
 .. figure:: /_images/code_examples/synth_flow/opt_02.*
-    :class: width-helper
+   :class: width-helper
 
 .. literalinclude:: /code_examples/synth_flow/opt_02.ys
    :language: yoscrypt
@@ -173,7 +195,7 @@ Example
    :caption: ``docs/source/code_examples/synth_flow/opt_02.v``
 
 .. figure:: /_images/code_examples/synth_flow/opt_03.*
-    :class: width-helper
+   :class: width-helper
 
 .. literalinclude:: /code_examples/synth_flow/opt_03.ys
    :language: yoscrypt
@@ -184,7 +206,7 @@ Example
    :caption: ``docs/source/code_examples/synth_flow/opt_03.v``
 
 .. figure:: /_images/code_examples/synth_flow/opt_04.*
-    :class: width-helper
+   :class: width-helper
 
 .. literalinclude:: /code_examples/synth_flow/opt_04.v
    :language: verilog
@@ -194,20 +216,16 @@ Example
    :language: yoscrypt
    :caption: ``docs/source/code_examples/synth_flow/opt_04.ys``
 
-
 When to use :cmd:ref:`opt` or :cmd:ref:`clean`
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+""""""""""""""""""""""""""""""""""""""""""""""
 
 Usually it does not hurt to call :cmd:ref:`opt` after each regular command in
 the synthesis script. But it increases the synthesis time, so it is favourable
 to only call :cmd:ref:`opt` when an improvement can be achieved.
 
-The designs in ``yosys-bigsim`` are a good playground for experimenting with the
-effects of calling :cmd:ref:`opt` in various places of the flow.
-
-It generally is a good idea to call :cmd:ref:`opt` before inherently expensive
+It is generally a good idea to call :cmd:ref:`opt` before inherently expensive
 commands such as :cmd:ref:`sat` or :cmd:ref:`freduce`, as the possible gain is
-much higher in this cases as the possible loss.
+much higher in these cases as the possible loss.
 
 The :cmd:ref:`clean` command on the other hand is very fast and many commands
 leave a mess (dangling signal wires, etc). For example, most commands do not
@@ -215,26 +233,44 @@ remove any wires or cells. They just change the connections and depend on a
 later call to clean to get rid of the now unused objects. So the occasional
 ``;;`` is a good idea in every synthesis script.
 
-The :cmd:ref:`memory` command
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Other common optimization commands
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. todo:: fill out descriptions for other optimization commands
+
+:cmd:ref:`wreduce`
+    Reduces the word size of operations.
+
+:cmd:ref:`peepopt`
+    Applies a collection of peephole optimizers to the current design.
+
+:cmd:ref:`share`
+    Merges shareable resources into a single resource using a SAT solver to
+    determine if two resources are shareable.
+
+Memory handling
+~~~~~~~~~~~~~~~
 
 In the RTL netlist, memory reads and writes are individual cells. This makes
 consolidating the number of ports for a memory easier. The :cmd:ref:`memory`
 transforms memories to an implementation. Per default that is logic for address
-decoders and registers. It also is a macro command that calls other commands:
+decoders and registers. It also is a macro command that calls the other
+``memory_*`` commands in a sensible order:
 
-.. code-block:: yoscrypt
+.. todo:: fill out missing :cmd:ref:`memory` subcommands descriptions
 
-    # this merges registers into the memory read- and write cells.
-    memory_dff
+#. :cmd:ref:`memory_bmux2rom`
+#. :cmd:ref:`memory_dff` merges registers into the memory read- and write cells.
+#. :cmd:ref:`memory_share`
+#. :cmd:ref:`memory_memx`
+#. :cmd:ref:`memory_collect` collects all read and write cells for a memory and
+   transforms them into one multi-port memory cell.
+#. :cmd:ref:`memory_bram`
+#. :cmd:ref:`memory_map` takes the multi-port memory cell and transforms it to
+   address decoder logic and registers.
 
-    # this collects all read and write cells for a memory and transforms them
-    # into one multi-port memory cell.
-    memory_collect
-
-    # this takes the multi-port memory cell and transforms it to address decoder
-    # logic and registers. This step is skipped if "memory" is called with -nomap.
-    memory_map
+.. todo:: is :yoscrypt:`memory -nomap; techmap -map my_memory_map.v; memory_map`
+   superceded by :yoscrypt:`memory_libmap`?
 
 Usually it is preferred to use architecture-specific RAM resources for memory.
 For example:
@@ -243,11 +279,16 @@ For example:
 
     memory -nomap; techmap -map my_memory_map.v; memory_map
 
+For more information about :cmd:ref:`memory`, such as disabling certain sub
+commands, see :doc:`/cmd/memory`.
+
 Example
 ^^^^^^^
 
+.. todo:: describe ``memory`` images
+
 .. figure:: /_images/code_examples/synth_flow/memory_01.*
-    :class: width-helper
+   :class: width-helper
 
 .. literalinclude:: /code_examples/synth_flow/memory_01.ys
    :language: yoscrypt
@@ -258,7 +299,7 @@ Example
    :caption: ``docs/source/code_examples/synth_flow/memory_01.v``
 
 .. figure:: /_images/code_examples/synth_flow/memory_02.*
-    :class: width-helper
+   :class: width-helper
 
 .. literalinclude:: /code_examples/synth_flow/memory_02.v
    :language: verilog
@@ -268,59 +309,49 @@ Example
    :language: yoscrypt
    :caption: ``docs/source/code_examples/synth_flow/memory_02.ys``
 
+The :cmd:ref:`memory_libmap` command
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-The :cmd:ref:`fsm` command
-~~~~~~~~~~~~~~~~~~~~~~~~~~
+.. todo:: :cmd:ref:`memory_libmap` description
+
+FSM handling
+~~~~~~~~~~~~
 
 The :cmd:ref:`fsm` command identifies, extracts, optimizes (re-encodes), and
 re-synthesizes finite state machines. It again is a macro that calls a series of
 other commands:
 
-.. code-block:: yoscrypt
+#. :cmd:ref:`fsm_detect` identifies FSM state registers and marks them
+   with the ``(* fsm_encoding = "auto" *)`` attribute, if they do not have the
+   ``fsm_encoding`` set already. Mark registers with ``(* fsm_encoding = "none"
+   *)`` to disable FSM optimization for a register.
+#. :cmd:ref:`fsm_extract` replaces the entire FSM (logic and state registers)
+   with a ``$fsm`` cell.
+#. :cmd:ref:`fsm_opt` optimizes the FSM. Called multiple times.
+#. :cmd:ref:`fsm_expand` optionally merges additional auxilliary gates into the
+   ``$fsm`` cell.
+#. :cmd:ref:`fsm_recode` also optimizes the FSM.
+#. :cmd:ref:`fsm_info` logs internal FSM information.
+#. :cmd:ref:`fsm_export` optionally exports each FSM to KISS2 files.
+#. :cmd:ref:`fsm_map` converts the (optimized) ``$fsm`` cell back to logic and
+   registers.
 
-    fsm_detect          # unless got option -nodetect
-    fsm_extract
+See also :doc:`/cmd/fsm`.
 
-    fsm_opt
-    clean
-    fsm_opt
+DSP handling
+~~~~~~~~~~~~
 
-    fsm_expand          # if got option -expand
-    clean               # if got option -expand
-    fsm_opt             # if got option -expand
+.. todo:: add info about dsp handling
 
-    fsm_recode          # unless got option -norecode
-
-    fsm_info
-
-    fsm_export          # if got option -export
-    fsm_map             # unless got option -nomap
-
-Some details on the most important commands from the ``fsm_*`` group:
-
-The :cmd:ref:`fsm_detect` command identifies FSM state registers and marks them
-with the ``(* fsm_encoding = "auto" *)`` attribute, if they do not have the
-``fsm_encoding`` set already. Mark registers with ``(* fsm_encoding = "none"
-*)`` to disable FSM optimization for a register.
-
-The :cmd:ref:`fsm_extract` command replaces the entire FSM (logic and state
-registers) with a ``$fsm`` cell.
-
-The commands :cmd:ref:`fsm_opt` and :cmd:ref:`fsm_recode` can be used to
-optimize the FSM.
-
-Finally the :cmd:ref:`fsm_map` command can be used to convert the (optimized)
-``$fsm`` cell back to logic and registers.
-
-The :cmd:ref:`techmap` command
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-.. figure:: /_images/code_examples/synth_flow/techmap_01.*
-    :class: width-helper
+Technology mapping
+~~~~~~~~~~~~~~~~~~
 
 The :cmd:ref:`techmap` command replaces cells with implementations given as
 verilog source. For example implementing a 32 bit adder using 16 bit adders:
 
+.. figure:: /_images/code_examples/synth_flow/techmap_01.*
+   :class: width-helper
+
 .. literalinclude:: /code_examples/synth_flow/techmap_01_map.v
    :language: verilog
    :caption: ``docs/source/code_examples/synth_flow/techmap_01_map.v``
@@ -333,6 +364,8 @@ verilog source. For example implementing a 32 bit adder using 16 bit adders:
    :language: yoscrypt
    :caption: ``docs/source/code_examples/synth_flow/techmap_01.ys``
 
+See :doc:`/yosys_internals/techmap` for more.
+
 stdcell mapping
 ^^^^^^^^^^^^^^^
 
@@ -378,6 +411,8 @@ advanced ABC features. It is also possible to write the design with
 Example
 ^^^^^^^
 
+.. todo:: describe ``abc`` images
+
 .. literalinclude:: /code_examples/synth_flow/abc_01.v
    :language: verilog
    :caption: ``docs/source/code_examples/synth_flow/abc_01.v``
@@ -387,58 +422,36 @@ Example
    :caption: ``docs/source/code_examples/synth_flow/abc_01.ys``
 
 .. figure:: /_images/code_examples/synth_flow/abc_01.*
-    :class: width-helper
+   :class: width-helper
 
 Other special-purpose mapping commands
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
+The commands below may be used depending on the targeted architecture for
+compatibility with, or to take advantage of, resources available.
+
 :cmd:ref:`dfflibmap`
-  This command maps the internal register cell types to the register types
-  described in a liberty file.
+    This command maps the internal register cell types to the register types
+    described in a liberty file.
 
 :cmd:ref:`hilomap`
-  Some architectures require special driver cells for driving a constant hi or
-  lo value. This command replaces simple constants with instances of such driver
-  cells.
+    Some architectures require special driver cells for driving a constant hi or
+    lo value. This command replaces simple constants with instances of such
+    driver cells.
 
 :cmd:ref:`iopadmap`
-  Top-level input/outputs must usually be implemented using special I/O-pad
-  cells. This command inserts this cells to the design.
+    Top-level input/outputs must usually be implemented using special I/O-pad
+    cells. This command inserts such cells to the design.
 
-Example Synthesis Script
-~~~~~~~~~~~~~~~~~~~~~~~~
+:cmd:ref:`alumacc`
+    Translate arithmetic operations like $add, $mul, $lt, etc. to $alu and $macc
+    cells.
 
-.. code-block:: yoscrypt
+:cmd:ref:`dfflegalize`
+    Specify a set of supported FF cells/cell groups and convert all FFs to them.
 
-    # read and elaborate design
-    read_verilog cpu_top.v cpu_ctrl.v cpu_regs.v
-    read_verilog -D WITH_MULT cpu_alu.v
-    hierarchy -check -top cpu_top
+:cmd:ref:`deminout`
+    Convert inout ports to input or output ports, if possible.
 
-    # high-level synthesis
-    proc; opt; fsm;; memory -nomap; opt
-
-    # substitute block rams
-    techmap -map map_rams.v
-
-    # map remaining memories
-    memory_map
-
-    # low-level synthesis
-    techmap; opt; flatten;; abc -lut6
-    techmap -map map_xl_cells.v
-
-    # add clock buffers
-    select -set xl_clocks t:FDRE %x:+FDRE[C] t:FDRE %d
-    iopadmap -inpad BUFGP O:I @xl_clocks
-
-    # add io buffers
-    select -set xl_nonclocks w:* t:BUFGP %x:+BUFGP[I] %d
-    iopadmap -outpad OBUF I:O -inpad IBUF O:I @xl_nonclocks
-
-    # write synthesis results
-    write_edif synth.edif
-
-The weird :cmd:ref:`select` expressions at the end of this script are discussed
-later in
-:doc:`using_yosys/more_scripting/selections</using_yosys/more_scripting/selections>`.
+:cmd:ref:`pmuxtree`
+    Transforms parallel mux cells, ``$pmux``, to trees of ``$mux`` cells.