Optimization passes

clean - remove unused cells and wires

yosys> help clean

clean [options] [selection]

This is identical to 'opt_clean', but less verbose.

When commands are separated using the ';;' token, this command will be executed
between the commands.

When commands are separated using the ';;;' token, this command will be executed
in -purge mode between the commands.

Note

Help text automatically generated from passes/opt/opt_clean.cc:729

muxpack - $mux/$pmux cascades to $pmux

yosys> help muxpack

muxpack [selection]

This pass converts cascaded chains of $pmux cells (e.g. those create from case
constructs) and $mux cells (e.g. those created by if-else constructs) into
$pmux cells.

This optimisation is conservative --- it will only pack $mux or $pmux cells
whose select lines are driven by '$eq' cells with other such cells if it can be
certain that their select inputs are mutually exclusive.

Note

Help text automatically generated from passes/opt/muxpack.cc:328

onehot - optimize $eq cells for onehot signals

yosys> help onehot

onehot [options] [selection]

This pass optimizes $eq cells that compare one-hot signals against constants

-v, -vv

verbose output

Note

Help text automatically generated from passes/opt/pmux2shiftx.cc:733

opt - perform simple optimizations

yosys> help opt

opt [options] [selection]

This pass calls all the other opt_* passes in a useful order. This performs
a series of trivial optimizations and cleanups. This pass executes the other
passes in the following order:

    opt_expr [-mux_undef] [-mux_bool] [-undriven] [-noclkinv] [-fine] [-full] [-keepdc]
    opt_merge [-share_all] -nomux

    do
        opt_muxtree
        opt_reduce [-fine] [-full]
        opt_merge [-share_all]
        opt_share  (-full only)
        opt_dff [-nodffe] [-nosdff] [-keepdc] [-sat]  (except when called with -noff)
        opt_hier (-hier only)
        opt_clean [-purge]
        opt_expr [-mux_undef] [-mux_bool] [-undriven] [-noclkinv] [-fine] [-full] [-keepdc]
    while <changed design>

When called with -fast the following script is used instead:

    do
        opt_expr [-mux_undef] [-mux_bool] [-undriven] [-noclkinv] [-fine] [-full] [-keepdc]
        opt_merge [-share_all]
        opt_dff [-nodffe] [-nosdff] [-keepdc] [-sat]  (except when called with -noff)
        opt_hier (-hier only)
        opt_clean [-purge]
    while <changed design in opt_dff>

Note: Options in square brackets (such as [-keepdc]) are passed through to
the opt_* commands when given to 'opt'.

Note

Help text automatically generated from passes/opt/opt.cc:29

opt_clean - remove unused cells and wires

yosys> help opt_clean

opt_clean [options] [selection]

This pass identifies wires and cells that are unused and removes them. Other
passes often remove cells but leave the wires in the design or reconnect the
wires but leave the old cells in the design. This pass can be used to clean up
after the passes that do the actual work.

This pass only operates on completely selected modules without processes.

-purge

also remove internal nets if they have a public name

Note

Help text automatically generated from passes/opt/opt_clean.cc:662

opt_demorgan - Optimize reductions with DeMorgan equivalents

yosys> help opt_demorgan

opt_demorgan [selection]

This pass pushes inverters through $reduce_* cells if this will reduce the
overall gate count of the circuit

Note

Help text automatically generated from passes/opt/opt_demorgan.cc:175

opt_dff - perform DFF optimizations

yosys> help opt_dff

opt_dff [-nodffe] [-nosdff] [-keepdc] [-sat] [selection]

This pass converts flip-flops to a more suitable type by merging clock enables
and synchronous reset multiplexers, removing unused control inputs, or
potentially removes the flip-flop altogether, converting it to a constant
driver.

-nodffe

disables dff -> dffe conversion, and other transforms recognizing clock
enable

-nosdff

disables dff -> sdff conversion, and other transforms recognizing sync
resets

-simple-dffe

only enables clock enable recognition transform for obvious cases

-sat

additionally invoke SAT solver to detect and remove flip-flops (with
non-constant inputs) that can also be replaced with a constant driver

-keepdc

some optimizations change the behavior of the circuit with respect to
don't-care bits. for example in 'a+0' a single x-bit in 'a' will cause
all result bits to be set to x. this behavior changes when 'a+0' is
replaced by 'a'. the -keepdc option disables all such optimizations.

Note

Help text automatically generated from passes/opt/opt_dff.cc:913

opt_expr - perform const folding and simple expression rewriting

yosys> help opt_expr

opt_expr [options] [selection]

This pass performs const folding on internal cell types with constant inputs.
It also performs some simple expression rewriting.

-mux_undef

remove 'undef' inputs from $mux, $pmux and $_MUX_ cells

-mux_bool

replace $mux cells with inverters or buffers when possible

-undriven

replace undriven nets with undef (x) constants

-noclkinv

do not optimize clock inverters by changing FF types

-fine

perform fine-grain optimizations

-full

alias for -mux_undef -mux_bool -undriven -fine

-keepdc

some optimizations change the behavior of the circuit with respect to
don't-care bits. for example in 'a+0' a single x-bit in 'a' will cause
all result bits to be set to x. this behavior changes when 'a+0' is
replaced by 'a'. the -keepdc option disables all such optimizations.

Note

Help text automatically generated from passes/opt/opt_expr.cc:2277

opt_ffinv - push inverters through FFs

yosys> help opt_ffinv

opt_ffinv [selection]

This pass pushes inverters to the other side of a FF when they can be merged
into LUTs on the other side.

Note

Help text automatically generated from passes/opt/opt_ffinv.cc:236

opt_hier - perform cross-boundary optimization

yosys> help opt_hier

opt_hier [selection]

This pass considers the design hierarchy and propagates unused signals, constant
signals, and tied-together signals across module boundaries to facilitate
optimization. Only the selected modules are affected.

Note this pass changes port semantics on modules which are not the top.

Note

Help text automatically generated from passes/opt/opt_hier.cc:407

opt_lut - optimize LUT cells

yosys> help opt_lut

opt_lut [options] [selection]

This pass combines cascaded $lut cells with unused inputs.

-tech ice40

treat the design as a LUT-mapped circuit for the iCE40 architecture
and preserve connections to SB_CARRY as appropriate

-limit N

only perform the first N combines, then stop. useful for debugging.

Note

Help text automatically generated from passes/opt/opt_lut.cc:527

opt_lut_ins - discard unused LUT inputs

yosys> help opt_lut_ins

opt_lut_ins [options] [selection]

This pass removes unused inputs from LUT cells (that is, inputs that can not
influence the output signal given this LUT's value).  While such LUTs cannot
be directly emitted by ABC, they can be a result of various post-ABC
transformations, such as mapping wide LUTs (not all sub-LUTs will use the
full set of inputs) or optimizations such as xilinx_dffopt.

-tech <technology>

Instead of generic $lut cells, operate on LUT cells specific
to the given technology.  Valid values are: xilinx, lattice, gowin.

Note

Help text automatically generated from passes/opt/opt_lut_ins.cc:27

opt_mem - optimize memories

yosys> help opt_mem

opt_mem [options] [selection]

This pass performs various optimizations on memories in the design.

Note

Help text automatically generated from passes/opt/opt_mem.cc:29

opt_mem_feedback - convert memory read-to-write port feedback paths to write enables

yosys> help opt_mem_feedback

opt_mem_feedback [selection]

This pass detects cases where an asynchronous read port is only connected via
a mux tree to a write port with the same address.  When such a connection is
found, it is replaced with a new condition on an enable signal, allowing
for removal of the read port.

Note

Help text automatically generated from passes/opt/opt_mem_feedback.cc:326

opt_mem_priority - remove priority relations between write ports that can never collide

yosys> help opt_mem_priority

opt_mem_priority [selection]

This pass detects cases where one memory write port has priority over another
even though they can never collide with each other -- ie. there can never be
a situation where a given memory bit is written by both ports at the same
time, for example because of always-different addresses, or mutually exclusive
enable signals. In such cases, the priority relation is removed.

Note

Help text automatically generated from passes/opt/opt_mem_priority.cc:29

opt_mem_widen - optimize memories where all ports are wide

yosys> help opt_mem_widen

opt_mem_widen [options] [selection]

This pass looks for memories where all ports are wide and adjusts the base
memory width up until that stops being the case.

Note

Help text automatically generated from passes/opt/opt_mem_widen.cc:27

opt_merge - consolidate identical cells

yosys> help opt_merge

opt_merge [options] [selection]

This pass identifies cells with identical type and input signals. Such cells
are then merged to one cell.

-nomux

Do not merge MUX cells.

-share_all

Operate on all cell types, not just built-in types.

-keepdc

Do not merge flipflops with don't-care bits in their initial value.

Note

Help text automatically generated from passes/opt/opt_merge.cc:328

opt_muxtree - eliminate dead trees in multiplexer trees

yosys> help opt_muxtree

opt_muxtree [selection]

This pass analyzes the control signals for the multiplexer trees in the design
and identifies inputs that can never be active. It then removes this dead
branches from the multiplexer trees.

This pass only operates on completely selected modules without processes.

Note

Help text automatically generated from passes/opt/opt_muxtree.cc:590

opt_reduce - simplify large MUXes and AND/OR gates

yosys> help opt_reduce

opt_reduce [options] [selection]

This pass performs two interlinked optimizations:

1. it consolidates trees of large AND gates or OR gates and eliminates
duplicated inputs.

2. it identifies duplicated inputs to MUXes and replaces them with a single
input with the original control signals OR'ed together.

-fine

perform fine-grain optimizations

-full

alias for -fine

Note

Help text automatically generated from passes/opt/opt_reduce.cc:612

opt_share - merge mutually exclusive cells of the same type that share an input signal

yosys> help opt_share

opt_share [selection]

This pass identifies mutually exclusive cells of the same type that:
    (a) share an input signal,
    (b) drive the same $mux, $_MUX_, or $pmux multiplexing cell,

allowing the cell to be merged and the multiplexer to be moved from
multiplexing its output to multiplexing the non-shared input signals.

Note

Help text automatically generated from passes/opt/opt_share.cc:339

peepopt - collection of peephole optimizers

yosys> help peepopt

peepopt [options] [selection]

This pass applies a collection of peephole optimizers to the current design.

This pass employs the following rules by default:

   * muldiv - Replace (A*B)/B with A

   * muldiv_c - Replace (A*B)/C with A*(B/C) when C is a const divisible by B.

   * shiftmul - Replace A>>(B*C) with A'>>(B<<K) where C and K are constants
                and A' is derived from A by appropriately inserting padding
                into the signal. (right variant)

                Analogously, replace A<<(B*C) with appropriate selection of
                output bits from A<<(B<<K). (left variant)

   * shiftadd - Replace A>>(B+D) with (A'>>D)>>(B) where D is constant and
                A' is derived from A by padding or cutting inaccessible bits.
                Scratchpad: 'peepopt.shiftadd.max_data_multiple' (default: 2)
                limits the amount of padding to a multiple of the data, 
                to avoid high resource usage from large temporary MUX trees.

If -formalclk is specified it instead employs the following rules:

   * clockgateff - Replace latch based clock gating patterns with a flip-flop
                   based pattern to prevent combinational paths from the
                   output to the enable input after running clk2fflogic.

Note

Help text automatically generated from passes/opt/peepopt.cc:43

pmux2shiftx - transform $pmux cells to $shiftx cells

yosys> help pmux2shiftx

pmux2shiftx [options] [selection]

This pass transforms $pmux cells to $shiftx cells.

-v, -vv

verbose output

-min_density <percentage>

specifies the minimum density for the shifter
default: 50

-min_choices <int>

specified the minimum number of choices for a control signal
default: 3

-onehot ignore|pmux|shiftx

select strategy for one-hot encoded control signals
default: pmux

-norange

disable $sub inference for "range decoders"

Note

Help text automatically generated from passes/opt/pmux2shiftx.cc:192

recover_names - Execute a lossy mapping command and recover original netnames

yosys> help recover_names

recover_names [command]

This pass executes a lossy mapping command and uses a combination of simulation
 to find candidate equivalences and SAT to recover exact original net names.

Note

Help text automatically generated from passes/sat/recover_names.cc:693

share - perform sat-based resource sharing

yosys> help share

share [options] [selection]

This pass merges shareable resources into a single resource. A SAT solver
is used to determine if two resources are share-able.

-force

Per default the selection of cells that is considered for sharing is
narrowed using a list of cell types. With this option all selected
cells are considered for resource sharing.

IMPORTANT NOTE: If the -all option is used then no cells with internal
state must be selected!

-aggressive

Per default some heuristics are used to reduce the number of cells
considered for resource sharing to only large resources. This options
turns this heuristics off, resulting in much more cells being considered
for resource sharing.

-fast

Only consider the simple part of the control logic in SAT solving, resulting
in much easier SAT problems at the cost of maybe missing some opportunities
for resource sharing.

-limit N

Only perform the first N merges, then stop. This is useful for debugging.

-pattern-limit N

Only analyze up to N activation patterns per cell, otherwise assume active.
N is 1000 by default. Higher values may merge more resources at the cost of
more runtime and memory consumption.

Note

Help text automatically generated from passes/opt/share.cc:1516

wreduce - reduce the word size of operations if possible

yosys> help wreduce

wreduce [options] [selection]

This command reduces the word size of operations. For example it will replace
the 32 bit adders in the following code with adders of more appropriate widths:

    module test(input [3:0] a, b, c, output [7:0] y);
        assign y = a + b + c + 1;
    endmodule

Options:

-memx

Do not change the width of memory address ports. Use this options in
flows that use the 'memory_memx' pass.

-mux_undef

remove 'undef' inputs from $mux, $pmux and $_MUX_ cells

-keepdc

Do not optimize explicit don't-care values.

Note

Help text automatically generated from passes/opt/wreduce.cc:522