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

Docs: Shorten cmd:ref

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
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

14
docs/source/appendix/auxlibs.rst
View File

@ -29,7 +29,7 @@ ezSAT
The files in ``libs/ezsat`` provide a library for simplifying generating CNF
formulas for SAT solvers. It also contains bindings of MiniSAT. The ezSAT
library is written by C. Wolf. It is used by the :cmd:ref:`sat` pass (see
library is written by C. Wolf. It is used by the `sat` pass (see
:doc:`/cmd/sat`).
fst
@ -37,22 +37,22 @@ fst
``libfst`` files from `gtkwave`_ are included in ``libs/fst`` to support
reading/writing signal traces from/to the GTKWave developed FST format. This is
primarily used in the :cmd:ref:`sim` command.
primarily used in the `sim` command.
.. _gtkwave: https://github.com/gtkwave/gtkwave
json11
------
For reading/writing designs from/to JSON, :cmd:ref:`read_json` and
:cmd:ref:`write_json` should be used. For everything else there is the `json11
For reading/writing designs from/to JSON, `read_json` and
`write_json` should be used. For everything else there is the `json11
library`_:
json11 is a tiny JSON library for C++11, providing JSON parsing and
serialization.
This library is used for outputting machine-readable statistics (:cmd:ref:`stat`
with ``-json`` flag), using the RPC frontend (:cmd:ref:`connect_rpc`), and the
This library is used for outputting machine-readable statistics (`stat`
with ``-json`` flag), using the RPC frontend (`connect_rpc`), and the
yosys-witness ``yw`` format.
.. _json11 library: https://github.com/dropbox/json11
@ -61,7 +61,7 @@ MiniSAT
-------
The files in ``libs/minisat`` provide a high-performance SAT solver, used by the
:cmd:ref:`sat` command.
`sat` command.
SHA1
----

2
docs/source/appendix/env_vars.rst
View File

@ -3,7 +3,7 @@ Yosys environment variables
``HOME``
Yosys command history is stored in :file:`$HOME/.yosys_history`. Graphics
(from :cmd:ref:`show` and :cmd:ref:`viz` commands) will output to this
(from `show` and `viz` commands) will output to this
directory by default. This environment variable is also used in some cases
for resolving filenames with :file:`~`.

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

@ -2,9 +2,9 @@ Synthesis starter
-----------------
This page will be a guided walkthrough of the prepackaged iCE40 FPGA synthesis
script - :cmd:ref:`synth_ice40`. We will take a simple design through each
script - `synth_ice40`. We will take a simple design through each
step, looking at the commands being called and what they do to the design. While
:cmd:ref:`synth_ice40` is specific to the iCE40 platform, most of the operations
`synth_ice40` is specific to the iCE40 platform, most of the operations
we will be discussing are common across the majority of FPGA synthesis scripts.
Thus, this document will provide a good foundational understanding of how
synthesis in Yosys is performed, regardless of the actual architecture being
@ -59,8 +59,8 @@ can run each of the commands individually for a better sense of how each part
contributes to the flow. We will also start with just a single module;
``addr_gen``.
At the bottom of the :cmd:ref:`help` output for
:cmd:ref:`synth_ice40` is the complete list of commands called by this script.
At the bottom of the `help` output for
`synth_ice40` is the complete list of commands called by this script.
Let's start with the section labeled ``begin``:
.. literalinclude:: /cmd/synth_ice40.rst
@ -105,8 +105,8 @@ Since we're just getting started, let's instead begin with :yoscrypt:`hierarchy
.. note::
:cmd:ref:`hierarchy` should always be the first command after the design has
been read. By specifying the top module, :cmd:ref:`hierarchy` will also set
`hierarchy` should always be the first command after the design has
been read. By specifying the top module, `hierarchy` will also set
the ``(* top *)`` attribute on it. This is used by other commands that need
to know which module is the top.
@ -125,7 +125,7 @@ Our ``addr_gen`` circuit now looks like this:
:class: width-helper invert-helper
:name: addr_gen_hier
``addr_gen`` module after :cmd:ref:`hierarchy`
``addr_gen`` module after `hierarchy`
Simple operations like ``addr + 1`` and ``addr == MAX_DATA-1`` can be extracted
from our ``always @`` block in :ref:`addr_gen-v`. This gives us the highlighted
@ -137,9 +137,9 @@ second line refers to the line numbers of the start/end of the corresponding
``PROC`` referring to line 0.
To handle these, let us now introduce the next command: :doc:`/cmd/proc`.
:cmd:ref:`proc` is a macro command like :cmd:ref:`synth_ice40`. Rather than
`proc` is a macro command like `synth_ice40`. Rather than
modifying the design directly, it instead calls a series of other commands. In
the case of :cmd:ref:`proc`, these sub-commands work to convert the behavioral
the case of `proc`, these sub-commands work to convert the behavioral
logic of processes into multiplexers and registers. Let's see what happens when
we run it. For now, we will call :yoscrypt:`proc -noopt` to prevent some
automatic optimizations which would normally happen.
@ -160,8 +160,8 @@ Notice how in the top left of :ref:`addr_gen_proc` we have a floating wire,
generated from the initial assignment of 0 to the ``addr`` wire. However, this
initial assignment is not synthesizable, so this will need to be cleaned up
before we can generate the physical hardware. We can do this now by calling
:cmd:ref:`clean`. We're also going to call :cmd:ref:`opt_expr` now, which would
normally be called at the end of :cmd:ref:`proc`. We can call both commands at
`clean`. We're also going to call `opt_expr` now, which would
normally be called at the end of `proc`. We can call both commands at
the same time by separating them with a colon and space: :yoscrypt:`opt_expr;
clean`.
@ -175,7 +175,7 @@ You may also notice that the highlighted `$eq` cell input of ``255`` has
changed to ``8'11111111``. Constant values are presented in the format
``<bit_width>'<bits>``, with 32-bit values instead using the decimal number.
This indicates that the constant input has been reduced from 32-bit wide to
8-bit wide. This is a side-effect of running :cmd:ref:`opt_expr`, which
8-bit wide. This is a side-effect of running `opt_expr`, which
performs constant folding and simple expression rewriting. For more on why
this happens, refer to :doc:`/using_yosys/synthesis/opt` and the :ref:`section
on opt_expr <adv_opt_expr>`.
@ -185,7 +185,7 @@ on opt_expr <adv_opt_expr>`.
:doc:`/cmd/clean` can also be called with two semicolons after any command,
for example we could have called :yoscrypt:`opt_expr;;` instead of
:yoscrypt:`opt_expr; clean`. You may notice some scripts will end each line
with ``;;``. It is beneficial to run :cmd:ref:`clean` before inspecting
with ``;;``. It is beneficial to run `clean` before inspecting
intermediate products to remove disconnected parts of the circuit which have
been left over, and in some cases can reduce the processing required in
subsequent commands.
@ -202,7 +202,7 @@ The full example
Let's now go back and check on our full design by using :yoscrypt:`hierarchy
-check -top fifo`. By passing the ``-check`` option there we are also telling
the :cmd:ref:`hierarchy` command that if the design includes any non-blackbox
the `hierarchy` command that if the design includes any non-blackbox
modules without an implementation it should return an error.
Note that if we tried to run this command now then we would get an error. This
@ -221,15 +221,15 @@ could restart our shell session, but instead let's use two new commands:
Notice how this time we didn't see any of those ``$abstract`` modules? That's
because when we ran ``yosys fifo.v``, the first command Yosys called was
:yoscrypt:`read_verilog -defer fifo.v`. The ``-defer`` option there tells
:cmd:ref:`read_verilog` only read the abstract syntax tree and defer actual
compilation to a later :cmd:ref:`hierarchy` command. This is useful in cases
`read_verilog` only read the abstract syntax tree and defer actual
compilation to a later `hierarchy` command. This is useful in cases
where the default parameters of modules yield invalid code which is not
synthesizable. This is why Yosys defers compilation automatically and is one of
the reasons why hierarchy should always be the first command after loading the
design. If we know that our design won't run into this issue, we can skip the
``-defer``.
.. todo:: :cmd:ref:`hierarchy` failure modes
.. todo:: `hierarchy` failure modes
.. note::
@ -243,19 +243,19 @@ design. If we know that our design won't run into this issue, we can skip the
interactive terminal. :kbd:`ctrl+c` (i.e. SIGINT) will also end the terminal
session but will return an error code rather than exiting gracefully.
We can also run :cmd:ref:`proc` now to finish off the full :ref:`synth_begin`.
We can also run `proc` now to finish off the full :ref:`synth_begin`.
Because the design schematic is quite large, we will be showing just the data
path for the ``rdata`` output. If you would like to see the entire design for
yourself, you can do so with :doc:`/cmd/show`. Note that the :cmd:ref:`show`
yourself, you can do so with :doc:`/cmd/show`. Note that the `show`
command only works with a single module, so you may need to call it with
:yoscrypt:`show fifo`. :ref:`show_intro` section in
:doc:`/getting_started/scripting_intro` has more on how to use :cmd:ref:`show`.
:doc:`/getting_started/scripting_intro` has more on how to use `show`.
.. figure:: /_images/code_examples/fifo/rdata_proc.*
:class: width-helper invert-helper
:name: rdata_proc
``rdata`` output after :cmd:ref:`proc`
``rdata`` output after `proc`
The highlighted ``fifo_reader`` block contains an instance of the
:ref:`addr_gen_proc` that we looked at earlier. Notice how the type is shown as
@ -276,7 +276,7 @@ Flattening
~~~~~~~~~~
At this stage of a synthesis flow there are a few other commands we could run.
In :cmd:ref:`synth_ice40` we get these:
In `synth_ice40` we get these:
.. literalinclude:: /cmd/synth_ice40.rst
:language: yoscrypt
@ -286,7 +286,7 @@ In :cmd:ref:`synth_ice40` we get these:
:name: synth_flatten
:caption: ``flatten`` section
First off is :cmd:ref:`flatten`. Flattening the design like this can allow for
First off is `flatten`. Flattening the design like this can allow for
optimizations between modules which would otherwise be missed. Let's run
:yoscrypt:`flatten;;` on our design.
@ -310,19 +310,19 @@ The pieces have moved around a bit, but we can see :ref:`addr_gen_proc` from
earlier has replaced the ``fifo_reader`` block in :ref:`rdata_proc`. We can
also see that the ``addr`` output has been renamed to :file:`fifo_reader.addr`
and merged with the ``raddr`` wire feeding into the `$memrd` cell. This wire
merging happened during the call to :cmd:ref:`clean` which we can see in the
merging happened during the call to `clean` which we can see in the
:ref:`flat_clean`.
.. note::
:cmd:ref:`flatten` and :cmd:ref:`clean` would normally be combined into a
`flatten` and `clean` would normally be combined into a
single :yoterm:`yosys> flatten;;` output, but they appear separately here as
a side effect of using :cmd:ref:`echo` for generating the terminal style
a side effect of using `echo` for generating the terminal style
output.
Depending on the target architecture, this stage of synthesis might also see
commands such as :cmd:ref:`tribuf` with the ``-logic`` option and
:cmd:ref:`deminout`. These remove tristate and inout constructs respectively,
commands such as `tribuf` with the ``-logic`` option and
`deminout`. These remove tristate and inout constructs respectively,
replacing them with logic suitable for mapping to an FPGA. Since we do not have
any such constructs in our example running these commands does not change our
design.
@ -342,7 +342,7 @@ optimizations and other transformations done previously.
.. note::
While the iCE40 flow had a :ref:`synth_flatten` and put :cmd:ref:`proc` in
While the iCE40 flow had a :ref:`synth_flatten` and put `proc` in
the :ref:`synth_begin`, some synthesis scripts will instead include these in
this section.
@ -359,8 +359,8 @@ In the iCE40 flow, we start with the following commands:
:caption: ``coarse`` section (part 1)
:name: synth_coarse1
We've already come across :cmd:ref:`opt_expr`, and :cmd:ref:`opt_clean` is the
same as :cmd:ref:`clean` but with more verbose output. The :cmd:ref:`check`
We've already come across `opt_expr`, and `opt_clean` is the
same as `clean` but with more verbose output. The `check`
pass identifies a few obvious problems which will cause errors later. Calling
it here lets us fail faster rather than wasting time on something we know is
impossible.
@ -368,13 +368,13 @@ impossible.
Next up is :yoscrypt:`opt -nodffe -nosdff` performing a set of simple
optimizations on the design. This command also ensures that only a specific
subset of FF types are included, in preparation for the next command:
:doc:`/cmd/fsm`. Both :cmd:ref:`opt` and :cmd:ref:`fsm` are macro commands
:doc:`/cmd/fsm`. Both `opt` and `fsm` are macro commands
which are explored in more detail in :doc:`/using_yosys/synthesis/opt` and
:doc:`/using_yosys/synthesis/fsm` respectively.
Up until now, the data path for ``rdata`` has remained the same since
:ref:`rdata_flat`. However the next call to :cmd:ref:`opt` does cause a change.
Specifically, the call to :cmd:ref:`opt_dff` without the ``-nodffe -nosdff``
:ref:`rdata_flat`. However the next call to `opt` does cause a change.
Specifically, the call to `opt_dff` without the ``-nodffe -nosdff``
options is able to fold one of the `$mux` cells into the `$adff` to form an
`$adffe` cell; highlighted below:
@ -382,13 +382,13 @@ options is able to fold one of the `$mux` cells into the `$adff` to form an
:language: doscon
:start-at: yosys> opt_dff
:end-before: yosys> select
:caption: output of :cmd:ref:`opt_dff`
:caption: output of `opt_dff`
.. figure:: /_images/code_examples/fifo/rdata_adffe.*
:class: width-helper invert-helper
:name: rdata_adffe
``rdata`` output after :cmd:ref:`opt_dff`
``rdata`` output after `opt_dff`
.. seealso:: Advanced usage docs for
@ -414,26 +414,26 @@ First up is :doc:`/cmd/wreduce`. If we run this we get the following:
:language: doscon
:start-at: yosys> wreduce
:end-before: yosys> select
:caption: output of :cmd:ref:`wreduce`
:caption: output of `wreduce`
Looking at the data path for ``rdata``, the most relevant of these width
reductions are the ones affecting ``fifo.$flatten\fifo_reader.$add$fifo.v``.
That is the `$add` cell incrementing the fifo_reader address. We can look at
the schematic and see the output of that cell has now changed.
.. todo:: pending bugfix in :cmd:ref:`wreduce` and/or :cmd:ref:`opt_clean`
.. todo:: pending bugfix in `wreduce` and/or `opt_clean`
.. figure:: /_images/code_examples/fifo/rdata_wreduce.*
:class: width-helper invert-helper
:name: rdata_wreduce
``rdata`` output after :cmd:ref:`wreduce`
``rdata`` output after `wreduce`
The next two (new) commands are :doc:`/cmd/peepopt` and :doc:`/cmd/share`.
Neither of these affect our design, and they're explored in more detail in
:doc:`/using_yosys/synthesis/opt`, so let's skip over them. :yoscrypt:`techmap
-map +/cmp2lut.v -D LUT_WIDTH=4` optimizes certain comparison operators by
converting them to LUTs instead. The usage of :cmd:ref:`techmap` is explored
converting them to LUTs instead. The usage of `techmap` is explored
more in :doc:`/using_yosys/synthesis/techmap_synth`.
Our next command to run is
@ -443,15 +443,15 @@ Our next command to run is
:language: doscon
:start-at: yosys> memory_dff
:end-before: yosys> select
:caption: output of :cmd:ref:`memory_dff`
:caption: output of `memory_dff`
.. figure:: /_images/code_examples/fifo/rdata_memrdv2.*
:class: width-helper invert-helper
:name: rdata_memrdv2
``rdata`` output after :cmd:ref:`memory_dff`
``rdata`` output after `memory_dff`
As the title suggests, :cmd:ref:`memory_dff` has merged the output `$dff` into
As the title suggests, `memory_dff` has merged the output `$dff` into
the `$memrd` cell and converted it to a `$memrd_v2` (highlighted). This has
also connected the ``CLK`` port to the ``clk`` input as it is now a synchronous
memory read with appropriate enable (``EN=1'1``) and reset (``ARST=1'0`` and
@ -466,7 +466,7 @@ memory read with appropriate enable (``EN=1'1``) and reset (``ARST=1'0`` and
Part 3
^^^^^^
The third part of the :cmd:ref:`synth_ice40` flow is a series of commands for
The third part of the `synth_ice40` flow is a series of commands for
mapping to DSPs. By default, the iCE40 flow will not map to the hardware DSP
blocks and will only be performed if called with the ``-dsp`` flag:
:yoscrypt:`synth_ice40 -dsp`. While our example has nothing that could be
@ -483,24 +483,24 @@ what they do.
:yoscrypt:`wreduce t:$mul` performs width reduction again, this time targetting
only cells of type `$mul`. :yoscrypt:`techmap -map +/mul2dsp.v -map
+/ice40/dsp_map.v ... -D DSP_NAME=$__MUL16X16` uses :cmd:ref:`techmap` to map
+/ice40/dsp_map.v ... -D DSP_NAME=$__MUL16X16` uses `techmap` to map
`$mul` cells to ``$__MUL16X16`` which are, in turn, mapped to the iCE40
``SB_MAC16``. Any multipliers which aren't compatible with conversion to
``$__MUL16X16`` are relabelled to ``$__soft_mul`` before :cmd:ref:`chtype`
``$__MUL16X16`` are relabelled to ``$__soft_mul`` before `chtype`
changes them back to `$mul`.
During the mul2dsp conversion, some of the intermediate signals are marked with
the attribute ``mul2dsp``. By calling :yoscrypt:`select a:mul2dsp` we restrict
the following commands to only operate on the cells and wires used for these
signals. :cmd:ref:`setattr` removes the now unnecessary ``mul2dsp`` attribute.
:cmd:ref:`opt_expr` we've already come across for const folding and simple
signals. `setattr` removes the now unnecessary ``mul2dsp`` attribute.
`opt_expr` we've already come across for const folding and simple
expression rewriting, the ``-fine`` option just enables more fine-grain
optimizations. Then we perform width reduction a final time and clear the
selection.
.. todo:: ``ice40_dsp`` is pmgen
Finally we have :cmd:ref:`ice40_dsp`: similar to the :cmd:ref:`memory_dff`
Finally we have `ice40_dsp`: similar to the `memory_dff`
command we saw in the previous section, this merges any surrounding registers
into the ``SB_MAC16`` cell. This includes not just the input/output registers,
but also pipeline registers and even a post-adder where applicable: turning a
@ -525,40 +525,40 @@ That brings us to the fourth and final part for the iCE40 synthesis flow:
Where before each type of arithmetic operation had its own cell, e.g. `$add`,
we now want to extract these into `$alu` and `$macc` cells which can help
identify opportunities for reusing logic. We do this by running
:cmd:ref:`alumacc`, which we can see produce the following changes in our
`alumacc`, which we can see produce the following changes in our
example design:
.. literalinclude:: /code_examples/fifo/fifo.out
:language: doscon
:start-at: yosys> alumacc
:end-before: yosys> select
:caption: output of :cmd:ref:`alumacc`
:caption: output of `alumacc`
.. figure:: /_images/code_examples/fifo/rdata_alumacc.*
:class: width-helper invert-helper
:name: rdata_alumacc
``rdata`` output after :cmd:ref:`alumacc`
``rdata`` output after `alumacc`
Once these cells have been inserted, the call to :cmd:ref:`opt` can combine
Once these cells have been inserted, the call to `opt` can combine
cells which are now identical but may have been missed due to e.g. the
difference between `$add` and `$sub`.
The other new command in this part is :doc:`/cmd/memory`. :cmd:ref:`memory` is
The other new command in this part is :doc:`/cmd/memory`. `memory` is
another macro command which we examine in more detail in
:doc:`/using_yosys/synthesis/memory`. For this document, let us focus just on
the step most relevant to our example: :cmd:ref:`memory_collect`. Up until this
the step most relevant to our example: `memory_collect`. Up until this
point, our memory reads and our memory writes have been totally disjoint cells;
operating on the same memory only in the abstract. :cmd:ref:`memory_collect`
operating on the same memory only in the abstract. `memory_collect`
combines all of the reads and writes for a memory block into a single cell.
.. figure:: /_images/code_examples/fifo/rdata_coarse.*
:class: width-helper invert-helper
:name: rdata_coarse
``rdata`` output after :cmd:ref:`memory_collect`
``rdata`` output after `memory_collect`
Looking at the schematic after running :cmd:ref:`memory_collect` we see that our
Looking at the schematic after running `memory_collect` we see that our
`$memrd_v2` cell has been replaced with a `$mem_v2` cell named ``data``, the
same name that we used in :ref:`fifo-v`. Where before we had a single set of
signals for address and enable, we now have one set for reading (``RD_*``) and
@ -592,8 +592,8 @@ If you skipped calling :yoscrypt:`read_verilog -D ICE40_HX -lib -specify
Memory blocks
^^^^^^^^^^^^^
Mapping to hard memory blocks uses a combination of :cmd:ref:`memory_libmap` and
:cmd:ref:`techmap`.
Mapping to hard memory blocks uses a combination of `memory_libmap` and
`techmap`.
.. literalinclude:: /cmd/synth_ice40.rst
:language: yoscrypt
@ -619,7 +619,7 @@ As a result, extra logic is added so that the generated circuit matches the
behaviour of the verilog. :ref:`no_rw_check` describes how we could change our
verilog to match our hardware instead.
If we run :cmd:ref:`memory_libmap` under the :cmd:ref:`debug` command we can see
If we run `memory_libmap` under the `debug` command we can see
candidates which were identified for mapping, along with the costs of each and
what logic requires emulation.
@ -628,9 +628,9 @@ what logic requires emulation.
:lines: 2, 6-
The ``$__ICE40_RAM4K_`` cell is defined in the file |techlibs/ice40/brams.txt|_,
with the mapping to ``SB_RAM40_4K`` done by :cmd:ref:`techmap` using
with the mapping to ``SB_RAM40_4K`` done by `techmap` using
|techlibs/ice40/brams_map.v|_. Any leftover memory cells are then converted
into flip flops (the ``logic fallback``) with :cmd:ref:`memory_map`.
into flip flops (the ``logic fallback``) with `memory_map`.
.. |techlibs/ice40/brams.txt| replace:: :file:`techlibs/ice40/brams.txt`
.. _techlibs/ice40/brams.txt: https://github.com/YosysHQ/yosys/tree/main/techlibs/ice40/brams.txt
@ -654,7 +654,7 @@ into flip flops (the ``logic fallback``) with :cmd:ref:`memory_map`.
.. note::
The visual clutter on the ``RDATA`` output port (highlighted) is an
unfortunate side effect of :cmd:ref:`opt_clean` on the swizzled data bits. In
unfortunate side effect of `opt_clean` on the swizzled data bits. In
connecting the `$mux` input port directly to ``RDATA`` to reduce the number
of wires, the ``$techmap579\data.0.0.RDATA`` wire becomes more visually
complex.
@ -667,7 +667,7 @@ into flip flops (the ``logic fallback``) with :cmd:ref:`memory_map`.
Arithmetic
^^^^^^^^^^
Uses :cmd:ref:`techmap` to map basic arithmetic logic to hardware. This sees
Uses `techmap` to map basic arithmetic logic to hardware. This sees
somewhat of an explosion in cells as multi-bit :cell:ref:`$mux` and `$adffe` are
replaced with single-bit `$_MUX_` and `$_DFFE_PP0P_` cells, while the
:cell:ref:`$alu` is replaced with primitive `$_OR_` and `$_NOT_` gates and a
@ -693,11 +693,11 @@ replaced with single-bit `$_MUX_` and `$_DFFE_PP0P_` cells, while the
Flip-flops
^^^^^^^^^^
Convert FFs to the types supported in hardware with :cmd:ref:`dfflegalize`, and
then use :cmd:ref:`techmap` to map them. In our example, this converts the
Convert FFs to the types supported in hardware with `dfflegalize`, and
then use `techmap` to map them. In our example, this converts the
`$_DFFE_PP0P_` cells to ``SB_DFFER``.
We also run :cmd:ref:`simplemap` here to convert any remaining cells which could
We also run `simplemap` here to convert any remaining cells which could
not be mapped to hardware into gate-level primitives. This includes optimizing
`$_MUX_` cells where one of the inputs is a constant ``1'0``, replacing it
instead with an `$_AND_` cell.
@ -722,9 +722,9 @@ instead with an `$_AND_` cell.
LUTs
^^^^
:cmd:ref:`abc` and :cmd:ref:`techmap` are used to map LUTs; converting primitive
`abc` and `techmap` are used to map LUTs; converting primitive
cell types to use `$lut` and ``SB_CARRY`` cells. Note that the iCE40 flow
uses :cmd:ref:`abc9` rather than :cmd:ref:`abc`. For more on what these do, and
uses `abc9` rather than `abc`. For more on what these do, and
what the difference between these two commands are, refer to
:doc:`/using_yosys/synthesis/abc`.
@ -742,7 +742,7 @@ what the difference between these two commands are, refer to
``rdata`` output after :ref:`map_luts`
Finally we use :cmd:ref:`techmap` to map the generic `$lut` cells to iCE40
Finally we use `techmap` to map the generic `$lut` cells to iCE40
``SB_LUT4`` cells.
.. literalinclude:: /cmd/synth_ice40.rst
@ -769,12 +769,12 @@ Other cells
The following commands may also be used for mapping other cells:
:cmd:ref:`hilomap`
`hilomap`
Some architectures require special driver cells for driving a constant hi or
lo value. This command replaces simple constants with instances of such
driver cells.
:cmd:ref:`iopadmap`
`iopadmap`
Top-level input/outputs must usually be implemented using special I/O-pad
cells. This command inserts such cells to the design.
@ -801,27 +801,27 @@ The new commands here are:
- :doc:`/cmd/stat`, and
- :doc:`/cmd/blackbox`.
The output from :cmd:ref:`stat` is useful for checking resource utilization;
The output from `stat` is useful for checking resource utilization;
providing a list of cells used in the design and the number of each, as well as
the number of other resources used such as wires and processes. For this
design, the final call to :cmd:ref:`stat` should look something like the
design, the final call to `stat` should look something like the
following:
.. literalinclude:: /code_examples/fifo/fifo.stat
:language: doscon
:start-at: yosys> stat -top fifo
Note that the :yoscrypt:`-top fifo` here is optional. :cmd:ref:`stat` will
Note that the :yoscrypt:`-top fifo` here is optional. `stat` will
automatically use the module with the ``top`` attribute set, which ``fifo`` was
when we called :cmd:ref:`hierarchy`. If no module is marked ``top``, then stats
when we called `hierarchy`. If no module is marked ``top``, then stats
will be shown for each module selected.
The :cmd:ref:`stat` output is also useful as a kind of sanity-check: Since we
have already run :cmd:ref:`proc`, we wouldn't expect there to be any processes.
The `stat` output is also useful as a kind of sanity-check: Since we
have already run `proc`, we wouldn't expect there to be any processes.
We also expect ``data`` to use hard memory; if instead of an ``SB_RAM40_4K`` saw
a high number of flip-flops being used we might suspect something was wrong.
If we instead called :cmd:ref:`stat` immediately after :yoscrypt:`read_verilog
If we instead called `stat` immediately after :yoscrypt:`read_verilog
fifo.v` we would see something very different:
.. literalinclude:: /code_examples/fifo/fifo.stat
@ -845,7 +845,7 @@ The iCE40 synthesis flow has the following output modes available:
As an example, if we called :yoscrypt:`synth_ice40 -top fifo -json fifo.json`,
our synthesized ``fifo`` design will be output as :file:`fifo.json`. We can
then read the design back into Yosys with :cmd:ref:`read_json`, but make sure
then read the design back into Yosys with `read_json`, but make sure
you use :yoscrypt:`design -reset` or open a new interactive terminal first. The
JSON output we get can also be loaded into `nextpnr`_ to do place and route; but
that is beyond the scope of this documentation.

6
docs/source/getting_started/installation.rst
View File

@ -88,7 +88,7 @@ A C++ compiler with C++17 support is required as well as some standard tools
such as GNU Flex, GNU Bison, Make and Python. Some additional tools: readline,
libffi, Tcl and zlib; are optional but enabled by default (see
:makevar:`ENABLE_*` settings in Makefile). Graphviz and Xdot are used by the
:cmd:ref:`show` command to display schematics.
`show` command to display schematics.
Installing all prerequisites for Ubuntu 20.04:
@ -185,8 +185,8 @@ directories:
``passes/``
This directory contains a subdirectory for each pass or group of passes. For
example as of this writing the directory :file:`passes/hierarchy/` contains the
code for three passes: :cmd:ref:`hierarchy`, :cmd:ref:`submod`, and
:cmd:ref:`uniquify`.
code for three passes: `hierarchy`, `submod`, and
`uniquify`.
``techlibs/``
This directory contains simulation models and standard implementations for

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

@ -7,8 +7,7 @@ file format and how you can make your own synthesis scripts.
Yosys script files typically use the :file:`.ys` extension and contain a set of
commands for Yosys to run sequentially. These commands are the same ones we
were using on the previous page like :cmd:ref:`read_verilog` and
:cmd:ref:`hierarchy`.
were using on the previous page like `read_verilog` and `hierarchy`.
Script parsing
~~~~~~~~~~~~~~
@ -39,9 +38,9 @@ Another special character that can be used in Yosys scripts is the bang ``!``.
Anything after the bang will be executed as a shell command. This can only be
terminated with a new line. Any semicolons, hashes, or other special characters
will be passed to the shell. If an error code is returned from the shell it
will be raised by Yosys. :cmd:ref:`exec` provides a much more flexible way of
executing commands, allowing the output to be logged and more control over when
to generate errors.
will be raised by Yosys. `exec` provides a much more flexible way of executing
commands, allowing the output to be logged and more control over when to
generate errors.
The synthesis starter script
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@ -62,7 +61,7 @@ already, let's take a look at some of those script files now.
:caption: A section of :file:`fifo.ys`, generating the images used for :ref:`addr_gen_example`
:name: fifo-ys
The first command there, :yoscrypt:`echo on`, uses :cmd:ref:`echo` to enable
The first command there, :yoscrypt:`echo on`, uses `echo` to enable
command echoes on. This is how we generated the code listing for
:ref:`hierarchy_output`. Turning command echoes on prints the ``yosys>
hierarchy -top addr_gen`` line, making the output look the same as if it were an
@ -70,15 +69,15 @@ interactive terminal. :yoscrypt:`hierarchy -top addr_gen` is of course the
command we were demonstrating, including the output text and an image of the
design schematic after running it.
We briefly touched on :cmd:ref:`select` when it came up in
:cmd:ref:`synth_ice40`, but let's look at it more now.
We briefly touched on `select` when it came up in
`synth_ice40`, but let's look at it more now.
.. _select_intro:
Selections intro
^^^^^^^^^^^^^^^^
The :cmd:ref:`select` command is used to modify and view the list of selected
The `select` command is used to modify and view the list of selected
objects:
.. literalinclude:: /code_examples/fifo/fifo.out
@ -119,7 +118,7 @@ statement.
Many commands also support an optional ``[selection]`` argument which can be
used to override the currently selected objects. We could, for example, call
:yoscrypt:`clean addr_gen` to have :cmd:ref:`clean` operate on *just* the
:yoscrypt:`clean addr_gen` to have `clean` operate on *just* the
``addr_gen`` module.
Detailed documentation of the select framework can be found under
@ -131,9 +130,9 @@ Detailed documentation of the select framework can be found under
Displaying schematics
^^^^^^^^^^^^^^^^^^^^^
While the :cmd:ref:`select` command is very useful, sometimes nothing beats
being able to see a design for yourself. This is where :cmd:ref:`show` comes
in. Note that this document is just an introduction to the :cmd:ref:`show`
While the `select` command is very useful, sometimes nothing beats
being able to see a design for yourself. This is where `show` comes
in. Note that this document is just an introduction to the `show`
command, only covering the basics. For more information, including a guide on
what the different symbols represent, see :ref:`interactive_show` and the
:doc:`/using_yosys/more_scripting/interactive_investigation` page.
@ -142,11 +141,11 @@ what the different symbols represent, see :ref:`interactive_show` and the
:class: width-helper invert-helper
:name: addr_gen_show
Calling :yoscrypt:`show addr_gen` after :cmd:ref:`hierarchy`
Calling :yoscrypt:`show addr_gen` after `hierarchy`
.. note::
The :cmd:ref:`show` command requires a working installation of `GraphViz`_
The `show` command requires a working installation of `GraphViz`_
and `xdot`_ for displaying the actual circuit diagrams.
.. _GraphViz: http://www.graphviz.org/
@ -161,7 +160,7 @@ we see the following:
:start-at: -prefix addr_gen_show
:end-before: yosys> show
Calling :cmd:ref:`show` with :yoscrypt:`-format dot` tells it we want to output
Calling `show` with :yoscrypt:`-format dot` tells it we want to output
a :file:`.dot` file rather than opening it for display. The :yoscrypt:`-prefix
addr_gen_show` option indicates we want the file to be called
:file:`addr_gen_show.{*}`. Remember, we do this in :file:`fifo.ys` because we
@ -186,7 +185,7 @@ That last parameter doesn't have to be a module name, it can be any valid
selection string. Remember when we :ref:`assigned a name to a
selection<select_new_cells>` and called it ``new_cells``? We saw in the
:yoscrypt:`select -list` output that it contained two cells, an `$add` and an
`$eq`. We can call :cmd:ref:`show` on that selection just as easily:
`$eq`. We can call `show` on that selection just as easily:
.. figure:: /_images/code_examples/fifo/new_cells_show.*
:class: width-helper invert-helper
@ -208,10 +207,10 @@ the two ``PROC`` blocks. To achieve this highlight, we make use of the
Calling :yoscrypt:`show -color maroon3 @new_cells -color cornflowerblue p:* -notitle`
As described in the the :cmd:ref:`help` output for :cmd:ref:`show` (or by
clicking on the :cmd:ref:`show` link), colors are specified as :yoscrypt:`-color
As described in the the `help` output for `show` (or by
clicking on the `show` link), colors are specified as :yoscrypt:`-color
<color> <object>`. Color names for the ``<color>`` portion can be found on the
`GraphViz color docs`_. Unlike the final :cmd:ref:`show` parameter which can
`GraphViz color docs`_. Unlike the final `show` parameter which can
have be any selection string, the ``<object>`` part must be a single selection
expression or named selection. That means while we can use ``@new_cells``, we
couldn't use ``t:$eq t:$add``. In general, if a command lists ``[selection]``
@ -221,7 +220,7 @@ expression instead.
.. _GraphViz color docs: https://graphviz.org/doc/info/colors
For all of the options available to :cmd:ref:`show`, check the command reference
For all of the options available to `show`, check the command reference
at :doc:`/cmd/show`.
.. seealso:: :ref:`interactive_show` on the

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:

6
docs/source/yosys_internals/extending_yosys/extensions.rst
View File

@ -35,7 +35,7 @@ about the internal data storage format used in Yosys and the classes that it
provides.
This document will focus on the much simpler version of RTLIL left after the
commands :cmd:ref:`proc` and :cmd:ref:`memory` (or :yoscrypt:`memory -nomap`):
commands `proc` and `memory` (or :yoscrypt:`memory -nomap`):
.. figure:: /_images/internals/simplified_rtlil.*
:class: width-helper invert-helper
@ -56,7 +56,7 @@ It is possible to only work on this simpler version:
}
When trying to understand what a command does, creating a small test case to
look at the output of :cmd:ref:`dump` and :cmd:ref:`show` before and after the
look at the output of `dump` and `show` before and after the
command has been executed can be helpful.
:doc:`/using_yosys/more_scripting/selections` has more information on using
these commands.
@ -152,7 +152,7 @@ Most commands modify existing modules, not create new ones.
When modifying existing modules, stick to the following DOs and DON'Ts:
- Do not remove wires. Simply disconnect them and let a successive
:cmd:ref:`clean` command worry about removing it.
`clean` command worry about removing it.
- Use ``module->fixup_ports()`` after changing the ``port_*`` properties of
wires.
- You can safely remove cells or change the ``connections`` property of a cell,

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

@ -600,15 +600,15 @@ The proc pass
The ProcessGenerator converts a behavioural model in AST representation to a
behavioural model in ``RTLIL::Process`` representation. The actual conversion
from a behavioural model to an RTL representation is performed by the
:cmd:ref:`proc` pass and the passes it launches:
`proc` pass and the passes it launches:
- | :cmd:ref:`proc_clean` and :cmd:ref:`proc_rmdead`
- | `proc_clean` and `proc_rmdead`
| These two passes just clean up the ``RTLIL::Process`` structure. The
:cmd:ref:`proc_clean` pass removes empty parts (eg. empty assignments) from
the process and :cmd:ref:`proc_rmdead` detects and removes unreachable
`proc_clean` pass removes empty parts (eg. empty assignments) from
the process and `proc_rmdead` detects and removes unreachable
branches from the process's decision trees.
- | :cmd:ref:`proc_arst`
- | `proc_arst`
| This pass detects processes that describe d-type flip-flops with
asynchronous resets and rewrites the process to better reflect what they
are modelling: Before this pass, an asynchronous reset has two
@ -616,21 +616,21 @@ from a behavioural model to an RTL representation is performed by the
reset path. After this pass the sync rule for the reset is level-sensitive
and the top-level ``RTLIL::SwitchRule`` has been removed.
- | :cmd:ref:`proc_mux`
- | `proc_mux`
| This pass converts the ``RTLIL::CaseRule``/\ ``RTLIL::SwitchRule``-tree to a
tree of multiplexers per written signal. After this, the ``RTLIL::Process``
structure only contains the ``RTLIL::SyncRule`` s that describe the output
registers.
- | :cmd:ref:`proc_dff`
- | `proc_dff`
| This pass replaces the ``RTLIL::SyncRule``\ s to d-type flip-flops (with
asynchronous resets if necessary).
- | :cmd:ref:`proc_dff`
- | `proc_dff`
| This pass replaces the ``RTLIL::MemWriteAction``\ s with `$memwr` cells.
- | :cmd:ref:`proc_clean`
| A final call to :cmd:ref:`proc_clean` removes the now empty
- | `proc_clean`
| A final call to `proc_clean` removes the now empty
``RTLIL::Process`` objects.
Performing these last processing steps in passes instead of in the Verilog

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

@ -258,7 +258,7 @@ additional two parameters:
``\ARST_VALUE``
The state of ``\Q`` will be set to this value when the reset is active.
Usually these cells are generated by the :cmd:ref:`proc` pass using the
Usually these cells are generated by the `proc` pass using the
information in the designs RTLIL::Process objects.
D-type flip-flops with synchronous reset are represented by `$sdff` cells. As
@ -472,7 +472,7 @@ synthesis to succeed.
initialization conflict.
The HDL frontend models a memory using ``RTLIL::Memory`` objects and
asynchronous `$memrd_v2` and `$memwr_v2` cells. The :cmd:ref:`memory` pass
asynchronous `$memrd_v2` and `$memwr_v2` cells. The `memory` pass
(i.e. its various sub-passes) migrates `$dff` cells into the `$memrd_v2` and
`$memwr_v2` cells making them synchronous, then converts them to a single
`$mem_v2` cell and (optionally) maps this cell type to `$dff` cells for the
@ -604,14 +604,14 @@ The `$mem_v2` cell has the following ports:
This input is ``\WR_PORTS*\WIDTH`` bits wide, containing all data
signals for the write ports.
The :cmd:ref:`memory_collect` pass can be used to convert discrete
The `memory_collect` pass can be used to convert discrete
`$memrd_v2`, `$memwr_v2`, and `$meminit_v2` cells belonging to the same
memory to a single `$mem_v2` cell, whereas the :cmd:ref:`memory_unpack` pass
performs the inverse operation. The :cmd:ref:`memory_dff` pass can combine
memory to a single `$mem_v2` cell, whereas the `memory_unpack` pass
performs the inverse operation. The `memory_dff` pass can combine
asynchronous memory ports that are fed by or feeding registers into synchronous
memory ports. The :cmd:ref:`memory_bram` pass can be used to recognize
memory ports. The `memory_bram` pass can be used to recognize
`$mem_v2` cells that can be implemented with a block RAM resource on an FPGA.
The :cmd:ref:`memory_map` pass can be used to implement `$mem_v2` cells as
The `memory_map` pass can be used to implement `$mem_v2` cells as
basic logic: word-wide DFFs and address decoders.
Finite state machines

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

@ -76,7 +76,7 @@ This has three advantages:
- Second, the information about which identifiers were originally provided by
the user is always available which can help guide some optimizations. For
example, :cmd:ref:`opt_clean` tries to preserve signals with a user-provided
example, `opt_clean` tries to preserve signals with a user-provided
name but doesn't hesitate to delete signals that have auto-generated names
when they just duplicate other signals. Note that this can be overridden
with the ``-purge`` option to also delete internal nets with user-provided
@ -320,7 +320,7 @@ trees before further processing them.
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
the :cmd:ref:`proc_arst` pass. This pass transforms the above example to the
the `proc_arst` pass. This pass transforms the above example to the
following ``RTLIL::Process``:
.. code:: RTLIL

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

@ -1,7 +1,7 @@
Techmap by example
------------------
As a quick recap, the :cmd:ref:`techmap` command replaces cells in the design
As a quick recap, the `techmap` command replaces cells in the design
with implementations given as Verilog code (called "map files"). It can replace
Yosys' internal cell types (such as `$or`) as well as user-defined cell types.
@ -87,14 +87,14 @@ Scripting in map modules
- You can even call techmap recursively!
- Example use-cases:
- Using always blocks in map module: call :cmd:ref:`proc`
- Perform expensive optimizations (such as :cmd:ref:`freduce`) on cells
- Using always blocks in map module: call `proc`
- Perform expensive optimizations (such as `freduce`) on cells
where this is known to work well.
- Interacting with custom commands.
.. note:: PROTIP:
Commands such as :cmd:ref:`shell`, ``show -pause``, and :cmd:ref:`dump` can
Commands such as `shell`, ``show -pause``, and `dump` can
be used in the ``_TECHMAP_DO_*`` scripts for debugging map modules.
Example: