riscv
/
yosys
mirror of https://github.com/YosysHQ/yosys.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

Docs: optimization passes 

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

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

@ -1,43 +1,28 @@
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.
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
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
this writing the :cmd:ref:`opt` pass executes the following passes that each
perform a simple optimization:
to run this pass after each major step in the synthesis script. As listed in
:doc:`/cmd/opt`, this macro command calls the following ``opt_*`` commands:
.. 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
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
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Const folding and simple expression rewriting - :cmd:ref:`opt_expr`
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This pass performs const folding on the internal combinational cell types
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
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.
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,
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
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
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
``$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.
It also creates an ``\unused_bits`` attribute on wires with unused bits. This
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
~~~~~~~
.. 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.*
: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
much higher in these cases as the possible loss.
The :cmd:ref:`clean` command on the other hand is very fast and many commands
leave a mess (dangling signal wires, etc). For example, most commands do not
remove any wires or cells. They just change the connections and depend on a
later call to clean to get rid of the now unused objects. So the occasional
``;;`` is a good idea in every synthesis script.
The :cmd:ref:`clean` command, which is an alias for :cmd:ref:`opt_clean` with
fewer outputs, on the other hand is very fast and many commands leave a mess
(dangling signal wires, etc). For example, most commands do not remove any wires
or cells. They just change the connections and depend on a later call to clean
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
-------------------