Major Tools
Other Tools
General Info

Verilator Frequently Asked Questions (FAQ)

Can I contribute code?

Please do contribute patches! Just file an issue asking for a merge, or ask on the forums if looking for something to help on.

How commonly is Verilator used?

Verilator is used by many of the largest silicon design companies, and all the way down to college projects. Verilator is a "big 4" simulator, meaning one of the 4 main SystemVerilog simulators available, namely the commercial products Synopsys' VCS (tm), Mentor's ModelSim (tm), Cadence Incisive/NC-Verilog/NC-Sim, and the open-source Verilator. The three commercial choices are commonly collectively called the "big 3" simulators.

Does it run under Windows?

Yes, using Cygwin. Verilated output should also compile under Microsoft Visual C++ Version 7 or newer.

Can you provide binaries?

Verilator is available as a package on many distributions; this is done by porters and may slightly lag the primary distribution. If there isn't a binary build for your distribution, how about you set one up? Please contact the authors for assistance.

Note people sometimes request binaries when they are having problems with their C++ compiler. Alas, binaries won't help this, as in the end a fully working C++ compiler is required to compile the output of Verilator.

How can Verilator be faster than (name-the-commercial-big-3-simulator)?

Generally, the implied part of the question is ``... with all of their manpower they can put into it.''

Most commercial simulators have to be Verilog compliant, meaning event driven. This prevents them from being able to reorder blocks and make netlist-style optimizations, which are where most of the gains come from.

Non-compliance shouldn't be scary. Your synthesis program isn't compliant, so your simulator shouldn't have to be -- and Verilator is closer to the synthesis interpretation, so this is a good thing for getting working silicon.

Does code that comes out of Verilator remain under my own license?

Yes, it's just like using GCC on your programs; this is why Verilator uses the "GNU Lesser Public License Version 3" instead of the more typical "GNU Public License". See the licenses for details, but in brief, if you change Verilator itself or the header files Verilator includes, you must make the source code available under the GNU Lesser Public License. However, Verilator output (the Verilated code) only "include"s the licensed files, and so you are NOT required to release any output from Verilator.

You also have the option of using the Perl Artistic License, which again does not require you release your Verilog or generated code, and also allows you to modify Verilator for internal use without distributing the modified version. But please contribute back to the community!

One limit is that you cannot under either license release a commercial Verilog simulation product incorporating Verilator without making the source code available.

As is standard with Open Source, contributions back to Verilator will be placed under the Verilator copyright and LGPL/Artistic license. Small test cases will be released into the public domain so they can be used anywhere, large tests under the LGPL/Artistic, unless requested otherwise.

Why is running Verilator (to create a model) so slow?

Verilator needs more memory than the resulting simulator will require, as Verilator creates internally all of the state of the resulting simulator in order to optimize it. If it takes more than a minute or so (and you're not using --debug), see if your machine is paging; most likely you need to run it on a machine with more memory. Verilator is a full 64 bit application and may use more than 4GB, but about 1GB is the maximum typically needed.

How do I generate waveforms (traces) in C++ or SystemC?

See the next question for tracing in SystemPerl mode.

Add the --trace switch to Verilator, and make sure the SystemPerl package is installed. SystemC itself does not need to be installed for C++ only tracing. You do not even need to compile SystemPerl; you may simply untar the SystemPerl kit and point the SYSTEMPERL environment variable to the untarred directory.

In your top level C code, call Verilated::traceEverOn(true). Then create a SpTraceVcdC object, and in your main loop call ``trace_object->dump(time)'' every time step, and finally call ``trace_object->close()''. For an example, see the example directory in the distribution.

You also need to compile SpTraceVcdC.cpp and add it to your link. This is done for you if using the Verilator --exe flag.

How do I view waveforms (traces)?

Verilator makes standard VCD (Value Change Dump) files. They are viewable with the public domain Dinotrace or GtkWave programs, or any of the many commercial offerings. You can also generate FST files for GTKWave.

Where is the translate_off command? (How do I ignore a construct?)

Translate on/off pragmas are generally a bad idea, as it's easy to have mismatched pairs, and you can't see what another tool sees by just preprocessing the code. Instead, use the preprocessor; Verilator defines the ``verilator'' define for you, so just wrap the code in a ifndef region:

`ifndef verilator

Why do I get ``unexpected `do''' or ``unexpected `bit''' errors?

Do, bit, ref, return, and other words are now SystemVerilog keywords. You should change your code to not use them to insure it works with newer tools. Alternatively, surround them by the Verilog 2005/SystemVerilog begin_keywords pragma to indicate Verilog 2001 code.

`begin_keywords "1364-2001" 
  integer bit; initial bit = 1;

If you want the whole file to be parsed as Verilog 2001, just create a file with

`begin_keywords "1364-2001"

and add it before other Verilog files on the command line. (Note this will also change the default for --prefix, so if you're not using --prefix, you will now need to.)

How do I prevent my assertions from firing during reset?

Call Verilated::assertOn(false) before you first call the model, then turn it back on after reset. It defaults to true. When false, all assertions controlled by --assert are disabled.

Why do I get ``undefined reference to `sc_time_stamp()'''?

In C++ (non SystemC) code you need to define this function so that the simulator knows the current time. See the ``CONNECTING TO C++'' examples in the documentation.

Why do I get ``undefined reference to `VL_RAND_RESET_I' or `Verilated::...'''?

You need to link your compiled Verilated code against the verilated.cpp file found in the include directory of the Verilator kit. If you use --exe this is done for you.

Is the PLI supported?

Mostly no.

More specifically, the common PLI-ish calls $display, $finish, $stop, $time, $write are converted to C++ equivalents. If you want something more complex, since Verilator emits standard C++ code, you can simply write your own C++ routines that can access and modify signal values without needing any PLI interface code, and call it with $c(``{any_c++_statement}'').

To interface new routines, Verilator does support DPI, which is generally a faster and more modern alternative to VPI.

How do I make a Verilog module that contain a C++ object?

You need to add the object to the structure that Verilator creates, then use $c to call a method inside your object. The test_regress/t/t_extend_class files show an example of how to do this.

How do I get faster GCC compile times?

Verilator can generate a lot of code that needs compiling, so GCC can become a bottleneck. Two ways to cheat are to compile on parallel machines and avoid compilations altogether. See the --output-split option, and the web for the ccache package. You really want to be using ccache (or a similar alternative).

Why do so many files need to recompile when I add a signal?

Adding a new signal requires the symbol table to be recompiled. Verilator uses one large symbol table, as that results in 2-3 less assembly instructions for each signal access. This makes the execution time 10-15% faster, but can result in more compilations when something changes.

How do I access signals in C?

First, the best option is not to, instead call a DPI function, as this will better optimize.

Alternatively, declare the signals you will be accessing with a /*verilator public*/ comment before the closing semicolon. Then scope into the C++ class to read the value of the signal, as you would any other member variable.

Signals are the smallest of 8 bit chars, 16 bit shorts, 32 bit longs, or 64 bit long longs that fits the width of the signal. Generally, you can use just uint32_t's for 1 to 32 bits, or uint64_t for 1 to 64 bits, and the compiler will properly up-convert smaller entities.

Signals wider than 64 bits are stored as an array of 32-bit uint32_t's. Thus to read bits 31:0, access signal0, and for bits 63:32, access signal1. Unused bits (for example bit numbers 65-96 of a 65 bit vector) will always be zero. if you change the value you must make sure to pack zeros in the unused bits or core-dumps may result. (Because Verilator strips array bound checks where it believes them to be unnecessary.)

In the SYSTEMC example above, if you had in our.v:

input clk /*verilator public*/;

From the sc_main.cpp file, you'd then:

#include "Vour.h" 
#include "Vour_our.h" 
cout << "clock is " << top->v.clk << endl;

In this example, clk is a bool you can read or set as any other variable. The value of normal signals may be set, though clocks shouldn't be changed by your code or you'll get strange results.

Should a module be in Verilog or SystemC?

Sometimes there is a block that just interconnects cells, and have a choice as to if you write it in Verilog or SystemC. Everything else being equal, best performance is when Verilator sees all of the design. So, look at the hierarchy of your design, labeling cells as to if they are SystemC or Verilog. Then:

A module with only SystemC cells below must be SystemC.

A module with a mix of Verilog and SystemC cells below must be SystemC. (As Verilator cannot connect to lower-level SystemC cells.)

A module with only Verilog cells below can be either, but for best performance should be Verilog. (The exception is if you have a design that is instantiated many times; in this case Verilating one of the lower modules and instantiating that Verilated cells multiple times into a SystemC module may be faster.)