mirrors/yosys
3
0
Fork 0
mirror of https://github.com/YosysHQ/yosys synced 2025-04-12 20:18:20 +00:00
Code Activity

Docs: optimization passes

Browse source 
Working on `opt.rst`.
Replace the hardcoded `opt` psuedo code listing with a `literalinclude` from `/cmd/opt.rst`.
Reorder and update `opt_*` list to match current `opt`.
Expand sub-section titles with the function of the pass (keeping the `:cmd:ref:` part at the end to prevent the Esbonio error in vscode when a heading starts with a directive).
Move comments about `clean` and `;;` being aliases into final `opt` subsection.

Also renames `Test suites` -> `Testing Yosys`.
This commit is contained in:
Krystine Sherwin 2024-01-15 13:15:11 +13:00
parent 9eab5d8b24
commit 9fe3dcda78
No known key found for this signature in database
2 changed files with 58 additions and 58 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

4
docs/source/test_suites.rst
View file

@ -1,5 +1,5 @@
Test suites Testing Yosys
=========== =============
.. todo:: more about the included test suite .. todo:: more about the included test suite

112
docs/source/using_yosys/synthesis/opt.rst
View file

@ -1,43 +1,28 @@
Optimization passes Optimization passes
=================== ===================
.. todo:: check text context, also check the optimization passes still do what they say
Yosys employs a number of optimizations to generate better and cleaner results. Yosys employs a number of optimizations to generate better and cleaner results.
This chapter outlines these optimizations. This chapter outlines these optimizations.
The :cmd:ref:`opt` pass .. todo:: "outlines these optimizations" or "outlines *some*.."?
--------------------------
The :cmd:ref:`opt` macro command
--------------------------------
The Yosys pass :cmd:ref:`opt` runs a number of simple optimizations. This The Yosys pass :cmd:ref:`opt` runs a number of simple optimizations. This
includes removing unused signals and cells and const folding. It is recommended includes removing unused signals and cells and const folding. It is recommended
to run this pass after each major step in the synthesis script. At the time of to run this pass after each major step in the synthesis script. As listed in
this writing the :cmd:ref:`opt` pass executes the following passes that each :doc:`/cmd/opt`, this macro command calls the following ``opt_*`` commands:
perform a simple optimization:
.. code-block:: yoscrypt .. literalinclude:: /cmd/opt.rst
:language: yoscrypt
:start-after: following order:
:end-at: while <changed design>
:dedent:
:caption: Passes called by :cmd:ref:`opt`
opt_expr # const folding and simple expression rewriting Const folding and simple expression rewriting - :cmd:ref:`opt_expr`
opt_merge -nomux # merging identical cells ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
do
opt_muxtree # remove never-active branches from multiplexer tree
opt_reduce # consolidate trees of boolean ops to reduce functions
opt_merge # merging identical cells
opt_rmdff # remove/simplify registers with constant inputs
opt_clean # remove unused objects (cells, wires) from design
opt_expr # const folding and simple expression rewriting
while [changed design]
The command :cmd:ref:`clean` can be used as alias for :cmd:ref:`opt_clean`. And
``;;`` can be used as shortcut for :cmd:ref:`clean`. For example:
.. code-block:: yoscrypt
hierarchy; proc; opt; memory; opt_expr;; fsm;;
The :cmd:ref:`opt_expr` pass
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This pass performs const folding on the internal combinational cell types This pass performs const folding on the internal combinational cell types
described in :doc:`/yosys_internals/formats/cell_library`. This means a cell described in :doc:`/yosys_internals/formats/cell_library`. This means a cell
@ -90,8 +75,20 @@ The :cmd:ref:`opt_expr` pass is very conservative regarding optimizing ``$mux``
cells, as these cells are often used to model decision-trees and breaking these cells, as these cells are often used to model decision-trees and breaking these
trees can interfere with other optimizations. trees can interfere with other optimizations.
The :cmd:ref:`opt_muxtree` pass Merging identical cells - :cmd:ref:`opt_merge`
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This pass performs trivial resource sharing. This means that this pass
identifies cells with identical inputs and replaces them with a single instance
of the cell.
The option ``-nomux`` can be used to disable resource sharing for multiplexer
cells (``$mux`` and ``$pmux``.) This can be useful as it prevents multiplexer
trees to be merged, which might prevent :cmd:ref:`opt_muxtree` to identify
possible optimizations.
Removing never-active branches from multiplexer tree - :cmd:ref:`opt_muxtree`
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This pass optimizes trees of multiplexer cells by analyzing the select inputs. This pass optimizes trees of multiplexer cells by analyzing the select inputs.
Consider the following simple example: Consider the following simple example:
@ -108,8 +105,8 @@ multiplexer and 0 for the inner multiplexer. The :cmd:ref:`opt_muxtree` pass
detects this contradiction and replaces the inner multiplexer with a constant 1, detects this contradiction and replaces the inner multiplexer with a constant 1,
yielding the logic for ``y = a ? 1 : 3``. yielding the logic for ``y = a ? 1 : 3``.
The :cmd:ref:`opt_reduce` pass Simplifying large MUXes and AND/OR gates - :cmd:ref:`opt_reduce`
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This is a simple optimization pass that identifies and consolidates identical This is a simple optimization pass that identifies and consolidates identical
input bits to ``$reduce_and`` and ``$reduce_or`` cells. It also sorts the input input bits to ``$reduce_and`` and ``$reduce_or`` cells. It also sorts the input
@ -126,38 +123,36 @@ Lastly this pass consolidates trees of ``$reduce_and`` cells and trees of
These three simple optimizations are performed in a loop until a stable result These three simple optimizations are performed in a loop until a stable result
is produced. is produced.
The ``opt_rmdff`` pass Merging mutually exclusive cells with shared inputs - :cmd:ref:`opt_share`
~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. TODO:: Update to ``opt_dff`` .. TODO:: ``opt_share``
Performing DFF optimizations - :cmd:ref:`opt_dff`
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This pass identifies single-bit d-type flip-flops (``$_DFF_``, ``$dff``, and This pass identifies single-bit d-type flip-flops (``$_DFF_``, ``$dff``, and
``$adff`` cells) with a constant data input and replaces them with a constant ``$adff`` cells) with a constant data input and replaces them with a constant
driver. driver. It can also merge clock enables and synchronous reset multiplexers,
removing unused control inputs.
The :cmd:ref:`opt_clean` pass Called with ``-nodffe`` and ``-nosdff``, this pass is used to prepare a design
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ for :doc:`/using_yosys/synthesis/fsm`.
Removing unused cells and wires - :cmd:ref:`opt_clean` pass
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This pass identifies unused signals and cells and removes them from the design. This pass identifies unused signals and cells and removes them from the design.
It also creates an ``\unused_bits`` attribute on wires with unused bits. This It also creates an ``\unused_bits`` attribute on wires with unused bits. This
attribute can be used for debugging or by other optimization passes. attribute can be used for debugging or by other optimization passes.
The :cmd:ref:`opt_merge` pass
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This pass performs trivial resource sharing. This means that this pass
identifies cells with identical inputs and replaces them with a single instance
of the cell.
The option ``-nomux`` can be used to disable resource sharing for multiplexer
cells (``$mux`` and ``$pmux``.) This can be useful as it prevents multiplexer
trees to be merged, which might prevent :cmd:ref:`opt_muxtree` to identify
possible optimizations.
Example Example
~~~~~~~ ~~~~~~~
.. todo:: describe ``opt`` images .. todo:: describe ``opt`` images
and/or replace with an example image showing before/after of each ``opt_*``
command
.. figure:: /_images/code_examples/synth_flow/opt_01.* .. figure:: /_images/code_examples/synth_flow/opt_01.*
:class: width-helper :class: width-helper
@ -214,11 +209,16 @@ It is generally a good idea to call :cmd:ref:`opt` before inherently expensive
commands such as :cmd:ref:`sat` or :cmd:ref:`freduce`, as the possible gain is commands such as :cmd:ref:`sat` or :cmd:ref:`freduce`, as the possible gain is
much higher in these cases as the possible loss. much higher in these cases as the possible loss.
The :cmd:ref:`clean` command on the other hand is very fast and many commands The :cmd:ref:`clean` command, which is an alias for :cmd:ref:`opt_clean` with
leave a mess (dangling signal wires, etc). For example, most commands do not fewer outputs, on the other hand is very fast and many commands leave a mess
remove any wires or cells. They just change the connections and depend on a (dangling signal wires, etc). For example, most commands do not remove any wires
later call to clean to get rid of the now unused objects. So the occasional or cells. They just change the connections and depend on a later call to clean
``;;`` is a good idea in every synthesis script. to get rid of the now unused objects. So the occasional ``;;``, which itself is
an alias for :cmd:ref:`clean`, is a good idea in every synthesis script, e.g:
.. code-block:: yoscrypt
hierarchy; proc; opt; memory; opt_expr;; fsm;;
Other optimizations Other optimizations
------------------- -------------------