diff --git a/docs/source/appendix/auxlibs.rst b/docs/source/appendix/auxlibs.rst index 321cb52c4..8c78ed6b3 100644 --- a/docs/source/appendix/auxlibs.rst +++ b/docs/source/appendix/auxlibs.rst @@ -29,7 +29,7 @@ ezSAT The files in ``libs/ezsat`` provide a library for simplifying generating CNF formulas for SAT solvers. It also contains bindings of MiniSAT. The ezSAT -library is written by C. Wolf. It is used by the :cmd:ref:`sat` pass (see +library is written by C. Wolf. It is used by the `sat` pass (see :doc:`/cmd/sat`). fst @@ -37,22 +37,22 @@ fst ``libfst`` files from `gtkwave`_ are included in ``libs/fst`` to support reading/writing signal traces from/to the GTKWave developed FST format. This is -primarily used in the :cmd:ref:`sim` command. +primarily used in the `sim` command. .. _gtkwave: https://github.com/gtkwave/gtkwave json11 ------ -For reading/writing designs from/to JSON, :cmd:ref:`read_json` and -:cmd:ref:`write_json` should be used. For everything else there is the `json11 +For reading/writing designs from/to JSON, `read_json` and +`write_json` should be used. For everything else there is the `json11 library`_: json11 is a tiny JSON library for C++11, providing JSON parsing and serialization. -This library is used for outputting machine-readable statistics (:cmd:ref:`stat` -with ``-json`` flag), using the RPC frontend (:cmd:ref:`connect_rpc`), and the +This library is used for outputting machine-readable statistics (`stat` +with ``-json`` flag), using the RPC frontend (`connect_rpc`), and the yosys-witness ``yw`` format. .. _json11 library: https://github.com/dropbox/json11 @@ -61,7 +61,7 @@ MiniSAT ------- The files in ``libs/minisat`` provide a high-performance SAT solver, used by the -:cmd:ref:`sat` command. +`sat` command. SHA1 ---- diff --git a/docs/source/appendix/env_vars.rst b/docs/source/appendix/env_vars.rst index 26cc37c81..69e86c922 100644 --- a/docs/source/appendix/env_vars.rst +++ b/docs/source/appendix/env_vars.rst @@ -3,7 +3,7 @@ Yosys environment variables ``HOME`` Yosys command history is stored in :file:`$HOME/.yosys_history`. Graphics - (from :cmd:ref:`show` and :cmd:ref:`viz` commands) will output to this + (from `show` and `viz` commands) will output to this directory by default. This environment variable is also used in some cases for resolving filenames with :file:`~`. diff --git a/docs/source/getting_started/example_synth.rst b/docs/source/getting_started/example_synth.rst index 28e74ecc0..ec1f967ea 100644 --- a/docs/source/getting_started/example_synth.rst +++ b/docs/source/getting_started/example_synth.rst @@ -2,9 +2,9 @@ Synthesis starter ----------------- This page will be a guided walkthrough of the prepackaged iCE40 FPGA synthesis -script - :cmd:ref:`synth_ice40`. We will take a simple design through each +script - `synth_ice40`. We will take a simple design through each step, looking at the commands being called and what they do to the design. While -:cmd:ref:`synth_ice40` is specific to the iCE40 platform, most of the operations +`synth_ice40` is specific to the iCE40 platform, most of the operations we will be discussing are common across the majority of FPGA synthesis scripts. Thus, this document will provide a good foundational understanding of how synthesis in Yosys is performed, regardless of the actual architecture being @@ -59,8 +59,8 @@ can run each of the commands individually for a better sense of how each part contributes to the flow. We will also start with just a single module; ``addr_gen``. -At the bottom of the :cmd:ref:`help` output for -:cmd:ref:`synth_ice40` is the complete list of commands called by this script. +At the bottom of the `help` output for +`synth_ice40` is the complete list of commands called by this script. Let's start with the section labeled ``begin``: .. literalinclude:: /cmd/synth_ice40.rst @@ -105,8 +105,8 @@ Since we're just getting started, let's instead begin with :yoscrypt:`hierarchy .. note:: - :cmd:ref:`hierarchy` should always be the first command after the design has - been read. By specifying the top module, :cmd:ref:`hierarchy` will also set + `hierarchy` should always be the first command after the design has + been read. By specifying the top module, `hierarchy` will also set the ``(* top *)`` attribute on it. This is used by other commands that need to know which module is the top. @@ -125,7 +125,7 @@ Our ``addr_gen`` circuit now looks like this: :class: width-helper invert-helper :name: addr_gen_hier - ``addr_gen`` module after :cmd:ref:`hierarchy` + ``addr_gen`` module after `hierarchy` Simple operations like ``addr + 1`` and ``addr == MAX_DATA-1`` can be extracted from our ``always @`` block in :ref:`addr_gen-v`. This gives us the highlighted @@ -137,9 +137,9 @@ second line refers to the line numbers of the start/end of the corresponding ``PROC`` referring to line 0. To handle these, let us now introduce the next command: :doc:`/cmd/proc`. -:cmd:ref:`proc` is a macro command like :cmd:ref:`synth_ice40`. Rather than +`proc` is a macro command like `synth_ice40`. Rather than modifying the design directly, it instead calls a series of other commands. In -the case of :cmd:ref:`proc`, these sub-commands work to convert the behavioral +the case of `proc`, these sub-commands work to convert the behavioral logic of processes into multiplexers and registers. Let's see what happens when we run it. For now, we will call :yoscrypt:`proc -noopt` to prevent some automatic optimizations which would normally happen. @@ -160,8 +160,8 @@ Notice how in the top left of :ref:`addr_gen_proc` we have a floating wire, generated from the initial assignment of 0 to the ``addr`` wire. However, this initial assignment is not synthesizable, so this will need to be cleaned up before we can generate the physical hardware. We can do this now by calling -:cmd:ref:`clean`. We're also going to call :cmd:ref:`opt_expr` now, which would -normally be called at the end of :cmd:ref:`proc`. We can call both commands at +`clean`. We're also going to call `opt_expr` now, which would +normally be called at the end of `proc`. We can call both commands at the same time by separating them with a colon and space: :yoscrypt:`opt_expr; clean`. @@ -175,7 +175,7 @@ You may also notice that the highlighted `$eq` cell input of ``255`` has changed to ``8'11111111``. Constant values are presented in the format ``'``, with 32-bit values instead using the decimal number. This indicates that the constant input has been reduced from 32-bit wide to -8-bit wide. This is a side-effect of running :cmd:ref:`opt_expr`, which +8-bit wide. This is a side-effect of running `opt_expr`, which performs constant folding and simple expression rewriting. For more on why this happens, refer to :doc:`/using_yosys/synthesis/opt` and the :ref:`section on opt_expr `. @@ -185,7 +185,7 @@ on opt_expr `. :doc:`/cmd/clean` can also be called with two semicolons after any command, for example we could have called :yoscrypt:`opt_expr;;` instead of :yoscrypt:`opt_expr; clean`. You may notice some scripts will end each line - with ``;;``. It is beneficial to run :cmd:ref:`clean` before inspecting + with ``;;``. It is beneficial to run `clean` before inspecting intermediate products to remove disconnected parts of the circuit which have been left over, and in some cases can reduce the processing required in subsequent commands. @@ -202,7 +202,7 @@ The full example Let's now go back and check on our full design by using :yoscrypt:`hierarchy -check -top fifo`. By passing the ``-check`` option there we are also telling -the :cmd:ref:`hierarchy` command that if the design includes any non-blackbox +the `hierarchy` command that if the design includes any non-blackbox modules without an implementation it should return an error. Note that if we tried to run this command now then we would get an error. This @@ -221,15 +221,15 @@ could restart our shell session, but instead let's use two new commands: Notice how this time we didn't see any of those ``$abstract`` modules? That's because when we ran ``yosys fifo.v``, the first command Yosys called was :yoscrypt:`read_verilog -defer fifo.v`. The ``-defer`` option there tells -:cmd:ref:`read_verilog` only read the abstract syntax tree and defer actual -compilation to a later :cmd:ref:`hierarchy` command. This is useful in cases +`read_verilog` only read the abstract syntax tree and defer actual +compilation to a later `hierarchy` command. This is useful in cases where the default parameters of modules yield invalid code which is not synthesizable. This is why Yosys defers compilation automatically and is one of the reasons why hierarchy should always be the first command after loading the design. If we know that our design won't run into this issue, we can skip the ``-defer``. -.. todo:: :cmd:ref:`hierarchy` failure modes +.. todo:: `hierarchy` failure modes .. note:: @@ -243,19 +243,19 @@ design. If we know that our design won't run into this issue, we can skip the interactive terminal. :kbd:`ctrl+c` (i.e. SIGINT) will also end the terminal session but will return an error code rather than exiting gracefully. -We can also run :cmd:ref:`proc` now to finish off the full :ref:`synth_begin`. +We can also run `proc` now to finish off the full :ref:`synth_begin`. Because the design schematic is quite large, we will be showing just the data path for the ``rdata`` output. If you would like to see the entire design for -yourself, you can do so with :doc:`/cmd/show`. Note that the :cmd:ref:`show` +yourself, you can do so with :doc:`/cmd/show`. Note that the `show` command only works with a single module, so you may need to call it with :yoscrypt:`show fifo`. :ref:`show_intro` section in -:doc:`/getting_started/scripting_intro` has more on how to use :cmd:ref:`show`. +:doc:`/getting_started/scripting_intro` has more on how to use `show`. .. figure:: /_images/code_examples/fifo/rdata_proc.* :class: width-helper invert-helper :name: rdata_proc - ``rdata`` output after :cmd:ref:`proc` + ``rdata`` output after `proc` The highlighted ``fifo_reader`` block contains an instance of the :ref:`addr_gen_proc` that we looked at earlier. Notice how the type is shown as @@ -276,7 +276,7 @@ Flattening ~~~~~~~~~~ At this stage of a synthesis flow there are a few other commands we could run. -In :cmd:ref:`synth_ice40` we get these: +In `synth_ice40` we get these: .. literalinclude:: /cmd/synth_ice40.rst :language: yoscrypt @@ -286,7 +286,7 @@ In :cmd:ref:`synth_ice40` we get these: :name: synth_flatten :caption: ``flatten`` section -First off is :cmd:ref:`flatten`. Flattening the design like this can allow for +First off is `flatten`. Flattening the design like this can allow for optimizations between modules which would otherwise be missed. Let's run :yoscrypt:`flatten;;` on our design. @@ -310,19 +310,19 @@ The pieces have moved around a bit, but we can see :ref:`addr_gen_proc` from earlier has replaced the ``fifo_reader`` block in :ref:`rdata_proc`. We can also see that the ``addr`` output has been renamed to :file:`fifo_reader.addr` and merged with the ``raddr`` wire feeding into the `$memrd` cell. This wire -merging happened during the call to :cmd:ref:`clean` which we can see in the +merging happened during the call to `clean` which we can see in the :ref:`flat_clean`. .. note:: - :cmd:ref:`flatten` and :cmd:ref:`clean` would normally be combined into a + `flatten` and `clean` would normally be combined into a single :yoterm:`yosys> flatten;;` output, but they appear separately here as - a side effect of using :cmd:ref:`echo` for generating the terminal style + a side effect of using `echo` for generating the terminal style output. Depending on the target architecture, this stage of synthesis might also see -commands such as :cmd:ref:`tribuf` with the ``-logic`` option and -:cmd:ref:`deminout`. These remove tristate and inout constructs respectively, +commands such as `tribuf` with the ``-logic`` option and +`deminout`. These remove tristate and inout constructs respectively, replacing them with logic suitable for mapping to an FPGA. Since we do not have any such constructs in our example running these commands does not change our design. @@ -342,7 +342,7 @@ optimizations and other transformations done previously. .. note:: - While the iCE40 flow had a :ref:`synth_flatten` and put :cmd:ref:`proc` in + While the iCE40 flow had a :ref:`synth_flatten` and put `proc` in the :ref:`synth_begin`, some synthesis scripts will instead include these in this section. @@ -359,8 +359,8 @@ In the iCE40 flow, we start with the following commands: :caption: ``coarse`` section (part 1) :name: synth_coarse1 -We've already come across :cmd:ref:`opt_expr`, and :cmd:ref:`opt_clean` is the -same as :cmd:ref:`clean` but with more verbose output. The :cmd:ref:`check` +We've already come across `opt_expr`, and `opt_clean` is the +same as `clean` but with more verbose output. The `check` pass identifies a few obvious problems which will cause errors later. Calling it here lets us fail faster rather than wasting time on something we know is impossible. @@ -368,13 +368,13 @@ impossible. Next up is :yoscrypt:`opt -nodffe -nosdff` performing a set of simple optimizations on the design. This command also ensures that only a specific subset of FF types are included, in preparation for the next command: -:doc:`/cmd/fsm`. Both :cmd:ref:`opt` and :cmd:ref:`fsm` are macro commands +:doc:`/cmd/fsm`. Both `opt` and `fsm` are macro commands which are explored in more detail in :doc:`/using_yosys/synthesis/opt` and :doc:`/using_yosys/synthesis/fsm` respectively. Up until now, the data path for ``rdata`` has remained the same since -:ref:`rdata_flat`. However the next call to :cmd:ref:`opt` does cause a change. -Specifically, the call to :cmd:ref:`opt_dff` without the ``-nodffe -nosdff`` +:ref:`rdata_flat`. However the next call to `opt` does cause a change. +Specifically, the call to `opt_dff` without the ``-nodffe -nosdff`` options is able to fold one of the `$mux` cells into the `$adff` to form an `$adffe` cell; highlighted below: @@ -382,13 +382,13 @@ options is able to fold one of the `$mux` cells into the `$adff` to form an :language: doscon :start-at: yosys> opt_dff :end-before: yosys> select - :caption: output of :cmd:ref:`opt_dff` + :caption: output of `opt_dff` .. figure:: /_images/code_examples/fifo/rdata_adffe.* :class: width-helper invert-helper :name: rdata_adffe - ``rdata`` output after :cmd:ref:`opt_dff` + ``rdata`` output after `opt_dff` .. seealso:: Advanced usage docs for @@ -414,26 +414,26 @@ First up is :doc:`/cmd/wreduce`. If we run this we get the following: :language: doscon :start-at: yosys> wreduce :end-before: yosys> select - :caption: output of :cmd:ref:`wreduce` + :caption: output of `wreduce` Looking at the data path for ``rdata``, the most relevant of these width reductions are the ones affecting ``fifo.$flatten\fifo_reader.$add$fifo.v``. That is the `$add` cell incrementing the fifo_reader address. We can look at the schematic and see the output of that cell has now changed. -.. todo:: pending bugfix in :cmd:ref:`wreduce` and/or :cmd:ref:`opt_clean` +.. todo:: pending bugfix in `wreduce` and/or `opt_clean` .. figure:: /_images/code_examples/fifo/rdata_wreduce.* :class: width-helper invert-helper :name: rdata_wreduce - ``rdata`` output after :cmd:ref:`wreduce` + ``rdata`` output after `wreduce` The next two (new) commands are :doc:`/cmd/peepopt` and :doc:`/cmd/share`. Neither of these affect our design, and they're explored in more detail in :doc:`/using_yosys/synthesis/opt`, so let's skip over them. :yoscrypt:`techmap -map +/cmp2lut.v -D LUT_WIDTH=4` optimizes certain comparison operators by -converting them to LUTs instead. The usage of :cmd:ref:`techmap` is explored +converting them to LUTs instead. The usage of `techmap` is explored more in :doc:`/using_yosys/synthesis/techmap_synth`. Our next command to run is @@ -443,15 +443,15 @@ Our next command to run is :language: doscon :start-at: yosys> memory_dff :end-before: yosys> select - :caption: output of :cmd:ref:`memory_dff` + :caption: output of `memory_dff` .. figure:: /_images/code_examples/fifo/rdata_memrdv2.* :class: width-helper invert-helper :name: rdata_memrdv2 - ``rdata`` output after :cmd:ref:`memory_dff` + ``rdata`` output after `memory_dff` -As the title suggests, :cmd:ref:`memory_dff` has merged the output `$dff` into +As the title suggests, `memory_dff` has merged the output `$dff` into the `$memrd` cell and converted it to a `$memrd_v2` (highlighted). This has also connected the ``CLK`` port to the ``clk`` input as it is now a synchronous memory read with appropriate enable (``EN=1'1``) and reset (``ARST=1'0`` and @@ -466,7 +466,7 @@ memory read with appropriate enable (``EN=1'1``) and reset (``ARST=1'0`` and Part 3 ^^^^^^ -The third part of the :cmd:ref:`synth_ice40` flow is a series of commands for +The third part of the `synth_ice40` flow is a series of commands for mapping to DSPs. By default, the iCE40 flow will not map to the hardware DSP blocks and will only be performed if called with the ``-dsp`` flag: :yoscrypt:`synth_ice40 -dsp`. While our example has nothing that could be @@ -483,24 +483,24 @@ what they do. :yoscrypt:`wreduce t:$mul` performs width reduction again, this time targetting only cells of type `$mul`. :yoscrypt:`techmap -map +/mul2dsp.v -map -+/ice40/dsp_map.v ... -D DSP_NAME=$__MUL16X16` uses :cmd:ref:`techmap` to map ++/ice40/dsp_map.v ... -D DSP_NAME=$__MUL16X16` uses `techmap` to map `$mul` cells to ``$__MUL16X16`` which are, in turn, mapped to the iCE40 ``SB_MAC16``. Any multipliers which aren't compatible with conversion to -``$__MUL16X16`` are relabelled to ``$__soft_mul`` before :cmd:ref:`chtype` +``$__MUL16X16`` are relabelled to ``$__soft_mul`` before `chtype` changes them back to `$mul`. During the mul2dsp conversion, some of the intermediate signals are marked with the attribute ``mul2dsp``. By calling :yoscrypt:`select a:mul2dsp` we restrict the following commands to only operate on the cells and wires used for these -signals. :cmd:ref:`setattr` removes the now unnecessary ``mul2dsp`` attribute. -:cmd:ref:`opt_expr` we've already come across for const folding and simple +signals. `setattr` removes the now unnecessary ``mul2dsp`` attribute. +`opt_expr` we've already come across for const folding and simple expression rewriting, the ``-fine`` option just enables more fine-grain optimizations. Then we perform width reduction a final time and clear the selection. .. todo:: ``ice40_dsp`` is pmgen -Finally we have :cmd:ref:`ice40_dsp`: similar to the :cmd:ref:`memory_dff` +Finally we have `ice40_dsp`: similar to the `memory_dff` command we saw in the previous section, this merges any surrounding registers into the ``SB_MAC16`` cell. This includes not just the input/output registers, but also pipeline registers and even a post-adder where applicable: turning a @@ -525,40 +525,40 @@ That brings us to the fourth and final part for the iCE40 synthesis flow: Where before each type of arithmetic operation had its own cell, e.g. `$add`, we now want to extract these into `$alu` and `$macc` cells which can help identify opportunities for reusing logic. We do this by running -:cmd:ref:`alumacc`, which we can see produce the following changes in our +`alumacc`, which we can see produce the following changes in our example design: .. literalinclude:: /code_examples/fifo/fifo.out :language: doscon :start-at: yosys> alumacc :end-before: yosys> select - :caption: output of :cmd:ref:`alumacc` + :caption: output of `alumacc` .. figure:: /_images/code_examples/fifo/rdata_alumacc.* :class: width-helper invert-helper :name: rdata_alumacc - ``rdata`` output after :cmd:ref:`alumacc` + ``rdata`` output after `alumacc` -Once these cells have been inserted, the call to :cmd:ref:`opt` can combine +Once these cells have been inserted, the call to `opt` can combine cells which are now identical but may have been missed due to e.g. the difference between `$add` and `$sub`. -The other new command in this part is :doc:`/cmd/memory`. :cmd:ref:`memory` is +The other new command in this part is :doc:`/cmd/memory`. `memory` is another macro command which we examine in more detail in :doc:`/using_yosys/synthesis/memory`. For this document, let us focus just on -the step most relevant to our example: :cmd:ref:`memory_collect`. Up until this +the step most relevant to our example: `memory_collect`. Up until this point, our memory reads and our memory writes have been totally disjoint cells; -operating on the same memory only in the abstract. :cmd:ref:`memory_collect` +operating on the same memory only in the abstract. `memory_collect` combines all of the reads and writes for a memory block into a single cell. .. figure:: /_images/code_examples/fifo/rdata_coarse.* :class: width-helper invert-helper :name: rdata_coarse - ``rdata`` output after :cmd:ref:`memory_collect` + ``rdata`` output after `memory_collect` -Looking at the schematic after running :cmd:ref:`memory_collect` we see that our +Looking at the schematic after running `memory_collect` we see that our `$memrd_v2` cell has been replaced with a `$mem_v2` cell named ``data``, the same name that we used in :ref:`fifo-v`. Where before we had a single set of signals for address and enable, we now have one set for reading (``RD_*``) and @@ -592,8 +592,8 @@ If you skipped calling :yoscrypt:`read_verilog -D ICE40_HX -lib -specify Memory blocks ^^^^^^^^^^^^^ -Mapping to hard memory blocks uses a combination of :cmd:ref:`memory_libmap` and -:cmd:ref:`techmap`. +Mapping to hard memory blocks uses a combination of `memory_libmap` and +`techmap`. .. literalinclude:: /cmd/synth_ice40.rst :language: yoscrypt @@ -619,7 +619,7 @@ As a result, extra logic is added so that the generated circuit matches the behaviour of the verilog. :ref:`no_rw_check` describes how we could change our verilog to match our hardware instead. -If we run :cmd:ref:`memory_libmap` under the :cmd:ref:`debug` command we can see +If we run `memory_libmap` under the `debug` command we can see candidates which were identified for mapping, along with the costs of each and what logic requires emulation. @@ -628,9 +628,9 @@ what logic requires emulation. :lines: 2, 6- The ``$__ICE40_RAM4K_`` cell is defined in the file |techlibs/ice40/brams.txt|_, -with the mapping to ``SB_RAM40_4K`` done by :cmd:ref:`techmap` using +with the mapping to ``SB_RAM40_4K`` done by `techmap` using |techlibs/ice40/brams_map.v|_. Any leftover memory cells are then converted -into flip flops (the ``logic fallback``) with :cmd:ref:`memory_map`. +into flip flops (the ``logic fallback``) with `memory_map`. .. |techlibs/ice40/brams.txt| replace:: :file:`techlibs/ice40/brams.txt` .. _techlibs/ice40/brams.txt: https://github.com/YosysHQ/yosys/tree/main/techlibs/ice40/brams.txt @@ -654,7 +654,7 @@ into flip flops (the ``logic fallback``) with :cmd:ref:`memory_map`. .. note:: The visual clutter on the ``RDATA`` output port (highlighted) is an - unfortunate side effect of :cmd:ref:`opt_clean` on the swizzled data bits. In + unfortunate side effect of `opt_clean` on the swizzled data bits. In connecting the `$mux` input port directly to ``RDATA`` to reduce the number of wires, the ``$techmap579\data.0.0.RDATA`` wire becomes more visually complex. @@ -667,7 +667,7 @@ into flip flops (the ``logic fallback``) with :cmd:ref:`memory_map`. Arithmetic ^^^^^^^^^^ -Uses :cmd:ref:`techmap` to map basic arithmetic logic to hardware. This sees +Uses `techmap` to map basic arithmetic logic to hardware. This sees somewhat of an explosion in cells as multi-bit :cell:ref:`$mux` and `$adffe` are replaced with single-bit `$_MUX_` and `$_DFFE_PP0P_` cells, while the :cell:ref:`$alu` is replaced with primitive `$_OR_` and `$_NOT_` gates and a @@ -693,11 +693,11 @@ replaced with single-bit `$_MUX_` and `$_DFFE_PP0P_` cells, while the Flip-flops ^^^^^^^^^^ -Convert FFs to the types supported in hardware with :cmd:ref:`dfflegalize`, and -then use :cmd:ref:`techmap` to map them. In our example, this converts the +Convert FFs to the types supported in hardware with `dfflegalize`, and +then use `techmap` to map them. In our example, this converts the `$_DFFE_PP0P_` cells to ``SB_DFFER``. -We also run :cmd:ref:`simplemap` here to convert any remaining cells which could +We also run `simplemap` here to convert any remaining cells which could not be mapped to hardware into gate-level primitives. This includes optimizing `$_MUX_` cells where one of the inputs is a constant ``1'0``, replacing it instead with an `$_AND_` cell. @@ -722,9 +722,9 @@ instead with an `$_AND_` cell. LUTs ^^^^ -:cmd:ref:`abc` and :cmd:ref:`techmap` are used to map LUTs; converting primitive +`abc` and `techmap` are used to map LUTs; converting primitive cell types to use `$lut` and ``SB_CARRY`` cells. Note that the iCE40 flow -uses :cmd:ref:`abc9` rather than :cmd:ref:`abc`. For more on what these do, and +uses `abc9` rather than `abc`. For more on what these do, and what the difference between these two commands are, refer to :doc:`/using_yosys/synthesis/abc`. @@ -742,7 +742,7 @@ what the difference between these two commands are, refer to ``rdata`` output after :ref:`map_luts` -Finally we use :cmd:ref:`techmap` to map the generic `$lut` cells to iCE40 +Finally we use `techmap` to map the generic `$lut` cells to iCE40 ``SB_LUT4`` cells. .. literalinclude:: /cmd/synth_ice40.rst @@ -769,12 +769,12 @@ Other cells The following commands may also be used for mapping other cells: -:cmd:ref:`hilomap` +`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` +`iopadmap` Top-level input/outputs must usually be implemented using special I/O-pad cells. This command inserts such cells to the design. @@ -801,27 +801,27 @@ The new commands here are: - :doc:`/cmd/stat`, and - :doc:`/cmd/blackbox`. -The output from :cmd:ref:`stat` is useful for checking resource utilization; +The output from `stat` is useful for checking resource utilization; providing a list of cells used in the design and the number of each, as well as the number of other resources used such as wires and processes. For this -design, the final call to :cmd:ref:`stat` should look something like the +design, the final call to `stat` should look something like the following: .. literalinclude:: /code_examples/fifo/fifo.stat :language: doscon :start-at: yosys> stat -top fifo -Note that the :yoscrypt:`-top fifo` here is optional. :cmd:ref:`stat` will +Note that the :yoscrypt:`-top fifo` here is optional. `stat` will automatically use the module with the ``top`` attribute set, which ``fifo`` was -when we called :cmd:ref:`hierarchy`. If no module is marked ``top``, then stats +when we called `hierarchy`. If no module is marked ``top``, then stats will be shown for each module selected. -The :cmd:ref:`stat` output is also useful as a kind of sanity-check: Since we -have already run :cmd:ref:`proc`, we wouldn't expect there to be any processes. +The `stat` output is also useful as a kind of sanity-check: Since we +have already run `proc`, we wouldn't expect there to be any processes. We also expect ``data`` to use hard memory; if instead of an ``SB_RAM40_4K`` saw a high number of flip-flops being used we might suspect something was wrong. -If we instead called :cmd:ref:`stat` immediately after :yoscrypt:`read_verilog +If we instead called `stat` immediately after :yoscrypt:`read_verilog fifo.v` we would see something very different: .. literalinclude:: /code_examples/fifo/fifo.stat @@ -845,7 +845,7 @@ The iCE40 synthesis flow has the following output modes available: As an example, if we called :yoscrypt:`synth_ice40 -top fifo -json fifo.json`, our synthesized ``fifo`` design will be output as :file:`fifo.json`. We can -then read the design back into Yosys with :cmd:ref:`read_json`, but make sure +then read the design back into Yosys with `read_json`, but make sure you use :yoscrypt:`design -reset` or open a new interactive terminal first. The JSON output we get can also be loaded into `nextpnr`_ to do place and route; but that is beyond the scope of this documentation. diff --git a/docs/source/getting_started/installation.rst b/docs/source/getting_started/installation.rst index 4d1a2f36a..8ed7cebb8 100644 --- a/docs/source/getting_started/installation.rst +++ b/docs/source/getting_started/installation.rst @@ -88,7 +88,7 @@ A C++ compiler with C++17 support is required as well as some standard tools such as GNU Flex, GNU Bison, Make and Python. Some additional tools: readline, libffi, Tcl and zlib; are optional but enabled by default (see :makevar:`ENABLE_*` settings in Makefile). Graphviz and Xdot are used by the -:cmd:ref:`show` command to display schematics. +`show` command to display schematics. Installing all prerequisites for Ubuntu 20.04: @@ -185,8 +185,8 @@ directories: ``passes/`` This directory contains a subdirectory for each pass or group of passes. For example as of this writing the directory :file:`passes/hierarchy/` contains the - code for three passes: :cmd:ref:`hierarchy`, :cmd:ref:`submod`, and - :cmd:ref:`uniquify`. + code for three passes: `hierarchy`, `submod`, and + `uniquify`. ``techlibs/`` This directory contains simulation models and standard implementations for diff --git a/docs/source/getting_started/scripting_intro.rst b/docs/source/getting_started/scripting_intro.rst index 1e2ebabff..ef728e1cf 100644 --- a/docs/source/getting_started/scripting_intro.rst +++ b/docs/source/getting_started/scripting_intro.rst @@ -7,8 +7,7 @@ file format and how you can make your own synthesis scripts. Yosys script files typically use the :file:`.ys` extension and contain a set of commands for Yosys to run sequentially. These commands are the same ones we -were using on the previous page like :cmd:ref:`read_verilog` and -:cmd:ref:`hierarchy`. +were using on the previous page like `read_verilog` and `hierarchy`. Script parsing ~~~~~~~~~~~~~~ @@ -39,9 +38,9 @@ Another special character that can be used in Yosys scripts is the bang ``!``. Anything after the bang will be executed as a shell command. This can only be terminated with a new line. Any semicolons, hashes, or other special characters will be passed to the shell. If an error code is returned from the shell it -will be raised by Yosys. :cmd:ref:`exec` provides a much more flexible way of -executing commands, allowing the output to be logged and more control over when -to generate errors. +will be raised by Yosys. `exec` provides a much more flexible way of executing +commands, allowing the output to be logged and more control over when to +generate errors. The synthesis starter script ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -62,7 +61,7 @@ already, let's take a look at some of those script files now. :caption: A section of :file:`fifo.ys`, generating the images used for :ref:`addr_gen_example` :name: fifo-ys -The first command there, :yoscrypt:`echo on`, uses :cmd:ref:`echo` to enable +The first command there, :yoscrypt:`echo on`, uses `echo` to enable command echoes on. This is how we generated the code listing for :ref:`hierarchy_output`. Turning command echoes on prints the ``yosys> hierarchy -top addr_gen`` line, making the output look the same as if it were an @@ -70,15 +69,15 @@ interactive terminal. :yoscrypt:`hierarchy -top addr_gen` is of course the command we were demonstrating, including the output text and an image of the design schematic after running it. -We briefly touched on :cmd:ref:`select` when it came up in -:cmd:ref:`synth_ice40`, but let's look at it more now. +We briefly touched on `select` when it came up in +`synth_ice40`, but let's look at it more now. .. _select_intro: Selections intro ^^^^^^^^^^^^^^^^ -The :cmd:ref:`select` command is used to modify and view the list of selected +The `select` command is used to modify and view the list of selected objects: .. literalinclude:: /code_examples/fifo/fifo.out @@ -119,7 +118,7 @@ statement. Many commands also support an optional ``[selection]`` argument which can be used to override the currently selected objects. We could, for example, call -:yoscrypt:`clean addr_gen` to have :cmd:ref:`clean` operate on *just* the +:yoscrypt:`clean addr_gen` to have `clean` operate on *just* the ``addr_gen`` module. Detailed documentation of the select framework can be found under @@ -131,9 +130,9 @@ Detailed documentation of the select framework can be found under Displaying schematics ^^^^^^^^^^^^^^^^^^^^^ -While the :cmd:ref:`select` command is very useful, sometimes nothing beats -being able to see a design for yourself. This is where :cmd:ref:`show` comes -in. Note that this document is just an introduction to the :cmd:ref:`show` +While the `select` command is very useful, sometimes nothing beats +being able to see a design for yourself. This is where `show` comes +in. Note that this document is just an introduction to the `show` command, only covering the basics. For more information, including a guide on what the different symbols represent, see :ref:`interactive_show` and the :doc:`/using_yosys/more_scripting/interactive_investigation` page. @@ -142,11 +141,11 @@ what the different symbols represent, see :ref:`interactive_show` and the :class: width-helper invert-helper :name: addr_gen_show - Calling :yoscrypt:`show addr_gen` after :cmd:ref:`hierarchy` + Calling :yoscrypt:`show addr_gen` after `hierarchy` .. note:: - The :cmd:ref:`show` command requires a working installation of `GraphViz`_ + The `show` command requires a working installation of `GraphViz`_ and `xdot`_ for displaying the actual circuit diagrams. .. _GraphViz: http://www.graphviz.org/ @@ -161,7 +160,7 @@ we see the following: :start-at: -prefix addr_gen_show :end-before: yosys> show -Calling :cmd:ref:`show` with :yoscrypt:`-format dot` tells it we want to output +Calling `show` with :yoscrypt:`-format dot` tells it we want to output a :file:`.dot` file rather than opening it for display. The :yoscrypt:`-prefix addr_gen_show` option indicates we want the file to be called :file:`addr_gen_show.{*}`. Remember, we do this in :file:`fifo.ys` because we @@ -186,7 +185,7 @@ That last parameter doesn't have to be a module name, it can be any valid selection string. Remember when we :ref:`assigned a name to a selection` and called it ``new_cells``? We saw in the :yoscrypt:`select -list` output that it contained two cells, an `$add` and an -`$eq`. We can call :cmd:ref:`show` on that selection just as easily: +`$eq`. We can call `show` on that selection just as easily: .. figure:: /_images/code_examples/fifo/new_cells_show.* :class: width-helper invert-helper @@ -208,10 +207,10 @@ the two ``PROC`` blocks. To achieve this highlight, we make use of the Calling :yoscrypt:`show -color maroon3 @new_cells -color cornflowerblue p:* -notitle` -As described in the the :cmd:ref:`help` output for :cmd:ref:`show` (or by -clicking on the :cmd:ref:`show` link), colors are specified as :yoscrypt:`-color +As described in the the `help` output for `show` (or by +clicking on the `show` link), colors are specified as :yoscrypt:`-color `. Color names for the ```` portion can be found on the -`GraphViz color docs`_. Unlike the final :cmd:ref:`show` parameter which can +`GraphViz color docs`_. Unlike the final `show` parameter which can have be any selection string, the ```` part must be a single selection expression or named selection. That means while we can use ``@new_cells``, we couldn't use ``t:$eq t:$add``. In general, if a command lists ``[selection]`` @@ -221,7 +220,7 @@ expression instead. .. _GraphViz color docs: https://graphviz.org/doc/info/colors -For all of the options available to :cmd:ref:`show`, check the command reference +For all of the options available to `show`, check the command reference at :doc:`/cmd/show`. .. seealso:: :ref:`interactive_show` on the diff --git a/docs/source/using_yosys/more_scripting/interactive_investigation.rst b/docs/source/using_yosys/more_scripting/interactive_investigation.rst index 77d826376..f2e3d5219 100644 --- a/docs/source/using_yosys/more_scripting/interactive_investigation.rst +++ b/docs/source/using_yosys/more_scripting/interactive_investigation.rst @@ -13,7 +13,7 @@ A look at the show command .. TODO:: merge into :doc:`/getting_started/scripting_intro` show section -This section explores the :cmd:ref:`show` command and explains the symbols used +This section explores the `show` command and explains the symbols used in the circuit diagrams generated by it. The code used is included in the Yosys code base under |code_examples/show|_. @@ -24,7 +24,7 @@ A simple circuit ^^^^^^^^^^^^^^^^ :ref:`example_v` below provides the Verilog code for a simple circuit which we -will use to demonstrate the usage of :cmd:ref:`show` in a simple setting. +will use to demonstrate the usage of `show` in a simple setting. .. literalinclude:: /code_examples/show/example.v :language: Verilog @@ -32,7 +32,7 @@ will use to demonstrate the usage of :cmd:ref:`show` in a simple setting. :name: example_v The Yosys synthesis script we will be running is included as -:numref:`example_ys`. Note that :cmd:ref:`show` is called with the ``-pause`` +:numref:`example_ys`. Note that `show` is called with the ``-pause`` option, that halts execution of the Yosys script until the user presses the Enter key. Using :yoscrypt:`show -pause` also allows the user to enter an interactive shell to further investigate the circuit before continuing @@ -58,7 +58,7 @@ is shown. .. figure:: /_images/code_examples/show/example_first.* :class: width-helper invert-helper - Output of the first :cmd:ref:`show` command in :numref:`example_ys` + Output of the first `show` command in :numref:`example_ys` The first output shows the design directly after being read by the Verilog front-end. Input and output ports are displayed as octagonal shapes. Cells are @@ -84,39 +84,39 @@ original ``always``-block in the second line. Note how the multiplexer from the ``?:``-expression is represented as a `$mux` cell but the multiplexer from the ``if``-statement is yet still hidden within the process. -The :cmd:ref:`proc` command transforms the process from the first diagram into a +The `proc` command transforms the process from the first diagram into a multiplexer and a d-type flip-flop, which brings us to the second diagram: .. figure:: /_images/code_examples/show/example_second.* :class: width-helper invert-helper - Output of the second :cmd:ref:`show` command in :numref:`example_ys` + Output of the second `show` command in :numref:`example_ys` The Rhombus shape to the right is a dangling wire. (Wire nodes are only shown if they are dangling or have "public" names, for example names assigned from the Verilog input.) Also note that the design now contains two instances of a -``BUF``-node. These are artefacts left behind by the :cmd:ref:`proc` command. It +``BUF``-node. These are artefacts left behind by the `proc` command. It is quite usual to see such artefacts after calling commands that perform changes in the design, as most commands only care about doing the transformation in the least complicated way, not about cleaning up after them. The next call to -:cmd:ref:`clean` (or :cmd:ref:`opt`, which includes :cmd:ref:`clean` as one of +`clean` (or `opt`, which includes `clean` as one of its operations) will clean up these artefacts. This operation is so common in Yosys scripts that it can simply be abbreviated with the ``;;`` token, which doubles as separator for commands. Unless one wants to specifically analyze this artefacts left behind some operations, it is therefore recommended to always -call :cmd:ref:`clean` before calling :cmd:ref:`show`. +call `clean` before calling `show`. -In this script we directly call :cmd:ref:`opt` as the next step, which finally +In this script we directly call `opt` as the next step, which finally leads us to the third diagram: .. figure:: /_images/code_examples/show/example_third.* :class: width-helper invert-helper :name: example_out - Output of the third :cmd:ref:`show` command in :ref:`example_ys` + Output of the third `show` command in :ref:`example_ys` -Here we see that the :cmd:ref:`opt` command not only has removed the artifacts -left behind by :cmd:ref:`proc`, but also determined correctly that it can remove +Here we see that the `opt` command not only has removed the artifacts +left behind by `proc`, but also determined correctly that it can remove the first `$mux` cell without changing the behavior of the circuit. Break-out boxes for signal vectors @@ -129,7 +129,7 @@ accesses. :caption: :file:`splice.v` :name: splice_src -Notice how the output for this circuit from the :cmd:ref:`show` command +Notice how the output for this circuit from the `show` command (:numref:`splice_dia`) appears quite complex. This is an unfortunate side effect of the way Yosys handles signal vectors (aka. multi-bit wires or buses) as native objects. While this provides great advantages when analyzing circuits @@ -169,7 +169,7 @@ mapped to a cell library: :name: first_pitfall A half-adder built from simple CMOS gates, demonstrating common pitfalls when - using :cmd:ref:`show` + using `show` .. literalinclude:: /code_examples/show/cmos.ys :language: yoscrypt @@ -188,7 +188,7 @@ individual bits, resulting in an unnecessary complex diagram. :class: width-helper invert-helper :name: second_pitfall - Effects of :cmd:ref:`splitnets` command and of providing a cell library on + Effects of `splitnets` command and of providing a cell library on design in :numref:`first_pitfall` .. literalinclude:: /code_examples/show/cmos.ys @@ -201,11 +201,11 @@ individual bits, resulting in an unnecessary complex diagram. For :numref:`second_pitfall`, Yosys has been given a description of the cell library as Verilog file containing blackbox modules. There are two ways to load cell descriptions into Yosys: First the Verilog file for the cell library can be -passed directly to the :cmd:ref:`show` command using the ``-lib `` +passed directly to the `show` command using the ``-lib `` option. Secondly it is possible to load cell libraries into the design with the :yoscrypt:`read_verilog -lib ` command. The second method has the great advantage that the library only needs to be loaded once and can then be -used in all subsequent calls to the :cmd:ref:`show` command. +used in all subsequent calls to the `show` command. In addition to that, :numref:`second_pitfall` was generated after :yoscrypt:`splitnet -ports` was run on the design. This command splits all @@ -216,7 +216,7 @@ module ports. Per default the command only operates on interior signals. Miscellaneous notes ^^^^^^^^^^^^^^^^^^^ -Per default the :cmd:ref:`show` command outputs a temporary dot file and +Per default the `show` command outputs a temporary dot file and launches ``xdot`` to display it. The options ``-format``, ``-viewer`` and ``-prefix`` can be used to change format, viewer and filename prefix. Note that the ``pdf`` and ``ps`` format are the only formats that support plotting @@ -225,13 +225,13 @@ modules, however ``xdot`` will raise an error when trying to read them. In densely connected circuits it is sometimes hard to keep track of the individual signal wires. For these cases it can be useful to call -:cmd:ref:`show` with the ``-colors `` argument, which randomly assigns +`show` with the ``-colors `` argument, which randomly assigns colors to the nets. The integer (> 0) is used as seed value for the random color assignments. Sometimes it is necessary it try some values to find an assignment of colors that looks good. The command :yoscrypt:`help show` prints a complete listing of all options -supported by the :cmd:ref:`show` command. +supported by the `show` command. Navigating the design ~~~~~~~~~~~~~~~~~~~~~ @@ -245,9 +245,9 @@ In addition to *what* to display one also needs to carefully decide *when* to display it, with respect to the synthesis flow. In general it is a good idea to troubleshoot a circuit in the earliest state in which a problem can be reproduced. So if, for example, the internal state before calling the -:cmd:ref:`techmap` command already fails to verify, it is better to troubleshoot -the coarse-grain version of the circuit before :cmd:ref:`techmap` than the -gate-level circuit after :cmd:ref:`techmap`. +`techmap` command already fails to verify, it is better to troubleshoot +the coarse-grain version of the circuit before `techmap` than the +gate-level circuit after `techmap`. .. Note:: @@ -260,16 +260,16 @@ Interactive navigation ^^^^^^^^^^^^^^^^^^^^^^ Once the right state within the synthesis flow for debugging the circuit has -been identified, it is recommended to simply add the :cmd:ref:`shell` command to +been identified, it is recommended to simply add the `shell` command to the matching place in the synthesis script. This command will stop the synthesis at the specified moment and go to shell mode, where the user can interactively enter commands. For most cases, the shell will start with the whole design selected (i.e. when the synthesis script does not already narrow the selection). The command -:cmd:ref:`ls` can now be used to create a list of all modules. The command -:cmd:ref:`cd` can be used to switch to one of the modules (type ``cd ..`` to -switch back). Now the :cmd:ref:`ls` command lists the objects within that +`ls` can now be used to create a list of all modules. The command +`cd` can be used to switch to one of the modules (type ``cd ..`` to +switch back). Now the `ls` command lists the objects within that module. This is demonstrated below using :file:`example.v` from `A simple circuit`_: @@ -277,10 +277,10 @@ circuit`_: :language: doscon :start-at: yosys> ls :end-before: yosys [example]> dump - :caption: Output of :cmd:ref:`ls` and :cmd:ref:`cd` after running :file:`yosys example.v` + :caption: Output of `ls` and `cd` after running :file:`yosys example.v` :name: lscd -When a module is selected using the :cmd:ref:`cd` command, all commands (with a +When a module is selected using the `cd` command, all commands (with a few exceptions, such as the ``read_`` and ``write_`` commands) operate only on the selected module. This can also be useful for synthesis scripts where different synthesis strategies should be applied to different modules in the @@ -293,12 +293,12 @@ contains some additional information on the origin of the named object. But in most cases those names can simply be abbreviated using the last part. Usually all interactive work is done with one module selected using the -:cmd:ref:`cd` command. But it is also possible to work from the design-context +`cd` command. But it is also possible to work from the design-context (``cd ..``). In this case all object names must be prefixed with ``/``. For example ``a*/b*`` would refer to all objects whose names start with ``b`` from all modules whose names start with ``a``. -The :cmd:ref:`dump` command can be used to print all information about an +The `dump` command can be used to print all information about an object. For example, calling :yoscrypt:`dump $2` after the :yoscrypt:`cd example` above: @@ -323,10 +323,10 @@ tools). - The selection mechanism, especially patterns such as ``%ci`` and ``%co``, can be used to figure out how parts of the design are connected. -- Commands such as :cmd:ref:`submod`, :cmd:ref:`expose`, and :cmd:ref:`splice` +- Commands such as `submod`, `expose`, and `splice` can be used to transform the design into an equivalent design that is easier to analyse. -- Commands such as :cmd:ref:`eval` and :cmd:ref:`sat` can be used to investigate +- Commands such as `eval` and `sat` can be used to investigate the behavior of the circuit. - :doc:`/cmd/show`. - :doc:`/cmd/dump`. @@ -342,10 +342,10 @@ The code used is included in the Yosys code base under Changing design hierarchy ^^^^^^^^^^^^^^^^^^^^^^^^^ -Commands such as :cmd:ref:`flatten` and :cmd:ref:`submod` can be used to change +Commands such as `flatten` and `submod` can be used to change the design hierarchy, i.e. flatten the hierarchy or moving parts of a module to a submodule. This has applications in synthesis scripts as well as in reverse -engineering and analysis. An example using :cmd:ref:`submod` is shown below for +engineering and analysis. An example using `submod` is shown below for reorganizing a module in Yosys and checking the resulting circuit. .. literalinclude:: /code_examples/scrambler/scrambler.v @@ -388,7 +388,7 @@ Analyzing the resulting circuit with :doc:`/cmd/eval`: Behavioral changes ^^^^^^^^^^^^^^^^^^ -Commands such as :cmd:ref:`techmap` can be used to make behavioral changes to +Commands such as `techmap` can be used to make behavioral changes to the design, for example changing asynchronous resets to synchronous resets. This has applications in design space exploration (evaluation of various architectures for one circuit). @@ -425,7 +425,7 @@ Yosys script for ASIC synthesis of the Amber ARMv2 CPU. endmodule -For more on the :cmd:ref:`techmap` command, see the page on +For more on the `techmap` command, see the page on :doc:`/yosys_internals/techmap`. Advanced investigation techniques @@ -448,12 +448,12 @@ Recall the ``memdemo`` design from :ref:`advanced_logic_cones`: Because this produces a rather large circuit, it can be useful to split it into smaller parts for viewing and working with. :numref:`submod` does exactly that, -utilising the :cmd:ref:`submod` command to split the circuit into three +utilising the `submod` command to split the circuit into three sections: ``outstage``, ``selstage``, and ``scramble``. .. literalinclude:: /code_examples/selections/submod.ys :language: yoscrypt - :caption: Using :cmd:ref:`submod` to break up the circuit from :file:`memdemo.v` + :caption: Using `submod` to break up the circuit from :file:`memdemo.v` :start-after: cd memdemo :end-before: cd .. :name: submod @@ -481,7 +481,7 @@ below. Evaluation of combinatorial circuits ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -The :cmd:ref:`eval` command can be used to evaluate combinatorial circuits. As +The `eval` command can be used to evaluate combinatorial circuits. As an example, we will use the ``selstage`` subnet of ``memdemo`` which we found above and is shown in :numref:`selstage`. @@ -526,20 +526,20 @@ The ``-table`` option can be used to create a truth table. For example: Assumed undef (x) value for the following signals: \s2 -Note that the :cmd:ref:`eval` command (as well as the :cmd:ref:`sat` command +Note that the `eval` command (as well as the `sat` command discussed in the next sections) does only operate on flattened modules. It can not analyze signals that are passed through design hierarchy levels. So the -:cmd:ref:`flatten` command must be used on modules that instantiate other +`flatten` command must be used on modules that instantiate other modules before these commands can be applied. Solving combinatorial SAT problems ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Often the opposite of the :cmd:ref:`eval` command is needed, i.e. the circuits +Often the opposite of the `eval` command is needed, i.e. the circuits output is given and we want to find the matching input signals. For small circuits with only a few input bits this can be accomplished by trying all possible input combinations, as it is done by the ``eval -table`` command. For -larger circuits however, Yosys provides the :cmd:ref:`sat` command that uses a +larger circuits however, Yosys provides the `sat` command that uses a `SAT`_ solver, `MiniSAT`_, to solve this kind of problems. .. _SAT: http://en.wikipedia.org/wiki/Circuit_satisfiability @@ -551,7 +551,7 @@ larger circuits however, Yosys provides the :cmd:ref:`sat` command that uses a While it is possible to perform model checking directly in Yosys, it is highly recommended to use SBY or EQY for formal hardware verification. -The :cmd:ref:`sat` command works very similar to the :cmd:ref:`eval` command. +The `sat` command works very similar to the `eval` command. The main difference is that it is now also possible to set output values and find the corresponding input values. For Example: @@ -580,7 +580,7 @@ find the corresponding input values. For Example: \s1 0 0 00 \s2 0 0 00 -Note that the :cmd:ref:`sat` command supports signal names in both arguments to +Note that the `sat` command supports signal names in both arguments to the ``-set`` option. In the above example we used ``-set s1 s2`` to constraint ``s1`` and ``s2`` to be equal. When more complex constraints are needed, a wrapper circuit must be constructed that checks the constraints and signals if @@ -642,7 +642,7 @@ of course be to perform the test in 32 bits, for example by replacing ``p != a*b`` in the miter with ``p != {16'd0,a}b``, or by using a temporary variable for the 32 bit product ``a*b``. But as 31 fits well into 8 bits (and as the purpose of this document is to show off Yosys features) we can also simply force -the upper 8 bits of ``a`` and ``b`` to zero for the :cmd:ref:`sat` call, as is +the upper 8 bits of ``a`` and ``b`` to zero for the `sat` call, as is done below. .. todo:: replace inline code @@ -705,16 +705,16 @@ command: sat -seq 6 -show y -show d -set-init-undef \ -max_undef -set-at 4 y 1 -set-at 5 y 2 -set-at 6 y 3 -The ``-seq 6`` option instructs the :cmd:ref:`sat` command to solve a sequential +The ``-seq 6`` option instructs the `sat` command to solve a sequential problem in 6 time steps. (Experiments with lower number of steps have show that at least 3 cycles are necessary to bring the circuit in a state from which the sequence 1, 2, 3 can be produced.) -The ``-set-init-undef`` option tells the :cmd:ref:`sat` command to initialize +The ``-set-init-undef`` option tells the `sat` command to initialize all registers to the undef (``x``) state. The way the ``x`` state is treated in Verilog will ensure that the solution will work for any initial state. -The ``-max_undef`` option instructs the :cmd:ref:`sat` command to find a +The ``-max_undef`` option instructs the `sat` command to find a solution with a maximum number of undefs. This way we can see clearly which inputs bits are relevant to the solution. @@ -807,7 +807,7 @@ is the only way of setting the ``s1`` and ``s2`` registers to a known value. The input values for the other steps are a bit harder to work out manually, but the SAT solver finds the correct solution in an instant. -There is much more to write about the :cmd:ref:`sat` command. For example, there +There is much more to write about the `sat` command. For example, there is a set of options that can be used to performs sequential proofs using temporal induction :cite:p:`een2003temporal`. The command ``help sat`` can be used to print a list of all options with short descriptions of their functions. diff --git a/docs/source/using_yosys/more_scripting/model_checking.rst b/docs/source/using_yosys/more_scripting/model_checking.rst index 92a9d85ce..88eeb9bcd 100644 --- a/docs/source/using_yosys/more_scripting/model_checking.rst +++ b/docs/source/using_yosys/more_scripting/model_checking.rst @@ -17,7 +17,7 @@ passes in Yosys. Other applications include checking if a module conforms to interface standards. -The :cmd:ref:`sat` command in Yosys can be used to perform Symbolic Model +The `sat` command in Yosys can be used to perform Symbolic Model Checking. Checking techmap diff --git a/docs/source/using_yosys/more_scripting/selections.rst b/docs/source/using_yosys/more_scripting/selections.rst index 9c76b20b7..1f0efb1f3 100644 --- a/docs/source/using_yosys/more_scripting/selections.rst +++ b/docs/source/using_yosys/more_scripting/selections.rst @@ -9,7 +9,7 @@ The selection framework .. todo:: reduce overlap with :doc:`/getting_started/scripting_intro` select section -The :cmd:ref:`select` command can be used to create a selection for subsequent +The `select` command can be used to create a selection for subsequent commands. For example: .. code:: yoscrypt @@ -17,7 +17,7 @@ commands. For example: select foobar # select the module foobar delete # delete selected objects -Normally the :cmd:ref:`select` command overwrites a previous selection. The +Normally the `select` command overwrites a previous selection. The commands :yoscrypt:`select -add` and :yoscrypt:`select -del` can be used to add or remove objects from the current selection. @@ -26,16 +26,16 @@ default, which is a complete selection of everything in the current module. This selection framework can also be used directly in many other commands. Whenever a command has ``[selection]`` as last argument in its usage help, this -means that it will use the engine behind the :cmd:ref:`select` command to +means that it will use the engine behind the `select` command to evaluate additional arguments and use the resulting selection instead of the -selection created by the last :cmd:ref:`select` command. +selection created by the last `select` command. -For example, the command :cmd:ref:`delete` will delete everything in the current +For example, the command `delete` will delete everything in the current selection; while :yoscrypt:`delete foobar` will only delete the module foobar. -If no :cmd:ref:`select` command has been made, then the "current selection" will +If no `select` command has been made, then the "current selection" will be the whole design. -.. note:: Many of the examples on this page make use of the :cmd:ref:`show` +.. note:: Many of the examples on this page make use of the `show` command to visually demonstrate the effect of selections. For a more detailed look at this command, refer to :ref:`interactive_show`. @@ -59,7 +59,7 @@ Module and design context ^^^^^^^^^^^^^^^^^^^^^^^^^ Commands can be executed in *module/* or *design/* context. Until now, all -commands have been executed in design context. The :cmd:ref:`cd` command can be +commands have been executed in design context. The `cd` command can be used to switch to module context. In module context, all commands only effect the active module. Objects in the @@ -101,7 +101,7 @@ Operations on selections Combining selections ^^^^^^^^^^^^^^^^^^^^ -The :cmd:ref:`select` command is actually much more powerful than it might seem +The `select` command is actually much more powerful than it might seem at first glance. When it is called with multiple arguments, each argument is evaluated and pushed separately on a stack. After all arguments have been processed it simply creates the union of all elements on the stack. So @@ -190,7 +190,7 @@ Selecting logic cones :numref:`sumprod_01` shows what is called the ``input cone`` of ``sum``, i.e. all cells and signals that are used to generate the signal ``sum``. The ``%ci`` action can be used to select the input cones of all object in the top selection -in the stack maintained by the :cmd:ref:`select` command. +in the stack maintained by the `select` command. As with the ``%x`` action, these commands broaden the selection by one "step". But this time the operation only works against the direction of data flow. That @@ -222,9 +222,9 @@ The following sequence of diagrams demonstrates this step-wise expansion: Notice the subtle difference between :yoscrypt:`show prod %ci` and :yoscrypt:`show prod %ci %ci`. Both images show the `$mul` cell driven by some inputs ``$3_Y`` and ``c``. However it is not until the second image, -having called ``%ci`` the second time, that :cmd:ref:`show` is able to +having called ``%ci`` the second time, that `show` is able to distinguish between ``$3_Y`` being a wire and ``c`` being an input. We can see -this better with the :cmd:ref:`dump` command instead: +this better with the `dump` command instead: .. literalinclude:: /code_examples/selections/sumprod.out :language: RTLIL @@ -276,7 +276,7 @@ look at the first section: This loads :numref:`memdemo_src` and synthesizes the included module. Note that this code can be copied and run directly in a Yosys command line session, provided :file:`memdemo.v` is in the same directory. We can now change to the -``memdemo`` module with ``cd memdemo``, and call :cmd:ref:`show` to see the +``memdemo`` module with ``cd memdemo``, and call `show` to see the diagram in :numref:`memdemo_00`. .. figure:: /_images/code_examples/selections/memdemo_00.* @@ -387,14 +387,14 @@ Storing and recalling selections The current selection can be stored in memory with the command ``select -set ``. It can later be recalled using ``select @``. In fact, the ``@`` expression pushes the stored selection on the stack maintained by -the :cmd:ref:`select` command. So for example :yoscrypt:`select @foo @bar %i` +the `select` command. So for example :yoscrypt:`select @foo @bar %i` will select the intersection between the stored selections ``foo`` and ``bar``. In larger investigation efforts it is highly recommended to maintain a script that sets up relevant selections, so they can easily be recalled, for example when Yosys needs to be re-run after a design or source code change. -The :cmd:ref:`history` command can be used to list all recent interactive +The `history` command can be used to list all recent interactive commands. This feature can be useful for creating such a script from the commands used in an interactive session. diff --git a/docs/source/using_yosys/synthesis/abc.rst b/docs/source/using_yosys/synthesis/abc.rst index fca9ddec0..0c2e4868a 100644 --- a/docs/source/using_yosys/synthesis/abc.rst +++ b/docs/source/using_yosys/synthesis/abc.rst @@ -10,11 +10,11 @@ fine-grained optimisation and LUT mapping. Yosys has two different commands, which both use this logic toolbox, but use it in different ways. -The :cmd:ref:`abc` pass can be used for both ASIC (e.g. :yoscrypt:`abc +The `abc` pass can be used for both ASIC (e.g. :yoscrypt:`abc -liberty`) and FPGA (:yoscrypt:`abc -lut`) mapping, but this page will focus on FPGA mapping. -The :cmd:ref:`abc9` pass generally provides superior mapping quality due to +The `abc9` pass generally provides superior mapping quality due to being aware of combination boxes and DFF and LUT timings, giving it a more global view of the mapping problem. @@ -23,7 +23,7 @@ global view of the mapping problem. ABC: the unit delay model, simple and efficient ----------------------------------------------- -The :cmd:ref:`abc` pass uses a highly simplified view of an FPGA: +The `abc` pass uses a highly simplified view of an FPGA: - An FPGA is made up of a network of inputs that connect through LUTs to a network of outputs. These inputs may actually be I/O pins, D flip-flops, @@ -126,7 +126,7 @@ guide to the syntax: By convention, all delays in ``specify`` blocks are in integer picoseconds. Files containing ``specify`` blocks should be read with the ``-specify`` option -to :cmd:ref:`read_verilog` so that they aren't skipped. +to `read_verilog` so that they aren't skipped. LUTs ^^^^ @@ -145,9 +145,9 @@ DFFs DFFs should be annotated with an ``(* abc9_flop *)`` attribute, however ABC9 has some specific requirements for this to be valid: - the DFF must initialise to -zero (consider using :cmd:ref:`dfflegalize` to ensure this). - the DFF cannot -have any asynchronous resets/sets (see the simplification idiom and the Boxes -section for what to do here). +zero (consider using `dfflegalize` to ensure this). - the DFF cannot have any +asynchronous resets/sets (see the simplification idiom and the Boxes section for +what to do here). It is worth noting that in pure ``abc9`` mode, only the setup and arrival times are passed to ABC9 (specifically, they are modelled as buffers with the given @@ -158,9 +158,9 @@ Some vendors have universal DFF models which include async sets/resets even when they're unused. Therefore *the simplification idiom* exists to handle this: by using a ``techmap`` file to discover flops which have a constant driver to those asynchronous controls, they can be mapped into an intermediate, simplified flop -which qualifies as an ``(* abc9_flop *)``, ran through :cmd:ref:`abc9`, and then -mapped back to the original flop. This is used in :cmd:ref:`synth_intel_alm` and -:cmd:ref:`synth_quicklogic` for the PolarPro3. +which qualifies as an ``(* abc9_flop *)``, ran through `abc9`, and then mapped +back to the original flop. This is used in `synth_intel_alm` and +`synth_quicklogic` for the PolarPro3. DFFs are usually specified to have setup constraints against the clock on the input signals, and an arrival time for the ``Q`` output. diff --git a/docs/source/using_yosys/synthesis/cell_libs.rst b/docs/source/using_yosys/synthesis/cell_libs.rst index 58b6431a5..c8dbba838 100644 --- a/docs/source/using_yosys/synthesis/cell_libs.rst +++ b/docs/source/using_yosys/synthesis/cell_libs.rst @@ -54,7 +54,7 @@ Our circuit now looks like this: :class: width-helper invert-helper :name: counter-hierarchy - ``counter`` after :cmd:ref:`hierarchy` + ``counter`` after `hierarchy` Coarse-grain representation ~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -82,7 +82,7 @@ Logic gate mapping .. figure:: /_images/code_examples/intro/counter_02.* :class: width-helper invert-helper - ``counter`` after :cmd:ref:`techmap` + ``counter`` after `techmap` Mapping to hardware ~~~~~~~~~~~~~~~~~~~ @@ -102,7 +102,7 @@ Recall that the Yosys built-in logic gate types are `$_NOT_`, `$_AND_`, `$_OR_`, `$_XOR_`, and `$_MUX_` with an assortment of dff memory types. :ref:`mycells-lib` defines our target cells as ``BUF``, ``NOT``, ``NAND``, ``NOR``, and ``DFF``. Mapping between these is performed with the commands -:cmd:ref:`dfflibmap` and :cmd:ref:`abc` as follows: +`dfflibmap` and `abc` as follows: .. literalinclude:: /code_examples/intro/counter.ys :language: yoscrypt @@ -117,7 +117,7 @@ The final version of our ``counter`` module looks like this: ``counter`` after hardware cell mapping -Before finally being output as a verilog file with :cmd:ref:`write_verilog`, +Before finally being output as a verilog file with `write_verilog`, which can then be loaded into another tool: .. literalinclude:: /code_examples/intro/counter.ys diff --git a/docs/source/using_yosys/synthesis/extract.rst b/docs/source/using_yosys/synthesis/extract.rst index c9b76840e..176e2ffdd 100644 --- a/docs/source/using_yosys/synthesis/extract.rst +++ b/docs/source/using_yosys/synthesis/extract.rst @@ -1,13 +1,13 @@ The extract pass ---------------- -- Like the :cmd:ref:`techmap` pass, the :cmd:ref:`extract` pass is called with a +- Like the `techmap` pass, the `extract` pass is called with a map file. It compares the circuits inside the modules of the map file with the design and looks for sub-circuits in the design that match any of the modules in the map file. -- If a match is found, the :cmd:ref:`extract` pass will replace the matching +- If a match is found, the `extract` pass will replace the matching subcircuit with an instance of the module from the map file. -- In a way the :cmd:ref:`extract` pass is the inverse of the techmap pass. +- In a way the `extract` pass is the inverse of the techmap pass. .. todo:: add/expand supporting text, also mention custom pattern matching and pmgen @@ -25,7 +25,7 @@ Example code can be found in |code_examples/macc|_. .. figure:: /_images/code_examples/macc/macc_simple_test_00a.* :class: width-helper invert-helper - before :cmd:ref:`extract` + before `extract` .. literalinclude:: /code_examples/macc/macc_simple_test.ys :language: yoscrypt @@ -34,7 +34,7 @@ Example code can be found in |code_examples/macc|_. .. figure:: /_images/code_examples/macc/macc_simple_test_00b.* :class: width-helper invert-helper - after :cmd:ref:`extract` + after `extract` .. literalinclude:: /code_examples/macc/macc_simple_test.v :language: verilog @@ -76,18 +76,18 @@ wrap-extract-unwrap method: wrap Identify candidate-cells in the circuit and wrap them in a cell with a - constant wider bit-width using :cmd:ref:`techmap`. The wrappers use the same + constant wider bit-width using `techmap`. The wrappers use the same parameters as the original cell, so the information about the original width - of the ports is preserved. Then use the :cmd:ref:`connwrappers` command to + of the ports is preserved. Then use the `connwrappers` command to connect up the bit-extended in- and outputs of the wrapper cells. extract Now all operations are encoded using the same bit-width as the coarse grain - element. The :cmd:ref:`extract` command can be used to replace circuits with + element. The `extract` command can be used to replace circuits with cells of the target architecture. unwrap - The remaining wrapper cell can be unwrapped using :cmd:ref:`techmap`. + The remaining wrapper cell can be unwrapped using `techmap`. Example: DSP48_MACC ~~~~~~~~~~~~~~~~~~~ @@ -127,7 +127,7 @@ Extract: :file:`macc_xilinx_xmap.v` :caption: :file:`macc_xilinx_xmap.v` ... simply use the same wrapping commands on this module as on the design to -create a template for the :cmd:ref:`extract` command. +create a template for the `extract` command. Unwrapping multipliers: :file:`macc_xilinx_unwrap_map.v` diff --git a/docs/source/using_yosys/synthesis/fsm.rst b/docs/source/using_yosys/synthesis/fsm.rst index 3c5a80ad3..cb65a298b 100644 --- a/docs/source/using_yosys/synthesis/fsm.rst +++ b/docs/source/using_yosys/synthesis/fsm.rst @@ -1,14 +1,14 @@ FSM handling ============ -The :cmd:ref:`fsm` command identifies, extracts, optimizes (re-encodes), and +The `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: .. literalinclude:: /code_examples/macro_commands/fsm.ys :language: yoscrypt :start-after: #end: - :caption: Passes called by :cmd:ref:`fsm` + :caption: Passes called by `fsm` See also :doc:`/cmd/fsm`. @@ -18,7 +18,7 @@ general reported technique :cite:p:`fsmextract`. FSM detection ~~~~~~~~~~~~~ -The :cmd:ref:`fsm_detect` pass identifies FSM state registers. It sets the +The `fsm_detect` pass identifies FSM state registers. It sets the ``\fsm_encoding = "auto"`` attribute on any (multi-bit) wire that matches the following description: @@ -44,7 +44,7 @@ results. FSM extraction ~~~~~~~~~~~~~~ -The :cmd:ref:`fsm_extract` pass operates on all state signals marked with the +The `fsm_extract` pass operates on all state signals marked with the (``\fsm_encoding != "none"``) attribute. For each state signal the following information is determined: @@ -87,7 +87,7 @@ given set of result signals using a set of signal-value assignments. It can also be passed a list of stop-signals that abort the ConstEval algorithm if the value of a stop-signal is needed in order to calculate the result signals. -The :cmd:ref:`fsm_extract` pass uses the ConstEval class in the following way to +The `fsm_extract` pass uses the ConstEval class in the following way to create a transition table. For each state: 1. Create a ConstEval object for the module containing the FSM @@ -108,12 +108,12 @@ drivers for the control outputs are disconnected. FSM optimization ~~~~~~~~~~~~~~~~ -The :cmd:ref:`fsm_opt` pass performs basic optimizations on `$fsm` cells (not +The `fsm_opt` pass performs basic optimizations on `$fsm` cells (not including state recoding). The following optimizations are performed (in this order): - Unused control outputs are removed from the `$fsm` cell. The attribute - ``\unused_bits`` (that is usually set by the :cmd:ref:`opt_clean` pass) is + ``\unused_bits`` (that is usually set by the `opt_clean` pass) is used to determine which control outputs are unused. - Control inputs that are connected to the same driver are merged. @@ -134,11 +134,11 @@ order): FSM recoding ~~~~~~~~~~~~ -The :cmd:ref:`fsm_recode` pass assigns new bit pattern to the states. Usually +The `fsm_recode` pass assigns new bit pattern to the states. Usually this also implies a change in the width of the state signal. At the moment of this writing only one-hot encoding with all-zero for the reset state is supported. -The :cmd:ref:`fsm_recode` pass can also write a text file with the changes +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. diff --git a/docs/source/using_yosys/synthesis/index.rst b/docs/source/using_yosys/synthesis/index.rst index c00a940da..ae6da302a 100644 --- a/docs/source/using_yosys/synthesis/index.rst +++ b/docs/source/using_yosys/synthesis/index.rst @@ -8,17 +8,17 @@ coarse-grain optimizations before being mapped to hard blocks and fine-grain cells. Most commands in Yosys will target either coarse-grain representation or fine-grain representation, with only a select few compatible with both states. -Commands such as :cmd:ref:`proc`, :cmd:ref:`fsm`, and :cmd:ref:`memory` rely on +Commands such as `proc`, `fsm`, and `memory` rely on the additional information in the coarse-grain representation, along with a -number of optimizations such as :cmd:ref:`wreduce`, :cmd:ref:`share`, and -:cmd:ref:`alumacc`. :cmd:ref:`opt` provides optimizations which are useful in -both states, while :cmd:ref:`techmap` is used to convert coarse-grain cells +number of optimizations such as `wreduce`, `share`, and +`alumacc`. `opt` provides optimizations which are useful in +both states, while `techmap` is used to convert coarse-grain cells to the corresponding fine-grain representation. Single-bit cells (logic gates, FFs) as well as LUTs, half-adders, and full-adders make up the bulk of the fine-grain representation and are necessary -for commands such as :cmd:ref:`abc`\ /:cmd:ref:`abc9`, :cmd:ref:`simplemap`, -:cmd:ref:`dfflegalize`, and :cmd:ref:`memory_map`. +for commands such as `abc`\ /`abc9`, `simplemap`, +`dfflegalize`, and `memory_map`. .. toctree:: :maxdepth: 3 diff --git a/docs/source/using_yosys/synthesis/memory.rst b/docs/source/using_yosys/synthesis/memory.rst index dcbde2ae6..ad8b47d78 100644 --- a/docs/source/using_yosys/synthesis/memory.rst +++ b/docs/source/using_yosys/synthesis/memory.rst @@ -1,11 +1,11 @@ Memory handling =============== -The :cmd:ref:`memory` command +The `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` +consolidating the number of ports for a memory easier. The `memory` pass transforms memories to an implementation. Per default that is logic for address decoders and registers. It also is a macro command that calls the other common ``memory_*`` passes in a sensible order: @@ -13,19 +13,19 @@ common ``memory_*`` passes in a sensible order: .. literalinclude:: /code_examples/macro_commands/memory.ys :language: yoscrypt :start-after: #end: - :caption: Passes called by :cmd:ref:`memory` + :caption: Passes called by `memory` .. todo:: Make ``memory_*`` notes less quick Some quick notes: -- :cmd:ref:`memory_dff` merges registers into the memory read- and write cells. -- :cmd:ref:`memory_collect` collects all read and write cells for a memory and +- `memory_dff` merges registers into the memory read- and write cells. +- `memory_collect` collects all read and write cells for a memory and transforms them into one multi-port memory cell. -- :cmd:ref:`memory_map` takes the multi-port memory cell and transforms it to +- `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 +For more information about `memory`, such as disabling certain sub commands, see :doc:`/cmd/memory`. Example @@ -75,22 +75,22 @@ For example: techmap -map my_memory_map.v memory_map -:cmd:ref:`memory_libmap` attempts to convert memory cells (`$mem_v2` etc) into +`memory_libmap` attempts to convert memory cells (`$mem_v2` etc) into hardware supported memory using a provided library (:file:`my_memory_map.txt` in the example above). Where necessary, emulation logic is added to ensure functional equivalence before and after this conversion. :yoscrypt:`techmap -map -my_memory_map.v` then uses :cmd:ref:`techmap` to map to hardware primitives. Any +my_memory_map.v` then uses `techmap` to map to hardware primitives. Any leftover memory cells unable to be converted are then picked up by -:cmd:ref:`memory_map` and mapped to DFFs and address decoders. +`memory_map` and mapped to DFFs and address decoders. .. note:: More information about what mapping options are available and associated costs of each can be found by enabling debug outputs. This can be done with - the :cmd:ref:`debug` command, or by using the ``-g`` flag when calling Yosys + the `debug` command, or by using the ``-g`` flag when calling Yosys to globally enable debug messages. -For more on the lib format for :cmd:ref:`memory_libmap`, see +For more on the lib format for `memory_libmap`, see `passes/memory/memlib.md `_ diff --git a/docs/source/using_yosys/synthesis/opt.rst b/docs/source/using_yosys/synthesis/opt.rst index cd40f6999..db1525a05 100644 --- a/docs/source/using_yosys/synthesis/opt.rst +++ b/docs/source/using_yosys/synthesis/opt.rst @@ -6,10 +6,10 @@ This chapter outlines these optimizations. .. todo:: "outlines these optimizations" or "outlines *some*.."? -The :cmd:ref:`opt` macro command +The `opt` macro command -------------------------------- -The Yosys pass :cmd:ref:`opt` runs a number of simple optimizations. This +The Yosys pass `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. As listed in :doc:`/cmd/opt`, this macro command calls the following ``opt_*`` commands: @@ -17,11 +17,11 @@ to run this pass after each major step in the synthesis script. As listed in .. literalinclude:: /code_examples/macro_commands/opt.ys :language: yoscrypt :start-after: #end: - :caption: Passes called by :cmd:ref:`opt` + :caption: Passes called by `opt` .. _adv_opt_expr: -Constant folding and simple expression rewriting - :cmd:ref:`opt_expr` +Constant folding and simple expression rewriting - `opt_expr` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. todo:: unsure if this is too much detail and should be in :doc:`/yosys_internals/index` @@ -31,7 +31,7 @@ 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`. +.. table:: Const folding rules for `$_AND_` cells as used in `opt_expr`. :name: tab:opt_expr_and :align: center @@ -69,7 +69,7 @@ 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 +Besides this basic const folding the `opt_expr` pass can replace 1-bit wide `$eq` and `$ne` cells with buffers or not-gates if one input is constant. Equality checks may also be reduced in size if there are redundant bits in the arguments (i.e. bits which are constant on both inputs). This can, @@ -77,7 +77,7 @@ for example, result in a 32-bit wide constant like ``255`` being reduced to the 8-bit value of ``8'11111111`` if the signal being compared is only 8-bit as in :ref:`addr_gen_clean` of :doc:`/getting_started/example_synth`. -The :cmd:ref:`opt_expr` pass is very conservative regarding optimizing `$mux` +The `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. @@ -85,14 +85,14 @@ trees can interfere with other optimizations. :language: Verilog :start-after: read_verilog <fixup_ports()`` after changing the ``port_*`` properties of wires. - You can safely remove cells or change the ``connections`` property of a cell, diff --git a/docs/source/yosys_internals/flow/verilog_frontend.rst b/docs/source/yosys_internals/flow/verilog_frontend.rst index 7c8c9d8fb..fced46e8c 100644 --- a/docs/source/yosys_internals/flow/verilog_frontend.rst +++ b/docs/source/yosys_internals/flow/verilog_frontend.rst @@ -600,15 +600,15 @@ The proc pass The ProcessGenerator converts a behavioural model in AST representation to a behavioural model in ``RTLIL::Process`` representation. The actual conversion from a behavioural model to an RTL representation is performed by the -:cmd:ref:`proc` pass and the passes it launches: +`proc` pass and the passes it launches: -- | :cmd:ref:`proc_clean` and :cmd:ref:`proc_rmdead` +- | `proc_clean` and `proc_rmdead` | These two passes just clean up the ``RTLIL::Process`` structure. The - :cmd:ref:`proc_clean` pass removes empty parts (eg. empty assignments) from - the process and :cmd:ref:`proc_rmdead` detects and removes unreachable + `proc_clean` pass removes empty parts (eg. empty assignments) from + the process and `proc_rmdead` detects and removes unreachable branches from the process's decision trees. -- | :cmd:ref:`proc_arst` +- | `proc_arst` | This pass detects processes that describe d-type flip-flops with asynchronous resets and rewrites the process to better reflect what they are modelling: Before this pass, an asynchronous reset has two @@ -616,21 +616,21 @@ from a behavioural model to an RTL representation is performed by the reset path. After this pass the sync rule for the reset is level-sensitive and the top-level ``RTLIL::SwitchRule`` has been removed. -- | :cmd:ref:`proc_mux` +- | `proc_mux` | This pass converts the ``RTLIL::CaseRule``/\ ``RTLIL::SwitchRule``-tree to a tree of multiplexers per written signal. After this, the ``RTLIL::Process`` structure only contains the ``RTLIL::SyncRule`` s that describe the output registers. -- | :cmd:ref:`proc_dff` +- | `proc_dff` | This pass replaces the ``RTLIL::SyncRule``\ s to d-type flip-flops (with asynchronous resets if necessary). -- | :cmd:ref:`proc_dff` +- | `proc_dff` | This pass replaces the ``RTLIL::MemWriteAction``\ s with `$memwr` cells. -- | :cmd:ref:`proc_clean` - | A final call to :cmd:ref:`proc_clean` removes the now empty +- | `proc_clean` + | A final call to `proc_clean` removes the now empty ``RTLIL::Process`` objects. Performing these last processing steps in passes instead of in the Verilog diff --git a/docs/source/yosys_internals/formats/cell_library.rst b/docs/source/yosys_internals/formats/cell_library.rst index cd1496e11..e9ed4d7f9 100644 --- a/docs/source/yosys_internals/formats/cell_library.rst +++ b/docs/source/yosys_internals/formats/cell_library.rst @@ -258,7 +258,7 @@ additional two parameters: ``\ARST_VALUE`` The state of ``\Q`` will be set to this value when the reset is active. -Usually these cells are generated by the :cmd:ref:`proc` pass using the +Usually these cells are generated by the `proc` pass using the information in the designs RTLIL::Process objects. D-type flip-flops with synchronous reset are represented by `$sdff` cells. As @@ -472,7 +472,7 @@ synthesis to succeed. initialization conflict. The HDL frontend models a memory using ``RTLIL::Memory`` objects and -asynchronous `$memrd_v2` and `$memwr_v2` cells. The :cmd:ref:`memory` pass +asynchronous `$memrd_v2` and `$memwr_v2` cells. The `memory` pass (i.e. its various sub-passes) migrates `$dff` cells into the `$memrd_v2` and `$memwr_v2` cells making them synchronous, then converts them to a single `$mem_v2` cell and (optionally) maps this cell type to `$dff` cells for the @@ -604,14 +604,14 @@ The `$mem_v2` cell has the following ports: This input is ``\WR_PORTS*\WIDTH`` bits wide, containing all data signals for the write ports. -The :cmd:ref:`memory_collect` pass can be used to convert discrete +The `memory_collect` pass can be used to convert discrete `$memrd_v2`, `$memwr_v2`, and `$meminit_v2` cells belonging to the same -memory to a single `$mem_v2` cell, whereas the :cmd:ref:`memory_unpack` pass -performs the inverse operation. The :cmd:ref:`memory_dff` pass can combine +memory to a single `$mem_v2` cell, whereas the `memory_unpack` pass +performs the inverse operation. The `memory_dff` pass can combine asynchronous memory ports that are fed by or feeding registers into synchronous -memory ports. The :cmd:ref:`memory_bram` pass can be used to recognize +memory ports. The `memory_bram` pass can be used to recognize `$mem_v2` cells that can be implemented with a block RAM resource on an FPGA. -The :cmd:ref:`memory_map` pass can be used to implement `$mem_v2` cells as +The `memory_map` pass can be used to implement `$mem_v2` cells as basic logic: word-wide DFFs and address decoders. Finite state machines diff --git a/docs/source/yosys_internals/formats/rtlil_rep.rst b/docs/source/yosys_internals/formats/rtlil_rep.rst index 785a2d28b..fec970532 100644 --- a/docs/source/yosys_internals/formats/rtlil_rep.rst +++ b/docs/source/yosys_internals/formats/rtlil_rep.rst @@ -76,7 +76,7 @@ This has three advantages: - Second, the information about which identifiers were originally provided by the user is always available which can help guide some optimizations. For - example, :cmd:ref:`opt_clean` tries to preserve signals with a user-provided + example, `opt_clean` tries to preserve signals with a user-provided name but doesn't hesitate to delete signals that have auto-generated names when they just duplicate other signals. Note that this can be overridden with the ``-purge`` option to also delete internal nets with user-provided @@ -320,7 +320,7 @@ trees before further processing them. One of the first actions performed on a design in RTLIL representation in most synthesis scripts is identifying asynchronous resets. This is usually done using -the :cmd:ref:`proc_arst` pass. This pass transforms the above example to the +the `proc_arst` pass. This pass transforms the above example to the following ``RTLIL::Process``: .. code:: RTLIL diff --git a/docs/source/yosys_internals/techmap.rst b/docs/source/yosys_internals/techmap.rst index e5d6972ee..f894394bb 100644 --- a/docs/source/yosys_internals/techmap.rst +++ b/docs/source/yosys_internals/techmap.rst @@ -1,7 +1,7 @@ Techmap by example ------------------ -As a quick recap, the :cmd:ref:`techmap` command replaces cells in the design +As a quick recap, the `techmap` command replaces cells in the design with implementations given as Verilog code (called "map files"). It can replace Yosys' internal cell types (such as `$or`) as well as user-defined cell types. @@ -87,14 +87,14 @@ Scripting in map modules - You can even call techmap recursively! - Example use-cases: - - Using always blocks in map module: call :cmd:ref:`proc` - - Perform expensive optimizations (such as :cmd:ref:`freduce`) on cells + - Using always blocks in map module: call `proc` + - Perform expensive optimizations (such as `freduce`) on cells where this is known to work well. - Interacting with custom commands. .. note:: PROTIP: - Commands such as :cmd:ref:`shell`, ``show -pause``, and :cmd:ref:`dump` can + Commands such as `shell`, ``show -pause``, and `dump` can be used in the ``_TECHMAP_DO_*`` scripts for debugging map modules. Example: