mirrors/yosys
3
0
Fork 0
mirror of https://github.com/YosysHQ/yosys synced 2026-06-06 00:50:57 +00:00
Code Activity

WIP docs

Browse source
This commit is contained in:
Krystine Sherwin 2026-06-02 15:45:00 +12:00
parent 693d5a7eb0
commit 776995c74d
No known key found for this signature in database
8 changed files with 227 additions and 182 deletions
Download patch file Download diff file Expand all files Collapse all files

1
.gitignore vendored
View file

@ -1,5 +1,6 @@
## user config ## user config
/Makefile.conf /Makefile.conf
/Configuration.cmake
## homebrew ## homebrew
/Brewfile.lock.json /Brewfile.lock.json

96
README.md
View file

@ -75,10 +75,11 @@ or
$ cd yosys $ cd yosys
$ git submodule update --init --recursive $ git submodule update --init --recursive
You need a C++ compiler with C++17 support (up-to-date CLANG or GCC is A C++ compiler with C++20 support is required as well as some standard tools
recommended) and some standard tools such as GNU Flex, GNU Bison, and GNU Make. such as GNU Flex, GNU Bison (>=3.8), CMake (>=3.27), Make, and Python (>=3.11).
TCL, readline and libffi are optional (see ``ENABLE_*`` settings in Makefile). Some additional tools: readline, libffi, Tcl and zlib; will be used if available
Xdot (graphviz) is used by the ``show`` command in yosys to display schematics. but are optional. Graphviz and Xdot are used by the `show` command to display
schematics.
For example on Ubuntu Linux 22.04 LTS the following commands will install all For example on Ubuntu Linux 22.04 LTS the following commands will install all
prerequisites for building yosys: prerequisites for building yosys:
@ -86,45 +87,50 @@ prerequisites for building yosys:
$ sudo apt-get install gawk git make python3 lld bison clang flex \ $ sudo apt-get install gawk git make python3 lld bison clang flex \
libffi-dev libfl-dev libreadline-dev pkg-config tcl-dev zlib1g-dev \ libffi-dev libfl-dev libreadline-dev pkg-config tcl-dev zlib1g-dev \
graphviz xdot graphviz xdot
$ curl -LsSf https://astral.sh/uv/install.sh | sh
The environment variable `CXX` can be used to control the C++ compiler used, or **NOTE**: By default, Ubuntu 22.04 LTS is limited to CMake 3.22 via `apt`. To
run one of the following to override it: install a newer version and meet the minimum required for building Yosys, use
`sudo snap install cmake --classic`.
$ make config-clang CMake is used for build configuration, and requires a separate build directory:
$ make config-gcc
The Makefile has many variables influencing the build process. These can be $ cmake -B build .
adjusted by modifying the Makefile.conf file which is created at the `make
config-...` step (see above), or they can be set by passing an option to the
make command directly:
$ make CXX=$CXX Once generated, build variables can be inspected and modified with:
For other compilers and build configurations it might be necessary to make some $ ccmake build #..or..
changes to the config section of the Makefile. It's also an alternative way to $ vi build/CMakeCache.txt
set the make variables mentioned above.
$ vi Makefile # ..or.. one-off options with
$ vi Makefile.conf
To build Yosys simply type 'make' in this directory. $ cmake -B build . --fresh \
-DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++
$ make set persistent options with
$ sudo make install
Tests are located in the tests subdirectory and can be executed using the test $ vi Configuration.cmake # ..then..
$ cmake -C Configuration.cmake -B build . --fresh
e.g.
set(CMAKE_C_COMPILER clang CACHE STRING "")
set(CMAKE_CXX_COMPILER clang++ CACHE STRING "")
ALSO
$ cmake -G Ninja -B build .
INSTALL
$ cmake -B build . -DCMAKE_BUILD_TYPE=Release
$ cmake --build build --config Release --parallel $(nproc)
$ sudo cmake --install build --strip
Tests are located in the tests subdirectory and can be executed using the `test`
target. Note that you need gawk, a recent version of iverilog, and gtest. target. Note that you need gawk, a recent version of iverilog, and gtest.
Execute tests via: Execute tests via:
$ make test $ cmake --build build --target test --parallel $(nproc)
To use a separate (out-of-tree) build directory, provide a path to the Makefile.
$ mkdir build; cd build
$ make -f ../Makefile
Out-of-tree builds require a clean source tree.
Getting Started Getting Started
@ -134,7 +140,7 @@ Yosys can be used with the interactive command shell, with
synthesis scripts or with command line arguments. Let's perform synthesis scripts or with command line arguments. Let's perform
a simple synthesis job using the interactive command shell: a simple synthesis job using the interactive command shell:
$ ./yosys $ ./build/yosys
yosys> yosys>
the command ``help`` can be used to print a list of all available the command ``help`` can be used to print a list of all available
@ -256,7 +262,7 @@ following are used for building the website:
Or for MacOS, using homebrew: Or for MacOS, using homebrew:
$ brew install pdf2svg libfaketime $ brew install pdf2svg libfaketime
PDFLaTeX, included with most LaTeX distributions, is also needed during the PDFLaTeX, included with most LaTeX distributions, is also needed during the
build process for the website. Or, run the following: build process for the website. Or, run the following:
@ -265,24 +271,20 @@ build process for the website. Or, run the following:
Or for MacOS, using homebrew: Or for MacOS, using homebrew:
$ brew install basictex $ brew install basictex
$ sudo tlmgr update --self $ sudo tlmgr update --self
$ sudo tlmgr install collection-latexextra latexmk tex-gyre $ sudo tlmgr install collection-latexextra latexmk tex-gyre
The Python package, Sphinx, is needed along with those listed in The Python package, Sphinx, is needed along with those listed in
`docs/source/requirements.txt`: `docs/source/requirements.txt`:
$ pip install -U sphinx -r docs/source/requirements.txt $ pip install -U sphinx -r docs/source/requirements.txt
From the root of the repository, run `make docs`. This will build/rebuild yosys DOCS (e.g.)
as necessary before generating the website documentation from the yosys help
commands. To build for pdf instead of html, call $ cmake --build build --target docs-html --parallel
`make docs DOC_TARGET=latexpdf`.
This will build/rebuild yosys as necessary before generating the website
documentation from the yosys help commands. To build for pdf instead of html,
use the `docs-latexpdf` target.
It is recommended to use the `ENABLE_HELP_SOURCE` make option for Yosys builds
that will be used to build the documentation. This option enables source
location tracking for passes and improves the command reference through grouping
related commands and allowing for the documentation to link to the corresponding
source files. Without this, a warning will be raised during the Sphinx build
about `Found commands assigned to group unknown` and `make docs` is configured
to fail on warnings by default.

2
cmake/YosysAbcSubmodule.cmake
View file

@ -56,7 +56,7 @@ function(yosys_check_abc_submodule)
else() # else() #
message(FATAL_ERROR message(FATAL_ERROR
"${CMAKE_SOURCE_DIR} is not configured as a git repository, and 'abc' folder is missing.\n" "${CMAKE_SOURCE_DIR} is not configured as a git repository, and 'abc' folder is missing.\n"
"If you already have ABC, set 'ABCEXTERNAL' make variable to point to ABC executable.\n" "If you already have ABC, set 'YOSYS_ABC_EXECUTABLE' make variable to point to ABC executable.\n"
"Otherwise, download release archive 'yosys.tar.gz' from https://github.com/YosysHQ/yosys/releases.\n" "Otherwise, download release archive 'yosys.tar.gz' from https://github.com/YosysHQ/yosys/releases.\n"
" ('Source code' archive does not contain submodules.)\n" " ('Source code' archive does not contain submodules.)\n"
) )

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

@ -14,8 +14,9 @@ Yosys environment variables
Used for storing temporary files. Used for storing temporary files.
``ABC`` ``ABC``
When compiling Yosys with out-of-tree ABC using :makevar:`ABCEXTERNAL`, this When compiling Yosys with out-of-tree ABC using
variable can be used to override the external ABC executable. :makevar:`YOSYS_ABC_EXECUTABLE`, this variable can be used to override the
external ABC executable.
``YOSYS_NOVERIFIC`` ``YOSYS_NOVERIFIC``
If Yosys was built with Verific, this environment variable can be used to If Yosys was built with Verific, this environment variable can be used to

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

@ -88,10 +88,10 @@ Build prerequisites
^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^
A C++ compiler with C++20 support is required as well as some standard tools A C++ compiler with C++20 support is required as well as some standard tools
such as GNU Flex, GNU Bison (>=3.8), Make, and Python (>=3.11). Some additional such as GNU Flex, GNU Bison (>=3.8), CMake (>=3.27), Make (or other CMake
tools: readline, libffi, Tcl and zlib; are optional but enabled by default (see generator such as Ninja), and Python (>=3.11). Some additional tools: readline,
:makevar:`ENABLE_*` settings in Makefile). Graphviz and Xdot are used by the libffi, Tcl and zlib; will be used if available but are optional. Graphviz and
`show` command to display schematics. Xdot are used by the `show` command to display schematics.
Installing all prerequisites: Installing all prerequisites:
@ -102,7 +102,15 @@ Installing all prerequisites:
sudo apt-get install gawk git make python3 lld bison clang flex \ sudo apt-get install gawk git make python3 lld bison clang flex \
libffi-dev libfl-dev libreadline-dev pkg-config tcl-dev zlib1g-dev \ libffi-dev libfl-dev libreadline-dev pkg-config tcl-dev zlib1g-dev \
graphviz xdot graphviz xdot
curl -LsSf https://astral.sh/uv/install.sh | sh sudo snap install cmake --classic
.. tab:: Ubuntu 24.04
.. code:: console
sudo apt-get install gawk git cmake make python3 lld bison clang flex \
libffi-dev libfl-dev libreadline-dev pkg-config tcl-dev zlib1g-dev \
graphviz xdot
.. tab:: macOS 13 (with Homebrew) .. tab:: macOS 13 (with Homebrew)
@ -127,6 +135,10 @@ Installing all prerequisites:
.. note:: On FreeBSD system use gmake instead of make. To run tests use: .. note:: On FreeBSD system use gmake instead of make. To run tests use:
``MAKE=gmake CXX=cxx CC=cc gmake test`` ``MAKE=gmake CXX=cxx CC=cc gmake test``
.. TODO:: CMAKE_TODO
Is this still required, and (how) does it work with CMake
.. tab:: Cygwin .. tab:: Cygwin
Use the following command to install all prerequisites, or select these Use the following command to install all prerequisites, or select these
@ -134,7 +146,7 @@ Installing all prerequisites:
.. code:: console .. code:: console
setup-x86_64.exe -q --packages=bison,flex,gcc-core,gcc-g++,git,libffi-devel,libreadline-devel,make,pkg-config,python3,tcl-devel,zlib-devel setup-x86_64.exe -q --packages=bison,flex,gcc-core,gcc-g++,git,libffi-devel,libreadline-devel,cmake,make,pkg-config,python3,tcl-devel,zlib-devel
.. warning:: .. warning::
@ -142,7 +154,7 @@ Installing all prerequisites:
minimum required version of Python is 3.11. This means that Cygwin is not minimum required version of Python is 3.11. This means that Cygwin is not
compatible with many of the Python-based frontends. While this does not compatible with many of the Python-based frontends. While this does not
currently prevent Yosys itself from working, no guarantees are made for currently prevent Yosys itself from working, no guarantees are made for
continued support. You may also need to specify ``CXXSTD=gnu++17`` to continued support. You may also need to specify ``CXXSTD=gnu++20`` to
resolve missing ``strdup`` function when using gcc. It is instead resolve missing ``strdup`` function when using gcc. It is instead
recommended to use Windows Subsystem for Linux (WSL) and follow the recommended to use Windows Subsystem for Linux (WSL) and follow the
instructions for Ubuntu. instructions for Ubuntu.
@ -168,52 +180,53 @@ Installing all prerequisites:
Build configuration Build configuration
^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^
The Yosys build is based solely on Makefiles, and uses a number of variables The Yosys build is configured via CMake, and uses a number of variables
which influence the build process. The recommended method for configuring which influence the build process.
builds is with a ``Makefile.conf`` file in the root ``yosys`` directory. The
following commands will clean the directory and provide an initial configuration set one-off options with
file:
.. code:: console .. code:: console
make config-clang # ..or.. cmake -B build . --fresh \
make config-gcc -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++
Check the root Makefile to see what other configuration targets are available. set persistent options with
Other variables can then be added to the ``Makefile.conf`` as needed, for
example:
.. code:: console .. code:: console
echo "ENABLE_ZLIB := 0" >> Makefile.conf vi Configuration.cmake # ..then..
cmake -C Configuration.cmake -B build . --fresh
Using one of these targets will set the ``CONFIG`` variable to something other e.g.
than ``none``, and will override the environment variable for ``CXX``. To use a
different compiler than the default when building, use: .. code:: cmake
set(CMAKE_C_COMPILER clang CACHE STRING "")
set(CMAKE_CXX_COMPILER clang++ CACHE STRING "")
set(YOSYS_WITHOUT_ZLIB ON CACHE STRING "")
Once generated, build variables can be inspected and modified with:
.. code:: console .. code:: console
make CXX=$CXX # ..or.. ccmake build #..or..
make CXX="g++-11" vi build/CMakeCache.txt
.. note::
Setting the compiler in this way will prevent some other options such as
``ENABLE_CCACHE`` from working as expected.
If you have clang, and (a compatible version of) ``ld.lld`` available in PATH, If you have clang, and (a compatible version of) ``ld.lld`` available in PATH,
it's recommended to speed up incremental builds with lld by enabling LTO with it's recommended to speed up incremental builds with lld by enabling LTO with
``ENABLE_LTO=1``. On macOS, LTO requires using clang from homebrew rather than ``CMAKE_INTERPROCEDURAL_OPTIMIZATION=ON``. On macOS, LTO requires using clang
clang from xcode. For example: from homebrew rather than clang from xcode. For example:
.. code:: console .. code:: console
make ENABLE_LTO=1 CXX=$(brew --prefix)/opt/llvm/bin/clang++ cmake -B build . -DCMAKE_INTERPROCEDURAL_OPTIMIZATION=ON \
-DCMAKE_C_COMPILER=$(brew --prefix)/opt/llvm/bin/clang \
-DCMAKE_CXX_COMPILER=$(brew --prefix)/opt/llvm/bin/clang++
By default, building (and installing) yosys will build (and install) `ABC`_, By default, building (and installing) yosys will build (and install) `ABC`_,
using :program:`yosys-abc` as the executable name. To use an existing ABC using :program:`yosys-abc` as the executable name. To use an existing ABC
executable instead, set the ``ABCEXTERNAL`` make variable to point to the executable instead, set the :makevar:`YOSYS_ABC_EXECUTABLE` make variable to point to
desired executable. the desired executable.
Running the build system Running the build system
^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^
@ -222,17 +235,12 @@ From the root ``yosys`` directory, call the following commands:
.. code:: console .. code:: console
make cmake -B build . -DCMAKE_BUILD_TYPE=Release
sudo make install cmake --build build --config Release --parallel $(nproc)
sudo cmake --install build --strip
To use a separate (out-of-tree) build directory, provide a path to the Makefile. Note that Yosys does not support in-tree builds, and if calling ``cmake`` from
the root ``yosys`` directory the ``-B`` option must be provided.
.. code:: console
mkdir build; cd build
make -f ../Makefile
Out-of-tree builds require a clean source tree.
.. seealso:: .. seealso::
@ -248,6 +256,9 @@ directories:
``backends/`` ``backends/``
This directory contains a subdirectory for each of the backend modules. This directory contains a subdirectory for each of the backend modules.
``cmake/``
Additional ``.cmake`` files used by CMake during build generation.
``docs/`` ``docs/``
Contains the source for this documentation, including images and sample code. Contains the source for this documentation, including images and sample code.
@ -281,6 +292,10 @@ directories:
example as of this writing the directory :file:`passes/hierarchy/` contains example as of this writing the directory :file:`passes/hierarchy/` contains
the code for three passes: `hierarchy`, `submod`, and `uniquify`. the code for three passes: `hierarchy`, `submod`, and `uniquify`.
``pyosys/``
Contains the scripts and wrappers necessary for building :doc:`Pyosys
</using_yosys/pyosys>`.
``techlibs/`` ``techlibs/``
This directory contains simulation models and standard implementations for This directory contains simulation models and standard implementations for
the cells from the internal cell library. the cells from the internal cell library.
@ -289,19 +304,28 @@ directories:
This directory contains the suite of unit tests and regression tests used by This directory contains the suite of unit tests and regression tests used by
Yosys. See :doc:`/yosys_internals/extending_yosys/test_suites`. Yosys. See :doc:`/yosys_internals/extending_yosys/test_suites`.
The top-level Makefile includes :file:`frontends/{*}/Makefile.inc`, .. TODO:: CMAKE_TODO
: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 - ``yosys_<pass|test_pass|frontend|backend>(<name>)`` for each pass
passes are :file:`passes/opt/opt_dff.cc` and :file:`passes/opt/opt_merge.cc`.
Users of the Qt Creator IDE can generate a QT Creator project file using make - see :file:`cmake/YosysComponent.cmake`
qtcreator. Users of the Eclipse IDE can use the "Makefile Project with Existing
Code" project type in the Eclipse "New Project" dialog (only available after the - if using a sub folder, add it to the parent's ``CMakeLists.txt`` with
CDT plugin has been installed) to create an Eclipse project in order to ``add_subdirectory(<name>)``
programming extensions to Yosys or just browse the Yosys code base.
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 :file:`passes/opt/opt_dff.cc` and :file:`passes/opt/opt_merge.cc`.
Users of the Qt Creator IDE can generate a QT Creator project file using make
qtcreator. Users of the Eclipse IDE can use the "Makefile Project with Existing
Code" project type in the Eclipse "New Project" dialog (only available after the
CDT plugin has been installed) to create an Eclipse project in order to
programming extensions to Yosys or just browse the Yosys code base.

24
docs/source/using_yosys/pyosys.rst
View file

@ -1,6 +1,8 @@
Scripting with Pyosys Scripting with Pyosys
===================== =====================
.. TODO:: document libyosys sans python
Pyosys is a limited subset of the Yosys C++ API (aka "libyosys") made available Pyosys is a limited subset of the Yosys C++ API (aka "libyosys") made available
using the Python programming language. using the Python programming language.
@ -14,6 +16,13 @@ Though unlike these two, Pyosys goes a bit further, allowing you to use the
Yosys API to implement advanced functionality that would otherwise require Yosys API to implement advanced functionality that would otherwise require
custom passes written in C++. custom passes written in C++.
.. note::
It is recommended to install ``uv`` for managing python environments:
.. code:: console
curl -LsSf https://astral.sh/uv/install.sh | sh
Getting Pyosys Getting Pyosys
-------------- --------------
@ -21,7 +30,11 @@ Getting Pyosys
Pyosys supports CPython 3.8 or higher. You can access Pyosys using one of two Pyosys supports CPython 3.8 or higher. You can access Pyosys using one of two
methods: methods:
1. Compiling Yosys with the Makefile flag ``ENABLE_PYOSYS=1`` .. TODO:: CMAKE_TODO
may still be pending further changes
1. Compiling Yosys with the CMake flag ``-DYOSYS_WITH_PYTHON=ON``
This adds the flag ``-y`` to the Yosys binary, which allows you to execute This adds the flag ``-y`` to the Yosys binary, which allows you to execute
Python scripts using an interpreter embedded in Yosys itself: Python scripts using an interpreter embedded in Yosys itself:
@ -29,12 +42,9 @@ methods:
``yosys -y ./my_pyosys_script.py`` ``yosys -y ./my_pyosys_script.py``
Do note this requires some build-time dependencies to be available to Python, Do note this requires some build-time dependencies to be available to Python,
namely, ``pybind11`` and ``cxxheaderparser``. By default, the required namely, ``pybind11`` and ``cxxheaderparser``. If available, ``uv`` will be
``uv`` package will be used to create an ephemeral environment with the used to create an ephemeral environment with the correct versions of the
correct versions of the tools installed. tools installed.
You can force use of your current Python environment by passing the Makefile
flag ``PYOSYS_USE_UV=0``.
2. Installing the Pyosys wheels 2. Installing the Pyosys wheels

102
docs/source/yosys_internals/extending_yosys/build_verific.rst
View file

@ -39,36 +39,36 @@ incorrect results.
Compile options Compile options
--------------- ---------------
To enable Verific support ``ENABLE_VERIFIC`` has to be set to ``1`` and To enable Verific support, set the :makevar:`YOSYS_VERIFIC_DIR` CMake variable
``VERIFIC_DIR`` needs to point to the location where the library is located. to point to the location where the library is located, e.g.
============== ========================== =============================== .. code-block:: console
Parameter Default Description
============== ========================== ===============================
ENABLE_VERIFIC 0 Enable compilation with Verific
VERIFIC_DIR /usr/local/src/verific_lib Library and headers location
============== ========================== ===============================
Since there are multiple Verific library builds and they can have different cmake -B build . -DYOSYS_VERIFIC_DIR="/usr/local/src/verific_lib"
features, there are compile options to select them.
================================= ======= =================================== During building, CMake will attempt to automatically detect available Verific
Parameter Default Description library components to enable the corresponding compile-time option in Yosys.
================================= ======= =================================== This can be overridden by manually setting the :makevar:`YOSYS_VERIFIC_FEATURES`
ENABLE_VERIFIC_SYSTEMVERILOG 1 SystemVerilog support CMake variable. This variable should contain a semi-colon separated list, e.g.
ENABLE_VERIFIC_VHDL 1 VHDL support ``-DYOSYS_VERIFIC_FEATURES="systemverilog;hier_tree"``. The table below lists
ENABLE_VERIFIC_HIER_TREE 1 Hierarchy tree support the features available to Yosys.
ENABLE_VERIFIC_YOSYSHQ_EXTENSIONS 0 YosysHQ specific extensions support
ENABLE_VERIFIC_EDIF 0 EDIF support
ENABLE_VERIFIC_LIBERTY 0 Liberty file support
================================= ======= ===================================
To find the compile options used for a given Yosys build, call ``yosys-config ============== =========== ===================================
--cxxflags``. This documentation was built with the following compile options: Feature Directory Description
============== =========== ===================================
systemverilog verilog SystemVerilog support
vhdl vhdl VHDL support
hier_tree hier_tree Hierarchy tree support
extensions extensions YosysHQ specific extensions support
edif edif EDIF support
liberty synlib Liberty file support
============== =========== ===================================
.. literalinclude:: /generated/yosys-config .. TODO:: CMAKE_TODO
:start-at: --cxxflags
:end-before: --linkflags ``yosys-config --cxxflags`` no longer includes the verific features, and the
CMakeCache.txt doesn't report auto detected :makevar:`YOSYS_VERIFIC_FEATURES`
- can we export these somehow?
.. note:: .. note::
@ -82,11 +82,10 @@ are required for the Yosys-Verific patch:
* RTL elaboration with * RTL elaboration with
* SystemVerilog with ``ENABLE_VERIFIC_SYSTEMVERILOG``, and/or * SystemVerilog with ``systemverilog``, and/or
* VHDL support with ``ENABLE_VERIFIC_VHDL``. * VHDL support with ``vhdl``.
* Hierarchy tree support and static elaboration with * Hierarchy tree support and static elaboration with ``hier_tree``.
``ENABLE_VERIFIC_HIER_TREE``.
Please be aware that the following Verific configuration build parameter needs Please be aware that the following Verific configuration build parameter needs
to be enabled in order to create the fully supported build: to be enabled in order to create the fully supported build:
@ -105,11 +104,12 @@ to be enabled in order to create the fully supported build:
Optional Verific features Optional Verific features
~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~
The following Verific features are available with TabbyCAD and can be enabled in The following Verific features are available with TabbyCAD and will be
Yosys builds: automatically enabled in Yosys builds if the listed directory is included in the
:makevar:`YOSYS_VERIFIC_DIR`:
* EDIF support with ``ENABLE_VERIFIC_EDIF``, and * EDIF support with ``edif`` directory, and
* Liberty file support with ``ENABLE_VERIFIC_LIBERTY``. * Liberty file support with ``synlib`` directory.
Partially supported builds Partially supported builds
~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~
@ -124,32 +124,18 @@ lists a series of build configurations which are possible, but only provide a
limited subset of features. Please note that support is limited without YosysHQ limited subset of features. Please note that support is limited without YosysHQ
specific extensions of Verific library. specific extensions of Verific library.
Configuration values: ======================================================================= =================================
a. ``ENABLE_VERIFIC_SYSTEMVERILOG`` Features :makevar:`YOSYS_VERIFIC_FEATURES`
b. ``ENABLE_VERIFIC_VHDL`` ======================================================================= =================================
c. ``ENABLE_VERIFIC_HIER_TREE`` SystemVerilog + RTL elaboration systemverilog
d. ``ENABLE_VERIFIC_YOSYSHQ_EXTENSIONS`` VHDL + RTL elaboration vhdl
SystemVerilog + VHDL + RTL elaboration systemverilog;vhdl
+--------------------------------------------------------------------------+-----+-----+-----+-----+ SystemVerilog + RTL elaboration + Static elaboration + Hier tree systemverilog;vhdl;hier_tree
| | Configuration values | VHDL + RTL elaboration + Static elaboration + Hier tree vhdl;hier_tree
+--------------------------------------------------------------------------+-----+-----+-----+-----+ SystemVerilog + VHDL + RTL elaboration + Static elaboration + Hier tree systemverilog;vhdl;hier_tree
| Features | a | b | c | d | ======================================================================= =================================
+==========================================================================+=====+=====+=====+=====+
| SystemVerilog + RTL elaboration | 1 | 0 | 0 | 0 |
+--------------------------------------------------------------------------+-----+-----+-----+-----+
| VHDL + RTL elaboration | 0 | 1 | 0 | 0 |
+--------------------------------------------------------------------------+-----+-----+-----+-----+
| SystemVerilog + VHDL + RTL elaboration | 1 | 1 | 0 | 0 |
+--------------------------------------------------------------------------+-----+-----+-----+-----+
| SystemVerilog + RTL elaboration + Static elaboration + Hier tree | 1 | 0 | 1 | 0 |
+--------------------------------------------------------------------------+-----+-----+-----+-----+
| VHDL + RTL elaboration + Static elaboration + Hier tree | 0 | 1 | 1 | 0 |
+--------------------------------------------------------------------------+-----+-----+-----+-----+
| SystemVerilog + VHDL + RTL elaboration + Static elaboration + Hier tree | 1 | 1 | 1 | 0 |
+--------------------------------------------------------------------------+-----+-----+-----+-----+
.. note:: .. note::
In case your Verific build has EDIF and/or Liberty support, you can enable In case your Verific build has EDIF and/or Liberty support, you can enable
those options. These are not mentioned above for simplification and since those options. These are not mentioned above for simplification.
they are disabled by default.

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

@ -7,19 +7,32 @@ Running the included test suite
------------------------------- -------------------------------
The Yosys source comes with a test suite to avoid regressions and keep The Yosys source comes with a test suite to avoid regressions and keep
everything working as expected. Tests can be run by calling ``make test`` from everything working as expected. Tests can be run by building the ``test``
the root Yosys directory. By default, this runs vanilla and unit tests. target from the root Yosys directory. By default, this runs vanilla and unit
tests.
.. code:: console
cmake -B build .
cmake --build build --target test --parallel $(nproc)
.. TODO:: CMAKE_TODO
Using ``make -C <docs|tests>`` does work, but only if using default
:makevar:`BUILD_DIR` (``build``) and :makevar:`PROGRAM_PREFIX` (none).
Vanilla tests Vanilla tests
~~~~~~~~~~~~~ ~~~~~~~~~~~~~
These make up the majority of our testing coverage. .. TODO:: update for test infra changes
They can be run with ``make vanilla-test`` and are based on calls to
make subcommands (``make makefile-tests``) and shell scripts These make up the majority of our testing coverage. They can be run with the
(``make seed-tests`` and ``make abcopt-tests``). Both use ``run-test.sh`` ``test-vanilla`` CMake target, or by calling ``make vanilla-test`` from the
files, but make-based tests only call ``tests/gen-tests-makefile.sh`` ``tests`` directory, and are based on calls to make subcommands (``make
to generate a makefile appropriate for the given directory, so only makefile-tests``) and shell scripts (``make seed-tests`` and ``make
afterwards when make is invoked do the tests actually run. abcopt-tests``). Both use ``run-test.sh`` files, but make-based tests only call
``tests/gen-tests-makefile.sh`` to generate a makefile appropriate for the given
directory, so only afterwards when make is invoked do the tests actually run.
Usually their structure looks something like this: Usually their structure looks something like this:
you write a .ys file that gets automatically run, you write a .ys file that gets automatically run,
@ -45,7 +58,7 @@ Running the unit tests requires the following additional packages:
No additional requirements. No additional requirements.
Unit tests can be run with ``make unit-test``. Unit tests can be run with the ``test-unit`` CMake target.
Functional tests Functional tests
~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~
@ -75,12 +88,20 @@ If you don't have one of the :ref:`getting_started/installation:CAD suite(s)`
installed, you should also install Z3 `following their installed, you should also install Z3 `following their
instructions <https://github.com/Z3Prover/z3>`_. instructions <https://github.com/Z3Prover/z3>`_.
.. TODO:: CMAKE_TODO
How does this work under CMake? Is it only via ``make -C tests ENABLE_FUNCTIONAL_TESTS=1``
Then, set the :makevar:`ENABLE_FUNCTIONAL_TESTS` make variable when calling Then, set the :makevar:`ENABLE_FUNCTIONAL_TESTS` make variable when calling
``make test`` and the functional tests will be run as well. ``make test`` and the functional tests will be run as well.
Docs tests Docs tests
~~~~~~~~~~ ~~~~~~~~~~
.. TODO:: CMAKE_TODO
Is this available via CMake?
There are some additional tests for checking examples included in the There are some additional tests for checking examples included in the
documentation, which can be run by calling ``make test`` from the documentation, which can be run by calling ``make test`` from the
:file:`yosys/docs` sub-directory (or ``make -C docs test`` from the root). This :file:`yosys/docs` sub-directory (or ``make -C docs test`` from the root). This