search

chipsalliance / Surelog

SystemVerilog 2017 Pre-processor, Parser, Elaborator, UHDM Compiler. Provides IEEE Design/TB C/C++ VPI and Python AST & UHDM APIs. Compiles on Linux gcc, Windows msys2-gcc & msvc, OsX
Apache License 2.0
369 stars 69 forks source link
antlr antlr4-grammar elaboration linter parser parser-ast preprocessor python-api systemverilog uvm verilog vpi vpi-api vpi-standard

readme

Surelog

SystemVerilog 2017 Pre-processor, Parser, Elaborator, UHDM Compiler. Provides IEEE Design/TB C/C++ VPI and Python AST API.

Goal

This project aims at providing a complete SystemVerilog 2017 front-end: a preprocessor, a parser, an elaborator for both design and testbench. We are aiming at supporting all open-source cores.

Applications

Linter, Simulator, Synthesis tool, Formal tools can use this front-end. They either can be developed as plugins (linked with) or use this front-end as an intermediate step of their compilation flows using the on-disk serialized models (UHDM).

Presentation

Contributing to this project

This project is open to contributions from any users! From the commercial vendor to the Verilog enthusiast, all are welcome. We started maintaining a list of ideas for contribution under Help Wanted

Features

Build instructions and test:

If you had a previous install, remove it first:
  make uninstall  (PREFIX=...)

  make
or
  make debug
or
  make release_no_tcmalloc (For no tcmalloc)
or
  make release_with_python

make install (/usr/local/bin and /usr/local/lib by default,
              use PREFIX= for alternative location)

For more build/test options and system requirements for building see src/README file.

Use Surelog as an external package with CMake

For your project to use Surelog as an external module, you need to tell CMake where to find Surelog. Note that CMake expects the module directory organized a certain way and Surelog's installation step does that so make sure to run that. You can provide the path to CMake in few different ways -

  1. By updating CMAKE_MODULE_PATH variable in your project's CMakeLists.txt file by adding the following lines -
set(CMAKE_MODULE_PATH ${CMAKE_MODULE_PATH} <absolute or relative path to surelog installation folder>)
find_package(Surelog)

  1. By providing the location of the surelog installation with the find_package command itself, as in the following -

    find_package(Surelog PATHS <absolute or relative path to surelog installation folder>)

  2. By providing the location of the surelog installation as a command line parameter when invoking CMake -

    cmake -DSurelog_DIR=<absolute or relative path to surelog installation folder> -S . -B out

For additional help, refer to cmake documentation on external modules.

Once CMake successfully finds Surelog, all you would need is to add the following line after the call to add_library/add_executable in your CMakeLists.txt file.

target_link_libraries(<your project name> surelog)

Usage

Surelog commands

 * SEPARATE COMPILATION FLOW OPTIONS:

-init Initializes cache for separate compile flow -sepcomp Separate compilation, each invocation of surelog creates a compilation unit (Optional -nohash) Each -sepcomp step can run in parallel -link Links and elaborates the separately compiled files (Optional -nohash and -elabuhdm)

Example: surelog -init surelog pkg1.sv pkg2.sv -sepcomp surelog top.sv -sepcomp surelog -link 


 * YOSYS AND VERILATOR FEATURES:
   To enable feature:

--enable-feature=,

   To disable feature:

--disable-feature=,

   Possible features:

parametersubstitution Enables/Disables substitution of assignment patterns in parameters letexprsubstitution Enables/Disables Let expr substitution

 * TRACES OPTIONS:

-d Debug 1-4, lib, ast, inst, incl, uhdm, coveruhdm, cache -nostdout Mutes Standard output -verbose Gives verbose processing information -profile Gives Profiling information

 * OUTPUT OPTIONS:

-l Specifies log file, default is surelog.log under output dir -odir/--Mdir

Specifies the output directory, default is ./ -writeppfile Writes out Preprocessor output in file (all compilation units will override this file) -writepp Writes out Preprocessor output (all compilation units will generate files under slpp_all/ or slpp_unit/) -lineoffsetascomments Writes the preprocessor line offsets as comments as opposed as parser directives -nocache Default allows to create a cache for include files, this option prevents it -cache Specifies the cache directory, default is slpp_all/cache or slpp_unit/cache -nohash Don't use hash mechanism for cache file path, always treat cache as valid (no timestamp/dependancy check) -createcache Create cache for precompiled packages -filterdirectives Filters out simple directives like default_nettype in pre-processor's output -filterprotected Filters out protected regions in pre-processor's output -filtercomments Filters out comments in pre-processor's output -outputlineinfo Outputs SLline directives in pre-processor's output -pploc Output message location in terms of post preprocessor location -noinfo Filters out INFO messages -nonote Filters out NOTE messages -nowarning Filters out WARNING messages -synth Reports non-synthesizable constructs Honnors //pragma translate_off , //pragma translate_on -formal Reports non-synthesizable constructs line -synth but still allows model checking constructs -o Turns on all compilation stages, produces all outputs under that path -cd Internally change directory to -exe Post execute a system call , passes it the preprocessor file list. --help This help --version Surelog version and build date

 * RETURN CODE

Bit mask the return code, more than 1 bit can be on. 0 - No issues 0x1 - Fatal error(s) 0x2 - Syntax error(s) 0x4 - Error(s)


### C++ API

 * Surelog comes in the form of a library libsurelog.a and can be linked to an executalble.
 * Extensive API is provided to browse:
   * the preprocessor file contents in AST form,
   * the post-parsing file contents in AST form,
   * the non-elaborated and elaborated design/testbench data model.
   * the UHDM or IEEE VPI Object Model.
 * Creating your own executable using libsurelog.a is discussed in [`src/README`](src/README.md) file.
 * Three examples executable source file [`src/hellosureworld.cpp`](src/hellosureworld.cpp), [`src/hellouhdm.cpp`](src/hellouhdm.cpp),  [`src/hellodesign.cpp`](src/hellodesign.cpp) illustrate how to navigate the Surelog internal data structure or the UHDM "VPI Standard Object Model" of the design using the libsurelog.a library.

### Python API

 * The most powerful Python API is the UHDM Python wrapper. It can be used independently of Surelog python's API and build options. See [UHDM Python API](https://github.com/chipsalliance/UHDM#python-api)   
 * By default Surelog does not build the Python API, See  [`src/README`](src/README.md)
 * The Python API is operating on the Preprocessor and Parser ASTs. It is not supporting elaboration. Post-elaborated API seekers need to the use UHDM C/C++ API.
 * The file [`slformatmsg.py`](src/API/slformatmsg.py) illustrates how messages can be reformated.
   * Place a modified version of this file either in the execution directory, or install directory /usr/local/lib/surelog-python

 * A simple example of creating a new error message and generating errors can be found here: [`python_listener.py`](src/API/python_listener.py)

 * A simple example for design-level data model exploration can be found here: [`myscriptPerDesign.py`](tests/UnitPython/myscriptPerDesign.py)

 * The complete Python API is described in the following files: [`SLAPI.h`](src/API/SLAPI.h) [`vobjecttypes`](src/API/vobjecttypes.py)

 * Waivers can be installed in slwaivers.py files in the execution directory or install directory /usr/local/lib/surelog-python

### Large design compilation on Linux
 * It is recommanded to use the -lowmem -mp <nb processor> options in conjunction for large designs.
 * The preprocessing will occur using one process, but the parsing will occur using multiple processes.
 * The elaboration and UHDM creation will use a single process.
 * Surelog spawns sub-Surelog processes to achieve the overall compilation.
 * Or course don't use the -nocache option to benefit from incremental compilation and reuse cached parsed files 

### Batch mode operations

  * A utility script [`tests/create_batch_script.tcl`](tests/create_batch_script.tcl) generates batch command files for large unit test regressions. See the script's internal help.

## Projects using Surelog:
* [Yosys SystemVerilog plugin](https://github.com/antmicro/yosys-systemverilog) Yosys plugin using Surelog/UHDM to add read_systemverilog command to Yosys
* [Surelog/UHDM/Yosys/Verilator](https://github.com/chipsalliance/UHDM-integration-tests) Full SystemVerilog Synthesis / Simulation flow
* [https://github.com/siliconcompiler/siliconcompiler](https://github.com/siliconcompiler/siliconcompiler) A modular build system for hardware

## Sister project:
* [UHDM](https://github.com/chipsalliance/UHDM/) - Full SystemVerilog (VHDL later) VPI API for interfacing with 3rd party tools

## Similar projects:
* [hdlConvertor](https://github.com/Nic30/hdlConvertor/) - SystemVerilog and VHDL parser, preprocessor and code generator for Python/C++ written in C++
* [cl-vhdl](https://github.com/mabragor/cl-vhdl) - lisp, Parser of VHDL into lisp-expressions
* [HDL_ANTLR4](https://github.com/denisgav/HDL_ANTLR4) - C# projects that use ANTLR4 library to analyse VHDL and Verilog code
* [hdlparse](https://github.com/kevinpt/hdlparse/) - vhdl/verilog parser in python
* [ieee1800_2017](https://github.com/veriktig/ieee1800_2017) - Java, SystemVerilog preprocessor
* [Pyverilog](https://github.com/PyHDI/Pyverilog) - python verilog toolkit
* [pyVHDLParser](https://github.com/Paebbels/pyVHDLParser) - python vhdl parser with 2008 support
* [rust_hdl](https://github.com/kraigher/rust_hdl) - rust vhdl 2008 parser
* [slang](https://github.com/MikePopoloski/slang) - Parser and compiler library for SystemVerilog.
* [sv-parser](https://github.com/dalance/sv-parser) - Rust, SystemVerilog parser library fully compliant with IEEE 1800-2017
* [systemc-clang](https://github.com/anikau31/systemc-clang) - SystemC Parser using the Clang Front-end
* [v2sc](https://github.com/denisgav/v2sc) - vhdl to systemc
* [veelox](https://github.com/martinda/veelox) - Java+ANTLR,  An experiment in SystemVerilog Preprocessing
* [verilog-parser](https://github.com/ben-marshall/verilog-parser) - A Flex/Bison Parser for the IEEE 1364-2001 Verilog Standard.
* [vbpp](https://github.com/balanx/vbpp) - C, Verilog PreProcessor
* [tree-sitter-verilog](https://github.com/tree-sitter/tree-sitter-verilog) - JS, Verilog grammar for tree-sitter
* [Verilog-Perl](https://metacpan.org/pod/Verilog-Perl)
* [vpp.pl](https://www.beyond-circuits.com/wordpress/vpp-pl-man-page/) - verilog preprocessor with integrated Perl
* [sv2v](https://github.com/zachjs/sv2v)- Haskell, SystemVerilog to Verilog