Synlig

Synlig is a SystemVerilog synthesis tool that uses Surelog as a SystemVerilog 2017 preprocessor, parser and elaborator, with Yosys as a framework for synthesis.

Installation

Download Synlig

You can download Synlig from the GitHub release page. First, make sure you have all required dependencies installed with:

apt install -y jq curl wget tk

then use the following script to download Synlig:

    curl https://api.github.com/repos/chipsalliance/synlig/releases/latest | jq -r '.assets | .[] | select(.name | startswith("synlig")) | .browser_download_url' | xargs wget -O - | tar -xz

To use Synlig, make sure to either use absolute paths, or update the PATH variable before use.

    export PATH=`pwd`/synlig:$PATH

Synlig is now ready to be used. Go to the Usage section of this document to learn how to use it.

Installation from source

Debian Bookworm:

Install dependencies

    apt install -y gcc-11 g++-11 build-essential cmake tclsh ant default-jre swig google-perftools libgoogle-perftools-dev python3 python3-dev python3-pip uuid uuid-dev tcl-dev flex libfl-dev git pkg-config libreadline-dev bison libffi-dev wget python3-orderedmultidict

Build required binaries

You can build all required binaries using the provided Makefile. make install will build and install Synlig in /usr/local directory.

    git submodule sync
    git submodule update --init --recursive third_party/{surelog,yosys}
    make install -j$(nproc)

Usage

You can now start Synlig by executing the synlig command. To read SystemVerilog files, use:

• read_systemverilog [options] [filenames] - reads SystemVerilog files.
• read_uhdm [options] [filename] - allows reading UHDM files - SystemVerilog files already processed by Surelog. Afterwards, it works similarly to read_systemverilog.

Quick start examples

Counter

Consider the following SystemVerilog code:

    module top (
      input clk,
      output [3:0] led
    );
      localparam BITS = 4;
      localparam LOG2DELAY = 22;

      wire bufg;
      BUFG bufgctrl (
          .I(clk),
          .O(bufg)
      );
      reg [BITS+LOG2DELAY-1:0] counter = 0;
      always @(posedge bufg) begin
        counter <= counter + 1;
      end
      assign led[3:0] = counter >> LOG2DELAY;
    endmodule

Running synthesis using Synlig is very simple:

    > read_systemverilog counter.sv
    1. Executing SystemVerilog frontend.
    (...)

    > synth_xilinx
    2. Executing SYNTH_XILINX pass.
    (...)

    Number of wires:                 10
    Number of wire bits:            167
    Number of public wires:           4
    Number of public wire bits:      32
    Number of ports:                  2
    Number of port bits:              5
    Number of memories:               0
    Number of memory bits:            0
    Number of processes:              0
    Number of cells:                 40
      BUFG                            1
      CARRY4                          7
      FDRE                           26
      IBUF                            1
      INV                             1
      OBUF                            4
    (...)

    > write_edif counter.edif
    3. Executing Synlig EDIF backend.

As a result, we get a counter.edif file that can be further processed to generate the bitstream.

Parsing multiple files

To parse a multi-file design with the read_systemverilog command, all files have to be listed simultaneously. This can be troublesome for larger designs. To mitigate this issue, Synlig supports a flow that allows users to pass files and link them separately. Files can be loaded one by one using the -defer flag. Once all files are uploaded, you should call read_systemverilog -link to elaborate them. The described flow looks like the following:

    # Read each file separately
    read_systemverilog -defer tests/separate_compilation/separate_compilation.v
    read_systemverilog -defer tests/separate_compilation/separate_compilation_buf.sv
    read_systemverilog -defer tests/separate_compilation/separate_compilation_pkg.sv
    # Finish reading files, elaborate the design
    read_systemverilog -link
    # Continue Synlig flow...
    exit

The -defer flag is experimental. If you encounter any problems with it, please compare the results with a single read_systemverilog command, check the open issues, and open a new issue if required.

Testing locally

Formal verification

Synlig runs formal verification tests to make sure it provides results comparable with other synthesis tools. More information about formal verification can be found in this README.

Prerequisites

Dependencies

Building sv2v requires Haskell Stack, you can install it by running:

   wget -qO- https://get.haskellstack.org/ | sh -s - -f -d /usr/local/bin

Installation

All required prerequisites can be installed by running:

    git submodule update --init --recursive --checkout third_party/{sv2v,eqy,sby,yosys}
    make tools -j $(nproc)

Running formal verification

To start formal verification tests, use the dedicated script:

    ./tests/scripts/run_formal.sh --name=<test_suite_name> run

To gather formal verification results, run:

    ./tests/scripts/run_formal.sh --name=<test_suite_name> gather_results

Available targets

You can see the available test_suite_name options by running:

    ./tests/scripts/run_formal.sh --help

Design tests

Synlig is also tested by synthesizing several designs:

• OpenTitan,
• Ibex,
• VeeR,
• BlackParrot.

For more details, check .github/workflows/large-designs.yml or run:

    ./tests/scripts/run_large_designs.sh --help

Parsing tests

Synlig is additionally tested with parsing tests. For more details check .github/workflows/parsing-tests.yml or run:

    ./tests/scripts/run_parsing.sh --help

General & debugging tips

1. You can print the UHDM tree by adding the -debug flag to read_uhdm or read_systemverilog. This flag also prints the converted Yosys AST.
2. The order of the files matters. Surelog requires all definitions to be already defined when a file is parsed (e.g. if file B is defining a type used in file A, file B needs to be parsed before file A).

Embedding Synlig in a larger cmake-based project

1. An alternative build mechanism defined in the CMakeLists.txt file is provided to allow Synlig to be built as part of a larger cmake-based project. Simply include add_subsystem(synlig) in your parent CMake. See CMakeLists.txt for compilation options (with or without vendored Yosys and Surelog).
2. To test this build system locally, use make -f cmake-makefile.

Plugin mode

Synlig is also available as a Yosys plugin. Note that almost all tests are made using the Synlig binary instead of the plugin version, and there is no guarantee that the plugin version will be still developed in the future.

Installation from source

Install dependencies

    apt install -y gcc-11 g++-11 build-essential cmake tclsh ant default-jre swig google-perftools libgoogle-perftools-dev python3 python3-dev python3-pip uuid uuid-dev tcl-dev flex libfl-dev git pkg-config libreadline-dev bison libffi-dev wget python3-orderedmultidict

Build required binaries

You can build all required binaries using the provided Makefile. make install-plugin will build Yosys and Synlig as a plugin, and place them in the out directory. You need to add out/bin to your PATH variable to ensure you are using correct versions of the binaries.

    git submodule update --init --recursive third_party/{surelog,yosys}
    make install-plugin -j$(nproc)

To use Yosys built from a submodule, make sure to either use absolute paths, or update the PATH variable before use.

    export PATH=`pwd`/out/bin:$PATH

Loading Synlig as a plugin into Yosys

You can now start Yosys by executing the yosys command. In order to use the SystemVerilog plugin, you first need to load it in Yosys by executing the following command in Yosys prompt: plugin -i systemverilog.