From 9878e69d6c6450a90f16f4c5649328221ebaa968 Mon Sep 17 00:00:00 2001 From: Krystine Sherwin <93062060+KrystalDelusion@users.noreply.github.com> Date: Tue, 30 Jan 2024 13:31:00 +1300 Subject: [PATCH] Docs: tidying - Use `:file:` role for file names, as well as `:makevar:` and `:program:`. - Remove deprecated `linux-arm` and `linux-riscv64` oss-cad-suite targets. - Add link to ABC. - More (and better) links to code examples. Formatted `:file:` text with link to source on github. - Includes a few extra todos (mostly picking up inline code blocks and a couple intro reminders). - Fixing a few missing `:yoscrypt:` and `:cmd:ref:` tags. - Reflowing some paragraphs for spacing/width. --- docs/source/appendix/env_vars.rst | 10 +- docs/source/getting_started/example_synth.rst | 22 ++-- docs/source/getting_started/installation.rst | 38 +++--- .../getting_started/scripting_intro.rst | 32 ++--- .../interactive_investigation.rst | 109 +++++++++++------- .../more_scripting/model_checking.rst | 32 +++-- .../using_yosys/more_scripting/selections.rst | 28 +++-- .../using_yosys/synthesis/cell_libs.rst | 28 ++--- docs/source/using_yosys/synthesis/extract.rst | 45 ++++---- docs/source/using_yosys/synthesis/memory.rst | 15 ++- docs/source/using_yosys/synthesis/proc.rst | 17 ++- .../extending_yosys/abc_flow.rst | 10 +- .../extending_yosys/extensions.rst | 41 ++++--- docs/source/yosys_internals/flow/index.rst | 1 - .../yosys_internals/flow/verilog_frontend.rst | 73 ++++++------ .../yosys_internals/formats/cell_library.rst | 45 ++++---- docs/source/yosys_internals/formats/index.rst | 2 + docs/source/yosys_internals/techmap.rst | 55 +++++---- 18 files changed, 348 insertions(+), 255 deletions(-) diff --git a/docs/source/appendix/env_vars.rst b/docs/source/appendix/env_vars.rst index bb8ef34df..26cc37c81 100644 --- a/docs/source/appendix/env_vars.rst +++ b/docs/source/appendix/env_vars.rst @@ -2,10 +2,10 @@ Yosys environment variables =========================== ``HOME`` - Yosys command history is stored in ``$HOME/.yosys_history``. Graphics (from - :cmd:ref:`show` and :cmd:ref:`viz` commands) will output to this directory by - default. This environment variable is also used in some cases for resolving - filenames with ``~``. + Yosys command history is stored in :file:`$HOME/.yosys_history`. Graphics + (from :cmd:ref:`show` and :cmd:ref:`viz` commands) will output to this + directory by default. This environment variable is also used in some cases + for resolving filenames with :file:`~`. ``PATH`` May be used in OpenBSD builds for finding the location of Yosys executable. @@ -14,7 +14,7 @@ Yosys environment variables Used for storing temporary files. ``ABC`` - When compiling Yosys with out-of-tree ABC using ``ABCEXTERNAL``, this + When compiling Yosys with out-of-tree ABC using :makevar:`ABCEXTERNAL`, this variable can be used to override the external ABC executable. ``YOSYS_NOVERIFIC`` diff --git a/docs/source/getting_started/example_synth.rst b/docs/source/getting_started/example_synth.rst index edeb2c118..371115117 100644 --- a/docs/source/getting_started/example_synth.rst +++ b/docs/source/getting_started/example_synth.rst @@ -26,7 +26,7 @@ First, let's quickly look at the design we'll be synthesizing: .. literalinclude:: /code_examples/fifo/fifo.v :language: Verilog :linenos: - :caption: ``fifo.v`` + :caption: :file:`fifo.v` :name: fifo-v .. todo:: fifo.v description @@ -36,7 +36,7 @@ Loading the design Let's load the design into Yosys. From the command line, we can call ``yosys fifo.v``. This will open an interactive Yosys shell session and immediately -parse the code from ``fifo.v`` and convert it into an Abstract Syntax Tree +parse the code from :ref:`fifo-v` and convert it into an Abstract Syntax Tree (AST). If you are interested in how this happens, there is more information in the document, :doc:`/yosys_internals/flow/verilog_frontend`. For now, suffice it to say that we do this to simplify further processing of the design. You @@ -214,7 +214,7 @@ could restart our shell session, but instead let's use two new commands: :language: doscon :start-at: design -reset :end-before: yosys> proc - :caption: reloading ``fifo.v`` and running :yoscrypt:`hierarchy -check -top fifo` + :caption: reloading :file:`fifo.v` and running :yoscrypt:`hierarchy -check -top fifo` 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 @@ -234,7 +234,7 @@ design. If we know that our design won't run into this issue, we can skip the The number before a command's output increments with each command run. Don't worry if your numbers don't match ours! The output you are seeing comes from the same script that was used to generate the images in this document, - included in the source as ``fifo.ys``. There are extra commands being run + included in the source as :file:`fifo.ys`. There are extra commands being run which you don't see, but feel free to try them yourself, or play around with different commands. You can always start over with a clean slate by calling ``exit`` or hitting ``ctrl+c`` (i.e. SIGINT) and re-launching the Yosys @@ -305,8 +305,8 @@ optimizations between modules which would otherwise be missed. Let's run 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 ``fifo_reader.addr`` and -merged with the ``raddr`` wire feeding into the ``$memrd`` cell. This wire +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 :ref:`flat_clean`. Note that in an interactive terminal the outputs of :cmd:ref:`flatten` and :cmd:ref:`clean` will be combined into a single @@ -803,11 +803,11 @@ The iCE40 synthesis flow has the following output modes available: - :doc:`/cmd/write_json`. As an example, if we called :yoscrypt:`synth_ice40 -top fifo -json fifo.json`, -our synthesized ``fifo`` design will be output as ``fifo.json``. We can then -read the design back into Yosys with :cmd:ref:`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. +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 +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. .. _nextpnr: https://github.com/YosysHQ/nextpnr diff --git a/docs/source/getting_started/installation.rst b/docs/source/getting_started/installation.rst index e8dbbe77a..302d6d291 100644 --- a/docs/source/getting_started/installation.rst +++ b/docs/source/getting_started/installation.rst @@ -49,9 +49,7 @@ The `OSS CAD Suite`_ releases `nightly builds`_ for the following architectures: - Targeted for Windows 10 and 11, but older 64-bit version of Windows 7, 8, or 8.1 should work - - linux-arm |linux-arm| - linux-arm64 |linux-arm64| - - linux-riscv64 (untested) |linux-riscv64| .. _OSS CAD Suite: https://github.com/YosysHQ/oss-cad-suite-build .. _nightly builds: https://github.com/YosysHQ/oss-cad-suite-build/releases/latest @@ -60,9 +58,7 @@ The `OSS CAD Suite`_ releases `nightly builds`_ for the following architectures: .. |darwin-x64| image:: https://github.com/YosysHQ/oss-cad-suite-build/actions/workflows/darwin-x64.yml/badge.svg .. |darwin-arm64| image:: https://github.com/YosysHQ/oss-cad-suite-build/actions/workflows/darwin-arm64.yml/badge.svg .. |windows-x64| image:: https://github.com/YosysHQ/oss-cad-suite-build/actions/workflows/windows-x64.yml/badge.svg -.. |linux-arm| image:: https://github.com/YosysHQ/oss-cad-suite-build/actions/workflows/linux-arm.yml/badge.svg .. |linux-arm64| image:: https://github.com/YosysHQ/oss-cad-suite-build/actions/workflows/linux-arm64.yml/badge.svg -.. |linux-riscv64| image:: https://github.com/YosysHQ/oss-cad-suite-build/actions/workflows/linux-riscv64.yml/badge.svg Building from source ~~~~~~~~~~~~~~~~~~~~ @@ -133,8 +129,10 @@ Then, simply run ``make`` in this directory. make sudo make install -Note that this also downloads, builds, and installs ABC (using yosys-abc as the -executable name). +Note that this also downloads, builds, and installs `ABC`_ (using +:program:`yosys-abc` as the executable name). + +.. _ABC: https://github.com/berkeley-abc/abc .. seealso:: @@ -167,11 +165,12 @@ directories: ``kernel/`` This directory contains all the core functionality of Yosys. This includes the functions and definitions for working with the RTLIL data structures - (``rtlil.{h|cc}``), the ``main()`` function (``driver.cc``), the internal - framework for generating log messages (``log.{h|cc}``), the internal - framework for registering and calling passes (``register.{h|cc}``), some core - commands that are not really passes (``select.cc``, ``show.cc``, …) and a - couple of other small utility libraries. + (:file:`rtlil.{h|cc}`), the ``main()`` function (:file:`driver.cc`), the + internal framework for generating log messages (:file:`log.{h|cc}`), the + internal framework for registering and calling passes + (:file:`register.{h|cc}`), some core commands that are not really passes + (:file:`select.cc`, :file:`show.cc`, …) and a couple of other small utility + libraries. ``libs/`` Libraries packaged with Yosys builds are contained in this folder. See @@ -182,7 +181,7 @@ directories: ``passes/`` This directory contains a subdirectory for each pass or group of passes. For - example as of this writing the directory ``passes/hierarchy/`` contains the + 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`. @@ -194,15 +193,16 @@ directories: This directory contains the suite of unit tests and regression tests used by Yosys. See :doc:`/test_suites`. -The top-level Makefile includes ``frontends/*/Makefile.inc``, -``passes/*/Makefile.inc`` and ``backends/*/Makefile.inc``. So when extending -Yosys it is enough to create a new directory in ``frontends/``, ``passes/`` or -``backends/`` with your sources and a ``Makefile.inc``. The Yosys kernel -automatically detects all commands linked with Yosys. So it is not needed to add -additional commands to a central list of commands. +The top-level Makefile includes :file:`frontends/{*}/Makefile.inc`, +:file:`passes/{*}/Makefile.inc` and :file:`backends/{*}/Makefile.inc`. So when +extending Yosys it is enough to create a new directory in :file:`frontends/`, +:file:`passes/` or :file:`backends/` with your sources and a +:file:`Makefile.inc`. The Yosys kernel automatically detects all commands linked +with Yosys. So it is not needed to add additional commands to a central list of +commands. Good starting points for reading example source code to learn how to write -passes are ``passes/opt/opt_dff.cc`` and ``passes/opt/opt_merge.cc``. +passes are :file:`passes/opt/opt_dff.cc` and :file:`passes/opt/opt_merge.cc`. See the top-level README file for a quick Getting Started guide and build instructions. The Yosys build is based solely on Makefiles. diff --git a/docs/source/getting_started/scripting_intro.rst b/docs/source/getting_started/scripting_intro.rst index e971432c0..63eca9901 100644 --- a/docs/source/getting_started/scripting_intro.rst +++ b/docs/source/getting_started/scripting_intro.rst @@ -5,13 +5,13 @@ On the previous page we went through a synthesis script, running each command in the interactive Yosys shell. On this page, we will be introducing the script file format and how you can make your own synthesis scripts. -Yosys script files typically use the ``.ys`` extension and contain a set of +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`. As with the interactive shell, each command consists of the command name, and an optional whitespace separated list of arguments. -Commands are terminated with the newline character, or by a semicolon (;). -Empty lines, and lines starting with the hash sign (#), are ignored. +Commands are terminated with the newline character, or by a semicolon (;). Empty +lines, and lines starting with the hash sign (#), are ignored. The synthesis starter script ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -21,7 +21,7 @@ The synthesis starter script All of the images and console output used in :doc:`/getting_started/example_synth` were generated by Yosys, using Yosys -script files found in ``docs/source/code_examples/fifo``. If you haven't +script files found in :file:`docs/source/code_examples/fifo`. If you haven't already, let's take a look at some of those script files now. .. literalinclude:: /code_examples/fifo/fifo.ys @@ -29,7 +29,7 @@ already, let's take a look at some of those script files now. :lineno-match: :start-at: echo on :end-before: design -reset - :caption: A section of ``fifo.ys``, generating the images used for :ref:`addr_gen_example` + :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 @@ -121,9 +121,9 @@ what the different symbols represent, see :ref:`interactive_show` and the .. _GraphViz: http://www.graphviz.org/ .. _xdot: https://github.com/jrfonseca/xdot.py -This is the first :yoscrypt:`show` command we called in ``fifo.ys``, :ref:`as we -saw above `. If we look at the log output for this image we see the -following: +This is the first :yoscrypt:`show` command we called in :file:`fifo.ys`, +:ref:`as we saw above `. If we look at the log output for this image +we see the following: .. literalinclude:: /code_examples/fifo/fifo.out :language: doscon @@ -131,14 +131,14 @@ following: :end-before: yosys> show Calling :cmd:ref:`show` with :yoscrypt:`-format dot` tells it we want to output -a ``.dot`` file rather than opening it for display. The :yoscrypt:`-prefix -addr_gen_show` option indicates we want the file to be called `addr_gen_show.*`. -Remember, we do this in ``fifo.ys`` because we need to store the image for -displaying in the documentation you're reading. But if you just want to display -the images locally you can skip these two options. The ``-format`` option -internally calls the ``dot`` command line program from GraphViz to convert to -formats other than ``.dot``. Check `GraphViz output docs`_ for more on -available formats. +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 +need to store the image for displaying in the documentation you're reading. But +if you just want to display the images locally you can skip these two options. +The ``-format`` option internally calls the ``dot`` command line program from +GraphViz to convert to formats other than :file:`.dot`. Check `GraphViz output +docs`_ for more on available formats. .. _GraphViz output docs: https://graphviz.org/docs/outputs/ diff --git a/docs/source/using_yosys/more_scripting/interactive_investigation.rst b/docs/source/using_yosys/more_scripting/interactive_investigation.rst index 7e01ff06d..d0d78a783 100644 --- a/docs/source/using_yosys/more_scripting/interactive_investigation.rst +++ b/docs/source/using_yosys/more_scripting/interactive_investigation.rst @@ -1,6 +1,8 @@ Interactive design investigation -------------------------------- +.. todo:: interactive design opening text + .. role:: yoscrypt(code) :language: yoscrypt @@ -9,22 +11,24 @@ Interactive design investigation 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 -in the circuit diagrams generated by it. +in the circuit diagrams generated by it. The code used is included in the Yosys +code base under |code_examples/show|_. + +.. |code_examples/show| replace:: :file:`docs/source/code_examples/show` +.. _code_examples/show: https://github.com/YosysHQ/yosys/tree/krys/docs/docs/source/code_examples/show 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. The -code used is included in the Yosys code base under -`docs/source/code_examples/show`_. - -.. _docs/source/code_examples/show: https://github.com/YosysHQ/yosys/tree/krys/docs/docs/source/code_examples/show +will use to demonstrate the usage of :cmd:ref:`show` in a simple setting. .. literalinclude:: /code_examples/show/example.v :language: Verilog - :caption: ``example.v`` + :caption: :file:`example.v` :name: example_v The Yosys synthesis script we will be running is included as @@ -36,7 +40,7 @@ synthesis. .. literalinclude:: /code_examples/show/example_show.ys :language: yoscrypt - :caption: ``example_show.ys`` + :caption: :file:`example_show.ys` :name: example_ys This script, when executed, will show the design after each of the three @@ -45,11 +49,11 @@ is shown. .. note:: - The images uses in this document are generated from the ``example.ys`` file, - rather than ``example_show.ys``. ``example.ys`` outputs the schematics as - ``.dot`` files rather than displaying them directly. You can view these - images yourself by running ``yosys example.ys`` and then ``xdot - example_first.dot`` etc. + The images uses in this document are generated from the :file:`example.ys` + file, rather than :file:`example_show.ys`. :file:`example.ys` outputs the + schematics as :file:`.dot` files rather than displaying them directly. You + can view these images yourself by running :file:`yosys example.ys` and then + ``xdot example_first.dot`` etc. .. figure:: /_images/code_examples/show/example_first.* :class: width-helper @@ -122,7 +126,7 @@ The code listing below shows a simple circuit which uses a lot of spliced signal accesses. .. literalinclude:: /code_examples/show/splice.v - :caption: ``docs/source/code_examples/show/splice.v`` + :caption: :file:`splice.v` :name: splice_src Notice how the output for this circuit from the :cmd:ref:`show` command @@ -199,15 +203,15 @@ 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 `` option. Secondly it is possible to load cell libraries into the design with the -``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. +: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. -In addition to that, :numref:`second_pitfall` was generated after ``splitnet --ports`` was run on the design. This command splits all signal vectors into -individual signal bits, which is often desirable when looking at gate-level -circuits. The ``-ports`` option is required to also split module ports. Per -default the command only operates on interior signals. +In addition to that, :numref:`second_pitfall` was generated after +:yoscrypt:`splitnet -ports` was run on the design. This command splits all +signal vectors into individual signal bits, which is often desirable when +looking at gate-level circuits. The ``-ports`` option is required to also split +module ports. Per default the command only operates on interior signals. Miscellaneous notes ^^^^^^^^^^^^^^^^^^^ @@ -225,16 +229,16 @@ 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 ``help show`` prints a complete listing of all options supported by -the :cmd:ref:`show` command. +The command :yoscrypt:`help show` prints a complete listing of all options +supported by the :cmd:ref:`show` command. Navigating the design ~~~~~~~~~~~~~~~~~~~~~ -Plotting circuit diagrams for entire modules in the design brings us -only helps in simple cases. For complex modules the generated circuit -diagrams are just stupidly big and are no help at all. In such cases one -first has to select the relevant portions of the circuit. +Plotting circuit diagrams for entire modules in the design brings us only helps +in simple cases. For complex modules the generated circuit diagrams are just +stupidly big and are no help at all. In such cases one first has to select the +relevant portions of the circuit. 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 @@ -244,10 +248,12 @@ reproduced. So if, for example, the internal state before calling the the coarse-grain version of the circuit before :cmd:ref:`techmap` than the gate-level circuit after :cmd:ref:`techmap`. -.. Note:: It is generally recommended to verify the internal state of a - design by writing it to a Verilog file using ``write_verilog -noexpr`` - and using the simulation models from ``simlib.v`` and ``simcells.v`` - from the Yosys data directory (as printed by ``yosys-config --datdir``). +.. Note:: + + It is generally recommended to verify the internal state of a design by + writing it to a Verilog file using :yoscrypt:`write_verilog -noexpr` and + using the simulation models from :file:`simlib.v` and :file:`simcells.v` from + the Yosys data directory (as printed by ``yosys-config --datdir``). Interactive navigation ^^^^^^^^^^^^^^^^^^^^^^ @@ -263,13 +269,14 @@ 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 -module. This is demonstrated below using ``example.v`` from `A simple circuit`_: +module. This is demonstrated below using :file:`example.v` from `A simple +circuit`_: .. literalinclude:: /code_examples/show/example.out :language: doscon :start-at: yosys> ls :end-before: yosys [example]> dump - :caption: Output of :cmd:ref:`ls` and :cmd:ref:`cd` after running ``yosys example.v`` + :caption: Output of :cmd:ref:`ls` and :cmd:ref:`cd` after running :file:`yosys example.v` :name: lscd When a module is selected using the :cmd:ref:`cd` command, all commands (with a @@ -324,6 +331,12 @@ tools). - :doc:`/cmd/dump`. - :doc:`/cmd/add` and :doc:`/cmd/delete` can be used to modify and reorganize a design dynamically. + +The code used is included in the Yosys code base under +|code_examples/scrambler|_. + +.. |code_examples/scrambler| replace:: :file:`docs/source/code_examples/scrambler` +.. _code_examples/scrambler: https://github.com/YosysHQ/yosys/tree/krys/docs/docs/source/code_examples/scrambler Changing design hierarchy ^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -336,11 +349,11 @@ reorganizing a module in Yosys and checking the resulting circuit. .. literalinclude:: /code_examples/scrambler/scrambler.v :language: verilog - :caption: ``docs/source/code_examples/scrambler/scrambler.v`` + :caption: :file:`scrambler.v` .. literalinclude:: /code_examples/scrambler/scrambler.ys :language: yoscrypt - :caption: ``docs/source/code_examples/scrambler/scrambler.ys`` + :caption: :file:`scrambler.ys` :end-before: cd .. .. figure:: /_images/code_examples/scrambler/scrambler_p01.* @@ -351,6 +364,8 @@ reorganizing a module in Yosys and checking the resulting circuit. Analyzing the resulting circuit with :doc:`/cmd/eval`: +.. todo:: replace inline code + .. code:: text > cd xorshift32 @@ -381,6 +396,8 @@ The following techmap map file replaces all positive-edge async reset flip-flops with positive-edge sync reset flip-flops. The code is taken from the example Yosys script for ASIC synthesis of the Amber ARMv2 CPU. +.. todo:: replace inline code + .. code:: verilog (* techmap_celltype = "$adff" *) @@ -435,7 +452,7 @@ sections: ``outstage``, ``selstage``, and ``scramble``. .. literalinclude:: /code_examples/selections/submod.ys :language: yoscrypt - :caption: Using :cmd:ref:`submod` to break up the circuit from ``memdemo.v`` + :caption: Using :cmd:ref:`submod` to break up the circuit from :file:`memdemo.v` :start-after: cd memdemo :end-before: cd .. :name: submod @@ -467,6 +484,8 @@ The :cmd:ref:`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`. +.. todo:: replace inline code + :: yosys [selstage]> eval -set s2,s1 4'b1001 -set d 4'hc -show n2 -show n1 @@ -535,6 +554,8 @@ The :cmd:ref:`sat` command works very similar to the :cmd:ref:`eval` command. The main difference is that it is now also possible to set output values and find the corresponding input values. For Example: +.. todo:: replace inline code + :: yosys [selstage]> sat -show s1,s2,d -set s1 s2 -set n2,n1 4'b1001 @@ -569,7 +590,7 @@ circuit.) .. literalinclude:: /code_examples/primetest.v :language: verilog - :caption: ``primetest.v``, a simple miter circuit for testing if a number is + :caption: :file:`primetest.v`, a simple miter circuit for testing if a number is prime. But it has a problem. :name: primetest @@ -577,8 +598,10 @@ circuit.) number test. If ``ok`` is 1 for all input values ``a`` and ``b`` for a given ``p``, then ``p`` is prime, or at least that is the idea. +.. todo:: replace inline code + .. code-block:: - :caption: Experiments with the miter circuit from ``primetest.v``. + :caption: Experiments with the miter circuit from :file:`primetest.v`. :name: prime_shell yosys [primetest]> sat -prove ok 1 -set p 31 @@ -621,8 +644,10 @@ 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 done below. +.. todo:: replace inline code + .. code-block:: - :caption: Miter circuit from ``primetest.v``, with the upper 8 bits of ``a`` + :caption: Miter circuit from :file:`primetest.v`, with the upper 8 bits of ``a`` and ``b`` constrained to prevent overflow. :name: prime_fixed @@ -672,6 +697,8 @@ want to know which sequence of input values for ``d`` will cause the output y to produce the sequence 1, 2, 3 from any initial state. Let's use the following command: +.. todo:: replace inline code? + .. code-block:: yoscrypt sat -seq 6 -show y -show d -set-init-undef \ @@ -695,6 +722,8 @@ play the 1, 2, 3 sequence, starting with time step 4. This produces the following output: +.. todo:: replace inline code + .. code-block:: :caption: Solving a sequential SAT problem in the ``memdemo`` module. :name: memdemo_sat diff --git a/docs/source/using_yosys/more_scripting/model_checking.rst b/docs/source/using_yosys/more_scripting/model_checking.rst index f0171b14c..0f722e05c 100644 --- a/docs/source/using_yosys/more_scripting/model_checking.rst +++ b/docs/source/using_yosys/more_scripting/model_checking.rst @@ -25,23 +25,27 @@ Checking techmap .. todo:: add/expand supporting text -Let's look at the following example: +Let's take a look at an example included in the Yosys code base under +|code_examples/synth_flow|_: + +.. |code_examples/synth_flow| replace:: :file:`docs/source/code_examples/synth_flow` +.. _code_examples/synth_flow: https://github.com/YosysHQ/yosys/tree/krys/docs/docs/source/code_examples/synth_flow .. literalinclude:: /code_examples/synth_flow/techmap_01_map.v :language: verilog - :caption: ``docs/source/code_examples/synth_flow/techmap_01_map.v`` + :caption: :file:`techmap_01_map.v` .. literalinclude:: /code_examples/synth_flow/techmap_01.v :language: verilog - :caption: ``docs/source/code_examples/synth_flow/techmap_01.v`` + :caption: :file:`techmap_01.v` .. literalinclude:: /code_examples/synth_flow/techmap_01.ys :language: yoscrypt - :caption: ``docs/source/code_examples/synth_flow/techmap_01.ys`` + :caption: :file:`techmap_01.ys` To see if it is correct we can use the following code: -.. todo:: replace inline yosys script code +.. todo:: replace inline code .. code:: yoscrypt @@ -73,6 +77,12 @@ Result: AXI4 Stream Master ~~~~~~~~~~~~~~~~~~ +The code used in this section is included in the Yosys code base under +|code_examples/axis|_. + +.. |code_examples/axis| replace:: :file:`docs/source/code_examples/axis` +.. _code_examples/axis: https://github.com/YosysHQ/yosys/tree/krys/docs/docs/source/code_examples/axis + The following AXI4 Stream Master has a bug. But the bug is not exposed if the slave keeps ``tready`` asserted all the time. (Something a test bench might do.) @@ -83,24 +93,26 @@ values for ``tready`` that yield the incorrect behavior. .. literalinclude:: /code_examples/axis/axis_master.v :language: verilog - :caption: ``docs/source/code_examples/axis/axis_master.v`` + :caption: :file:`axis_master.v` .. literalinclude:: /code_examples/axis/axis_test.v :language: verilog - :caption: ``docs/source/code_examples/axis/axis_test.v`` + :caption: :file:`axis_test.v` .. literalinclude:: /code_examples/axis/axis_test.ys :language: yoscrypt - :caption: ``docs/source/code_examples/axis/test.ys`` + :caption: :file:`test.ys` -Result with unmodified ``axis_master.v``: +Result with unmodified :file:`axis_master.v`: + +.. todo:: replace inline code .. code:: Solving problem with 159344 variables and 442126 clauses.. SAT proof finished - model found: FAIL! -Result with fixed ``axis_master.v``: +Result with fixed :file:`axis_master.v`: .. code:: diff --git a/docs/source/using_yosys/more_scripting/selections.rst b/docs/source/using_yosys/more_scripting/selections.rst index 517304fad..72316d75a 100644 --- a/docs/source/using_yosys/more_scripting/selections.rst +++ b/docs/source/using_yosys/more_scripting/selections.rst @@ -7,6 +7,8 @@ Selections 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 commands. For example: @@ -56,7 +58,7 @@ in synthesis scripts that are hand-tailored for a specific design. Module and design context ^^^^^^^^^^^^^^^^^^^^^^^^^ -Commands can be executed in *module/* or *design/* context. Until now all +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 used to switch to module context. @@ -83,9 +85,12 @@ Selecting by object property or type Special patterns can be used to select by object property or type. For example: - select all wires whose names start with ``reg_``: :yoscrypt:`select w:reg_*` -- select all objects with the attribute ``foobar`` set: :yoscrypt:`select a:foobar` -- select all objects with the attribute ``foobar`` set to 42: :yoscrypt:`select a:foobar=42` -- select all modules with the attribute ``blabla`` set: :yoscrypt:`select A:blabla` +- select all objects with the attribute ``foobar`` set: :yoscrypt:`select + a:foobar` +- select all objects with the attribute ``foobar`` set to 42: :yoscrypt:`select + a:foobar=42` +- select all modules with the attribute ``blabla`` set: :yoscrypt:`select + A:blabla` - select all $add cells from the module foo: :yoscrypt:`select foo/t:$add` A complete list of pattern expressions can be found in :doc:`/cmd/select`. @@ -255,11 +260,11 @@ code is available in ``docs/source/code_examples/selections`` of the Yosys source repository. .. literalinclude:: /code_examples/selections/memdemo.v - :caption: ``memdemo.v`` + :caption: :file:`memdemo.v` :name: memdemo_src :language: verilog -The script ``memdemo.ys`` is used to generate the images included here. Let's +The script :file:`memdemo.ys` is used to generate the images included here. Let's look at the first section: .. literalinclude:: /code_examples/selections/memdemo.ys @@ -270,7 +275,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 ``memdemo.v`` is in the same directory. We can now change to the +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 diagram in :numref:`memdemo_00`. @@ -397,15 +402,18 @@ Remember that select expressions can also be used directly as arguments to most commands. Some commands also accept a single select argument to some options. In those cases selection variables must be used to capture more complex selections. -Example: +Example code from |code_examples/selections|_: + +.. |code_examples/selections| replace:: :file:`docs/source/code_examples/selections` +.. _code_examples/selections: https://github.com/YosysHQ/yosys/tree/krys/docs/docs/source/code_examples/selections .. literalinclude:: /code_examples/selections/select.v :language: verilog - :caption: ``docs/source/code_examples/selections/select.v`` + :caption: :file:`select.v` .. literalinclude:: /code_examples/selections/select.ys :language: yoscrypt - :caption: ``docs/source/code_examples/selections/select.ys`` + :caption: :file:`select.ys` :name: select_ys .. figure:: /_images/code_examples/selections/select.* diff --git a/docs/source/using_yosys/synthesis/cell_libs.rst b/docs/source/using_yosys/synthesis/cell_libs.rst index 4353b3cdc..a2fac8dbf 100644 --- a/docs/source/using_yosys/synthesis/cell_libs.rst +++ b/docs/source/using_yosys/synthesis/cell_libs.rst @@ -7,16 +7,16 @@ Mapping to cell libraries While much of this documentation focuses on the use of Yosys with FPGAs, it is also possible to map to cell libraries which can be used in designing ASICs. This section will cover a brief `example project`_, available in the Yosys -source code as ``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``). Many -of the early steps here are already covered in more detail in the -:doc:`/getting_started/example_synth` document. +source code under :file:`docs/source/code_examples/intro/`. The project +contains a simple ASIC synthesis script (:file:`counter.ys`), a digital design +written in Verilog (:file:`counter.v`), and a simple CMOS cell library +(:file:`mycells.lib`). Many of the early steps here are already covered in more +detail in the :doc:`/getting_started/example_synth` document. .. note:: - The ``counter.ys`` script includes the commands used to generate the images - in this document. Code snippets in this document skip these commands; + The :file:`counter.ys` script includes the commands used to generate the + images in this document. Code snippets in this document skip these commands; including line numbers to allow the reader to follow along with the source. To learn more about these commands, check out :ref:`interactive_show`. @@ -32,7 +32,7 @@ First, let's quickly look at the design: :language: Verilog :linenos: :name: counter-v - :caption: ``counter.v`` + :caption: :file:`counter.v` This is a simple counter with reset and enable. If the reset signal, ``rst``, is high then the counter will reset to 0. Otherwise, if the enable signal, @@ -46,7 +46,7 @@ Loading the design :language: yoscrypt :lines: 1-3 :lineno-match: - :caption: ``counter.ys`` - read design + :caption: :file:`counter.ys` - read design Our circuit now looks like this: @@ -63,7 +63,7 @@ Coarse-grain representation :language: yoscrypt :lines: 7-10 :lineno-match: - :caption: ``counter.ys`` - the high-level stuff + :caption: :file:`counter.ys` - the high-level stuff .. figure:: /_images/code_examples/intro/counter_01.* :class: width-helper @@ -77,7 +77,7 @@ Logic gate mapping :language: yoscrypt :lines: 14-15 :lineno-match: - :caption: ``counter.ys`` - mapping to internal cell library + :caption: :file:`counter.ys` - mapping to internal cell library .. figure:: /_images/code_examples/intro/counter_02.* :class: width-helper @@ -94,7 +94,7 @@ our internal cell library will be mapped to: :language: Liberty :linenos: :name: mycells-lib - :caption: ``mycells.lib`` + :caption: :file:`mycells.lib` Recall that the Yosys built-in logic gate types are ``$_NOT_``, ``$_AND_``, ``$_OR_``, ``$_XOR_``, and ``$_MUX_`` with an assortment of dff memory types. @@ -106,7 +106,7 @@ Recall that the Yosys built-in logic gate types are ``$_NOT_``, ``$_AND_``, :language: yoscrypt :lines: 20-27 :lineno-match: - :caption: ``counter.ys`` - mapping to hardware + :caption: :file:`counter.ys` - mapping to hardware The final version of our ``counter`` module looks like this: @@ -122,4 +122,4 @@ which can then be loaded into another tool: :language: yoscrypt :lines: 30-31 :lineno-match: - :caption: ``counter.ys`` - write synthesized design + :caption: :file:`counter.ys` - write synthesized design diff --git a/docs/source/using_yosys/synthesis/extract.rst b/docs/source/using_yosys/synthesis/extract.rst index c5a64273a..650354469 100644 --- a/docs/source/using_yosys/synthesis/extract.rst +++ b/docs/source/using_yosys/synthesis/extract.rst @@ -12,7 +12,11 @@ The extract pass .. todo:: add/expand supporting text, also mention custom pattern matching and pmgen -Example code can be found in ``docs/source/code_examples/macc/``. +Example code can be found in |code_examples/macc|_. + +.. |code_examples/macc| replace:: :file:`docs/source/code_examples/macc` +.. _code_examples/macc: https://github.com/YosysHQ/yosys/tree/krys/docs/docs/source/code_examples/macc + .. literalinclude:: /code_examples/macc/macc_simple_test.ys :language: yoscrypt @@ -34,15 +38,15 @@ Example code can be found in ``docs/source/code_examples/macc/``. .. literalinclude:: /code_examples/macc/macc_simple_test.v :language: verilog - :caption: ``macc_simple_test.v`` + :caption: :file:`macc_simple_test.v` .. literalinclude:: /code_examples/macc/macc_simple_xmap.v :language: verilog - :caption: ``macc_simple_xmap.v`` + :caption: :file:`macc_simple_xmap.v` .. literalinclude:: /code_examples/macc/macc_simple_test_01.v :language: verilog - :caption: ``macc_simple_test_01.v`` + :caption: :file:`macc_simple_test_01.v` .. figure:: /_images/code_examples/macc/macc_simple_test_01a.* :class: width-helper @@ -52,7 +56,7 @@ Example code can be found in ``docs/source/code_examples/macc/``. .. literalinclude:: /code_examples/macc/macc_simple_test_02.v :language: verilog - :caption: ``macc_simple_test_02.v`` + :caption: :file:`macc_simple_test_02.v` .. figure:: /_images/code_examples/macc/macc_simple_test_02a.* :class: width-helper @@ -90,10 +94,9 @@ Example: DSP48_MACC This section details an example that shows how to map MACC operations of arbitrary size to MACC cells with a 18x25-bit multiplier and a 48-bit adder -(such as the Xilinx DSP48 cells). Source code can be found in -``docs/source/code_examples/macc/``. +(such as the Xilinx DSP48 cells). -Preconditioning: ``macc_xilinx_swap_map.v`` +Preconditioning: :file:`macc_xilinx_swap_map.v` Make sure ``A`` is the smaller port on all multipliers @@ -101,49 +104,49 @@ Make sure ``A`` is the smaller port on all multipliers .. literalinclude:: /code_examples/macc/macc_xilinx_swap_map.v :language: verilog - :caption: ``macc_xilinx_swap_map.v`` + :caption: :file:`macc_xilinx_swap_map.v` -Wrapping multipliers: ``macc_xilinx_wrap_map.v`` +Wrapping multipliers: :file:`macc_xilinx_wrap_map.v` .. literalinclude:: /code_examples/macc/macc_xilinx_wrap_map.v :language: verilog :lines: 1-46 - :caption: ``macc_xilinx_wrap_map.v`` + :caption: :file:`macc_xilinx_wrap_map.v` -Wrapping adders: ``macc_xilinx_wrap_map.v`` +Wrapping adders: :file:`macc_xilinx_wrap_map.v` .. literalinclude:: /code_examples/macc/macc_xilinx_wrap_map.v :language: verilog :lines: 48-89 - :caption: ``macc_xilinx_wrap_map.v`` + :caption: :file:`macc_xilinx_wrap_map.v` -Extract: ``macc_xilinx_xmap.v`` +Extract: :file:`macc_xilinx_xmap.v` .. literalinclude:: /code_examples/macc/macc_xilinx_xmap.v :language: verilog - :caption: ``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. -Unwrapping multipliers: ``macc_xilinx_unwrap_map.v`` +Unwrapping multipliers: :file:`macc_xilinx_unwrap_map.v` .. literalinclude:: /code_examples/macc/macc_xilinx_unwrap_map.v :language: verilog :lines: 1-30 - :caption: ``$__mul_wrapper`` module in ``macc_xilinx_unwrap_map.v`` + :caption: ``$__mul_wrapper`` module in :file:`macc_xilinx_unwrap_map.v` -Unwrapping adders: ``macc_xilinx_unwrap_map.v`` +Unwrapping adders: :file:`macc_xilinx_unwrap_map.v` .. literalinclude:: /code_examples/macc/macc_xilinx_unwrap_map.v :language: verilog :lines: 32-61 - :caption: ``$__add_wrapper`` module in ``macc_xilinx_unwrap_map.v`` + :caption: ``$__add_wrapper`` module in :file:`macc_xilinx_unwrap_map.v` .. literalinclude:: /code_examples/macc/macc_xilinx_test.v :language: verilog :lines: 1-6 - :caption: ``test1`` of ``macc_xilinx_test.v`` + :caption: ``test1`` of :file:`macc_xilinx_test.v` .. figure:: /_images/code_examples/macc/macc_xilinx_test1a.* :class: width-helper @@ -154,7 +157,7 @@ Unwrapping adders: ``macc_xilinx_unwrap_map.v`` .. literalinclude:: /code_examples/macc/macc_xilinx_test.v :language: verilog :lines: 8-13 - :caption: ``test2`` of ``macc_xilinx_test.v`` + :caption: ``test2`` of :file:`macc_xilinx_test.v` .. figure:: /_images/code_examples/macc/macc_xilinx_test2a.* :class: width-helper diff --git a/docs/source/using_yosys/synthesis/memory.rst b/docs/source/using_yosys/synthesis/memory.rst index 2378af542..9301b8d54 100644 --- a/docs/source/using_yosys/synthesis/memory.rst +++ b/docs/source/using_yosys/synthesis/memory.rst @@ -33,27 +33,32 @@ Example .. todo:: describe ``memory`` images +|code_examples/synth_flow|_. + +.. |code_examples/synth_flow| replace:: :file:`docs/source/code_examples/synth_flow` +.. _code_examples/synth_flow: https://github.com/YosysHQ/yosys/tree/krys/docs/docs/source/code_examples/synth_flow + .. 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`` + :caption: :file:`memory_01.ys` .. literalinclude:: /code_examples/synth_flow/memory_01.v :language: verilog - :caption: ``docs/source/code_examples/synth_flow/memory_01.v`` + :caption: :file:`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`` + :caption: :file:`memory_02.v` .. literalinclude:: /code_examples/synth_flow/memory_02.ys :language: yoscrypt - :caption: ``docs/source/code_examples/synth_flow/memory_02.ys`` + :caption: :file:`memory_02.ys` .. _memory_map: @@ -71,7 +76,7 @@ For example: memory_map :cmd:ref:`memory_libmap` attempts to convert memory cells (``$mem_v2`` etc) into -hardware supported memory using a provided library (``my_memory_map.txt`` in the +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 diff --git a/docs/source/using_yosys/synthesis/proc.rst b/docs/source/using_yosys/synthesis/proc.rst index 265930c8c..8c047e6b8 100644 --- a/docs/source/using_yosys/synthesis/proc.rst +++ b/docs/source/using_yosys/synthesis/proc.rst @@ -28,13 +28,18 @@ Example .. todo:: describe ``proc`` images +|code_examples/synth_flow|_. + +.. |code_examples/synth_flow| replace:: :file:`docs/source/code_examples/synth_flow` +.. _code_examples/synth_flow: https://github.com/YosysHQ/yosys/tree/krys/docs/docs/source/code_examples/synth_flow + .. literalinclude:: /code_examples/synth_flow/proc_01.v :language: verilog - :caption: ``docs/source/code_examples/synth_flow/proc_01.v`` + :caption: :file:`proc_01.v` .. literalinclude:: /code_examples/synth_flow/proc_01.ys :language: yoscrypt - :caption: ``docs/source/code_examples/synth_flow/proc_01.ys`` + :caption: :file:`proc_01.ys` .. figure:: /_images/code_examples/synth_flow/proc_01.* :class: width-helper @@ -44,19 +49,19 @@ Example .. literalinclude:: /code_examples/synth_flow/proc_02.v :language: verilog - :caption: ``docs/source/code_examples/synth_flow/proc_02.v`` + :caption: :file:`proc_02.v` .. literalinclude:: /code_examples/synth_flow/proc_02.ys :language: yoscrypt - :caption: ``docs/source/code_examples/synth_flow/proc_02.ys`` + :caption: :file:`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`` + :caption: :file:`proc_03.ys` .. literalinclude:: /code_examples/synth_flow/proc_03.v :language: verilog - :caption: ``docs/source/code_examples/synth_flow/proc_03.v`` + :caption: :file:`proc_03.v` diff --git a/docs/source/yosys_internals/extending_yosys/abc_flow.rst b/docs/source/yosys_internals/extending_yosys/abc_flow.rst index e55c87870..86afd3336 100644 --- a/docs/source/yosys_internals/extending_yosys/abc_flow.rst +++ b/docs/source/yosys_internals/extending_yosys/abc_flow.rst @@ -22,7 +22,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 ``read_verilog`` so that they aren't skipped. +to :cmd:ref:`read_verilog` so that they aren't skipped. LUTs ^^^^ @@ -41,9 +41,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 ``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 :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). 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 @@ -59,7 +59,7 @@ mapped back to the original flop. This is used in :cmd:ref:`synth_intel_alm` and :cmd:ref:`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. +input signals, and an arrival time for the ``Q`` output. Boxes ^^^^^ diff --git a/docs/source/yosys_internals/extending_yosys/extensions.rst b/docs/source/yosys_internals/extending_yosys/extensions.rst index 2d6847f25..902c1c66c 100644 --- a/docs/source/yosys_internals/extending_yosys/extensions.rst +++ b/docs/source/yosys_internals/extending_yosys/extensions.rst @@ -6,7 +6,7 @@ Writing extensions .. todo:: check text is coherent -.. todo:: update to use ``/code_examples/extensions/test*.log`` +.. todo:: update to use :file:`/code_examples/extensions/test*.log` This chapter contains some bits and pieces of information about programming yosys extensions. Don't be afraid to ask questions on the YosysHQ Slack. @@ -21,7 +21,11 @@ Quick guide ----------- Code examples from this section are included in the -``docs/code_examples/extensions/`` directory of the Yosys source code. +|code_examples/extensions|_ directory of the Yosys source code. + +.. |code_examples/extensions| replace:: :file:`docs/source/code_examples/extensions` +.. _code_examples/extensions: https://github.com/YosysHQ/yosys/tree/krys/docs/docs/source/code_examples/extensions + Program components and data formats ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -31,7 +35,7 @@ about the internal data storage format used in Yosys and the classes that it provides. This document will focus on the much simpler version of RTLIL left after the -commands :cmd:ref:`proc` and :cmd:ref:`memory` (or ``memory -nomap``): +commands :cmd:ref:`proc` and :cmd:ref:`memory` (or :yoscrypt:`memory -nomap`): .. figure:: /_images/internals/simplified_rtlil.* :class: width-helper @@ -41,6 +45,8 @@ commands :cmd:ref:`proc` and :cmd:ref:`memory` (or ``memory -nomap``): It is possible to only work on this simpler version: +.. todo:: consider replacing inline code + .. code:: c++ for (RTLIL::Module *module : design->selected_modules() { @@ -66,10 +72,10 @@ with, and lists off the current design's modules. .. literalinclude:: /code_examples/extensions/my_cmd.cc :language: c++ :lines: 1, 4, 6, 7-20 - :caption: Example command :yoscrypt:`my_cmd` from ``my_cmd.cc`` + :caption: Example command :yoscrypt:`my_cmd` from :file:`my_cmd.cc` Note that we are making a global instance of a class derived from -``Yosys::Pass``, which we get by including ``kernel/yosys.h``. +``Yosys::Pass``, which we get by including :file:`kernel/yosys.h`. Compiling to a plugin ~~~~~~~~~~~~~~~~~~~~~ @@ -80,6 +86,8 @@ to create plugins. The following command compiles our example :yoscrypt:`my_cmd` to a Yosys plugin: +.. todo:: replace inline code + .. code:: shell yosys-config --exec --cxx --cxxflags --ldflags \ @@ -120,7 +128,7 @@ We'll do the same as before and format it as a a ``Yosys::Pass``. .. literalinclude:: /code_examples/extensions/my_cmd.cc :language: c++ :lines: 23-47 - :caption: :yoscrypt:`test1` - creating the absval module, from ``my_cmd.cc`` + :caption: :yoscrypt:`test1` - creating the absval module, from :file:`my_cmd.cc` .. code:: shell-session @@ -160,7 +168,7 @@ Consider the following module: .. literalinclude:: /code_examples/extensions/sigmap_test.v :language: Verilog - :caption: sigmap_test.v + :caption: :file:`sigmap_test.v` In this case ``a``, ``x``, and ``y`` are all different names for the same signal. However: @@ -204,7 +212,10 @@ Use ``log_id()`` to create a C-string for an ``RTLIL::IdString``: log("Name of this module: %s\n", log_id(module->name)); -Use ``log_header()`` and ``log_push()``/``log_pop()`` to structure log messages: +Use ``log_header()`` and ``log_push()``/\ ``log_pop()`` to structure log +messages: + +.. todo:: replace inline code .. code:: C++ @@ -219,6 +230,8 @@ Error handling Use ``log_error()`` to report a non-recoverable error: +.. todo:: replace inline code + .. code:: C++ if (design->modules.count(module->name) != 0) @@ -238,20 +251,22 @@ The "stubnets" example module ------------------------------ The following is the complete code of the "stubnets" example module. It is -included in the Yosys source distribution as -``docs/source/code_examples/stubnets/stubnets.cc``. +included in the Yosys source distribution under |code_examples/stubnets|_. + +.. |code_examples/stubnets| replace:: :file:`docs/source/code_examples/stubnets` +.. _code_examples/stubnets: https://github.com/YosysHQ/yosys/tree/krys/docs/docs/source/code_examples/stubnets .. literalinclude:: /code_examples/stubnets/stubnets.cc :language: c++ :linenos: - :caption: docs/source/code_examples/stubnets/stubnets.cc + :caption: :file:`stubnets.cc` .. literalinclude:: /code_examples/stubnets/Makefile :language: makefile :linenos: - :caption: docs/source/code_examples/stubnets/Makefile + :caption: :file:`Makefile` .. literalinclude:: /code_examples/stubnets/test.v :language: verilog :linenos: - :caption: docs/source/code_examples/stubnets/test.v + :caption: :file:`test.v` diff --git a/docs/source/yosys_internals/flow/index.rst b/docs/source/yosys_internals/flow/index.rst index 7733ec855..c7ab0ebcc 100644 --- a/docs/source/yosys_internals/flow/index.rst +++ b/docs/source/yosys_internals/flow/index.rst @@ -1,7 +1,6 @@ Internal flow ============= - A (usually short) synthesis script controls Yosys. These scripts contain three types of commands: diff --git a/docs/source/yosys_internals/flow/verilog_frontend.rst b/docs/source/yosys_internals/flow/verilog_frontend.rst index b36eb3bbf..127fa7be3 100644 --- a/docs/source/yosys_internals/flow/verilog_frontend.rst +++ b/docs/source/yosys_internals/flow/verilog_frontend.rst @@ -23,8 +23,8 @@ representation that closely resembles the structure of the original Verilog code. The Verilog frontend consists of three components, the Preprocessor, the Lexer and the Parser. -The source code to the Verilog frontend can be found in ``frontends/verilog/`` -in the Yosys source tree. +The source code to the Verilog frontend can be found in +:file:`frontends/verilog/` in the Yosys source tree. The Verilog preprocessor ~~~~~~~~~~~~~~~~~~~~~~~~ @@ -37,20 +37,19 @@ It is implemented as a C++ function that is passed a file descriptor as input and returns the pre-processed Verilog code as a ``std::string``. The source code to the Verilog Preprocessor can be found in -``frontends/verilog/preproc.cc`` in the Yosys source tree. +:file:`frontends/verilog/preproc.cc` in the Yosys source tree. The Verilog lexer ~~~~~~~~~~~~~~~~~ -The Verilog Lexer is written using the lexer generator flex. Its source code -can be found in ``frontends/verilog/verilog_lexer.l`` in the Yosys source tree. +The Verilog Lexer is written using the lexer generator flex. Its source code can +be found in :file:`frontends/verilog/verilog_lexer.l` in the Yosys source tree. The lexer does little more than identifying all keywords and literals recognised by the Yosys Verilog frontend. -The lexer keeps track of the current location in the Verilog source code -using some global variables. These variables are used by the constructor -of AST nodes to annotate each node with the source code location it -originated from. +The lexer keeps track of the current location in the Verilog source code using +some global variables. These variables are used by the constructor of AST nodes +to annotate each node with the source code location it originated from. Finally the lexer identifies and handles special comments such as "``// synopsys translate_off``" and "``// synopsys full_case``". (It is recommended to use @@ -62,10 +61,11 @@ The Verilog parser ~~~~~~~~~~~~~~~~~~ The Verilog Parser is written using the parser generator bison. Its source code -can be found in ``frontends/verilog/verilog_parser.y`` in the Yosys source tree. +can be found in :file:`frontends/verilog/verilog_parser.y` in the Yosys source +tree. It generates an AST using the ``AST::AstNode`` data structure defined in -``frontends/ast/ast.h``. An ``AST::AstNode`` object has the following +:file:`frontends/ast/ast.h`. An ``AST::AstNode`` object has the following properties: .. list-table:: AST node types with their corresponding Verilog constructs. @@ -77,7 +77,8 @@ properties: * - AST_NONE - This Node type should never be used. * - AST_DESIGN - - This node type is used for the top node of the AST tree. It has no corresponding Verilog construct. + - This node type is used for the top node of the AST tree. It has no + corresponding Verilog construct. * - AST_MODULE, AST_TASK, AST_FUNCTION - ``module``, ``task`` and ``function`` * - AST_WIRE @@ -99,9 +100,11 @@ properties: * - AST_CELLTYPE - The type of cell in cell instantiation * - AST_IDENTIFIER - - An Identifier (signal name in expression or cell/task/etc. name in other contexts) + - An Identifier (signal name in expression or cell/task/etc. name in other + contexts) * - AST_PREFIX - - Construct an identifier in the form []. (used only in advanced generate constructs) + - Construct an identifier in the form []. (used + only in advanced generate constructs) * - AST_FCALL, AST_TCALL - Call to function or task * - AST_TO_SIGNED, AST_TO_UNSIGNED @@ -113,7 +116,8 @@ properties: * - AST_REDUCE_AND, AST_REDUCE_OR, AST_REDUCE_XOR, AST_REDUCE_XNOR - The unary reduction operators ``~``, ``&``, ``|``, ``^`` and ``~^`` * - AST_REDUCE_BOOL - - Conversion from multi-bit value to boolean value (equivalent to AST_REDUCE_OR) + - Conversion from multi-bit value to boolean value (equivalent to + AST_REDUCE_OR) * - AST_SHIFT_LEFT, AST_SHIFT_RIGHT, AST_SHIFT_SLEFT, AST_SHIFT_SRIGHT - The shift operators ``<<``, ``>>``, ``<<<`` and ``>>>`` * - AST_LT, AST_LE, AST_EQ, AST_NE, AST_GE, AST_GT @@ -127,7 +131,8 @@ properties: * - AST_TERNARY - The ternary ``?:``-operator * - AST_MEMRD AST_MEMWR - - Read and write memories. These nodes are generated by the AST simplifier for writes/reads to/from Verilog arrays. + - Read and write memories. These nodes are generated by the AST simplifier + for writes/reads to/from Verilog arrays. * - AST_ASSIGN - An ``assign`` statement * - AST_CELL @@ -139,13 +144,16 @@ properties: * - AST_BLOCK - A ``begin``-``end``-block * - AST_ASSIGN_EQ. AST_ASSIGN_LE - - Blocking (``=``) and nonblocking (``<=``) assignments within an ``always``- or ``initial``-block + - Blocking (``=``) and nonblocking (``<=``) assignments within an + ``always``- or ``initial``-block * - AST_CASE. AST_COND, AST_DEFAULT - - The ``case`` (``if``) statements, conditions within a case and the default case respectively + - The ``case`` (``if``) statements, conditions within a case and the + default case respectively * - AST_FOR - A ``for``-loop with an ``always``- or ``initial``-block * - AST_GENVAR, AST_GENBLOCK, AST_GENFOR, AST_GENIF - - The ``genvar`` and ``generate`` keywords and ``for`` and ``if`` within a generate block. + - The ``genvar`` and ``generate`` keywords and ``for`` and ``if`` within a + generate block. * - AST_POSEDGE, AST_NEGEDGE, AST_EDGE - Event conditions for ``always`` blocks. @@ -295,7 +303,7 @@ correct intermediate values whenever one of the previously assigned signals is used in an expression. Unfortunately the generation of a correct -``RTLIL::CaseRule``/``RTLIL::SwitchRule`` tree for behavioural code is a +``RTLIL::CaseRule``/\ ``RTLIL::SwitchRule`` tree for behavioural code is a non-trivial task. The AST frontend solves the problem using the approach described on the following pages. The following example illustrates what the algorithm is supposed to do. Consider the following Verilog code: @@ -371,7 +379,7 @@ expressions after the initial assignment. The signal ``out2`` is assigned using nonblocking assignments and therefore is not substituted on the right-hand-side expressions. -The ``RTLIL::CaseRule``/``RTLIL::SwitchRule`` tree must be interpreted the +The ``RTLIL::CaseRule``/\ ``RTLIL::SwitchRule`` tree must be interpreted the following way: - On each case level (the body of the process is the root case), first the @@ -388,7 +396,7 @@ following way: objects within a ``RTLIL::CaseRule`` is preserved with respect to the original AST and Verilog code. -- The whole ``RTLIL::CaseRule``/``RTLIL::SwitchRule`` tree describes an +- The whole ``RTLIL::CaseRule``/\ ``RTLIL::SwitchRule`` tree describes an asynchronous circuit. I.e. the decision tree formed by the switches can be seen independently for each assigned signal. Whenever one assigned signal changes, all signals that depend on the changed signals are to be updated. @@ -403,11 +411,11 @@ the original Verilog code has been translated into the synchronization type (posedge) and signal (``\clock``) for the ``RTLIL::SyncRule`` object. In the case of this simple example the ``RTLIL::SyncRule`` object is later simply transformed into a set of d-type flip-flops and the -``RTLIL::CaseRule``/``RTLIL::SwitchRule`` tree to a decision tree using +``RTLIL::CaseRule``/\ ``RTLIL::SwitchRule`` tree to a decision tree using multiplexers. In more complex examples (e.g. asynchronous resets) the part of the -``RTLIL::CaseRule``/``RTLIL::SwitchRule`` tree that describes the asynchronous +``RTLIL::CaseRule``/\ ``RTLIL::SwitchRule`` tree that describes the asynchronous reset must first be transformed to the correct ``RTLIL::SyncRule`` objects. This is done by the ``proc_arst`` pass. @@ -583,7 +591,7 @@ Note how this step always overrides a previous assignment to the old temporary variable. Other than nonblocking assignments, the old assignment could still have an effect somewhere in the design, as there have been calls to ``AST::AstNode::genRTLIL()`` with a -``subst_rvalue_from``/ ``subst_rvalue_to``-tuple that contained the +``subst_rvalue_from``/\ ``subst_rvalue_to``-tuple that contained the right-hand-side of the old assignment. The proc pass @@ -609,17 +617,17 @@ from a behavioural model to an RTL representation is performed by the and the top-level ``RTLIL::SwitchRule`` has been removed. - | :cmd:ref:`proc_mux` - | This pass converts the ``RTLIL::CaseRule``/ ``RTLIL::SwitchRule``-tree to a + | 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` - | This pass replaces the ``RTLIL::SyncRule`` s to d-type flip-flops (with + | This pass replaces the ``RTLIL::SyncRule``\ s to d-type flip-flops (with asynchronous resets if necessary). - | :cmd:ref:`proc_dff` - | This pass replaces the ``RTLIL::MemWriteAction`` s with ``$memwr`` cells. + | 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 @@ -636,18 +644,13 @@ Second it improves flexibility. This scheme can easily be extended to support other types of storage-elements, such as sr-latches or d-latches, without having to extend the actual Verilog frontend. -Synthesizing Verilog arrays ---------------------------- - -.. todo:: +.. todo:: Synthesizing Verilog arrays Add some information on the generation of ``$memrd`` and ``$memwr`` cells and how they are processed in the memory pass. -Synthesizing parametric designs -------------------------------- -.. todo:: +.. todo:: Synthesizing parametric designs Add some information on the ``RTLIL::Module::derive()`` method and how it is used to synthesize parametric modules via the hierarchy pass. diff --git a/docs/source/yosys_internals/formats/cell_library.rst b/docs/source/yosys_internals/formats/cell_library.rst index bbbec836c..7d4670797 100644 --- a/docs/source/yosys_internals/formats/cell_library.rst +++ b/docs/source/yosys_internals/formats/cell_library.rst @@ -9,8 +9,11 @@ Internal cell library .. todo:: less academic, also check formatting consistency Most of the passes in Yosys operate on netlists, i.e. they only care about the -RTLIL::Wire and RTLIL::Cell objects in an RTLIL::Module. This chapter discusses -the cell types used by Yosys to represent a behavioural design internally. +``RTLIL::Wire`` and ``RTLIL::Cell`` objects in an ``RTLIL::Module``. This +chapter discusses the cell types used by Yosys to represent a behavioural design +internally. + +.. TODO:: is this chapter split preserved This chapter is split in two parts. In the first part the internal RTL cells are covered. These cells are used to represent the design on a coarse grain level. @@ -33,7 +36,7 @@ parameters in sync with the size of the signals connected to the inputs and outputs. Simulation models for the RTL cells can be found in the file -``techlibs/common/simlib.v`` in the Yosys source tree. +:file:`techlibs/common/simlib.v` in the Yosys source tree. Unary operators ~~~~~~~~~~~~~~~ @@ -42,8 +45,8 @@ All unary RTL cells have one input port ``\A`` and one output port ``\Y``. They also have the following parameters: ``\A_SIGNED`` - Set to a non-zero value if the input ``\A`` is signed and therefore - should be sign-extended when needed. + Set to a non-zero value if the input ``\A`` is signed and therefore should be + sign-extended when needed. ``\A_WIDTH`` The width of the input port ``\A``. @@ -110,7 +113,7 @@ All binary RTL cells have two input ports ``\A`` and ``\B`` and one output port :name: tab:CellLib_binary ======================= ============= ======================= ========= - Verilog Cell Type Verilog Cell Type + Verilog Cell Type Verilog Cell Type ======================= ============= ======================= ========= :verilog:`Y = A & B` $and :verilog:`Y = A < B` $lt :verilog:`Y = A | B` $or :verilog:`Y = A <= B` $le @@ -124,7 +127,7 @@ All binary RTL cells have two input ports ``\A`` and ``\B`` and one output port :verilog:`Y = A || B` $logic_or :verilog:`Y = A / B` $div :verilog:`Y = A === B` $eqx :verilog:`Y = A % B` $mod :verilog:`Y = A !== B` $nex ``N/A`` $divfloor - :verilog:`Y = A ** B` $pow ``N/A`` $modfoor + :verilog:`Y = A ** B` $pow ``N/A`` $modfloor ======================= ============= ======================= ========= The ``$shl`` and ``$shr`` cells implement logical shifts, whereas the ``$sshl`` @@ -141,7 +144,7 @@ positions are filled with undef (x) bits, and corresponds to the Verilog indexed part-select expression. For the binary cells that output a logical value (``$logic_and``, ``$logic_or``, -``$eqx``, ``$nex``, ``$lt``, ``$le``, ``$eq``, ``$ne``, ``$ge``, ``$gt)``, when +``$eqx``, ``$nex``, ``$lt``, ``$le``, ``$eq``, ``$ne``, ``$ge``, ``$gt``), when the ``\Y_WIDTH`` parameter is greater than 1, the output is zero-extended, and only the least significant bit varies. @@ -334,11 +337,11 @@ cells. Memories ~~~~~~~~ -Memories are either represented using RTLIL::Memory objects, ``$memrd_v2``, +Memories are either represented using ``RTLIL::Memory`` objects, ``$memrd_v2``, ``$memwr_v2``, and ``$meminit_v2`` cells, or by ``$mem_v2`` cells alone. -In the first alternative the RTLIL::Memory objects hold the general metadata for -the memory (bit width, size in number of words, etc.) and for each port a +In the first alternative the ``RTLIL::Memory`` objects hold the general metadata +for the memory (bit width, size in number of words, etc.) and for each port a ``$memrd_v2`` (read port) or ``$memwr_v2`` (write port) cell is created. Having individual cells for read and write ports has the advantage that they can be consolidated using resource sharing passes. In some cases this drastically @@ -353,7 +356,7 @@ address input ``\ADDR``, a data output ``\DATA``, an asynchronous reset input parameters: ``\MEMID`` - The name of the RTLIL::Memory object that is associated with this read + The name of the ``RTLIL::Memory`` object that is associated with this read port. ``\ABITS`` @@ -413,7 +416,7 @@ The ``$memwr_v2`` cells have a clock input ``\CLK``, an enable input ``\EN`` ``\DATA``. They also have the following parameters: ``\MEMID`` - The name of the RTLIL::Memory object that is associated with this write + The name of the ``RTLIL::Memory`` object that is associated with this write port. ``\ABITS`` @@ -452,7 +455,7 @@ to ``\WIDTH`` parameter. All three of the inputs must resolve to a constant for synthesis to succeed. ``\MEMID`` - The name of the RTLIL::Memory object that is associated with this + The name of the ``RTLIL::Memory`` object that is associated with this initialization cell. ``\ABITS`` @@ -468,9 +471,9 @@ synthesis to succeed. The cell with the higher integer value in this parameter wins an 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 (i.e.~its -various sub-passes) migrates ``$dff`` cells into the ``$memrd_v2`` and +The HDL frontend models a memory using ``RTLIL::Memory`` objects and +asynchronous ``$memrd_v2`` and ``$memwr_v2`` cells. The :cmd:ref:`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 individual words and multiplexer-based address decoders for the read and write @@ -480,7 +483,7 @@ is left in the design. The ``$mem_v2`` cell provides the following parameters: ``\MEMID`` - The name of the original RTLIL::Memory object that became this + The name of the original ``RTLIL::Memory`` object that became this ``$mem_v2`` cell. ``\SIZE`` @@ -1145,8 +1148,8 @@ mapped to physical flip-flop cells from a Liberty file using the dfflibmap pass. The combinatorial logic cells can be mapped to physical cells from a Liberty file via ABC using the abc pass. -Add information about ``$slice`` and ``$concat`` cells. +.. todo:: Add information about ``$slice`` and ``$concat`` cells. -Add information about ``$lut`` and ``$sop`` cells. +.. todo:: Add information about ``$lut`` and ``$sop`` cells. -Add information about ``$alu``, ``$macc``, ``$fa``, and ``$lcu`` cells. +.. todo:: Add information about ``$alu``, ``$macc``, ``$fa``, and ``$lcu`` cells. diff --git a/docs/source/yosys_internals/formats/index.rst b/docs/source/yosys_internals/formats/index.rst index aa77d1ea6..c187a8238 100644 --- a/docs/source/yosys_internals/formats/index.rst +++ b/docs/source/yosys_internals/formats/index.rst @@ -1,6 +1,8 @@ Internal formats ================ +.. todo:: brief overview for the internal formats index + .. toctree:: :maxdepth: 3 diff --git a/docs/source/yosys_internals/techmap.rst b/docs/source/yosys_internals/techmap.rst index ce40ea19c..8508e6280 100644 --- a/docs/source/yosys_internals/techmap.rst +++ b/docs/source/yosys_internals/techmap.rst @@ -12,6 +12,13 @@ Yosys' internal cell types (such as ``$or``) as well as user-defined cell types. file. - Generate blocks and recursion are powerful tools for writing map files. +Code examples used in this document are included in the Yosys code base under +|code_examples/techmap|_. + +.. |code_examples/techmap| replace:: :file:`docs/source/code_examples/techmap` +.. _code_examples/techmap: https://github.com/YosysHQ/yosys/tree/krys/docs/docs/source/code_examples/techmap + + Mapping OR3X1 ~~~~~~~~~~~~~ @@ -24,31 +31,32 @@ Mapping OR3X1 .. literalinclude:: /code_examples/techmap/red_or3x1_map.v :language: verilog - :caption: ``docs/source/code_examples/techmap/red_or3x1_map.v`` + :caption: :file:`red_or3x1_map.v` .. figure:: /_images/code_examples/techmap/red_or3x1.* :class: width-helper .. literalinclude:: /code_examples/techmap/red_or3x1_test.ys :language: yoscrypt - :caption: ``docs/source/code_examples/techmap/red_or3x1_test.ys`` + :caption: :file:`red_or3x1_test.ys` .. literalinclude:: /code_examples/techmap/red_or3x1_test.v :language: verilog - :caption: ``docs/source/code_examples/techmap/red_or3x1_test.v`` + :caption: :file:`red_or3x1_test.v` Conditional techmap ~~~~~~~~~~~~~~~~~~~ - In some cases only cells with certain properties should be substituted. -- The special wire ``_TECHMAP_FAIL_`` can be used to disable a module - in the map file for a certain set of parameters. -- The wire ``_TECHMAP_FAIL_`` must be set to a constant value. If it - is non-zero then the module is disabled for this set of parameters. +- The special wire ``_TECHMAP_FAIL_`` can be used to disable a module in the map + file for a certain set of parameters. +- The wire ``_TECHMAP_FAIL_`` must be set to a constant value. If it is non-zero + then the module is disabled for this set of parameters. - Example use-cases: - coarse-grain cell types that only operate on certain bit widths - - memory resources for different memory geometries (width, depth, ports, etc.) + - memory resources for different memory geometries (width, depth, ports, + etc.) Example: @@ -57,22 +65,22 @@ Example: .. literalinclude:: /code_examples/techmap/sym_mul_map.v :language: verilog - :caption: ``docs/source/code_examples/techmap/sym_mul_map.v`` + :caption: :file:`sym_mul_map.v` .. literalinclude:: /code_examples/techmap/sym_mul_test.v :language: verilog - :caption: ``docs/source/code_examples/techmap/sym_mul_test.v`` + :caption: :file:`sym_mul_test.v` .. literalinclude:: /code_examples/techmap/sym_mul_test.ys :language: yoscrypt - :caption: ``docs/source/code_examples/techmap/sym_mul_test.ys`` + :caption: :file:`sym_mul_test.ys` Scripting in map modules ~~~~~~~~~~~~~~~~~~~~~~~~ -- The special wires ``_TECHMAP_DO_*`` can be used to run Yosys scripts - in the context of the replacement module. +- The special wires ``_TECHMAP_DO_*`` can be used to run Yosys scripts in the + context of the replacement module. - The wire that comes first in alphabetical oder is interpreted as string (must be connected to constants) that is executed as script. Then the wire is removed. Repeat. @@ -96,15 +104,15 @@ Example: .. literalinclude:: /code_examples/techmap/mymul_map.v :language: verilog - :caption: ``docs/source/code_examples/techmap/mymul_map.v`` + :caption: :file:`mymul_map.v` .. literalinclude:: /code_examples/techmap/mymul_test.v :language: verilog - :caption: ``docs/source/code_examples/techmap/mymul_test.v`` + :caption: :file:`mymul_test.v` .. literalinclude:: /code_examples/techmap/mymul_test.ys :language: yoscrypt - :caption: ``docs/source/code_examples/techmap/mymul_test.ys`` + :caption: :file:`mymul_test.ys` Handling constant inputs ~~~~~~~~~~~~~~~~~~~~~~~~ @@ -126,15 +134,15 @@ Example: .. literalinclude:: /code_examples/techmap/mulshift_map.v :language: verilog - :caption: ``docs/source/code_examples/techmap/mulshift_map.v`` + :caption: :file:`mulshift_map.v` .. literalinclude:: /code_examples/techmap/mulshift_test.v :language: verilog - :caption: ``docs/source/code_examples/techmap/mulshift_test.v`` + :caption: :file:`mulshift_test.v` .. literalinclude:: /code_examples/techmap/mulshift_test.ys :language: yoscrypt - :caption: ``docs/source/code_examples/techmap/mulshift_test.ys`` + :caption: :file:`mulshift_test.ys` Handling shorted inputs ~~~~~~~~~~~~~~~~~~~~~~~ @@ -143,7 +151,8 @@ Handling shorted inputs ``_TECHMAP_CONNMAP__`` can be used to handle shorted inputs. - Each bit of the port correlates to an ``_TECHMAP_BITS_CONNMAP_`` bits wide number in ``_TECHMAP_CONNMAP__``. -- Each unique signal bit is assigned its own number. Identical fields in the ``_TECHMAP_CONNMAP__`` parameters mean shorted signal bits. +- Each unique signal bit is assigned its own number. Identical fields in the + ``_TECHMAP_CONNMAP__`` parameters mean shorted signal bits. - The numbers 0-3 are reserved for ``0``, ``1``, ``x``, and ``z`` respectively. - Example use-cases: @@ -157,15 +166,15 @@ Example: .. literalinclude:: /code_examples/techmap/addshift_map.v :language: verilog - :caption: ``docs/source/code_examples/techmap/addshift_map.v`` + :caption: :file:`addshift_map.v` .. literalinclude:: /code_examples/techmap/addshift_test.v :language: verilog - :caption: ``docs/source/code_examples/techmap/addshift_test.v`` + :caption: :file:`addshift_test.v` .. literalinclude:: /code_examples/techmap/addshift_test.ys :language: yoscrypt - :caption: ``docs/source/code_examples/techmap/addshift_test.ys`` + :caption: :file:`addshift_test.ys` Notes on using techmap ~~~~~~~~~~~~~~~~~~~~~~