Docs: example_synth fifo update

More detail on `memory_libmap`, the `$__ICE40_RAM4K_` intermediate step, and the
bizarre opt output.

docs/source/code_examples/fifo/fifo.libmap

@@ -0,0 +1,65 @@
+
+yosys> debug memory_libmap -lib +/ice40/brams.txt -lib +/ice40/spram.txt -no-auto-huge
+
+yosys> memory_libmap -lib +/ice40/brams.txt -lib +/ice40/spram.txt -no-auto-huge
+
+4. Executing MEMORY_LIBMAP pass (mapping memories to cells).
+Memory fifo.data mapping candidates (post-geometry):
+- logic fallback
+  - cost: 2048.000000
+- $__ICE40_RAM4K_:
+  - option HAS_BE 0
+  - emulation score: 7
+  - replicates (for ports): 1
+  - replicates (for data): 1
+  - mux score: 0
+  - demux score: 0
+  - cost: 78.000000
+  - abits 11 dbits 2 4 8 16
+  - chosen base width 8
+  - swizzle 0 1 2 3 4 5 6 7
+  - emulate read-first behavior
+  - write port 0: port group W
+    - widths 2 4 8
+  - read port 0: port group R
+    - widths 2 4 8 16
+    - emulate transparency with write port 0
+- $__ICE40_RAM4K_:
+  - option HAS_BE 1
+  - emulation score: 7
+  - replicates (for ports): 1
+  - replicates (for data): 1
+  - mux score: 0
+  - demux score: 0
+  - cost: 78.000000
+  - abits 11 dbits 2 4 8 16
+  - byte width 1
+  - chosen base width 8
+  - swizzle 0 1 2 3 4 5 6 7
+  - emulate read-first behavior
+  - write port 0: port group W
+    - widths 16
+  - read port 0: port group R
+    - widths 2 4 8 16
+    - emulate transparency with write port 0
+Memory fifo.data mapping candidates (after post-geometry prune):
+- logic fallback
+  - cost: 2048.000000
+- $__ICE40_RAM4K_:
+  - option HAS_BE 0
+  - emulation score: 7
+  - replicates (for ports): 1
+  - replicates (for data): 1
+  - mux score: 0
+  - demux score: 0
+  - cost: 78.000000
+  - abits 11 dbits 2 4 8 16
+  - chosen base width 8
+  - swizzle 0 1 2 3 4 5 6 7
+  - emulate read-first behavior
+  - write port 0: port group W
+    - widths 2 4 8
+  - read port 0: port group R
+    - widths 2 4 8 16
+    - emulate transparency with write port 0
+mapping memory fifo.data via $__ICE40_RAM4K_

docs/source/code_examples/fifo/fifo.stat

@@ -36,7 +36,7 @@ yosys> stat
 
 yosys> stat -top fifo
 
-16. Printing statistics.
+17. Printing statistics.
 
 === fifo ===
 

docs/source/code_examples/fifo/fifo_map.ys

@@ -7,11 +7,14 @@ synth_ice40 -top fifo -run begin:map_ram
 
 # ========================================================
 
+echo on
+tee -o fifo.libmap debug memory_libmap -lib +/ice40/brams.txt -lib +/ice40/spram.txt -no-auto-huge
+echo off
 synth_ice40 -top fifo -run map_ram:map_ffram
 select -set mem t:SB_RAM40_4K
 select -set remap @mem %ci:+SB_RAM40_4K[RADDR] @mem %co %%
 select -set rdata_path t:SB_RAM40_4K %ci*:-SB_RAM40_4K[WCLKE,WDATA,WADDR,WE] t:SB_RAM40_4K %co* %%
-show -color maroon3 @mem -color cornflowerblue @remap -notitle -format dot -prefix rdata_map_ram @rdata_path
+show -color cornflowerblue @remap -notitle -format dot -prefix rdata_map_ram @rdata_path
 
 # ========================================================
 

docs/source/getting_started/example_synth.rst

@@ -592,8 +592,8 @@ If you skipped calling :yoscrypt:`read_verilog -D ICE40_HX -lib -specify
 Memory blocks
 ^^^^^^^^^^^^^
 
-Mapping to hard memory blocks uses a combination of :cmd:ref:`memory_libmap`,
+Mapping to hard memory blocks uses a combination of :cmd:ref:`memory_libmap` and
-:cmd:ref:`memory_map`, and :cmd:ref:`techmap`.
+:cmd:ref:`techmap`.
 
 .. literalinclude:: /cmd/synth_ice40.rst
    :language: yoscrypt
@@ -609,15 +609,33 @@ Mapping to hard memory blocks uses a combination of :cmd:ref:`memory_libmap`,
 
    ``rdata`` output after :ref:`map_ram`
 
-:ref:`map_ram` converts the generic ``$mem_v2`` into the iCE40 ``SB_RAM40_4K``
+The :ref:`map_ram` converts the generic ``$mem_v2`` into the iCE40
-(highlighted). We can also see the memory address has been remapped, and the
+``SB_RAM40_4K`` (highlighted). We can also see the memory address has been
-data bits have been reordered (or swizzled).  There is also now a ``$mux`` cell
+remapped, and the data bits have been reordered (or swizzled).  There is also
-controlling the value of ``rdata``.  In :ref:`fifo-v` we wrote our memory as
+now a ``$mux`` cell controlling the value of ``rdata``.  In :ref:`fifo-v` we
-read-before-write, however the ``SB_RAM40_4K`` has undefined behaviour when
+wrote our memory as read-before-write, however the ``SB_RAM40_4K`` has undefined
-reading from and writing to the same address in the same cycle.  As a result,
+behaviour when reading from and writing to the same address in the same cycle.
-extra logic is added so that the generated circuit matches the behaviour of the
+As a result, extra logic is added so that the generated circuit matches the
-verilog.  :ref:`no_rw_check` describes how we could change our verilog to match
+behaviour of the verilog.  :ref:`no_rw_check` describes how we could change our
-our hardware instead.
+verilog to match our hardware instead.
+
+If we run :cmd:ref:`memory_libmap` under the :cmd:ref:`debug` command we can see
+candidates which were identified for mapping, along with the costs of each and
+what logic requires emulation.
+
+.. literalinclude:: /code_examples/fifo/fifo.libmap
+   :language: doscon
+   :lines: 2, 6-
+
+The ``$__ICE40_RAM4K_`` cell is defined in the file |techlibs/ice40/brams.txt|_,
+with the mapping to ``SB_RAM40_4K`` done by :cmd:ref:`techmap` using
+|techlibs/ice40/brams_map.v|_.  Any leftover memory cells are then converted
+into flip flops (the ``logic fallback``) with :cmd:ref:`memory_map`.
+
+.. |techlibs/ice40/brams.txt| replace:: :file:`techlibs/ice40/brams.txt`
+.. _techlibs/ice40/brams.txt: https://github.com/YosysHQ/yosys/tree/master/techlibs/ice40/brams.txt
+.. |techlibs/ice40/brams_map.v| replace:: :file:`techlibs/ice40/brams_map.v`
+.. _techlibs/ice40/brams_map.v: https://github.com/YosysHQ/yosys/tree/master/techlibs/ice40/brams_map.v
 
 .. literalinclude:: /cmd/synth_ice40.rst
    :language: yoscrypt
@@ -633,7 +651,13 @@ our hardware instead.
 
    ``rdata`` output after :ref:`map_ffram`
 
-.. TODO:: what even is this opt output
+.. note::
+
+   The visual clutter on the ``RDATA`` output port (highlighted) is an
+   unfortunate side effect of :cmd:ref:`opt_clean` on the swizzled data bits. In
+   connecting the ``$mux`` input port directly to ``RDATA`` to reduce the number
+   of wires, the ``$techmap579\data.0.0.RDATA`` wire becomes more visually
+   complex.
 
 .. seealso:: Advanced usage docs for