Awesome
<!-- # 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:
<!-- name="install-dependencies-package" -->apt install -y jq curl wget tk
then use the following script to download Synlig:
<!-- name="download-release" --> 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
<!-- name="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 toread_systemverilog
.
Quick start examples
Counter
Consider the following SystemVerilog code:
<!-- name="counter.sv" --> 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:
<!-- name="synthesis-example" --> > 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:
<!-- name="install-tools" --> 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:
<!-- name="formal-verification-run" --> ./tests/scripts/run_formal.sh --name=<test_suite_name> run
To gather formal verification results, run:
<!-- name="formal-verification-gather-results" --> ./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
- You can print the UHDM tree by adding the
-debug
flag toread_uhdm
orread_systemverilog
. This flag also prints the converted Yosys AST. - 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 fileA
, fileB
needs to be parsed before fileA
).
Embedding Synlig in a larger cmake-based project
- 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). - 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
<!-- name="install-dependencies-plugin" --> 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
.