From 12fa443fe36514329a87ae3cb394a4ab1ec1d578 Mon Sep 17 00:00:00 2001 From: Krystine Sherwin <93062060+KrystalDelusion@users.noreply.github.com> Date: Sat, 13 Jan 2024 17:46:04 +1300 Subject: [PATCH] example_synth: more on hierarchy and stat --- docs/source/code_examples/fifo/fifo.stat | 56 +++++++++++++++++++ docs/source/code_examples/fifo/fifo_map.ys | 7 +++ docs/source/getting_started/example_synth.rst | 43 ++++++++++++-- 3 files changed, 102 insertions(+), 4 deletions(-) create mode 100644 docs/source/code_examples/fifo/fifo.stat diff --git a/docs/source/code_examples/fifo/fifo.stat b/docs/source/code_examples/fifo/fifo.stat new file mode 100644 index 000000000..b3a3d926f --- /dev/null +++ b/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 + diff --git a/docs/source/code_examples/fifo/fifo_map.ys b/docs/source/code_examples/fifo/fifo_map.ys index 00c1f08ad..701de3c35 100644 --- a/docs/source/code_examples/fifo/fifo_map.ys +++ b/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 diff --git a/docs/source/getting_started/example_synth.rst b/docs/source/getting_started/example_synth.rst index 256bf7bba..9664b04f3 100644 --- a/docs/source/getting_started/example_synth.rst +++ b/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.