Home

Awesome

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>)
  1. 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

 -f <file>             Accepts a file containing command line arguments
 -v <file>             Library file
 -sv <file>            Forces this file to be parsed as a SystemVerilog file
 -sverilog             Forces all files to be parsed as SystemVerilog files
 -y <path>             Library directory
 +incdir+<dir>[+<dir>...]  Specifies include paths
 -Idir                 Specifies include paths
 +libext+<extname>+... Specifies the library extensions
 <file>.v              Verilog File
 <file>.sv             SystemVerilog File
 +liborder             Lib Order option (ignored)
 +librescan            Lib Rescan option (ignored)
 +libverbose           Lib Verbose option (ignored)
 +nolibcell            No Lib Cell option (ignored)
 +define+name=value[+name=value...] Defines a macro and optionally its value
 -L <libName>          Defines library compilation order
 -map <mapFile>        Specifies a library mapping file (multiple -map options supported)
 -cfgfile <confiFile>  Specifies a configuration file (multiple -cfgFile options supported)
 -cfg <configName>     Specifies a configuration to use (multiple -cfg options supported)
 -Dvar=value           Same as env var definition for -f files var substitution
 -Pparameter=value     Overrides a toplevel module parameter
 -cmd_ign <cmd> <argc> Ignore <cmd> when encountered and drop <argc> arguments
 -cmd_ren <flag1> <flag2> rename <flag1> into <flag2> when encountered 
 -cmd_mrg <flag1> <flag2> merge <flag1> argument into a unified <flag2> '+' argument when encountered 
  -fileunit             Compiles each Verilog file as an independent compilation unit (under slpp_unit/ if -writepp used)
  -diffcompunit         Compiles both all files as a whole unit and separate compilation units to perform diffs
  -parse                Parse/Compile/Elaborate/Produces UHDM.
  -top/--top-module <module> Top level module for elaboration (multiple cmds ok)
  -bb_mod <module>      Blackbox module (multiple cmds ok, ex: -bb_mod work@top)
  -bb_inst <instance>   Blackbox instance (multiple cmds ok, ex: -bb_inst work@top.u1)
  -noparse              Turns off Parsing & Compilation & Elaboration
  -nocomp               Turns off Compilation & Elaboration
  -noelab               Turns off Elaboration
  -parseonly            Only Parses, reloads Preprocessor saved db
  -elabuhdm             Forces UHDM/VPI Full Elaboration/Uniquification, default is the Folded Model.
                        A client application can elect to perform the full elaboration after reading back the UHDM db by invoking the Elaborator listener.
  -batch <batch.txt>    Runs all the tests specified in the file in batch mode. Tests are expressed as one full command line per line.
  -pythonlistener       Enables the Parser Python Listener
  -pythonlistenerfile <script.py> Specifies the AST python listener file
  -pythonevalscriptperfile <script.py>  Eval the Python script on each source file (Multithreaded)
  -pythonevalscript <script.py> Eval the Python script at the design level
  -nopython             Turns off all Python features, including waivers
  -withpython           Turns on all Python features, including waivers (Requires to build with python (SURELOG_WITH_PYTHON=1)
  -strictpythoncheck    Turns on strict Python checks
  -mt/--threads <nb_max_treads>   0 up to 512 max threads, 0 or 1 being single threaded, if "max" is given, the program will use one thread per core on the host
  -mp <nb_max_processes> 0 up to 512 max processes, 0 or 1 being single process
  -lowmem               Minimizes memory high water mark (uses multiple staggered processes for preproc, parsing and elaboration)
  -split <line number>  Split files or modules larger than specified line number for multi thread compilation
  -timescale=<timescale> Specifies the overall timescale
  -nobuiltin            Do not parse SV builtin classes (array...)

Example:
 surelog top.sv -parse -d uhdm

 -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 

   -d <int>              Debug <level> 1-4, lib, ast, inst, incl, uhdm, coveruhdm, cache
   -nostdout             Mutes Standard output
   -verbose              Gives verbose processing information
   -profile              Gives Profiling information
   -l <file>             Specifies log file, default is surelog.log under output dir
   -odir/--Mdir <dir>    Specifies the output directory, default is ./
   -writeppfile <file>   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 <dir>          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 <path>             Turns on all compilation stages, produces all outputs under that path
   -cd <dir>             Internally change directory to <dir>
   -exe <command>        Post execute a system call <command>, passes it the preprocessor file list.
   --help                This help
   --version             Surelog version and build date
   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

Python API

Large design compilation on Linux

Batch mode operations

Projects using Surelog:

Sister project:

Similar projects: