riscv
/
yosys
mirror of https://github.com/YosysHQ/yosys.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

Docs: Update internal cells to autoref

This commit is contained in:
Krystine Sherwin 2024-05-03 13:14:25 +12:00
parent c0f9828b3c
commit e4ec3717bc
No known key found for this signature in database
12 changed files with 183 additions and 179 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

64
docs/source/getting_started/example_synth.rst
View File

@ -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 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 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 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 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 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` ``addr_gen`` module after :yoscrypt:`proc -noopt`
There are now a few new cells from our ``always @``, which have been There are now a few new cells from our ``always @``, which have been
highlighted. The ``if`` statements are now modeled with ``$mux`` cells, while 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 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 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`. 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` ``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 changed to ``8'11111111``. Constant values are presented in the format
``<bit_width>'<bits>``, with 32-bit values instead using the decimal number. ``<bit_width>'<bits>``, with 32-bit values instead using the decimal number.
This indicates that the constant input has been reduced from 32-bit wide to 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 :end-before: yosys> proc
:caption: reloading :file:`fifo.v` and running :yoscrypt:`hierarchy -check -top fifo` :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 because when we ran ``yosys fifo.v``, the first command Yosys called was
:yoscrypt:`read_verilog -defer fifo.v`. The ``-defer`` option there tells :yoscrypt:`read_verilog -defer fifo.v`. The ``-defer`` option there tells
:cmd:ref:`read_verilog` only read the abstract syntax tree and defer actual :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 instance of the ``addr_gen`` module with the ``MAX_DATA`` parameter set to the
given value. 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 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 ``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. signal undefined; shown with the ``1'x`` inputs.
.. seealso:: Advanced usage docs for .. 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 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 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` 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 merging happened during the call to :cmd:ref:`clean` which we can see in the
:ref:`flat_clean`. :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 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. :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`` 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 options is able to fold one of the `$mux` cells into the `$adff` to form an
``$adffe`` cell; highlighted below: `$adffe` cell; highlighted below:
.. literalinclude:: /code_examples/fifo/fifo.out .. literalinclude:: /code_examples/fifo/fifo.out
:language: doscon :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 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``. 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. 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` .. 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` ``rdata`` output after :cmd:ref:`memory_dff`
As the title suggests, :cmd:ref:`memory_dff` has merged the output ``$dff`` into 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 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 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 memory read with appropriate enable (``EN=1'1``) and reset (``ARST=1'0`` and
``SRST=1'0``) inputs. ``SRST=1'0``) inputs.
@ -482,12 +482,12 @@ what they do.
:name: synth_coarse3 :name: synth_coarse3
:yoscrypt:`wreduce t:$mul` performs width reduction again, this time targetting :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 +/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 ``SB_MAC16``. Any multipliers which aren't compatible with conversion to
``$__MUL16X16`` are relabelled to ``$__soft_mul`` before :cmd:ref:`chtype` ``$__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 During the mul2dsp conversion, some of the intermediate signals are marked with
the attribute ``mul2dsp``. By calling :yoscrypt:`select a:mul2dsp` we restrict 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) :caption: ``coarse`` section (part 4)
:name: synth_coarse4 :name: synth_coarse4
Where before each type of arithmetic operation had its own cell, e.g. ``$add``, 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 we now want to extract these into `$alu` and `$macc` cells which can help
identify opportunities for reusing logic. We do this by running identify opportunities for reusing logic. We do this by running
:cmd:ref:`alumacc`, which we can see produce the following changes in our :cmd:ref:`alumacc`, which we can see produce the following changes in our
example design: example design:
@ -542,7 +542,7 @@ example design:
Once these cells have been inserted, the call to :cmd:ref:`opt` can combine 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 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 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 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` ``rdata`` output after :cmd:ref:`memory_collect`
Looking at the schematic after running :cmd:ref:`memory_collect` we see that our 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 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 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`` 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` ``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 ``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 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 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. 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 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 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 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 of wires, the ``$techmap579\data.0.0.RDATA`` wire becomes more visually
complex. complex.
@ -668,10 +668,10 @@ Arithmetic
^^^^^^^^^^ ^^^^^^^^^^
Uses :cmd:ref:`techmap` to map basic arithmetic logic to hardware. This sees 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 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 replaced with single-bit `$_MUX_` and `$_DFFE_PP0P_` cells, while the
``$alu`` is replaced with primitive ``$_OR_`` and ``$_NOT_`` gates and a :cell:ref:`$alu` is replaced with primitive `$_OR_` and `$_NOT_` gates and a
``$lut`` cell. `$lut` cell.
.. literalinclude:: /cmd/synth_ice40.rst .. literalinclude:: /cmd/synth_ice40.rst
:language: yoscrypt :language: yoscrypt
@ -695,12 +695,12 @@ Flip-flops
Convert FFs to the types supported in hardware with :cmd:ref:`dfflegalize`, and 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 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 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 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 `$_MUX_` cells where one of the inputs is a constant ``1'0``, replacing it
instead with an ``$_AND_`` cell. instead with an `$_AND_` cell.
.. literalinclude:: /cmd/synth_ice40.rst .. literalinclude:: /cmd/synth_ice40.rst
:language: yoscrypt :language: yoscrypt
@ -723,7 +723,7 @@ LUTs
^^^^ ^^^^
:cmd:ref:`abc` and :cmd:ref:`techmap` are used to map LUTs; converting primitive :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 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 what the difference between these two commands are, refer to
:doc:`/using_yosys/synthesis/abc`. :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` ``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. ``SB_LUT4`` cells.
.. literalinclude:: /cmd/synth_ice40.rst .. literalinclude:: /cmd/synth_ice40.rst

15
docs/source/getting_started/scripting_intro.rst
View File

@ -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 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 cells, regardless of their type. The active selection is now shown as
``[addr_gen]*``, indicating some sub-selection of the ``addr_gen`` module. This ``[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. :ref:`addr_gen_hier` image.
.. _select_new_cells: .. _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. 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 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 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/` know we only have the one module in our design, we can even skip the
part. Looking further down :ref:`the fifo.ys code <fifo-ys>` we can see this ``addr_gen/`` part. Looking further down :ref:`the fifo.ys code <fifo-ys>` we
with :yoscrypt:`select -set new_cells t:$mux t:*dff`. We can also see in that can see this with :yoscrypt:`select -set new_cells t:$mux t:*dff`. We can also
command that selections don't have to be limited to a single statement. 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 Many commands also support an optional ``[selection]`` argument which can be
used to override the currently selected objects. We could, for example, call 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 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 string. Remember when we :ref:`assigned a name to a
selection<select_new_cells>` and called it ``new_cells``? We saw in the selection<select_new_cells>` and called it ``new_cells``? We saw in the
:yoscrypt:`select -list` output that it contained two cells, an ``$add`` and an :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: `$eq`. We can call :cmd:ref:`show` on that selection just as easily:
.. figure:: /_images/code_examples/fifo/new_cells_show.* .. figure:: /_images/code_examples/fifo/new_cells_show.*
:class: width-helper invert-helper :class: width-helper invert-helper

4
docs/source/using_yosys/more_scripting/interactive_investigation.rst
View File

@ -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 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 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 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. ``if``-statement is yet still hidden within the process.
The :cmd:ref:`proc` command transforms the process from the first diagram into a 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 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 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 Break-out boxes for signal vectors
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

12
docs/source/using_yosys/more_scripting/selections.rst
View File

@ -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 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 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 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: with the ``foo`` attribute set:
.. literalinclude:: /code_examples/selections/foobaraddsub.v .. 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 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 ``%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 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:: .. code-block::
:caption: Output for command ``select t:$add a:foo %i -list`` on :numref:`foobaraddsub` :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` Output of :yoscrypt:`show prod %ci %ci %ci` on :numref:`sumprod`
Notice the subtle difference between :yoscrypt:`show prod %ci` and 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, 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 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 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` 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 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 ``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 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 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 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 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]`: type with :yoscrypt:`show y %ci5:-$mux[S]`:
.. figure:: /_images/code_examples/selections/memdemo_03.* .. 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`` 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 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``: ignoring any ports named ``CLK`` or ``S``:
.. TODO:: pending discussion on whether rule ordering is a bug or a feature .. TODO:: pending discussion on whether rule ordering is a bug or a feature

4
docs/source/using_yosys/synthesis/cell_libs.rst
View File

@ -98,8 +98,8 @@ our internal cell library will be mapped to:
:name: mycells-lib :name: mycells-lib
:caption: :file:`mycells.lib` :caption: :file:`mycells.lib`
Recall that the Yosys built-in logic gate types are ``$_NOT_``, ``$_AND_``, Recall that the Yosys built-in logic gate types are `$_NOT_`, `$_AND_`,
``$_OR_``, ``$_XOR_``, and ``$_MUX_`` with an assortment of dff memory types. `$_OR_`, `$_XOR_`, and `$_MUX_` with an assortment of dff memory types.
:ref:`mycells-lib` defines our target cells as ``BUF``, ``NOT``, ``NAND``, :ref:`mycells-lib` defines our target cells as ``BUF``, ``NOT``, ``NAND``,
``NOR``, and ``DFF``. Mapping between these is performed with the commands ``NOR``, and ``DFF``. Mapping between these is performed with the commands
:cmd:ref:`dfflibmap` and :cmd:ref:`abc` as follows: :cmd:ref:`dfflibmap` and :cmd:ref:`abc` as follows:

18
docs/source/using_yosys/synthesis/fsm.rst
View File

@ -24,12 +24,12 @@ following description:
- Does not already have the ``\fsm_encoding`` attribute. - Does not already have the ``\fsm_encoding`` attribute.
- Is not an output of the containing module. - Is not an output of the containing module.
- Is driven by single ``$dff`` or ``$adff`` cell. - Is driven by single `$dff` or `$adff` cell.
- The ``\D``-Input of this ``$dff`` or ``$adff`` cell is driven by a - 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 multiplexer tree that only has constants or the old state value on its
leaves. leaves.
- The state value is only used in the said multiplexer tree or by simple - 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). cells).
This heuristic has proven to work very well. It is possible to overwrite it by 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 The state registers (and asynchronous reset state, if applicable) is simply
determined by identifying the driver for the state signal. 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 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. not the state signal itself is found.
The list of control outputs is initialized with the bits from the state signal. 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 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 to the module. This new cell is connected to the control signals and the old
drivers for the control outputs are disconnected. drivers for the control outputs are disconnected.
FSM optimization 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 including state recoding). The following optimizations are performed (in this
order): 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 ``\unused_bits`` (that is usually set by the :cmd:ref:`opt_clean` pass) is
used to determine which control outputs are unused. used to determine which control outputs are unused.

10
docs/source/using_yosys/synthesis/memory.rst
View File

@ -75,7 +75,7 @@ For example:
techmap -map my_memory_map.v techmap -map my_memory_map.v
memory_map 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 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 example above). Where necessary, emulation logic is added to ensure functional
equivalence before and after this conversion. :yoscrypt:`techmap -map 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: This process can be overridden by attaching a ram_style attribute to the memory:
- `(* ram_style = "logic" *)` selects FF RAM - ``(* ram_style = "logic" *)`` selects FF RAM
- `(* ram_style = "distributed" *)` selects LUT RAM - ``(* ram_style = "distributed" *)`` selects LUT RAM
- `(* ram_style = "block" *)` selects block RAM - ``(* ram_style = "block" *)`` selects block RAM
- `(* ram_style = "huge" *)` selects huge RAM - ``(* ram_style = "huge" *)`` selects huge RAM
It is an error if this override cannot be realized for the given target. It is an error if this override cannot be realized for the given target.

30
docs/source/using_yosys/synthesis/opt.rst
View File

@ -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. 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. 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 :name: tab:opt_expr_and
:align: center :align: center
@ -54,7 +54,7 @@ In some cases this pass can also optimize cells with some constant inputs.
========= ========= =========== ========= ========= ===========
:numref:`Table %s <tab:opt_expr_and>` shows the replacement rules used for :numref:`Table %s <tab:opt_expr_and>` 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 folding rules. Note that 'any' might include dynamic values calculated by other
parts of the circuit. The following three lines propagate undef (X) states. 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 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 will change to an undef value or a 1 and therefore the output can be set to
undef. 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. with a buffer.
Besides this basic const folding the :cmd:ref:`opt_expr` pass can replace 1-bit 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 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, 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 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 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`. :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 cells, as these cells are often used to model decision-trees and breaking these
trees can interfere with other optimizations. 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. of the cell.
The option ``-nomux`` can be used to disable resource sharing for multiplexer 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 trees to be merged, which might prevent :cmd:ref:`opt_muxtree` to identify
possible optimizations. 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 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 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`` bits to ease identification of shareable `$reduce_and` and `$reduce_or`
cells in other passes. cells in other passes.
This pass also identifies and consolidates identical inputs to multiplexer 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. cell that combines the original select bits.
Lastly this pass consolidates trees of ``$reduce_and`` cells and trees of Lastly this pass consolidates trees of `$reduce_and` cells and trees of
``$reduce_or`` cells to single large ``$reduce_and`` or ``$reduce_or`` cells. `$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 These three simple optimizations are performed in a loop until a stable result
is produced. 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: This pass identifies mutually exclusive cells of the same type that:
a. share an input signal, and 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 allowing the cell to be merged and the multiplexer to be moved from
multiplexing its output to multiplexing the non-shared input signals. 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` 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`. optimized away by :cmd:ref:`opt_expr`.
Performing DFF optimizations - :cmd:ref:`opt_dff` Performing DFF optimizations - :cmd:ref:`opt_dff`
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This pass identifies single-bit d-type flip-flops (``$_DFF_``, ``$dff``, and 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 `$adff` cells) with a constant data input and replaces them with a constant
driver. It can also merge clock enables and synchronous reset multiplexers, driver. It can also merge clock enables and synchronous reset multiplexers,
removing unused control inputs. removing unused control inputs.

4
docs/source/yosys_internals/flow/verilog_frontend.rst
View File

@ -627,7 +627,7 @@ from a behavioural model to an RTL representation is performed by the
asynchronous resets if necessary). asynchronous resets if necessary).
- | :cmd:ref:`proc_dff` - | :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` - | :cmd:ref:`proc_clean`
| A final call to :cmd:ref:`proc_clean` removes the now empty | 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 .. 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. how they are processed in the memory pass.

183
docs/source/yosys_internals/formats/cell_library.rst
View File

@ -73,15 +73,15 @@ also have the following parameters:
:verilog:`Y = !A` $logic_not :verilog:`Y = !A` $logic_not
================== ============ ================== ============
For the unary cells that output a logical value (``$reduce_and``, For the unary cells that output a logical value (`$reduce_and`,
``$reduce_or``, ``$reduce_xor``, ``$reduce_xnor``, ``$reduce_bool``, `$reduce_or`, `$reduce_xor`, `$reduce_xnor`, `$reduce_bool`,
``$logic_not``), when the ``\Y_WIDTH`` parameter is greater than 1, the output `$logic_not`), when the ``\Y_WIDTH`` parameter is greater than 1, the output
is zero-extended, and only the least significant bit varies. 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 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_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_bool` cell is generated when a bit vector is used as a condition in
an ``if``-statement or ``?:``-expression. an ``if``-statement or ``?:``-expression.
Binary operators 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 :verilog:`Y = A ** B` $pow ``N/A`` $modfloor
======================= ============= ======================= ========= ======================= ============= ======================= =========
The ``$shl`` and ``$shr`` cells implement logical shifts, whereas the ``$sshl`` The `$shl` and `$shr` cells implement logical shifts, whereas the `$sshl`
and ``$sshr`` cells implement arithmetic shifts. The ``$shl`` and ``$sshl`` and `$sshr` cells implement arithmetic shifts. The `$shl` and `$sshl`
cells implement the same operation. All four of these cells interpret the second cells implement the same operation. All four of these cells interpret the second
operand as unsigned, and require ``\B_SIGNED`` to be zero. operand as unsigned, and require ``\B_SIGNED`` to be zero.
Two additional shift operator cells are available that do not directly Two additional shift operator cells are available that do not directly
correspond to any operator in Verilog, ``$shift`` and ``$shiftx``. The correspond to any operator in Verilog, `$shift` and `$shiftx`. The
``$shift`` cell performs a right logical shift if the second operand is positive `$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 (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 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 positions are filled with undef (x) bits, and corresponds to the Verilog indexed
part-select expression. part-select expression.
For the binary cells that output a logical value (``$logic_and``, ``$logic_or``, For the binary cells that output a logical value (`$logic_and`, `$logic_or`,
``$eqx``, ``$nex``, ``$lt``, ``$le``, ``$eq``, ``$ne``, ``$ge``, ``$gt``), when `$eqx`, `$nex`, `$lt`, `$le`, `$eq`, `$ne`, `$ge`, `$gt`), when
the ``\Y_WIDTH`` parameter is greater than 1, the output is zero-extended, and the ``\Y_WIDTH`` parameter is greater than 1, the output is zero-extended, and
only the least significant bit varies. only the least significant bit varies.
Division and modulo cells are available in two rounding modes. The original Division and modulo cells are available in two rounding modes. The original
``$div`` and ``$mod`` cells are based on truncating division, and correspond to `$div` and `$mod` cells are based on truncating division, and correspond to
the semantics of the verilog ``/`` and ``%`` operators. The ``$divfloor`` and the semantics of the verilog ``/`` and ``%`` operators. The `$divfloor` and
``$modfloor`` cells represent flooring division and flooring modulo, the latter `$modfloor` cells represent flooring division and flooring modulo, the latter
of which is also known as "remainder" in several languages. See of which is also known as "remainder" in several languages. See
:numref:`tab:CellLib_divmod` for a side-by-side comparison between the different :numref:`tab:CellLib_divmod` for a side-by-side comparison between the different
semantics. 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 Multiplexers are also generated by the proc pass to map the decision trees from
RTLIL::Process objects to logic. 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``, ``\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 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 ``\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`. 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 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 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 ``\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 "parallel cases" (defined by using the ``parallel_case`` attribute or detected
by an optimization). 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 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 ``\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, 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 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 Behavioural code with cascaded if-then-else- and case-statements usually results
in trees of multiplexer cells. Many passes (from various optimizations to FSM in trees of multiplexer cells. Many passes (from various optimizations to FSM
extraction) heavily depend on these multiplexer trees to understand dependencies extraction) heavily depend on these multiplexer trees to understand dependencies
between signals. Therefore optimizations should not break these multiplexer between signals. Therefore optimizations should not break these multiplexer
trees (e.g. by replacing a multiplexer between a calculated signal and a 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 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 ``\SET`` and ``\CLR`` and an output port ``\Q``. They have the following
parameters: parameters:
@ -232,12 +232,12 @@ parameters:
``1'b1`` and active-low if this parameter is ``1'b0``. ``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 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. 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 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`` ``\WIDTH``
The width of input ``\D`` and output ``\Q``. 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 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``. ``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 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 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 also have a single-bit ``\ARST`` input port for the reset pin and the following
additional two parameters: additional two parameters:
@ -261,8 +261,8 @@ additional two parameters:
Usually these cells are generated by the :cmd:ref:`proc` pass using the Usually these cells are generated by the :cmd:ref:`proc` pass using the
information in the designs RTLIL::Process objects. information in the designs RTLIL::Process objects.
D-type flip-flops with synchronous reset are represented by ``$sdff`` cells. As 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 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 also have a single-bit ``\SRST`` input port for the reset pin and the following
additional two parameters: additional two parameters:
@ -273,11 +273,11 @@ additional two parameters:
``\SRST_VALUE`` ``\SRST_VALUE``
The state of ``\Q`` will be set to this value when the reset is active. 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. value is constant.
D-type flip-flops with asynchronous load are represented by ``$aldff`` cells. As 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 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 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 ``\AD`` input port with the same width as data for the async load data, and the
following additional parameter: following additional parameter:
@ -286,15 +286,15 @@ following additional parameter:
The asynchronous load is active-high if this parameter has the value The asynchronous load is active-high if this parameter has the value
``1'b1`` and active-low if this parameter is ``1'b0``. ``1'b1`` and active-low if this parameter is ``1'b0``.
D-type flip-flops with asynchronous set and reset are represented by ``$dffsr`` 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 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 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``, D-type flip-flops with enable are represented by `$dffe`, `$adffe`,
``$aldffe``, ``$dffsre``, ``$sdffe``, and ``$sdffce`` cells, which are enhanced `$aldffe`, `$dffsre`, `$sdffe`, and `$sdffce` cells, which are enhanced
variants of ``$dff``, ``$adff``, ``$aldff``, ``$dffsr``, ``$sdff`` (with reset variants of `$dff`, `$adff`, `$aldff`, `$dffsr`, `$sdff` (with reset
over enable) and ``$sdff`` (with enable over reset) cells, respectively. They 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 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 have a single-bit ``\EN`` input port for the enable pin and the following
parameter: parameter:
@ -303,9 +303,9 @@ parameter:
The enable input is active-high if this parameter has the value ``1'b1`` The enable input is active-high if this parameter has the value ``1'b1``
and active-low if this parameter is ``1'b0``. 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 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`` ``\WIDTH``
The width of input ``\D`` and output ``\Q``. 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. The latch is transparent when the ``\EN`` input is active.
D-type latches with reset are represented by ``$adlatch`` cells. In addition to 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 `$dlatch` ports and parameters, they also have a single-bit ``\ARST`` input
port for the reset pin and the following additional parameters: port for the reset pin and the following additional parameters:
``\ARST_POLARITY`` ``\ARST_POLARITY``
@ -327,9 +327,9 @@ port for the reset pin and the following additional parameters:
``\ARST_VALUE`` ``\ARST_VALUE``
The state of ``\Q`` will be set to this value when the reset is active. 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 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`` addition to `$dlatch` ports and parameters, they also have multi-bit ``\SET``
and ``\CLR`` input ports and the corresponding polarity parameters, like ``$sr`` and ``\CLR`` input ports and the corresponding polarity parameters, like `$sr`
cells. cells.
.. _sec:memcells: .. _sec:memcells:
@ -337,20 +337,20 @@ cells.
Memories Memories
~~~~~~~~ ~~~~~~~~
Memories are either represented using ``RTLIL::Memory`` objects, ``$memrd_v2``, Memories are either represented using ``RTLIL::Memory`` objects, `$memrd_v2`,
``$memwr_v2``, and ``$meminit_v2`` cells, or by ``$mem_v2`` cells alone. `$memwr_v2`, and `$meminit_v2` cells, or by `$mem_v2` cells alone.
In the first alternative the ``RTLIL::Memory`` objects hold the general metadata 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 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 individual cells for read and write ports has the advantage that they can be
consolidated using resource sharing passes. In some cases this drastically consolidated using resource sharing passes. In some cases this drastically
reduces the number of required ports on the memory cell. In this alternative, 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 delaying constant folding for initialization addresses and data until after the
frontend finishes. 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 address input ``\ADDR``, a data output ``\DATA``, an asynchronous reset input
``\ARST``, and a synchronous reset input ``\SRST``. They also have the following ``\ARST``, and a synchronous reset input ``\SRST``. They also have the following
parameters: parameters:
@ -411,7 +411,7 @@ parameters:
when ``\EN`` is true. Otherwise, ``\SRST`` is recognized regardless of when ``\EN`` is true. Otherwise, ``\SRST`` is recognized regardless of
``\EN``. ``\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 (one enable bit for each data bit), an address input ``\ADDR`` and a data input
``\DATA``. They also have the following parameters: ``\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`` ``\WIDTH``
The number of data bits (width of the ``\DATA`` output port). Like with 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. multiple of memory width, with the corresponding restriction on address.
``\CLK_ENABLE`` ``\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 undefined. Priority can only be set between two synchronous ports sharing
the same clock domain. 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 ``\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 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 to ``\WIDTH`` parameter. All three of the inputs must resolve to a constant for
@ -472,19 +472,19 @@ synthesis to succeed.
initialization conflict. initialization conflict.
The HDL frontend models a memory using ``RTLIL::Memory`` objects and The HDL frontend models a memory using ``RTLIL::Memory`` objects and
asynchronous ``$memrd_v2`` and ``$memwr_v2`` cells. The :cmd:ref:`memory` pass 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 (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 `$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 `$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 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. is left in the design.
The ``$mem_v2`` cell provides the following parameters: The `$mem_v2` cell provides the following parameters:
``\MEMID`` ``\MEMID``
The name of the original ``RTLIL::Memory`` object that became this The name of the original ``RTLIL::Memory`` object that became this
``$mem_v2`` cell. `$mem_v2` cell.
``\SIZE`` ``\SIZE``
The number of words in the memory. The number of words in the memory.
@ -519,12 +519,12 @@ The ``$mem_v2`` cell provides the following parameters:
``\RD_TRANSPARENCY_MASK`` ``\RD_TRANSPARENCY_MASK``
This parameter is ``\RD_PORTS*\WR_PORTS`` bits wide, containing a This parameter is ``\RD_PORTS*\WR_PORTS`` bits wide, containing a
concatenation of all ``\TRANSPARENCY_MASK`` values of the original concatenation of all ``\TRANSPARENCY_MASK`` values of the original
``$memrd_v2`` cells. `$memrd_v2` cells.
``\RD_COLLISION_X_MASK`` ``\RD_COLLISION_X_MASK``
This parameter is ``\RD_PORTS*\WR_PORTS`` bits wide, containing a This parameter is ``\RD_PORTS*\WR_PORTS`` bits wide, containing a
concatenation of all ``\COLLISION_X_MASK`` values of the original concatenation of all ``\COLLISION_X_MASK`` values of the original
``$memrd_v2`` cells. `$memrd_v2` cells.
``\RD_CE_OVER_SRST`` ``\RD_CE_OVER_SRST``
This parameter is ``\RD_PORTS`` bits wide, determining relative This parameter is ``\RD_PORTS`` bits wide, determining relative
@ -560,9 +560,9 @@ The ``$mem_v2`` cell provides the following parameters:
``\WR_PRIORITY_MASK`` ``\WR_PRIORITY_MASK``
This parameter is ``\WR_PORTS*\WR_PORTS`` bits wide, containing a This parameter is ``\WR_PORTS*\WR_PORTS`` bits wide, containing a
concatenation of all ``\PRIORITY_MASK`` values of the original 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`` ``\RD_CLK``
This input is ``\RD_PORTS`` bits wide, containing all clock signals for 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. signals for the write ports.
The :cmd:ref:`memory_collect` pass can be used to convert discrete The :cmd:ref:`memory_collect` pass can be used to convert discrete
``$memrd_v2``, ``$memwr_v2``, and ``$meminit_v2`` cells belonging to the same `$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 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 performs the inverse operation. The :cmd:ref:`memory_dff` pass can combine
asynchronous memory ports that are fed by or feeding registers into synchronous 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 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. `$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 The :cmd:ref:`memory_map` pass can be used to implement `$mem_v2` cells as
basic logic: word-wide DFFs and address decoders. basic logic: word-wide DFFs and address decoders.
Finite state machines Finite state machines
~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~
Add a brief description of the ``$fsm`` cell type. Add a brief description of the `$fsm` cell type.
Coarse arithmetics 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:: .. code-block::
@ -708,21 +708,21 @@ in the ``\TABLE`` values.
Specify rules Specify rules
~~~~~~~~~~~~~ ~~~~~~~~~~~~~
Add information about ``$specify2``, ``$specify3``, and ``$specrule`` cells. Add information about `$specify2`, `$specify3`, and `$specrule` cells.
Formal verification cells Formal verification cells
~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~
Add information about ``$check``, ``$assert``, ``$assume``, ``$live``, ``$fair``, Add information about `$check`, `$assert`, `$assume`, `$live`, `$fair`,
``$cover``, ``$equiv``, ``$initstate``, ``$anyconst``, ``$anyseq``, `$cover`, `$equiv`, `$initstate`, `$anyconst`, `$anyseq`,
``$anyinit``, ``$allconst``, ``$allseq`` cells. `$anyinit`, `$allconst`, `$allseq` cells.
Add information about ``$ff`` and ``$_FF_`` cells. Add information about `$ff` and `$_FF_` cells.
Debugging 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 translatable to) the ``$display`` and ``$write`` family of tasks in Verilog. It
has the following parameters: has the following parameters:
@ -746,13 +746,14 @@ If ``\TRG_ENABLE`` is true, the following parameters also apply:
negative-edge triggered. negative-edge triggered.
``\PRIORITY`` ``\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. execute in descending priority order.
Ports: Ports:
``\TRG`` ``\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 If the width of this port is zero and ``\TRG_ENABLE`` is true, the cell is
triggered during initial evaluation (time zero) only. triggered during initial evaluation (time zero) only.
@ -1040,14 +1041,14 @@ Tables :numref:`%s <tab:CellLib_gates>`, :numref:`%s <tab:CellLib_gates_dffe>`,
:numref:`%s <tab:CellLib_gates_dffsr>`, :numref:`%s <tab:CellLib_gates_dffsre>`, :numref:`%s <tab:CellLib_gates_dffsr>`, :numref:`%s <tab:CellLib_gates_dffsre>`,
:numref:`%s <tab:CellLib_gates_adlatch>`, :numref:`%s :numref:`%s <tab:CellLib_gates_adlatch>`, :numref:`%s
<tab:CellLib_gates_dlatchsr>` and :numref:`%s <tab:CellLib_gates_sr>` list all <tab:CellLib_gates_dlatchsr>` and :numref:`%s <tab:CellLib_gates_sr>` list all
cell types used for gate level logic. The cell types ``$_BUF_``, ``$_NOT_``, cell types used for gate level logic. The cell types `$_BUF_`, `$_NOT_`,
``$_AND_``, ``$_NAND_``, ``$_ANDNOT_``, ``$_OR_``, ``$_NOR_``, ``$_ORNOT_``, `$_AND_`, `$_NAND_`, `$_ANDNOT_`, `$_OR_`, `$_NOR_`, `$_ORNOT_`,
``$_XOR_``, ``$_XNOR_``, ``$_AOI3_``, ``$_OAI3_``, ``$_AOI4_``, ``$_OAI4_``, `$_XOR_`, `$_XNOR_`, `$_AOI3_`, `$_OAI3_`, `$_AOI4_`, `$_OAI4_`,
``$_MUX_``, ``$_MUX4_``, ``$_MUX8_``, ``$_MUX16_`` and ``$_NMUX_`` are used to `$_MUX_`, `$_MUX4_`, `$_MUX8_`, `$_MUX16_` and `$_NMUX_` are used to
model combinatorial logic. The cell type ``$_TBUF_`` is used to model tristate model combinatorial logic. The cell type `$_TBUF_` is used to model tristate
logic. 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: muxes, and correspond to the following Verilog code:
.. code-block:: verilog .. code-block:: verilog
@ -1071,7 +1072,7 @@ muxes, and correspond to the following Verilog code:
T ? (S ? D : C) : T ? (S ? D : C) :
(S ? B : A); (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 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 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) else if (E == EN_LVL)
Q <= D; 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 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 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 The combinatorial logic cells can be mapped to physical cells from a Liberty
file via ABC using the abc pass. 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. .. todo:: Add information about ``$demux`` cell.

16
docs/source/yosys_internals/formats/rtlil_rep.rst
View File

@ -79,7 +79,7 @@ This has three advantages:
example, :cmd:ref:`opt_clean` tries to preserve signals with a user-provided 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 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 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. names.
- Third, the delicate job of finding suitable auto-generated public visible - Third, the delicate job of finding suitable auto-generated public visible
@ -366,7 +366,7 @@ multiplexer for the enable signal:
end end
Different combinations of passes may yield different results. Note that 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. cell types from the target cell library.
Some passes refuse to operate on modules that still contain ``RTLIL::Process`` 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 width of an addressable word
- The size of the memory in number of words - The size of the memory in number of words
All read accesses to the memory are transformed to ``$memrd`` cells and all 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 write accesses to `$memwr` cells by the language frontend. These cells consist
of independent read- and write-ports to the memory. Memory initialization is 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 parameter on these cells is used to link them together and to the
``RTLIL::Memory`` object they belong to. ``RTLIL::Memory`` object they belong to.
The rationale behind using separate cells for the individual ports versus The rationale behind using separate cells for the individual ports versus
creating a large multiport memory cell right in the language frontend is that 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 sharing. As resource sharing is a non-trivial optimization problem where
different synthesis tasks can have different requirements it lends itself to do different synthesis tasks can have different requirements it lends itself to do
the optimisation in separate passes and merge the ``RTLIL::Memory`` objects and 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. sharing is completed.
The memory pass performs this conversion and can (depending on the options 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 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. See :ref:`sec:memcells` for details about the memory cell types.

2
docs/source/yosys_internals/techmap.rst
View File

@ -3,7 +3,7 @@ Techmap by example
As a quick recap, the :cmd:ref:`techmap` command replaces cells in the design 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 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. - Verilog parameters are used extensively to customize the internal cell types.
- Additional special parameters are used by techmap to communicate meta-data to - Additional special parameters are used by techmap to communicate meta-data to