Connecting to Verilated Models

Connecting to C++

Verilator creates a prefix.h and prefix.cpp file for the top level module, together with additional .h and .cpp files for internals. See the examples directory in the kit for examples. See Files Read/Written for information on all the files it writes.

After the model is created, there will be a prefix.mk file that may be used with Make to produce a prefix__ALL.a file with all required objects in it.

The user must write a C++ wrapper and main loop for the simulation, to link with the Verilated model. Here is a simple example:

#include <verilated.h>          // Defines common routines
#include <iostream>             // Need std::cout
#include "Vtop.h"               // From Verilating "top.v"

Vtop *top;                      // Instantiation of module

vluint64_t main_time = 0;       // Current simulation time
// This is a 64-bit integer to reduce wrap over issues and
// allow modulus.  This is in units of the timeprecision
// used in Verilog (or from --timescale-override)

double sc_time_stamp() {        // Called by $time in Verilog
    return main_time;           // converts to double, to match
                                // what SystemC does
}

int main(int argc, char** argv) {
    Verilated::commandArgs(argc, argv);   // Remember args

    top = new Vtop;             // Create instance

    top->reset_l = 0;           // Set some inputs

    while (!Verilated::gotFinish()) {
        if (main_time > 10) {
            top->reset_l = 1;   // Deassert reset
        }
        if ((main_time % 10) == 1) {
            top->clk = 1;       // Toggle clock
        }
        if ((main_time % 10) == 6) {
            top->clk = 0;
        }
        top->eval();            // Evaluate model
        cout << top->out << endl;       // Read a output
        main_time++;            // Time passes...
    }

    top->final();               // Done simulating
    //    // (Though this example doesn't get here)
    delete top;
}

Note signals are read and written as member variables of the model. You call the eval() method to evaluate the model. When the simulation is complete call the final() method to execute any SystemVerilog final blocks, and complete any assertions. See Wrappers and Model Evaluation Loop.

Connecting to SystemC

Verilator will convert the top level module to a SC_MODULE. This module will attach directly into a SystemC netlist as an instantiation.

The SC_MODULE gets the same pinout as the Verilog module, with the following type conversions: Pins of a single bit become bool. Pins 2-32 bits wide become uint32_t’s. Pins 33-64 bits wide become sc_bv’s or vluint64_t’s depending on the --no-pins64 option. Wider pins become sc_bv’s. (Uints simulate the fastest so are used where possible.)

Lower modules are not pure SystemC code. This is a feature, as using the SystemC pin interconnect scheme everywhere would reduce performance by an order of magnitude.

Direct Programming Interface (DPI)

Verilator supports SystemVerilog Direct Programming Interface import and export statements. Only the SystemVerilog form (“DPI-C”) is supported, not the original Synopsys-only DPI.

DPI Example

In the SYSTEMC example above, if you wanted to import C++ functions into Verilog, put in our.v:

import "DPI-C" function int add (input int a, input int b);

initial begin
   $display("%x + %x = %x", 1, 2, add(1,2));
endtask

Then after Verilating, Verilator will create a file Vour__Dpi.h with the prototype to call this function:

extern int add(int a, int b);

From the sc_main.cpp file (or another .cpp file passed to the Verilator command line, or the link), you’d then:

#include "svdpi.h"
#include "Vour__Dpi.h"
int add(int a, int b) { return a+b; }

DPI System Task/Functions

Verilator extends the DPI format to allow using the same scheme to efficiently add system functions. Simply use a dollar-sign prefixed system function name for the import, but note it must be escaped.

export "DPI-C" function integer \$myRand;

initial $display("myRand=%d", $myRand());

Going the other direction, you can export Verilog tasks so they can be called from C++:

export "DPI-C" task publicSetBool;

task publicSetBool;
   input bit in_bool;
   var_bool = in_bool;
endtask

Then after Verilating, Verilator will create a file Vour__Dpi.h with the prototype to call this function:

extern void publicSetBool(svBit in_bool);

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

#include "Vour__Dpi.h"
publicSetBool(value);

Or, alternatively, call the function under the design class. This isn’t DPI compatible but is easier to read and better supports multiple designs.

#include "Vour__Dpi.h"
Vour::publicSetBool(value);
// or top->publicSetBool(value);

Note that if the DPI task or function accesses any register or net within the RTL, it will require a scope to be set. This can be done using the standard functions within svdpi.h, after the module is instantiated, but before the task(s) and/or function(s) are called.

For example, if the top level module is instantiated with the name “dut” and the name references within tasks are all hierarchical (dotted) names with respect to that top level module, then the scope could be set with

#include "svdpi.h"
...
svSetScope(svGetScopeFromName("TOP.dut"));

(Remember that Verilator adds a “TOP” to the top of the module hierarchy.)

Scope can also be set from within a DPI imported C function that has been called from Verilog by querying the scope of that function. See the sections on DPI Context Functions and DPI Header Isolation below and the comments within the svdpi.h header for more information.

DPI Imports that access signals

If a DPI import accesses a signal through the VPI Verilator will not be able to know what variables are accessed and may schedule the code inappropriately. Ideally pass the values as inputs/outputs so the VPI is not required. Alternatively a workaround is to use a non-inlined task as a wrapper:

logic din;

// This DPI function will read "din"
import "DPI-C" context function void dpi_that_accesses_din();

always @(...)
   dpi_din_args(din);

task dpi_din_args(input din);
   /* verilator no_inline_task */
   dpi_that_accesses_din();
endtask

DPI Display Functions

Verilator allows writing $display like functions using this syntax:

import "DPI-C" function void
      \$my_display(input string formatted /*verilator sformat*/ );

The /*verilator sformat*/ metacomment indicates that this function accepts a $display like format specifier followed by any number of arguments to satisfy the format.

DPI Context Functions

Verilator supports IEEE DPI Context Functions. Context imports pass the simulator context, including calling scope name, and filename and line number to the C code. For example, in Verilog:

import "DPI-C" context function int dpic_line();
initial $display("This is line %d, again, line %d\n", `line, dpic_line());

This will call C++ code which may then use the svGet* functions to read information, in this case the line number of the Verilog statement that invoked the dpic_line function:

int dpic_line() {
    // Get a scope:  svScope scope = svGetScope();

    const char* scopenamep = svGetNameFromScope(scope);
    assert(scopenamep);

    const char* filenamep = "";
    int lineno = 0;
    if (svGetCallerInfo(&filenamep, &lineno)) {
        printf("dpic_line called from scope %s on line %d\n",
           scopenamep, lineno);
        return lineno;
    } else {
        return 0;
    }
}

See the IEEE Standard for more information.

DPI Header Isolation

Verilator places the IEEE standard header files such as svdpi.h into a separate include directory, vltstd (VeriLaTor STandarD). When compiling most applications $VERILATOR_ROOT/include/vltstd would be in the include path along with the normal $VERILATOR_ROOT/include. However, when compiling Verilated models into other simulators which have their own svdpi.h and similar standard files with different contents, the vltstd directory should not be included to prevent picking up incompatible definitions.

Public Functions

Instead of DPI exporting, there’s also Verilator public functions, which are slightly faster, but less compatible.

Verification Procedural Interface (VPI)

Verilator supports a limited subset of the VPI. This subset allows inspection, examination, value change callbacks, and depositing of values to public signals only.

VPI is enabled with the Verilator --vpi option.

To access signals via the VPI, Verilator must be told exactly which signals are to be accessed. This is done using the Verilator public pragmas documented below.

Verilator has an important difference from an event based simulator; signal values that are changed by the VPI will not immediately propagate their values, instead the top level header file’s eval() method must be called. Normally this would be part of the normal evaluation (i.e. the next clock edge), not as part of the value change. This makes the performance of VPI routines extremely fast compared to event based simulators, but can confuse some test-benches that expect immediate propagation.

Note the VPI by its specified implementation will always be much slower than accessing the Verilator values by direct reference (structure->module->signame), as the VPI accessors perform lookup in functions at simulation runtime requiring at best hundreds of instructions, while the direct references are evaluated by the compiler and result in only a couple of instructions.

For signal callbacks to work the main loop of the program must call VerilatedVpi::callValueCbs().

VPI Example

In the below example, we have readme marked read-only, and writeme which if written from outside the model will have the same semantics as if it changed on the specified clock edge.

cat >our.v <<'EOF'
  module our (input clk);
     reg readme   /*verilator public_flat_rd*/;
     reg writeme  /*verilator public_flat_rw @(posedge clk) */;
     initial $finish;
  endmodule
EOF

There are many online tutorials and books on the VPI, but an example that accesses the above signal “readme” would be:

cat >sim_main.cpp <<'<<EOF'
  #include "Vour.h"
  #include "verilated.h"
  #include "verilated_vpi.h"  // Required to get definitions

  vluint64_t main_time = 0;   // See comments in first example
  double sc_time_stamp() { return main_time; }

  void read_and_check() {
      vpiHandle vh1 = vpi_handle_by_name((PLI_BYTE8*)"TOP.our.readme", NULL);
      if (!vh1) vl_fatal(__FILE__, __LINE__, "sim_main", "No handle found");
      const char* name = vpi_get_str(vpiName, vh1);
      printf("Module name: %s\n", name);  // Prints "readme"

      s_vpi_value v;
      v.format = vpiIntVal;
      vpi_get_value(vh1, &v);
      printf("Value of v: %d\n", v.value.integer);  // Prints "readme"
  }

  int main(int argc, char** argv, char** env) {
      Verilated::commandArgs(argc, argv);
      Vour* top = new Vour;
      Verilated::internalsDump();  // See scopes to help debug
      while (!Verilated::gotFinish()) {
          top->eval();
          VerilatedVpi::callValueCbs();  // For signal callbacks
          read_and_check();
      }
      delete top;
      return 0;
  }
EOF

Wrappers and Model Evaluation Loop

When using SystemC, evaluation of the Verilated model is managed by the SystemC kernel, and for the most part can be ignored. When using C++, the user must call eval(), or eval_step() and eval_end_step().

1. When there is a single design instantiated at the C++ level that needs to evaluate within a given context, call designp->eval().

2. When there are multiple designs instantiated at the C++ level that need to evaluate within a context, call first_designp->eval_step() then ->eval_step() on all other designs. Then call ->eval_end_step() on the first design then all other designs. If there is only a single design, you would call eval_step() then eval_end_step(); in fact eval() described above is just a wrapper which calls these two functions.

When eval() (or eval_step()) is called Verilator looks for changes in clock signals and evaluates related sequential always blocks, such as computing always_ff @ (posedge…) outputs. Then Verilator evaluates combinatorial logic.

Note combinatorial logic is not computed before sequential always blocks are computed (for speed reasons). Therefore it is best to set any non-clock inputs up with a separate eval() call before changing clocks.

Alternatively, if all always_ff statements use only the posedge of clocks, or all inputs go directly to always_ff statements, as is typical, then you can change non-clock inputs on the negative edge of the input clock, which will be faster as there will be fewer eval() calls.

For more information on evaluation, see docs/internals.rst in the distribution.

Verilated and VerilatedContext

Multiple Verilated models may be part of the same simulation context, that is share a VPI interface, sense of time, and common settings. This common simulation context information is stored in a VerilatedContext structure. If a VerilatedContext is not created prior to creating a model, a default global one is created automatically.

The Verilated:: methods, including the Verilated::commandArgs call shown above, simply call VerilatedContext methods using the default global VerilatedContext. (Technically they operate on the last one used by a given thread.) If you are using multiple simulation contexts you should not use the Verilated:: methods, and instead always use VerilatedContext methods called on the appropriate VerilatedContext object.

For methods available under Verilated and VerilatedContext see include/verilated.h in the distribution.