Internal commands for developers

example_dt - drivertools example

yosys> help example_dt

Warning

This command is intended for internal developer use only

TODO: add help message

Note

Help text automatically generated from passes/cmds/example_dt.cc:24

internal_stats - print internal statistics

yosys> help internal_stats

Warning

This command is experimental

Warning

This command is intended for internal developer use only

Print internal statistics for developers (experimental)

Note

Help text automatically generated from passes/cmds/internal_stats.cc:72

test_abcloop - automatically test handling of loops in abc command

yosys> help test_abcloop

Warning

This command is intended for internal developer use only

test_abcloop [options]
Test handling of logic loops in ABC.
-n {integer}
create this number of circuits and test them (default = 100).
-s {positive_integer}
use this value as rng seed value (default = unix time).

Note

Help text automatically generated from passes/tests/test_abcloop.cc:246

test_autotb - generate simple test benches

yosys> help test_autotb

Warning

This command is intended for internal developer use only

test_autotb [options] [filename]
Automatically create primitive Verilog test benches for all modules in the
design. The generated testbenches toggle the input pins of the module in
a semi-random manner and dumps the resulting output signals.

This can be used to check the synthesis results for simple circuits by
comparing the testbench output for the input files and the synthesis results.

The backend automatically detects clock signals. Additionally a signal can
be forced to be interpreted as clock signal by setting the attribute
'gentb_clock' on the signal.

The attribute 'gentb_constant' can be used to force a signal to a constant
value after initialization. This can e.g. be used to force a reset signal
low in order to explore more inner states in a state machine.

The attribute 'gentb_skip' can be attached to modules to suppress testbench
generation.
-n <int>
number of iterations the test bench should run (default = 1000)
-seed <int>
seed used for pseudo-random number generation (default = 0).
a value of 0 will cause an arbitrary seed to be chosen, based on
the current system time.

Note

Help text automatically generated from passes/tests/test_autotb.cc:329

test_cell - automatically test the implementation of a cell type

yosys> help test_cell

Warning

This command is intended for internal developer use only

test_cell [options] {cell-types}
Tests the internal implementation of the given cell type (for example '$add')
by comparing SAT solver, EVAL and TECHMAP implementations of the cell types..

Run with 'all' instead of a cell type to run the test on all supported
cell types. Use for example 'all /$add' for all cell types except $add.
-n {integer}
create this number of cell instances and test them (default = 100).
-s {positive_integer}
use this value as rng seed value (default = unix time).
-f {rtlil_file}
don't generate circuits. instead load the specified RTLIL file.
-w {filename_prefix}
don't test anything. just generate the circuits and write them
to RTLIL files with the specified prefix
-map {filename}
pass this option to techmap.
-simlib
use "techmap -D SIMLIB_NOCHECKS -map +/simlib.v -max_iter 2 -autoproc"
-aigmap
instead of calling "techmap", call "aigmap"
-muxdiv
when creating test benches with dividers, create an additional mux
to mask out the division-by-zero case
-script {script_file}
instead of calling "techmap", call "script {script_file}".
-const
set some input bits to random constant values
-nosat
do not check SAT model or run SAT equivalence checking
-noeval
do not check const-eval models
-noopt
do not opt tecchmapped design
-edges
test cell edges db creator against sat-based implementation
-v
print additional debug information to the console
-vlog {filename}
create a Verilog test bench to test simlib and write_verilog
-bloat {factor}
increase cell size limits b{factor} times where possible
-check_cost
check if the estimated cell cost is a valid upper bound for
the techmapped cell count

Note

Help text automatically generated from passes/tests/test_cell.cc:806

test_generic - test the generic compute graph

yosys> help test_generic

Warning

This command is intended for internal developer use only

TODO: add help message

Note

Help text automatically generated from backends/functional/test_generic.cc:119

test_pmgen - test pass for pmgen

yosys> help test_pmgen

Warning

This command is intended for internal developer use only

test_pmgen -reduce_chain [options] [selection]
Demo for recursive pmgen patterns. Map chains of AND/OR/XOR to $reduce_*.
test_pmgen -reduce_tree [options] [selection]
Demo for recursive pmgen patterns. Map trees of AND/OR/XOR to $reduce_*.
test_pmgen -eqpmux [options] [selection]
Demo for recursive pmgen patterns. Optimize EQ/NE/PMUX circuits.
test_pmgen -generate [options] <pattern_name>
Create modules that match the specified pattern.

Note

Help text automatically generated from passes/pmgen/test_pmgen.cc:120

Writing command help

  • use chformal as an example

  • generated help content below

chformal - change formal constraints of the design

yosys> help chformal
chformal [types] [mode] [options] [selection]

Make changes to the formal constraints of the design. The [types] options the type of constraint to operate on. If none of the following options are given, the command will operate on all constraint types:

-assert

$assert cells, representing assert(...) constraints

-assume

$assume cells, representing assume(...) constraints

-live

$live cells, representing assert(s_eventually ...)

-fair

$fair cells, representing assume(s_eventually ...)

-cover

$cover cells, representing cover() statements

Additionally chformal will operate on $check cells corresponding to the selected constraint types.

Exactly one of the following modes must be specified:

-remove

remove the cells and thus constraints from the design

-early

bypass FFs that only delay the activation of a constraint. When inputs of the bypassed FFs do not remain stable between clock edges, this may result in unexpected behavior.

-delay <N>

delay activation of the constraint by <N> clock cycles

-skip <N>

ignore activation of the constraint in the first <N> clock cycles

-coverenable

add cover statements for the enable signals of the constraints

Note: For the Verific frontend it is currently not guaranteed that a reachable SVA statement corresponds to an active enable signal.

-assert2assume
-assert2cover
-assume2assert
-live2fair
-fair2live

change the roles of cells as indicated. these options can be combined

-lower

convert each $check cell into an $assert, $assume, $live, $fair or $cover cell. If the $check cell contains a message, also produce a $print cell.

Note

Help text automatically generated from passes/cmds/chformal.cc:74

The formatted_help() method

  • PrettyHelp::get_current()

  • PrettyHelp::set_group()

    • used with .. autocmdgroup:: <group>

    • can assign group and return false

    • if no group is set, will try to use source_location and assign group from path to source file

  • return value

    • true means help content added to current PrettyHelp

    • false to use Pass::help()

  • adding content

    • help content is a list of ContentListing nodes, each one having a type, body, and its own list of children ContentListings

    • PrettyHelp::get_root() returns the root ContentListing (type="root")

    • ContentListing::{usage, option, codeblock, paragraph} each add a ContentListing to the current node, with type the same as the method

      • the first argument is the body of the new node

      • usage shows how to call the command (i.e. its “signature”)

      • paragraph content is formatted as a paragraph of text with line breaks added automatically

      • codeblock content is displayed verbatim, use line breaks as desired; takes an optional language argument for assigning the language in RST output for code syntax highlighting (use yoscrypt for yosys script syntax highlighting)

      • option lists a single option for the command, usually starting with a dash (-); takes an optional second argument which adds a paragraph node as a means of description

    • ContentListing::open_usage creates and returns a new usage node, can be used to e.g. add text/options specific to a given usage of the command

    • ContentListing::open_option creates and returns a new option node, can be used to e.g. add multiple paragraphs to an option’s description

    • paragraphs are treated as raw RST, allowing for inline formatting and references as if it were written in the RST file itself

Listing 397 ChformalPass::formatted_help() from passes/cmds/chformal.cc
	bool formatted_help() override {
		auto *help = PrettyHelp::get_current();
		help->set_group("formal");

		auto content_root = help->get_root();

		content_root->usage("chformal [types] [mode] [options] [selection]");
		content_root->paragraph(
			"Make changes to the formal constraints of the design. The [types] options "
			"the type of constraint to operate on. If none of the following options are "
			"given, the command will operate on all constraint types:"
		);

		content_root->option("-assert", "`$assert` cells, representing ``assert(...)`` constraints");
		content_root->option("-assume", "`$assume` cells, representing ``assume(...)`` constraints");
		content_root->option("-live", "`$live` cells, representing ``assert(s_eventually ...)``");
		content_root->option("-fair", "`$fair` cells, representing ``assume(s_eventually ...)``");
		content_root->option("-cover", "`$cover` cells, representing ``cover()`` statements");
		content_root->paragraph(
			"Additionally chformal will operate on `$check` cells corresponding to the "
			"selected constraint types."
		);

		content_root->paragraph("Exactly one of the following modes must be specified:");

		content_root->option("-remove", "remove the cells and thus constraints from the design");
		content_root->option("-early",
			"bypass FFs that only delay the activation of a constraint. When inputs "
			"of the bypassed FFs do not remain stable between clock edges, this may "
			"result in unexpected behavior."
		);
		content_root->option("-delay <N>", "delay activation of the constraint by <N> clock cycles");
		content_root->option("-skip <N>", "ignore activation of the constraint in the first <N> clock cycles");
		auto cover_option = content_root->open_option("-coverenable");
		cover_option->paragraph(
			"add cover statements for the enable signals of the constraints"
		);
#ifdef YOSYS_ENABLE_VERIFIC
		cover_option->paragraph(
			"Note: For the Verific frontend it is currently not guaranteed that a "
			"reachable SVA statement corresponds to an active enable signal."
		);
#endif
		content_root->option("-assert2assume");
		content_root->option("-assert2cover");
		content_root->option("-assume2assert");
		content_root->option("-live2fair");
		content_root->option("-fair2live", "change the roles of cells as indicated. these options can be combined");
		content_root->option("-lower",
			"convert each $check cell into an $assert, $assume, $live, $fair or "
			"$cover cell. If the $check cell contains a message, also produce a "
			"$print cell."
		);
		return true;
	}

Dumping command help to json

  • help -dump-cells-json cmds.json

    • generates a ContentListing for each command registered in Yosys

    • tries to parse unformatted Pass::help() output if Pass::formatted_help() is unimplemented or returns false

      • if a line starts with four spaces followed by the name of the command then a space, it is parsed as a signature (usage node)

      • if a line is indented and starts with a dash (-), it is parsed as an option

      • anything else is parsed as a codeblock and added to either the root node or the current option depending on the indentation

    • dictionary of command name to ContentListing

      • uses ContentListing::to_json() recursively for each node in root

      • root node used for source location of class definition

      • includes flags set during pass constructor (e.g. experimental_flag set by Pass::experimental())

      • also title (short_help argument in Pass::Pass), group, and class name

    • dictionary of group name to list of commands in that group

  • used by sphinx autodoc to generate help content

Listing 398 chformal in generated cmds.json
    "chformal": {
      "title": "change formal constraints of the design",
      "content": [
        {"body": "chformal [types] [mode] [options] [selection]", "content": [], "options": {}, "source_file": "passes/cmds/chformal.cc", "source_line": 82, "type": "usage"},
        {"body": "Make changes to the formal constraints of the design. The [types] options the type of constraint to operate on. If none of the following options are given, the command will operate on all constraint types:", "content": [], "options": {}, "source_file": "passes/cmds/chformal.cc", "source_line": 83, "type": "text"},
        {"body": "-assert", "content": [{"body": "`$assert` cells, representing ``assert(...)`` constraints", "content": [], "options": {}, "source_file": "passes/cmds/chformal.cc", "source_line": 89, "type": "text"}], "options": {}, "source_file": "kernel/log_help.cc", "source_line": 47, "type": "option"},
        {"body": "-assume", "content": [{"body": "`$assume` cells, representing ``assume(...)`` constraints", "content": [], "options": {}, "source_file": "passes/cmds/chformal.cc", "source_line": 90, "type": "text"}], "options": {}, "source_file": "kernel/log_help.cc", "source_line": 47, "type": "option"},
        {"body": "-live", "content": [{"body": "`$live` cells, representing ``assert(s_eventually ...)``", "content": [], "options": {}, "source_file": "passes/cmds/chformal.cc", "source_line": 91, "type": "text"}], "options": {}, "source_file": "kernel/log_help.cc", "source_line": 47, "type": "option"},
        {"body": "-fair", "content": [{"body": "`$fair` cells, representing ``assume(s_eventually ...)``", "content": [], "options": {}, "source_file": "passes/cmds/chformal.cc", "source_line": 92, "type": "text"}], "options": {}, "source_file": "kernel/log_help.cc", "source_line": 47, "type": "option"},
        {"body": "-cover", "content": [{"body": "`$cover` cells, representing ``cover()`` statements", "content": [], "options": {}, "source_file": "passes/cmds/chformal.cc", "source_line": 93, "type": "text"}], "options": {}, "source_file": "kernel/log_help.cc", "source_line": 47, "type": "option"},
        {"body": "Additionally chformal will operate on `$check` cells corresponding to the selected constraint types.", "content": [], "options": {}, "source_file": "passes/cmds/chformal.cc", "source_line": 94, "type": "text"},
        {"body": "Exactly one of the following modes must be specified:", "content": [], "options": {}, "source_file": "passes/cmds/chformal.cc", "source_line": 99, "type": "text"},
        {"body": "-remove", "content": [{"body": "remove the cells and thus constraints from the design", "content": [], "options": {}, "source_file": "passes/cmds/chformal.cc", "source_line": 101, "type": "text"}], "options": {}, "source_file": "kernel/log_help.cc", "source_line": 47, "type": "option"},
        {"body": "-early", "content": [{"body": "bypass FFs that only delay the activation of a constraint. When inputs of the bypassed FFs do not remain stable between clock edges, this may result in unexpected behavior.", "content": [], "options": {}, "source_file": "passes/cmds/chformal.cc", "source_line": 102, "type": "text"}], "options": {}, "source_file": "kernel/log_help.cc", "source_line": 47, "type": "option"},
        {"body": "-delay <N>", "content": [{"body": "delay activation of the constraint by <N> clock cycles", "content": [], "options": {}, "source_file": "passes/cmds/chformal.cc", "source_line": 107, "type": "text"}], "options": {}, "source_file": "kernel/log_help.cc", "source_line": 47, "type": "option"},
        {"body": "-skip <N>", "content": [{"body": "ignore activation of the constraint in the first <N> clock cycles", "content": [], "options": {}, "source_file": "passes/cmds/chformal.cc", "source_line": 108, "type": "text"}], "options": {}, "source_file": "kernel/log_help.cc", "source_line": 47, "type": "option"},
        {"body": "-coverenable", "content": [{"body": "add cover statements for the enable signals of the constraints", "content": [], "options": {}, "source_file": "passes/cmds/chformal.cc", "source_line": 110, "type": "text"}, {"body": "Note: For the Verific frontend it is currently not guaranteed that a reachable SVA statement corresponds to an active enable signal.", "content": [], "options": {}, "source_file": "passes/cmds/chformal.cc", "source_line": 114, "type": "text"}], "options": {}, "source_file": "passes/cmds/chformal.cc", "source_line": 109, "type": "option"},
        {"body": "-assert2assume", "content": [], "options": {}, "source_file": "kernel/log_help.cc", "source_line": 47, "type": "option"},
        {"body": "-assert2cover", "content": [], "options": {}, "source_file": "kernel/log_help.cc", "source_line": 47, "type": "option"},
        {"body": "-assume2assert", "content": [], "options": {}, "source_file": "kernel/log_help.cc", "source_line": 47, "type": "option"},
        {"body": "-live2fair", "content": [], "options": {}, "source_file": "kernel/log_help.cc", "source_line": 47, "type": "option"},
        {"body": "-fair2live", "content": [{"body": "change the roles of cells as indicated. these options can be combined", "content": [], "options": {}, "source_file": "passes/cmds/chformal.cc", "source_line": 123, "type": "text"}], "options": {}, "source_file": "kernel/log_help.cc", "source_line": 47, "type": "option"},
        {"body": "-lower", "content": [{"body": "convert each $check cell into an $assert, $assume, $live, $fair or $cover cell. If the $check cell contains a message, also produce a $print cell.", "content": [], "options": {}, "source_file": "passes/cmds/chformal.cc", "source_line": 124, "type": "text"}], "options": {}, "source_file": "kernel/log_help.cc", "source_line": 47, "type": "option"}
      ],
      "group": "formal",
      "source_file": "passes/cmds/chformal.cc",
      "source_line": 74,
      "source_func": "ChformalPass",
      "experimental_flag": false,
      "internal_flag": false
    },

Note

Synthesis command scripts are special cased

If the final block of help output starts with the string "The following commands are executed by this synthesis command:n", then the rest of the code block is formatted as yoscrypt (e.g. synth_ice40). The caveat here is that if the script() calls run() on any commands prior to the first check_label then the auto detection will break and revert to unformatted code (e.g. synth_fabulous).

Command line rendering

  • if Pass::formatted_help() returns true, will call PrettyHelp::log_help()

    • traverse over the children of the root node and render as plain text

    • effectively the reverse of converting unformatted Pass::help() text

    • lines are broken at 80 characters while maintaining indentation (controlled by MAX_LINE_LEN in kernel/log_help.cc)

    • each line is broken into words separated by spaces, if a given word starts and ends with backticks they will be stripped

  • if it returns false it will call Pass::help() which should call log() directly to print and format help text

    • if Pass::help() is not overridden then a default message about missing help will be displayed

-- Running command `help chformal' --

    chformal [types] [mode] [options] [selection] 

Make changes to the formal constraints of the design. The [types] options the 
type of constraint to operate on. If none of the following options are given, 
the command will operate on all constraint types: 

    -assert 
        $assert cells, representing assert(...) constraints 

    -assume 
        $assume cells, representing assume(...) constraints 

    -live 
        $live cells, representing ``assert(s_eventually ...)`` 

    -fair 
        $fair cells, representing ``assume(s_eventually ...)`` 

    -cover 
        $cover cells, representing cover() statements 

Additionally chformal will operate on $check cells corresponding to the 
selected constraint types. 

Exactly one of the following modes must be specified: 

    -remove 
        remove the cells and thus constraints from the design 

    -early 
        bypass FFs that only delay the activation of a constraint. When inputs 
        of the bypassed FFs do not remain stable between clock edges, this may result 
        in unexpected behavior. 

    -delay <N> 
        delay activation of the constraint by <N> clock cycles 

    -skip <N> 
        ignore activation of the constraint in the first <N> clock cycles 

    -coverenable 
        add cover statements for the enable signals of the constraints 

        Note: For the Verific frontend it is currently not guaranteed that a 
        reachable SVA statement corresponds to an active enable signal. 

    -assert2assume 
    -assert2cover 
    -assume2assert 
    -live2fair 
    -fair2live 
        change the roles of cells as indicated. these options can be combined 

    -lower 
        convert each $check cell into an $assert, $assume, $live, $fair or 
        $cover cell. If the $check cell contains a message, also produce a $print 
        cell.

RST generated from autocmd

  • below is the raw RST output from autocmd (YosysCmdDocumenter class in docs/util/cmd_documenter.py) for chformal command

  • heading will be rendered as a subheading of the most recent heading (see chformal autocmd above rendered under Writing command help)

  • .. cmd:def:: <cmd> line is indexed for cross references with :cmd:ref: directive (chformal autocmd above uses :noindex: option so that chformal still links to the correct location)

    • :title: option controls text that appears when hovering over the chformal link

  • commands with warning flags (experimental or internal) add a .. warning block before any of the help content

  • if a command has no source_location the .. note at the bottom will instead link to Other commands

Listing 399 Generated rst for .. autocmd:: chformal
chformal - change formal constraints of the design
##################################################
.. cmd:def:: chformal
   :title: change formal constraints of the design

   .. cmd:usage:: chformal::chformal [types] [mode] [options] [selection]

   Make changes to the formal constraints of the design. The [types] options the type of constraint to operate on. If none of the following options are given, the command will operate on all constraint types:

   :option -assert:
      `$assert` cells, representing ``assert(...)`` constraints

   :option -assume:
      `$assume` cells, representing ``assume(...)`` constraints

   :option -live:
      `$live` cells, representing ``assert(s_eventually ...)``

   :option -fair:
      `$fair` cells, representing ``assume(s_eventually ...)``

   :option -cover:
      `$cover` cells, representing ``cover()`` statements

   Additionally chformal will operate on `$check` cells corresponding to the selected constraint types.

   Exactly one of the following modes must be specified:

   :option -remove:
      remove the cells and thus constraints from the design

   :option -early:
      bypass FFs that only delay the activation of a constraint. When inputs of the bypassed FFs do not remain stable between clock edges, this may result in unexpected behavior.

   :option -delay <N>:
      delay activation of the constraint by <N> clock cycles

   :option -skip <N>:
      ignore activation of the constraint in the first <N> clock cycles

   :option -coverenable:
      add cover statements for the enable signals of the constraints

      Note: For the Verific frontend it is currently not guaranteed that a reachable SVA statement corresponds to an active enable signal.

   :option -assert2assume:
   :option -assert2cover:
   :option -assume2assert:
   :option -live2fair:
   :option -fair2live:
      change the roles of cells as indicated. these options can be combined

   :option -lower:
      convert each $check cell into an $assert, $assume, $live, $fair or $cover cell. If the $check cell contains a message, also produce a $print cell.


   .. note:: Help text automatically generated from :file:`passes/cmds/chformal.cc:74`