mirror of
https://github.com/YosysHQ/yosys
synced 2025-10-31 11:42:30 +00:00
422 lines
16 KiB
ReStructuredText
422 lines
16 KiB
ReStructuredText
Selections
|
|
----------
|
|
|
|
.. role:: yoscrypt(code)
|
|
:language: yoscrypt
|
|
|
|
The selection framework
|
|
~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
.. todo:: reduce overlap with :doc:`/getting_started/scripting_intro` select section
|
|
|
|
The `select` command can be used to create a selection for subsequent commands.
|
|
For example:
|
|
|
|
.. code:: yoscrypt
|
|
|
|
select foobar # select the module foobar
|
|
delete # delete selected objects
|
|
|
|
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.
|
|
|
|
The command :yoscrypt:`select -clear` can be used to reset the selection to the
|
|
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 `select` command to evaluate
|
|
additional arguments and use the resulting selection instead of the selection
|
|
created by the last `select` command.
|
|
|
|
For example, the command `delete` will delete everything in the current
|
|
selection; while :yoscrypt:`delete foobar` will only delete the module foobar.
|
|
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 `show`
|
|
command to visually demonstrate the effect of selections. For a more
|
|
detailed look at this command, refer to :ref:`interactive_show`.
|
|
|
|
How to make a selection
|
|
~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
Selection by object name
|
|
^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
The easiest way to select objects is by object name. This is usually only done
|
|
in synthesis scripts that are hand-tailored for a specific design.
|
|
|
|
.. code:: yoscrypt
|
|
|
|
select foobar # select module foobar
|
|
select foo* # select all modules whose names start with foo
|
|
select foo*/bar* # select all objects matching bar* from modules matching foo*
|
|
select */clk # select objects named clk from all modules
|
|
|
|
Module and design context
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
Commands can be executed in *module/* or *design/* context. Until now, all
|
|
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
|
|
module are selected without the ``<module_name>/`` prefix. For example:
|
|
|
|
.. code:: yoscrypt
|
|
|
|
cd foo # switch to module foo
|
|
delete bar # delete object foo/bar
|
|
|
|
cd mycpu # switch to module mycpu
|
|
dump reg_* # print details on all objects whose names start with reg_
|
|
|
|
cd .. # switch back to design
|
|
|
|
Note: Most synthesis scripts never switch to module context. But it is a very
|
|
powerful tool which we explore more in
|
|
:doc:`/using_yosys/more_scripting/interactive_investigation`.
|
|
|
|
Selecting by object property or type
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
Special patterns can be used to select by object property or type. For example:
|
|
|
|
- select all wires whose names start with ``reg_``: :yoscrypt:`select w:reg_*`
|
|
- select all objects with the attribute ``foobar`` set: :yoscrypt:`select
|
|
a:foobar`
|
|
- select all objects with the attribute ``foobar`` set to 42: :yoscrypt:`select
|
|
a:foobar=42`
|
|
- select all modules with the attribute ``blabla`` set: :yoscrypt:`select
|
|
A:blabla`
|
|
- select all `$add` cells from the module foo: :yoscrypt:`select foo/t:$add`
|
|
|
|
A complete list of pattern expressions can be found in :cmd:title:`select`.
|
|
|
|
Operations on selections
|
|
~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
Combining selections
|
|
^^^^^^^^^^^^^^^^^^^^
|
|
|
|
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 :yoscrypt:`select
|
|
t:$add a:foo` will select all `$add` cells and all objects with the ``foo``
|
|
attribute set:
|
|
|
|
.. literalinclude:: /code_examples/selections/foobaraddsub.v
|
|
:caption: Test module for operations on selections
|
|
:name: foobaraddsub
|
|
:language: verilog
|
|
|
|
.. code-block::
|
|
:caption: Output for command ``select t:$add a:foo -list`` on :numref:`foobaraddsub`
|
|
|
|
yosys> select t:$add a:foo -list
|
|
foobaraddsub/$add$foobaraddsub.v:6$3
|
|
foobaraddsub/$sub$foobaraddsub.v:5$2
|
|
foobaraddsub/$add$foobaraddsub.v:4$1
|
|
|
|
In many cases simply adding more and more stuff to the selection is an
|
|
ineffective way of selecting the interesting part of the design. Special
|
|
arguments can be used to combine the elements on the stack. For example the
|
|
``%i`` arguments pops the last two elements from the stack, intersects them, and
|
|
pushes the result back on the stack. So :yoscrypt:`select t:$add a:foo %i` will
|
|
select all `$add` cells that have the ``foo`` attribute set:
|
|
|
|
.. code-block::
|
|
:caption: Output for command ``select t:$add a:foo %i -list`` on :numref:`foobaraddsub`
|
|
|
|
yosys> select t:$add a:foo %i -list
|
|
foobaraddsub/$add$foobaraddsub.v:4$1
|
|
|
|
Some of the special ``%``-codes:
|
|
|
|
- ``%u``: union of top two elements on stack -- pop 2, push 1
|
|
- ``%d``: difference of top two elements on stack -- pop 2, push 1
|
|
- ``%i``: intersection of top two elements on stack -- pop 2, push 1
|
|
- ``%n``: inverse of top element on stack -- pop 1, push 1
|
|
|
|
See :cmd:title:`select` for the full list.
|
|
|
|
Expanding selections
|
|
^^^^^^^^^^^^^^^^^^^^
|
|
|
|
:numref:`sumprod` uses the Yosys non-standard ``{... *}`` syntax to set the
|
|
attribute ``sumstuff`` on all cells generated by the first assign statement.
|
|
(This works on arbitrary large blocks of Verilog code and can be used to mark
|
|
portions of code for analysis.)
|
|
|
|
.. literalinclude:: /code_examples/selections/sumprod.v
|
|
:caption: Another test module for operations on selections
|
|
:name: sumprod
|
|
:language: verilog
|
|
|
|
Selecting ``a:sumstuff`` in this module will yield the following circuit
|
|
diagram:
|
|
|
|
.. figure:: /_images/code_examples/selections/sumprod_00.*
|
|
:class: width-helper invert-helper
|
|
:name: sumprod_00
|
|
|
|
Output of ``show a:sumstuff`` on :numref:`sumprod`
|
|
|
|
As only the cells themselves are selected, but not the temporary wire ``$1_Y``,
|
|
the two adders are shown as two disjunct parts. This can be very useful for
|
|
global signals like clock and reset signals: just unselect them using a command
|
|
such as :yoscrypt:`select -del clk rst` and each cell using them will get its
|
|
own net label.
|
|
|
|
In this case however we would like to see the cells connected properly. This can
|
|
be achieved using the ``%x`` action, that broadens the selection, i.e. for each
|
|
selected wire it selects all cells connected to the wire and vice versa. So
|
|
:yoscrypt:`show a:sumstuff %x` yields the diagram shown in :numref:`sumprod_01`:
|
|
|
|
.. figure:: /_images/code_examples/selections/sumprod_01.*
|
|
:class: width-helper invert-helper
|
|
:name: sumprod_01
|
|
|
|
Output of ``show a:sumstuff %x`` on :numref:`sumprod`
|
|
|
|
.. _selecting_logic_cones:
|
|
|
|
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 `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
|
|
means, wires only select cells via output ports and cells only select wires via
|
|
input ports.
|
|
|
|
The following sequence of diagrams demonstrates this step-wise expansion:
|
|
|
|
.. figure:: /_images/code_examples/selections/sumprod_02.*
|
|
:class: width-helper invert-helper
|
|
|
|
Output of :yoscrypt:`show prod` on :numref:`sumprod`
|
|
|
|
.. figure:: /_images/code_examples/selections/sumprod_03.*
|
|
:class: width-helper invert-helper
|
|
|
|
Output of :yoscrypt:`show prod %ci` on :numref:`sumprod`
|
|
|
|
.. figure:: /_images/code_examples/selections/sumprod_04.*
|
|
:class: width-helper invert-helper
|
|
|
|
Output of :yoscrypt:`show prod %ci %ci` on :numref:`sumprod`
|
|
|
|
.. figure:: /_images/code_examples/selections/sumprod_05.*
|
|
:class: width-helper invert-helper
|
|
|
|
Output of :yoscrypt:`show prod %ci %ci %ci` on :numref:`sumprod`
|
|
|
|
Notice the subtle difference between :yoscrypt:`show prod %ci` and
|
|
:yoscrypt:`show prod %ci %ci`. Both images show the `$mul` cell driven by some
|
|
inputs ``$3_Y`` and ``c``. However it is not until the second image, 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
|
|
`dump` command instead:
|
|
|
|
.. literalinclude:: /code_examples/selections/sumprod.out
|
|
:language: RTLIL
|
|
:end-at: end
|
|
:caption: Output of :yoscrypt:`dump prod %ci`
|
|
|
|
.. literalinclude:: /code_examples/selections/sumprod.out
|
|
:language: RTLIL
|
|
:start-after: end
|
|
:caption: Output of :yoscrypt:`dump prod %ci %ci`
|
|
|
|
When selecting many levels of logic, repeating ``%ci`` over and over again can
|
|
be a bit dull. So there is a shortcut for that: the number of iterations can be
|
|
appended to the action. So for example the action ``%ci3`` is identical to
|
|
performing the ``%ci`` action three times.
|
|
|
|
The action ``%ci*`` performs the ``%ci`` action over and over again until it has
|
|
no effect anymore.
|
|
|
|
.. _advanced_logic_cones:
|
|
|
|
Advanced logic cone selection
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
In most cases there are certain cell types and/or ports that should not be
|
|
considered for the ``%ci`` action, or we only want to follow certain cell types
|
|
and/or ports. This can be achieved using additional patterns that can be
|
|
appended to the ``%ci`` action.
|
|
|
|
Lets consider :numref:`memdemo_src`. It serves no purpose other than being a
|
|
non-trivial circuit for demonstrating some of the advanced Yosys features. This
|
|
code is available in ``docs/source/code_examples/selections`` of the Yosys
|
|
source repository.
|
|
|
|
.. literalinclude:: /code_examples/selections/memdemo.v
|
|
:caption: :file:`memdemo.v`
|
|
:name: memdemo_src
|
|
:language: verilog
|
|
|
|
The script :file:`memdemo.ys` is used to generate the images included here.
|
|
Let's look at the first section:
|
|
|
|
.. literalinclude:: /code_examples/selections/memdemo.ys
|
|
:caption: Synthesizing :ref:`memdemo_src`
|
|
:name: memdemo_ys
|
|
:language: yoscrypt
|
|
:end-at: opt
|
|
|
|
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 `show` to see the diagram in
|
|
:numref:`memdemo_00`.
|
|
|
|
.. figure:: /_images/code_examples/selections/memdemo_00.*
|
|
:class: width-helper invert-helper
|
|
:name: memdemo_00
|
|
|
|
Complete circuit diagram for the design shown in :numref:`memdemo_src`
|
|
|
|
There's a lot going on there, but maybe we are only interested in the tree of
|
|
multiplexers that select the output value. Let's start by just showing the
|
|
output signal, ``y``, and its immediate predecessors. Remember `Selecting logic
|
|
cones`_ from above, we can use :yoscrypt:`show y %ci2`:
|
|
|
|
.. figure:: /_images/code_examples/selections/memdemo_01.*
|
|
:class: width-helper invert-helper
|
|
:name: memdemo_01
|
|
|
|
Output of :yoscrypt:`show y %ci2`
|
|
|
|
From this we would learn that ``y`` is driven by a `$dff` cell, that ``y`` is
|
|
connected to the output port ``Q``, that the ``clk`` signal goes into the
|
|
``CLK`` input port of the cell, and that the data comes from an auto-generated
|
|
wire into the input ``D`` of the flip-flop cell (indicated by the ``$`` at the
|
|
start of the name). Let's go a bit further now and try :yoscrypt:`show y %ci5`:
|
|
|
|
.. figure:: /_images/code_examples/selections/memdemo_02.*
|
|
:class: width-helper invert-helper
|
|
:name: memdemo_02
|
|
|
|
Output of :yoscrypt:`show y %ci5`
|
|
|
|
That's starting to get a bit messy, so maybe we want to ignore the mux select
|
|
inputs. To add a pattern we add a colon followed by the pattern to the ``%ci``
|
|
action. The pattern itself starts with ``-`` or ``+``, indicating if it is an
|
|
include or exclude pattern, followed by an optional comma separated list of cell
|
|
types, followed by an optional comma separated list of port names in square
|
|
brackets. In this case, we want to exclude the ``S`` port of the `$mux` cell
|
|
type with :yoscrypt:`show y %ci5:-$mux[S]`:
|
|
|
|
.. figure:: /_images/code_examples/selections/memdemo_03.*
|
|
:class: width-helper invert-helper
|
|
:name: memdemo_03
|
|
|
|
Output of :yoscrypt:`show y %ci5:-$mux[S]`
|
|
|
|
We could use a command such as :yoscrypt:`show y %ci2:+$dff[Q,D]
|
|
%ci*:-$mux[S]:-$dff` in which the first ``%ci`` jumps over the initial d-type
|
|
flip-flop and the 2nd action selects the entire input cone without going over
|
|
multiplexer select inputs and flip-flop cells:
|
|
|
|
.. figure:: /_images/code_examples/selections/memdemo_05.*
|
|
:class: width-helper invert-helper
|
|
:name: memdemo_05
|
|
|
|
Output of ``show y %ci2:+$dff[Q,D] %ci*:-$mux[S]:-$dff``
|
|
|
|
Or we could use :yoscrypt:`show y %ci*:-[CLK,S]:+$dff:+$mux` instead, following
|
|
the input cone all the way but only following `$dff` and `$mux` cells, and
|
|
ignoring any ports named ``CLK`` or ``S``:
|
|
|
|
.. TODO:: pending discussion on whether rule ordering is a bug or a feature
|
|
|
|
.. figure:: /_images/code_examples/selections/memdemo_04.*
|
|
:class: width-helper invert-helper
|
|
:name: memdemo_04
|
|
|
|
Output of :yoscrypt:`show y %ci*:-[CLK,S]:+$dff,$mux`
|
|
|
|
Similar to ``%ci`` exists an action ``%co`` to select output cones that accepts
|
|
the same syntax for pattern and repetition. The ``%x`` action mentioned
|
|
previously also accepts this advanced syntax.
|
|
|
|
These actions for traversing the circuit graph, combined with the actions for
|
|
boolean operations such as intersection (``%i``) and difference (``%d``) are
|
|
powerful tools for extracting the relevant portions of the circuit under
|
|
investigation.
|
|
|
|
Again, see :cmd:title:`select` for full documentation of these expressions.
|
|
|
|
Incremental selection
|
|
^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
Sometimes a selection can most easily be described by a series of add/delete
|
|
operations. As mentioned previously, the commands :yoscrypt:`select -add` and
|
|
:yoscrypt:`select -del` respectively add or remove objects from the current
|
|
selection instead of overwriting it.
|
|
|
|
.. code:: yoscrypt
|
|
|
|
select -none # start with an empty selection
|
|
select -add reg_* # select a bunch of objects
|
|
select -del reg_42 # but not this one
|
|
select -add state %ci # and add more stuff
|
|
|
|
Within a select expression the token ``%`` can be used to push the previous
|
|
selection on the stack.
|
|
|
|
.. code:: yoscrypt
|
|
|
|
select t:$add t:$sub # select all $add and $sub cells
|
|
select % %ci % %d # select only the input wires to those cells
|
|
|
|
Storing and recalling selections
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
.. todo:: reflow for not presentation
|
|
|
|
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 `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 `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.
|
|
|
|
Remember that select expressions can also be used directly as arguments to most
|
|
commands. Some commands also accept a single select argument to some options. In
|
|
those cases selection variables must be used to capture more complex selections.
|
|
|
|
Example code from |code_examples/selections|_:
|
|
|
|
.. |code_examples/selections| replace:: :file:`docs/source/code_examples/selections`
|
|
.. _code_examples/selections: https://github.com/YosysHQ/yosys/tree/main/docs/source/code_examples/selections
|
|
|
|
.. literalinclude:: /code_examples/selections/select.v
|
|
:language: verilog
|
|
:caption: :file:`select.v`
|
|
|
|
.. literalinclude:: /code_examples/selections/select.ys
|
|
:language: yoscrypt
|
|
:caption: :file:`select.ys`
|
|
:name: select_ys
|
|
|
|
.. figure:: /_images/code_examples/selections/select.*
|
|
:class: width-helper invert-helper
|
|
|
|
Circuit diagram produced by :numref:`select_ys`
|