From 1e3b90ae56ab504f6de39979a06090c047a82907 Mon Sep 17 00:00:00 2001 From: Krystine Sherwin <93062060+KrystalDelusion@users.noreply.github.com> Date: Thu, 7 Dec 2023 17:14:21 +1300 Subject: [PATCH] Removing typical phases doc 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. --- docs/source/getting_started/example_synth.rst | 58 ++- .../source/getting_started/typical_phases.rst | 457 ------------------ .../using_yosys/more_scripting/index.rst | 9 +- .../more_scripting/load_design.rst | 37 ++ docs/source/using_yosys/synthesis/abc.rst | 39 ++ .../synthesis/{opt_passes.rst => fsm.rst} | 186 +------ docs/source/using_yosys/synthesis/index.rst | 7 +- .../{memory_mapping.rst => memory.rst} | 108 ++++- docs/source/using_yosys/synthesis/opt.rst | 233 +++++++++ docs/source/using_yosys/synthesis/proc.rst | 69 ++- docs/source/using_yosys/synthesis/synth.rst | 31 +- 11 files changed, 568 insertions(+), 666 deletions(-) delete mode 100644 docs/source/getting_started/typical_phases.rst create mode 100644 docs/source/using_yosys/more_scripting/load_design.rst create mode 100644 docs/source/using_yosys/synthesis/abc.rst rename docs/source/using_yosys/synthesis/{opt_passes.rst => fsm.rst} (52%) rename docs/source/using_yosys/synthesis/{memory_mapping.rst => memory.rst} (86%) create mode 100644 docs/source/using_yosys/synthesis/opt.rst diff --git a/docs/source/getting_started/example_synth.rst b/docs/source/getting_started/example_synth.rst index 9f61e9180..d155d41c9 100644 --- a/docs/source/getting_started/example_synth.rst +++ b/docs/source/getting_started/example_synth.rst @@ -1,17 +1,35 @@ Synthesis starter ----------------- +.. + Typical phases of a synthesis flow are as follows: + + - Reading and elaborating the design + - Higher-level synthesis and optimization + + - Converting ``always``-blocks to logic and registers + - Perform coarse-grain optimizations (resource sharing, const folding, ...) + - Handling of memories and other coarse-grain blocks + - Extracting and optimizing finite state machines + + - Convert remaining logic to bit-level logic functions + - Perform optimizations on bit-level logic functions + - Map bit-level logic gates and registers to cell library + - Write results to output file + A simple counter ~~~~~~~~~~~~~~~~ .. role:: yoscrypt(code) :language: yoscrypt -This section covers an example project available in -``docs/source/code_examples/intro/*``. The project contains a simple ASIC +This section covers an `example project`_ available in +``docs/source/code_examples/intro/``. The project contains a simple ASIC synthesis script (``counter.ys``), a digital design written in Verilog (``counter.v``), and a simple CMOS cell library (``mycells.lib``). +.. _example project: https://github.com/YosysHQ/yosys/tree/krys/docs/docs/source/code_examples/intro + First, let's quickly look at the design: .. literalinclude:: /code_examples/intro/counter.v @@ -159,20 +177,27 @@ Some of the commands we might use here are: - :doc:`/cmd/memory`, - :doc:`/cmd/wreduce`, - :doc:`/cmd/peepopt`, +- :doc:`/cmd/pmuxtree`, - :doc:`/cmd/alumacc`, and - :doc:`/cmd/share`. -Techmap -~~~~~~~ +We could have also + +Logic gate mapping +~~~~~~~~~~~~~~~~~~ :yoscrypt:`techmap` - Map coarse-grain RTL cells (adders, etc.) to fine-grain logic gates (AND, OR, NOT, etc.). -.. literalinclude:: /code_examples/intro/counter.ys - :language: yoscrypt - :lines: 8-9 +When :cmd:ref:`techmap` is used without a map file, it uses a built-in map file +to map all RTL cell types to a generic library of built-in logic gates and +registers. -Result: +The built-in logic gate types are: ``$_NOT_``, ``$_AND_``, ``$_OR_``, +``$_XOR_``, and ``$_MUX_``. + +See :doc:`/yosys_internals/formats/cell_library` for more about the internal +cells used. .. figure:: /_images/code_examples/intro/counter_02.* :class: width-helper @@ -193,6 +218,22 @@ Mapping to hardware ``counter`` after hardware cell mapping +:cmd:ref:`dfflibmap` + This command maps the internal register cell types to the register types + described in a liberty file. + +:cmd:ref:`hilomap` + Some architectures require special driver cells for driving a constant hi or + lo value. This command replaces simple constants with instances of such + driver cells. + +:cmd:ref:`iopadmap` + Top-level input/outputs must usually be implemented using special I/O-pad + cells. This command inserts such cells to the design. + +:cmd:ref:`dfflegalize` + Specify a set of supported FF cells/cell groups and convert all FFs to them. + .. _cmos_lib: The CMOS cell library @@ -215,3 +256,4 @@ The script file :language: yoscrypt :caption: ``docs/source/code_examples/intro/counter.ys`` +See also :doc:`/using_yosys/synthesis/synth`. diff --git a/docs/source/getting_started/typical_phases.rst b/docs/source/getting_started/typical_phases.rst deleted file mode 100644 index d6cf89be5..000000000 --- a/docs/source/getting_started/typical_phases.rst +++ /dev/null @@ -1,457 +0,0 @@ -Typical phases of a synthesis flow ----------------------------------- - -.. role:: yoscrypt(code) - :language: yoscrypt - -.. todo:: should e.g. :yoscrypt:`proc` and :yoscrypt:`memory` examples be - included here (typical phases) or examples - -.. todo:: expand bullet points - -- Reading and elaborating the design -- Higher-level synthesis and optimization - - - Converting ``always``-blocks to logic and registers - - Perform coarse-grain optimizations (resource sharing, const folding, ...) - - Handling of memories and other coarse-grain blocks - - Extracting and optimizing finite state machines - -- Convert remaining logic to bit-level logic functions -- Perform optimizations on bit-level logic functions -- Map bit-level logic gates and registers to cell library -- Write results to output file - -Reading the design -~~~~~~~~~~~~~~~~~~ - -.. todo:: include ``read_verilog <` 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. diff --git a/docs/source/using_yosys/synthesis/index.rst b/docs/source/using_yosys/synthesis/index.rst index b8dba55e9..007fd555d 100644 --- a/docs/source/using_yosys/synthesis/index.rst +++ b/docs/source/using_yosys/synthesis/index.rst @@ -5,6 +5,9 @@ Synthesis in detail :maxdepth: 3 synth - opt_passes proc - memory_mapping + fsm + memory + opt + abc + diff --git a/docs/source/using_yosys/synthesis/memory_mapping.rst b/docs/source/using_yosys/synthesis/memory.rst similarity index 86% rename from docs/source/using_yosys/synthesis/memory_mapping.rst rename to docs/source/using_yosys/synthesis/memory.rst index 7fd0a3eb9..721a86672 100644 --- a/docs/source/using_yosys/synthesis/memory_mapping.rst +++ b/docs/source/using_yosys/synthesis/memory.rst @@ -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 `_ -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 diff --git a/docs/source/using_yosys/synthesis/opt.rst b/docs/source/using_yosys/synthesis/opt.rst new file mode 100644 index 000000000..7851e78be --- /dev/null +++ b/docs/source/using_yosys/synthesis/opt.rst @@ -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 ` 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`. diff --git a/docs/source/using_yosys/synthesis/proc.rst b/docs/source/using_yosys/synthesis/proc.rst index 1d7b823be..498e1264a 100644 --- a/docs/source/using_yosys/synthesis/proc.rst +++ b/docs/source/using_yosys/synthesis/proc.rst @@ -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`` diff --git a/docs/source/using_yosys/synthesis/synth.rst b/docs/source/using_yosys/synthesis/synth.rst index 2ac717f05..62cac991b 100644 --- a/docs/source/using_yosys/synthesis/synth.rst +++ b/docs/source/using_yosys/synthesis/synth.rst @@ -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.