mirror of https://github.com/YosysHQ/yosys.git
WIP docs
This commit is contained in:
Krystine Sherwin
parent
693d5a7eb0
commit
776995c74d
|
|
@ -1,5 +1,6 @@
|
|||
## user config
|
||||
/Makefile.conf
|
||||
/Configuration.cmake
|
||||
|
||||
## homebrew
|
||||
/Brewfile.lock.json
|
||||
|
|
|
|||
96
README.md
96
README.md
|
|
@ -75,10 +75,11 @@ or
|
|||
$ cd yosys
|
||||
$ git submodule update --init --recursive
|
||||
|
||||
You need a C++ compiler with C++17 support (up-to-date CLANG or GCC is
|
||||
recommended) and some standard tools such as GNU Flex, GNU Bison, and GNU Make.
|
||||
TCL, readline and libffi are optional (see ``ENABLE_*`` settings in Makefile).
|
||||
Xdot (graphviz) is used by the ``show`` command in yosys to display schematics.
|
||||
A C++ compiler with C++20 support is required as well as some standard tools
|
||||
such as GNU Flex, GNU Bison (>=3.8), CMake (>=3.27), Make, and Python (>=3.11).
|
||||
Some additional tools: readline, libffi, Tcl and zlib; will be used if available
|
||||
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
|
||||
prerequisites for building yosys:
|
||||
|
|
@ -86,45 +87,50 @@ prerequisites for building yosys:
|
|||
$ sudo apt-get install gawk git make python3 lld bison clang flex \
|
||||
libffi-dev libfl-dev libreadline-dev pkg-config tcl-dev zlib1g-dev \
|
||||
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
|
||||
run one of the following to override it:
|
||||
**NOTE**: By default, Ubuntu 22.04 LTS is limited to CMake 3.22 via `apt`. To
|
||||
install a newer version and meet the minimum required for building Yosys, use
|
||||
`sudo snap install cmake --classic`.
|
||||
|
||||
$ make config-clang
|
||||
$ make config-gcc
|
||||
CMake is used for build configuration, and requires a separate build directory:
|
||||
|
||||
The Makefile has many variables influencing the build process. These can be
|
||||
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:
|
||||
$ cmake -B build .
|
||||
|
||||
$ 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
|
||||
changes to the config section of the Makefile. It's also an alternative way to
|
||||
set the make variables mentioned above.
|
||||
$ ccmake build #..or..
|
||||
$ vi build/CMakeCache.txt
|
||||
|
||||
$ vi Makefile # ..or..
|
||||
$ vi Makefile.conf
|
||||
one-off options with
|
||||
|
||||
To build Yosys simply type 'make' in this directory.
|
||||
$ cmake -B build . --fresh \
|
||||
-DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++
|
||||
|
||||
$ make
|
||||
$ sudo make install
|
||||
set persistent options with
|
||||
|
||||
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.
|
||||
Execute tests via:
|
||||
|
||||
$ make test
|
||||
|
||||
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.
|
||||
$ cmake --build build --target test --parallel $(nproc)
|
||||
|
||||
|
||||
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
|
||||
a simple synthesis job using the interactive command shell:
|
||||
|
||||
$ ./yosys
|
||||
$ ./build/yosys
|
||||
yosys>
|
||||
|
||||
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:
|
||||
|
||||
$ brew install pdf2svg libfaketime
|
||||
$ brew install pdf2svg libfaketime
|
||||
|
||||
PDFLaTeX, included with most LaTeX distributions, is also needed during the
|
||||
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:
|
||||
|
||||
$ brew install basictex
|
||||
$ sudo tlmgr update --self
|
||||
$ sudo tlmgr install collection-latexextra latexmk tex-gyre
|
||||
$ brew install basictex
|
||||
$ sudo tlmgr update --self
|
||||
$ sudo tlmgr install collection-latexextra latexmk tex-gyre
|
||||
|
||||
The Python package, Sphinx, is needed along with those listed in
|
||||
`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
|
||||
as necessary before generating the website documentation from the yosys help
|
||||
commands. To build for pdf instead of html, call
|
||||
`make docs DOC_TARGET=latexpdf`.
|
||||
DOCS (e.g.)
|
||||
|
||||
$ cmake --build build --target docs-html --parallel
|
||||
|
||||
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.
|
||||
|
|
|
|||
|
|
@ -56,7 +56,7 @@ function(yosys_check_abc_submodule)
|
|||
else() #
|
||||
message(FATAL_ERROR
|
||||
"${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"
|
||||
" ('Source code' archive does not contain submodules.)\n"
|
||||
)
|
||||
|
|
|
|||
|
|
@ -14,8 +14,9 @@ Yosys environment variables
|
|||
Used for storing temporary files.
|
||||
|
||||
``ABC``
|
||||
When compiling Yosys with out-of-tree ABC using :makevar:`ABCEXTERNAL`, this
|
||||
variable can be used to override the external ABC executable.
|
||||
When compiling Yosys with out-of-tree ABC using
|
||||
:makevar:`YOSYS_ABC_EXECUTABLE`, this variable can be used to override the
|
||||
external ABC executable.
|
||||
|
||||
``YOSYS_NOVERIFIC``
|
||||
If Yosys was built with Verific, this environment variable can be used to
|
||||
|
|
|
|||
|
|
@ -88,10 +88,10 @@ Build prerequisites
|
|||
^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
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
|
||||
tools: readline, libffi, Tcl and zlib; are optional but enabled by default (see
|
||||
:makevar:`ENABLE_*` settings in Makefile). Graphviz and Xdot are used by the
|
||||
`show` command to display schematics.
|
||||
such as GNU Flex, GNU Bison (>=3.8), CMake (>=3.27), Make (or other CMake
|
||||
generator such as Ninja), and Python (>=3.11). Some additional tools: readline,
|
||||
libffi, Tcl and zlib; will be used if available but are optional. Graphviz and
|
||||
Xdot are used by the `show` command to display schematics.
|
||||
|
||||
Installing all prerequisites:
|
||||
|
||||
|
|
@ -102,7 +102,15 @@ Installing all prerequisites:
|
|||
sudo apt-get install gawk git make python3 lld bison clang flex \
|
||||
libffi-dev libfl-dev libreadline-dev pkg-config tcl-dev zlib1g-dev \
|
||||
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)
|
||||
|
||||
|
|
@ -127,6 +135,10 @@ Installing all prerequisites:
|
|||
.. note:: On FreeBSD system use gmake instead of make. To run tests use:
|
||||
``MAKE=gmake CXX=cxx CC=cc gmake test``
|
||||
|
||||
.. TODO:: CMAKE_TODO
|
||||
|
||||
Is this still required, and (how) does it work with CMake
|
||||
|
||||
.. tab:: Cygwin
|
||||
|
||||
Use the following command to install all prerequisites, or select these
|
||||
|
|
@ -134,7 +146,7 @@ Installing all prerequisites:
|
|||
|
||||
.. 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::
|
||||
|
||||
|
|
@ -142,7 +154,7 @@ Installing all prerequisites:
|
|||
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
|
||||
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
|
||||
recommended to use Windows Subsystem for Linux (WSL) and follow the
|
||||
instructions for Ubuntu.
|
||||
|
|
@ -168,52 +180,53 @@ Installing all prerequisites:
|
|||
Build configuration
|
||||
^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
The Yosys build is based solely on Makefiles, and uses a number of variables
|
||||
which influence the build process. The recommended method for configuring
|
||||
builds is with a ``Makefile.conf`` file in the root ``yosys`` directory. The
|
||||
following commands will clean the directory and provide an initial configuration
|
||||
file:
|
||||
The Yosys build is configured via CMake, and uses a number of variables
|
||||
which influence the build process.
|
||||
|
||||
set one-off options with
|
||||
|
||||
.. code:: console
|
||||
|
||||
make config-clang # ..or..
|
||||
make config-gcc
|
||||
cmake -B build . --fresh \
|
||||
-DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++
|
||||
|
||||
Check the root Makefile to see what other configuration targets are available.
|
||||
Other variables can then be added to the ``Makefile.conf`` as needed, for
|
||||
example:
|
||||
set persistent options with
|
||||
|
||||
.. 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
|
||||
than ``none``, and will override the environment variable for ``CXX``. To use a
|
||||
different compiler than the default when building, use:
|
||||
e.g.
|
||||
|
||||
.. 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
|
||||
|
||||
make CXX=$CXX # ..or..
|
||||
make CXX="g++-11"
|
||||
|
||||
.. note::
|
||||
|
||||
Setting the compiler in this way will prevent some other options such as
|
||||
``ENABLE_CCACHE`` from working as expected.
|
||||
ccmake build #..or..
|
||||
vi build/CMakeCache.txt
|
||||
|
||||
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
|
||||
``ENABLE_LTO=1``. On macOS, LTO requires using clang from homebrew rather than
|
||||
clang from xcode. For example:
|
||||
``CMAKE_INTERPROCEDURAL_OPTIMIZATION=ON``. On macOS, LTO requires using clang
|
||||
from homebrew rather than clang from xcode. For example:
|
||||
|
||||
.. 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`_,
|
||||
using :program:`yosys-abc` as the executable name. To use an existing ABC
|
||||
executable instead, set the ``ABCEXTERNAL`` make variable to point to the
|
||||
desired executable.
|
||||
executable instead, set the :makevar:`YOSYS_ABC_EXECUTABLE` make variable to point to
|
||||
the desired executable.
|
||||
|
||||
Running the build system
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
|
@ -222,17 +235,12 @@ From the root ``yosys`` directory, call the following commands:
|
|||
|
||||
.. code:: console
|
||||
|
||||
make
|
||||
sudo make install
|
||||
cmake -B build . -DCMAKE_BUILD_TYPE=Release
|
||||
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.
|
||||
|
||||
.. code:: console
|
||||
|
||||
mkdir build; cd build
|
||||
make -f ../Makefile
|
||||
|
||||
Out-of-tree builds require a clean source tree.
|
||||
Note that Yosys does not support in-tree builds, and if calling ``cmake`` from
|
||||
the root ``yosys`` directory the ``-B`` option must be provided.
|
||||
|
||||
.. seealso::
|
||||
|
||||
|
|
@ -248,6 +256,9 @@ directories:
|
|||
``backends/``
|
||||
This directory contains a subdirectory for each of the backend modules.
|
||||
|
||||
``cmake/``
|
||||
Additional ``.cmake`` files used by CMake during build generation.
|
||||
|
||||
``docs/``
|
||||
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
|
||||
the code for three passes: `hierarchy`, `submod`, and `uniquify`.
|
||||
|
||||
``pyosys/``
|
||||
Contains the scripts and wrappers necessary for building :doc:`Pyosys
|
||||
</using_yosys/pyosys>`.
|
||||
|
||||
``techlibs/``
|
||||
This directory contains simulation models and standard implementations for
|
||||
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
|
||||
Yosys. See :doc:`/yosys_internals/extending_yosys/test_suites`.
|
||||
|
||||
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.
|
||||
.. TODO:: CMAKE_TODO
|
||||
|
||||
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`.
|
||||
- ``yosys_<pass|test_pass|frontend|backend>(<name>)`` for each pass
|
||||
|
||||
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.
|
||||
- see :file:`cmake/YosysComponent.cmake`
|
||||
|
||||
- if using a sub folder, add it to the parent's ``CMakeLists.txt`` with
|
||||
``add_subdirectory(<name>)``
|
||||
|
||||
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.
|
||||
|
|
|
|||
|
|
@ -1,6 +1,8 @@
|
|||
Scripting with Pyosys
|
||||
=====================
|
||||
|
||||
.. TODO:: document libyosys sans python
|
||||
|
||||
Pyosys is a limited subset of the Yosys C++ API (aka "libyosys") made available
|
||||
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
|
||||
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
|
||||
--------------
|
||||
|
|
@ -21,7 +30,11 @@ Getting Pyosys
|
|||
Pyosys supports CPython 3.8 or higher. You can access Pyosys using one of two
|
||||
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
|
||||
Python scripts using an interpreter embedded in Yosys itself:
|
||||
|
|
@ -29,12 +42,9 @@ methods:
|
|||
``yosys -y ./my_pyosys_script.py``
|
||||
|
||||
Do note this requires some build-time dependencies to be available to Python,
|
||||
namely, ``pybind11`` and ``cxxheaderparser``. By default, the required
|
||||
``uv`` package will be used to create an ephemeral environment with the
|
||||
correct versions of the tools installed.
|
||||
|
||||
You can force use of your current Python environment by passing the Makefile
|
||||
flag ``PYOSYS_USE_UV=0``.
|
||||
namely, ``pybind11`` and ``cxxheaderparser``. If available, ``uv`` will be
|
||||
used to create an ephemeral environment with the correct versions of the
|
||||
tools installed.
|
||||
|
||||
2. Installing the Pyosys wheels
|
||||
|
||||
|
|
|
|||
|
|
@ -39,36 +39,36 @@ incorrect results.
|
|||
Compile options
|
||||
---------------
|
||||
|
||||
To enable Verific support ``ENABLE_VERIFIC`` has to be set to ``1`` and
|
||||
``VERIFIC_DIR`` needs to point to the location where the library is located.
|
||||
To enable Verific support, set the :makevar:`YOSYS_VERIFIC_DIR` CMake variable
|
||||
to point to the location where the library is located, e.g.
|
||||
|
||||
============== ========================== ===============================
|
||||
Parameter Default Description
|
||||
============== ========================== ===============================
|
||||
ENABLE_VERIFIC 0 Enable compilation with Verific
|
||||
VERIFIC_DIR /usr/local/src/verific_lib Library and headers location
|
||||
============== ========================== ===============================
|
||||
.. code-block:: console
|
||||
|
||||
Since there are multiple Verific library builds and they can have different
|
||||
features, there are compile options to select them.
|
||||
cmake -B build . -DYOSYS_VERIFIC_DIR="/usr/local/src/verific_lib"
|
||||
|
||||
================================= ======= ===================================
|
||||
Parameter Default Description
|
||||
================================= ======= ===================================
|
||||
ENABLE_VERIFIC_SYSTEMVERILOG 1 SystemVerilog support
|
||||
ENABLE_VERIFIC_VHDL 1 VHDL support
|
||||
ENABLE_VERIFIC_HIER_TREE 1 Hierarchy tree support
|
||||
ENABLE_VERIFIC_YOSYSHQ_EXTENSIONS 0 YosysHQ specific extensions support
|
||||
ENABLE_VERIFIC_EDIF 0 EDIF support
|
||||
ENABLE_VERIFIC_LIBERTY 0 Liberty file support
|
||||
================================= ======= ===================================
|
||||
During building, CMake will attempt to automatically detect available Verific
|
||||
library components to enable the corresponding compile-time option in Yosys.
|
||||
This can be overridden by manually setting the :makevar:`YOSYS_VERIFIC_FEATURES`
|
||||
CMake variable. This variable should contain a semi-colon separated list, e.g.
|
||||
``-DYOSYS_VERIFIC_FEATURES="systemverilog;hier_tree"``. The table below lists
|
||||
the features available to Yosys.
|
||||
|
||||
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
|
||||
:start-at: --cxxflags
|
||||
:end-before: --linkflags
|
||||
.. TODO:: CMAKE_TODO
|
||||
|
||||
``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::
|
||||
|
||||
|
|
@ -82,11 +82,10 @@ are required for the Yosys-Verific patch:
|
|||
|
||||
* RTL elaboration with
|
||||
|
||||
* SystemVerilog with ``ENABLE_VERIFIC_SYSTEMVERILOG``, and/or
|
||||
* VHDL support with ``ENABLE_VERIFIC_VHDL``.
|
||||
* SystemVerilog with ``systemverilog``, and/or
|
||||
* VHDL support with ``vhdl``.
|
||||
|
||||
* Hierarchy tree support and static elaboration with
|
||||
``ENABLE_VERIFIC_HIER_TREE``.
|
||||
* Hierarchy tree support and static elaboration with ``hier_tree``.
|
||||
|
||||
Please be aware that the following Verific configuration build parameter needs
|
||||
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
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
The following Verific features are available with TabbyCAD and can be enabled in
|
||||
Yosys builds:
|
||||
The following Verific features are available with TabbyCAD and will be
|
||||
automatically enabled in Yosys builds if the listed directory is included in the
|
||||
:makevar:`YOSYS_VERIFIC_DIR`:
|
||||
|
||||
* EDIF support with ``ENABLE_VERIFIC_EDIF``, and
|
||||
* Liberty file support with ``ENABLE_VERIFIC_LIBERTY``.
|
||||
* EDIF support with ``edif`` directory, and
|
||||
* Liberty file support with ``synlib`` directory.
|
||||
|
||||
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
|
||||
specific extensions of Verific library.
|
||||
|
||||
Configuration values:
|
||||
a. ``ENABLE_VERIFIC_SYSTEMVERILOG``
|
||||
b. ``ENABLE_VERIFIC_VHDL``
|
||||
c. ``ENABLE_VERIFIC_HIER_TREE``
|
||||
d. ``ENABLE_VERIFIC_YOSYSHQ_EXTENSIONS``
|
||||
|
||||
+--------------------------------------------------------------------------+-----+-----+-----+-----+
|
||||
| | Configuration values |
|
||||
+--------------------------------------------------------------------------+-----+-----+-----+-----+
|
||||
| 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 |
|
||||
+--------------------------------------------------------------------------+-----+-----+-----+-----+
|
||||
======================================================================= =================================
|
||||
Features :makevar:`YOSYS_VERIFIC_FEATURES`
|
||||
======================================================================= =================================
|
||||
SystemVerilog + RTL elaboration systemverilog
|
||||
VHDL + RTL elaboration vhdl
|
||||
SystemVerilog + VHDL + RTL elaboration systemverilog;vhdl
|
||||
SystemVerilog + RTL elaboration + Static elaboration + Hier tree systemverilog;vhdl;hier_tree
|
||||
VHDL + RTL elaboration + Static elaboration + Hier tree vhdl;hier_tree
|
||||
SystemVerilog + VHDL + RTL elaboration + Static elaboration + Hier tree systemverilog;vhdl;hier_tree
|
||||
======================================================================= =================================
|
||||
|
||||
.. note::
|
||||
|
||||
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
|
||||
they are disabled by default.
|
||||
those options. These are not mentioned above for simplification.
|
||||
|
|
|
|||
|
|
@ -7,19 +7,32 @@ Running the included test suite
|
|||
-------------------------------
|
||||
|
||||
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
|
||||
the root Yosys directory. By default, this runs vanilla and unit tests.
|
||||
everything working as expected. Tests can be run by building the ``test``
|
||||
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
|
||||
~~~~~~~~~~~~~
|
||||
|
||||
These make up the majority of our testing coverage.
|
||||
They can be run with ``make vanilla-test`` and are based on calls to
|
||||
make subcommands (``make makefile-tests``) and shell scripts
|
||||
(``make seed-tests`` and ``make 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.
|
||||
.. TODO:: update for test infra changes
|
||||
|
||||
These make up the majority of our testing coverage. They can be run with the
|
||||
``test-vanilla`` CMake target, or by calling ``make vanilla-test`` from the
|
||||
``tests`` directory, and are based on calls to make subcommands (``make
|
||||
makefile-tests``) and shell scripts (``make seed-tests`` and ``make
|
||||
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:
|
||||
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.
|
||||
|
||||
Unit tests can be run with ``make unit-test``.
|
||||
Unit tests can be run with the ``test-unit`` CMake target.
|
||||
|
||||
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
|
||||
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
|
||||
``make test`` and the functional tests will be run as well.
|
||||
|
||||
Docs tests
|
||||
~~~~~~~~~~
|
||||
|
||||
.. TODO:: CMAKE_TODO
|
||||
|
||||
Is this available via CMake?
|
||||
|
||||
There are some additional tests for checking examples included in 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
|
||||
|
|
|
|||
Loading…
Reference in New Issue