Design modification¶

abstract - replace signals with abstract values during formal verification¶

yosys> help abstract¶

abstract [mode] [options] [selection]¶

Perform abstraction of signals within the design. Abstraction replaces a signal
with an unconstrained abstract value that can take an arbitrary concrete value
during formal verification. The mode and options control when a signal should
be abstracted and how it should affect FFs present in the design.

Modes:

-state

The selected FFs will be modified to load a new abstract value on every
active clock edge, async reset or async load. This is independent of any
clock enable that may be present on the FF cell. Conditional abstraction
is supported with the -enable/-enabeln options. If present, the condition
is sampled at the same time as the FF would smaple the correspnding data
or async-data input whose value will be replaced with an abstract value.

The selection can be used to specify which state bits to abstract. For
each selected wire, any state bits that the wire is driven by will be
abstracted. For a selected FF cell, all of its state is abstracted.
Individual bits of a single wire can be abtracted using the -slice and

-rtlilslice options.

-init

The selected FFs will be modified to have an abstract initial value.
The -enable/-enablen options are not supported in this mode.

The selection is used in the same way as it is for the -state mode.

-value

The drivers of the selected signals will be replaced with an abstract
value. In this mode, the abstract value can change at any time and is
not synchronized to any clock or other signal. Conditional abstraction
is supported with the -enable/-enablen options. The condition will
combinationally select between the original driver and the abstract
value.

The selection can be used to specify which output bits of which drivers
to abtract. For a selected cell, all its output bits will be abstracted.
For a selected wire, every output bit that is driving the wire will be
abstracted. Individual bits of a single wire can be abstracted using the

-slice and -rtlilslice options.

-enable <wire-name>

-enablen <wire-name>

Perform conditional abstraction with a named single bit wire as
condition. For -enable the wire is used as an active-high condition and
for -enablen as an active-low condition. See the description of the

-state and -value modes for details on how the condition affects the

abstractions performed by either mode. This option is not supported in
the -init mode.

-initstates <n>

Perform conditional abstraction for the first <n> time steps. See the
description of the -state and -value modes for details on how the
condition affects the abstractions performed by either mode. This option
is not supported in the -init mode.

-slice <lhs>:<rhs>

-slice <index>

-rtlilslice <lhs>:<rhs>

-rtlilslice <index>

Limit the abstraction to a slice of a single selected wire. The targeted
bits of the wire can be given as an inclusive range of indices or as a
single index. When using the -slice option, the indices are interpreted
following the source level declaration of the wire. This means the

-slice option will respect declarations with a non-zero-based index range

or with reversed bitorder. The -rtlilslice options will always use
zero-based indexing where index 0 corresponds to the least significant
bit of the wire.

Note

Help text automatically generated from passes/cmds/abstract.cc:320

add - add objects to the design¶

yosys> help add¶

add <command> [selection]¶

This command adds objects to the design. It operates on all fully selected
modules. So e.g. 'add -wire foo' will add a wire foo to all selected modules.

add {-wire|-input|-inout|-output} <name> <width> [selection]¶

Add a wire (input, inout, output port) with the given name and width. The
command will fail if the object exists already and has different properties
than the object to be created.

add -global_input <name> <width> [selection]¶

Like 'add -input', but also connect the signal between instances of the
selected modules.

add {-assert|-assume|-live|-fair|-cover} <name1> [-if <name2>]¶

Add an $assert, $assume, etc. cell connected to a wire named name1, with its
enable signal optionally connected to a wire named name2 (default: 1'b1).

add -mod <name[s]>¶

Add module[s] with the specified name[s].

Note

Help text automatically generated from passes/cmds/add.cc:118

autoname - automatically assign names to objects¶

yosys> help autoname¶

autoname [selection]¶

Assign auto-generated public names to objects with private names (the ones
with $-prefix).

Note

Help text automatically generated from passes/cmds/autoname.cc:111

blackbox - convert modules into blackbox modules¶

yosys> help blackbox¶

blackbox [options] [selection]¶

Convert modules into blackbox modules (remove contents and set the blackbox
module attribute).

Note

Help text automatically generated from passes/cmds/blackbox.cc:26

box_derive - derive box modules¶

yosys> help box_derive¶

box_derive [-base <base_module>] [-naming_attr <attr>] [selection]¶

As part of the assembly of the design hierarchy done by the 'hierarchy' command,
specializations of parametric modules are derived on demand: for each choice of
parameter values appearing in the design, a copy of the parametric module is
derived which is specialized to that choice.

This derivation process ignores blackboxes and whiteboxes (boxes). To supplement,
this 'box_derive' command can be used to request the derivation of modules based
on box instances appearing in the design, which is desirable in certain use
cases. Only the selected cells are considered as the instances that steer the
derivation process.

-base <base_module>

instead of deriving the module that directly corresponds to each box
instance, derive a specialization of <base_module> (this option applies
to all selected box cells)

-naming_attr <attr>

once a specialization is derived, use the value of the module attribute
<attr> for a name which should be used for the derived module (this
replaces the internal Yosys naming scheme in which the names of derived
modules start with '$paramod$')

-apply_derived_type

use the derived modules

Note

Help text automatically generated from passes/cmds/box_derive.cc:25

bugpoint - minimize testcases¶

yosys> help bugpoint¶

bugpoint [options] [-script <filename> | -command "<command>"]"]" title="Link to this definition">¶

This command minimizes the current design that is known to crash Yosys with the
given script into a smaller testcase. It does this by removing an arbitrary part
of the design and recursively invokes a new Yosys process with this modified
design and the same script, repeating these steps while it can find a smaller
design that still causes a crash. Once this command finishes, it replaces the
current design with the smallest testcase it was able to produce.
In order to save the reduced testcase you must write this out to a file with
another command after `bugpoint` like `write_rtlil` or `write_verilog`.

-script <filename> | -command "<command>"

use this script file or command to crash Yosys. required.

-yosys <filename>

use this Yosys binary. if not specified, `yosys` is used.

-grep "<string>"

only consider crashes that place this string in the log file.

-expect-return <int>

only consider crashes that return the specified value. e.g. SEGFAULT
returns a value of 139.

-fast

run `proc_clean; clean -purge` after each minimization step. converges
faster, but produces larger testcases, and may fail to produce any
testcase at all if the crash is related to dangling wires.

-clean

run `proc_clean; clean -purge` before checking testcase and after
finishing. produces smaller and more useful testcases, but may fail to
produce any testcase at all if the crash is related to dangling wires.

-runner "<prefix>"

child process wrapping command, e.g., "timeout 30", or valgrind.

-err-grep "<string>"

only consider crashes that print this string on stderr. useful for
errors outside of yosys.

-suffix "<string>"

add suffix to generated file names. useful when running more than one
instance of bugpoint in the same directory. limited to 8 characters.

It is possible to constrain which parts of the design will be considered for
removal. Unless one or more of the following options are specified, all parts
will be considered.

-modules

try to remove modules. modules with a (* bugpoint_keep *) attribute
will be skipped.

-ports

try to remove module ports. ports with a (* bugpoint_keep *) attribute
will be skipped (useful for clocks, resets, etc.)

-cells

try to remove cells. cells with a (* bugpoint_keep *) attribute will
be skipped.

-connections

try to reconnect ports to 'x.

-processes

try to remove processes. processes with a (* bugpoint_keep *) attribute
will be skipped.

-assigns

try to remove process assigns from cases.

-updates

try to remove process updates from syncs.

-wires

try to remove wires. wires with a (* bugpoint_keep *) attribute will be
skipped.

Note

Help text automatically generated from passes/cmds/bugpoint.cc:40

chparam - re-evaluate modules with new parameters¶

yosys> help chparam¶

chparam [ -set name value ]... [selection]¶

Re-evaluate the selected modules with new parameters. String values must be
passed in double quotes (").

chparam -list [selection]¶

List the available parameters of the selected modules.

Note

Help text automatically generated from passes/cmds/setattr.cc:197

chtype - change type of cells in the design¶

yosys> help chtype¶

chtype [options] [selection]¶

Change the types of cells in the design.

-set <type>

set the cell type to the given type

-map <old_type> <new_type>

change cells types that match <old_type> to <new_type>

-publish_icells

change internal cells types to public types

Note

Help text automatically generated from passes/cmds/chtype.cc:47

clean_zerowidth - clean zero-width connections from the design¶

yosys> help clean_zerowidth¶

clean_zerowidth [selection]¶

Fixes the selected cells and processes to contain no zero-width connections.
Depending on the cell type, this may be implemented by removing the connection,
widening it to 1-bit, or removing the cell altogether.

Note

Help text automatically generated from passes/cmds/clean_zerowidth.cc:28

connect - create or remove connections¶

yosys> help connect¶

connect [-nomap] [-nounset] -set <lhs-expr> <rhs-expr> [selection]¶

Create a connection. This is equivalent to adding the statement 'assign
<lhs-expr> = <rhs-expr>;' to the Verilog input. Per default, all existing
drivers for <lhs-expr> are unconnected. This can be overwritten by using
the -nounset option.

connect [-nomap] -unset <expr> [selection]¶

Unconnect all existing drivers for the specified expression.

connect [-nomap] [-assert] -port <cell> <port> <expr> [selection]¶

Connect the specified cell port to the specified cell port.

Per default signal alias names are resolved and all signal names are mapped
the the signal name of the primary driver. Using the -nomap option deactivates
this behavior.

The connect command operates in one module only. Either only one module must
be selected or an active module must be set using the 'cd' command.

The -assert option verifies that the connection already exists, instead of
making it.

This command does not operate on module with processes.

Note

Help text automatically generated from passes/cmds/connect.cc:45

connwrappers - match width of input-output port pairs¶

yosys> help connwrappers¶

connwrappers [options] [selection]¶

Wrappers are used in coarse-grain synthesis to wrap cells with smaller ports
in wrapper cells with a (larger) constant port size. I.e. the upper bits
of the wrapper output are signed/unsigned bit extended. This command uses this
knowledge to rewire the inputs of the driven cells to match the output of
the driving cell.

-signed <cell_type> <port_name> <width_param>

-unsigned <cell_type> <port_name> <width_param>

consider the specified signed/unsigned wrapper output

-port <cell_type> <port_name> <width_param> <sign_param>

use the specified parameter to decide if signed or unsigned

The options -signed, -unsigned, and -port can be specified multiple times.

Note

Help text automatically generated from passes/cmds/connwrappers.cc:145

copy - copy modules in the design¶

yosys> help copy¶

copy old_name new_name¶

Copy the specified module. Note that selection patterns are not supported
by this command.

Note

Help text automatically generated from passes/cmds/copy.cc:28

delete - delete objects in the design¶

yosys> help delete¶

delete [selection]¶

Deletes the selected objects. This will also remove entire modules, if the
whole module is selected.

delete {-input|-output|-port} [selection]¶

Does not delete any object but removes the input and/or output flag on the
selected wires, thus 'deleting' module ports.

Note

Help text automatically generated from passes/cmds/delete.cc:26

design - save, restore and reset current design¶

yosys> help design¶

design -reset¶

Clear the current design.

design -save <name>¶

Save the current design under the given name.

design -stash <name>¶

Save the current design under the given name and then clear the current design.

design -push¶

Push the current design to the stack and then clear the current design.

design -push-copy¶

Push the current design to the stack without clearing the current design.

design -pop¶

Reset the current design and pop the last design from the stack.

design -load <name>¶

Reset the current design and load the design previously saved under the given
name.

design -copy-from <name> [-as <new_mod_name>] <selection>¶

Copy modules from the specified design into the current one. The selection is
evaluated in the other design.

design -copy-to <name> [-as <new_mod_name>] [selection]¶

Copy modules from the current design into the specified one.

design -import <name> [-as <new_top_name>] [selection]¶

Import the specified design into the current design. The source design must
either have a selected top module or the selection must contain exactly one
module that is then used as top module for this command.

design -reset-vlog¶

The Verilog front-end remembers defined macros and top-level declarations
between calls to 'read_verilog'. This command resets this memory.

    design -delete <name>

Delete the design previously saved under the given name.

Note

Help text automatically generated from passes/cmds/design.cc:30

design_equal - check if two designs are the same¶

yosys> help design_equal¶

design_equal <name>¶

Compare the current design with the design previously saved under the given
name. Abort with an error if the designs are different.

Note

Help text automatically generated from passes/cmds/design_equal.cc:328

expose - convert internal signals to module ports¶

yosys> help expose¶

expose [options] [selection]¶

This command exposes all selected internal signals of a module as additional
outputs.

-dff

only consider wires that are directly driven by register cell.

-cut

when exposing a wire, create an input/output pair and cut the internal
signal path at that wire.

-input

when exposing a wire, create an input port and disconnect the internal
driver.

-shared

only expose those signals that are shared among the selected modules.
this is useful for preparing modules for equivalence checking.

-evert

also turn connections to instances of other modules to additional
inputs and outputs and remove the module instances.

-evert-dff

turn flip-flops to sets of inputs and outputs.

-sep <separator>

when creating new wire/port names, the original object name is suffixed
with this separator (default: '.') and the port name or a type
designator for the exposed signal.

Note

Help text automatically generated from passes/sat/expose.cc:218

icell_liberty - write Liberty interfaces for used internal cells¶

yosys> help icell_liberty¶

icell_liberty <liberty_file>¶

Write Liberty files modeling the interfaces of used internal cells.

Models are not guaranteed to be logically sound.

Note

Help text automatically generated from passes/cmds/icell_liberty.cc:150

linecoverage - report coverage information¶

yosys> help linecoverage¶

linecoverage [options] [selection]¶

This command prints coverage information on the design based on the current
selection, where items in the selection are considered covered and items not in
the selection are considered uncovered. If the same source location is found
both on items inside and out of the selection, it is considered uncovered.

-lcov <filename>

write coverage information in lcov format to this file

Note

Help text automatically generated from passes/cmds/linecoverage.cc:32

rename - rename object in the design¶

yosys> help rename¶

rename old_name new_name¶

Rename the specified object. Note that selection patterns are not supported
by this command.

rename -output old_name new_name¶

Like above, but also make the wire an output. This will fail if the object is
not a wire.

rename -src [selection]¶

Assign names auto-generated from the src attribute to all selected wires and
cells with private names.

rename -wire [selection] [-move-to-cell] [-suffix <suffix>]¶

Assign auto-generated names based on the wires they drive to all selected
cells with private names. Ignores cells driving privatly named wires.
By default, the cell is named after the wire with the cell type as suffix.
The -suffix option can be used to set the suffix to the given string instead.

The -move-to-cell option can be used to name the cell after the wire without
any suffix. If this would lead to conflicts, the suffix is added to the wire
instead. For cells driving ports, the -move-to-cell option is ignored.

rename -enumerate [-pattern <pattern>] [selection]¶

Assigns auto-generated names to objects used in formal verification
that do not have a public name. This applies to all formal property
cells, $any*/$all* output wires, and their containing cells.

rename -witness¶

Assigns auto-generated names to objects used in formal verification
that do not have a public name. This applies to all formal property
cells ($assert, $assume, $cover, $live, $fair, $check), $any*/$all*
output wires, and their containing cells.

rename -hide [selection]¶

Assign private names (the ones with $-prefix) to all selected wires and cells
with public names. This ignores all selected ports.

rename -top new_name¶

Rename top module.

rename -scramble-name [-seed <seed>] [selection]¶

Assign randomly-generated names to all selected wires and cells. The seed option
can be used to change the random number generator seed from the default, but it
must be non-zero.

rename -unescape [selection]¶

Rename all selected public wires and cells that have to be escaped in Verilog.
Replaces characters with underscores or adds additional underscores and numbers.

Note

Help text automatically generated from passes/cmds/rename.cc:219

scatter - add additional intermediate nets¶

yosys> help scatter¶

scatter [selection]¶

This command adds additional intermediate nets on all cell ports. This is used
for testing the correct use of the SigMap helper in passes. If you don't know
what this means: don't worry -- you only need this pass when testing your own
extensions to Yosys.

Use the opt_clean command to get rid of the additional nets.

Note

Help text automatically generated from passes/cmds/scatter.cc:29

setattr - set/unset attributes on objects¶

yosys> help setattr¶

setattr [ -mod ] [ -set name value | -unset name ]... [selection]¶

Set/unset the given attributes on the selected objects. String values must be
passed in double quotes (").

When called with -mod, this command will set and unset attributes on modules
instead of objects within modules.

Note

Help text automatically generated from passes/cmds/setattr.cc:58

setparam - set/unset parameters on objects¶

yosys> help setparam¶

setparam [ -type cell_type ] [ -set name value | -unset name ]... [selection]¶

Set/unset the given parameters on the selected cells. String values must be
passed in double quotes (").

The -type option can be used to change the cell type of the selected cells.

Note

Help text automatically generated from passes/cmds/setattr.cc:145

setundef - replace undef values with defined constants¶

yosys> help setundef¶

setundef [options] [selection]¶

This command replaces undef (x) constants with defined (0/1) constants.

-undriven

also set undriven nets to constant values

-expose

also expose undriven nets as inputs (use with -undriven)

-zero

replace with bits cleared (0)

-one

replace with bits set (1)

-undef

replace with undef (x) bits, may be used with -undriven

-anyseq

replace with $anyseq drivers (for formal)

-anyconst

replace with $anyconst drivers (for formal)

-random <seed>

replace with random bits using the specified integer as seed
value for the random number generator.

-init

also create/update init values for flip-flops

-params

replace undef in cell parameters

Note

Help text automatically generated from passes/cmds/setundef.cc:110

sort - sort the design objects¶

yosys> help sort¶

sort¶

Sorts the design objects.

Note

Help text automatically generated from passes/cmds/sort.cc:7

splice - create explicit splicing cells¶

yosys> help splice¶

splice [options] [selection]¶

This command adds $slice and $concat cells to the design to make the splicing
of multi-bit signals explicit. This for example is useful for coarse grain
synthesis, where dedicated hardware is needed to splice signals.

-sel_by_cell

only select the cell ports to rewire by the cell. if the selection
contains a cell, than all cell inputs are rewired, if necessary.

-sel_by_wire

only select the cell ports to rewire by the wire. if the selection
contains a wire, than all cell ports driven by this wire are wired,
if necessary.

-sel_any_bit

it is sufficient if the driver of any bit of a cell port is selected.
by default all bits must be selected.

-wires

also add $slice and $concat cells to drive otherwise unused wires.

-no_outputs

do not rewire selected module outputs.

-port <name>

only rewire cell ports with the specified name. can be used multiple
times. implies -no_output.

-no_port <name>

do not rewire cell ports with the specified name. can be used multiple
times. can not be combined with -port <name>.

By default selected output wires and all cell ports of selected cells driven
by selected wires are rewired.

Note

Help text automatically generated from passes/cmds/splice.cc:248

splitcells - split up multi-bit cells¶

yosys> help splitcells¶

splitcells [options] [selection]¶

This command splits multi-bit cells into smaller chunks, based on usage of the
cell output bits.

This command operates only in cells such as $or, $and, and $mux, that are easily
cut into bit-slices.

-format char1[char2[char3]]

the first char is inserted between the cell name and the bit index, the
second char is appended to the cell name. e.g. -format () creates cell
names like 'mycell(42)'. the 3rd character is the range separation
character when creating multi-bit cells. the default is '[]:'.

Note

Help text automatically generated from passes/cmds/splitcells.cc:200

splitnets - split up multi-bit nets¶

yosys> help splitnets¶

splitnets [options] [selection]¶

This command splits multi-bit nets into single-bit nets.

-format char1[char2[char3]]

the first char is inserted between the net name and the bit index, the
second char is appended to the netname. e.g. -format () creates net
names like 'mysignal(42)'. the 3rd character is the range separation
character when creating multi-bit wires. the default is '[]:'.

-ports

also split module ports. per default only internal signals are split.

-driver

don't blindly split nets in individual bits. instead look at the driver
and split nets so that no driver drives only part of a net.

Note

Help text automatically generated from passes/cmds/splitnets.cc:98

test_select - call internal selection methods on design for testing purposes¶

yosys> help test_select¶

test_select [options]¶

Test semantics of internal 'RTLIL::Design::selected_modules()' by modifying the
current selection to only include the results of the call.

Includes partially selected modules by default, use one of the following options
to remove them instead:

-whole_only

-whole_warn

-whole_err

-whole_cmderr

remove partially selected modules, raising warning, error, or cmd error

test_select -unboxed_only [options]

Remove boxed modules from selection.

-include_wb

don't remove white boxes from selection

-warn_boxes

-err_boxes

-cmderr_boxes

raise warning, error, or cmd error if a box is removed

Note

Help text automatically generated from passes/cmds/test_select.cc:7

timeest - estimate timing¶

yosys> help timeest¶

timeest [-clk <clk_signal>] [options] [selection]¶

Estimate the critical path by counting AIG nodes.

-all_paths

Print or select nodes from all critical paths instead of focusing on
a single illustratory path.

-select

Select the nodes of a critical path

Note

Help text automatically generated from passes/cmds/timeest.cc:376

wbflip - flip the whitebox attribute¶

yosys> help wbflip¶

wbflip [selection]¶

Flip the whitebox attribute on selected cells. I.e. if it's set, unset it, and
vice-versa. Blackbox cells are not effected by this command.

Note

Help text automatically generated from passes/cmds/setattr.cc:114

wrapcell - wrap individual cells into new modules¶

yosys> help wrapcell¶

wrapcell -name <format> [selection]¶

This command wraps the selected cells individually into modules. The name for
each wrapper module is derived from the template <format> by substituting
parameter values as specified in curly brackets. If the named module already
exists, it is reused.

If the template contains the special string '{%unused}', the command tracks
unused output ports -- specialized wrapper modules will be generated per every
distinct set of unused port bits as appearing on any selected cell.

-setattr <attribute-name>

set the given boolean attribute on each created wrapper module

-formatattr <attribute-name> <format>

set a string attribute on the created wrapper module by substituting
parameter values into <format>

Currently this command only supports wrapping internal cell types.

Note

Help text automatically generated from passes/cmds/wrapcell.cc:128