riscv
/
yosys
mirror of https://github.com/YosysHQ/yosys.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity
yosys/docs/source/using_yosys/more_scripting/selections.rst

252 lines
8.0 KiB
ReStructuredText
Raw Blame History

Selections
----------
.. TODO: copypaste
Most Yosys commands make use of the "selection framework" of Yosys. It can be
used to apply commands only to part of the design. For example:
.. code:: yoscrypt
delete # will delete the whole design, but
delete foobar # will only delete the module foobar.
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
select -clear # reset selection (select whole design)
See :doc:`/cmd/select`
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 for interactive design investigation.
Selecting by object property or type
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Special patterns can be used to select by object property or type. For example:
.. code:: yoscrypt
select w:reg_* # select all wires whose names start with reg_
select a:foobar # select all objects with the attribute foobar set
select a:foobar=42 # select all objects with the attribute foobar set to 42
select A:blabla # select all modules with the attribute blabla set
select foo/t:$add # select all $add cells from the module foo
A complete list of this pattern expressions can be found in the command
reference to the ``select`` command.
Combining selection
^^^^^^^^^^^^^^^^^^^
When more than one selection expression is used in one statement, then they are
pushed on a stack. The final elements on the stack are combined into a union:
.. code:: yoscrypt
select t:$dff r:WIDTH>1 # all cells of type $dff and/or with a parameter WIDTH > 1
Special ``%``-commands can be used to combine the elements on the stack:
.. code:: yoscrypt
select t:$dff r:WIDTH>1 %i # all cells of type $dff *AND* with a parameter WIDTH > 1
Examples for ``%``-codes (see :doc:`/cmd/select` for full list):
- ``%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
Expanding selections
^^^^^^^^^^^^^^^^^^^^
Selections of cells and wires can be expanded along connections using
``%``-codes for selecting input cones (``%ci``), output cones (``%co``), or
both (``%x``).
.. code:: yoscrypt
# select all wires that are inputs to $add cells
select t:$add %ci w:* %i
Additional constraints such as port names can be specified.
.. code:: yoscrypt
# select all wires that connect a "Q" output with a "D" input
select c:* %co:+[Q] w:* %i c:* %ci:+[D] w:* %i %i
# select the multiplexer tree that drives the signal 'state'
select state %ci*:+$mux,$pmux[A,B,Y]
See :doc:`/cmd/select` for full documentation of these expressions.
Incremental selection
^^^^^^^^^^^^^^^^^^^^^
Sometimes a selection can most easily be described by a series of add/delete
operations. The commands ``select -add`` and ``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
Creating selection variables
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Selections can be stored under a name with the ``select -set <name>``
command. The stored selections can be used in later select expressions
using the syntax ``@<name>``.
.. code:: yoscrypt
select -set cone_a state_a %ci*:-$dff # set @cone_a to the input cone of state_a
select -set cone_b state_b %ci*:-$dff # set @cone_b to the input cone of state_b
select @cone_a @cone_b %i # select the objects that are in both cones
Remember that select expressions can also be used directly as arguments to most
commands. Some commands also except a single select argument to some options.
In those cases selection variables must be used to capture more complex selections.
.. code:: yoscrypt
dump @cone_a @cone_b
select -set cone_ab @cone_a @cone_b %i
show -color red @cone_ab -color magenta @cone_a -color blue @cone_b
Example:
.. literalinclude:: ../../../resources/PRESENTATION_ExAdv/select.v
:language: verilog
:caption: ``docs/resources/PRESENTATION_ExAdv/select.v``
.. literalinclude:: ../../../resources/PRESENTATION_ExAdv/select.ys
:language: yoscrypt
:caption: ``docs/resources/PRESENTATION_ExAdv/select.ys``
.. figure:: ../../../images/res/PRESENTATION_ExAdv/select.*
:class: width-helper
Interactive Design Investigation
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Yosys can also be used to investigate designs (or netlists created from other
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 ``submod``, ``expose``, and ``splice`` can be used to
transform the design into an equivalent design that is easier to analyse.
- Commands such as ``eval`` and ``sat`` can be used to investigate the behavior
of the circuit.
- :doc:`/cmd/show`.
- :doc:`/cmd/dump`.
Reorganizing a module
^^^^^^^^^^^^^^^^^^^^^
.. literalinclude:: ../../../resources/PRESENTATION_ExOth/scrambler.v
:language: verilog
:caption: ``docs/resources/PRESENTATION_ExOth/scrambler.v``
.. code:: yoscrypt
read_verilog scrambler.v
hierarchy; proc;;
cd scrambler
submod -name xorshift32 \
xs %c %ci %D %c %ci:+[D] %D \
%ci*:-$dff xs %co %ci %d
.. figure:: ../../../images/res/PRESENTATION_ExOth/scrambler_p01.*
:class: width-helper
.. figure:: ../../../images/res/PRESENTATION_ExOth/scrambler_p02.*
:class: width-helper
Analysis of circuit behavior
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. code:: text
> read_verilog scrambler.v
> hierarchy; proc;; cd scrambler
> submod -name xorshift32 xs %c %ci %D %c %ci:+[D] %D %ci*:-$dff xs %co %ci %d
> cd xorshift32
> rename n2 in
> rename n1 out
> eval -set in 1 -show out
Eval result: \out = 270369.
> eval -set in 270369 -show out
Eval result: \out = 67634689.
> sat -set out 632435482
Signal Name Dec Hex Bin
-------------------- ---------- ---------- -------------------------------------
\in 745495504 2c6f5bd0 00101100011011110101101111010000
\out 632435482 25b2331a 00100101101100100011001100011010
Reference in New Issue View Git Blame Copy Permalink