mirror of https://github.com/YosysHQ/yosys.git
Updates to install and tests
Includes CAD suite info and details on the OSS CAD suite nightly build targets. Instructions for building from source, largely based on the readme but with some minor modifications. Tests are still WIP, but we replaced the old test suites with a brief comment on the github workflow tests. Still needs more on the tests themselves and how to run them locally. Also an extra todo on the index page.
This commit is contained in:
Krystine Sherwin
parent
f949579cf3
commit
4ecceaed44
|
|
@ -1,14 +1,148 @@
|
|||
Installation
|
||||
------------
|
||||
|
||||
.. todo:: update and finish installation instructions
|
||||
This document will guide you through the process of installing Yosys.
|
||||
|
||||
CAD suite(s)
|
||||
~~~~~~~~~~~~
|
||||
|
||||
Yosys is part of the `Tabby CAD Suite
|
||||
<https://www.yosyshq.com/tabby-cad-datasheet>`_ and the `OSS CAD Suite
|
||||
<https://github.com/YosysHQ/oss-cad-suite-build>`_! The easiest way to use yosys
|
||||
is to install the binary software suite, which contains all required
|
||||
dependencies and related tools.
|
||||
|
||||
* `Contact YosysHQ <https://www.yosyshq.com/contact>`_ for a `Tabby CAD Suite
|
||||
<https://www.yosyshq.com/tabby-cad-datasheet>`_ Evaluation License and
|
||||
download link
|
||||
* OR go to https://github.com/YosysHQ/oss-cad-suite-build/releases to download
|
||||
the free OSS CAD Suite
|
||||
* Follow the `Install Instructions on GitHub
|
||||
<https://github.com/YosysHQ/oss-cad-suite-build#installation>`_
|
||||
|
||||
Make sure to get a Tabby CAD Suite Evaluation License if you need features such
|
||||
as industry-grade SystemVerilog and VHDL parsers!
|
||||
|
||||
For more information about the difference between Tabby CAD Suite and the OSS
|
||||
CAD Suite, please visit https://www.yosyshq.com/tabby-cad-datasheet
|
||||
|
||||
Many Linux distributions also provide Yosys binaries, some more up to date than
|
||||
others. Check with your package manager!
|
||||
|
||||
Targeted architectures
|
||||
^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
The `OSS CAD Suite`_ releases `nightly builds`_ for the following architectures:
|
||||
|
||||
- linux-x64 |linux-x64|
|
||||
- Most personal Linux based computers
|
||||
|
||||
- darwin-x64 |darwin-x64|
|
||||
- macOS 10.14 or later with Intel CPU
|
||||
|
||||
- darwin-arm64 |darwin-arm64|
|
||||
- macOS 11.00 or later with M1 CPU
|
||||
|
||||
- windows-x64 |windows-x64|
|
||||
- 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
|
||||
|
||||
.. |linux-x64| image:: https://github.com/YosysHQ/oss-cad-suite-build/actions/workflows/linux-x64.yml/badge.svg
|
||||
.. |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
|
||||
~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Refer to the `readme`_ for the most up-to-date install instructions.
|
||||
|
||||
.. _readme: https://github.com/YosysHQ/yosys#building-from-source
|
||||
|
||||
Supported platforms
|
||||
~~~~~~~~~~~~~~~~~~~
|
||||
^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
The following platforms are supported and regularly tested:
|
||||
|
||||
- Linux
|
||||
- macOS
|
||||
|
||||
Other platforms which may work, but instructions may not be up to date and are
|
||||
not regularly tested:
|
||||
|
||||
- FreeBSD
|
||||
- WSL
|
||||
- Windows with (e.g.) Cygwin
|
||||
|
||||
Build prerequisites
|
||||
^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
A C++ compiler with C++11 support is required as well as some standard tools
|
||||
such as GNU Flex, GNU Bison, Make, libffi, and Python3.6 or later. Some
|
||||
additional tools: readline, Tcl and zlib; are optional but enabled by default
|
||||
(see ``ENABLE_*`` settings in Makefile). Xdot (graphviz) is optional unless
|
||||
using the :cmd:ref:`show` command to display schematics.
|
||||
|
||||
..
|
||||
unclear if libffi is required now or still optional
|
||||
readme says optional, but I can't find a corresponding ENABLE_*
|
||||
|
||||
Installing all prerequisites for Ubuntu 20.04:
|
||||
|
||||
.. code:: console
|
||||
|
||||
sudo sudo apt-get install build-essential clang bison flex \
|
||||
libreadline-dev gawk tcl-dev libffi-dev git make \
|
||||
graphviz xdot pkg-config python3 libboost-system-dev \
|
||||
libboost-python-dev libboost-filesystem-dev zlib1g-dev
|
||||
|
||||
Installing all prerequisites for macOS 11 (with Homebrew):
|
||||
|
||||
.. code:: console
|
||||
|
||||
brew install bison flex gawk libffi git graphviz \
|
||||
pkg-config python3 tcl-tk xdot bash boost-python3
|
||||
|
||||
Running the build system
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
To configure the build system to use a specific compiler, use one of the
|
||||
following:
|
||||
|
||||
.. code:: console
|
||||
|
||||
make config-clang
|
||||
make config-gcc
|
||||
|
||||
Then, simply run ``make`` in this directory.
|
||||
|
||||
.. code:: console
|
||||
|
||||
make
|
||||
sudo make install
|
||||
|
||||
Note that this also downloads, builds, and installs ABC (using yosys-abc as the
|
||||
executable name).
|
||||
|
||||
.. seealso::
|
||||
|
||||
Refer to :doc:`/test_suites` for details on testing Yosys once compiled.
|
||||
|
||||
Source tree and build system
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
.. todo:: check if source tree/build system details need updating
|
||||
|
||||
The Yosys source tree is organized into the following top-level
|
||||
directories:
|
||||
|
||||
|
|
|
|||
|
|
@ -7,6 +7,12 @@ Yosys Open SYnthesis Suite
|
|||
Consider adding something here that isn't just table of contents since this
|
||||
*is* the root page and is where the logo links to.
|
||||
|
||||
.. todo:: look into command ref improvements
|
||||
|
||||
- Search bar with live drop down suggestions for matching on title /
|
||||
autocompleting commands
|
||||
- Scroll the left sidebar to the current location on page load
|
||||
|
||||
.. only:: html
|
||||
|
||||
Table of contents
|
||||
|
|
|
|||
|
|
@ -1,55 +1,18 @@
|
|||
Test suites
|
||||
===========
|
||||
|
||||
.. note:: Potentially significantly out of date information
|
||||
last updated circa 2015
|
||||
.. todo:: more about the included test suite
|
||||
|
||||
.. todo:: update content from 2015
|
||||
Automatic testing
|
||||
-----------------
|
||||
|
||||
Continuously checking the correctness of Yosys and making sure that new features
|
||||
do not break old ones is a high priority in Yosys. Two external test suites
|
||||
have been built for Yosys: VlogHammer and yosys-bigsim. In addition to that,
|
||||
yosys comes with approx 200 test cases used in ``make test``. A debug build of
|
||||
Yosys also contains a lot of asserts and checks the integrity of the internal
|
||||
state after each command.
|
||||
The `Yosys Git repo`_ has automatic testing of builds and running of the
|
||||
included test suite on the following platforms:
|
||||
|
||||
VlogHammer
|
||||
----------
|
||||
- Ubuntu 20.04 (Focal Fossa) |test-linux|
|
||||
- macOS 11 (Big Sur) |test-macos|
|
||||
|
||||
VlogHammer is a Verilog regression test suite developed to test the different
|
||||
subsystems in Yosys by comparing them to each other and to the output created by
|
||||
some other tools (Xilinx Vivado, Xilinx XST, Altera Quartus II, ...).
|
||||
.. _Yosys Git repo: https://github.com/YosysHQ/yosys
|
||||
|
||||
Yosys Subsystems tested: Verilog frontend, const folding, const eval, technology
|
||||
mapping, simulation models, SAT models.
|
||||
|
||||
Thousands of auto-generated test cases containing code such as:
|
||||
|
||||
.. code-block:: verilog
|
||||
|
||||
assign y9 = $signed(((+$signed((^(6'd2 ** a2))))<$unsigned($unsigned(((+a3))))));
|
||||
assign y10 = (-((+((+{2{(~^p13)}})))^~(!{{b5,b1,a0},(a1&p12),(a4+a3)})));
|
||||
assign y11 = (~&(-{(-3'sd3),($unsigned($signed($unsigned({p0,b4,b1}))))}));
|
||||
|
||||
Some bugs in Yosys were found and fixed thanks to VlogHammer. Over 50 bugs in
|
||||
the other tools used as external reference where found and reported so far.
|
||||
|
||||
yosys-bigsim
|
||||
------------
|
||||
|
||||
yosys-bigsim is a collection of real-world open-source Verilog designs and test
|
||||
benches. yosys-bigsim compares the testbench outputs of simulations of the original
|
||||
Verilog code and synthesis results.
|
||||
|
||||
The following designs are included in yosys-bigsim (excerpt):
|
||||
|
||||
- ``openmsp430`` -- an MSP430 compatible 16 bit CPU
|
||||
- ``aes_5cycle_2stage`` -- an AES encryption core
|
||||
- ``softusb_navre`` -- an AVR compatible 8 bit CPU
|
||||
- ``amber23`` -- an ARMv2 compatible 32 bit CPU
|
||||
- ``lm32`` -- another 32 bit CPU from Lattice Semiconductor
|
||||
- ``verilog-pong`` -- a hardware pong game with VGA output
|
||||
- ``elliptic_curve_group`` -- ECG point-add and point-scalar-mul core
|
||||
- ``reed_solomon_decoder`` -- a Reed-Solomon Error Correction Decoder
|
||||
|
||||
Code available at https://github.com/YosysHQ/yosys-bigsim
|
||||
.. |test-linux| image:: https://github.com/YosysHQ/yosys/actions/workflows/test-linux.yml/badge.svg?branch=master
|
||||
.. |test-macos| image:: https://github.com/YosysHQ/yosys/actions/workflows/test-macos.yml/badge.svg?branch=master
|
||||
|
|
|
|||
Loading…
Reference in New Issue