Verilator Release 4.213 Wilson Snyder 2021-09-27 GETTING STARTED 1 Overview 1 2 Examples 2 2.1 Example C++ Execution.........................................2 2.2 Example SystemC Execution......................................3 2.3 Examples in the Distribution.......................................4 3 Installation 6 3.1 Package Manager Quick Install.....................................6 3.2 Git Quick Install.............................................6 3.3 Detailed Build Instructions........................................7 3.4 Verilator Build Docker Container.................................... 10 3.5 Verilator Executable Docker Container................................. 11 4 Verilating 13 4.1 C++ and SystemC Generation...................................... 13 4.2 Hierarchical Verilation.......................................... 14 4.3 Cross Compilation............................................ 15 4.4 Multithreading.............................................. 15 4.5 GNU Make................................................ 17 4.6 CMake.................................................. 17 5 Connecting to Verilated Models 20 5.1 Structure of the Verilated Model..................................... 20 5.2 Connecting to C++............................................ 21 5.3 Connecting to SystemC......................................... 22 5.4 Direct Programming Interface (DPI)................................... 22 5.5 Verification Procedural Interface (VPI)................................. 25 5.6 Wrappers and Model Evaluation Loop.................................. 26 5.7 Verilated and VerilatedContext...................................... 27 6 Simulating (Verilated-Model Runtime) 28 6.1 Benchmarking & Optimization..................................... 28 6.2 Coverage Analysis............................................ 29 6.3 Code Profiling.............................................. 31 6.4 Thread Profiling............................................. 31 6.5 Profiling ccache efficiency........................................ 33 6.6 Save/Restore............................................... 33 6.7 Profile-Guided Optimization....................................... 33 7 Contributing and Reporting Bugs 36 i 7.1 Announcements............................................. 36 7.2 Reporting Bugs.............................................. 36 7.3 Contributing to Verilator......................................... 37 8 FAQ/Frequently Asked Questions 39 8.1 Questions................................................. 39 9 Input Languages 47 9.1 Language Standard Support....................................... 47 9.2 Language Limitations.......................................... 48 9.3 Language Keyword Limitations..................................... 52 10 Language Extensions 54 11 Executable and Argument Reference 60 11.1 verilator Arguments........................................... 60 11.2 Configuration Files............................................ 79 11.3 verilator_coverage............................................ 82 11.4 verilator_gantt.............................................. 83 11.5 verilator_profcfunc............................................ 85 11.6 Simulation Runtime Arguments..................................... 85 12 Errors and Warnings 87 12.1 Disabling Warnings........................................... 87 12.2 Error And Warning Format........................................ 87 12.3 List Of Warnings............................................. 88 13 Files 106 13.1 Files in the Git Tree........................................... 106 13.2 Files Read/Written............................................ 106 14 Environment 109 15 Deprecations 111 16 Contributors and Origins 112 16.1 Authors.................................................. 112 16.2 Contributors............................................... 112 16.3 Historical Origins............................................ 113 17 Revision History 115 17.1 Revision History and Change Log.................................... 115 18 Copyright 190 ii CHAPTER ONE OVERVIEW Welcome to Verilator! The Verilator package converts Verilog1 and SystemVerilog2 hardware description language (HDL) designs into a C++ or SystemC model that after compiling can be executed. Verilator is not a traditional simulator, but a compiler. Verilator is typically used as follows: 1. The verilator executable is invoked with parameters similar to GCC, or other simulators such as Cadence Verilog-XL/NC-Verilog, or Synopsys VCS. Verilator reads the specified SystemVerilog code, lints it, optionally adds coverage and waveform tracing support, and compiles the design into a source level multithreaded C++ or SystemC “model”. The resulting model’s C++ or SystemC code is output as .cpp and .h files. This is referred to as “Verilating” and the process is “to Verilate”; the output is a “Verilated” model. 2. For simulation, a small user written C++ wrapper file is required, the “wrapper”. This wrapper defines the C++ standard function “main()” which instantiates the Verilated model as a C++/SystemC object. 3. The user C++ wrapper, the files created by Verilator, a “runtime library” provided by Verilator, and if applicable SystemC libraries are then compiled using a C++ compiler to create a simulation executable. 4. The resulting executable will perform the actual simulation, during “simulation runtime”. 5. If appropriately enabled, the executable may also generate waveform traces of the design that may be viewed. It may also create coverage analysis data for post-analysis. The best place to get started is to try the Examples. 1 Verilog is defined by the Institute of Electrical and Electronics Engineers (IEEE) Standard for Verilog Hardware Description Language, Std. 1364, released in 1995, 2001, and 2005. The Verilator documentation uses the shorthand e.g. “IEEE 1394-2005” to refer to the e.g. 2005 version of this standard. 2 SystemVerilog is defined by the Institute of Electrical and Electronics Engineers (IEEE) Standard for SystemVerilog - Unified Hardware Design, Specification, and Verification Language, Standard 1800, released in 2005, 2009, 2012, and 2017. The Verilator documentation uses the shorthand e.g. “IEEE 1800-2017” to refer to the e.g. 2017 version of this standard. 1 CHAPTER TWO EXAMPLES This section covers the following examples: • Example C++ Execution • Example SystemC Execution • Examples in the Distribution 2.1 Example C++ Execution We’ll compile this example into C++. For an extended and commented version of what this C++ code is doing, see examples/make_tracing_c/sim_main.cpp in the distribution. First you need Verilator installed, see Installation. In brief, if you installed Verilator using the package manager of your operating system, or did a make install to place Verilator into your default path, you do not need anything special in your environment, and should not have VERILATOR_ROOT set. However, if you installed Verilator from sources and want to run Verilator out of where you compiled Verilator, you need to point to the kit: # See above; don't do this if using an OS-distributed Verilator export VERILATOR_ROOT=/path/to/where/verilator/was/installed export PATH=$VERILATOR_ROOT/bin:$PATH Now, let’s create an example Verilog, and C++ wrapper file: mkdir test_our cd test_our cat >our.v <<'EOF' module our; initial begin $display("Hello World"); $finish; end endmodule EOF cat >sim_main.cpp <<'EOF' #include "Vour.h" #include "verilated.h" int main(int argc, char** argv, char** env) { VerilatedContext* contextp = new VerilatedContext; contextp->commandArgs(argc, argv); Vour* top = new Vour{contextp}; while (!contextp->gotFinish()) { top->eval(); } delete top; delete contextp; (continues on next page) 2 Verilator, Release 4.213 (continued from previous page) return 0; } EOF Now we run Verilator on our little example. verilator -Wall --cc --exe --build sim_main.cpp our.v Breaking this command down: 1. -Wall so Verilator has stronger lint warnings enabled. 2. --cc to get C++ output (versus e.g. SystemC or only linting). 3. --exe, along with our sim_main.cpp wrapper file, so the build will create an executable instead of only a library. 4. --build so Verilator will call make itself. This is we don’t need to manually call make as a separate step. You can also write your own compile rules, and run make yourself as we show in Example SystemC Execution.) 5. An finally, our.v which is our SystemVerilog design file. Once Verilator completes we can see the generated C++ code under the obj_dir directory. ls -l obj_dir (See Files Read/Written for descriptions of some of the files that were created.) And now we run it: obj_dir/Vour And we get as output: Hello World - our.v:2: Verilog $finish Really, you’re better off using a Makefile to run the steps for you so when your source changes it will automatically run all of the appropriate steps. To aid this Verilator can create a makefile dependency file. For examples that do this see the examples directory in the distribution. 2.2 Example SystemC Execution This is an example similar to the Example C++ Execution, but using SystemC. We’ll also explicitly run make. First you need Verilator installed, see Installation. In brief, if you installed Verilator using the package manager of your operating system, or did a make install to place Verilator into your default path, you do not need anything special in your environment, and should not have VERILATOR_ROOT set. However, if you installed Verilator from sources and want to run Verilator out of where you compiled Verilator,