Calling back into the testbench

The call goes out and comes back in

An import lets SystemVerilog call C. An export does the reverse: export "DPI-C" function sv_accept; makes the SystemVerilog function sv_accept callable from C under its plain name. Verilator writes its prototype into Vtb__Dpi.h next to the imports, so the bridge calls it like any C function. In the example, the testbench calls c_visit(3), C calls sv_accept(3), the counter grows, and both calls return in turn.

The whole chain is synchronous. c_visit does not return until sv_accept has, and the initial block that called visit is waiting the whole time. A call back into SystemVerilog is a plain function call that happens to cross a language.

Context: which instance the export belongs to

The example has two instances of acceptor, and each has its own accepted. When u1.visit(10) calls c_visit, the export must land in u1, and it does: the import is declared context, so the simulator keeps the calling scope with the call. svGetScope returns it, and the example prints that name from C. An import without context has no scope: the standard forbids it to call an export, and Verilator hands svGetScope a null with a warning.

A bridge may also pick an instance itself. svSetScope(s) makes s the current scope for the exports that follow; use a scope obtained from svGetScopeFromName("tb.u1") or saved earlier from svGetScope. Restore the previous scope afterwards, so the caller's own callbacks keep going to the right place.

extern "C" int c_visit_other(int value) {
  const svScope mine = svGetScope();              // remember who called
  svSetScope(svGetScopeFromName("tb.u1"));        // talk to u1 for a moment
  const int r = sv_accept(value);
  svSetScope(mine);                               // and put the caller back
  return r;
}

Time belongs to the simulator

Every function in this chain returns without advancing simulation time, the imports and the export alike. A sleep or a busy loop in C holds the simulator's thread: wall time passes, the clock stays still, and every other process waits. That is the hook's frozen waveform.

When C needs to wait for a clock edge, the wait has to happen in SystemVerilog. The DPI way is an exported task that waits, called from an import declared as a context task; the task carries the delay, C only asks for it. The example keeps to functions. A simpler design often wins: let C return a prediction, and let the testbench decide when to compare it, as the UVM scoreboards in U9 do.

Try it

Run it as it is and read the three lines C prints: the scope changes with the instance that called. Then add a third visit of -2 on u0 and check that both the return value and u0.accepted show 5.

Then remove the word context from the import in acceptor and run again. The build still succeeds, but at run time Verilator warns that the import is missing context, svGetScope returns null, c_visit returns -1, and the first assertion stops the run.

#include "Vtb__Dpi.h"
#include "svdpi.h"
#include <cstdint>
#include <climits>
#include <cstring>
#include <cstdio>
// context import: the simulator keeps the caller's scope available to this function.
extern "C" int c_visit(int value) {
  const svScope caller = svGetScope();          // the instance whose visit() called us
  if (!caller) return -1;
  printf("c_visit(%d) from %s\n", value, svGetNameFromScope(caller));
  return sv_accept(value);                      // runs in that instance, returns before we do
}

Check yourself

`timescale 1ns/1ps
module tb;
  import "DPI-C" context function int c_visit(input int value);
  import "DPI-C" context function int c_visit_twice(input int value);
  export "DPI-C" function sv_accept;
  int accepted = 0;
  function int sv_accept(input int value);
    accepted += value;
    return accepted;
  endfunction
  int r1, r2;
  initial begin
    r1 = c_visit_twice(3);
    r2 = c_visit(1);
    $display("%0d %0d", r1, r2);
    $finish;
  end
endmodule

#include "Vtb__Dpi.h"
#include "svdpi.h"
#include <cstdint>
#include <climits>
#include <cstring>
extern "C" int c_visit(int value) { return sv_accept(value); }
extern "C" int c_visit_twice(int value) {
  sv_accept(value);              // the first call back has already run when the next line starts
  return sv_accept(value);
}

r = c_visit(3); @(posedge clk);

r = c_visit_after_pause(3);

@(posedge clk); r = c_visit(3);

#5; r = c_visit(3);

#include "Vtb__Dpi.h"
#include "svdpi.h"
#include <cstdint>
#include <climits>
#include <cstring>
#include <unistd.h>
extern "C" int c_visit(int value) { return sv_accept(value); }
// "Give the design time": sleeps for two milliseconds of wall time, then calls back.
extern "C" int c_visit_after_pause(int value) { usleep(2000); return sv_accept(value); }