verilator

Simulate and lint Verilog/SystemVerilog designs

TLDR

Build a specific C project in the current directory

$ verilator --binary --build-jobs 0 -Wall [path/to/source.v]

Create a C++ executable in a specific folder

$ verilator --cc --exe --build --build-jobs 0 -Wall [path/to/source.cpp] [path/to/output.v]

Perform linting over a code in the current directory

$ verilator --lint-only -Wall

Create XML output about the design (files, modules, instance hierarchy, logic and data types) to feed into other tools

$ verilator --xml-output -Wall [path/to/output.xml]

SYNOPSIS

verilator [options] [files.v] [...]

--cc
    Generate C++ output code. This is the most common target language.

--sc
    Generate SystemC output code. Useful for integrating with SystemC verification environments.

--exe
    Link in a main_vlg.mk file and compile the generated code into an executable. Requires a C++ `main` function (e.g., `sim_main.cpp`) to be linked.

--build
    After Verilator completes code generation, execute `make` on the generated files to compile the executable. This simplifies the build process.

-o
    Name of the generated executable (when used with --exe).

-y

    Add directory to search path for Verilog includes/modules. Can be specified multiple times.

-I
    Equivalent to -y ; adds a directory to the search path for Verilog files.

--trace
    Enable waveform tracing (VCD or FST format). Verilator generates code to dump signals, which can then be viewed with tools like GTKWave.

--trace-fst
    Specifically enables FST (Fast Signal Trace) format tracing, which is often more efficient than VCD for large designs.

--trace-max-array
    Limit the depth of arrays that will be traced. Useful to reduce trace file size.

--lint-only
    Only perform linting checks on the Verilog code; do not generate C++/SystemC output. Useful for static code analysis.

--Wno-
    Disable a specific warning message (e.g., --Wno-UNOPTFLAT).

--Werror-
    Treat a specific warning as an error (e.g., --Werror-WIDTH).

--top
    Specify the top-level module in the design. If not specified, Verilator attempts to infer it.

--Mdir
    Set the directory where generated C++/SystemC files and Makefiles will be placed. Defaults to `obj_dir`.

-CFLAGS ""
    Add custom flags to the C++ compilation step (e.g., for optimization -O3 or debugging -g).

-LDFLAGS ""
    Add custom flags to the C++ linking step (e.g., for linking external libraries).

DESCRIPTION

Verilator is an open-source tool that converts Verilog/SystemVerilog HDL code into high-performance, cycle-accurate C++ or SystemC models. It compiles your HDL design directly into C++ (or SystemC), which is then compiled into an executable binary using a standard C++ compiler like GCC or Clang. This approach allows for very fast simulation speeds, often significantly quicker than traditional event-driven simulators, making it ideal for large-scale digital designs and CPU verification.

Beyond simulation, Verilator also functions as a robust linting tool, providing warnings and errors for common HDL design issues, Verilog specification violations, and potential synthesis problems, even if not generating executable code. It is widely used in hardware design and verification flows, especially for unit-level testing, co-simulation with C++ testbenches, and integrating hardware models into software development environments.

CAVEATS

Verilator is a cycle-accurate simulator, not an event-driven one, which means it excels at fast, cycle-by-cycle execution but may not fully support all intricate timing models or SystemVerilog constructs (e.g., UVM, `bind`, `covergroup` assertions for formal verification) found in commercial simulators. Its focus is on synthesizable and behavioral RTL. Debugging happens at the C++/SystemC level, which can require different skills than typical HDL waveform debugging.

INTEGRATION WITH C++/SYSTEMC TESTBENCHES

Verilator's primary strength lies in its ability to integrate Verilog/SystemVerilog designs directly into a C++ or SystemC environment. This allows designers to write complex testbenches, verification components, and co-simulation scenarios using familiar programming languages, leveraging existing C++ libraries and debugging tools.

LINTING CAPABILITIES

Even without generating simulation models, Verilator serves as an excellent linting tool. It can identify common design errors, potential synthesis mismatches, uninitialized signals, combinatorial loops, and other issues that might lead to unexpected hardware behavior or difficult-to-debug problems in later stages of the design flow. This makes it valuable for early-stage design analysis.

HISTORY

Developed by Wilson Snyder, Verilator emerged as an open-source solution to address the need for high-performance simulation of Verilog designs. Its initial development focused on achieving speeds comparable to or exceeding proprietary simulators for cycle-accurate verification. Over the years, it has continuously evolved to support more SystemVerilog features and improve compilation efficiency, becoming a staple in various academic and industrial hardware verification workflows, particularly for FPGA and ASIC prototyping and pre-silicon validation.