mirrors/yosys
3
0
Fork 0
mirror of https://github.com/YosysHQ/yosys synced 2025-06-07 06:33:24 +00:00
Code Activity

Converting a number of inline commands to refs

Browse source 
Also reflowing text for line width.
Maybe look into supporting commands with options?
This commit is contained in:
Krystine Sherwin 2023-08-08 12:45:18 +12:00
parent f8333e52f7
commit 685da6a2e5
No known key found for this signature in database
17 changed files with 398 additions and 384 deletions
Download patch file Download diff file Expand all files Collapse all files

4
docs/source/appendix/APPNOTE_010_Verilog_to_BLIF.rst
View file

@ -235,8 +235,8 @@ signal is connected throughout the whole design hierarchy.
endmodule endmodule
In line 18 the ``proc`` command is called. But in this script the signal name In line 18 the :cmd:ref:`proc` command is called. But in this script the signal
globrst is passed to the command as a global reset signal for resetting the name globrst is passed to the command as a global reset signal for resetting the
registers to their assigned initial values. registers to their assigned initial values.
Finally in line 19 the techmap command is used to replace all instances of Finally in line 19 the techmap command is used to replace all instances of

293
docs/source/appendix/APPNOTE_011_Design_Investigation.rst
View file

@ -6,9 +6,9 @@ Installation and prerequisites
============================== ==============================
This Application Note is based on the `Yosys GIT`_ `Rev. 2b90ba1`_ from This Application Note is based on the `Yosys GIT`_ `Rev. 2b90ba1`_ from
2013-12-08. The README file covers how to install Yosys. The ``show`` command 2013-12-08. The README file covers how to install Yosys. The :cmd:ref:`show`
requires a working installation of `GraphViz`_ and `xdot` for generating the command requires a working installation of `GraphViz`_ and `xdot` for generating
actual circuit diagrams. the actual circuit diagrams.
.. _Yosys GIT: https://github.com/YosysHQ/yosys .. _Yosys GIT: https://github.com/YosysHQ/yosys
@ -23,8 +23,8 @@ Overview
This application note is structured as follows: This application note is structured as follows:
:ref:`intro_show` introduces the ``show`` command and explains the symbols used :ref:`intro_show` introduces the :cmd:ref:`show` command and explains the
in the circuit diagrams generated by it. symbols used in the circuit diagrams generated by it.
:ref:`navigate` introduces additional commands used to navigate in the design, :ref:`navigate` introduces additional commands used to navigate in the design,
select portions of the design, and print additional information on the elements select portions of the design, and print additional information on the elements
@ -41,7 +41,7 @@ Introduction to the show command
================================ ================================
.. code-block:: console .. code-block:: console
:caption: Yosys script with ``show`` commands and example design :caption: Yosys script with :cmd:ref:`show` commands and example design
:name: example_src :name: example_src
$ cat example.ys $ cat example.ys
@ -64,24 +64,24 @@ Introduction to the show command
:class: width-helper :class: width-helper
:name: example_out :name: example_out
Output of the three ``show`` commands from :numref:`example_src` Output of the three :cmd:ref:`show` commands from :numref:`example_src`
The ``show`` command generates a circuit diagram for the design in its current The :cmd:ref:`show` command generates a circuit diagram for the design in its
state. Various options can be used to change the appearance of the circuit current state. Various options can be used to change the appearance of the
diagram, set the name and format for the output file, and so forth. When called circuit diagram, set the name and format for the output file, and so forth. When
without any special options, it saves the circuit diagram in a temporary file called without any special options, it saves the circuit diagram in a temporary
and launches ``xdot`` to display the diagram. Subsequent calls to show re-use the file and launches ``xdot`` to display the diagram. Subsequent calls to show
``xdot`` instance (if still running). re-use the ``xdot`` instance (if still running).
A simple circuit A simple circuit
---------------- ----------------
:numref:`example_src` shows a simple synthesis script and a Verilog file that :numref:`example_src` shows a simple synthesis script and a Verilog file that
demonstrate the usage of show in a simple setting. Note that ``show`` is called with demonstrate the usage of show in a simple setting. Note that :cmd:ref:`show` is
the ``-pause`` option, that halts execution of the Yosys script until the user called with the :cmd:ref:`-pause` option, that halts execution of the Yosys
presses the Enter key. The ``show -pause`` command also allows the user to enter script until the user presses the Enter key. The ``show -pause`` command also
an interactive shell to further investigate the circuit before continuing allows the user to enter an interactive shell to further investigate the circuit
synthesis. before continuing synthesis.
So this script, when executed, will show the design after each of the three So this script, when executed, will show the design after each of the three
synthesis commands. The generated circuit diagrams are shown in synthesis commands. The generated circuit diagrams are shown in
@ -111,28 +111,28 @@ original ``always``-block in the 2nd 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 ``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
multiplexer and a d-type flip-flip, which brings us to the 2nd diagram. multiplexer and a d-type flip-flip, which brings us to the 2nd diagram.
The Rhombus shape to the right is a dangling wire. (Wire nodes are only shown if The Rhombus shape to the right is a dangling wire. (Wire nodes are only shown if
they are dangling or have "public" names, for example names assigned from the they are dangling or have "public" names, for example names assigned from the
Verilog input.) Also note that the design now contains two instances of a Verilog input.) Also note that the design now contains two instances of a
``BUF``-node. This are artefacts left behind by the ``proc``-command. It is ``BUF``-node. This are artefacts left behind by the :cmd:ref:`proc` command. It
quite usual to see such artefacts after calling commands that perform changes in is quite usual to see such artefacts after calling commands that perform changes
the design, as most commands only care about doing the transformation in the in the design, as most commands only care about doing the transformation in the
least complicated way, not about cleaning up after them. The next call to least complicated way, not about cleaning up after them. The next call to
``clean`` (or ``opt``, which includes ``clean`` as one of its operations) will :cmd:ref:`clean` (or :cmd:ref:`proc`, which includes :cmd:ref:`clean` as one of
clean up this artefacts. This operation is so common in Yosys scripts that it its operations) will clean up this artefacts. This operation is so common in
can simply be abbreviated with the ``;;`` token, which doubles as separator for Yosys scripts that it can simply be abbreviated with the ``;;`` token, which
commands. Unless one wants to specifically analyze this artefacts left behind doubles as separator for commands. Unless one wants to specifically analyze this
some operations, it is therefore recommended to always call ``clean`` before artefacts left behind some operations, it is therefore recommended to always
calling ``show``. call :cmd:ref:`clean` before calling :cmd:ref:`show`.
In this script we directly call ``opt`` as next step, which finally leads us to In this script we directly call :cmd:ref:`proc` as next step, which finally
the 3rd diagram in :numref:`example_out`. Here we see that the ``opt`` command leads us to the 3rd diagram in :numref:`example_out`. Here we see that the
not only has removed the artifacts left behind by ``proc``, but also determined :cmd:ref:`proc` command not only has removed the artifacts left behind by
correctly that it can remove the first ``$mux`` cell without changing the :cmd:ref:`proc`, but also determined correctly that it can remove the first
behavior of the circuit. ``$mux`` cell without changing the behavior of the circuit.
.. figure:: ../../images/011/splice.* .. figure:: ../../images/011/splice.*
:class: width-helper :class: width-helper
@ -148,7 +148,7 @@ behavior of the circuit.
:class: width-helper :class: width-helper
:name: splitnets_libfile :name: splitnets_libfile
Effects of ``splitnets`` command and of providing a cell library. (The Effects of :cmd:ref:`splitnets` command and of providing a cell library. (The
circuit is a half-adder built from simple CMOS gates.) circuit is a half-adder built from simple CMOS gates.)
Break-out boxes for signal vectors Break-out boxes for signal vectors
@ -158,8 +158,8 @@ As has been indicated by the last example, Yosys is can manage signal vectors
(aka. multi-bit wires or buses) as native objects. This provides great (aka. multi-bit wires or buses) as native objects. This provides great
advantages when analyzing circuits that operate on wide integers. But it also advantages when analyzing circuits that operate on wide integers. But it also
introduces some additional complexity when the individual bits of of a signal introduces some additional complexity when the individual bits of of a signal
vector are accessed. The example ``show`` in :numref:`splice_src` demonstrates vector are accessed. The example :cmd:ref:`show` in :numref:`splice_src`
how such circuits are visualized by the ``show`` command. demonstrates how such circuits are visualized by the :cmd:ref:`show` command.
The key elements in understanding this circuit diagram are of course the boxes The key elements in understanding this circuit diagram are of course the boxes
with round corners and rows labeled ``<MSB_LEFT>:<LSB_LEFT> - with round corners and rows labeled ``<MSB_LEFT>:<LSB_LEFT> -
@ -191,11 +191,11 @@ bits, resulting in an unnecessary complex diagram.
For the 2nd diagram Yosys has been given a description of the cell library as For the 2nd diagram Yosys has been given a description of the cell library as
Verilog file containing blackbox modules. There are two ways to load cell Verilog file containing blackbox modules. There are two ways to load cell
descriptions into Yosys: First the Verilog file for the cell library can be descriptions into Yosys: First the Verilog file for the cell library can be
passed directly to the ``show`` command using the ``-lib <filename>`` option. passed directly to the :cmd:ref:`show` command using the ``-lib <filename>``
Secondly it is possible to load cell libraries into the design with the option. Secondly it is possible to load cell libraries into the design with the
``read_verilog -lib <filename>`` command. The 2nd method has the great advantage ``read_verilog -lib <filename>`` command. The 2nd method has the great advantage
that the library only needs to be loaded once and can then be used in all that the library only needs to be loaded once and can then be used in all
subsequent calls to the ``show`` command. subsequent calls to the :cmd:ref:`show` command.
In addition to that, the 2nd diagram was generated after ``splitnet -ports`` was In addition to that, the 2nd diagram was generated after ``splitnet -ports`` was
run on the design. This command splits all signal vectors into individual signal run on the design. This command splits all signal vectors into individual signal
@ -206,21 +206,21 @@ command only operates on interior signals.
Miscellaneous notes Miscellaneous notes
------------------- -------------------
Per default the ``show`` command outputs a temporary dot file and launches Per default the :cmd:ref:`show` command outputs a temporary dot file and
``xdot`` to display it. The options ``-format``, ``-viewer`` and ``-prefix`` can launches ``xdot`` to display it. The options ``-format``, ``-viewer`` and
be used to change format, viewer and filename prefix. Note that the ``pdf`` and ``-prefix`` can be used to change format, viewer and filename prefix. Note that
``ps`` format are the only formats that support plotting multiple modules in one the ``pdf`` and ``ps`` format are the only formats that support plotting
run. multiple modules in one run.
In densely connected circuits it is sometimes hard to keep track of the In densely connected circuits it is sometimes hard to keep track of the
individual signal wires. For this cases it can be useful to call ``show`` with individual signal wires. For this cases it can be useful to call :cmd:ref:`show`
the ``-colors <integer>`` argument, which randomly assigns colors to the nets. with the ``-colors <integer>`` argument, which randomly assigns colors to the
The integer (> 0) is used as seed value for the random color assignments. nets. The integer (> 0) is used as seed value for the random color assignments.
Sometimes it is necessary it try some values to find an assignment of colors Sometimes it is necessary it try some values to find an assignment of colors
that looks good. that looks good.
The command ``help show`` prints a complete listing of all options supported by The command ``help show`` prints a complete listing of all options supported by
the ``show`` command. the :cmd:ref:`show` command.
.. _navigate: .. _navigate:
@ -232,13 +232,13 @@ only helps in simple cases. For complex modules the generated circuit
diagrams are just stupidly big and are no help at all. In such cases one diagrams are just stupidly big and are no help at all. In such cases one
first has to select the relevant portions of the circuit. first has to select the relevant portions of the circuit.
In addition to *what* to display one also needs to carefully decide *when* In addition to *what* to display one also needs to carefully decide *when* to
to display it, with respect to the synthesis flow. In general it is a display it, with respect to the synthesis flow. In general it is a good idea to
good idea to troubleshoot a circuit in the earliest state in which a troubleshoot a circuit in the earliest state in which a problem can be
problem can be reproduced. So if, for example, the internal state before reproduced. So if, for example, the internal state before calling the
calling the ``techmap`` command already fails to verify, it is better to :cmd:ref:`techmap` command already fails to verify, it is better to troubleshoot
troubleshoot the coarse-grain version of the circuit before ``techmap`` than the coarse-grain version of the circuit before :cmd:ref:`techmap` than the
the gate-level circuit after ``techmap``. gate-level circuit after :cmd:ref:`techmap`.
.. Note:: It is generally recommended to verify the internal state of a .. Note:: It is generally recommended to verify the internal state of a
design by writing it to a Verilog file using ``write_verilog -noexpr`` design by writing it to a Verilog file using ``write_verilog -noexpr``
@ -249,7 +249,7 @@ Interactive navigation
---------------------- ----------------------
.. code-block:: none .. code-block:: none
:caption: Demonstration of ``ls`` and ``cd`` using ``example.v`` from :numref:`example_src` :caption: Demonstration of :cmd:ref:`ls` and :cmd:ref:`cd` using ``example.v`` from :numref:`example_src`
:name: lscd :name: lscd
yosys> ls yosys> ls
@ -293,17 +293,17 @@ Interactive navigation
end end
Once the right state within the synthesis flow for debugging the circuit has Once the right state within the synthesis flow for debugging the circuit has
been identified, it is recommended to simply add the ``shell`` command to the been identified, it is recommended to simply add the :cmd:ref:`shell` command to
matching place in the synthesis script. This command will stop the synthesis at the matching place in the synthesis script. This command will stop the synthesis
the specified moment and go to shell mode, where the user can interactively at the specified moment and go to shell mode, where the user can interactively
enter commands. enter commands.
For most cases, the shell will start with the whole design selected (i.e. when For most cases, the shell will start with the whole design selected (i.e. when
the synthesis script does not already narrow the selection). The command ``ls`` the synthesis script does not already narrow the selection). The command
can now be used to create a list of all modules. The command ``cd`` can be used :cmd:ref:`ls` can now be used to create a list of all modules. The command
to switch to one of the modules (type ``cd ..`` to switch back). Now the `ls` :cmd:ref:`cd` can be used to switch to one of the modules (type ``cd ..`` to
command lists the objects within that module. :numref:`lscd` demonstrates this switch back). Now the `ls` command lists the objects within that module.
using the design from :numref:`example_src`. :numref:`lscd` demonstrates this using the design from :numref:`example_src`.
There is a thing to note in :numref:`lscd`: We can see that the cell names from There is a thing to note in :numref:`lscd`: We can see that the cell names from
:numref:`example_out` are just abbreviations of the actual cell names, namely :numref:`example_out` are just abbreviations of the actual cell names, namely
@ -312,16 +312,16 @@ starting with a dollar sign) are rather long and contains some additional
information on the origin of the named object. But in most cases those names can information on the origin of the named object. But in most cases those names can
simply be abbreviated using the last part. simply be abbreviated using the last part.
Usually all interactive work is done with one module selected using the ``cd`` Usually all interactive work is done with one module selected using the
command. But it is also possible to work from the design-context (``cd ..``). In :cmd:ref:`cd` command. But it is also possible to work from the design-context
this case all object names must be prefixed with ``<module_name>/``. For example (``cd ..``). In this case all object names must be prefixed with
``a*/b*`` would refer to all objects whose names start with ``b`` from all ``<module_name>/``. For example ``a*/b*`` would refer to all objects whose names
modules whose names start with ``a``. start with ``b`` from all modules whose names start with ``a``.
The ``dump`` command can be used to print all information about an object. For The :cmd:ref:`dump` command can be used to print all information about an
example ``dump $2`` will print :numref:`dump2`. This can for example be useful object. For example ``dump $2`` will print :numref:`dump2`. This can for example
to determine the names of nets connected to cells, as the net-names are usually be useful to determine the names of nets connected to cells, as the net-names
suppressed in the circuit diagram if they are auto-generated. are usually suppressed in the circuit diagram if they are auto-generated.
For the remainder of this document we will assume that the commands are For the remainder of this document we will assume that the commands are
run from module-context and not design-context. run from module-context and not design-context.
@ -333,23 +333,24 @@ Working with selections
:class: width-helper :class: width-helper
:name: seladd :name: seladd
Output of ``show`` after ``select $2`` or ``select t:$add`` (see also Output of :cmd:ref:`show` after ``select $2`` or ``select t:$add`` (see also
:numref:`example_out`) :numref:`example_out`)
When a module is selected using the ``cd`` command, all commands (with a few When a module is selected using the :cmd:ref:`cd` command, all commands (with a
exceptions, such as the ``read_`` and ``write_`` commands) operate only on the few exceptions, such as the ``read_`` and ``write_`` commands) operate only on
selected module. This can also be useful for synthesis scripts where different the selected module. This can also be useful for synthesis scripts where
synthesis strategies should be applied to different modules in the design. different synthesis strategies should be applied to different modules in the
design.
But for most interactive work we want to further narrow the set of But for most interactive work we want to further narrow the set of selected
selected objects. This can be done using the ``select`` command. objects. This can be done using the :cmd:ref:`select` command.
For example, if the command ``select $2`` is executed, a subsequent ``show`` For example, if the command ``select $2`` is executed, a subsequent
command will yield the diagram shown in :numref:`seladd`. Note that the nets are :cmd:ref:`show` command will yield the diagram shown in :numref:`seladd`. Note
now displayed in ellipses. This indicates that they are not selected, but only that the nets are now displayed in ellipses. This indicates that they are not
shown because the diagram contains a cell that is connected to the net. This of selected, but only shown because the diagram contains a cell that is connected
course makes no difference for the circuit that is shown, but it can be a useful to the net. This of course makes no difference for the circuit that is shown,
information when manipulating selections. but it can be a useful information when manipulating selections.
Objects can not only be selected by their name but also by other properties. For Objects can not only be selected by their name but also by other properties. For
example ``select t:$add`` will select all cells of type ``$add``. In this case example ``select t:$add`` will select all cells of type ``$add``. In this case
@ -366,13 +367,13 @@ matching different properties.
Many commands can operate on explicit selections. For example the command ``dump Many commands can operate on explicit selections. For example the command ``dump
t:$add`` will print information on all ``$add`` cells in the active module. t:$add`` will print information on all ``$add`` cells in the active module.
Whenever a command has ``[selection]`` as last argument in its usage help, this Whenever a command has ``[selection]`` as last argument in its usage help, this
means that it will use the engine behind the ``select`` command to evaluate means that it will use the engine behind the :cmd:ref:`select` command to
additional arguments and use the resulting selection instead of the selection evaluate additional arguments and use the resulting selection instead of the
created by the last ``select`` command. selection created by the last :cmd:ref:`select` command.
Normally the ``select`` command overwrites a previous selection. The commands Normally the :cmd:ref:`select` command overwrites a previous selection. The
``select -add`` and ``select -del`` can be used to add or remove objects from commands ``select -add`` and ``select -del`` can be used to add or remove
the current selection. objects from the current selection.
The command ``select -clear`` can be used to reset the selection to the default, The command ``select -clear`` can be used to reset the selection to the default,
which is a complete selection of everything in the current module. which is a complete selection of everything in the current module.
@ -391,9 +392,9 @@ Operations on selections
Output of ``show a:sumstuff`` on :numref:`sumprod` Output of ``show a:sumstuff`` on :numref:`sumprod`
The ``select`` command is actually much more powerful than it might seem on the The :cmd:ref:`select` command is actually much more powerful than it might seem
first glimpse. When it is called with multiple arguments, each argument is on the first glimpse. When it is called with multiple arguments, each argument
evaluated and pushed separately on a stack. After all arguments have been 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 the processed it simply creates the union of all elements on the stack. So the
following command will select all ``$add`` cells and all objects with the following command will select all ``$add`` cells and all objects with the
``foo`` attribute set: ``foo`` attribute set:
@ -445,7 +446,7 @@ Selecting logic cones
:numref:`sumprod_01` shows what is called the ``input cone`` of ``sum``, i.e. :numref:`sumprod_01` shows what is called the ``input cone`` of ``sum``, i.e.
all cells and signals that are used to generate the signal ``sum``. The ``%ci`` all cells and signals that are used to generate the signal ``sum``. The ``%ci``
action can be used to select the input cones of all object in the top selection action can be used to select the input cones of all object in the top selection
in the stack maintained by the ``select`` command. in the stack maintained by the :cmd:ref:`select` command.
As the ``%x`` action, this commands broadens the selection by one "step". As the ``%x`` action, this commands broadens the selection by one "step".
But this time the operation only works against the direction of data But this time the operation only works against the direction of data
@ -484,8 +485,8 @@ appended to the ``%ci`` action.
Lets consider the design from :numref:`memdemo_src`. It serves no purpose other Lets consider the design from :numref:`memdemo_src`. It serves no purpose other
than being a non-trivial circuit for demonstrating some of the advanced Yosys than being a non-trivial circuit for demonstrating some of the advanced Yosys
features. We synthesize the circuit using ``proc; opt; memory; opt`` and change features. We synthesize the circuit using ``proc; opt; memory; opt`` and change
to the ``memdemo`` module with ``cd memdemo``. If we type ``show`` now we see to the ``memdemo`` module with ``cd memdemo``. If we type :cmd:ref:`show` now we
the diagram shown in :numref:`memdemo_00`. see the diagram shown in :numref:`memdemo_00`.
.. literalinclude:: ../APPNOTE_011_Design_Investigation/memdemo.v .. literalinclude:: ../APPNOTE_011_Design_Investigation/memdemo.v
:caption: Demo circuit for demonstrating some advanced Yosys features :caption: Demo circuit for demonstrating some advanced Yosys features
@ -580,7 +581,7 @@ Storing and recalling selections
The current selection can be stored in memory with the command ``select -set The current selection can be stored in memory with the command ``select -set
<name>``. It can later be recalled using ``select @<name>``. In fact, the <name>``. It can later be recalled using ``select @<name>``. In fact, the
``@<name>`` expression pushes the stored selection on the stack maintained by ``@<name>`` expression pushes the stored selection on the stack maintained by
the ``select`` command. So for example the :cmd:ref:`select` command. So for example
.. code-block:: yoscrypt .. code-block:: yoscrypt
@ -593,9 +594,9 @@ script that sets up relevant selections, so they can easily be recalled,
for example when Yosys needs to be re-run after a design or source code for example when Yosys needs to be re-run after a design or source code
change. change.
The ``history`` command can be used to list all recent interactive commands. The :cmd:ref:`history` command can be used to list all recent interactive
This feature can be useful for creating such a script from the commands commands. This feature can be useful for creating such a script from the
used in an interactive session. commands used in an interactive session.
.. _poke: .. _poke:
@ -610,10 +611,10 @@ of the module and wants to carefully read all the debug output created by the
commands in order to spot a problem. This kind of troubleshooting is much easier commands in order to spot a problem. This kind of troubleshooting is much easier
if the circuit under investigation is encapsulated in a separate module. if the circuit under investigation is encapsulated in a separate module.
:numref:`submod` shows how the ``submod`` command can be used to split the :numref:`submod` shows how the :cmd:ref:`submod` command can be used to split
circuit from :numref:`memdemo_src` and :numref:`memdemo_00` into its components. the circuit from :numref:`memdemo_src` and :numref:`memdemo_00` into its
The ``-name`` option is used to specify the name of the new module and also the components. The ``-name`` option is used to specify the name of the new module
name of the new cell in the current module. and also the name of the new cell in the current module.
.. figure:: ../../images/011/submod_dots.* .. figure:: ../../images/011/submod_dots.*
:class: width-helper :class: width-helper
@ -621,7 +622,7 @@ name of the new cell in the current module.
.. code-block:: yoscrypt .. code-block:: yoscrypt
:caption: The circuit from :numref:`memdemo_src` and :numref:`memdemo_00` :caption: The circuit from :numref:`memdemo_src` and :numref:`memdemo_00`
broken up using ``submod`` broken up using :cmd:ref:`submod`
:name: submod :name: submod
select -set outstage y %ci2:+$dff[Q,D] %ci*:-$mux[S]:-$dff select -set outstage y %ci2:+$dff[Q,D] %ci*:-$mux[S]:-$dff
@ -634,8 +635,8 @@ name of the new cell in the current module.
Evaluation of combinatorial circuits Evaluation of combinatorial circuits
------------------------------------ ------------------------------------
The ``eval`` command can be used to evaluate combinatorial circuits. For example The :cmd:ref:`eval` command can be used to evaluate combinatorial circuits. For
(see :numref:`submod` for the circuit diagram of ``selstage``): example (see :numref:`submod` for the circuit diagram of ``selstage``):
:: ::
@ -676,11 +677,11 @@ The ``-table`` option can be used to create a truth table. For example:
Assumed undef (x) value for the following signals: \s2 Assumed undef (x) value for the following signals: \s2
Note that the ``eval`` command (as well as the ``sat`` command discussed in the Note that the :cmd:ref:`eval` command (as well as the :cmd:ref:`sat` command
next sections) does only operate on flattened modules. It can not analyze discussed in the next sections) does only operate on flattened modules. It can
signals that are passed through design hierarchy levels. So the ``flatten`` not analyze signals that are passed through design hierarchy levels. So the
command must be used on modules that instantiate other modules before this :cmd:ref:`flatten` command must be used on modules that instantiate other
commands can be applied. modules before this commands can be applied.
Solving combinatorial SAT problems Solving combinatorial SAT problems
---------------------------------- ----------------------------------
@ -754,18 +755,18 @@ Solving combinatorial SAT problems
\____ $$$|__/|________/|__/|_______/|__/ \____ $$$|__/|________/|__/|_______/|__/
\__/ \__/
Often the opposite of the ``eval`` command is needed, i.e. the circuits output Often the opposite of the :cmd:ref:`eval` command is needed, i.e. the circuits
is given and we want to find the matching input signals. For small circuits with output is given and we want to find the matching input signals. For small
only a few input bits this can be accomplished by trying all possible input circuits with only a few input bits this can be accomplished by trying all
combinations, as it is done by the ``eval -table`` command. For larger circuits possible input combinations, as it is done by the ``eval -table`` command. For
however, Yosys provides the ``sat`` command that uses a `SAT`_ solver, larger circuits however, Yosys provides the :cmd:ref:`sat` command that uses a
`MiniSAT`_, to solve this kind of problems. `SAT`_ solver, `MiniSAT`_, to solve this kind of problems.
.. _SAT: http://en.wikipedia.org/wiki/Circuit_satisfiability .. _SAT: http://en.wikipedia.org/wiki/Circuit_satisfiability
.. _MiniSAT: http://minisat.se/ .. _MiniSAT: http://minisat.se/
The ``sat`` command works very similar to the ``eval`` command. The main The :cmd:ref:`sat` command works very similar to the :cmd:ref:`eval` command. The main
difference is that it is now also possible to set output values and find the difference is that it is now also possible to set output values and find the
corresponding input values. For Example: corresponding input values. For Example:
@ -792,8 +793,8 @@ corresponding input values. For Example:
\s1 0 0 00 \s1 0 0 00
\s2 0 0 00 \s2 0 0 00
Note that the ``sat`` command supports signal names in both arguments to the Note that the :cmd:ref:`sat` command supports signal names in both arguments to
``-set`` option. In the above example we used ``-set s1 s2`` to constraint the ``-set`` option. In the above example we used ``-set s1 s2`` to constraint
``s1`` and ``s2`` to be equal. When more complex constraints are needed, a ``s1`` and ``s2`` to be equal. When more complex constraints are needed, a
wrapper circuit must be constructed that checks the constraints and signals if wrapper circuit must be constructed that checks the constraints and signals if
the constraint was met using an extra output port, which then can be forced to a the constraint was met using an extra output port, which then can be forced to a
@ -812,8 +813,8 @@ of course be to perform the test in 32 bits, for example by replacing ``p !=
a*b`` in the miter with ``p != {16'd0,a}b``, or by using a temporary variable a*b`` in the miter with ``p != {16'd0,a}b``, or by using a temporary variable
for the 32 bit product ``a*b``. But as 31 fits well into 8 bits (and as the for the 32 bit product ``a*b``. But as 31 fits well into 8 bits (and as the
purpose of this document is to show off Yosys features) we can also simply force purpose of this document is to show off Yosys features) we can also simply force
the upper 8 bits of ``a`` and ``b`` to zero for the ``sat`` call, as is done in the upper 8 bits of ``a`` and ``b`` to zero for the :cmd:ref:`sat` call, as is
the second command in :numref:`primesat` (line 31). done in the second command in :numref:`primesat` (line 31).
The ``-prove`` option used in this example works similar to ``-set``, but tries The ``-prove`` option used in this example works similar to ``-set``, but tries
to find a case in which the two arguments are not equal. If such a case is not to find a case in which the two arguments are not equal. If such a case is not
@ -917,18 +918,18 @@ to this question, as produced by the following command:
sat -seq 6 -show y -show d -set-init-undef \ sat -seq 6 -show y -show d -set-init-undef \
-max_undef -set-at 4 y 1 -set-at 5 y 2 -set-at 6 y 3 -max_undef -set-at 4 y 1 -set-at 5 y 2 -set-at 6 y 3
The ``-seq 6`` option instructs the ``sat`` command to solve a sequential The ``-seq 6`` option instructs the :cmd:ref:`sat` command to solve a sequential
problem in 6 time steps. (Experiments with lower number of steps have show that problem in 6 time steps. (Experiments with lower number of steps have show that
at least 3 cycles are necessary to bring the circuit in a state from which the at least 3 cycles are necessary to bring the circuit in a state from which the
sequence 1, 2, 3 can be produced.) sequence 1, 2, 3 can be produced.)
The ``-set-init-undef`` option tells the ``sat`` command to initialize all The ``-set-init-undef`` option tells the :cmd:ref:`sat` command to initialize
registers to the undef (``x``) state. The way the ``x`` state is treated in all registers to the undef (``x``) state. The way the ``x`` state is treated in
Verilog will ensure that the solution will work for any initial state. Verilog will ensure that the solution will work for any initial state.
The ``-max_undef`` option instructs the ``sat`` command to find a solution with The ``-max_undef`` option instructs the :cmd:ref:`sat` command to find a
a maximum number of undefs. This way we can see clearly which inputs bits are solution with a maximum number of undefs. This way we can see clearly which
relevant to the solution. inputs bits are relevant to the solution.
Finally the three ``-set-at`` options add constraints for the ``y`` signal to Finally the three ``-set-at`` options add constraints for the ``y`` signal to
play the 1, 2, 3 sequence, starting with time step 4. play the 1, 2, 3 sequence, starting with time step 4.
@ -938,27 +939,27 @@ is the only way of setting the ``s1`` and ``s2`` registers to a known value. The
input values for the other steps are a bit harder to work out manually, but the input values for the other steps are a bit harder to work out manually, but the
SAT solver finds the correct solution in an instant. SAT solver finds the correct solution in an instant.
There is much more to write about the ``sat`` command. For example, there is a There is much more to write about the :cmd:ref:`sat` command. For example, there
set of options that can be used to performs sequential proofs using temporal is a set of options that can be used to performs sequential proofs using
induction :cite:p:`een2003temporal`. The command ``help sat`` can be used to temporal induction :cite:p:`een2003temporal`. The command ``help sat`` can be
print a list of all options with short descriptions of their functions. used to print a list of all options with short descriptions of their functions.
.. _conclusion: .. _conclusion:
Conclusion Conclusion
========== ==========
Yosys provides a wide range of functions to analyze and investigate Yosys provides a wide range of functions to analyze and investigate designs. For
designs. For many cases it is sufficient to simply display circuit many cases it is sufficient to simply display circuit diagrams, maybe use some
diagrams, maybe use some additional commands to narrow the scope of the additional commands to narrow the scope of the circuit diagrams to the
circuit diagrams to the interesting parts of the circuit. But some cases interesting parts of the circuit. But some cases require more than that. For
require more than that. For this applications Yosys provides commands this applications Yosys provides commands that can be used to further inspect
that can be used to further inspect the behavior of the circuit, either the behavior of the circuit, either by evaluating which output values are
by evaluating which output values are generated from certain input generated from certain input values (:cmd:ref:`eval`) or by evaluation which
values (``eval``) or by evaluation which input values and initial conditions input values and initial conditions can result in a certain behavior at the
can result in a certain behavior at the outputs (``sat``). The SAT command outputs (:cmd:ref:`sat`). The SAT command can even be used to prove (or
can even be used to prove (or disprove) theorems regarding the circuit, disprove) theorems regarding the circuit, in more advanced cases with the
in more advanced cases with the additional help of a miter circuit. additional help of a miter circuit.
This features can be powerful tools for the circuit designer using Yosys This features can be powerful tools for the circuit designer using Yosys
as a utility for building circuits and the software developer using as a utility for building circuits and the software developer using

2
docs/source/appendix/APPNOTE_012_Verilog_to_BTOR.rst
View file

@ -180,7 +180,7 @@ to the Yosys documentation, or run ``yosys -h <command_name>``.
The script presented earlier can be easily modified to have a BTOR file that The script presented earlier can be easily modified to have a BTOR file that
does not contain memories. This is done by removing the line number 8 and 10, does not contain memories. This is done by removing the line number 8 and 10,
and introduces a new command ``memory`` at line number 8. and introduces a new command :cmd:ref:`memory` at line number 8.
:numref:`btor_script_without_memory` shows the modified Yosys script file: :numref:`btor_script_without_memory` shows the modified Yosys script file:
.. code-block:: sh .. code-block:: sh

3
docs/source/getting_started/examples.rst
View file

@ -81,7 +81,8 @@ synthesis script (``counter.ys``), a digital design written in Verilog
#. :yoscrypt:`dfflibmap -liberty mycells.lib` - Map registers to available #. :yoscrypt:`dfflibmap -liberty mycells.lib` - Map registers to available
hardware flip-flops. hardware flip-flops.
#. :yoscrypt:`abc -liberty mycells.lib` - Map logic to available hardware gates. #. :yoscrypt:`abc -liberty mycells.lib` - Map logic to available hardware gates.
#. :yoscrypt:`clean` - Clean up the design (just the last step of ``opt``). #. :yoscrypt:`clean` - Clean up the design (just the last step of
:cmd:ref:`opt`).
#. :yoscrypt:`write_verilog synth.v` - Write final synthesis result to output #. :yoscrypt:`write_verilog synth.v` - Write final synthesis result to output
file. file.

16
docs/source/getting_started/scripting_intro.rst
View file

@ -10,10 +10,10 @@ terminated using the newline character or a semicolon (;). Empty lines and lines
starting with the hash sign (#) are ignored. See :ref:`sec:typusecase` for an starting with the hash sign (#) are ignored. See :ref:`sec:typusecase` for an
example synthesis script. example synthesis script.
The command ``help`` can be used to access the command reference manual, with The command :cmd:ref:`help` can be used to access the command reference manual,
``help <command>`` providing details for a specific command. ``yosys -H`` or with ``help <command>`` providing details for a specific command. ``yosys -H``
``yosys -h <command>`` will do the same outside of an interactive prompt. The or ``yosys -h <command>`` will do the same outside of an interactive prompt.
entire reference manual is also available here at :doc:`/cmd_ref`. The entire reference manual is also available here at :doc:`/cmd_ref`.
Example commands Example commands
~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~
@ -99,10 +99,10 @@ Selections intro
~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~
Most commands can operate not only on the entire design but also specifically on Most commands can operate not only on the entire design but also specifically on
selected parts of the design. For example the command ``dump`` will print all selected parts of the design. For example the command :cmd:ref:`dump` will print
selected objects in the current design while ``dump foobar`` will only print the all selected objects in the current design while ``dump foobar`` will only print
module ``foobar`` and ``dump *`` will print the entire design regardless of the the module ``foobar`` and ``dump *`` will print the entire design regardless of
current selection. the current selection.
.. code:: yoscrypt .. code:: yoscrypt

126
docs/source/getting_started/typical_phases.rst
View file

@ -57,17 +57,17 @@ needed variations of parametric modules.
hierarchy -check -top top_module hierarchy -check -top top_module
The ``proc`` command The :cmd:ref:`proc` command
~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~
The Verilog frontend converts ``always``-blocks to RTL netlists for the The Verilog frontend converts ``always``-blocks to RTL netlists for the
expressions and "processess" for the control- and memory elements. expressions and "processess" for the control- and memory elements.
The ``proc`` command transforms this "processess" to netlists of RTL multiplexer The :cmd:ref:`proc` command transforms this "processess" to netlists of RTL
and register cells. multiplexer and register cells.
The ``proc`` command is actually a macro-command that calls the following other The :cmd:ref:`proc` command is actually a macro-command that calls the following
commands: other commands:
.. code-block:: yoscrypt .. code-block:: yoscrypt
@ -80,8 +80,8 @@ commands:
proc_clean # if all went fine, this should remove all the processes proc_clean # if all went fine, this should remove all the processes
Many commands can not operate on modules with "processess" in them. Usually a Many commands can not operate on modules with "processess" in them. Usually a
call to ``proc`` is the first command in the actual synthesis procedure after call to :cmd:ref:`proc` is the first command in the actual synthesis procedure
design elaboration. after design elaboration.
Example Example
^^^^^^^ ^^^^^^^
@ -120,11 +120,11 @@ Example
:caption: ``docs/resources/PRESENTATION_ExSyn/proc_03.v`` :caption: ``docs/resources/PRESENTATION_ExSyn/proc_03.v``
The ``opt`` command The :cmd:ref:`opt` command
~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~
The ``opt`` command implements a series of simple optimizations. It also is a The :cmd:ref:`opt` command implements a series of simple optimizations. It also
macro command that calls other commands: is a macro command that calls other commands:
.. code-block:: yoscrypt .. code-block:: yoscrypt
@ -140,8 +140,8 @@ macro command that calls other commands:
opt_expr # const folding and simple expression rewriting opt_expr # const folding and simple expression rewriting
while [changed design] while [changed design]
The command ``clean`` can be used as alias for ``opt_clean``. And ``;;`` can be The command :cmd:ref:`clean` can be used as alias for :cmd:ref:`opt_clean`. And
used as shortcut for ``clean``. For example: ``;;`` can be used as shortcut for :cmd:ref:`clean`. For example:
.. code-block:: yoscrypt .. code-block:: yoscrypt
@ -195,31 +195,31 @@ Example
:caption: ``docs/resources/PRESENTATION_ExSyn/opt_04.ys`` :caption: ``docs/resources/PRESENTATION_ExSyn/opt_04.ys``
When to use ``opt`` or ``clean`` When to use :cmd:ref:`opt` or :cmd:ref:`clean`
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Usually it does not hurt to call ``opt`` after each regular command in the Usually it does not hurt to call :cmd:ref:`opt` after each regular command in
synthesis script. But it increases the synthesis time, so it is favourable to the synthesis script. But it increases the synthesis time, so it is favourable
only call ``opt`` when an improvement can be achieved. to only call :cmd:ref:`opt` when an improvement can be achieved.
The designs in ``yosys-bigsim`` are a good playground for experimenting with the The designs in ``yosys-bigsim`` are a good playground for experimenting with the
effects of calling ``opt`` in various places of the flow. effects of calling :cmd:ref:`opt` in various places of the flow.
It generally is a good idea to call ``opt`` before inherently expensive commands It generally is a good idea to call :cmd:ref:`opt` before inherently expensive
such as ``sat`` or ``freduce``, as the possible gain is much higher in this commands such as :cmd:ref:`sat` or :cmd:ref:`freduce`, as the possible gain is
cases as the possible loss. much higher in this cases as the possible loss.
The ``clean`` command on the other hand is very fast and many commands leave a The :cmd:ref:`clean` command on the other hand is very fast and many commands
mess (dangling signal wires, etc). For example, most commands do not remove any leave a mess (dangling signal wires, etc). For example, most commands do not
wires or cells. They just change the connections and depend on a later call to remove any wires or cells. They just change the connections and depend on a
clean to get rid of the now unused objects. So the occasional ``;;`` is a good later call to clean to get rid of the now unused objects. So the occasional
idea in every synthesis script. ``;;`` is a good idea in every synthesis script.
The ``memory`` command The :cmd:ref:`memory` command
~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
In the RTL netlist, memory reads and writes are individual cells. This makes In the RTL netlist, memory reads and writes are individual cells. This makes
consolidating the number of ports for a memory easier. The ``memory`` consolidating the number of ports for a memory easier. The :cmd:ref:`memory`
transforms memories to an implementation. Per default that is logic for address transforms memories to an implementation. Per default that is logic for address
decoders and registers. It also is a macro command that calls other commands: decoders and registers. It also is a macro command that calls other commands:
@ -269,12 +269,12 @@ Example
:caption: ``docs/resources/PRESENTATION_ExSyn/memory_02.ys`` :caption: ``docs/resources/PRESENTATION_ExSyn/memory_02.ys``
The ``fsm`` command The :cmd:ref:`fsm` command
~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~
The ``fsm`` command identifies, extracts, optimizes (re-encodes), and The :cmd:ref:`fsm` command identifies, extracts, optimizes (re-encodes), and
re-synthesizes finite state machines. It again is a macro that calls re-synthesizes finite state machines. It again is a macro that calls a series of
a series of other commands: other commands:
.. code-block:: yoscrypt .. code-block:: yoscrypt
@ -298,26 +298,27 @@ a series of other commands:
Some details on the most important commands from the ``fsm_*`` group: Some details on the most important commands from the ``fsm_*`` group:
The ``fsm_detect`` command identifies FSM state registers and marks them with The :cmd:ref:`fsm_detect` command identifies FSM state registers and marks them
the ``(* fsm_encoding = "auto" *)`` attribute, if they do not have the with the ``(* fsm_encoding = "auto" *)`` attribute, if they do not have the
``fsm_encoding`` set already. Mark registers with ``(* fsm_encoding = "none" ``fsm_encoding`` set already. Mark registers with ``(* fsm_encoding = "none"
*)`` to disable FSM optimization for a register. *)`` to disable FSM optimization for a register.
The ``fsm_extract`` command replaces the entire FSM (logic and state registers) The :cmd:ref:`fsm_extract` command replaces the entire FSM (logic and state
with a ``$fsm`` cell. registers) with a ``$fsm`` cell.
The commands ``fsm_opt`` and ``fsm_recode`` can be used to optimize the FSM. The commands :cmd:ref:`fsm_opt` and :cmd:ref:`fsm_recode` can be used to
optimize the FSM.
Finally the ``fsm_map`` command can be used to convert the (optimized) ``$fsm`` Finally the :cmd:ref:`fsm_map` command can be used to convert the (optimized)
cell back to logic and registers. ``$fsm`` cell back to logic and registers.
The ``techmap`` command The :cmd:ref:`techmap` command
~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. figure:: ../../images/res/PRESENTATION_ExSyn/techmap_01.* .. figure:: ../../images/res/PRESENTATION_ExSyn/techmap_01.*
:class: width-helper :class: width-helper
The ``techmap`` command replaces cells with implementations given as The :cmd:ref:`techmap` command replaces cells with implementations given as
verilog source. For example implementing a 32 bit adder using 16 bit adders: verilog source. For example implementing a 32 bit adder using 16 bit adders:
.. literalinclude:: ../../resources/PRESENTATION_ExSyn/techmap_01_map.v .. literalinclude:: ../../resources/PRESENTATION_ExSyn/techmap_01_map.v
@ -335,8 +336,9 @@ verilog source. For example implementing a 32 bit adder using 16 bit adders:
stdcell mapping stdcell mapping
^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^
When ``techmap`` is used without a map file, it uses a built-in map file to map When :cmd:ref:`techmap` is used without a map file, it uses a built-in map file
all RTL cell types to a generic library of built-in logic gates and registers. to map all RTL cell types to a generic library of built-in logic gates and
registers.
The built-in logic gate types are: ``$_NOT_``, ``$_AND_``, ``$_OR_``, The built-in logic gate types are: ``$_NOT_``, ``$_AND_``, ``$_OR_``,
``$_XOR_``, and ``$_MUX_``. ``$_XOR_``, and ``$_MUX_``.
@ -351,26 +353,27 @@ The register types are: ``$_SR_NN_``, ``$_SR_NP_``, ``$_SR_PN_``, ``$_SR_PP_``,
See :doc:`/yosys_internals/formats/cell_library` for more about the internal See :doc:`/yosys_internals/formats/cell_library` for more about the internal
cells used. cells used.
The ``abc`` command The :cmd:ref:`abc` command
~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~
The ``abc`` command provides an interface to ABC_, an open source tool for The :cmd:ref:`abc` command provides an interface to ABC_, an open source tool
low-level logic synthesis. for low-level logic synthesis.
.. _ABC: http://www.eecs.berkeley.edu/~alanmi/abc/ .. _ABC: http://www.eecs.berkeley.edu/~alanmi/abc/
The ``abc`` command processes a netlist of internal gate types and can perform: The :cmd:ref:`abc` command processes a netlist of internal gate types and can
perform:
- logic minimization (optimization) - logic minimization (optimization)
- mapping of logic to standard cell library (liberty format) - mapping of logic to standard cell library (liberty format)
- mapping of logic to k-LUTs (for FPGA synthesis) - mapping of logic to k-LUTs (for FPGA synthesis)
Optionally ``abc`` can process registers from one clock domain and perform Optionally :cmd:ref:`abc` can process registers from one clock domain and
sequential optimization (such as register balancing). perform sequential optimization (such as register balancing).
ABC is also controlled using scripts. An ABC script can be specified to use more ABC is also controlled using scripts. An ABC script can be specified to use more
advanced ABC features. It is also possible to write the design with advanced ABC features. It is also possible to write the design with
``write_blif`` and load the output file into ABC outside of Yosys. :cmd:ref:`write_blif` and load the output file into ABC outside of Yosys.
Example Example
^^^^^^^ ^^^^^^^
@ -389,16 +392,16 @@ Example
Other special-purpose mapping commands Other special-purpose mapping commands
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
``dfflibmap`` :cmd:ref:`dfflibmap`
This command maps the internal register cell types to the register types This command maps the internal register cell types to the register types
described in a liberty file. described in a liberty file.
``hilomap`` :cmd:ref:`hilomap`
Some architectures require special driver cells for driving a constant hi or Some architectures require special driver cells for driving a constant hi or
lo value. This command replaces simple constants with instances of such driver lo value. This command replaces simple constants with instances of such driver
cells. cells.
``iopadmap`` :cmd:ref:`iopadmap`
Top-level input/outputs must usually be implemented using special I/O-pad Top-level input/outputs must usually be implemented using special I/O-pad
cells. This command inserts this cells to the design. cells. This command inserts this cells to the design.
@ -436,5 +439,6 @@ Example Synthesis Script
# write synthesis results # write synthesis results
write_edif synth.edif write_edif synth.edif
The weird ``select`` expressions at the end of this script are discussed later The weird :cmd:ref:`select` expressions at the end of this script are discussed
in :doc:`using_yosys/more_scripting/selections</using_yosys/more_scripting/selections>`. later in
:doc:`using_yosys/more_scripting/selections</using_yosys/more_scripting/selections>`.

13
docs/source/using_yosys/memory_mapping.rst
View file

@ -3,12 +3,13 @@
Memory mapping Memory mapping
============== ==============
Documentation for the Yosys ``memory_libmap`` memory mapper. Note that not all supported patterns Documentation for the Yosys :cmd:ref:`memory_libmap` memory mapper. Note that
are included in this document, of particular note is that combinations of multiple patterns should not all supported patterns are included in this document, of particular note is
generally work. For example, `Write port with byte enables`_ could be used in conjunction with any that combinations of multiple patterns should generally work. For example,
of the simple dual port (SDP) models. In general if a hardware memory definition does not support a `Write port with byte enables`_ could be used in conjunction with any of the
given configuration, additional logic will be instantiated to guarantee behaviour is consistent with simple dual port (SDP) models. In general if a hardware memory definition does
simulation. not support a given configuration, additional logic will be instantiated to
guarantee behaviour is consistent with simulation.
See also: `passes/memory/memlib.md <https://github.com/YosysHQ/yosys/blob/master/passes/memory/memlib.md>`_ See also: `passes/memory/memlib.md <https://github.com/YosysHQ/yosys/blob/master/passes/memory/memlib.md>`_

74
docs/source/using_yosys/more_scripting/opt_passes.rst
View file

@ -11,12 +11,13 @@ This chapter outlines these optimizations.
Simple optimizations Simple optimizations
-------------------- --------------------
The Yosys pass ``opt`` runs a number of simple optimizations. This includes removing The Yosys pass :cmd:ref:`opt` runs a number of simple optimizations. This
unused signals and cells and const folding. It is recommended to run this pass includes removing unused signals and cells and const folding. It is recommended
after each major step in the synthesis script. At the time of this writing the to run this pass after each major step in the synthesis script. At the time of
``opt`` pass executes the following passes that each perform a simple optimization: this writing the :cmd:ref:`opt` pass executes the following passes that each
perform a simple optimization:
- Once at the beginning of ``opt``: - Once at the beginning of :cmd:ref:`opt`:
- ``opt_expr`` - ``opt_expr``
- ``opt_merge -nomux`` - ``opt_merge -nomux``
@ -32,15 +33,15 @@ after each major step in the synthesis script. At the time of this writing the
The following section describes each of the ``opt_`` passes. The following section describes each of the ``opt_`` passes.
The opt_expr pass The :cmd:ref:`opt_expr` pass
~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This pass performs const folding on the internal combinational cell types This pass performs const folding on the internal combinational cell types
described in :ref:`chapter:celllib`. This means a cell with all described in :ref:`chapter:celllib`. This means a cell with all constant inputs
constant inputs is replaced with the constant value this cell drives. In some is replaced with the constant value this cell drives. In some cases this pass
cases this pass can also optimize cells with some constant inputs. can also optimize cells with some constant inputs.
.. table:: Const folding rules for ``$_AND_`` cells as used in 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
@ -80,15 +81,16 @@ 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 opt_expr pass can replace 1-bit wide Besides this basic const folding the :cmd:ref:`opt_expr` pass can replace 1-bit
``$eq`` and ``$ne`` cells with buffers or not-gates if one input is constant. wide ``$eq`` and ``$ne`` cells with buffers or not-gates if one input is
constant.
The opt_expr pass is very conservative regarding optimizing ``$mux`` cells, as The :cmd:ref:`opt_expr` pass is very conservative regarding optimizing ``$mux``
these cells are often used to model decision-trees and breaking these trees can cells, as these cells are often used to model decision-trees and breaking these
interfere with other optimizations. trees can interfere with other optimizations.
The opt_muxtree pass The :cmd:ref:`opt_muxtree` pass
~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This pass optimizes trees of multiplexer cells by analyzing the select inputs. This pass optimizes trees of multiplexer cells by analyzing the select inputs.
Consider the following simple example: Consider the following simple example:
@ -99,12 +101,12 @@ Consider the following simple example:
module uut(a, y); input a; output [1:0] y = a ? (a ? 1 : 2) : 3; endmodule module uut(a, y); input a; output [1:0] y = a ? (a ? 1 : 2) : 3; endmodule
The output can never be 2, as this would require ``a`` to be 1 for the outer The output can never be 2, as this would require ``a`` to be 1 for the outer
multiplexer and 0 for the inner multiplexer. The opt_muxtree pass detects this multiplexer and 0 for the inner multiplexer. The :cmd:ref:`opt_muxtree` pass
contradiction and replaces the inner multiplexer with a constant 1, yielding the detects this contradiction and replaces the inner multiplexer with a constant 1,
logic for ``y = a ? 1 : 3``. yielding the logic for ``y = a ? 1 : 3``.
The opt_reduce pass The :cmd:ref:`opt_reduce` pass
~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
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
@ -121,22 +123,22 @@ Lastly this pass consolidates trees of ``$reduce_and`` cells and trees of
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.
The opt_rmdff pass The :cmd:ref:`opt_rmdff` pass
~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
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. driver.
The opt_clean pass The :cmd:ref:`opt_clean` pass
~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This pass identifies unused signals and cells and removes them from the design. This pass identifies unused signals and cells and removes them from the design.
It also creates an ``\unused_bits`` attribute on wires with unused bits. This It also creates an ``\unused_bits`` attribute on wires with unused bits. This
attribute can be used for debugging or by other optimization passes. attribute can be used for debugging or by other optimization passes.
The opt_merge pass The :cmd:ref:`opt_merge` pass
~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This pass performs trivial resource sharing. This means that this pass This pass performs trivial resource sharing. This means that this pass
identifies cells with identical inputs and replaces them with a single instance identifies cells with identical inputs and replaces them with a single instance
@ -144,8 +146,8 @@ 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 ``opt_muxtree`` to identify possible trees to be merged, which might prevent :cmd:ref:`opt_muxtree` to identify
optimizations. possible optimizations.
FSM extraction and encoding FSM extraction and encoding
--------------------------- ---------------------------
@ -193,9 +195,9 @@ using the ``\fsm_encoding`` attribute (unless ``\fsm_encoding`` is set to
``fsm_`` passes operate on these ``$fsm`` cells. The fsm_map call finally ``fsm_`` passes operate on these ``$fsm`` cells. The fsm_map call finally
replaces the ``$fsm`` cells with RTL cells. replaces the ``$fsm`` cells with RTL cells.
Note that these optimizations operate on an RTL netlist. I.e. the ``fsm`` pass Note that these optimizations operate on an RTL netlist. I.e. the :cmd:ref:`fsm`
should be executed after the proc pass has transformed all ``RTLIL::Process`` pass should be executed after the proc pass has transformed all
objects to RTL cells. ``RTLIL::Process`` objects to RTL cells.
The algorithms used for FSM detection and extraction are influenced by a more The algorithms used for FSM detection and extraction are influenced by a more
general reported technique :cite:p:`fsmextract`. general reported technique :cite:p:`fsmextract`.
@ -295,8 +297,8 @@ The fsm_opt pass performs basic optimizations on ``$fsm`` cells (not including
state recoding). The following optimizations are performed (in this order): 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 opt_clean pass) is used to ``\unused_bits`` (that is usually set by the :cmd:ref:`opt_clean` pass) is
determine which control outputs are unused. used to determine which control outputs are unused.
- Control inputs that are connected to the same driver are merged. - Control inputs that are connected to the same driver are merged.

42
docs/source/using_yosys/more_scripting/selections.rst
View file

@ -12,7 +12,7 @@ used to apply commands only to part of the design. For example:
delete foobar # will only delete the module foobar. delete foobar # will only delete the module foobar.
The ``select`` command can be used to create a selection for subsequent The :cmd:ref:`select` command can be used to create a selection for subsequent
commands. For example: commands. For example:
.. code:: yoscrypt .. code:: yoscrypt
@ -42,8 +42,8 @@ in synthesis scripts that are hand-tailored for a specific design.
Module and design context Module and design context
^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^
Commands can be executed in *module/* or *design/* context. Until now Commands can be executed in *module/* or *design/* context. Until now all
all commands have been executed in design context. The ``cd`` command can be commands have been executed in design context. The :cmd:ref:`cd` command can be
used to switch to module context. used to switch to module context.
In module context all commands only effect the active module. Objects in the In module context all commands only effect the active module. Objects in the
@ -76,7 +76,7 @@ Special patterns can be used to select by object property or type. For example:
select foo/t:$add # select all $add cells from the module foo select foo/t:$add # select all $add cells from the module foo
A complete list of this pattern expressions can be found in the command A complete list of this pattern expressions can be found in the command
reference to the ``select`` command. reference to the :cmd:ref:`select` command.
Combining selection Combining selection
^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^
@ -190,12 +190,13 @@ Interactive Design Investigation
Yosys can also be used to investigate designs (or netlists created from other Yosys can also be used to investigate designs (or netlists created from other
tools). tools).
- The selection mechanism, especially patterns such as ``%ci`` and ``%co``, - The selection mechanism, especially patterns such as ``%ci`` and ``%co``, can
can be used to figure out how parts of the design are connected. be used to figure out how parts of the design are connected.
- Commands such as ``submod``, ``expose``, and ``splice`` can be used to - Commands such as :cmd:ref:`submod`, :cmd:ref:`expose`, and :cmd:ref:`splice`
transform the design into an equivalent design that is easier to analyse. can be used to transform the design into an equivalent design that is easier
- Commands such as ``eval`` and ``sat`` can be used to investigate the behavior to analyse.
of the circuit. - Commands such as :cmd:ref:`eval` and :cmd:ref:`sat` can be used to investigate
the behavior of the circuit.
- :doc:`/cmd/show`. - :doc:`/cmd/show`.
- :doc:`/cmd/dump`. - :doc:`/cmd/dump`.
- :doc:`/cmd/add` and :doc:`/cmd/delete` can be used to modify and reorganize a - :doc:`/cmd/add` and :doc:`/cmd/delete` can be used to modify and reorganize a
@ -204,10 +205,10 @@ tools).
Changing design hierarchy Changing design hierarchy
^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^
Commands such as ``flatten`` and ``submod`` can be used to change the design Commands such as :cmd:ref:`flatten` and :cmd:ref:`submod` can be used to change
hierarchy, i.e. flatten the hierarchy or moving parts of a module to a the design hierarchy, i.e. flatten the hierarchy or moving parts of a module to
submodule. This has applications in synthesis scripts as well as in reverse a submodule. This has applications in synthesis scripts as well as in reverse
engineering and analysis. An example using ``submod`` is shown below for engineering and analysis. An example using :cmd:ref:`submod` is shown below for
reorganizing a module in Yosys and checking the resulting circuit. reorganizing a module in Yosys and checking the resulting circuit.
.. literalinclude:: ../../../resources/PRESENTATION_ExOth/scrambler.v .. literalinclude:: ../../../resources/PRESENTATION_ExOth/scrambler.v
@ -254,10 +255,10 @@ Analyzing the resulting circuit with :doc:`/cmd/eval`:
Behavioral changes Behavioral changes
^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^
Commands such as ``techmap`` can be used to make behavioral changes to the Commands such as :cmd:ref:`techmap` can be used to make behavioral changes to
design, for example changing asynchronous resets to synchronous resets. This has the design, for example changing asynchronous resets to synchronous resets. This
applications in design space exploration (evaluation of various architectures has applications in design space exploration (evaluation of various
for one circuit). architectures for one circuit).
The following techmap map file replaces all positive-edge async reset flip-flops The following techmap map file replaces all positive-edge async reset flip-flops
with positive-edge sync reset flip-flops. The code is taken from the example with positive-edge sync reset flip-flops. The code is taken from the example
@ -289,6 +290,5 @@ Yosys script for ASIC synthesis of the Amber ARMv2 CPU.
endmodule endmodule
For more on the ``techmap`` command, see the page on For more on the :cmd:ref:`techmap` command, see the page on
:doc:`/yosys_internals/techmap` or the :doc:`/yosys_internals/techmap`.
:doc:`techmap command reference document</cmd/techmap>`.

2
docs/source/using_yosys/more_scripting/synth.rst
View file

@ -1,7 +1,7 @@
Introduction to synthesis Introduction to synthesis
------------------------- -------------------------
The following commands are executed by the ``synth`` command: The following commands are executed by the :cmd:ref:`synth` command:
.. literalinclude:: /cmd/synth.rst .. literalinclude:: /cmd/synth.rst
:start-at: begin: :start-at: begin:

16
docs/source/yosys_internals/extensions.rst
View file

@ -58,7 +58,7 @@ about the internal data storage format used in Yosys and the classes that it
provides. provides.
This document will focus on the much simpler version of RTLIL left after the This document will focus on the much simpler version of RTLIL left after the
commands ``proc`` and ``memory`` (or ``memory -nomap``): commands :cmd:ref:`proc` and :cmd:ref:`memory` (or ``memory -nomap``):
.. figure:: ../../images/simplified_rtlil.* .. figure:: ../../images/simplified_rtlil.*
:class: width-helper :class: width-helper
@ -77,9 +77,10 @@ It is possible to only work on this simpler version:
} }
When trying to understand what a command does, creating a small test case to When trying to understand what a command does, creating a small test case to
look at the output of ``dump`` and ``show`` before and after the command has look at the output of :cmd:ref:`dump` and :cmd:ref:`show` before and after the
been executed can be helpful. The :doc:`/using_yosys/more_scripting/selections` command has been executed can be helpful. The
document has more information on using these commands. :doc:`/using_yosys/more_scripting/selections` document has more information on
using these commands.
.. todo:: copypaste .. todo:: copypaste
@ -120,15 +121,16 @@ Most commands modify existing modules, not create new ones.
When modifying existing modules, stick to the following DOs and DON'Ts: When modifying existing modules, stick to the following DOs and DON'Ts:
- Do not remove wires. Simply disconnect them and let a successive ``clean`` - Do not remove wires. Simply disconnect them and let a successive
command worry about removing it. :cmd:ref:`clean` command worry about removing it.
- Use ``module->fixup_ports()`` after changing the ``port_*`` properties of - Use ``module->fixup_ports()`` after changing the ``port_*`` properties of
wires. wires.
- You can safely remove cells or change the ``connections`` property of a cell, - You can safely remove cells or change the ``connections`` property of a cell,
but be careful when changing the size of the ``SigSpec`` connected to a cell but be careful when changing the size of the ``SigSpec`` connected to a cell
port. port.
- Use the ``SigMap`` helper class (see next slide) when you need a unique handle for each signal bit. - Use the ``SigMap`` helper class (see next section) when you need a unique
handle for each signal bit.
Using the SigMap helper class Using the SigMap helper class
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

33
docs/source/yosys_internals/flow/command_ordering.rst
View file

@ -28,13 +28,13 @@ components, such as LUTs, gates, or half- and full-adders.
The extract pass The extract pass
~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~
- Like the ``techmap`` pass, the ``extract`` pass is called with a map file. It - Like the :cmd:ref:`techmap` pass, the :cmd:ref:`extract` pass is called with a
compares the circuits inside the modules of the map file with the design and map file. It compares the circuits inside the modules of the map file with the
looks for sub-circuits in the design that match any of the modules in the map design and looks for sub-circuits in the design that match any of the modules
file. in the map file.
- If a match is found, the ``extract`` pass will replace the matching subcircuit - If a match is found, the :cmd:ref:`extract` pass will replace the matching
with an instance of the module from the map file. subcircuit with an instance of the module from the map file.
- In a way the ``extract`` pass is the inverse of the techmap pass. - In a way the :cmd:ref:`extract` pass is the inverse of the techmap pass.
.. todo:: copypaste .. todo:: copypaste
@ -93,19 +93,19 @@ can also be used to implement 16x20-bit multiplication.
A way of mapping such elements in coarse grain synthesis is the wrap-extract-unwrap method: A way of mapping such elements in coarse grain synthesis is the wrap-extract-unwrap method:
wrap wrap
Identify candidate-cells in the circuit and wrap them in a cell with a constant Identify candidate-cells in the circuit and wrap them in a cell with a
wider bit-width using ``techmap``. The wrappers use the same parameters as the original cell, so constant wider bit-width using :cmd:ref:`techmap`. The wrappers use the same
the information about the original width of the ports is preserved. parameters as the original cell, so the information about the original width
Then use the ``connwrappers`` command to connect up the bit-extended in- and of the ports is preserved. Then use the ``connwrappers`` command to connect up
outputs of the wrapper cells. the bit-extended in- and outputs of the wrapper cells.
extract extract
Now all operations are encoded using the same bit-width as the coarse grain Now all operations are encoded using the same bit-width as the coarse grain
element. The ``extract`` command can be used to replace circuits with cells element. The :cmd:ref:`extract` command can be used to replace circuits with
of the target architecture. cells of the target architecture.
unwrap unwrap
The remaining wrapper cell can be unwrapped using ``techmap``. The remaining wrapper cell can be unwrapped using :cmd:ref:`techmap`.
Example: DSP48_MACC Example: DSP48_MACC
~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~
@ -144,7 +144,8 @@ Extract: ``macc_xilinx_xmap.v``
:language: verilog :language: verilog
:caption: ``docs/resources/PRESENTATION_ExAdv/macc_xilinx_xmap.v`` :caption: ``docs/resources/PRESENTATION_ExAdv/macc_xilinx_xmap.v``
... simply use the same wrapping commands on this module as on the design to create a template for the ``extract`` command. ... simply use the same wrapping commands on this module as on the design to
create a template for the :cmd:ref:`extract` command.
Unwrapping multipliers: ``macc_xilinx_unwrap_map.v`` Unwrapping multipliers: ``macc_xilinx_unwrap_map.v``

3
docs/source/yosys_internals/flow/model_checking.rst
View file

@ -17,7 +17,8 @@ passes in Yosys.
Other applications include checking if a module conforms to interface standards. Other applications include checking if a module conforms to interface standards.
The ``sat`` command in Yosys can be used to perform Symbolic Model Checking. The :cmd:ref:`sat` command in Yosys can be used to perform Symbolic Model
Checking.
Checking techmap Checking techmap
~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~

32
docs/source/yosys_internals/flow/verilog_frontend.rst
View file

@ -407,9 +407,9 @@ transformed into a set of d-type flip-flops and the
multiplexers. multiplexers.
In more complex examples (e.g. asynchronous resets) the part of the In more complex examples (e.g. asynchronous resets) the part of the
``RTLIL::CaseRule``/``RTLIL::SwitchRule`` tree that describes the ``RTLIL::CaseRule``/``RTLIL::SwitchRule`` tree that describes the asynchronous
asynchronous reset must first be transformed to the correct reset must first be transformed to the correct ``RTLIL::SyncRule`` objects. This
``RTLIL::SyncRule`` objects. This is done by the proc_adff pass. is done by the :cmd:ref:`proc_adff` pass.
The ProcessGenerator algorithm The ProcessGenerator algorithm
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@ -591,16 +591,16 @@ The proc pass
The ProcessGenerator converts a behavioural model in AST representation to a The ProcessGenerator converts a behavioural model in AST representation to a
behavioural model in ``RTLIL::Process`` representation. The actual conversion behavioural model in ``RTLIL::Process`` representation. The actual conversion
from a behavioural model to an RTL representation is performed by the ``proc`` from a behavioural model to an RTL representation is performed by the
pass and the passes it launches: :cmd:ref:`proc` pass and the passes it launches:
- | proc_clean and proc_rmdead - | :cmd:ref:`proc_clean` and :cmd:ref:`proc_rmdead`
| These two passes just clean up the ``RTLIL::Process`` structure. The | These two passes just clean up the ``RTLIL::Process`` structure. The
``proc_clean`` pass removes empty parts (eg. empty assignments) from the :cmd:ref:`proc_clean` pass removes empty parts (eg. empty assignments) from
process and ``proc_rmdead`` detects and removes unreachable branches from the process and :cmd:ref:`proc_rmdead` detects and removes unreachable
the process's decision trees. branches from the process's decision trees.
- | proc_arst - | :cmd:ref:`proc_arst`
| This pass detects processes that describe d-type flip-flops with | This pass detects processes that describe d-type flip-flops with
asynchronous resets and rewrites the process to better reflect what they asynchronous resets and rewrites the process to better reflect what they
are modelling: Before this pass, an asynchronous reset has two are modelling: Before this pass, an asynchronous reset has two
@ -608,22 +608,22 @@ pass and the passes it launches:
reset path. After this pass the sync rule for the reset is level-sensitive reset path. After this pass the sync rule for the reset is level-sensitive
and the top-level ``RTLIL::SwitchRule`` has been removed. and the top-level ``RTLIL::SwitchRule`` has been removed.
- | proc_mux - | :cmd:ref:`proc_mux`
| This pass converts the ``RTLIL::CaseRule``/ ``RTLIL::SwitchRule``-tree to a | This pass converts the ``RTLIL::CaseRule``/ ``RTLIL::SwitchRule``-tree to a
tree of multiplexers per written signal. After this, the ``RTLIL::Process`` tree of multiplexers per written signal. After this, the ``RTLIL::Process``
structure only contains the ``RTLIL::SyncRule`` s that describe the output structure only contains the ``RTLIL::SyncRule`` s that describe the output
registers. registers.
- | proc_dff - | :cmd:ref:`proc_dff`
| This pass replaces the ``RTLIL::SyncRule`` s to d-type flip-flops (with | This pass replaces the ``RTLIL::SyncRule`` s to d-type flip-flops (with
asynchronous resets if necessary). asynchronous resets if necessary).
- | 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.
- | proc_clean - | :cmd:ref:`proc_clean`
| A final call to ``proc_clean`` removes the now empty ``RTLIL::Process`` | A final call to :cmd:ref:`proc_clean` removes the now empty
objects. ``RTLIL::Process`` objects.
Performing these last processing steps in passes instead of in the Verilog Performing these last processing steps in passes instead of in the Verilog
frontend has two important benefits: frontend has two important benefits:

57
docs/source/yosys_internals/formats/cell_library.rst
View file

@ -255,8 +255,8 @@ additional two 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.
Usually these cells are generated by the ``proc`` pass using the information in Usually these cells are generated by the :cmd:ref:`proc` pass using the
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
@ -270,8 +270,8 @@ 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 value is Note that the ``$adff`` and ``$sdff`` cells can only be used when the reset
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
@ -433,16 +433,17 @@ The ``$memwr_v2`` cells have a clock input ``\CLK``, an enable input ``\EN``
``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``.
``\PORTID`` ``\PORTID``
An identifier for this write port, used to index write port bit mask parameters. An identifier for this write port, used to index write port bit mask
parameters.
``\PRIORITY_MASK`` ``\PRIORITY_MASK``
This parameter is a bitmask of write ports that this write port has This parameter is a bitmask of write ports that this write port has priority
priority over in case of writing to the same address. The bits of this over in case of writing to the same address. The bits of this parameter are
parameter are indexed by the other write port's ``\PORTID`` parameter. indexed by the other write port's ``\PORTID`` parameter. Write ports can
Write ports can only have priority over write ports with lower port ID. only have priority over write ports with lower port ID. When two ports write
When two ports write to the same address and neither has priority over to the same address and neither has priority over the other, the result is
the other, the result is undefined. Priority can only be set between undefined. Priority can only be set between two synchronous ports sharing
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
@ -468,13 +469,13 @@ synthesis to succeed.
initialization conflict. initialization conflict.
The HDL frontend models a memory using RTLIL::Memory objects and asynchronous The HDL frontend models a memory using RTLIL::Memory objects and asynchronous
``$memrd_v2`` and ``$memwr_v2`` cells. The ``memory`` pass (i.e.~its various ``$memrd_v2`` and ``$memwr_v2`` cells. The :cmd:ref:`memory` pass (i.e.~its
sub-passes) migrates ``$dff`` cells into the ``$memrd_v2`` and ``$memwr_v2`` various sub-passes) migrates ``$dff`` cells into the ``$memrd_v2`` and
cells making them synchronous, then converts them to a single ``$mem_v2`` cell ``$memwr_v2`` cells making them synchronous, then converts them to a single
and (optionally) maps this cell type to ``$dff`` cells for the individual words ``$mem_v2`` cell and (optionally) maps this cell type to ``$dff`` cells for the
and multiplexer-based address decoders for the read and write interfaces. When individual words and multiplexer-based address decoders for the read and write
the last step is disabled or not possible, a ``$mem_v2`` cell is left in the interfaces. When the last step is disabled or not possible, a ``$mem_v2`` cell
design. is left in the design.
The ``$mem_v2`` cell provides the following parameters: The ``$mem_v2`` cell provides the following parameters:
@ -600,15 +601,15 @@ The ``$mem_v2`` cell has the following ports:
This input is ``\WR_PORTS*\WIDTH`` bits wide, containing all data This input is ``\WR_PORTS*\WIDTH`` bits wide, containing all data
signals for the write ports. signals for the write ports.
The ``memory_collect`` pass can be used to convert discrete ``$memrd_v2``, The :cmd:ref:`memory_collect` pass can be used to convert discrete
``$memwr_v2``, and ``$meminit_v2`` cells belonging to the same memory to a ``$memrd_v2``, ``$memwr_v2``, and ``$meminit_v2`` cells belonging to the same
single ``$mem_v2`` cell, whereas the ``memory_unpack`` pass performs the inverse memory to a single ``$mem_v2`` cell, whereas the :cmd:ref:`memory_unpack` pass
operation. The ``memory_dff`` pass can combine asynchronous memory ports that performs the inverse operation. The :cmd:ref:`memory_dff` pass can combine
are fed by or feeding registers into synchronous memory ports. The asynchronous memory ports that are fed by or feeding registers into synchronous
``memory_bram`` pass can be used to recognize ``$mem_v2`` cells that can be memory ports. The :cmd:ref:`memory_bram` pass can be used to recognize
implemented with a block RAM resource on an FPGA. The ``memory_map`` pass can be ``$mem_v2`` cells that can be implemented with a block RAM resource on an FPGA.
used to implement ``$mem_v2`` cells as basic logic: word-wide DFFs and address The :cmd:ref:`memory_map` pass can be used to implement ``$mem_v2`` cells as
decoders. basic logic: word-wide DFFs and address decoders.
Finite state machines Finite state machines
~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~

46
docs/source/yosys_internals/formats/rtlil_rep.rst
View file

@ -6,22 +6,22 @@ representation. The only exception are the high-level frontends that use the AST
representation as an intermediate step before generating RTLIL data. representation as an intermediate step before generating RTLIL data.
In order to avoid reinventing names for the RTLIL classes, they are simply In order to avoid reinventing names for the RTLIL classes, they are simply
referred to by their full C++ name, i.e. including the ``RTLIL::`` namespace prefix, referred to by their full C++ name, i.e. including the ``RTLIL::`` namespace
in this document. prefix, in this document.
:numref:`Figure %s <fig:Overview_RTLIL>` shows a simplified Entity-Relationship :numref:`Figure %s <fig:Overview_RTLIL>` shows a simplified Entity-Relationship
Diagram (ER Diagram) of RTLIL. In :math:`1:N` relationships the arrow points Diagram (ER Diagram) of RTLIL. In :math:`1:N` relationships the arrow points
from the :math:`N` side to the :math:`1`. For example one ``RTLIL::Design`` contains from the :math:`N` side to the :math:`1`. For example one ``RTLIL::Design``
:math:`N` (zero to many) instances of ``RTLIL::Module`` . A two-pointed arrow contains :math:`N` (zero to many) instances of ``RTLIL::Module`` . A two-pointed
indicates a :math:`1:1` relationship. arrow indicates a :math:`1:1` relationship.
The ``RTLIL::Design`` is the root object of the RTLIL data structure. There is The ``RTLIL::Design`` is the root object of the RTLIL data structure. There is
always one "current design" in memory which passes operate on, frontends add always one "current design" in memory which passes operate on, frontends add
data to and backends convert to exportable formats. But in some cases passes data to and backends convert to exportable formats. But in some cases passes
internally generate additional ``RTLIL::Design`` objects. For example when a pass is internally generate additional ``RTLIL::Design`` objects. For example when a
reading an auxiliary Verilog file such as a cell library, it might create an pass is reading an auxiliary Verilog file such as a cell library, it might
additional ``RTLIL::Design`` object and call the Verilog frontend with this other create an additional ``RTLIL::Design`` object and call the Verilog frontend with
object to parse the cell library. this other object to parse the cell library.
.. figure:: ../../../images/overview_rtlil.* .. figure:: ../../../images/overview_rtlil.*
:class: width-helper :class: width-helper
@ -31,9 +31,9 @@ object to parse the cell library.
There is only one active ``RTLIL::Design`` object that is used by all frontends, There is only one active ``RTLIL::Design`` object that is used by all frontends,
passes and backends called by the user, e.g. using a synthesis script. The passes and backends called by the user, e.g. using a synthesis script. The
``RTLIL::Design`` then contains zero to many ``RTLIL::Module`` objects. This corresponds ``RTLIL::Design`` then contains zero to many ``RTLIL::Module`` objects. This
to modules in Verilog or entities in VHDL. Each module in turn contains objects corresponds to modules in Verilog or entities in VHDL. Each module in turn
from three different categories: contains objects from three different categories:
- ``RTLIL::Cell`` and ``RTLIL::Wire`` objects represent classical netlist data. - ``RTLIL::Cell`` and ``RTLIL::Wire`` objects represent classical netlist data.
@ -44,8 +44,8 @@ from three different categories:
- ``RTLIL::Memory`` objects represent addressable memories (arrays). - ``RTLIL::Memory`` objects represent addressable memories (arrays).
Usually the output of the synthesis procedure is a netlist, i.e. all Usually the output of the synthesis procedure is a netlist, i.e. all
``RTLIL::Process`` and ``RTLIL::Memory`` objects must be replaced by ``RTLIL::Cell`` and ``RTLIL::Process`` and ``RTLIL::Memory`` objects must be replaced by
``RTLIL::Wire`` objects by synthesis passes. ``RTLIL::Cell`` and ``RTLIL::Wire`` objects by synthesis passes.
All features of the HDL that cannot be mapped directly to these RTLIL classes All features of the HDL that cannot be mapped directly to these RTLIL classes
must be transformed to an RTLIL-compatible representation by the HDL frontend. must be transformed to an RTLIL-compatible representation by the HDL frontend.
@ -78,9 +78,9 @@ This has three advantages:
- Second, the information about which identifiers were originally provided by - Second, the information about which identifiers were originally provided by
the user is always available which can help guide some optimizations. For the user is always available which can help guide some optimizations. For
example the ``opt_rmunused`` tries to preserve signals with a user-provided example the :cmd:ref:`opt_rmunused` tries to preserve signals with a
name but doesn't hesitate to delete signals that have auto-generated names user-provided name but doesn't hesitate to delete signals that have
when they just duplicate other signals. auto-generated names when they just duplicate other signals.
- Third, the delicate job of finding suitable auto-generated public visible - Third, the delicate job of finding suitable auto-generated public visible
names is deferred to one central location. Internally auto-generated names names is deferred to one central location. Internally auto-generated names
@ -184,8 +184,8 @@ An ``RTLIL::Cell`` object has the following properties:
- A list of parameters (for parametric cells) - A list of parameters (for parametric cells)
- Cell ports and the connections of ports to wires and constants - Cell ports and the connections of ports to wires and constants
The connections of ports to wires are coded by assigning an ``RTLIL::SigSpec`` to The connections of ports to wires are coded by assigning an ``RTLIL::SigSpec``
each cell port. The ``RTLIL::SigSpec`` data type is described in the next to each cell port. The ``RTLIL::SigSpec`` data type is described in the next
section. section.
.. _sec:rtlil_sigspec: .. _sec:rtlil_sigspec:
@ -320,8 +320,8 @@ trees before further processing them.
One of the first actions performed on a design in RTLIL representation in most One of the first actions performed on a design in RTLIL representation in most
synthesis scripts is identifying asynchronous resets. This is usually done using synthesis scripts is identifying asynchronous resets. This is usually done using
the ``proc_arst`` pass. This pass transforms the above example to the following the :cmd:ref:`proc_arst` pass. This pass transforms the above example to the
``RTLIL::Process``: following ``RTLIL::Process``:
.. code:: RTLIL .. code:: RTLIL
:number-lines: :number-lines:
@ -381,8 +381,8 @@ synthesis tasks.
RTLIL::Memory RTLIL::Memory
------------- -------------
For every array (memory) in the HDL code an ``RTLIL::Memory`` object is created. A For every array (memory) in the HDL code an ``RTLIL::Memory`` object is created.
memory object has the following properties: A memory object has the following properties:
- The memory name - The memory name
- A list of attributes - A list of attributes

20
docs/source/yosys_internals/techmap.rst
View file

@ -111,10 +111,9 @@ Techmap by example
.. todo:: copypaste .. todo:: copypaste
As a quick recap, the ``techmap`` command replaces cells in the design with As a quick recap, the :cmd:ref:`techmap` command replaces cells in the design
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 Yosys' internal cell types (such as ``$or``) as well as user-defined cell types.
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
@ -188,14 +187,15 @@ Scripting in map modules
- You can even call techmap recursively! - You can even call techmap recursively!
- Example use-cases: - Example use-cases:
- Using always blocks in map module: call ``proc`` - Using always blocks in map module: call :cmd:ref:`proc`
- Perform expensive optimizations (such as ``freduce``) on cells where - Perform expensive optimizations (such as :cmd:ref:`freduce`) on cells
this is known to work well. where this is known to work well.
- Interacting with custom commands. - Interacting with custom commands.
.. note:: PROTIP: .. note:: PROTIP:
Commands such as ``shell``, ``show -pause``, and ``dump`` can be use
in the ``_TECHMAP_DO_*`` scripts for debugging map modules. Commands such as :cmd:ref:`shell`, ``show -pause``, and :cmd:ref:`dump` can
be used in the ``_TECHMAP_DO_*`` scripts for debugging map modules.
Example: Example: