example_synth: more on hierarchy and stat

docs/source/code_examples/fifo/fifo.stat

@@ -0,0 +1,56 @@
+
+yosys> stat
+
+2. Printing statistics.
+
+=== fifo ===
+
+   Number of wires:                 28
+   Number of wire bits:            219
+   Number of public wires:           9
+   Number of public wire bits:      45
+   Number of memories:               1
+   Number of memory bits:         2048
+   Number of processes:              3
+   Number of cells:                  9
+     $add                            1
+     $logic_and                      2
+     $logic_not                      2
+     $memrd                          1
+     $sub                            1
+     addr_gen                        2
+
+=== addr_gen ===
+
+   Number of wires:                  8
+   Number of wire bits:             60
+   Number of public wires:           4
+   Number of public wire bits:      11
+   Number of memories:               0
+   Number of memory bits:            0
+   Number of processes:              2
+   Number of cells:                  2
+     $add                            1
+     $eq                             1
+
+
+yosys> stat -top fifo
+
+16. Printing statistics.
+
+=== fifo ===
+
+   Number of wires:                 97
+   Number of wire bits:            268
+   Number of public wires:          97
+   Number of public wire bits:     268
+   Number of memories:               0
+   Number of memory bits:            0
+   Number of processes:              0
+   Number of cells:                138
+     SB_CARRY                       26
+     SB_DFF                         26
+     SB_DFFER                       25
+     SB_LUT4                        60
+     SB_RAM40_4K                     1
+

docs/source/code_examples/fifo/fifo_map.ys

@@ -1,4 +1,7 @@
 read_verilog fifo.v
+echo on
+tee -o fifo.stat stat
+echo off
 synth_ice40 -top fifo -run begin:map_ram
 # this point should be the same as rdata_coarse
 
@@ -45,3 +48,7 @@ show -color maroon3 t:SB_CARRY -color cornflowerblue t:$lut -notitle -format dot
 synth_ice40 -top fifo -run map_cells:
 select -set rdata_path t:SB_RAM40_4K %ci*:-SB_RAM40_4K[WCLKE,WDATA,WADDR,WE] t:SB_RAM40_4K %co* %%
 show -color maroon3 t:SB_LUT* -notitle -format dot -prefix rdata_map_cells @rdata_path
+
+echo on
+tee -a fifo.stat stat -top fifo
+echo off

docs/source/getting_started/example_synth.rst

@@ -104,7 +104,9 @@ Since we're just getting started, let's instead begin with :yoscrypt:`hierarchy
 .. note::
 
    :cmd:ref:`hierarchy` should always be the first command after the design has
-   been read.
+   been read.  By specifying the top module, :cmd:ref:`hierarchy` will also set
+   the ``(* top *)`` attribute on it.  This is used by other commands that need
+   to know which module is the top.
 
 .. use doscon for a console-like display that supports the `yosys> [command]` format.
 
@@ -215,7 +217,7 @@ the reasons why hierarchy should always be the first command after loading the
 design.  If we know that our design won't run into this issue, we can skip the
 ``-defer``.
 
-.. TODO:: more on why :cmd:ref:`hierarchy` is important
+.. todo:: :cmd:ref:`hierarchy` failure modes
 
 .. note::
 
@@ -747,6 +749,39 @@ The new commands here are:
 - :doc:`/cmd/stat`, and
 - :doc:`/cmd/blackbox`.
 
+The output from :cmd:ref:`stat` is useful for checking resource utilization;
+providing a list of cells used in the design and the number of each, as well as
+the number of other resources used such as wires and processes.  For this
+design, the final call to :cmd:ref:`stat` should look something like the
+following:
+
+.. literalinclude:: /code_examples/fifo/fifo.stat
+   :language: doscon
+   :start-at: yosys> stat -top fifo
+
+Note that the :yoscrypt:`-top fifo` here is optional.  :cmd:ref:`stat` will
+automatically use the module with the ``top`` attribute set, which ``fifo`` was
+when we called :cmd:ref:`hierarchy`.  If no module is marked ``top``, then stats
+will be shown for each module selected.
+
+The :cmd:ref:`stat` output is also useful as a kind of sanity-check: Since we
+have already run :cmd:ref:`proc`, we wouldn't expect there to be any processes.
+We also expect ``data`` to use hard memory; if instead of an ``SB_RAM40_4K`` saw
+a high number of flip-flops being used we might suspect something was wrong.
+
+If we instead called :cmd:ref:`stat` immediately after :yoscrypt:`read_verilog
+fifo.v` we would see something very different:
+
+.. literalinclude:: /code_examples/fifo/fifo.stat
+   :language: doscon
+   :start-at: yosys> stat
+   :end-before: yosys> stat -top fifo
+
+Notice how ``fifo`` and ``addr_gen`` are listed separately, and the statistics
+for ``fifo`` show 2 ``addr_gen`` modules.  Because this is before the memory has
+been mapped, we also see that there is 1 memory with 2048 memory bits; matching
+our 8-bit wide ``data`` memory with 256 values (:math:`8*256=2048`).
+
 Synthesis output
 ^^^^^^^^^^^^^^^^
 
@@ -757,8 +792,8 @@ The iCE40 synthesis flow has the following output modes available:
 - :doc:`/cmd/write_json`.
 
 As an example, if we called :yoscrypt:`synth_ice40 -top fifo -json fifo.json`,
-our synthesized FIFO design will be output as ``fifo.json``.  We can then read
-the design back into Yosys with :cmd:ref:`read_json`, but make sure you use
+our synthesized ``fifo`` design will be output as ``fifo.json``.  We can then
+read the design back into Yosys with :cmd:ref:`read_json`, but make sure you use
 :yoscrypt:`design -reset` or open a new interactive terminal first.  The JSON
 output we get can also be loaded into `nextpnr`_ to do place and route; but that
 is beyond the scope of this documentation.