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

Docs: Shorten cmd:ref

Browse source
This commit is contained in:
Krystine Sherwin 2024-05-03 13:16:48 +12:00
parent e4ec3717bc
commit 829e02ec5b
No known key found for this signature in database
22 changed files with 296 additions and 297 deletions
Download patch file Download diff file Expand all files Collapse all files

104
docs/source/using_yosys/more_scripting/interactive_investigation.rst
View file

@ -13,7 +13,7 @@ A look at the show command
.. TODO:: merge into :doc:`/getting_started/scripting_intro` show section
This section explores the :cmd:ref:`show` command and explains the symbols used
This section explores the `show` command and explains the symbols used
in the circuit diagrams generated by it. The code used is included in the Yosys
code base under |code_examples/show|_.
@ -24,7 +24,7 @@ A simple circuit
^^^^^^^^^^^^^^^^
:ref:`example_v` below provides the Verilog code for a simple circuit which we
will use to demonstrate the usage of :cmd:ref:`show` in a simple setting.
will use to demonstrate the usage of `show` in a simple setting.
.. literalinclude:: /code_examples/show/example.v
:language: Verilog
@ -32,7 +32,7 @@ will use to demonstrate the usage of :cmd:ref:`show` in a simple setting.
:name: example_v
The Yosys synthesis script we will be running is included as
:numref:`example_ys`. Note that :cmd:ref:`show` is called with the ``-pause``
:numref:`example_ys`. Note that `show` is called with the ``-pause``
option, that halts execution of the Yosys script until the user presses the
Enter key. Using :yoscrypt:`show -pause` also allows the user to enter an
interactive shell to further investigate the circuit before continuing
@ -58,7 +58,7 @@ is shown.
.. figure:: /_images/code_examples/show/example_first.*
:class: width-helper invert-helper
Output of the first :cmd:ref:`show` command in :numref:`example_ys`
Output of the first `show` command in :numref:`example_ys`
The first output shows the design directly after being read by the Verilog
front-end. Input and output ports are displayed as octagonal shapes. Cells are
@ -84,39 +84,39 @@ original ``always``-block in the second line. Note how the multiplexer from the
``?:``-expression is represented as a `$mux` cell but the multiplexer from the
``if``-statement is yet still hidden within the process.
The :cmd:ref:`proc` command transforms the process from the first diagram into a
The `proc` command transforms the process from the first diagram into a
multiplexer and a d-type flip-flop, which brings us to the second diagram:
.. figure:: /_images/code_examples/show/example_second.*
:class: width-helper invert-helper
Output of the second :cmd:ref:`show` command in :numref:`example_ys`
Output of the second `show` command in :numref:`example_ys`
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
Verilog input.) Also note that the design now contains two instances of a
``BUF``-node. These are artefacts left behind by the :cmd:ref:`proc` command. It
``BUF``-node. These are artefacts left behind by the `proc` command. It
is quite usual to see such artefacts after calling commands that perform changes
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
:cmd:ref:`clean` (or :cmd:ref:`opt`, which includes :cmd:ref:`clean` as one of
`clean` (or `opt`, which includes `clean` as one of
its operations) will clean up these artefacts. This operation is so common in
Yosys scripts that it can simply be abbreviated with the ``;;`` token, which
doubles as separator for commands. Unless one wants to specifically analyze this
artefacts left behind some operations, it is therefore recommended to always
call :cmd:ref:`clean` before calling :cmd:ref:`show`.
call `clean` before calling `show`.
In this script we directly call :cmd:ref:`opt` as the next step, which finally
In this script we directly call `opt` as the next step, which finally
leads us to the third diagram:
.. figure:: /_images/code_examples/show/example_third.*
:class: width-helper invert-helper
:name: example_out
Output of the third :cmd:ref:`show` command in :ref:`example_ys`
Output of the third `show` command in :ref:`example_ys`
Here we see that the :cmd:ref:`opt` command not only has removed the artifacts
left behind by :cmd:ref:`proc`, but also determined correctly that it can remove
Here we see that the `opt` command not only has removed the artifacts
left behind by `proc`, but also determined correctly that it can remove
the first `$mux` cell without changing the behavior of the circuit.
Break-out boxes for signal vectors
@ -129,7 +129,7 @@ accesses.
:caption: :file:`splice.v`
:name: splice_src
Notice how the output for this circuit from the :cmd:ref:`show` command
Notice how the output for this circuit from the `show` command
(:numref:`splice_dia`) appears quite complex. This is an unfortunate side effect
of the way Yosys handles signal vectors (aka. multi-bit wires or buses) as
native objects. While this provides great advantages when analyzing circuits
@ -169,7 +169,7 @@ mapped to a cell library:
:name: first_pitfall
A half-adder built from simple CMOS gates, demonstrating common pitfalls when
using :cmd:ref:`show`
using `show`
.. literalinclude:: /code_examples/show/cmos.ys
:language: yoscrypt
@ -188,7 +188,7 @@ individual bits, resulting in an unnecessary complex diagram.
:class: width-helper invert-helper
:name: second_pitfall
Effects of :cmd:ref:`splitnets` command and of providing a cell library on
Effects of `splitnets` command and of providing a cell library on
design in :numref:`first_pitfall`
.. literalinclude:: /code_examples/show/cmos.ys
@ -201,11 +201,11 @@ individual bits, resulting in an unnecessary complex diagram.
For :numref:`second_pitfall`, Yosys has been given a description of the cell
library as 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
passed directly to the :cmd:ref:`show` command using the ``-lib <filename>``
passed directly to the `show` command using the ``-lib <filename>``
option. Secondly it is possible to load cell libraries into the design with the
:yoscrypt:`read_verilog -lib <filename>` command. The second method has the
great advantage that the library only needs to be loaded once and can then be
used in all subsequent calls to the :cmd:ref:`show` command.
used in all subsequent calls to the `show` command.
In addition to that, :numref:`second_pitfall` was generated after
:yoscrypt:`splitnet -ports` was run on the design. This command splits all
@ -216,7 +216,7 @@ module ports. Per default the command only operates on interior signals.
Miscellaneous notes
^^^^^^^^^^^^^^^^^^^
Per default the :cmd:ref:`show` command outputs a temporary dot file and
Per default the `show` command outputs a temporary dot file and
launches ``xdot`` to display it. The options ``-format``, ``-viewer`` and
``-prefix`` can be used to change format, viewer and filename prefix. Note that
the ``pdf`` and ``ps`` format are the only formats that support plotting
@ -225,13 +225,13 @@ modules, however ``xdot`` will raise an error when trying to read them.
In densely connected circuits it is sometimes hard to keep track of the
individual signal wires. For these cases it can be useful to call
:cmd:ref:`show` with the ``-colors <integer>`` argument, which randomly assigns
`show` with the ``-colors <integer>`` argument, which randomly assigns
colors to the 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 that looks good.
The command :yoscrypt:`help show` prints a complete listing of all options
supported by the :cmd:ref:`show` command.
supported by the `show` command.
Navigating the design
~~~~~~~~~~~~~~~~~~~~~
@ -245,9 +245,9 @@ In addition to *what* to display one also needs to carefully decide *when* to
display it, with respect to the synthesis flow. In general it is a good idea to
troubleshoot a circuit in the earliest state in which a problem can be
reproduced. So if, for example, the internal state before calling the
:cmd:ref:`techmap` command already fails to verify, it is better to troubleshoot
the coarse-grain version of the circuit before :cmd:ref:`techmap` than the
gate-level circuit after :cmd:ref:`techmap`.
`techmap` command already fails to verify, it is better to troubleshoot
the coarse-grain version of the circuit before `techmap` than the
gate-level circuit after `techmap`.
.. Note::
@ -260,16 +260,16 @@ Interactive navigation
^^^^^^^^^^^^^^^^^^^^^^
Once the right state within the synthesis flow for debugging the circuit has
been identified, it is recommended to simply add the :cmd:ref:`shell` command to
been identified, it is recommended to simply add the `shell` command to
the matching place in the synthesis script. This command will stop the synthesis
at the specified moment and go to shell mode, where the user can interactively
enter commands.
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
:cmd:ref:`ls` can now be used to create a list of all modules. The command
:cmd:ref:`cd` can be used to switch to one of the modules (type ``cd ..`` to
switch back). Now the :cmd:ref:`ls` command lists the objects within that
`ls` can now be used to create a list of all modules. The command
`cd` can be used to switch to one of the modules (type ``cd ..`` to
switch back). Now the `ls` command lists the objects within that
module. This is demonstrated below using :file:`example.v` from `A simple
circuit`_:
@ -277,10 +277,10 @@ circuit`_:
:language: doscon
:start-at: yosys> ls
:end-before: yosys [example]> dump
:caption: Output of :cmd:ref:`ls` and :cmd:ref:`cd` after running :file:`yosys example.v`
:caption: Output of `ls` and `cd` after running :file:`yosys example.v`
:name: lscd
When a module is selected using the :cmd:ref:`cd` command, all commands (with a
When a module is selected using the `cd` command, all commands (with a
few exceptions, such as the ``read_`` and ``write_`` commands) operate only on
the selected module. This can also be useful for synthesis scripts where
different synthesis strategies should be applied to different modules in the
@ -293,12 +293,12 @@ contains some additional information on the origin of the named object. But in
most cases those names can simply be abbreviated using the last part.
Usually all interactive work is done with one module selected using the
:cmd:ref:`cd` command. But it is also possible to work from the design-context
`cd` command. But it is also possible to work from the design-context
(``cd ..``). In this case all object names must be prefixed with
``<module_name>/``. For example ``a*/b*`` would refer to all objects whose names
start with ``b`` from all modules whose names start with ``a``.
The :cmd:ref:`dump` command can be used to print all information about an
The `dump` command can be used to print all information about an
object. For example, calling :yoscrypt:`dump $2` after the :yoscrypt:`cd
example` above:
@ -323,10 +323,10 @@ tools).
- The selection mechanism, especially patterns such as ``%ci`` and ``%co``, can
be used to figure out how parts of the design are connected.
- Commands such as :cmd:ref:`submod`, :cmd:ref:`expose`, and :cmd:ref:`splice`
- Commands such as `submod`, `expose`, and `splice`
can be used to transform the design into an equivalent design that is easier
to analyse.
- Commands such as :cmd:ref:`eval` and :cmd:ref:`sat` can be used to investigate
- Commands such as `eval` and `sat` can be used to investigate
the behavior of the circuit.
- :doc:`/cmd/show`.
- :doc:`/cmd/dump`.
@ -342,10 +342,10 @@ The code used is included in the Yosys code base under
Changing design hierarchy
^^^^^^^^^^^^^^^^^^^^^^^^^
Commands such as :cmd:ref:`flatten` and :cmd:ref:`submod` can be used to change
Commands such as `flatten` and `submod` can be used to change
the design hierarchy, i.e. flatten the hierarchy or moving parts of a module to
a submodule. This has applications in synthesis scripts as well as in reverse
engineering and analysis. An example using :cmd:ref:`submod` is shown below for
engineering and analysis. An example using `submod` is shown below for
reorganizing a module in Yosys and checking the resulting circuit.
.. literalinclude:: /code_examples/scrambler/scrambler.v
@ -388,7 +388,7 @@ Analyzing the resulting circuit with :doc:`/cmd/eval`:
Behavioral changes
^^^^^^^^^^^^^^^^^^
Commands such as :cmd:ref:`techmap` can be used to make behavioral changes to
Commands such as `techmap` can be used to make behavioral changes to
the design, for example changing asynchronous resets to synchronous resets. This
has applications in design space exploration (evaluation of various
architectures for one circuit).
@ -425,7 +425,7 @@ Yosys script for ASIC synthesis of the Amber ARMv2 CPU.
endmodule
For more on the :cmd:ref:`techmap` command, see the page on
For more on the `techmap` command, see the page on
:doc:`/yosys_internals/techmap`.
Advanced investigation techniques
@ -448,12 +448,12 @@ Recall the ``memdemo`` design from :ref:`advanced_logic_cones`:
Because this produces a rather large circuit, it can be useful to split it into
smaller parts for viewing and working with. :numref:`submod` does exactly that,
utilising the :cmd:ref:`submod` command to split the circuit into three
utilising the `submod` command to split the circuit into three
sections: ``outstage``, ``selstage``, and ``scramble``.
.. literalinclude:: /code_examples/selections/submod.ys
:language: yoscrypt
:caption: Using :cmd:ref:`submod` to break up the circuit from :file:`memdemo.v`
:caption: Using `submod` to break up the circuit from :file:`memdemo.v`
:start-after: cd memdemo
:end-before: cd ..
:name: submod
@ -481,7 +481,7 @@ below.
Evaluation of combinatorial circuits
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The :cmd:ref:`eval` command can be used to evaluate combinatorial circuits. As
The `eval` command can be used to evaluate combinatorial circuits. As
an example, we will use the ``selstage`` subnet of ``memdemo`` which we found
above and is shown in :numref:`selstage`.
@ -526,20 +526,20 @@ The ``-table`` option can be used to create a truth table. For example:
Assumed undef (x) value for the following signals: \s2
Note that the :cmd:ref:`eval` command (as well as the :cmd:ref:`sat` command
Note that the `eval` command (as well as the `sat` command
discussed in the next sections) does only operate on flattened modules. It can
not analyze signals that are passed through design hierarchy levels. So the
:cmd:ref:`flatten` command must be used on modules that instantiate other
`flatten` command must be used on modules that instantiate other
modules before these commands can be applied.
Solving combinatorial SAT problems
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Often the opposite of the :cmd:ref:`eval` command is needed, i.e. the circuits
Often the opposite of the `eval` command is needed, i.e. the circuits
output is given and we want to find the matching input signals. For small
circuits with only a few input bits this can be accomplished by trying all
possible input combinations, as it is done by the ``eval -table`` command. For
larger circuits however, Yosys provides the :cmd:ref:`sat` command that uses a
larger circuits however, Yosys provides the `sat` command that uses a
`SAT`_ solver, `MiniSAT`_, to solve this kind of problems.
.. _SAT: http://en.wikipedia.org/wiki/Circuit_satisfiability
@ -551,7 +551,7 @@ larger circuits however, Yosys provides the :cmd:ref:`sat` command that uses a
While it is possible to perform model checking directly in Yosys, it
is highly recommended to use SBY or EQY for formal hardware verification.
The :cmd:ref:`sat` command works very similar to the :cmd:ref:`eval` command.
The `sat` command works very similar to the `eval` command.
The main difference is that it is now also possible to set output values and
find the corresponding input values. For Example:
@ -580,7 +580,7 @@ find the corresponding input values. For Example:
\s1 0 0 00
\s2 0 0 00
Note that the :cmd:ref:`sat` command supports signal names in both arguments to
Note that the `sat` command supports signal names in both arguments to
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
wrapper circuit must be constructed that checks the constraints and signals if
@ -642,7 +642,7 @@ 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
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
the upper 8 bits of ``a`` and ``b`` to zero for the :cmd:ref:`sat` call, as is
the upper 8 bits of ``a`` and ``b`` to zero for the `sat` call, as is
done below.
.. todo:: replace inline code
@ -705,16 +705,16 @@ command:
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
The ``-seq 6`` option instructs the :cmd:ref:`sat` command to solve a sequential
The ``-seq 6`` option instructs the `sat` command to solve a sequential
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
sequence 1, 2, 3 can be produced.)
The ``-set-init-undef`` option tells the :cmd:ref:`sat` command to initialize
The ``-set-init-undef`` option tells the `sat` command to initialize
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.
The ``-max_undef`` option instructs the :cmd:ref:`sat` command to find a
The ``-max_undef`` option instructs the `sat` command to find a
solution with a maximum number of undefs. This way we can see clearly which
inputs bits are relevant to the solution.
@ -807,7 +807,7 @@ 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
SAT solver finds the correct solution in an instant.
There is much more to write about the :cmd:ref:`sat` command. For example, there
There is much more to write about the `sat` command. For example, there
is a set of options that can be used to performs sequential proofs using
temporal induction :cite:p:`een2003temporal`. The command ``help sat`` can be
used to print a list of all options with short descriptions of their functions.

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

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

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

@ -9,7 +9,7 @@ The selection framework
.. todo:: reduce overlap with :doc:`/getting_started/scripting_intro` select section
The :cmd:ref:`select` command can be used to create a selection for subsequent
The `select` command can be used to create a selection for subsequent
commands. For example:
.. code:: yoscrypt
@ -17,7 +17,7 @@ commands. For example:
select foobar # select the module foobar
delete # delete selected objects
Normally the :cmd:ref:`select` command overwrites a previous selection. The
Normally the `select` command overwrites a previous selection. The
commands :yoscrypt:`select -add` and :yoscrypt:`select -del` can be used to add
or remove objects from the current selection.
@ -26,16 +26,16 @@ default, which is a complete selection of everything in the current module.
This selection framework can also be used directly in many other commands.
Whenever a command has ``[selection]`` as last argument in its usage help, this
means that it will use the engine behind the :cmd:ref:`select` command to
means that it will use the engine behind the `select` command to
evaluate additional arguments and use the resulting selection instead of the
selection created by the last :cmd:ref:`select` command.
selection created by the last `select` command.
For example, the command :cmd:ref:`delete` will delete everything in the current
For example, the command `delete` will delete everything in the current
selection; while :yoscrypt:`delete foobar` will only delete the module foobar.
If no :cmd:ref:`select` command has been made, then the "current selection" will
If no `select` command has been made, then the "current selection" will
be the whole design.
.. note:: Many of the examples on this page make use of the :cmd:ref:`show`
.. note:: Many of the examples on this page make use of the `show`
command to visually demonstrate the effect of selections. For a more
detailed look at this command, refer to :ref:`interactive_show`.
@ -59,7 +59,7 @@ Module and design context
^^^^^^^^^^^^^^^^^^^^^^^^^
Commands can be executed in *module/* or *design/* context. Until now, all
commands have been executed in design context. The :cmd:ref:`cd` command can be
commands have been executed in design context. The `cd` command can be
used to switch to module context.
In module context, all commands only effect the active module. Objects in the
@ -101,7 +101,7 @@ Operations on selections
Combining selections
^^^^^^^^^^^^^^^^^^^^
The :cmd:ref:`select` command is actually much more powerful than it might seem
The `select` command is actually much more powerful than it might seem
at first glance. When it is called with multiple arguments, each argument is
evaluated and pushed separately on a stack. After all arguments have been
processed it simply creates the union of all elements on the stack. So
@ -190,7 +190,7 @@ Selecting logic cones
: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``
action can be used to select the input cones of all object in the top selection
in the stack maintained by the :cmd:ref:`select` command.
in the stack maintained by the `select` command.
As with the ``%x`` action, these commands broaden the selection by one "step".
But this time the operation only works against the direction of data flow. That
@ -222,9 +222,9 @@ The following sequence of diagrams demonstrates this step-wise expansion:
Notice the subtle difference between :yoscrypt:`show prod %ci` and
:yoscrypt:`show prod %ci %ci`. Both images show the `$mul` cell driven by
some inputs ``$3_Y`` and ``c``. However it is not until the second image,
having called ``%ci`` the second time, that :cmd:ref:`show` is able to
having called ``%ci`` the second time, that `show` is able to
distinguish between ``$3_Y`` being a wire and ``c`` being an input. We can see
this better with the :cmd:ref:`dump` command instead:
this better with the `dump` command instead:
.. literalinclude:: /code_examples/selections/sumprod.out
:language: RTLIL
@ -276,7 +276,7 @@ look at the first section:
This loads :numref:`memdemo_src` and synthesizes the included module. Note that
this code can be copied and run directly in a Yosys command line session,
provided :file:`memdemo.v` is in the same directory. We can now change to the
``memdemo`` module with ``cd memdemo``, and call :cmd:ref:`show` to see the
``memdemo`` module with ``cd memdemo``, and call `show` to see the
diagram in :numref:`memdemo_00`.
.. figure:: /_images/code_examples/selections/memdemo_00.*
@ -387,14 +387,14 @@ Storing and recalling selections
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>`` expression pushes the stored selection on the stack maintained by
the :cmd:ref:`select` command. So for example :yoscrypt:`select @foo @bar %i`
the `select` command. So for example :yoscrypt:`select @foo @bar %i`
will select the intersection between the stored selections ``foo`` and ``bar``.
In larger investigation efforts it is highly recommended to maintain a 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 change.
The :cmd:ref:`history` command can be used to list all recent interactive
The `history` command can be used to list all recent interactive
commands. This feature can be useful for creating such a script from the
commands used in an interactive session.

20
docs/source/using_yosys/synthesis/abc.rst
View file

@ -10,11 +10,11 @@ fine-grained optimisation and LUT mapping.
Yosys has two different commands, which both use this logic toolbox, but use it
in different ways.
The :cmd:ref:`abc` pass can be used for both ASIC (e.g. :yoscrypt:`abc
The `abc` pass can be used for both ASIC (e.g. :yoscrypt:`abc
-liberty`) and FPGA (:yoscrypt:`abc -lut`) mapping, but this page will focus on
FPGA mapping.
The :cmd:ref:`abc9` pass generally provides superior mapping quality due to
The `abc9` pass generally provides superior mapping quality due to
being aware of combination boxes and DFF and LUT timings, giving it a more
global view of the mapping problem.
@ -23,7 +23,7 @@ global view of the mapping problem.
ABC: the unit delay model, simple and efficient
-----------------------------------------------
The :cmd:ref:`abc` pass uses a highly simplified view of an FPGA:
The `abc` pass uses a highly simplified view of an FPGA:
- An FPGA is made up of a network of inputs that connect through LUTs to a
network of outputs. These inputs may actually be I/O pins, D flip-flops,
@ -126,7 +126,7 @@ guide to the syntax:
By convention, all delays in ``specify`` blocks are in integer picoseconds.
Files containing ``specify`` blocks should be read with the ``-specify`` option
to :cmd:ref:`read_verilog` so that they aren't skipped.
to `read_verilog` so that they aren't skipped.
LUTs
^^^^
@ -145,9 +145,9 @@ DFFs
DFFs should be annotated with an ``(* abc9_flop *)`` attribute, however ABC9 has
some specific requirements for this to be valid: - the DFF must initialise to
zero (consider using :cmd:ref:`dfflegalize` to ensure this). - the DFF cannot
have any asynchronous resets/sets (see the simplification idiom and the Boxes
section for what to do here).
zero (consider using `dfflegalize` to ensure this). - the DFF cannot have any
asynchronous resets/sets (see the simplification idiom and the Boxes section for
what to do here).
It is worth noting that in pure ``abc9`` mode, only the setup and arrival times
are passed to ABC9 (specifically, they are modelled as buffers with the given
@ -158,9 +158,9 @@ Some vendors have universal DFF models which include async sets/resets even when
they're unused. Therefore *the simplification idiom* exists to handle this: by
using a ``techmap`` file to discover flops which have a constant driver to those
asynchronous controls, they can be mapped into an intermediate, simplified flop
which qualifies as an ``(* abc9_flop *)``, ran through :cmd:ref:`abc9`, and then
mapped back to the original flop. This is used in :cmd:ref:`synth_intel_alm` and
:cmd:ref:`synth_quicklogic` for the PolarPro3.
which qualifies as an ``(* abc9_flop *)``, ran through `abc9`, and then mapped
back to the original flop. This is used in `synth_intel_alm` and
`synth_quicklogic` for the PolarPro3.
DFFs are usually specified to have setup constraints against the clock on the
input signals, and an arrival time for the ``Q`` output.

8
docs/source/using_yosys/synthesis/cell_libs.rst
View file

@ -54,7 +54,7 @@ Our circuit now looks like this:
:class: width-helper invert-helper
:name: counter-hierarchy
``counter`` after :cmd:ref:`hierarchy`
``counter`` after `hierarchy`
Coarse-grain representation
~~~~~~~~~~~~~~~~~~~~~~~~~~~
@ -82,7 +82,7 @@ Logic gate mapping
.. figure:: /_images/code_examples/intro/counter_02.*
:class: width-helper invert-helper
``counter`` after :cmd:ref:`techmap`
``counter`` after `techmap`
Mapping to hardware
~~~~~~~~~~~~~~~~~~~
@ -102,7 +102,7 @@ Recall that the Yosys built-in logic gate types are `$_NOT_`, `$_AND_`,
`$_OR_`, `$_XOR_`, and `$_MUX_` with an assortment of dff memory types.
:ref:`mycells-lib` defines our target cells as ``BUF``, ``NOT``, ``NAND``,
``NOR``, and ``DFF``. Mapping between these is performed with the commands
:cmd:ref:`dfflibmap` and :cmd:ref:`abc` as follows:
`dfflibmap` and `abc` as follows:
.. literalinclude:: /code_examples/intro/counter.ys
:language: yoscrypt
@ -117,7 +117,7 @@ The final version of our ``counter`` module looks like this:
``counter`` after hardware cell mapping
Before finally being output as a verilog file with :cmd:ref:`write_verilog`,
Before finally being output as a verilog file with `write_verilog`,
which can then be loaded into another tool:
.. literalinclude:: /code_examples/intro/counter.ys

20
docs/source/using_yosys/synthesis/extract.rst
View file

@ -1,13 +1,13 @@
The extract pass
----------------
- Like the :cmd:ref:`techmap` pass, the :cmd:ref:`extract` pass is called with a
- Like the `techmap` pass, the `extract` pass is called with a
map file. It compares the circuits inside the modules of the map file with the
design and looks for sub-circuits in the design that match any of the modules
in the map file.
- If a match is found, the :cmd:ref:`extract` pass will replace the matching
- If a match is found, the `extract` pass will replace the matching
subcircuit with an instance of the module from the map file.
- In a way the :cmd:ref:`extract` pass is the inverse of the techmap pass.
- In a way the `extract` pass is the inverse of the techmap pass.
.. todo:: add/expand supporting text, also mention custom pattern matching and
pmgen
@ -25,7 +25,7 @@ Example code can be found in |code_examples/macc|_.
.. figure:: /_images/code_examples/macc/macc_simple_test_00a.*
:class: width-helper invert-helper
before :cmd:ref:`extract`
before `extract`
.. literalinclude:: /code_examples/macc/macc_simple_test.ys
:language: yoscrypt
@ -34,7 +34,7 @@ Example code can be found in |code_examples/macc|_.
.. figure:: /_images/code_examples/macc/macc_simple_test_00b.*
:class: width-helper invert-helper
after :cmd:ref:`extract`
after `extract`
.. literalinclude:: /code_examples/macc/macc_simple_test.v
:language: verilog
@ -76,18 +76,18 @@ wrap-extract-unwrap method:
wrap
Identify candidate-cells in the circuit and wrap them in a cell with a
constant wider bit-width using :cmd:ref:`techmap`. The wrappers use the same
constant wider bit-width using `techmap`. The wrappers use the same
parameters as the original cell, so the information about the original width
of the ports is preserved. Then use the :cmd:ref:`connwrappers` command to
of the ports is preserved. Then use the `connwrappers` command to
connect up the bit-extended in- and outputs of the wrapper cells.
extract
Now all operations are encoded using the same bit-width as the coarse grain
element. The :cmd:ref:`extract` command can be used to replace circuits with
element. The `extract` command can be used to replace circuits with
cells of the target architecture.
unwrap
The remaining wrapper cell can be unwrapped using :cmd:ref:`techmap`.
The remaining wrapper cell can be unwrapped using `techmap`.
Example: DSP48_MACC
~~~~~~~~~~~~~~~~~~~
@ -127,7 +127,7 @@ Extract: :file:`macc_xilinx_xmap.v`
:caption: :file:`macc_xilinx_xmap.v`
... simply use the same wrapping commands on this module as on the design to
create a template for the :cmd:ref:`extract` command.
create a template for the `extract` command.
Unwrapping multipliers: :file:`macc_xilinx_unwrap_map.v`

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

@ -1,14 +1,14 @@
FSM handling
============
The :cmd:ref:`fsm` command identifies, extracts, optimizes (re-encodes), and
The `fsm` command identifies, extracts, optimizes (re-encodes), and
re-synthesizes finite state machines. It again is a macro that calls a series of
other commands:
.. literalinclude:: /code_examples/macro_commands/fsm.ys
:language: yoscrypt
:start-after: #end:
:caption: Passes called by :cmd:ref:`fsm`
:caption: Passes called by `fsm`
See also :doc:`/cmd/fsm`.
@ -18,7 +18,7 @@ general reported technique :cite:p:`fsmextract`.
FSM detection
~~~~~~~~~~~~~
The :cmd:ref:`fsm_detect` pass identifies FSM state registers. It sets the
The `fsm_detect` pass identifies FSM state registers. It sets the
``\fsm_encoding = "auto"`` attribute on any (multi-bit) wire that matches the
following description:
@ -44,7 +44,7 @@ results.
FSM extraction
~~~~~~~~~~~~~~
The :cmd:ref:`fsm_extract` pass operates on all state signals marked with the
The `fsm_extract` pass operates on all state signals marked with the
(``\fsm_encoding != "none"``) attribute. For each state signal the following
information is determined:
@ -87,7 +87,7 @@ given set of result signals using a set of signal-value assignments. It can also
be passed a list of stop-signals that abort the ConstEval algorithm if the value
of a stop-signal is needed in order to calculate the result signals.
The :cmd:ref:`fsm_extract` pass uses the ConstEval class in the following way to
The `fsm_extract` pass uses the ConstEval class in the following way to
create a transition table. For each state:
1. Create a ConstEval object for the module containing the FSM
@ -108,12 +108,12 @@ drivers for the control outputs are disconnected.
FSM optimization
~~~~~~~~~~~~~~~~
The :cmd:ref:`fsm_opt` pass performs basic optimizations on `$fsm` cells (not
The `fsm_opt` pass performs basic optimizations on `$fsm` cells (not
including state recoding). The following optimizations are performed (in this
order):
- Unused control outputs are removed from the `$fsm` cell. The attribute
``\unused_bits`` (that is usually set by the :cmd:ref:`opt_clean` pass) is
``\unused_bits`` (that is usually set by the `opt_clean` pass) is
used to determine which control outputs are unused.
- Control inputs that are connected to the same driver are merged.
@ -134,11 +134,11 @@ order):
FSM recoding
~~~~~~~~~~~~
The :cmd:ref:`fsm_recode` pass assigns new bit pattern to the states. Usually
The `fsm_recode` pass assigns new bit pattern to the states. Usually
this also implies a change in the width of the state signal. At the moment of
this writing only one-hot encoding with all-zero for the reset state is
supported.
The :cmd:ref:`fsm_recode` pass can also write a text file with the changes
The `fsm_recode` pass can also write a text file with the changes
performed by it that can be used when verifying designs synthesized by Yosys
using Synopsys Formality.

12
docs/source/using_yosys/synthesis/index.rst
View file

@ -8,17 +8,17 @@ coarse-grain optimizations before being mapped to hard blocks and fine-grain
cells. Most commands in Yosys will target either coarse-grain representation or
fine-grain representation, with only a select few compatible with both states.
Commands such as :cmd:ref:`proc`, :cmd:ref:`fsm`, and :cmd:ref:`memory` rely on
Commands such as `proc`, `fsm`, and `memory` rely on
the additional information in the coarse-grain representation, along with a
number of optimizations such as :cmd:ref:`wreduce`, :cmd:ref:`share`, and
:cmd:ref:`alumacc`. :cmd:ref:`opt` provides optimizations which are useful in
both states, while :cmd:ref:`techmap` is used to convert coarse-grain cells
number of optimizations such as `wreduce`, `share`, and
`alumacc`. `opt` provides optimizations which are useful in
both states, while `techmap` is used to convert coarse-grain cells
to the corresponding fine-grain representation.
Single-bit cells (logic gates, FFs) as well as LUTs, half-adders, and
full-adders make up the bulk of the fine-grain representation and are necessary
for commands such as :cmd:ref:`abc`\ /:cmd:ref:`abc9`, :cmd:ref:`simplemap`,
:cmd:ref:`dfflegalize`, and :cmd:ref:`memory_map`.
for commands such as `abc`\ /`abc9`, `simplemap`,
`dfflegalize`, and `memory_map`.
.. toctree::
:maxdepth: 3

24
docs/source/using_yosys/synthesis/memory.rst
View file

@ -1,11 +1,11 @@
Memory handling
===============
The :cmd:ref:`memory` command
The `memory` command
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
In the RTL netlist, memory reads and writes are individual cells. This makes
consolidating the number of ports for a memory easier. The :cmd:ref:`memory`
consolidating the number of ports for a memory easier. The `memory`
pass transforms memories to an implementation. Per default that is logic for
address decoders and registers. It also is a macro command that calls the other
common ``memory_*`` passes in a sensible order:
@ -13,19 +13,19 @@ common ``memory_*`` passes in a sensible order:
.. literalinclude:: /code_examples/macro_commands/memory.ys
:language: yoscrypt
:start-after: #end:
:caption: Passes called by :cmd:ref:`memory`
:caption: Passes called by `memory`
.. todo:: Make ``memory_*`` notes less quick
Some quick notes:
- :cmd:ref:`memory_dff` merges registers into the memory read- and write cells.
- :cmd:ref:`memory_collect` collects all read and write cells for a memory and
- `memory_dff` merges registers into the memory read- and write cells.
- `memory_collect` collects all read and write cells for a memory and
transforms them into one multi-port memory cell.
- :cmd:ref:`memory_map` takes the multi-port memory cell and transforms it to
- `memory_map` takes the multi-port memory cell and transforms it to
address decoder logic and registers.
For more information about :cmd:ref:`memory`, such as disabling certain sub
For more information about `memory`, such as disabling certain sub
commands, see :doc:`/cmd/memory`.
Example
@ -75,22 +75,22 @@ For example:
techmap -map my_memory_map.v
memory_map
:cmd:ref:`memory_libmap` attempts to convert memory cells (`$mem_v2` etc) into
`memory_libmap` attempts to convert memory cells (`$mem_v2` etc) into
hardware supported memory using a provided library (:file:`my_memory_map.txt` in the
example above). Where necessary, emulation logic is added to ensure functional
equivalence before and after this conversion. :yoscrypt:`techmap -map
my_memory_map.v` then uses :cmd:ref:`techmap` to map to hardware primitives. Any
my_memory_map.v` then uses `techmap` to map to hardware primitives. Any
leftover memory cells unable to be converted are then picked up by
:cmd:ref:`memory_map` and mapped to DFFs and address decoders.
`memory_map` and mapped to DFFs and address decoders.
.. note::
More information about what mapping options are available and associated
costs of each can be found by enabling debug outputs. This can be done with
the :cmd:ref:`debug` command, or by using the ``-g`` flag when calling Yosys
the `debug` command, or by using the ``-g`` flag when calling Yosys
to globally enable debug messages.
For more on the lib format for :cmd:ref:`memory_libmap`, see
For more on the lib format for `memory_libmap`, see
`passes/memory/memlib.md
<https://github.com/YosysHQ/yosys/blob/main/passes/memory/memlib.md>`_

66
docs/source/using_yosys/synthesis/opt.rst
View file

@ -6,10 +6,10 @@ This chapter outlines these optimizations.
.. todo:: "outlines these optimizations" or "outlines *some*.."?
The :cmd:ref:`opt` macro command
The `opt` macro command
--------------------------------
The Yosys pass :cmd:ref:`opt` runs a number of simple optimizations. This
The Yosys pass `opt` runs a number of simple optimizations. This
includes removing unused signals and cells and const folding. It is recommended
to run this pass after each major step in the synthesis script. As listed in
:doc:`/cmd/opt`, this macro command calls the following ``opt_*`` commands:
@ -17,11 +17,11 @@ to run this pass after each major step in the synthesis script. As listed in
.. literalinclude:: /code_examples/macro_commands/opt.ys
:language: yoscrypt
:start-after: #end:
:caption: Passes called by :cmd:ref:`opt`
:caption: Passes called by `opt`
.. _adv_opt_expr:
Constant folding and simple expression rewriting - :cmd:ref:`opt_expr`
Constant folding and simple expression rewriting - `opt_expr`
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. todo:: unsure if this is too much detail and should be in :doc:`/yosys_internals/index`
@ -31,7 +31,7 @@ described in :doc:`/yosys_internals/formats/cell_library`. This means a cell
with all constant inputs is replaced with the constant value this cell drives.
In some cases this pass can also optimize cells with some constant inputs.
.. table:: Const folding rules for `$_AND_` cells as used in :cmd:ref:`opt_expr`.
.. table:: Const folding rules for `$_AND_` cells as used in `opt_expr`.
:name: tab:opt_expr_and
:align: center
@ -69,7 +69,7 @@ undef.
The last two lines simply replace an `$_AND_` gate with one constant-1 input
with a buffer.
Besides this basic const folding the :cmd:ref:`opt_expr` pass can replace 1-bit
Besides this basic const folding the `opt_expr` pass can replace 1-bit
wide `$eq` and `$ne` cells with buffers or not-gates if one input is
constant. Equality checks may also be reduced in size if there are redundant
bits in the arguments (i.e. bits which are constant on both inputs). This can,
@ -77,7 +77,7 @@ for example, result in a 32-bit wide constant like ``255`` being reduced to the
8-bit value of ``8'11111111`` if the signal being compared is only 8-bit as in
:ref:`addr_gen_clean` of :doc:`/getting_started/example_synth`.
The :cmd:ref:`opt_expr` pass is very conservative regarding optimizing `$mux`
The `opt_expr` pass is very conservative regarding optimizing `$mux`
cells, as these cells are often used to model decision-trees and breaking these
trees can interfere with other optimizations.
@ -85,14 +85,14 @@ trees can interfere with other optimizations.
:language: Verilog
:start-after: read_verilog <<EOT
:end-before: EOT
:caption: example verilog for demonstrating :cmd:ref:`opt_expr`
:caption: example verilog for demonstrating `opt_expr`
.. figure:: /_images/code_examples/opt/opt_expr.*
:class: width-helper invert-helper
Before and after :cmd:ref:`opt_expr`
Before and after `opt_expr`
Merging identical cells - :cmd:ref:`opt_merge`
Merging identical cells - `opt_merge`
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This pass performs trivial resource sharing. This means that this pass
@ -101,21 +101,21 @@ of the cell.
The option ``-nomux`` can be used to disable resource sharing for multiplexer
cells (`$mux` and `$pmux`.) This can be useful as it prevents multiplexer
trees to be merged, which might prevent :cmd:ref:`opt_muxtree` to identify
trees to be merged, which might prevent `opt_muxtree` to identify
possible optimizations.
.. literalinclude:: /code_examples/opt/opt_merge.ys
:language: Verilog
:start-after: read_verilog <<EOT
:end-before: EOT
:caption: example verilog for demonstrating :cmd:ref:`opt_merge`
:caption: example verilog for demonstrating `opt_merge`
.. figure:: /_images/code_examples/opt/opt_merge.*
:class: width-helper invert-helper
Before and after :cmd:ref:`opt_merge`
Before and after `opt_merge`
Removing never-active branches from multiplexer tree - :cmd:ref:`opt_muxtree`
Removing never-active branches from multiplexer tree - `opt_muxtree`
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This pass optimizes trees of multiplexer cells by analyzing the select inputs.
@ -125,19 +125,19 @@ Consider the following simple example:
:language: Verilog
:start-after: read_verilog <<EOT
:end-before: EOT
:caption: example verilog for demonstrating :cmd:ref:`opt_muxtree`
:caption: example verilog for demonstrating `opt_muxtree`
The output can never be ``c``, as this would require ``a`` to be 1 for the outer
multiplexer and 0 for the inner multiplexer. The :cmd:ref:`opt_muxtree` pass
multiplexer and 0 for the inner multiplexer. The `opt_muxtree` pass
detects this contradiction and replaces the inner multiplexer with a constant 1,
yielding the logic for ``y = a ? b : d``.
.. figure:: /_images/code_examples/opt/opt_muxtree.*
:class: width-helper invert-helper
Before and after :cmd:ref:`opt_muxtree`
Before and after `opt_muxtree`
Simplifying large MUXes and AND/OR gates - :cmd:ref:`opt_reduce`
Simplifying large MUXes and AND/OR gates - `opt_reduce`
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This is a simple optimization pass that identifies and consolidates identical
@ -155,7 +155,7 @@ 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
is produced.
Merging mutually exclusive cells with shared inputs - :cmd:ref:`opt_share`
Merging mutually exclusive cells with shared inputs - `opt_share`
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This pass identifies mutually exclusive cells of the same type that:
@ -169,17 +169,17 @@ multiplexing its output to multiplexing the non-shared input signals.
:language: Verilog
:start-after: read_verilog <<EOT
:end-before: EOT
:caption: example verilog for demonstrating :cmd:ref:`opt_share`
:caption: example verilog for demonstrating `opt_share`
.. figure:: /_images/code_examples/opt/opt_share.*
:class: width-helper invert-helper
Before and after :cmd:ref:`opt_share`
Before and after `opt_share`
When running :cmd:ref:`opt` in full, the original `$mux` (labeled ``$3``) is
optimized away by :cmd:ref:`opt_expr`.
When running `opt` in full, the original `$mux` (labeled ``$3``) is
optimized away by `opt_expr`.
Performing DFF optimizations - :cmd:ref:`opt_dff`
Performing DFF optimizations - `opt_dff`
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This pass identifies single-bit d-type flip-flops (`$_DFF_`, `$dff`, and
@ -190,30 +190,30 @@ removing unused control inputs.
Called with ``-nodffe`` and ``-nosdff``, this pass is used to prepare a design
for :doc:`/using_yosys/synthesis/fsm`.
Removing unused cells and wires - :cmd:ref:`opt_clean` pass
Removing unused cells and wires - `opt_clean` pass
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
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
attribute can be used for debugging or by other optimization passes.
When to use :cmd:ref:`opt` or :cmd:ref:`clean`
When to use `opt` or `clean`
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Usually it does not hurt to call :cmd:ref:`opt` after each regular command in
Usually it does not hurt to call `opt` after each regular command in
the synthesis script. But it increases the synthesis time, so it is favourable
to only call :cmd:ref:`opt` when an improvement can be achieved.
to only call `opt` when an improvement can be achieved.
It is generally a good idea to call :cmd:ref:`opt` before inherently expensive
commands such as :cmd:ref:`sat` or :cmd:ref:`freduce`, as the possible gain is
It is generally a good idea to call `opt` before inherently expensive
commands such as `sat` or `freduce`, as the possible gain is
much higher in these cases as the possible loss.
The :cmd:ref:`clean` command, which is an alias for :cmd:ref:`opt_clean` with
The `clean` command, which is an alias for `opt_clean` with
fewer outputs, on the other hand is very fast and many commands leave a mess
(dangling signal wires, etc). For example, most commands do not remove any wires
or cells. They just change the connections and depend on a later call to clean
to get rid of the now unused objects. So the occasional ``;;``, which itself is
an alias for :cmd:ref:`clean`, is a good idea in every synthesis script, e.g:
an alias for `clean`, is a good idea in every synthesis script, e.g:
.. code-block:: yoscrypt
@ -227,4 +227,4 @@ Other optimizations
- :doc:`/cmd/wreduce`
- :doc:`/cmd/peepopt`
- :doc:`/cmd/share`
- :cmd:ref:`abc` and :cmd:ref:`abc9`, see also: :doc:`abc`.
- `abc` and `abc9`, see also: :doc:`abc`.

10
docs/source/using_yosys/synthesis/proc.rst
View file

@ -6,21 +6,21 @@ Converting process blocks
The Verilog frontend converts ``always``-blocks to RTL netlists for the
expressions and "processess" for the control- and memory elements. The
:cmd:ref:`proc` command then transforms these "processess" to netlists of RTL
`proc` command then transforms these "processess" to netlists of RTL
multiplexer and register cells. It also is a macro command that calls the other
``proc_*`` commands in a sensible order:
.. literalinclude:: /code_examples/macro_commands/proc.ys
:language: yoscrypt
:start-after: #end:
:caption: Passes called by :cmd:ref:`proc`
:caption: Passes called by `proc`
After all the ``proc_*`` commands, :cmd:ref:`opt_expr` is called. This can be
After all the ``proc_*`` commands, `opt_expr` is called. This can be
disabled by calling :yoscrypt:`proc -noopt`. For more information about
:cmd:ref:`proc`, such as disabling certain sub commands, see :doc:`/cmd/proc`.
`proc`, such as disabling certain sub commands, see :doc:`/cmd/proc`.
Many commands can not operate on modules with "processess" in them. Usually a
call to :cmd:ref:`proc` is the first command in the actual synthesis procedure
call to `proc` is the first command in the actual synthesis procedure
after design elaboration.
Example

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

@ -38,7 +38,7 @@ In addition to the above hardware-specific synth commands, there is also
getting into any architecture-specific mappings or optimizations. Among other
things, this is useful for design verification.
The following commands are executed by the :cmd:ref:`prep` command:
The following commands are executed by the `prep` command:
.. literalinclude:: /cmd/prep.rst
:start-at: begin: