From e4ec3717bcceed6e78e646f1afd4ca1e22840ead Mon Sep 17 00:00:00 2001 From: Krystine Sherwin <93062060+KrystalDelusion@users.noreply.github.com> Date: Fri, 3 May 2024 13:14:25 +1200 Subject: [PATCH] Docs: Update internal cells to autoref --- docs/source/getting_started/example_synth.rst | 64 +++--- .../getting_started/scripting_intro.rst | 15 +- .../interactive_investigation.rst | 4 +- .../using_yosys/more_scripting/selections.rst | 12 +- .../using_yosys/synthesis/cell_libs.rst | 4 +- docs/source/using_yosys/synthesis/fsm.rst | 18 +- docs/source/using_yosys/synthesis/memory.rst | 10 +- docs/source/using_yosys/synthesis/opt.rst | 30 +-- .../yosys_internals/flow/verilog_frontend.rst | 4 +- .../yosys_internals/formats/cell_library.rst | 183 +++++++++--------- .../yosys_internals/formats/rtlil_rep.rst | 16 +- docs/source/yosys_internals/techmap.rst | 2 +- 12 files changed, 183 insertions(+), 179 deletions(-) diff --git a/docs/source/getting_started/example_synth.rst b/docs/source/getting_started/example_synth.rst index ae0a9a366..28e74ecc0 100644 --- a/docs/source/getting_started/example_synth.rst +++ b/docs/source/getting_started/example_synth.rst @@ -129,7 +129,7 @@ Our ``addr_gen`` circuit now looks like this: Simple operations like ``addr + 1`` and ``addr == MAX_DATA-1`` can be extracted from our ``always @`` block in :ref:`addr_gen-v`. This gives us the highlighted -``$add`` and ``$eq`` cells we see. But control logic (like the ``if .. else``) +`$add` and `$eq` cells we see. But control logic (like the ``if .. else``) and memory elements (like the ``addr <= 0``) are not so straightforward. These get put into "processes", shown in the schematic as ``PROC``. Note how the second line refers to the line numbers of the start/end of the corresponding @@ -151,8 +151,8 @@ automatic optimizations which would normally happen. ``addr_gen`` module after :yoscrypt:`proc -noopt` There are now a few new cells from our ``always @``, which have been -highlighted. The ``if`` statements are now modeled with ``$mux`` cells, while -the register uses an ``$adff`` cell. If we look at the terminal output we can +highlighted. The ``if`` statements are now modeled with `$mux` cells, while +the register uses an `$adff` cell. If we look at the terminal output we can also see all of the different ``proc_*`` commands being called. We will look at each of these in more detail in :doc:`/using_yosys/synthesis/proc`. @@ -171,7 +171,7 @@ clean`. ``addr_gen`` module after :yoscrypt:`opt_expr; clean` -You may also notice that the highlighted ``$eq`` cell input of ``255`` has +You may also notice that the highlighted `$eq` cell input of ``255`` has changed to ``8'11111111``. Constant values are presented in the format ``'``, with 32-bit values instead using the decimal number. This indicates that the constant input has been reduced from 32-bit wide to @@ -218,7 +218,7 @@ could restart our shell session, but instead let's use two new commands: :end-before: yosys> proc :caption: reloading :file:`fifo.v` and running :yoscrypt:`hierarchy -check -top fifo` -Notice how this time we didn't see any of those `$abstract` modules? That's +Notice how this time we didn't see any of those ``$abstract`` modules? That's because when we ran ``yosys fifo.v``, the first command Yosys called was :yoscrypt:`read_verilog -defer fifo.v`. The ``-defer`` option there tells :cmd:ref:`read_verilog` only read the abstract syntax tree and defer actual @@ -263,10 +263,10 @@ The highlighted ``fifo_reader`` block contains an instance of the instance of the ``addr_gen`` module with the ``MAX_DATA`` parameter set to the given value. -The other highlighted block is a ``$memrd`` cell. At this stage of synthesis we +The other highlighted block is a `$memrd` cell. At this stage of synthesis we don't yet know what type of memory is going to be implemented, but we *do* know that ``rdata <= data[raddr];`` could be implemented as a read from memory. Note -that the ``$memrd`` cell here is asynchronous, with both the clock and enable +that the `$memrd` cell here is asynchronous, with both the clock and enable signal undefined; shown with the ``1'x`` inputs. .. seealso:: Advanced usage docs for @@ -309,7 +309,7 @@ optimizations between modules which would otherwise be missed. Let's run The pieces have moved around a bit, but we can see :ref:`addr_gen_proc` from earlier has replaced the ``fifo_reader`` block in :ref:`rdata_proc`. We can also see that the ``addr`` output has been renamed to :file:`fifo_reader.addr` -and merged with the ``raddr`` wire feeding into the ``$memrd`` cell. This wire +and merged with the ``raddr`` wire feeding into the `$memrd` cell. This wire merging happened during the call to :cmd:ref:`clean` which we can see in the :ref:`flat_clean`. @@ -375,8 +375,8 @@ which are explored in more detail in :doc:`/using_yosys/synthesis/opt` and Up until now, the data path for ``rdata`` has remained the same since :ref:`rdata_flat`. However the next call to :cmd:ref:`opt` does cause a change. Specifically, the call to :cmd:ref:`opt_dff` without the ``-nodffe -nosdff`` -options is able to fold one of the ``$mux`` cells into the ``$adff`` to form an -``$adffe`` cell; highlighted below: +options is able to fold one of the `$mux` cells into the `$adff` to form an +`$adffe` cell; highlighted below: .. literalinclude:: /code_examples/fifo/fifo.out :language: doscon @@ -418,7 +418,7 @@ First up is :doc:`/cmd/wreduce`. If we run this we get the following: Looking at the data path for ``rdata``, the most relevant of these width reductions are the ones affecting ``fifo.$flatten\fifo_reader.$add$fifo.v``. -That is the ``$add`` cell incrementing the fifo_reader address. We can look at +That is the `$add` cell incrementing the fifo_reader address. We can look at the schematic and see the output of that cell has now changed. .. todo:: pending bugfix in :cmd:ref:`wreduce` and/or :cmd:ref:`opt_clean` @@ -451,8 +451,8 @@ Our next command to run is ``rdata`` output after :cmd:ref:`memory_dff` -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). This has +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). This has also connected the ``CLK`` port to the ``clk`` input as it is now a synchronous memory read with appropriate enable (``EN=1'1``) and reset (``ARST=1'0`` and ``SRST=1'0``) inputs. @@ -482,12 +482,12 @@ what they do. :name: synth_coarse3 :yoscrypt:`wreduce t:$mul` performs width reduction again, this time targetting -only cells of type ``$mul``. :yoscrypt:`techmap -map +/mul2dsp.v -map +only cells of type `$mul`. :yoscrypt:`techmap -map +/mul2dsp.v -map +/ice40/dsp_map.v ... -D DSP_NAME=$__MUL16X16` uses :cmd:ref:`techmap` to map -``$mul`` cells to ``$__MUL16X16`` which are, in turn, mapped to the iCE40 +`$mul` cells to ``$__MUL16X16`` which are, in turn, mapped to the iCE40 ``SB_MAC16``. Any multipliers which aren't compatible with conversion to ``$__MUL16X16`` are relabelled to ``$__soft_mul`` before :cmd:ref:`chtype` -changes them back to ``$mul``. +changes them back to `$mul`. During the mul2dsp conversion, some of the intermediate signals are marked with the attribute ``mul2dsp``. By calling :yoscrypt:`select a:mul2dsp` we restrict @@ -522,8 +522,8 @@ That brings us to the fourth and final part for the iCE40 synthesis flow: :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 help +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 help identify opportunities for reusing logic. We do this by running :cmd:ref:`alumacc`, which we can see produce the following changes in our example design: @@ -542,7 +542,7 @@ example design: Once these cells have been inserted, the call to :cmd:ref:`opt` can combine cells which are now identical but may have been missed due to e.g. the -difference between ``$add`` and ``$sub``. +difference between `$add` and `$sub`. The other new command in this part is :doc:`/cmd/memory`. :cmd:ref:`memory` is another macro command which we examine in more detail in @@ -559,7 +559,7 @@ combines all of the reads and writes for a memory block into a single cell. ``rdata`` output after :cmd:ref:`memory_collect` Looking at the schematic after running :cmd:ref:`memory_collect` we see that our -``$memrd_v2`` cell has been replaced with a ``$mem_v2`` cell named ``data``, the +`$memrd_v2` cell has been replaced with a `$mem_v2` cell named ``data``, the same name that we used in :ref:`fifo-v`. Where before we had a single set of signals for address and enable, we now have one set for reading (``RD_*``) and one for writing (``WR_*``), as well as both ``WR_DATA`` input and ``RD_DATA`` @@ -609,10 +609,10 @@ Mapping to hard memory blocks uses a combination of :cmd:ref:`memory_libmap` and ``rdata`` output after :ref:`map_ram` -The :ref:`map_ram` converts the generic ``$mem_v2`` into the iCE40 +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 +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 @@ -655,7 +655,7 @@ into flip flops (the ``logic fallback``) with :cmd:ref:`memory_map`. 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 + 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. @@ -668,10 +668,10 @@ Arithmetic ^^^^^^^^^^ Uses :cmd:ref:`techmap` to map basic arithmetic logic to hardware. This sees -somewhat of an explosion in cells as multi-bit ``$mux`` and ``$adffe`` are -replaced with single-bit ``$_MUX_`` and ``$_DFFE_PP0P_`` cells, while the -``$alu`` is replaced with primitive ``$_OR_`` and ``$_NOT_`` gates and a -``$lut`` cell. +somewhat of an explosion in cells as multi-bit :cell:ref:`$mux` and `$adffe` are +replaced with single-bit `$_MUX_` and `$_DFFE_PP0P_` cells, while the +:cell:ref:`$alu` is replaced with primitive `$_OR_` and `$_NOT_` gates and a +`$lut` cell. .. literalinclude:: /cmd/synth_ice40.rst :language: yoscrypt @@ -695,12 +695,12 @@ Flip-flops Convert FFs to the types supported in hardware with :cmd:ref:`dfflegalize`, and then use :cmd:ref:`techmap` to map them. In our example, this converts the -``$_DFFE_PP0P_`` cells to ``SB_DFFER``. +`$_DFFE_PP0P_` cells to ``SB_DFFER``. We also run :cmd:ref:`simplemap` here to convert any remaining cells which could not be mapped to hardware into gate-level primitives. This includes optimizing -``$_MUX_`` cells where one of the inputs is a constant ``1'0``, replacing it -instead with an ``$_AND_`` cell. +`$_MUX_` cells where one of the inputs is a constant ``1'0``, replacing it +instead with an `$_AND_` cell. .. literalinclude:: /cmd/synth_ice40.rst :language: yoscrypt @@ -723,7 +723,7 @@ LUTs ^^^^ :cmd:ref:`abc` and :cmd:ref:`techmap` are used to map LUTs; converting primitive -cell types to use ``$lut`` and ``SB_CARRY`` cells. Note that the iCE40 flow +cell types to use `$lut` and ``SB_CARRY`` cells. Note that the iCE40 flow uses :cmd:ref:`abc9` rather than :cmd:ref:`abc`. For more on what these do, and what the difference between these two commands are, refer to :doc:`/using_yosys/synthesis/abc`. @@ -742,7 +742,7 @@ what the difference between these two commands are, refer to ``rdata`` output after :ref:`map_luts` -Finally we use :cmd:ref:`techmap` to map the generic ``$lut`` cells to iCE40 +Finally we use :cmd:ref:`techmap` to map the generic `$lut` cells to iCE40 ``SB_LUT4`` cells. .. literalinclude:: /cmd/synth_ice40.rst diff --git a/docs/source/getting_started/scripting_intro.rst b/docs/source/getting_started/scripting_intro.rst index a6b4cb6bb..1e2ebabff 100644 --- a/docs/source/getting_started/scripting_intro.rst +++ b/docs/source/getting_started/scripting_intro.rst @@ -99,7 +99,7 @@ signifies we are matching on the *cell type*, and the ``*`` means to match anything. For this (very simple) selection, we are trying to find all of the cells, regardless of their type. The active selection is now shown as ``[addr_gen]*``, indicating some sub-selection of the ``addr_gen`` module. This -gives us the ``$add`` and ``$eq`` cells, which we want to highlight for the +gives us the `$add` and `$eq` cells, which we want to highlight for the :ref:`addr_gen_hier` image. .. _select_new_cells: @@ -111,10 +111,11 @@ by referring to it as ``@new_cells``, which we will see later. Then we clear the selection so that the following commands can operate on the full design. While we split that out for this document, we could have done the same thing in a single line by calling :yoscrypt:`select -set new_cells addr_gen/t:*`. If we -know we only have the one module in our design, we can even skip the `addr_gen/` -part. Looking further down :ref:`the fifo.ys code ` we can see this -with :yoscrypt:`select -set new_cells t:$mux t:*dff`. We can also see in that -command that selections don't have to be limited to a single statement. +know we only have the one module in our design, we can even skip the +``addr_gen/`` part. Looking further down :ref:`the fifo.ys code ` we +can see this with :yoscrypt:`select -set new_cells t:$mux t:*dff`. We can also +see in that command that selections don't have to be limited to a single +statement. Many commands also support an optional ``[selection]`` argument which can be used to override the currently selected objects. We could, for example, call @@ -184,8 +185,8 @@ like when we called :yoscrypt:`select -module addr_gen` in :ref:`select_intro`. That last parameter doesn't have to be a module name, it can be any valid selection string. Remember when we :ref:`assigned a name to a selection` and called it ``new_cells``? We saw in the -:yoscrypt:`select -list` output that it contained two cells, an ``$add`` and an -``$eq``. We can call :cmd:ref:`show` on that selection just as easily: +:yoscrypt:`select -list` output that it contained two cells, an `$add` and an +`$eq`. We can call :cmd:ref:`show` on that selection just as easily: .. figure:: /_images/code_examples/fifo/new_cells_show.* :class: width-helper invert-helper diff --git a/docs/source/using_yosys/more_scripting/interactive_investigation.rst b/docs/source/using_yosys/more_scripting/interactive_investigation.rst index 03a1faefa..77d826376 100644 --- a/docs/source/using_yosys/more_scripting/interactive_investigation.rst +++ b/docs/source/using_yosys/more_scripting/interactive_investigation.rst @@ -81,7 +81,7 @@ internal representation of the decision-trees and synchronization events modelled in a Verilog ``always``-block. The label reads ``PROC`` followed by a unique identifier in the first line and contains the source code location of the original ``always``-block in the second line. Note how the multiplexer from the -``?:``-expression is represented as a ``$mux`` cell but the multiplexer from the +``?:``-expression is represented as a `$mux` cell but the multiplexer from the ``if``-statement is yet still hidden within the process. The :cmd:ref:`proc` command transforms the process from the first diagram into a @@ -117,7 +117,7 @@ leads us to the third diagram: Here we see that the :cmd:ref:`opt` command not only has removed the artifacts left behind by :cmd:ref:`proc`, but also determined correctly that it can remove -the first ``$mux`` cell without changing the behavior of the circuit. +the first `$mux` cell without changing the behavior of the circuit. Break-out boxes for signal vectors ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/docs/source/using_yosys/more_scripting/selections.rst b/docs/source/using_yosys/more_scripting/selections.rst index b00283474..9c76b20b7 100644 --- a/docs/source/using_yosys/more_scripting/selections.rst +++ b/docs/source/using_yosys/more_scripting/selections.rst @@ -105,7 +105,7 @@ The :cmd:ref:`select` command is actually much more powerful than it might seem at first glance. When it is called with multiple arguments, each argument is evaluated and pushed separately on a stack. After all arguments have been processed it simply creates the union of all elements on the stack. So -:yoscrypt:`select t:$add a:foo` will select all ``$add`` cells and all objects +:yoscrypt:`select t:$add a:foo` will select all `$add` cells and all objects with the ``foo`` attribute set: .. literalinclude:: /code_examples/selections/foobaraddsub.v @@ -126,7 +126,7 @@ ineffective way of selecting the interesting part of the design. Special arguments can be used to combine the elements on the stack. For example the ``%i`` arguments pops the last two elements from the stack, intersects them, and pushes the result back on the stack. So :yoscrypt:`select t:$add a:foo %i` will -select all ``$add`` cells that have the ``foo`` attribute set: +select all `$add` cells that have the ``foo`` attribute set: .. code-block:: :caption: Output for command ``select t:$add a:foo %i -list`` on :numref:`foobaraddsub` @@ -220,7 +220,7 @@ The following sequence of diagrams demonstrates this step-wise expansion: Output of :yoscrypt:`show prod %ci %ci %ci` on :numref:`sumprod` Notice the subtle difference between :yoscrypt:`show prod %ci` and -:yoscrypt:`show prod %ci %ci`. Both images show the ``$mul`` cell driven by +:yoscrypt:`show prod %ci %ci`. Both images show the `$mul` cell driven by some inputs ``$3_Y`` and ``c``. However it is not until the second image, having called ``%ci`` the second time, that :cmd:ref:`show` is able to distinguish between ``$3_Y`` being a wire and ``c`` being an input. We can see @@ -296,7 +296,7 @@ cones`_ from above, we can use :yoscrypt:`show y %ci2`: Output of :yoscrypt:`show y %ci2` -From this we would learn that ``y`` is driven by a ``$dff cell``, that ``y`` is +From this we would learn that ``y`` is driven by a `$dff` cell, that ``y`` is connected to the output port ``Q``, that the ``clk`` signal goes into the ``CLK`` input port of the cell, and that the data comes from an auto-generated wire into the input ``D`` of the flip-flop cell (indicated by the ``$`` at the @@ -313,7 +313,7 @@ inputs. To add a pattern we add a colon followed by the pattern to the ``%ci`` action. The pattern itself starts with ``-`` or ``+``, indicating if it is an include or exclude pattern, followed by an optional comma separated list of cell types, followed by an optional comma separated list of port names in square -brackets. In this case, we want to exclude the ``S`` port of the ``$mux`` cell +brackets. In this case, we want to exclude the ``S`` port of the `$mux` cell type with :yoscrypt:`show y %ci5:-$mux[S]`: .. figure:: /_images/code_examples/selections/memdemo_03.* @@ -334,7 +334,7 @@ multiplexer select inputs and flip-flop cells: Output of ``show y %ci2:+$dff[Q,D] %ci*:-$mux[S]:-$dff`` Or we could use :yoscrypt:`show y %ci*:-[CLK,S]:+$dff:+$mux` instead, following -the input cone all the way but only following ``$dff`` and ``$mux`` cells, and +the input cone all the way but only following `$dff` and `$mux` cells, and ignoring any ports named ``CLK`` or ``S``: .. TODO:: pending discussion on whether rule ordering is a bug or a feature diff --git a/docs/source/using_yosys/synthesis/cell_libs.rst b/docs/source/using_yosys/synthesis/cell_libs.rst index 4e800bdf2..58b6431a5 100644 --- a/docs/source/using_yosys/synthesis/cell_libs.rst +++ b/docs/source/using_yosys/synthesis/cell_libs.rst @@ -98,8 +98,8 @@ our internal cell library will be mapped to: :name: mycells-lib :caption: :file:`mycells.lib` -Recall that the Yosys built-in logic gate types are ``$_NOT_``, ``$_AND_``, -``$_OR_``, ``$_XOR_``, and ``$_MUX_`` with an assortment of dff memory types. +Recall that the Yosys built-in logic gate types are `$_NOT_`, `$_AND_`, +`$_OR_`, `$_XOR_`, and `$_MUX_` with an assortment of dff memory types. :ref:`mycells-lib` defines our target cells as ``BUF``, ``NOT``, ``NAND``, ``NOR``, and ``DFF``. Mapping between these is performed with the commands :cmd:ref:`dfflibmap` and :cmd:ref:`abc` as follows: diff --git a/docs/source/using_yosys/synthesis/fsm.rst b/docs/source/using_yosys/synthesis/fsm.rst index e1ed55133..3c5a80ad3 100644 --- a/docs/source/using_yosys/synthesis/fsm.rst +++ b/docs/source/using_yosys/synthesis/fsm.rst @@ -24,12 +24,12 @@ following description: - Does not already have the ``\fsm_encoding`` attribute. - Is not an output of the containing module. -- Is driven by single ``$dff`` or ``$adff`` cell. -- The ``\D``-Input of this ``$dff`` or ``$adff`` cell is driven by a +- Is driven by single `$dff` or `$adff` cell. +- The ``\D``-Input of this `$dff` or `$adff` cell is driven by a multiplexer tree that only has constants or the old state value on its leaves. - The state value is only used in the said multiplexer tree or by simple - relational cells that compare the state value to a constant (usually ``$eq`` + relational cells that compare the state value to a constant (usually `$eq` cells). This heuristic has proven to work very well. It is possible to overwrite it by @@ -64,9 +64,11 @@ information is determined: The state registers (and asynchronous reset state, if applicable) is simply determined by identifying the driver for the state signal. -From there the ``$mux-tree`` driving the state register inputs is recursively +.. todo:: Figure out what `$mux-tree` should actually be. + +From there the `$mux-tree` driving the state register inputs is recursively traversed. All select inputs are control signals and the leaves of the -``$mux-tree`` are the states. The algorithm fails if a non-constant leaf that is +`$mux-tree` are the states. The algorithm fails if a non-constant leaf that is not the state signal itself is found. The list of control outputs is initialized with the bits from the state signal. @@ -99,18 +101,18 @@ create a transition table. For each state: 6. If step 4 was successful: Emit transition -Finally a ``$fsm`` cell is created with the generated transition table and added +Finally a `$fsm` cell is created with the generated transition table and added to the module. This new cell is connected to the control signals and the old drivers for the control outputs are disconnected. FSM optimization ~~~~~~~~~~~~~~~~ -The :cmd:ref:`fsm_opt` pass performs basic optimizations on ``$fsm`` cells (not +The :cmd:ref:`fsm_opt` pass performs basic optimizations on `$fsm` cells (not including state recoding). The following optimizations are performed (in this order): -- Unused control outputs are removed from the ``$fsm`` cell. The attribute +- Unused control outputs are removed from the `$fsm` cell. The attribute ``\unused_bits`` (that is usually set by the :cmd:ref:`opt_clean` pass) is used to determine which control outputs are unused. diff --git a/docs/source/using_yosys/synthesis/memory.rst b/docs/source/using_yosys/synthesis/memory.rst index e95a64875..dcbde2ae6 100644 --- a/docs/source/using_yosys/synthesis/memory.rst +++ b/docs/source/using_yosys/synthesis/memory.rst @@ -75,7 +75,7 @@ For example: techmap -map my_memory_map.v memory_map -:cmd:ref:`memory_libmap` attempts to convert memory cells (``$mem_v2`` etc) into +:cmd:ref:`memory_libmap` attempts to convert memory cells (`$mem_v2` etc) into hardware supported memory using a provided library (:file:`my_memory_map.txt` in the example above). Where necessary, emulation logic is added to ensure functional equivalence before and after this conversion. :yoscrypt:`techmap -map @@ -171,10 +171,10 @@ In general, you can expect the automatic selection process to work roughly like This process can be overridden by attaching a ram_style attribute to the memory: -- `(* ram_style = "logic" *)` selects FF RAM -- `(* ram_style = "distributed" *)` selects LUT RAM -- `(* ram_style = "block" *)` selects block RAM -- `(* ram_style = "huge" *)` selects huge RAM +- ``(* ram_style = "logic" *)`` selects FF RAM +- ``(* ram_style = "distributed" *)`` selects LUT RAM +- ``(* ram_style = "block" *)`` selects block RAM +- ``(* ram_style = "huge" *)`` selects huge RAM It is an error if this override cannot be realized for the given target. diff --git a/docs/source/using_yosys/synthesis/opt.rst b/docs/source/using_yosys/synthesis/opt.rst index 2a06aadd1..cd40f6999 100644 --- a/docs/source/using_yosys/synthesis/opt.rst +++ b/docs/source/using_yosys/synthesis/opt.rst @@ -31,7 +31,7 @@ described in :doc:`/yosys_internals/formats/cell_library`. This means a cell with all constant inputs is replaced with the constant value this cell drives. In some cases this pass can also optimize cells with some constant inputs. -.. table:: Const folding rules for ``$_AND_`` cells as used in :cmd:ref:`opt_expr`. +.. table:: Const folding rules for `$_AND_` cells as used in :cmd:ref:`opt_expr`. :name: tab:opt_expr_and :align: center @@ -54,7 +54,7 @@ In some cases this pass can also optimize cells with some constant inputs. ========= ========= =========== :numref:`Table %s ` shows the replacement rules used for -optimizing an ``$_AND_`` gate. The first three rules implement the obvious const +optimizing an `$_AND_` gate. The first three rules implement the obvious const folding rules. Note that 'any' might include dynamic values calculated by other parts of the circuit. The following three lines propagate undef (X) states. These are the only three cases in which it is allowed to propagate an undef @@ -66,18 +66,18 @@ substitutions are possible they are performed first, in the hope that the 'any' will change to an undef value or a 1 and therefore the output can be set to undef. -The last two lines simply replace an ``$_AND_`` gate with one constant-1 input +The last two lines simply replace an `$_AND_` gate with one constant-1 input with a buffer. Besides this basic const folding the :cmd:ref:`opt_expr` pass can replace 1-bit -wide ``$eq`` and ``$ne`` cells with buffers or not-gates if one input is +wide `$eq` and `$ne` cells with buffers or not-gates if one input is constant. Equality checks may also be reduced in size if there are redundant bits in the arguments (i.e. bits which are constant on both inputs). This can, for example, result in a 32-bit wide constant like ``255`` being reduced to the 8-bit value of ``8'11111111`` if the signal being compared is only 8-bit as in :ref:`addr_gen_clean` of :doc:`/getting_started/example_synth`. -The :cmd:ref:`opt_expr` pass is very conservative regarding optimizing ``$mux`` +The :cmd:ref:`opt_expr` pass is very conservative regarding optimizing `$mux` cells, as these cells are often used to model decision-trees and breaking these trees can interfere with other optimizations. @@ -100,7 +100,7 @@ identifies cells with identical inputs and replaces them with a single instance of the cell. The option ``-nomux`` can be used to disable resource sharing for multiplexer -cells (``$mux`` and ``$pmux``.) This can be useful as it prevents multiplexer +cells (`$mux` and `$pmux`.) This can be useful as it prevents multiplexer trees to be merged, which might prevent :cmd:ref:`opt_muxtree` to identify possible optimizations. @@ -141,16 +141,16 @@ Simplifying large MUXes and AND/OR gates - :cmd:ref:`opt_reduce` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ This is a simple optimization pass that identifies and consolidates identical -input bits to ``$reduce_and`` and ``$reduce_or`` cells. It also sorts the input -bits to ease identification of shareable ``$reduce_and`` and ``$reduce_or`` +input bits to `$reduce_and` and `$reduce_or` cells. It also sorts the input +bits to ease identification of shareable `$reduce_and` and `$reduce_or` cells in other passes. This pass also identifies and consolidates identical inputs to multiplexer -cells. In this case the new shared select bit is driven using a ``$reduce_or`` +cells. In this case the new shared select bit is driven using a `$reduce_or` cell that combines the original select bits. -Lastly this pass consolidates trees of ``$reduce_and`` cells and trees of -``$reduce_or`` cells to single large ``$reduce_and`` or ``$reduce_or`` cells. +Lastly this pass consolidates trees of `$reduce_and` cells and trees of +`$reduce_or` cells to single large `$reduce_and` or `$reduce_or` cells. These three simple optimizations are performed in a loop until a stable result is produced. @@ -160,7 +160,7 @@ Merging mutually exclusive cells with shared inputs - :cmd:ref:`opt_share` This pass identifies mutually exclusive cells of the same type that: a. share an input signal, and - b. drive the same ``$mux``, ``$_MUX_``, or ``$pmux`` multiplexing cell, + b. drive the same `$mux`, `$_MUX_`, or `$pmux` multiplexing cell, allowing the cell to be merged and the multiplexer to be moved from multiplexing its output to multiplexing the non-shared input signals. @@ -176,14 +176,14 @@ multiplexing its output to multiplexing the non-shared input signals. Before and after :cmd:ref:`opt_share` -When running :cmd:ref:`opt` in full, the original ``$mux`` (labeled ``$3``) is +When running :cmd:ref:`opt` in full, the original `$mux` (labeled ``$3``) is optimized away by :cmd:ref:`opt_expr`. Performing DFF optimizations - :cmd:ref:`opt_dff` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -This pass identifies single-bit d-type flip-flops (``$_DFF_``, ``$dff``, and -``$adff`` cells) with a constant data input and replaces them with a constant +This pass identifies single-bit d-type flip-flops (`$_DFF_`, `$dff`, and +`$adff` cells) with a constant data input and replaces them with a constant driver. It can also merge clock enables and synchronous reset multiplexers, removing unused control inputs. diff --git a/docs/source/yosys_internals/flow/verilog_frontend.rst b/docs/source/yosys_internals/flow/verilog_frontend.rst index f2eaeae97..7c8c9d8fb 100644 --- a/docs/source/yosys_internals/flow/verilog_frontend.rst +++ b/docs/source/yosys_internals/flow/verilog_frontend.rst @@ -627,7 +627,7 @@ from a behavioural model to an RTL representation is performed by the asynchronous resets if necessary). - | :cmd:ref:`proc_dff` - | This pass replaces the ``RTLIL::MemWriteAction``\ s with ``$memwr`` cells. + | This pass replaces the ``RTLIL::MemWriteAction``\ s with `$memwr` cells. - | :cmd:ref:`proc_clean` | A final call to :cmd:ref:`proc_clean` removes the now empty @@ -646,7 +646,7 @@ to extend the actual Verilog frontend. .. todo:: Synthesizing Verilog arrays - Add some information on the generation of ``$memrd`` and ``$memwr`` cells and + Add some information on the generation of `$memrd` and `$memwr` cells and how they are processed in the memory pass. diff --git a/docs/source/yosys_internals/formats/cell_library.rst b/docs/source/yosys_internals/formats/cell_library.rst index 2e30ee25c..cd1496e11 100644 --- a/docs/source/yosys_internals/formats/cell_library.rst +++ b/docs/source/yosys_internals/formats/cell_library.rst @@ -73,15 +73,15 @@ also have the following parameters: :verilog:`Y = !A` $logic_not ================== ============ -For the unary cells that output a logical value (``$reduce_and``, -``$reduce_or``, ``$reduce_xor``, ``$reduce_xnor``, ``$reduce_bool``, -``$logic_not``), when the ``\Y_WIDTH`` parameter is greater than 1, the output +For the unary cells that output a logical value (`$reduce_and`, +`$reduce_or`, `$reduce_xor`, `$reduce_xnor`, `$reduce_bool`, +`$logic_not`), when the ``\Y_WIDTH`` parameter is greater than 1, the output is zero-extended, and only the least significant bit varies. -Note that ``$reduce_or`` and ``$reduce_bool`` actually represent the same logic +Note that `$reduce_or` and `$reduce_bool` actually represent the same logic function. But the HDL frontends generate them in different situations. A -``$reduce_or`` cell is generated when the prefix ``|`` operator is being used. A -``$reduce_bool`` cell is generated when a bit vector is used as a condition in +`$reduce_or` cell is generated when the prefix ``|`` operator is being used. A +`$reduce_bool` cell is generated when a bit vector is used as a condition in an ``if``-statement or ``?:``-expression. Binary operators @@ -130,28 +130,28 @@ All binary RTL cells have two input ports ``\A`` and ``\B`` and one output port :verilog:`Y = A ** B` $pow ``N/A`` $modfloor ======================= ============= ======================= ========= -The ``$shl`` and ``$shr`` cells implement logical shifts, whereas the ``$sshl`` -and ``$sshr`` cells implement arithmetic shifts. The ``$shl`` and ``$sshl`` +The `$shl` and `$shr` cells implement logical shifts, whereas the `$sshl` +and `$sshr` cells implement arithmetic shifts. The `$shl` and `$sshl` cells implement the same operation. All four of these cells interpret the second operand as unsigned, and require ``\B_SIGNED`` to be zero. Two additional shift operator cells are available that do not directly -correspond to any operator in Verilog, ``$shift`` and ``$shiftx``. The -``$shift`` cell performs a right logical shift if the second operand is positive -(or unsigned), and a left logical shift if it is negative. The ``$shiftx`` cell -performs the same operation as the ``$shift`` cell, but the vacated bit +correspond to any operator in Verilog, `$shift` and `$shiftx`. The +`$shift` cell performs a right logical shift if the second operand is positive +(or unsigned), and a left logical shift if it is negative. The `$shiftx` cell +performs the same operation as the `$shift` cell, but the vacated bit positions are filled with undef (x) bits, and corresponds to the Verilog indexed part-select expression. -For the binary cells that output a logical value (``$logic_and``, ``$logic_or``, -``$eqx``, ``$nex``, ``$lt``, ``$le``, ``$eq``, ``$ne``, ``$ge``, ``$gt``), when +For the binary cells that output a logical value (`$logic_and`, `$logic_or`, +`$eqx`, `$nex`, `$lt`, `$le`, `$eq`, `$ne`, `$ge`, `$gt`), when the ``\Y_WIDTH`` parameter is greater than 1, the output is zero-extended, and only the least significant bit varies. Division and modulo cells are available in two rounding modes. The original -``$div`` and ``$mod`` cells are based on truncating division, and correspond to -the semantics of the verilog ``/`` and ``%`` operators. The ``$divfloor`` and -``$modfloor`` cells represent flooring division and flooring modulo, the latter +`$div` and `$mod` cells are based on truncating division, and correspond to +the semantics of the verilog ``/`` and ``%`` operators. The `$divfloor` and +`$modfloor` cells represent flooring division and flooring modulo, the latter of which is also known as "remainder" in several languages. See :numref:`tab:CellLib_divmod` for a side-by-side comparison between the different semantics. @@ -180,14 +180,14 @@ Multiplexers are generated by the Verilog HDL frontend for ``?:``-expressions. Multiplexers are also generated by the proc pass to map the decision trees from RTLIL::Process objects to logic. -The simplest multiplexer cell type is ``$mux``. Cells of this type have a +The simplest multiplexer cell type is `$mux`. Cells of this type have a ``\WITDH`` parameter and data inputs ``\A`` and ``\B`` and a data output ``\Y``, all of the specified width. This cell also has a single bit control input ``\S``. If ``\S`` is 0 the value from the input ``\A`` is sent to the output, if -it is 1 the value from the ``\B`` input is sent to the output. So the ``$mux`` +it is 1 the value from the ``\B`` input is sent to the output. So the `$mux` cell implements the function :verilog:`Y = S ? B : A`. -The ``$pmux`` cell is used to multiplex between many inputs using a one-hot +The `$pmux` cell is used to multiplex between many inputs using a one-hot select signal. Cells of this type have a ``\WIDTH`` and a ``\S_WIDTH`` parameter and inputs ``\A``, ``\B``, and ``\S`` and an output ``\Y``. The ``\S`` input is ``\S_WIDTH`` bits wide. The ``\A`` input and the output are both ``\WIDTH`` bits @@ -199,24 +199,24 @@ from ``\S`` is set the output is undefined. Cells of this type are used to model "parallel cases" (defined by using the ``parallel_case`` attribute or detected by an optimization). -The ``$tribuf`` cell is used to implement tristate logic. Cells of this type +The `$tribuf` cell is used to implement tristate logic. Cells of this type have a ``\WIDTH`` parameter and inputs ``\A`` and ``\EN`` and an output ``\Y``. The ``\A`` input and ``\Y`` output are ``\WIDTH`` bits wide, and the ``\EN`` input is one bit wide. When ``\EN`` is 0, the output is not driven. When ``\EN`` is 1, the value from ``\A`` input is sent to the ``\Y`` output. Therefore, the -``$tribuf`` cell implements the function :verilog:`Y = EN ? A : 'bz`. +`$tribuf` cell implements the function :verilog:`Y = EN ? A : 'bz`. Behavioural code with cascaded if-then-else- and case-statements usually results in trees of multiplexer cells. Many passes (from various optimizations to FSM extraction) heavily depend on these multiplexer trees to understand dependencies between signals. Therefore optimizations should not break these multiplexer trees (e.g. by replacing a multiplexer between a calculated signal and a -constant zero with an ``$and`` gate). +constant zero with an `$and` gate). Registers ~~~~~~~~~ -SR-type latches are represented by ``$sr`` cells. These cells have input ports +SR-type latches are represented by `$sr` cells. These cells have input ports ``\SET`` and ``\CLR`` and an output port ``\Q``. They have the following parameters: @@ -232,12 +232,12 @@ parameters: ``1'b1`` and active-low if this parameter is ``1'b0``. Both set and reset inputs have separate bits for every output bit. When both the -set and reset inputs of an ``$sr`` cell are active for a given bit index, the +set and reset inputs of an `$sr` cell are active for a given bit index, the reset input takes precedence. -D-type flip-flops are represented by ``$dff`` cells. These cells have a clock +D-type flip-flops are represented by `$dff` cells. These cells have a clock port ``\CLK``, an input port ``\D`` and an output port ``\Q``. The following -parameters are available for ``$dff`` cells: +parameters are available for `$dff` cells: ``\WIDTH`` The width of input ``\D`` and output ``\Q``. @@ -246,8 +246,8 @@ parameters are available for ``$dff`` cells: Clock is active on the positive edge if this parameter has the value ``1'b1`` and on the negative edge if this parameter is ``1'b0``. -D-type flip-flops with asynchronous reset are represented by ``$adff`` cells. As -the ``$dff`` cells they have ``\CLK``, ``\D`` and ``\Q`` ports. In addition they +D-type flip-flops with asynchronous reset are represented by `$adff` cells. As +the `$dff` cells they have ``\CLK``, ``\D`` and ``\Q`` ports. In addition they also have a single-bit ``\ARST`` input port for the reset pin and the following additional two parameters: @@ -261,8 +261,8 @@ additional two parameters: Usually these cells are generated by the :cmd:ref:`proc` pass using the information in the designs RTLIL::Process objects. -D-type flip-flops with synchronous reset are represented by ``$sdff`` cells. As -the ``$dff`` cells they have ``\CLK``, ``\D`` and ``\Q`` ports. In addition they +D-type flip-flops with synchronous reset are represented by `$sdff` cells. As +the `$dff` cells they have ``\CLK``, ``\D`` and ``\Q`` ports. In addition they also have a single-bit ``\SRST`` input port for the reset pin and the following additional two parameters: @@ -273,11 +273,11 @@ additional two parameters: ``\SRST_VALUE`` The state of ``\Q`` will be set to this value when the reset is active. -Note that the ``$adff`` and ``$sdff`` cells can only be used when the reset +Note that the `$adff` and `$sdff` cells can only be used when the reset value is constant. -D-type flip-flops with asynchronous load are represented by ``$aldff`` cells. As -the ``$dff`` cells they have ``\CLK``, ``\D`` and ``\Q`` ports. In addition they +D-type flip-flops with asynchronous load are represented by `$aldff` cells. As +the `$dff` cells they have ``\CLK``, ``\D`` and ``\Q`` ports. In addition they also have a single-bit ``\ALOAD`` input port for the async load enable pin, a ``\AD`` input port with the same width as data for the async load data, and the following additional parameter: @@ -286,15 +286,15 @@ following additional parameter: The asynchronous load is active-high if this parameter has the value ``1'b1`` and active-low if this parameter is ``1'b0``. -D-type flip-flops with asynchronous set and reset are represented by ``$dffsr`` -cells. As the ``$dff`` cells they have ``\CLK``, ``\D`` and ``\Q`` ports. In +D-type flip-flops with asynchronous set and reset are represented by `$dffsr` +cells. As the `$dff` cells they have ``\CLK``, ``\D`` and ``\Q`` ports. In addition they also have multi-bit ``\SET`` and ``\CLR`` input ports and the -corresponding polarity parameters, like ``$sr`` cells. +corresponding polarity parameters, like `$sr` cells. -D-type flip-flops with enable are represented by ``$dffe``, ``$adffe``, -``$aldffe``, ``$dffsre``, ``$sdffe``, and ``$sdffce`` cells, which are enhanced -variants of ``$dff``, ``$adff``, ``$aldff``, ``$dffsr``, ``$sdff`` (with reset -over enable) and ``$sdff`` (with enable over reset) cells, respectively. They +D-type flip-flops with enable are represented by `$dffe`, `$adffe`, +`$aldffe`, `$dffsre`, `$sdffe`, and `$sdffce` cells, which are enhanced +variants of `$dff`, `$adff`, `$aldff`, `$dffsr`, `$sdff` (with reset +over enable) and `$sdff` (with enable over reset) cells, respectively. They have the same ports and parameters as their base cell. In addition they also have a single-bit ``\EN`` input port for the enable pin and the following parameter: @@ -303,9 +303,9 @@ parameter: The enable input is active-high if this parameter has the value ``1'b1`` and active-low if this parameter is ``1'b0``. -D-type latches are represented by ``$dlatch`` cells. These cells have an enable +D-type latches are represented by `$dlatch` cells. These cells have an enable port ``\EN``, an input port ``\D``, and an output port ``\Q``. The following -parameters are available for ``$dlatch`` cells: +parameters are available for `$dlatch` cells: ``\WIDTH`` The width of input ``\D`` and output ``\Q``. @@ -316,8 +316,8 @@ parameters are available for ``$dlatch`` cells: The latch is transparent when the ``\EN`` input is active. -D-type latches with reset are represented by ``$adlatch`` cells. In addition to -``$dlatch`` ports and parameters, they also have a single-bit ``\ARST`` input +D-type latches with reset are represented by `$adlatch` cells. In addition to +`$dlatch` ports and parameters, they also have a single-bit ``\ARST`` input port for the reset pin and the following additional parameters: ``\ARST_POLARITY`` @@ -327,9 +327,9 @@ port for the reset pin and the following additional parameters: ``\ARST_VALUE`` The state of ``\Q`` will be set to this value when the reset is active. -D-type latches with set and reset are represented by ``$dlatchsr`` cells. In -addition to ``$dlatch`` ports and parameters, they also have multi-bit ``\SET`` -and ``\CLR`` input ports and the corresponding polarity parameters, like ``$sr`` +D-type latches with set and reset are represented by `$dlatchsr` cells. In +addition to `$dlatch` ports and parameters, they also have multi-bit ``\SET`` +and ``\CLR`` input ports and the corresponding polarity parameters, like `$sr` cells. .. _sec:memcells: @@ -337,20 +337,20 @@ cells. Memories ~~~~~~~~ -Memories are either represented using ``RTLIL::Memory`` objects, ``$memrd_v2``, -``$memwr_v2``, and ``$meminit_v2`` cells, or by ``$mem_v2`` cells alone. +Memories are either represented using ``RTLIL::Memory`` objects, `$memrd_v2`, +`$memwr_v2`, and `$meminit_v2` cells, or by `$mem_v2` cells alone. In the first alternative the ``RTLIL::Memory`` objects hold the general metadata for the memory (bit width, size in number of words, etc.) and for each port a -``$memrd_v2`` (read port) or ``$memwr_v2`` (write port) cell is created. Having +`$memrd_v2` (read port) or `$memwr_v2` (write port) cell is created. Having individual cells for read and write ports has the advantage that they can be consolidated using resource sharing passes. In some cases this drastically reduces the number of required ports on the memory cell. In this alternative, -memory initialization data is represented by ``$meminit_v2`` cells, which allow +memory initialization data is represented by `$meminit_v2` cells, which allow delaying constant folding for initialization addresses and data until after the frontend finishes. -The ``$memrd_v2`` cells have a clock input ``\CLK``, an enable input ``\EN``, an +The `$memrd_v2` cells have a clock input ``\CLK``, an enable input ``\EN``, an address input ``\ADDR``, a data output ``\DATA``, an asynchronous reset input ``\ARST``, and a synchronous reset input ``\SRST``. They also have the following parameters: @@ -411,7 +411,7 @@ parameters: when ``\EN`` is true. Otherwise, ``\SRST`` is recognized regardless of ``\EN``. -The ``$memwr_v2`` cells have a clock input ``\CLK``, an enable input ``\EN`` +The `$memwr_v2` cells have a clock input ``\CLK``, an enable input ``\EN`` (one enable bit for each data bit), an address input ``\ADDR`` and a data input ``\DATA``. They also have the following parameters: @@ -424,7 +424,7 @@ The ``$memwr_v2`` cells have a clock input ``\CLK``, an enable input ``\EN`` ``\WIDTH`` The number of data bits (width of the ``\DATA`` output port). Like with - ``$memrd_v2`` cells, the width is allowed to be any power-of-two + `$memrd_v2` cells, the width is allowed to be any power-of-two multiple of memory width, with the corresponding restriction on address. ``\CLK_ENABLE`` @@ -448,7 +448,7 @@ The ``$memwr_v2`` cells have a clock input ``\CLK``, an enable input ``\EN`` undefined. Priority can only be set between two synchronous ports sharing the same clock domain. -The ``$meminit_v2`` cells have an address input ``\ADDR``, a data input +The `$meminit_v2` cells have an address input ``\ADDR``, a data input ``\DATA``, with the width of the ``\DATA`` port equal to ``\WIDTH`` parameter times ``\WORDS`` parameter, and a bit enable mask input ``\EN`` with width equal to ``\WIDTH`` parameter. All three of the inputs must resolve to a constant for @@ -472,19 +472,19 @@ synthesis to succeed. initialization conflict. The HDL frontend models a memory using ``RTLIL::Memory`` objects and -asynchronous ``$memrd_v2`` and ``$memwr_v2`` cells. The :cmd:ref:`memory` pass -(i.e. its various sub-passes) migrates ``$dff`` cells into the ``$memrd_v2`` and -``$memwr_v2`` cells making them synchronous, then converts them to a single -``$mem_v2`` cell and (optionally) maps this cell type to ``$dff`` cells for the +asynchronous `$memrd_v2` and `$memwr_v2` cells. The :cmd:ref:`memory` pass +(i.e. its various sub-passes) migrates `$dff` cells into the `$memrd_v2` and +`$memwr_v2` cells making them synchronous, then converts them to a single +`$mem_v2` cell and (optionally) maps this cell type to `$dff` cells for the individual words and multiplexer-based address decoders for the read and write -interfaces. When the last step is disabled or not possible, a ``$mem_v2`` cell +interfaces. When the last step is disabled or not possible, a `$mem_v2` cell is left in the design. -The ``$mem_v2`` cell provides the following parameters: +The `$mem_v2` cell provides the following parameters: ``\MEMID`` The name of the original ``RTLIL::Memory`` object that became this - ``$mem_v2`` cell. + `$mem_v2` cell. ``\SIZE`` The number of words in the memory. @@ -519,12 +519,12 @@ The ``$mem_v2`` cell provides the following parameters: ``\RD_TRANSPARENCY_MASK`` This parameter is ``\RD_PORTS*\WR_PORTS`` bits wide, containing a concatenation of all ``\TRANSPARENCY_MASK`` values of the original - ``$memrd_v2`` cells. + `$memrd_v2` cells. ``\RD_COLLISION_X_MASK`` This parameter is ``\RD_PORTS*\WR_PORTS`` bits wide, containing a concatenation of all ``\COLLISION_X_MASK`` values of the original - ``$memrd_v2`` cells. + `$memrd_v2` cells. ``\RD_CE_OVER_SRST`` This parameter is ``\RD_PORTS`` bits wide, determining relative @@ -560,9 +560,9 @@ The ``$mem_v2`` cell provides the following parameters: ``\WR_PRIORITY_MASK`` This parameter is ``\WR_PORTS*\WR_PORTS`` bits wide, containing a concatenation of all ``\PRIORITY_MASK`` values of the original - ``$memwr_v2`` cells. + `$memwr_v2` cells. -The ``$mem_v2`` cell has the following ports: +The `$mem_v2` cell has the following ports: ``\RD_CLK`` This input is ``\RD_PORTS`` bits wide, containing all clock signals for @@ -605,24 +605,24 @@ The ``$mem_v2`` cell has the following ports: signals for the write ports. The :cmd:ref:`memory_collect` pass can be used to convert discrete -``$memrd_v2``, ``$memwr_v2``, and ``$meminit_v2`` cells belonging to the same -memory to a single ``$mem_v2`` cell, whereas the :cmd:ref:`memory_unpack` pass +`$memrd_v2`, `$memwr_v2`, and `$meminit_v2` cells belonging to the same +memory to a single `$mem_v2` cell, whereas the :cmd:ref:`memory_unpack` pass performs the inverse operation. The :cmd:ref:`memory_dff` pass can combine asynchronous memory ports that are fed by or feeding registers into synchronous memory ports. The :cmd:ref:`memory_bram` pass can be used to recognize -``$mem_v2`` cells that can be implemented with a block RAM resource on an FPGA. -The :cmd:ref:`memory_map` pass can be used to implement ``$mem_v2`` cells as +`$mem_v2` cells that can be implemented with a block RAM resource on an FPGA. +The :cmd:ref:`memory_map` pass can be used to implement `$mem_v2` cells as basic logic: word-wide DFFs and address decoders. Finite state machines ~~~~~~~~~~~~~~~~~~~~~ -Add a brief description of the ``$fsm`` cell type. +Add a brief description of the `$fsm` cell type. Coarse arithmetics ~~~~~~~~~~~~~~~~~~~~~ -The ``$macc`` cell type represents a generalized multiply and accumulate operation. The cell is purely combinational. It outputs the result of summing up a sequence of products and other injected summands. +The `$macc` cell type represents a generalized multiply and accumulate operation. The cell is purely combinational. It outputs the result of summing up a sequence of products and other injected summands. .. code-block:: @@ -708,21 +708,21 @@ in the ``\TABLE`` values. Specify rules ~~~~~~~~~~~~~ -Add information about ``$specify2``, ``$specify3``, and ``$specrule`` cells. +Add information about `$specify2`, `$specify3`, and `$specrule` cells. Formal verification cells ~~~~~~~~~~~~~~~~~~~~~~~~~ -Add information about ``$check``, ``$assert``, ``$assume``, ``$live``, ``$fair``, -``$cover``, ``$equiv``, ``$initstate``, ``$anyconst``, ``$anyseq``, -``$anyinit``, ``$allconst``, ``$allseq`` cells. +Add information about `$check`, `$assert`, `$assume`, `$live`, `$fair`, +`$cover`, `$equiv`, `$initstate`, `$anyconst`, `$anyseq`, +`$anyinit`, `$allconst`, `$allseq` cells. -Add information about ``$ff`` and ``$_FF_`` cells. +Add information about `$ff` and `$_FF_` cells. Debugging cells ~~~~~~~~~~~~~~~ -The ``$print`` cell is used to log the values of signals, akin to (and +The `$print` cell is used to log the values of signals, akin to (and translatable to) the ``$display`` and ``$write`` family of tasks in Verilog. It has the following parameters: @@ -746,13 +746,14 @@ If ``\TRG_ENABLE`` is true, the following parameters also apply: negative-edge triggered. ``\PRIORITY`` - When multiple ``$print`` or ``$$check`` cells fire on the same trigger, they\ + When multiple `$print` or `$check` cells fire on the same trigger, they execute in descending priority order. Ports: ``\TRG`` - The signals that control when this ``$print`` cell is triggered. + The signals that control when this `$print` cell is triggered. + If the width of this port is zero and ``\TRG_ENABLE`` is true, the cell is triggered during initial evaluation (time zero) only. @@ -1040,14 +1041,14 @@ Tables :numref:`%s `, :numref:`%s `, :numref:`%s `, :numref:`%s `, :numref:`%s `, :numref:`%s ` and :numref:`%s ` list all -cell types used for gate level logic. The cell types ``$_BUF_``, ``$_NOT_``, -``$_AND_``, ``$_NAND_``, ``$_ANDNOT_``, ``$_OR_``, ``$_NOR_``, ``$_ORNOT_``, -``$_XOR_``, ``$_XNOR_``, ``$_AOI3_``, ``$_OAI3_``, ``$_AOI4_``, ``$_OAI4_``, -``$_MUX_``, ``$_MUX4_``, ``$_MUX8_``, ``$_MUX16_`` and ``$_NMUX_`` are used to -model combinatorial logic. The cell type ``$_TBUF_`` is used to model tristate +cell types used for gate level logic. The cell types `$_BUF_`, `$_NOT_`, +`$_AND_`, `$_NAND_`, `$_ANDNOT_`, `$_OR_`, `$_NOR_`, `$_ORNOT_`, +`$_XOR_`, `$_XNOR_`, `$_AOI3_`, `$_OAI3_`, `$_AOI4_`, `$_OAI4_`, +`$_MUX_`, `$_MUX4_`, `$_MUX8_`, `$_MUX16_` and `$_NMUX_` are used to +model combinatorial logic. The cell type `$_TBUF_` is used to model tristate logic. -The ``$_MUX4_``, ``$_MUX8_`` and ``$_MUX16_`` cells are used to model wide +The `$_MUX4_`, `$_MUX8_` and `$_MUX16_` cells are used to model wide muxes, and correspond to the following Verilog code: .. code-block:: verilog @@ -1071,7 +1072,7 @@ muxes, and correspond to the following Verilog code: T ? (S ? D : C) : (S ? B : A); -The cell types ``$_DFF_N_`` and ``$_DFF_P_`` represent d-type flip-flops. +The cell types `$_DFF_N_` and `$_DFF_P_` represent d-type flip-flops. The cell types ``$_DFFE_[NP][NP]_`` implement d-type flip-flops with enable. The values in the table for these cell types relate to the following Verilog code @@ -1186,7 +1187,7 @@ is ``posedge`` if ``SET_LVL`` if ``1``, ``negedge`` otherwise. else if (E == EN_LVL) Q <= D; -The cell types ``$_DLATCH_N_`` and ``$_DLATCH_P_`` represent d-type latches. +The cell types `$_DLATCH_N_` and `$_DLATCH_P_` represent d-type latches. The cell types ``$_DLATCH_[NP][NP][01]_`` implement d-type latches with reset. The values in the table for these cell types relate to the following Verilog @@ -1234,8 +1235,8 @@ mapped to physical flip-flop cells from a Liberty file using the dfflibmap pass. The combinatorial logic cells can be mapped to physical cells from a Liberty file via ABC using the abc pass. -.. todo:: Add information about ``$slice`` and ``$concat`` cells. +.. todo:: Add information about `$slice` and `$concat` cells. -.. todo:: Add information about ``$alu``, ``$fa``, and ``$lcu`` cells. +.. todo:: Add information about `$alu`, `$fa`, and `$lcu` cells. .. todo:: Add information about ``$demux`` cell. \ No newline at end of file diff --git a/docs/source/yosys_internals/formats/rtlil_rep.rst b/docs/source/yosys_internals/formats/rtlil_rep.rst index 2737cd4bd..785a2d28b 100644 --- a/docs/source/yosys_internals/formats/rtlil_rep.rst +++ b/docs/source/yosys_internals/formats/rtlil_rep.rst @@ -79,7 +79,7 @@ This has three advantages: example, :cmd:ref:`opt_clean` tries to preserve signals with a user-provided name but doesn't hesitate to delete signals that have auto-generated names when they just duplicate other signals. Note that this can be overridden - with the `-purge` option to also delete internal nets with user-provided + with the ``-purge`` option to also delete internal nets with user-provided names. - Third, the delicate job of finding suitable auto-generated public visible @@ -366,7 +366,7 @@ multiplexer for the enable signal: end Different combinations of passes may yield different results. Note that -``$adff`` and ``$mux`` are internal cell types that still need to be mapped to +`$adff` and `$mux` are internal cell types that still need to be mapped to cell types from the target cell library. Some passes refuse to operate on modules that still contain ``RTLIL::Process`` @@ -389,25 +389,25 @@ A memory object has the following properties: - The width of an addressable word - The size of the memory in number of words -All read accesses to the memory are transformed to ``$memrd`` cells and all -write accesses to ``$memwr`` cells by the language frontend. These cells consist +All read accesses to the memory are transformed to `$memrd` cells and all +write accesses to `$memwr` cells by the language frontend. These cells consist of independent read- and write-ports to the memory. Memory initialization is -transformed to ``$meminit`` cells by the language frontend. The ``\MEMID`` +transformed to `$meminit` cells by the language frontend. The ``\MEMID`` parameter on these cells is used to link them together and to the ``RTLIL::Memory`` object they belong to. The rationale behind using separate cells for the individual ports versus creating a large multiport memory cell right in the language frontend is that -the separate ``$memrd`` and ``$memwr`` cells can be consolidated using resource +the separate `$memrd` and `$memwr` cells can be consolidated using resource sharing. As resource sharing is a non-trivial optimization problem where different synthesis tasks can have different requirements it lends itself to do the optimisation in separate passes and merge the ``RTLIL::Memory`` objects and -``$memrd`` and ``$memwr`` cells to multiport memory blocks after resource +`$memrd` and `$memwr` cells to multiport memory blocks after resource sharing is completed. The memory pass performs this conversion and can (depending on the options passed to it) transform the memories directly to d-type flip-flops and address -logic or yield multiport memory blocks (represented using ``$mem`` cells). +logic or yield multiport memory blocks (represented using `$mem` cells). See :ref:`sec:memcells` for details about the memory cell types. diff --git a/docs/source/yosys_internals/techmap.rst b/docs/source/yosys_internals/techmap.rst index 00fce26bd..e5d6972ee 100644 --- a/docs/source/yosys_internals/techmap.rst +++ b/docs/source/yosys_internals/techmap.rst @@ -3,7 +3,7 @@ Techmap by example As a quick recap, the :cmd:ref:`techmap` command replaces cells in the design with implementations given as Verilog code (called "map files"). It can replace -Yosys' internal cell types (such as ``$or``) as well as user-defined cell types. +Yosys' internal cell types (such as `$or`) as well as user-defined cell types. - Verilog parameters are used extensively to customize the internal cell types. - Additional special parameters are used by techmap to communicate meta-data to