diff --git a/docs/source/getting_started/installation.rst b/docs/source/getting_started/installation.rst index 1677445fa..f32cdf69d 100644 --- a/docs/source/getting_started/installation.rst +++ b/docs/source/getting_started/installation.rst @@ -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 +`_ and the `OSS CAD Suite +`_! The easiest way to use yosys +is to install the binary software suite, which contains all required +dependencies and related tools. + +* `Contact YosysHQ `_ for a `Tabby CAD Suite + `_ 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 + `_ + +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: diff --git a/docs/source/index.rst b/docs/source/index.rst index c19036f81..17e12f123 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -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 diff --git a/docs/source/test_suites.rst b/docs/source/test_suites.rst index fde337b28..3fa84ad3e 100644 --- a/docs/source/test_suites.rst +++ b/docs/source/test_suites.rst @@ -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