Verilator - Veripool

1 Verilator Release Wilson Snyder 2022-01-19. GETTING STARTED. 1 Overview 1. 2 Examples 2. Example C++ Execution .. 2. Example SystemC Execution .. 3. Examples in the Distribution .. 4. 3 Installation 6. Package Manager Quick Install .. 6. Git Quick Install .. 6. Detailed Build Instructions .. 7. Verilator Build Docker Container .. 10. Verilator Executable Docker Container .. 11. 4 Verilating 13. C++ and SystemC Generation .. 13. Hierarchical Verilation .. 14. Cross Compilation .. 15. Multithreading .. 15. GNU Make .. 17. CMake .. 17. 5 Connecting to Verilated Models 20. Structure of the Verilated Model .. 20. Connecting to C++ .. 21. Connecting to SystemC .. 22. Direct Programming Interface (DPI) .. 22. Verification Procedural Interface (VPI) .. 25. Wrappers and Model Evaluation Loop .. 26. Verilated and VerilatedContext .. 27. 6 Simulating (Verilated-Model Runtime) 28. Benchmarking & Optimization .. 28. Coverage Analysis.

2 29. Code Profiling .. 31. Thread Profiling .. 31. Profiling ccache efficiency .. 33. Save/Restore .. 33. Profile-Guided Optimization .. 33. 7 Contributing and Reporting Bugs 36. i Announcements .. 36. Reporting Bugs .. 36. Contributing to Verilator .. 37. 8 FAQ/Frequently Asked Questions 39. Questions .. 39. 9 Input Languages 47. language Standard Support .. 47. language Limitations .. 48. language Keyword Limitations .. 52. 10 language Extensions 54. 11 Executable and Argument Reference 61. Verilator Arguments .. 61. Configuration Files .. 80. verilator_coverage .. 83. verilator_gantt .. 85. verilator_profcfunc .. 86. Simulation Runtime Arguments .. 87. 12 Errors and Warnings 89. Disabling Warnings .. 89. Error And Warning Format .. 89. List Of Warnings .. 90. 13 Files 108. Files in the Git Tree .. 108. Files Read/Written .. 108. 14 Environment 111. 15 Deprecations 113. 16 Contributors and Origins 114.

3 Authors .. 114. Contributors .. 114. Historical Origins .. 115. 17 Revision History 117. Revision History and Change Log .. 117. 18 Copyright 194. 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.

4 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.

5 1364, released in 1995, 2001, and 2005. The Verilator documentation uses the shorthand IEEE 1394-2005 to refer to the 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 IEEE 1800-2017 to refer to the 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 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_ 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.

6 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 > <<'EOF'. module our;. initial begin $display("Hello World"); $finish; end endmodule EOF. cat > <<'EOF'. #include " ". #include " ". 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 (continued from previous page). return 0;. }. EOF. Now we run Verilator on our little example.

7 Verilator -Wall --cc --exe --build Breaking this command down: 1. -Wall so Verilator has stronger lint warnings enabled. 2. --cc to get C++ output (versus SystemC or only linting). 3. --exe, along with our 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, 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 - :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.

8 To aid this Verilator can create a makefile dependency file. For examples that do this see the examples directory in the distribution. 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 , 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 SystemC wrapper file: Example SystemC Execution 3.

9 Verilator , Release mkdir test_our_sc cd test_our_sc cat > <<'EOF'. module our (clk);. input clk; // Clock is required to get initial activation always @(posedge clk). begin $display("Hello World"); $finish; end endmodule EOF. cat > <<'EOF'. #include " ". int sc_main(int argc, char** argv) {. Verilated::commandArgs(argc, argv);. sc_clock clk{"clk", 10, SC_NS, , 3, SC_NS, true};. Vour* top = new Vour{"top"};. top->clk(clk);. while (!Verilated::gotFinish()) { sc_start(1, SC_NS); }. delete top;. return 0;. }. EOF. Now we run Verilator on our little example: Verilator -Wall --sc --exe This example does not use build, therefore we need to explicitly compile it: make -j -C obj_dir -f Vour And now we run it: obj_dir/Vour And we get, after the SystemC banner, the same output as the C++ example: SystemC Hello World - :4: 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.

10 For examples that do this see the examples directory in the distribution. Examples in the Distribution See the examples/ directory that is part of the distribution, and is installed (in a OS-specific place, often in /usr/local/share/ Verilator /examples). These examples include: examples/make_hello_c Example GNU-make simple Verilog->C++ conversion examples/make_hello_sc Example GNU-make simple Verilog->SystemC conversion examples/make_tracing_c Example GNU-make Verilog->C++ with tracing Examples in the Distribution 4. Verilator , Release examples/make_tracing_sc Example GNU-make Verilog->SystemC with tracing examples/make_protect_lib Example using protect-lib examples/cmake_hello_c Example building make_hello_c with CMake examples/cmake_hello_sc Example building make_hello_sc with CMake examples/cmake_tracing_c Example building make_tracing_c with CMake examples/cmake_tracing_sc Example building make_tracing_sc with CMake examples/cmake_protect_lib Example building make_protect_lib with CMake To run an example copy the example to a new directory and run it.