| # 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, 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. |
| |
| # 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`](INSTALL.md) |
| |
| ```bash |
| 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`](src/README.md) file. |
| |
| # Surelog commands |
| * The executable is located here (If not installed in: |
| * build/dist/Release/surelog |
| |
| * STANDARD VERILOG COMMAND LINE: |
| * -f <file> Accepts a file containing command line arguments |
| * -v <file> Library file |
| * -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 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 <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 |
| * 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 <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...) |
| |
| * TRACES OPTIONS: |
| * -d <int> Debug <level> 1-4, lib, ast, inst, incl |
| * -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 |
| |
| * OUTPUT OPTIONS: |
| * -odir <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 |
| * -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 <path> Turns on all compilation stages, produces all outputs under that path |
| * --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) |
| |
| ### Python 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 |
| |
| * The file [`src/API/slSV3_1aPythonListener.py`](src/API/slSV3_1aPythonListener.py) illustrates how a listener can be created to listen to the Parser AST. |
| * 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 |
| |
| ### Creating your own executable using libsurelog.a |
| * This is discussed in [`src/README`](src/README.md) file. |
| |
| ### Similar projects: |
| |
| * [hdlConvertor](https://github.com/Nic30/hdlConvertor/) - System Verilog 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 complient 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 |
