commit	ec3b94fbc381ea9527f8db7efe0b4b58f17875f5	[log] [tgz]
author	Henner Zeller <h.zeller@acm.org>	Tue Nov 19 21:54:26 2019 -0800
committer	Henner Zeller <h.zeller@acm.org>	Tue Nov 19 21:54:26 2019 -0800
tree	049f0276cc8db470775700a9ca388779ca26b93f
parent	925c1c8877c694f21ea5fee908abb1b11525bdf2 [diff]

tree: 049f0276cc8db470775700a9ca388779ca26b93f

README.md

Surelog

System Verilog 2017 Pre-processor, Parser

Goal

This project aims at providing a complete System Verilog 2017 front-end: a preprocessor, a parser, an elaborator for both design and testbench.

Applications

Linter, Simulator, Synthesys tool, Formal tools can use this front-end and be developed either as plugins (linked with) or use this front-end as an intermediate step of their compilation flows using the on-disk memory models (down-converter).

Contributing to this project

This project is open to contributions from any users! From the commercial vendor to the Verilog enthousiast, all are welcome.

Features

The preprocessor and the parser use Antlr 4.72 as a parser generator.
The preprocessor and the parser ASTs are made persistent on disk using Google Flatbuffers, enabling incremental compilation.
The tool is built thread safe and performs multithread parsing.
Large files/modules/packages are splitted for multi-threading compilation.
Surelog accepts IEEE Simulator-compliant project specification.
Surelog issues Errors/Warning/Info/Notes about language compliance.
Surelog allows for pre-compiled packages (UVM,...).
A comprehensive Python API allows to:
- listen or visit the Parser grammar and create custom linting rules
- Visit the design data model and create custom linting rules
- Customize the message formats
- Waive messages

Build instructions and test:

Read INSTALL

make

make install (/usr/local/bin and /usr/local/lib/surelog by default, use DESTDIR= for alternative locations)

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

Surelog commands

The executable is located here (If not installed in:
- build/dist/Release/surelog
STANDARD VERILOG COMMAND LINE:
- -f Accepts a file containing command line arguments
- -v Library file
- -y Library directory
- +incdir+[+...] Specifies include paths
- -Idir Specifies include paths
- +libext++... Specifies the library extensions
- .v Verilog File
- .sv System Verilog 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 Defines library compilation order
- -map Specifies a library mapping file (multiple -map options supported)
- -cfgfile Specifies a configuration file (multiple -cfgFile options supported)
- -cfg Specifies a configuration to use (multiple -cfg options supported)
- -Dvar=value Same as env var definition for -f files var substitution
FLOWS OPTIONS:
- -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 the files after pre-processing step
- -nocomp Turns off Compilation & Elaboration
- -noelab Turns off Elaboration
- -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
- -strictpythoncheck Turns on strict Python checks
- -mt <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
```
- -split Split files or modules larger than specified line number for multi thread compilation
- -timescale= Specifies the overall timescale
- -nobuiltin Do not parse SV builtin classes (array...)
TRACES OPTIONS:
- -d Debug 1-4, lib, ast, inst, incl
- -nostdout Mutes Standard output
- -verbose Gives verbose processing information
- -profile Gives Profiling information
- -l Specifies log file, default is surelog.log under output dir
OUTPUT OPTIONS:
- -odir 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
- -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
- -o Turns on all compilation stages, produces all outputs under that path
- --help This help
- --version Surelog version and build date