First pass example_synth done

Split coarse grain representation into 4 parts, loosely: fsm/opt, other optimizations/techmap/memory_dff, DSPs, alumacc/memory -nomap.
Split hardware mapping into subsections as well: memory blocks (map_ram and map_ffram), arithmetic (map_gates), FFs (map_ffs), LUTs (map_luts and briefly abc), and other (map_cells and a note on hilomap and iopadmap).

Also add `-T` flag to Yosys call to remove footer from log output.

docs/source/code_examples/fifo/Makefile

@@ -2,14 +2,17 @@ PROGRAM_PREFIX :=
 
 YOSYS ?= ../../../../$(PROGRAM_PREFIX)yosys
 
-DOTS = addr_gen_hier.dot addr_gen_proc.dot
+DOT_NAMES = addr_gen_hier addr_gen_proc addr_gen_clean
-DOTS += rdata_proc.dot rdata_flat.dot
+DOT_NAMES += rdata_proc rdata_flat rdata_adffe rdata_memrdv2 rdata_alumacc
-DOTS += fifo_flat.dot fifo_synth.dot
+DOT_NAMES += rdata_coarse rdata_map_ram rdata_map_ffram rdata_map_gates 
+DOT_NAMES += rdata_map_ffs rdata_map_luts rdata_map_cells
+
+DOTS := $(addsuffix .dot,$(DOT_NAMES))
 
 dots: $(DOTS) fifo.out
 
 $(DOTS) fifo.out: fifo.v fifo.ys
-	$(YOSYS) fifo.ys -l fifo.out -Q
+	$(YOSYS) fifo.ys -l fifo.out -Q -T
 
 .PHONY: clean
 clean:

docs/source/code_examples/fifo/fifo.ys

@@ -56,7 +56,51 @@ show -color maroon3 @new_cells -notitle -format dot -prefix rdata_alumacc o:rdat
 design -reset
 read_verilog fifo.v
 synth_ice40 -top fifo -run begin:map_ram
-# memory_collect
-# opt
 select -set new_cells t:$mem_v2
-show -color maroon3 @new_cells -notitle -format dot -prefix rdata_coarse o:rdata %ci*
+select -set rdata_path @new_cells %ci*:-$mem_v2[WR_DATA,WR_ADDR,WR_EN] @new_cells %co* %%
+show -color maroon3 @new_cells -notitle -format dot -prefix rdata_coarse @rdata_path
+
+# turn command echoes off to avoid randomly generated abc file names
+echo off
+
+# ========================================================
+
+synth_ice40 -top fifo -run map_ram:map_ffram
+select -set new_cells t:SB_RAM40_4K
+select -set rdata_path @new_cells %ci*:-SB_RAM40_4K[WDATA,WADDR,WE] @new_cells %co* %%
+show -color maroon3 @new_cells -notitle -format dot -prefix rdata_map_ram @rdata_path
+
+# ========================================================
+
+synth_ice40 -top fifo -run map_ffram:map_gates
+select -set new_cells t:SB_RAM40_4K
+select -set rdata_path @new_cells %ci*:-SB_RAM40_4K[WDATA,WADDR,WE] @new_cells %co* %%
+show -color maroon3 @new_cells -notitle -format dot -prefix rdata_map_ffram @rdata_path
+
+# ========================================================
+
+synth_ice40 -top fifo -run map_gates:map_ffs
+select -set new_cells t:SB_RAM40_4K
+select -set rdata_path @new_cells %ci*:-SB_RAM40_4K[WDATA,WADDR,WE] @new_cells %co* %%
+show -color maroon3 @new_cells -notitle -format dot -prefix rdata_map_gates @rdata_path
+
+# ========================================================
+
+synth_ice40 -top fifo -run map_ffs:map_luts
+select -set new_cells t:SB_RAM40_4K
+select -set rdata_path @new_cells %ci*:-SB_RAM40_4K[WDATA,WADDR,WE] @new_cells %co* %%
+show -color maroon3 @new_cells -notitle -format dot -prefix rdata_map_ffs @rdata_path
+
+# ========================================================
+
+synth_ice40 -top fifo -run map_luts:map_cells
+select -set new_cells t:SB_RAM40_4K
+select -set rdata_path @new_cells %ci*:-SB_RAM40_4K[WDATA,WADDR,WE] @new_cells %co* %%
+show -color maroon3 @new_cells -notitle -format dot -prefix rdata_map_luts @rdata_path
+
+# ========================================================
+
+synth_ice40 -top fifo -run map_cells:
+select -set new_cells t:SB_RAM40_4K
+select -set rdata_path @new_cells %ci*:-SB_RAM40_4K[WDATA,WADDR,WE] @new_cells %co* %%
+show -color maroon3 @new_cells -notitle -format dot -prefix rdata_map_cells @rdata_path

docs/source/getting_started/example_synth.rst

@@ -299,20 +299,22 @@ optimizations and other transformations done previously.
 
    While the iCE40 flow had a :ref:`synth_flatten` and put :cmd:ref:`proc` in
    the :ref:`synth_begin`, some synthesis scripts will instead include these in
-   the :ref:`synth_coarse`.
+   this section.
 
-In the iCE40 flow we get all the following commands:
+Part 1
+^^^^^^
+
+In the iCE40 flow, we start with the following commands:
 
 .. literalinclude:: /cmd/synth_ice40.rst
    :language: yoscrypt
-   :linenos:
    :start-after: coarse:
-   :end-before: map_ram:
+   :end-before: wreduce
    :dedent:
-   :caption: ``coarse`` section
+   :caption: ``coarse`` section (part 1)
-   :name: synth_coarse
+   :name: synth_coarse1
 
-The first few commands are relatively straightforward.  We've already come
+The first few commands are relatively straightforward, and we've already come
 across :cmd:ref:`opt_clean` and :cmd:ref:`opt_expr`.  The :cmd:ref:`check` pass
 identifies a few obvious problems which will cause errors later.  Calling it
 here lets us fail faster rather than wasting time on something we know is
@@ -343,12 +345,30 @@ options is able to fold one of the ``$mux`` cells into the ``$adff`` to form an
 
    ``rdata`` output after :cmd:ref:`opt_dff`
 
+.. seealso:: Advanced usage docs for
+   
+   - :doc:`/using_yosys/synthesis/fsm`
+   - :doc:`/using_yosys/synthesis/opt`
+
+Part 2
+^^^^^^
+
+.. literalinclude:: /cmd/synth_ice40.rst
+   :language: yoscrypt
+   :start-at: wreduce
+   :end-before: t:$mul
+   :dedent:
+   :caption: ``coarse`` section (part 2)
+   :name: synth_coarse2
+
 The next three (new) commands are :doc:`/cmd/wreduce`, :doc:`/cmd/peepopt`, and
 :doc:`/cmd/share`.  None of these affect our design either, so let's skip over
 them.  :yoscrypt:`techmap -map +/cmp2lut.v -D LUT_WIDTH=4` optimizes certain
 comparison operators by converting them to LUTs instead.  The usage of
 :cmd:ref:`techmap` is explored more in
-:doc:`/using_yosys/synthesis/techmap_synth`. Our next command to run is
+:doc:`/using_yosys/synthesis/techmap_synth`.
+
+Our next command to run is
 :doc:`/cmd/memory_dff`.
 
 .. literalinclude:: /code_examples/fifo/fifo.out
@@ -365,10 +385,45 @@ comparison operators by converting them to LUTs instead.  The usage of
 
 As the title suggests, :cmd:ref:`memory_dff` has merged the output ``$dff`` into
 the ``$memrd`` cell and converted it to a ``$memrd_v2`` (highlighted).
-Following this is a series of commands for mapping to DSPs.
+
+.. seealso:: Advanced usage docs for
+   
+   - :doc:`/using_yosys/synthesis/opt`
+   - :doc:`/using_yosys/synthesis/techmap_synth`
+   - :doc:`/using_yosys/synthesis/memory`
+
+Part 3
+^^^^^^
+
+The third part of the :cmd:ref:`synth_ice40` flow is a series of commands for
+mapping to DSPs.
+
+.. literalinclude:: /cmd/synth_ice40.rst
+   :language: yoscrypt
+   :start-at: t:$mul
+   :end-before: alumacc
+   :dedent:
+   :caption: ``coarse`` section (part 3)
+   :name: synth_coarse3
 
 .. TODO:: more on DSP mapping
 
+.. seealso:: Advanced usage docs for
+   :doc:`/using_yosys/synthesis/techmap_synth`
+
+Part 4
+^^^^^^
+
+That brings us to the fourth and final part for the iCE40 synthesis flow:
+
+.. literalinclude:: /cmd/synth_ice40.rst
+   :language: yoscrypt
+   :start-at: alumacc
+   :end-before: map_ram:
+   :dedent:
+   :caption: ``coarse`` section (part 4)
+   :name: synth_coarse4
+
 Where before each type of arithmetic operation had its own cell, e.g. ``$add``,
 we now want to extract these into ``$alu`` and ``$macc`` cells which can be
 mapped to hard blocks.  We do this by running :cmd:ref:`alumacc`, which we can
@@ -386,15 +441,7 @@ see produce the following changes in our example design:
 
    ``rdata`` output after :cmd:ref:`alumacc`
 
-That brings us to the last commands, and a look at ``rdata`` at the end of the
+.. TODO:: discuss :cmd:ref:`memory_collect` and ``$mem_v2``
-:ref:`synth_coarse`.  We could also have gotten here by running
-:yoscrypt:`synth_ice40 -top fifo -run begin:map_ram` after loading the design.
-
-.. literalinclude:: /cmd/synth_ice40.rst
-   :language: yoscrypt
-   :start-at: memory -nomap
-   :end-before: map_ram:
-   :dedent:
 
 .. figure:: /_images/code_examples/fifo/rdata_coarse.*
    :class: width-helper
@@ -402,18 +449,26 @@ That brings us to the last commands, and a look at ``rdata`` at the end of the
 
    ``rdata`` output after :yoscrypt:`memory -nomap`
 
-.. TODO:: discuss :cmd:ref:`memory_collect` and ``$mem_v2``
+We could also have gotten here by running :yoscrypt:`synth_ice40 -top fifo -run
+begin:map_ram` after loading the design.
 
 .. seealso:: Advanced usage docs for
-   :doc:`/using_yosys/synthesis/fsm`
-   :doc:`/using_yosys/synthesis/opt`
-   :doc:`/using_yosys/synthesis/techmap_synth`
    :doc:`/using_yosys/synthesis/memory`
 
 Hardware mapping
 ~~~~~~~~~~~~~~~~
 
-.. TODO:: example_synth hardware mapping sections
+The remaining sections each map a different type of hardware and are much more
+architecture dependent than the previous sections.  As such we will only be
+looking at each section very briefly.
+
+Memory blocks
+^^^^^^^^^^^^^
+
+Mapping to hard memory blocks uses a combination of :cmd:ref:`memory_libmap`,
+:cmd:ref:`memory_map`, and :cmd:ref:`techmap`.
+
+.. TODO:: ``$mem_v2`` -> ``SB_RAM40_4K``
 
 .. literalinclude:: /cmd/synth_ice40.rst
    :language: yoscrypt
@@ -423,6 +478,12 @@ Hardware mapping
    :name: map_ram
    :caption: ``map_ram`` section
 
+.. figure:: /_images/code_examples/fifo/rdata_map_ram.*
+   :class: width-helper
+   :name: rdata_map_ram
+
+   ``rdata`` output after :ref:`map_ram`
+
 .. literalinclude:: /cmd/synth_ice40.rst
    :language: yoscrypt
    :start-after: map_ffram:
@@ -431,6 +492,24 @@ Hardware mapping
    :name: map_ffram
    :caption: ``map_ffram`` section
 
+.. figure:: /_images/code_examples/fifo/rdata_map_ffram.*
+   :class: width-helper
+   :name: rdata_map_ffram
+
+   ``rdata`` output after :ref:`map_ffram`
+
+.. seealso:: Advanced usage docs for
+   
+   - :doc:`/using_yosys/synthesis/techmap_synth`
+   - :doc:`/using_yosys/synthesis/memory`
+
+Arithmetic
+^^^^^^^^^^
+
+Uses :cmd:ref:`techmap`.
+
+.. TODO:: example_synth/Arithmetic
+
 .. literalinclude:: /cmd/synth_ice40.rst
    :language: yoscrypt
    :start-after: map_gates:
@@ -439,6 +518,23 @@ Hardware mapping
    :name: map_gates
    :caption: ``map_gates`` section
 
+.. figure:: /_images/code_examples/fifo/rdata_map_gates.*
+   :class: width-helper
+   :name: rdata_map_gates
+
+   ``rdata`` output after :ref:`map_gates`
+
+.. seealso:: Advanced usage docs for
+   :doc:`/using_yosys/synthesis/techmap_synth`
+
+Flip-flops
+^^^^^^^^^^
+
+Convert FFs to the types supported in hardware with :cmd:ref:`dfflegalize`, and
+then use :cmd:ref:`techmap` to map them.  We also run :cmd:ref:`simplemap` here
+to convert any remaining cells which could not be mapped to hardware into
+gate-level primitives.
+
 .. literalinclude:: /cmd/synth_ice40.rst
    :language: yoscrypt
    :start-after: map_ffs:
@@ -447,6 +543,23 @@ Hardware mapping
    :name: map_ffs
    :caption: ``map_ffs`` section
 
+.. figure:: /_images/code_examples/fifo/rdata_map_ffs.*
+   :class: width-helper
+   :name: rdata_map_ffs
+
+   ``rdata`` output after :ref:`map_ffs`
+
+.. seealso:: Advanced usage docs for
+   :doc:`/using_yosys/synthesis/techmap_synth`
+
+LUTs
+^^^^
+
+:cmd:ref:`abc` and :cmd:ref:`techmap` are used to map LUTs.  Note that the iCE40
+flow uses :cmd:ref:`abc` rather than :cmd:ref:`abc9`.  For more on what these
+do, and what the difference between these two commands are, refer to
+:doc:`/using_yosys/synthesis/abc`.
+
 .. literalinclude:: /cmd/synth_ice40.rst
    :language: yoscrypt
    :start-after: map_luts:
@@ -455,6 +568,22 @@ Hardware mapping
    :name: map_luts
    :caption: ``map_luts`` section
 
+.. figure:: /_images/code_examples/fifo/rdata_map_luts.*
+   :class: width-helper
+   :name: rdata_map_luts
+
+   ``rdata`` output after :ref:`map_luts`
+
+.. seealso:: Advanced usage docs for
+   
+   - :doc:`/using_yosys/synthesis/techmap_synth`
+   - :doc:`/using_yosys/synthesis/abc`
+
+Other cells
+^^^^^^^^^^^
+
+Seems to be wide LUTs into individual LUTs using :cmd:ref:`techmap`.
+
 .. literalinclude:: /cmd/synth_ice40.rst
    :language: yoscrypt
    :start-after: map_cells:
@@ -463,9 +592,13 @@ Hardware mapping
    :name: map_cells
    :caption: ``map_cells`` section
 
-:cmd:ref:`dfflibmap`
+.. figure:: /_images/code_examples/fifo/rdata_map_cells.*
-    This command maps the internal register cell types to the register types
+   :class: width-helper
-    described in a liberty file.
+   :name: rdata_map_cells
+
+   ``rdata`` output after :ref:`map_cells`
+
+.. TODO:: example_synth other cells
 
 :cmd:ref:`hilomap`
     Some architectures require special driver cells for driving a constant hi or
@@ -476,12 +609,8 @@ Hardware mapping
     Top-level input/outputs must usually be implemented using special I/O-pad
     cells. This command inserts such cells to the design.
 
-:cmd:ref:`dfflegalize`
-    Specify a set of supported FF cells/cell groups and convert all FFs to them.
-
 .. seealso:: Advanced usage docs for
-   :doc:`/yosys_internals/techmap`, and
+   :doc:`/yosys_internals/techmap`
-   :doc:`/using_yosys/synthesis/memory`.
 
 Final steps
 ~~~~~~~~~~~~