{"id":18352809,"url":"https://github.com/chipsalliance/surelog","last_synced_at":"2025-05-15T15:05:18.496Z","repository":{"id":36956333,"uuid":"218417034","full_name":"chipsalliance/Surelog","owner":"chipsalliance","description":"SystemVerilog 2017 Pre-processor, Parser, Elaborator, UHDM Compiler. Provides IEEE Design/TB C/C++ VPI and Python AST \u0026 UHDM APIs. Compiles on Linux gcc, Windows msys2-gcc \u0026 msvc, OsX ","archived":false,"fork":false,"pushed_at":"2025-03-30T05:18:48.000Z","size":879641,"stargazers_count":387,"open_issues_count":54,"forks_count":72,"subscribers_count":25,"default_branch":"master","last_synced_at":"2025-04-15T05:25:07.187Z","etag":null,"topics":["antlr","antlr4-grammar","elaboration","linter","parser","parser-ast","preprocessor","python-api","systemverilog","uvm","verilog","vpi","vpi-api","vpi-standard"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/chipsalliance.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2019-10-30T01:25:50.000Z","updated_at":"2025-04-04T03:53:13.000Z","dependencies_parsed_at":"2025-03-31T23:40:38.370Z","dependency_job_id":null,"html_url":"https://github.com/chipsalliance/Surelog","commit_stats":{"total_commits":3482,"total_committers":35,"mean_commits":99.48571428571428,"dds":0.3796668581275129,"last_synced_commit":"100847cfcea6ca55012872ae82abc2c9c3eb5abf"},"previous_names":[],"tags_count":44,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chipsalliance%2FSurelog","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chipsalliance%2FSurelog/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chipsalliance%2FSurelog/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chipsalliance%2FSurelog/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/chipsalliance","download_url":"https://codeload.github.com/chipsalliance/Surelog/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254364270,"owners_count":22058878,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["antlr","antlr4-grammar","elaboration","linter","parser","parser-ast","preprocessor","python-api","systemverilog","uvm","verilog","vpi","vpi-api","vpi-standard"],"created_at":"2024-11-05T21:37:28.994Z","updated_at":"2025-05-15T15:05:13.488Z","avatar_url":"https://github.com/chipsalliance.png","language":"C++","readme":"# Surelog\n\nSystemVerilog 2017 Pre-processor, Parser, Elaborator, UHDM Compiler. Provides IEEE Design/TB C/C++ VPI and Python AST API. \n\n## Goal\nThis 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.\n* Current status: \n   * Surelog's elaboration trees for [BlackParrot](https://github.com/black-parrot/black-parrot), [Ariane](https://github.com/lowRISC/ariane) cores are equivalent with Verilator's elaboration tree. \n   * [Ibex](https://github.com/lowRISC/ibex) and [Earlgrey](https://github.com/lowRISC/opentitan) completely Synthesizes and runs in Hardware with the Surelog/UHDM/Yosys flow. \n\n## Applications\n\nLinter, 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).\n\n## Presentation\n* [WOSET 2020 UHDM (\u0026 Surelog) Paper and Presentation](https://woset-workshop.github.io/WOSET2020.html#article-10)\n\n## Contributing to this project\n\nThis project is open to contributions from any users! From the commercial vendor to the Verilog enthusiast, all are welcome.\nWe started maintaining a list of ideas for contribution under [Help Wanted](https://github.com/alainmarcel/Help_Wanted)\n\n## Features\n\n * The preprocessor and the parser use Antlr 4.10 as a parser generator, we track Antlr/main.\n * The preprocessor and the parser ASTs are made persistent on disk using Cap'n'Proto, enabling incremental compilation.\n * The tool is built thread safe and performs multithread parsing.\n * Large files/modules/packages are splitted for multi-threading compilation.\n * Surelog accepts IEEE Simulator-compliant project specification.\n * Surelog issues Errors/Warning/Info/Notes about language compliance.\n * Surelog allows for pre-compiled packages (UVM,...).\n * A comprehensive Python API allows to:\n    * listen or visit the Parser grammar and create custom linting rules\n    * Visit the design data model and create custom linting rules\n    * Customize the message formats\n    * Waive messages\n * Surelog creates a [UHDM](https://github.com/chipsalliance/UHDM/) compiled database of the design that can be read by 3rd party tools (Synthesis, Simulator, Linter, Formal...) using the Standard VPI API.\n\n## Build instructions and test:\n\n * Read [`INSTALL`](INSTALL.md)\n\n```bash\nIf you had a previous install, remove it first:\n  make uninstall  (PREFIX=...)\n\n  make\nor\n  make debug\nor\n  make release_no_tcmalloc (For no tcmalloc)\nor\n  make release_with_python\n  \nmake install (/usr/local/bin and /usr/local/lib by default,\n              use PREFIX= for alternative location)\n```\n\nFor more build/test options and system requirements for building see\n[`src/README`](src/README.md) file.\n\n## Use Surelog as an external package with CMake\n\nFor 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 -\n\n1. By updating `CMAKE_MODULE_PATH` variable in your project's CMakeLists.txt file by adding the following lines -\n\n```\nset(CMAKE_MODULE_PATH ${CMAKE_MODULE_PATH} \u003cabsolute or relative path to surelog installation folder\u003e)\nfind_package(Surelog)\n```\n\n2. By providing the location of the surelog installation with the `find_package` command itself, as in the following -\n```\nfind_package(Surelog PATHS \u003cabsolute or relative path to surelog installation folder\u003e)\n```\n\n3. By providing the location of the surelog installation as a command line parameter when invoking CMake -\n```\ncmake -DSurelog_DIR=\u003cabsolute or relative path to surelog installation folder\u003e -S . -B out\n```\n\nFor additional help, refer to cmake documentation on external modules.\n\nOnce 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.\n```\ntarget_link_libraries(\u003cyour project name\u003e surelog)\n```\n\n## Usage\n\n### Surelog commands\n\n * The executable is located here:\n   * build/bin/surelog  (Release build)\n   * dbuild/bin/surelog (Debug build)\n   * /usr/local/bin/surelog (After install)\n\n * STANDARD VERILOG COMMAND LINE:\n  ```\n   -f \u003cfile\u003e             Accepts a file containing command line arguments\n   -v \u003cfile\u003e             Library file\n   -sv \u003cfile\u003e            Forces this file to be parsed as a SystemVerilog file\n   -sverilog             Forces all files to be parsed as SystemVerilog files\n   -y \u003cpath\u003e             Library directory\n   +incdir+\u003cdir\u003e[+\u003cdir\u003e...]  Specifies include paths\n   -Idir                 Specifies include paths\n   +libext+\u003cextname\u003e+... Specifies the library extensions\n   \u003cfile\u003e.v              Verilog File\n   \u003cfile\u003e.sv             SystemVerilog File\n   +liborder             Lib Order option (ignored)\n   +librescan            Lib Rescan option (ignored)\n   +libverbose           Lib Verbose option (ignored)\n   +nolibcell            No Lib Cell option (ignored)\n   +define+name=value[+name=value...] Defines a macro and optionally its value\n   -L \u003clibName\u003e          Defines library compilation order\n   -map \u003cmapFile\u003e        Specifies a library mapping file (multiple -map options supported)\n   -cfgfile \u003cconfiFile\u003e  Specifies a configuration file (multiple -cfgFile options supported)\n   -cfg \u003cconfigName\u003e     Specifies a configuration to use (multiple -cfg options supported)\n   -Dvar=value           Same as env var definition for -f files var substitution\n   -Pparameter=value     Overrides a toplevel module parameter\n```\n * EDA TOOLS COMPATIBILITY OPTIONS:\n ```\n  -cmd_ign \u003ccmd\u003e \u003cargc\u003e Ignore \u003ccmd\u003e when encountered and drop \u003cargc\u003e arguments\n  -cmd_ren \u003cflag1\u003e \u003cflag2\u003e rename \u003cflag1\u003e into \u003cflag2\u003e when encountered \n  -cmd_mrg \u003cflag1\u003e \u003cflag2\u003e merge \u003cflag1\u003e argument into a unified \u003cflag2\u003e '+' argument when encountered \n```\n * FLOWS OPTIONS:\n ```\n   -fileunit             Compiles each Verilog file as an independent compilation unit (under slpp_unit/ if -writepp used)\n   -diffcompunit         Compiles both all files as a whole unit and separate compilation units to perform diffs\n   -parse                Parse/Compile/Elaborate/Produces UHDM.\n   -top/--top-module \u003cmodule\u003e Top level module for elaboration (multiple cmds ok)\n   -bb_mod \u003cmodule\u003e      Blackbox module (multiple cmds ok, ex: -bb_mod work@top)\n   -bb_inst \u003cinstance\u003e   Blackbox instance (multiple cmds ok, ex: -bb_inst work@top.u1)\n   -noparse              Turns off Parsing \u0026 Compilation \u0026 Elaboration\n   -nocomp               Turns off Compilation \u0026 Elaboration\n   -noelab               Turns off Elaboration\n   -parseonly            Only Parses, reloads Preprocessor saved db\n   -elabuhdm             Forces UHDM/VPI Full Elaboration/Uniquification, default is the Folded Model.\n                         A client application can elect to perform the full elaboration after reading back the UHDM db by invoking the Elaborator listener.\n   -batch \u003cbatch.txt\u003e    Runs all the tests specified in the file in batch mode. Tests are expressed as one full command line per line.\n   -pythonlistener       Enables the Parser Python Listener\n   -pythonlistenerfile \u003cscript.py\u003e Specifies the AST python listener file\n   -pythonevalscriptperfile \u003cscript.py\u003e  Eval the Python script on each source file (Multithreaded)\n   -pythonevalscript \u003cscript.py\u003e Eval the Python script at the design level\n   -nopython             Turns off all Python features, including waivers\n   -withpython           Turns on all Python features, including waivers (Requires to build with python (SURELOG_WITH_PYTHON=1)\n   -strictpythoncheck    Turns on strict Python checks\n   -mt/--threads \u003cnb_max_treads\u003e   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\n   -mp \u003cnb_max_processes\u003e 0 up to 512 max processes, 0 or 1 being single process\n   -lowmem               Minimizes memory high water mark (uses multiple staggered processes for preproc, parsing and elaboration)\n   -split \u003cline number\u003e  Split files or modules larger than specified line number for multi thread compilation\n   -timescale=\u003ctimescale\u003e Specifies the overall timescale\n   -nobuiltin            Do not parse SV builtin classes (array...)\n\n Example:\n  surelog top.sv -parse -d uhdm\n\n```\n * SEPARATE COMPILATION FLOW OPTIONS:\n ```\n  -init                  Initializes cache for separate compile flow\n  -sepcomp               Separate compilation, each invocation of surelog creates a compilation unit (Optional -nohash)\n                         Each -sepcomp step can run in parallel\n  -link                  Links and elaborates the separately compiled files (Optional -nohash and -elabuhdm)\n\n  Example:\n    surelog -init\n    surelog pkg1.sv pkg2.sv -sepcomp\n    surelog top.sv -sepcomp \n    surelog -link \n\n``` \n\n * YOSYS AND VERILATOR FEATURES:\n   To enable feature:\n   ```\n   --enable-feature=\u003cfeature1\u003e,\u003cfeature2\u003e\n\n   ```\n   To disable feature:\n   ```\n   --disable-feature=\u003cfeature1\u003e,\u003cfeature2\u003e\n   ```\n   Possible features:\n   ```\n   parametersubstitution\tEnables/Disables substitution of assignment patterns in parameters\n   letexprsubstitution          Enables/Disables Let expr substitution\n   ```\n * TRACES OPTIONS:\n```\n   -d \u003cint\u003e              Debug \u003clevel\u003e 1-4, lib, ast, inst, incl, uhdm, coveruhdm, cache\n   -nostdout             Mutes Standard output\n   -verbose              Gives verbose processing information\n   -profile              Gives Profiling information\n```\n * OUTPUT OPTIONS:\n``` \n   -l \u003cfile\u003e             Specifies log file, default is surelog.log under output dir\n   -odir/--Mdir \u003cdir\u003e    Specifies the output directory, default is ./\n   -writeppfile \u003cfile\u003e   Writes out Preprocessor output in file (all compilation units will override this file)\n   -writepp              Writes out Preprocessor output (all compilation units will generate files under slpp_all/ or slpp_unit/)\n   -lineoffsetascomments Writes the preprocessor line offsets as comments as opposed as parser directives\n   -nocache              Default allows to create a cache for include files, this option prevents it\n   -cache \u003cdir\u003e          Specifies the cache directory, default is slpp_all/cache or slpp_unit/cache\n   -nohash               Don't use hash mechanism for cache file path, always treat cache as valid (no timestamp/dependancy check)\n   -createcache          Create cache for precompiled packages\n   -filterdirectives     Filters out simple directives like default_nettype in pre-processor's output\n   -filterprotected      Filters out protected regions in pre-processor's output\n   -filtercomments       Filters out comments in pre-processor's output\n   -outputlineinfo       Outputs SLline directives in pre-processor's output\n   -pploc                Output message location in terms of post preprocessor location\n   -noinfo               Filters out INFO messages\n   -nonote               Filters out NOTE messages\n   -nowarning            Filters out WARNING messages\n   -synth                Reports non-synthesizable constructs\n                         Honnors //pragma translate_off  ,  //pragma translate_on\n   -formal               Reports non-synthesizable constructs line -synth\n                         but still allows model checking constructs\n   -o \u003cpath\u003e             Turns on all compilation stages, produces all outputs under that path\n   -cd \u003cdir\u003e             Internally change directory to \u003cdir\u003e\n   -exe \u003ccommand\u003e        Post execute a system call \u003ccommand\u003e, passes it the preprocessor file list.\n   --help                This help\n   --version             Surelog version and build date\n```   \n * RETURN CODE\n``` \n   Bit mask the return code, more than 1 bit can be on.\n     0   - No issues\n     0x1 - Fatal error(s)\n     0x2 - Syntax error(s)\n     0x4 - Error(s)\n```\n### C++ API\n\n * Surelog comes in the form of a library libsurelog.a and can be linked to an executalble.\n * Extensive API is provided to browse:\n   * the preprocessor file contents in AST form,\n   * the post-parsing file contents in AST form,\n   * the non-elaborated and elaborated design/testbench data model.\n   * the UHDM or IEEE VPI Object Model.\n * Creating your own executable using libsurelog.a is discussed in [`src/README`](src/README.md) file.\n * 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.\n\n### Python API\n \n * 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)   \n * By default Surelog does not build the Python API, See  [`src/README`](src/README.md)\n * 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.\n * The file [`slformatmsg.py`](src/API/slformatmsg.py) illustrates how messages can be reformated.\n   * Place a modified version of this file either in the execution directory, or install directory /usr/local/lib/surelog-python\n\n * A simple example of creating a new error message and generating errors can be found here: [`python_listener.py`](src/API/python_listener.py)\n\n * A simple example for design-level data model exploration can be found here: [`myscriptPerDesign.py`](tests/UnitPython/myscriptPerDesign.py)\n\n * The complete Python API is described in the following files: [`SLAPI.h`](src/API/SLAPI.h) [`vobjecttypes`](src/API/vobjecttypes.py)\n\n * Waivers can be installed in slwaivers.py files in the execution directory or install directory /usr/local/lib/surelog-python\n\n### Large design compilation on Linux\n * It is recommanded to use the -lowmem -mp \u003cnb processor\u003e options in conjunction for large designs.\n * The preprocessing will occur using one process, but the parsing will occur using multiple processes.\n * The elaboration and UHDM creation will use a single process.\n * Surelog spawns sub-Surelog processes to achieve the overall compilation.\n * Or course don't use the -nocache option to benefit from incremental compilation and reuse cached parsed files \n\n### Batch mode operations\n\n  * 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.\n\n## Projects using Surelog:\n* [Yosys SystemVerilog plugin](https://github.com/antmicro/yosys-systemverilog) Yosys plugin using Surelog/UHDM to add read_systemverilog command to Yosys\n* [Surelog/UHDM/Yosys/Verilator](https://github.com/chipsalliance/UHDM-integration-tests) Full SystemVerilog Synthesis / Simulation flow\n* [https://github.com/siliconcompiler/siliconcompiler](https://github.com/siliconcompiler/siliconcompiler) A modular build system for hardware\n\n## Sister project:\n* [UHDM](https://github.com/chipsalliance/UHDM/) - Full SystemVerilog (VHDL later) VPI API for interfacing with 3rd party tools\n\n## Similar projects:\n* [hdlConvertor](https://github.com/Nic30/hdlConvertor/) - SystemVerilog and VHDL parser, preprocessor and code generator for Python/C++ written in C++\n* [cl-vhdl](https://github.com/mabragor/cl-vhdl) - lisp, Parser of VHDL into lisp-expressions\n* [HDL_ANTLR4](https://github.com/denisgav/HDL_ANTLR4) - C# projects that use ANTLR4 library to analyse VHDL and Verilog code\n* [hdlparse](https://github.com/kevinpt/hdlparse/) - vhdl/verilog parser in python\n* [ieee1800_2017](https://github.com/veriktig/ieee1800_2017) - Java, SystemVerilog preprocessor\n* [Pyverilog](https://github.com/PyHDI/Pyverilog) - python verilog toolkit\n* [pyVHDLParser](https://github.com/Paebbels/pyVHDLParser) - python vhdl parser with 2008 support\n* [rust_hdl](https://github.com/kraigher/rust_hdl) - rust vhdl 2008 parser\n* [slang](https://github.com/MikePopoloski/slang) - Parser and compiler library for SystemVerilog.\n* [sv-parser](https://github.com/dalance/sv-parser) - Rust, SystemVerilog parser library fully compliant with IEEE 1800-2017\n* [systemc-clang](https://github.com/anikau31/systemc-clang) - SystemC Parser using the Clang Front-end\n* [v2sc](https://github.com/denisgav/v2sc) - vhdl to systemc\n* [veelox](https://github.com/martinda/veelox) - Java+ANTLR,  An experiment in SystemVerilog Preprocessing\n* [verilog-parser](https://github.com/ben-marshall/verilog-parser) - A Flex/Bison Parser for the IEEE 1364-2001 Verilog Standard.\n* [vbpp](https://github.com/balanx/vbpp) - C, Verilog PreProcessor\n* [tree-sitter-verilog](https://github.com/tree-sitter/tree-sitter-verilog) - JS, Verilog grammar for tree-sitter\n* [Verilog-Perl](https://metacpan.org/pod/Verilog-Perl)\n* [vpp.pl](https://www.beyond-circuits.com/wordpress/vpp-pl-man-page/) - verilog preprocessor with integrated Perl\n* [sv2v](https://github.com/zachjs/sv2v)- Haskell, SystemVerilog to Verilog\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchipsalliance%2Fsurelog","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fchipsalliance%2Fsurelog","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchipsalliance%2Fsurelog/lists"}