Design status¶

cd - a shortcut for ‘select -module <name>’¶

yosys> help cd¶

cd <modname>¶

This is just a shortcut for 'select -module <modname>'.

cd <cellname>¶

When no module with the specified name is found, but there is a cell
with the specified name in the current module, then this is equivalent
to 'cd <celltype>'.

cd ..¶

Remove trailing substrings that start with '.' in current module name until
the name of a module in the current design is generated, then switch to that
module. Otherwise clear the current selection.

cd¶

This is just a shortcut for 'select -clear'.

Note

Help text automatically generated from passes/cmds/select.cc:1670

check - check for obvious problems in the design¶

yosys> help check¶

check [options] [selection]¶

This pass identifies the following problems in the current design:

  - combinatorial loops
  - two or more conflicting drivers for one wire
  - used wires that do not have a driver

Options:

-noinit

also check for wires which have the 'init' attribute set

-initdrv

also check for wires that have the 'init' attribute set and are not
driven by an FF cell type

-mapped

also check for internal cells that have not been mapped to cells of the
target architecture

-allow-tbuf

modify the -mapped behavior to still allow $_TBUF_ cells

-assert

produce a runtime error if any problems are found in the current design

-force-detailed-loop-check

for the detection of combinatorial loops, use a detailed connectivity
model for all internal cells for which it is available. This disables
falling back to a simpler overapproximating model for those cells for
which the detailed model is expected costly.

Note

Help text automatically generated from passes/cmds/check.cc:31

cover - print code coverage counters¶

yosys> help cover¶

Warning

This command is intended for internal developer use only

cover [options] [pattern]¶

Print the code coverage counters collected using the cover() macro in the Yosys
C++ code. This is useful to figure out what parts of Yosys are utilized by a
test bench.

-q

Do not print output to the normal destination (console and/or log file)

-o file

Write output to this file, truncate if exists.

-a file

Write output to this file, append if exists.

-d dir

Write output to a newly created file in the specified directory.

When one or more pattern (shell wildcards) are specified, then only counters
matching at least one pattern are printed.

It is also possible to instruct Yosys to print the coverage counters on program
exit to a file using environment variables:

    YOSYS_COVER_DIR="{dir-name}" yosys {args}

        This will create a file (with an auto-generated name) in this
        directory and write the coverage counters to it.

    YOSYS_COVER_FILE="{file-name}" yosys {args}

        This will append the coverage counters to the specified file.

Hint: Use the following AWK command to consolidate Yosys coverage files:

    gawk '{ p[$3] = $1; c[$3] += $2; } END { for (i in p)
      printf "%-60s %10d %s\n", p[i], c[i], i; }' {files} | sort -k3

Coverage counters are only available in Yosys for Linux.

Note

Help text automatically generated from passes/cmds/cover.cc:34

debug - run command with debug log messages enabled¶

yosys> help debug¶

debug cmd¶

Execute the specified command with debug log messages enabled

Note

Help text automatically generated from passes/cmds/trace.cc:104

edgetypes - list all types of edges in selection¶

yosys> help edgetypes¶

edgetypes [options] [selection]¶

This command lists all unique types of 'edges' found in the selection. An 'edge'
is a 4-tuple of source and sink cell type and port name.

Note

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

exec - execute commands in the operating system shell¶

yosys> help exec¶

exec [options] -- [command]¶

Execute a command in the operating system shell.  All supplied arguments are
concatenated and passed as a command to popen(3).  Whitespace is not guaranteed
to be preserved, even if quoted.  stdin and stderr are not connected, while
stdout is logged unless the "-q" option is specified.

-q

Suppress stdout and stderr from subprocess

-expect-return <int>

Generate an error if popen() does not return specified value.
May only be specified once; the final specified value is controlling
if specified multiple times.

-expect-stdout <regex>

Generate an error if the specified regex does not match any line
in subprocess's stdout.  May be specified multiple times.

-not-expect-stdout <regex>

Generate an error if the specified regex matches any line
in subprocess's stdout.  May be specified multiple times.

Example: exec -q -expect-return 0 -- echo "bananapie" | grep "nana"

Note

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

log - print text and log files¶

yosys> help log¶

log [options] string¶

log [ -push | -pop ]¶

Print the given string to the screen and/or the log file. This is useful for TCL
scripts, because the TCL command "puts" only goes to stdout but not to
logfiles.

-stdout

Print the output to stdout too. This is useful when all Yosys is
executed with a script and the -q (quiet operation) argument to notify
the user.

-stderr

Print the output to stderr too.

-nolog

Don't use the internal log() command. Use either -stdout or -stderr,
otherwise no output will be generated at all.

-n

do not append a newline

-header

log a pass header

-push

push a new level on the pass counter

-pop

pop from the pass counter

Note

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

logger - set logger properties¶

yosys> help logger¶

logger [options]¶

This command sets global logger properties, also available using command line
options.

-[no]time

enable/disable display of timestamp in log output.

-[no]stderr

enable/disable logging errors to stderr.

-warn regex

print a warning for all log messages matching the regex.

-nowarn regex

if a warning message matches the regex, it is printed as regular
message instead.

-werror regex

if a warning message matches the regex, it is printed as error
message instead and the tool terminates with a nonzero return code.

-[no]debug

globally enable/disable debug log messages.

-experimental <feature>

do not print warnings for the specified experimental feature

-expect <type> <regex> <expected_count>

expect log, warning or error to appear. matched errors will terminate
with exit code 0.
Types prefix-log, prefix-warning and prefix-error match the entire
logged string, including filename if present.

-expect-no-warnings

gives error in case there is at least one warning that is not expected.

-check-expected

verifies that the patterns previously set up by -expect have actually
been met, then clears the expected log list.  If this is not called
manually, the check will happen at yosys exit time instead.

Note

Help text automatically generated from passes/cmds/logger.cc:27

ls - list modules or objects in modules¶

yosys> help ls¶

ls [selection]¶

When no active module is selected, this prints a list of modules.

When an active module is selected, this prints a list of objects in the module.

Note

Help text automatically generated from passes/cmds/select.cc:1787

ltp - print longest topological path¶

yosys> help ltp¶

ltp [options] [selection]¶

This command prints the longest topological path in the design. (Only considers
paths within a single module, so the design must be flattened.)

-noff

automatically exclude FF cell types

Note

Help text automatically generated from passes/cmds/ltp.cc:144

plugin - load and list loaded plugins¶

yosys> help plugin¶

plugin [options]¶

Load and list loaded plugins.

-i <plugin_filename>

Load (install) the specified plugin.

-a <alias_name>

Register the specified alias name for the loaded plugin

-l

List loaded plugins

Note

Help text automatically generated from passes/cmds/plugin.cc:125

portarcs - derive port arcs for propagation delay¶

yosys> help portarcs¶

portarcs [options] [selection]¶

This command characterizes the combinational content of selected modules and
derives timing arcs going from module inputs to module outputs representing the
propagation delay of the module.

-draw

plot the computed delay table to the terminal

-icells

assign unit delay to gates from the internal Yosys cell library

-write

write the computed arcs back into the module as $specify2 instances

Note

Help text automatically generated from passes/cmds/portarcs.cc:41

portlist - list (top-level) ports¶

yosys> help portlist¶

portlist [options] [selection]¶

This command lists all module ports found in the selected modules.

If no selection is provided then it lists the ports on the top module.

-m

print verilog blackbox module definitions instead of port lists

Note

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

printattrs - print attributes of selected objects¶

yosys> help printattrs¶

printattrs [selection]¶

Print all attributes of the selected objects.

Note

Help text automatically generated from passes/cmds/printattrs.cc:27

scc - detect strongly connected components (logic loops)¶

yosys> help scc¶

scc [options] [selection]¶

This command identifies strongly connected components (aka logic loops) in the
design.

-expect <num>

expect to find exactly <num> SCCs. A different number of SCCs will
produce an error.

-max_depth <num>

limit to loops not longer than the specified number of cells. This
can e.g. be useful in identifying small local loops in a module that
implements one large SCC.

-nofeedback

do not count cells that have their output fed back into one of their
inputs as single-cell scc.

-all_cell_types

Usually this command only considers internal non-memory cells. With
this option set, all cells are considered. For unknown cells all ports
are assumed to be bidirectional 'inout' ports.

-set_attr <name> <value>

set the specified attribute on all cells that are part of a logic
loop. the special token {} in the value is replaced with a unique
identifier for the logic loop.

-select

replace the current selection with a selection of all cells and wires
that are part of a found logic loop

-specify

examine specify rules to detect logic loops in whitebox/blackbox cells

Note

Help text automatically generated from passes/cmds/scc.cc:252

scratchpad - get/set values in the scratchpad¶

yosys> help scratchpad¶

scratchpad [options]¶

This pass allows to read and modify values from the scratchpad of the current
design. Options:

-get <identifier>

print the value saved in the scratchpad under the given identifier.

-set <identifier> <value>

save the given value in the scratchpad under the given identifier.

-unset <identifier>

remove the entry for the given identifier from the scratchpad.

-copy <identifier_from> <identifier_to>

copy the value of the first identifier to the second identifier.

-assert <identifier> <value>

assert that the entry for the given identifier is set to the given
value.

-assert-set <identifier>

assert that the entry for the given identifier exists.

-assert-unset <identifier>

assert that the entry for the given identifier does not exist.

The identifier may not contain whitespace. By convention, it is usually prefixed
by the name of the pass that uses it, e.g. 'opt.did_something'. If the value
contains whitespace, it must be enclosed in double quotes.

Note

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

select - modify and view the list of selected objects¶

yosys> help select¶

select [ -add | -del | -set <name> ] {-read <filename> | <selection>}¶

select [ -unset <name> ]¶

select [ <assert_option> ] {-read <filename> | <selection>}¶

select [ -list | -list-mod | -write <filename> | -count | -clear ]¶

select -module <modname>¶

Most commands use the list of currently selected objects to determine which part
of the design to operate on. This command can be used to modify and view this
list of selected objects.

Note that many commands support an optional [selection] argument that can be
used to override the global selection for the command. The syntax of this
optional argument is identical to the syntax of the <selection> argument
described here.

-add, -del

add or remove the given objects to the current selection.
without this options the current selection is replaced.

-set <name>

do not modify the current selection. instead save the new selection
under the given name (see @<name> below). to save the current selection,
use "select -set <name> %"

-unset <name>

do not modify the current selection. instead remove a previously saved
selection under the given name (see @<name> below).

-assert-none

do not modify the current selection. instead assert that the given
selection is empty. i.e. produce an error if any object or module
matching the selection is found.

-assert-any

do not modify the current selection. instead assert that the given
selection is non-empty. i.e. produce an error if no object or module
matching the selection is found.

-assert-mod-count N

do not modify the current selection. instead assert that the given
selection contains exactly N modules (partially or fully selected).

-assert-count N

do not modify the current selection. instead assert that the given
selection contains exactly N objects.

-assert-max N

do not modify the current selection. instead assert that the given
selection contains less than or exactly N objects.

-assert-min N

do not modify the current selection. instead assert that the given
selection contains at least N objects.

-list

list all objects in the current selection

-write <filename>

like -list but write the output to the specified file

-read <filename>

read the specified file (written by -write)

-count

count all objects in the current selection

-clear

clear the current selection. this effectively selects the whole
design. it also resets the selected module (see -module). use the
command 'select *' to select everything but stay in the current module.

-none

create an empty selection. the current module is unchanged.

-module <modname>

limit the current scope to the specified module.
the difference between this and simply selecting the module
is that all object names are interpreted relative to this
module after this command until the selection is cleared again.

When this command is called without an argument, the current selection
is displayed in a compact form (i.e. only the module name when a whole module
is selected).

The <selection> argument itself is a series of commands for a simple stack
machine. Each element on the stack represents a set of selected objects.
After this commands have been executed, the union of all remaining sets
on the stack is computed and used as selection for the command.

Pushing (selecting) object when not in -module mode:

    <mod_pattern>
        select the specified module(s)

    <mod_pattern>/<obj_pattern>
        select the specified object(s) from the module(s)

Pushing (selecting) object when in -module mode:

    <obj_pattern>
        select the specified object(s) from the current module

By default, patterns will not match black/white-box modules or their
contents. To include such objects, prefix the pattern with '='.

A <mod_pattern> can be a module name, wildcard expression (*, ?, [..])
matching module names, or one of the following:

    A:<pattern>, A:<pattern>=<pattern>
        all modules with an attribute matching the given pattern
        in addition to = also <, <=, >=, and > are supported

    N:<pattern>
        all modules with a name matching the given pattern
        (i.e. 'N:' is optional as it is the default matching rule)

An <obj_pattern> can be an object name, wildcard expression, or one of
the following:

    w:<pattern>
        all wires with a name matching the given wildcard pattern

    i:<pattern>, o:<pattern>, x:<pattern>
        all inputs (i:), outputs (o:) or any ports (x:) with matching names

    s:<size>, s:<min>:<max>
        all wires with a matching width

    m:<pattern>
        all memories with a name matching the given pattern

    c:<pattern>
        all cells with a name matching the given pattern

    t:<pattern>
        all cells with a type matching the given pattern

    t:@<name>
        all cells with a type matching a module in the saved selection <name>

    p:<pattern>
        all processes with a name matching the given pattern

    a:<pattern>
        all objects with an attribute name matching the given pattern

    a:<pattern>=<pattern>
        all objects with a matching attribute name-value-pair.
        in addition to = also <, <=, >=, and > are supported

    r:<pattern>, r:<pattern>=<pattern>
        cells with matching parameters. also with <, <=, >= and >.

    n:<pattern>
        all objects with a name matching the given pattern
        (i.e. 'n:' is optional as it is the default matching rule)

    @<name>
        push the selection saved prior with 'select -set <name> ...'

The following actions can be performed on the top sets on the stack:

    %
        push a copy of the current selection to the stack

    %%
        replace the stack with a union of all elements on it

    %n
        replace top set with its invert

    %u
        replace the two top sets on the stack with their union

    %i
        replace the two top sets on the stack with their intersection

    %d
        pop the top set from the stack and subtract it from the new top

    %D
        like %d but swap the roles of two top sets on the stack

    %c
        create a copy of the top set from the stack and push it

    %x[<num1>|*][.<num2>][:<rule>[:<rule>..]]
        expand top set <num1> num times according to the specified rules.
        (i.e. select all cells connected to selected wires and select all
        wires connected to selected cells) The rules specify which cell
        ports to use for this. the syntax for a rule is a '-' for exclusion
        and a '+' for inclusion, followed by an optional comma separated
        list of cell types followed by an optional comma separated list of
        cell ports in square brackets. a rule can also be just a cell or wire
        name that limits the expansion (is included but does not go beyond).
        select at most <num2> objects. a warning message is printed when this
        limit is reached. When '*' is used instead of <num1> then the process
        is repeated until no further object are selected.

    %ci[<num1>|*][.<num2>][:<rule>[:<rule>..]]
    %co[<num1>|*][.<num2>][:<rule>[:<rule>..]]
        similar to %x, but only select input (%ci) or output cones (%co)

    %xe[...] %cie[...] %coe
        like %x, %ci, and %co but only consider combinatorial cells

    %a
        expand top set by selecting all wires that are (at least in part)
        aliases for selected wires.

    %s
        expand top set by adding all modules that implement cells in selected
        modules

    %m
        expand top set by selecting all modules that contain selected objects

    %M
        select modules that implement selected cells

    %C
        select cells that implement selected modules

    %R[<num>]
        select <num> random objects from top selection (default 1)

Example: the following command selects all wires that are connected to a
'GATE' input of a 'SWITCH' cell:

    select */t:SWITCH %x:+[GATE] */t:SWITCH %d

Note

Help text automatically generated from passes/cmds/select.cc:1086

setenv - set an environment variable¶

yosys> help setenv¶

setenv name value¶

Set the given environment variable on the current process. Values containing
whitespace must be passed in double quotes (").

Note

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

show - generate schematics using graphviz¶

yosys> help show¶

show [options] [selection]¶

Create a graphviz DOT file for the selected part of the design and compile it
to a graphics file (usually SVG or PostScript).

-viewer <viewer>

Run the specified command with the graphics file as parameter.
On Windows, this pauses yosys until the viewer exits.
Use "-viewer none" to not run any command.

-format <format>

Generate a graphics file in the specified format. Use 'dot' to just
generate a .dot file, or other <format> strings such as 'svg' or 'ps'
to generate files in other formats (this calls the 'dot' command).

-lib <verilog_or_rtlil_file>

Use the specified library file for determining whether cell ports are
inputs or outputs. This option can be used multiple times to specify
more than one library.

note: in most cases it is better to load the library before calling
show with 'read_verilog -lib <filename>'. it is also possible to
load liberty files with 'read_liberty -lib <filename>'.

-prefix <prefix>

generate <prefix>.* instead of ~/.yosys_show.*

-color <color> <object>

assign the specified color to the specified object. The object can be
a single selection wildcard expressions or a saved set of objects in
the @<name> syntax (see "help select" for details).

-label <text> <object>

assign the specified label text to the specified object. The object can
be a single selection wildcard expressions or a saved set of objects in
the @<name> syntax (see "help select" for details).

-colors <seed>

Randomly assign colors to the wires. The integer argument is the seed
for the random number generator. Change the seed value if the colored
graph still is ambiguous. A seed of zero deactivates the coloring.

-colorattr <attribute_name>

Use the specified attribute to assign colors. A unique color is
assigned to each unique value of this attribute.

-width

annotate buses with a label indicating the width of the bus.

-signed

mark ports (A, B) that are declared as signed (using the [AB]_SIGNED
cell parameter) with an asterisk next to the port name.

-stretch

stretch the graph so all inputs are on the left side and all outputs
(including inout ports) are on the right side.

-pause

wait for the user to press enter to before returning

-enum

enumerate objects with internal ($-prefixed) names

-long

do not abbreviate objects with internal ($-prefixed) names

-notitle

do not add the module name as graph title to the dot file

-nobg

don't run viewer in the background, IE wait for the viewer tool to
exit before returning

-href

adds href attribute to all items representing cells and wires, using
src attribute of origin

When no <format> is specified, 'dot' is used. When no <format> and <viewer> is
specified, 'xdot' is used to display the schematic (POSIX systems only).

The generated output files are '~/.yosys_show.dot' and '~/.yosys_show.<format>',
unless another prefix is specified using -prefix <prefix>.

Yosys on Windows and YosysJS use different defaults: The output is written
to 'show.dot' in the current directory and new viewer is launched each time
the 'show' command is executed.

Note

Help text automatically generated from passes/cmds/show.cc:659

sta - perform static timing analysis¶

yosys> help sta¶

sta [options] [selection]¶

This command performs static timing analysis on the design. (Only considers
paths within a single module, so the design must be flattened.)

Note

Help text automatically generated from passes/cmds/sta.cc:278

stat - print some statistics¶

yosys> help stat¶

stat [options] [selection]¶

Print some statistics (number of objects) on the selected portion of the
design.
Extracts the area of cells from a liberty file, if provided.

-top <module>

print design hierarchy with this module as top. if the design is fully
selected and a module has the 'top' attribute set, this module is used
default value for this option.

-liberty <liberty_file>

use cell area information from the provided liberty file

-tech <technology>

print area estimate for the specified technology. Currently supported
values for <technology>: xilinx, cmos

-width

annotate internal cell types with their word width.
e.g. $add_8 for an 8 bit wide $add cell.

-json

output the statistics in a machine-readable JSON format.
this is output to the console; use "tee" to output to a file.

-hierarchy

print hierarchical statistics, i.e. The area and number of cells include submodules.
this changes the format of the json output.

Note

Help text automatically generated from passes/cmds/stat.cc:884

tee - redirect command output to file¶

yosys> help tee¶

tee [-q] [-o logfile|-a logfile] cmd¶

Execute the specified command, optionally writing the commands output to the
specified logfile(s).

-q

Do not print output to the normal destination (console and/or log file).

-o logfile

Write output to this file, truncate if exists.

-a logfile

Write output to this file, append if exists.

-s scratchpad

Write output to this scratchpad value, truncate if it exists.

+INT, -INT
Add/subtract INT from the -v setting for this command.

Note

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

torder - print cells in topological order¶

yosys> help torder¶

torder [options] [selection]¶

This command prints the selected cells in topological order.

-stop <cell_type> <cell_port>

do not use the specified cell port in topological sorting

-noautostop

by default Q outputs of internal FF cells and memory read port outputs
are not used in topological sorting. this option deactivates that.

Note

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

trace - redirect command output to file¶

yosys> help trace¶

trace cmd¶

Execute the specified command, logging all changes the command performs on
the design in real time.

Note

Help text automatically generated from passes/cmds/trace.cc:63

viz - visualize data flow graph¶

yosys> help viz¶

viz [options] [selection]¶

Create a graphviz DOT file for the selected part of the design, showing the
relationships between the selected wires, and compile it to a graphics
file (usually SVG or PostScript).

-viewer <viewer>

Run the specified command with the graphics file as parameter.
On Windows, this pauses yosys until the viewer exits.

-format <format>

Generate a graphics file in the specified format. Use 'dot' to just
generate a .dot file, or other <format> strings such as 'svg' or 'ps'
to generate files in other formats (this calls the 'dot' command).

-prefix <prefix>

generate <prefix>.* instead of ~/.yosys_viz.*

-pause

wait for the user to press enter to before returning

-nobg

don't run viewer in the background, IE wait for the viewer tool to
exit before returning

-set-vg-attr

set their group index as 'vg' attribute on cells and wires

-g <selection>

manually define a group of terminal signals. this group is not being
merged with other terminal groups.

-u <selection>

manually define a unique group for each wire in the selection.

-x <selection>

manually exclude wires from being considered. (usually this is
used for global signals, such as reset.)

-s <selection>

like -g, but mark group as 'special', changing the algorithm to
preserve as much info about this groups connectivity as possible.

-G <selection_expr> .

-U <selection_expr> .

-X <selection_expr> .

-S <selection_expr> .

like -u, -g, -x, and -s, but parse all arguments up to a terminating .
as a single select expression. (see 'help select' for details)

-0, -1, -2, -3, -4, -5, -6, -7, -8, -9

select effort level. each level corresponds to an incresingly more
aggressive sequence of strategies for merging nodes of the data flow
graph. (default: 9)

When no <format> is specified, 'dot' is used. When no <format> and <viewer> is
specified, 'xdot' is used to display the schematic (POSIX systems only).

The generated output files are '~/.yosys_viz.dot' and '~/.yosys_viz.<format>',
unless another prefix is specified using -prefix <prefix>.

Yosys on Windows and YosysJS use different defaults: The output is written
to 'show.dot' in the current directory and new viewer is launched each time
the 'show' command is executed.

Note

Help text automatically generated from passes/cmds/viz.cc:820

write_file - write a text to a file¶

yosys> help write_file¶

write_file [options] output_file [input_file]¶

Write the text from the input file to the output file.

-a

Append to output file (instead of overwriting)

Inside a script the input file can also can a here-document:

    write_file hello.txt <<EOT
    Hello World!
    EOT

Note

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