diff --git a/docs/source/code_examples/fifo/fifo.libmap b/docs/source/code_examples/fifo/fifo.libmap new file mode 100644 index 000000000..5889b7cfd --- /dev/null +++ b/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_ diff --git a/docs/source/code_examples/fifo/fifo.stat b/docs/source/code_examples/fifo/fifo.stat index b3a3d926f..0a278b6e2 100644 --- a/docs/source/code_examples/fifo/fifo.stat +++ b/docs/source/code_examples/fifo/fifo.stat @@ -36,7 +36,7 @@ yosys> stat yosys> stat -top fifo -16. Printing statistics. +17. Printing statistics. === fifo === diff --git a/docs/source/code_examples/fifo/fifo_map.ys b/docs/source/code_examples/fifo/fifo_map.ys index 701de3c35..f5a3edeb4 100644 --- a/docs/source/code_examples/fifo/fifo_map.ys +++ b/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 # ======================================================== diff --git a/docs/source/getting_started/example_synth.rst b/docs/source/getting_started/example_synth.rst index a8babb647..bcbe6efc9 100644 --- a/docs/source/getting_started/example_synth.rst +++ b/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`, -:cmd:ref:`memory_map`, and :cmd:ref:`techmap`. +Mapping to hard memory blocks uses a combination of :cmd:ref:`memory_libmap` and +: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`` -(highlighted). We can also see the memory address has been remapped, and the -data bits have been reordered (or swizzled). There is also now a ``$mux`` cell -controlling the value of ``rdata``. In :ref:`fifo-v` we wrote our memory as -read-before-write, however the ``SB_RAM40_4K`` has undefined behaviour when -reading from and writing to the same address in the same cycle. As a result, -extra logic is added so that the generated circuit matches the behaviour of the -verilog. :ref:`no_rw_check` describes how we could change our verilog to match -our hardware instead. +The :ref:`map_ram` converts the generic ``$mem_v2`` into the iCE40 +``SB_RAM40_4K`` (highlighted). We can also see the memory address has been +remapped, and the data bits have been reordered (or swizzled). There is also +now a ``$mux`` cell controlling the value of ``rdata``. In :ref:`fifo-v` we +wrote our memory as read-before-write, however the ``SB_RAM40_4K`` has undefined +behaviour when reading from and writing to the same address in the same cycle. +As a result, extra logic is added so that the generated circuit matches the +behaviour of the verilog. :ref:`no_rw_check` describes how we could change our +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