mirrors/yosys
3
0
Fork 0
mirror of https://github.com/YosysHQ/yosys synced 2025-11-04 05:19:11 +00:00
Code Activity

Docs: tidying

Browse source 
- 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.
This commit is contained in:
Krystine Sherwin 2024-01-30 13:31:00 +13:00
parent a7e1c6e530
commit 9878e69d6c
No known key found for this signature in database
18 changed files with 348 additions and 255 deletions
Download patch file Download diff file Expand all files Collapse all files

10
docs/source/appendix/env_vars.rst
View file

@ -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``

22
docs/source/getting_started/example_synth.rst
View file

@ -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

38
docs/source/getting_started/installation.rst
View file

@ -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.

32
docs/source/getting_started/scripting_intro.rst
View file

@ -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 <fifo-ys>`. 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 <fifo-ys>`. 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/

109
docs/source/using_yosys/more_scripting/interactive_investigation.rst
View file

@ -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 <filename>``
option. Secondly it is possible to load cell libraries into the design with the
``read_verilog -lib <filename>`` 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 <filename>` 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

32
docs/source/using_yosys/more_scripting/model_checking.rst
View file

@ -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::

28
docs/source/using_yosys/more_scripting/selections.rst
View file

@ -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.*

28
docs/source/using_yosys/synthesis/cell_libs.rst
View file

@ -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

45
docs/source/using_yosys/synthesis/extract.rst
View file

@ -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

15
docs/source/using_yosys/synthesis/memory.rst
View file

@ -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

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

@ -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`

10
docs/source/yosys_internals/extending_yosys/abc_flow.rst
View file

@ -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
^^^^^

41
docs/source/yosys_internals/extending_yosys/extensions.rst
View file

@ -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`

1
docs/source/yosys_internals/flow/index.rst
View file

@ -1,7 +1,6 @@
Internal flow
=============
A (usually short) synthesis script controls Yosys.
These scripts contain three types of commands:

73
docs/source/yosys_internals/flow/verilog_frontend.rst
View file

@ -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 <prefix>[<index>].<suffix> (used only in advanced generate constructs)
- Construct an identifier in the form <prefix>[<index>].<suffix> (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.

45
docs/source/yosys_internals/formats/cell_library.rst
View file

@ -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.

2
docs/source/yosys_internals/formats/index.rst
View file

@ -1,6 +1,8 @@
Internal formats
================
.. todo:: brief overview for the internal formats index
.. toctree::
:maxdepth: 3

55
docs/source/yosys_internals/techmap.rst
View file

@ -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_<port-name>_`` can be used to handle shorted inputs.
- Each bit of the port correlates to an ``_TECHMAP_BITS_CONNMAP_`` bits wide
number in ``_TECHMAP_CONNMAP_<port-name>_``.
- Each unique signal bit is assigned its own number. Identical fields in the ``_TECHMAP_CONNMAP_<port-name>_`` parameters mean shorted signal bits.
- Each unique signal bit is assigned its own number. Identical fields in the
``_TECHMAP_CONNMAP_<port-name>_`` 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
~~~~~~~~~~~~~~~~~~~~~~