mirrors/yosys
3
0
Fork 0
mirror of https://github.com/YosysHQ/yosys synced 2025-06-06 06:03:23 +00:00
Code Activity

Removing typical phases doc

Browse source 
Moved remaining content into relevant places.
Added `load_design.rst` to more scripting.
Split fsm handling and abc out of optimization passes. Also moved things around to match the general flow previously described.
Changed generic `synth` for `prep` instead.
This commit is contained in:
Krystine Sherwin 2023-12-07 17:14:21 +13:00
parent f9ce3d1c26
commit 1e3b90ae56
No known key found for this signature in database
11 changed files with 568 additions and 666 deletions
Download patch file Download diff file Expand all files Collapse all files

9
docs/source/using_yosys/more_scripting/index.rst
View file

@ -2,8 +2,9 @@ More scripting
--------------
.. toctree::
:maxdepth: 3
:maxdepth: 3
selections
interactive_investigation
troubleshooting
load_design
selections
interactive_investigation
troubleshooting

37
docs/source/using_yosys/more_scripting/load_design.rst Normal file
View file

@ -0,0 +1,37 @@
Loading a design
~~~~~~~~~~~~~~~~
keyword: Frontends
- :doc:`/cmd/read_verilog`
.. todo:: include ``read_verilog <<EOF``, also other methods of loading designs
.. code-block:: yoscrypt
read_verilog file1.v
read_verilog -I include_dir -D enable_foo -D WIDTH=12 file2.v
read_verilog -lib cell_library.v
verilog_defaults -add -I include_dir
read_verilog file3.v
read_verilog file4.v
verilog_defaults -clear
verilog_defaults -push
verilog_defaults -add -I include_dir
read_verilog file5.v
read_verilog file6.v
verilog_defaults -pop
Others:
- :doc:`/cmd/read`
- `GHDL plugin`_ for VHDL
- :doc:`/cmd/read_rtlil` (direct textual representation of Yosys internal state)
- :doc:`/cmd/read_aiger`
- :doc:`/cmd/read_blif`
- :doc:`/cmd/read_json`
- :doc:`/cmd/read_liberty`
.. _GHDL plugin: https://github.com/ghdl/ghdl-yosys-plugin

39
docs/source/using_yosys/synthesis/abc.rst Normal file
View file

@ -0,0 +1,39 @@
The :cmd:ref:`abc` command
~~~~~~~~~~~~~~~~~~~~~~~~~~
.. todo:: discuss abc (more stable) vs abc9 (newer, possibly better)
The :cmd:ref:`abc` command provides an interface to ABC_, an open source tool
for low-level logic synthesis.
.. _ABC: http://www.eecs.berkeley.edu/~alanmi/abc/
The :cmd:ref:`abc` command processes a netlist of internal gate types and can
perform:
- logic minimization (optimization)
- mapping of logic to standard cell library (liberty format)
- mapping of logic to k-LUTs (for FPGA synthesis)
Optionally :cmd:ref:`abc` can process registers from one clock domain and
perform sequential optimization (such as register balancing).
ABC is also controlled using scripts. An ABC script can be specified to use more
advanced ABC features. It is also possible to write the design with
:cmd:ref:`write_blif` and load the output file into ABC outside of Yosys.
Example
^^^^^^^
.. todo:: describe ``abc`` images
.. literalinclude:: /code_examples/synth_flow/abc_01.v
:language: verilog
:caption: ``docs/source/code_examples/synth_flow/abc_01.v``
.. literalinclude:: /code_examples/synth_flow/abc_01.ys
:language: yoscrypt
:caption: ``docs/source/code_examples/synth_flow/abc_01.ys``
.. figure:: /_images/code_examples/synth_flow/abc_01.*
:class: width-helper

186
docs/source/using_yosys/synthesis/opt_passes.rst → docs/source/using_yosys/synthesis/fsm.rst
View file

@ -1,160 +1,26 @@
.. _chapter:opt:
FSM handling
============
Optimization passes
===================
The :cmd:ref:`fsm` command identifies, extracts, optimizes (re-encodes), and
re-synthesizes finite state machines. It again is a macro that calls a series of
other commands:
.. todo:: check text context, also check the optimization passes still do what they say
#. :cmd:ref:`fsm_detect` identifies FSM state registers and marks them
with the ``(* fsm_encoding = "auto" *)`` attribute, if they do not have the
``fsm_encoding`` set already. Mark registers with ``(* fsm_encoding = "none"
*)`` to disable FSM optimization for a register.
#. :cmd:ref:`fsm_extract` replaces the entire FSM (logic and state registers)
with a ``$fsm`` cell.
#. :cmd:ref:`fsm_opt` optimizes the FSM. Called multiple times.
#. :cmd:ref:`fsm_expand` optionally merges additional auxilliary gates into the
``$fsm`` cell.
#. :cmd:ref:`fsm_recode` also optimizes the FSM.
#. :cmd:ref:`fsm_info` logs internal FSM information.
#. :cmd:ref:`fsm_export` optionally exports each FSM to KISS2 files.
#. :cmd:ref:`fsm_map` converts the (optimized) ``$fsm`` cell back to logic and
registers.
Yosys employs a number of optimizations to generate better and cleaner results.
This chapter outlines these optimizations.
Simple optimizations
--------------------
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:
- Once at the beginning of :cmd:ref:`opt`:
- ``opt_expr``
- ``opt_merge -nomux``
- Repeat until result is stable:
- ``opt_muxtree``
- ``opt_reduce``
- ``opt_merge``
- ``opt_rmdff``
- ``opt_clean``
- ``opt_expr``
The following section describes each of the ``opt_`` passes.
The :cmd:ref:`opt_expr` pass
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This pass performs const folding on the internal combinational cell types
described in :doc:`/yosys_internals/formats/cell_library`. This means a cell
with all constant inputs is replaced with the constant value this cell drives.
In some cases this pass can also optimize cells with some constant inputs.
.. table:: Const folding rules for ``$_AND_`` cells as used in :cmd:ref:`opt_expr`.
:name: tab:opt_expr_and
:align: center
========= ========= ===========
A-Input B-Input Replacement
========= ========= ===========
any 0 0
0 any 0
1 1 1
--------- --------- -----------
X/Z X/Z X
1 X/Z X
X/Z 1 X
--------- --------- -----------
any X/Z 0
X/Z any 0
--------- --------- -----------
:math:`a` 1 :math:`a`
1 :math:`b` :math:`b`
========= ========= ===========
.. todo:: How to format table?
:numref:`Table %s <tab:opt_expr_and>` shows the replacement rules used for
optimizing an ``$_AND_`` gate. The first three rules implement the obvious const
folding rules. Note that 'any' might include dynamic values calculated by other
parts of the circuit. The following three lines propagate undef (X) states.
These are the only three cases in which it is allowed to propagate an undef
according to Sec. 5.1.10 of IEEE Std. 1364-2005 :cite:p:`Verilog2005`.
The next two lines assume the value 0 for undef states. These two rules are only
used if no other substitutions are possible in the current module. If other
substitutions are possible they are performed first, in the hope that the 'any'
will change to an undef value or a 1 and therefore the output can be set to
undef.
The last two lines simply replace an ``$_AND_`` gate with one constant-1 input
with a buffer.
Besides this basic const folding the :cmd:ref:`opt_expr` pass can replace 1-bit
wide ``$eq`` and ``$ne`` cells with buffers or not-gates if one input is
constant.
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
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This pass optimizes trees of multiplexer cells by analyzing the select inputs.
Consider the following simple example:
.. code:: verilog
module uut(a, y);
input a;
output [1:0] y = a ? (a ? 1 : 2) : 3;
endmodule
The output can never be 2, as this would require ``a`` to be 1 for the outer
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
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
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
bits to ease identification of shareable ``$reduce_and`` and ``$reduce_or``
cells in other passes.
This pass also identifies and consolidates identical inputs to multiplexer
cells. In this case the new shared select bit is driven using a ``$reduce_or``
cell that combines the original select bits.
Lastly this pass consolidates trees of ``$reduce_and`` cells and trees of
``$reduce_or`` cells to single large ``$reduce_and`` or ``$reduce_or`` cells.
These three simple optimizations are performed in a loop until a stable result
is produced.
The ``opt_rmdff`` pass
~~~~~~~~~~~~~~~~~~~~~~
.. todo:: Update to ``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.
The :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.
FSM extraction and encoding
---------------------------
See also :doc:`/cmd/fsm`.
The fsm pass performs finite-state-machine (FSM) extraction and recoding. The
fsm pass simply executes the following other passes:
@ -328,14 +194,4 @@ only one-hot encoding with all-zero for the reset state is supported.
The fsm_recode pass can also write a text file with the changes performed by it
that can be used when verifying designs synthesized by Yosys using Synopsys
Formality .
Logic optimization
------------------
Yosys can perform multi-level combinational logic optimization on gate-level
netlists using the external program ABC . The abc pass extracts the
combinational gate-level parts of the design, passes it through ABC, and
re-integrates the results. The abc pass can also be used to perform other
operations using ABC, such as technology mapping (see :ref:`sec:techmap_extern`
for details).
Formality.

7
docs/source/using_yosys/synthesis/index.rst
View file

@ -5,6 +5,9 @@ Synthesis in detail
:maxdepth: 3
synth
opt_passes
proc
memory_mapping
fsm
memory
opt
abc

108
docs/source/using_yosys/synthesis/memory_mapping.rst → docs/source/using_yosys/synthesis/memory.rst
View file

@ -1,20 +1,88 @@
.. _chapter:memorymap:
Memory handling
===============
The :cmd:ref:`memory` command
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
In the RTL netlist, memory reads and writes are individual cells. This makes
consolidating the number of ports for a memory easier. The :cmd:ref:`memory`
pass transforms memories to an implementation. Per default that is logic for
address decoders and registers. It also is a macro command that the other common
``memory_*`` commands in a sensible order:
.. todo:: fill out missing :cmd:ref:`memory` subcommands descriptions
#. :cmd:ref:`memory_bmux2rom`
#. :cmd:ref:`memory_dff` merges registers into the memory read- and write cells.
#. :cmd:ref:`memory_share`
#. :cmd:ref:`memory_memx`
#. :cmd:ref:`memory_collect` collects all read and write cells for a memory and
transforms them into one multi-port memory cell.
#. :cmd:ref:`memory_bram`
#. :cmd:ref:`memory_map` takes the multi-port memory cell and transforms it to
address decoder logic and registers.
For more information about :cmd:ref:`memory`, such as disabling certain sub
commands, see :doc:`/cmd/memory`.
Example
-------
.. todo:: describe ``memory`` images
.. figure:: /_images/code_examples/synth_flow/memory_01.*
:class: width-helper
.. literalinclude:: /code_examples/synth_flow/memory_01.ys
:language: yoscrypt
:caption: ``docs/source/code_examples/synth_flow/memory_01.ys``
.. literalinclude:: /code_examples/synth_flow/memory_01.v
:language: verilog
:caption: ``docs/source/code_examples/synth_flow/memory_01.v``
.. figure:: /_images/code_examples/synth_flow/memory_02.*
:class: width-helper
.. literalinclude:: /code_examples/synth_flow/memory_02.v
:language: verilog
:caption: ``docs/source/code_examples/synth_flow/memory_02.v``
.. literalinclude:: /code_examples/synth_flow/memory_02.ys
:language: yoscrypt
:caption: ``docs/source/code_examples/synth_flow/memory_02.ys``
.. _memory_map:
Memory mapping
==============
^^^^^^^^^^^^^^
Documentation for the Yosys :cmd:ref:`memory_libmap` memory mapper. Note that
not all supported patterns are included in this document, of particular note is
that combinations of multiple patterns should generally work. For example,
`Write port with byte enables`_ could be used in conjunction with any of the
simple dual port (SDP) models. In general if a hardware memory definition does
not support a given configuration, additional logic will be instantiated to
guarantee behaviour is consistent with simulation.
.. todo:: :cmd:ref:`memory_libmap` description
Usually it is preferred to use architecture-specific RAM resources for memory.
For example:
.. code-block:: yoscrypt
memory -nomap
memory_libmap -lib my_memory_map.txt
techmap -map my_memory_map.v
memory_map
Supported memory patterns
^^^^^^^^^^^^^^^^^^^^^^^^^
Note that not all supported patterns are included in this document, of
particular note is that combinations of multiple patterns should generally work.
For example, `wbe`_ could be used in conjunction with any of the simple dual
port (SDP) models. In general if a hardware memory definition does not support
a given configuration, additional logic will be instantiated to guarantee
behaviour is consistent with simulation.
See also: `passes/memory/memlib.md <https://github.com/YosysHQ/yosys/blob/master/passes/memory/memlib.md>`_
Additional notes
----------------
Notes
-----
Memory kind selection
~~~~~~~~~~~~~~~~~~~~~
@ -95,7 +163,9 @@ Initial data
Most FPGA targets support initializing all kinds of memory to user-provided values. If explicit
initialization is not used the initial memory value is undefined. Initial data can be provided by
either initial statements writing memory cells one by one of ``$readmemh`` or ``$readmemb`` system
tasks. For an example pattern, see `Synchronous read port with initial value`_.
tasks. For an example pattern, see `sr_init`_.
.. _wbe:
Write port with byte enables
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@ -128,6 +198,8 @@ Write port with byte enables
Simple dual port (SDP) memory patterns
--------------------------------------
.. todo:: assorted enables, e.g. cen, wen+ren
Asynchronous-read SDP
~~~~~~~~~~~~~~~~~~~~~
@ -219,6 +291,8 @@ Synchronous SDP with undefined collision behavior
read_data <= mem[read_addr];
end
.. _sdp_wf:
Synchronous SDP with write-first behavior
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@ -335,6 +409,8 @@ Synchronous single-port RAM with write-first behavior
read_data <= mem[addr];
end
.. _sr_init:
Synchronous read port with initial value
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@ -436,6 +512,8 @@ Asymmetric memory is supported on all targets, but may require emulation circuit
natively supported. Note that when the memory is larger than the underlying block RAM primitive,
hardware asymmetric memory support is likely not to be used even if present as it is more expensive.
.. _wide_sr:
Wide synchronous read port
~~~~~~~~~~~~~~~~~~~~~~~~~~
@ -597,7 +675,7 @@ Patterns only supported with Verific
Synchronous SDP with write-first behavior via blocking assignments
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- Use `Synchronous SDP with write-first behavior`_ for compatibility with Yosys
- Use `sdp_wf`_ for compatibility with Yosys
Verilog frontend.
.. code:: verilog
@ -615,8 +693,8 @@ Synchronous SDP with write-first behavior via blocking assignments
Asymmetric memories via part selection
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- Build wide ports out of narrow ports instead (see `Wide synchronous read
port`_) for compatibility with Yosys Verilog frontend.
- Build wide ports out of narrow ports instead (see `wide_sr`_) for
compatibility with Yosys Verilog frontend.
.. code:: verilog

233
docs/source/using_yosys/synthesis/opt.rst Normal file
View file

@ -0,0 +1,233 @@
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
--------------------------
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:
.. code-block:: yoscrypt
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
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This pass performs const folding on the internal combinational cell types
described in :doc:`/yosys_internals/formats/cell_library`. This means a cell
with all constant inputs is replaced with the constant value this cell drives.
In some cases this pass can also optimize cells with some constant inputs.
.. table:: Const folding rules for ``$_AND_`` cells as used in :cmd:ref:`opt_expr`.
:name: tab:opt_expr_and
:align: center
========= ========= ===========
A-Input B-Input Replacement
========= ========= ===========
any 0 0
0 any 0
1 1 1
--------- --------- -----------
X/Z X/Z X
1 X/Z X
X/Z 1 X
--------- --------- -----------
any X/Z 0
X/Z any 0
--------- --------- -----------
:math:`a` 1 :math:`a`
1 :math:`b` :math:`b`
========= ========= ===========
.. todo:: How to format table?
:numref:`Table %s <tab:opt_expr_and>` shows the replacement rules used for
optimizing an ``$_AND_`` gate. The first three rules implement the obvious const
folding rules. Note that 'any' might include dynamic values calculated by other
parts of the circuit. The following three lines propagate undef (X) states.
These are the only three cases in which it is allowed to propagate an undef
according to Sec. 5.1.10 of IEEE Std. 1364-2005 :cite:p:`Verilog2005`.
The next two lines assume the value 0 for undef states. These two rules are only
used if no other substitutions are possible in the current module. If other
substitutions are possible they are performed first, in the hope that the 'any'
will change to an undef value or a 1 and therefore the output can be set to
undef.
The last two lines simply replace an ``$_AND_`` gate with one constant-1 input
with a buffer.
Besides this basic const folding the :cmd:ref:`opt_expr` pass can replace 1-bit
wide ``$eq`` and ``$ne`` cells with buffers or not-gates if one input is
constant.
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
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This pass optimizes trees of multiplexer cells by analyzing the select inputs.
Consider the following simple example:
.. code:: verilog
module uut(a, y);
input a;
output [1:0] y = a ? (a ? 1 : 2) : 3;
endmodule
The output can never be 2, as this would require ``a`` to be 1 for the outer
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
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
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
bits to ease identification of shareable ``$reduce_and`` and ``$reduce_or``
cells in other passes.
This pass also identifies and consolidates identical inputs to multiplexer
cells. In this case the new shared select bit is driven using a ``$reduce_or``
cell that combines the original select bits.
Lastly this pass consolidates trees of ``$reduce_and`` cells and trees of
``$reduce_or`` cells to single large ``$reduce_and`` or ``$reduce_or`` cells.
These three simple optimizations are performed in a loop until a stable result
is produced.
The ``opt_rmdff`` pass
~~~~~~~~~~~~~~~~~~~~~~
.. todo:: Update to ``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.
The :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
.. figure:: /_images/code_examples/synth_flow/opt_01.*
:class: width-helper
.. literalinclude:: /code_examples/synth_flow/opt_01.ys
:language: yoscrypt
:caption: ``docs/source/code_examples/synth_flow/opt_01.ys``
.. literalinclude:: /code_examples/synth_flow/opt_01.v
:language: verilog
:caption: ``docs/source/code_examples/synth_flow/opt_01.v``
.. figure:: /_images/code_examples/synth_flow/opt_02.*
:class: width-helper
.. literalinclude:: /code_examples/synth_flow/opt_02.ys
:language: yoscrypt
:caption: ``docs/source/code_examples/synth_flow/opt_02.ys``
.. literalinclude:: /code_examples/synth_flow/opt_02.v
:language: verilog
:caption: ``docs/source/code_examples/synth_flow/opt_02.v``
.. figure:: /_images/code_examples/synth_flow/opt_03.*
:class: width-helper
.. literalinclude:: /code_examples/synth_flow/opt_03.ys
:language: yoscrypt
:caption: ``docs/source/code_examples/synth_flow/opt_03.ys``
.. literalinclude:: /code_examples/synth_flow/opt_03.v
:language: verilog
:caption: ``docs/source/code_examples/synth_flow/opt_03.v``
.. figure:: /_images/code_examples/synth_flow/opt_04.*
:class: width-helper
.. literalinclude:: /code_examples/synth_flow/opt_04.v
:language: verilog
:caption: ``docs/source/code_examples/synth_flow/opt_04.v``
.. literalinclude:: /code_examples/synth_flow/opt_04.ys
:language: yoscrypt
:caption: ``docs/source/code_examples/synth_flow/opt_04.ys``
When to use :cmd:ref:`opt` or :cmd:ref:`clean`
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Usually it does not hurt to call :cmd:ref:`opt` after each regular command in
the synthesis script. But it increases the synthesis time, so it is favourable
to only call :cmd:ref:`opt` when an improvement can be achieved.
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.
Other optimizations
-------------------
.. todo:: more on the other optimizations
- :doc:`/cmd/wreduce`
- :doc:`/cmd/peepopt`
- :doc:`/cmd/share`
- :cmd:ref:`abc` and :cmd:ref:`abc9`, see also: :doc:`abc`.

69
docs/source/using_yosys/synthesis/proc.rst
View file

@ -1,4 +1,67 @@
The :cmd:ref:`proc` command
---------------------------
Converting process blocks
~~~~~~~~~~~~~~~~~~~~~~~~~
text
The Verilog frontend converts ``always``-blocks to RTL netlists for the
expressions and "processess" for the control- and memory elements. The
:cmd:ref:`proc` command then transforms these "processess" to netlists of RTL
multiplexer and register cells. It also is a macro command that calls the other
``proc_*`` commands in a sensible order:
#. :cmd:ref:`proc_clean` removes empty branches and processes.
#. :cmd:ref:`proc_rmdead` removes unreachable branches.
#. :cmd:ref:`proc_prune`
#. :cmd:ref:`proc_init` special handling of "initial" blocks.
#. :cmd:ref:`proc_arst` identifies modeling of async resets.
#. :cmd:ref:`proc_rom`
#. :cmd:ref:`proc_mux` converts decision trees to multiplexer networks.
#. :cmd:ref:`proc_dlatch`
#. :cmd:ref:`proc_dff` extracts registers from processes.
#. :cmd:ref:`proc_memwr`
#. :cmd:ref:`proc_clean` this should remove all the processes, provided all went
fine.
After all the ``proc_*`` commands, :yoscrypt:`opt_expr` is called. This can be
disabled by calling :yoscrypt:`proc -noopt`. For more information about
:cmd:ref:`proc`, such as disabling certain sub commands, see :doc:`/cmd/proc`.
Many commands can not operate on modules with "processess" in them. Usually a
call to :cmd:ref:`proc` is the first command in the actual synthesis procedure
after design elaboration.
Example
^^^^^^^
.. todo:: describe ``proc`` images
.. literalinclude:: /code_examples/synth_flow/proc_01.v
:language: verilog
:caption: ``docs/source/code_examples/synth_flow/proc_01.v``
.. literalinclude:: /code_examples/synth_flow/proc_01.ys
:language: yoscrypt
:caption: ``docs/source/code_examples/synth_flow/proc_01.ys``
.. figure:: /_images/code_examples/synth_flow/proc_01.*
:class: width-helper
.. figure:: /_images/code_examples/synth_flow/proc_02.*
:class: width-helper
.. literalinclude:: /code_examples/synth_flow/proc_02.v
:language: verilog
:caption: ``docs/source/code_examples/synth_flow/proc_02.v``
.. literalinclude:: /code_examples/synth_flow/proc_02.ys
:language: yoscrypt
:caption: ``docs/source/code_examples/synth_flow/proc_02.ys``
.. figure:: /_images/code_examples/synth_flow/proc_03.*
:class: width-helper
.. literalinclude:: /code_examples/synth_flow/proc_03.ys
:language: yoscrypt
:caption: ``docs/source/code_examples/synth_flow/proc_03.ys``
.. literalinclude:: /code_examples/synth_flow/proc_03.v
:language: verilog
:caption: ``docs/source/code_examples/synth_flow/proc_03.v``

31
docs/source/using_yosys/synthesis/synth.rst
View file

@ -1,15 +1,5 @@
Introduction to synthesis
-------------------------
The generic ``synth``
~~~~~~~~~~~~~~~~~~~~~
The following commands are executed by the :cmd:ref:`synth` command:
.. literalinclude:: /cmd/synth.rst
:start-at: begin:
:end-before: .. raw:: latex
:dedent:
Synth commands
--------------
Packaged ``synth_*`` commands
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@ -38,3 +28,20 @@ being targeted.
- :doc:`/cmd/synth_quicklogic`
- :doc:`/cmd/synth_sf2`
- :doc:`/cmd/synth_xilinx`
General synthesis
~~~~~~~~~~~~~~~~~
In addition to the above hardware-specific synth commands, there is also
:doc:`/cmd/prep`. This command is limited to coarse-grain synthesis, without
getting into any architecture-specific mappings or optimizations. Among other
things, this is useful for design verification.
The following commands are executed by the :cmd:ref:`prep` command:
.. literalinclude:: /cmd/prep.rst
:start-at: begin:
:end-before: .. raw:: latex
:dedent:
The following sections will get more into what each of these commands do.