DPI-C tutorial · Part A · Step 05 · Spear & Tumbush §12.7–12.8

Export and context: when C calls back into SystemVerilog

Up to now C was a leaf: SV called it, it computed, it returned. This step makes the call go both ways. C calls SV functions and tasks through export "DPI-C", and it needs to know which SV instance it is talking to. That is what context and the scope API are for. Verilator implements most of this faithfully. One big piece it rejects outright, and one small piece it gets silently wrong.

Prereqs: 01 (import, the generated Vtop__Dpi.h), 03 (chandle, per-instance state)Book pages: PDF = book + 36 in ch. 12Every number below comes from lab/check.py

§0 · TutorialThe step in one idea

An imported C routine runs somewhere in the SV hierarchy: in the scope where its import declaration sits. As long as C only computes, that place doesn't matter. As soon as C wants to call back into SV (an exported function, a task, VPI), the simulator must know which module instance C stands in, because every instance has its own copy of the exported routine. context is the promise that makes the simulator record that place on every call. The scope API (svGetScope, svSetScope, …) lets C read and change it.

The step follows the book's §12.7–12.8 in order: export syntax, the three import flavors (pure, generic, context), the scope API, exported tasks, and the command-file memory model the book grows across Samples 12.37–12.45. Every sample was rebuilt in the lab on Verilator 5.052. Three results are worth knowing before you start:

• Verilator refuses timing controls inside exported tasks (#, @, even nested in a called task). The book's timed memory model (Sample 12.40) does not compile. The portable alternative is the pull model: SV owns time, C is an iterator.
• A non-context import that calls an export fails fatally when no scope was ever set. When an earlier context call left a scope behind, it silently runs the wrong instance's export (0.6).
• pure did not save a single call in Verilator, and a DPI function in combinational logic ran 11 times for 5 input changes. Call counts are the simulator's business, never yours (0.4).

0.1Two directions across one boundary

Steps 01–04 used one direction: import "DPI-C" makes a C symbol callable from SV. export "DPI-C" is the mirror. It makes an SV function or task callable from C, under a C symbol the simulator generates. The two combine into a round trip. SV calls an imported C routine, which calls an exported SV routine, which may call another import, and so on. Each crossing is a plain C call on the same machine stack. No threads, no messages, no copies of the simulator state.

0.2Your first export (Samples 12.34, 12.35, 12.46)

The export declaration is deliberately bare: export "DPI-C" function name;. There is no return type, no argument list, and not even (). The LRM forbids repeating the signature because it already lives in the SV function declaration, and two copies could drift apart. An optional C name renames it (export "DPI-C" c_name = function sv_name;), exactly like imports in step 01. The C side calls the symbol like any C function. Don't hand-write its prototype: include the generated Vtop__Dpi.h, which lists exports as well as imports.

// lab/scopes.sv: one C routine, two SV scopes (Samples 12.34 + 12.46)
module block;
  import "DPI-C" context function void c_display();
  export "DPI-C" function sv_display;          // no return type, no args, no ()
  function void sv_display();
    $display("LOG sv where=%m");
  endfunction
  initial c_display();
endmodule

module top;
  import "DPI-C" context function void c_display();
  export "DPI-C" function sv_display;          // a second, independent export
  function void sv_display(); $display("LOG sv where=%m"); endfunction
  block b1();
  initial #1 c_display();
endmodule

// lab/scopes.c: printf replaces the book's io_printf (a PLI routine Verilator doesn't have)
#include <stdio.h>
#include "svdpi.h"
#include "Vtop__Dpi.h"     // generated: prototypes for imports AND exports

void c_display(void) {
  const char* file = "?"; int line = 0;
  svGetCallerInfo(&file, &line);                    // SV file:line of the import call
  printf("LOG c scope=%s caller=%s:%d\n", svGetNameFromScope(svGetScope()), file, line);
  fflush(stdout);
  sv_display();            // which one? the export of the CURRENT scope
}

LOG c scope=top.b1 caller=scopes.sv:9
LOG sv where=top.b1.sv_display
LOG c scope=top caller=scopes.sv:19
LOG sv where=top.sv_display

One C symbol sv_display stands for two SV functions, top.sv_display and top.b1.sv_display. The simulator dispatches on the scope that the context import recorded. That is the book's §12.8.5 "meaning of context" in four log lines. The generated header shows the C view:

// build/vl_scopes/Vtop__Dpi.h (excerpt)
    // DPI EXPORTS
    extern void sv_display();
    // DPI IMPORTS
    extern void c_display();

What can be exported: functions and tasks declared in a module, interface, program, package or $unit. Class methods cannot be exported (§12.8.4), because no object exists at elaboration time when the C symbol is bound. 0.12 shows the workaround. In one scope, one export per C name. The same name exported from several scopes is legal: that is exactly the two-instance case above.

Arguments when C calls an export. An export has exactly the C header an import with the same SV signature would have (H.8.2), so the type rules of step 02 apply in reverse: small inputs by value, everything else by pointer. The difference is who allocates: now C is the caller, so C provides the storage for every by-reference argument, in canonical layout (H.8.5). For output bit [39:0] v that is svBitVecVal v[SV_PACKED_DATA_NELEMS(40)]; on the C stack; for output int x, an int. For an output string SV writes a pointer into your const char*: the storage belongs to SV, so copy the text if you need it after the next call (H.8.10).

0.3Three flavors of import: pure, generic, context

Every import makes a promise to the SV compiler about what the C code touches. The promise decides what the optimizer may assume and what bookkeeping the simulator must do on each call (IEEE 1800-2023 §35.5.2–35.5.3; book §12.7):

The book's term "generic" comes from Sutherland (2004). The LRM has no name for the default flavor. Two consequences matter for golden models. First, a reference model that keeps state between calls (a CRC register, a FIR delay line, a scoreboard queue) is not pure, even if each call looks like a function of its inputs. Second, the only things that require context are calling back into SV and asking about scopes. A C model that just computes and logs with printf is generic.

0.4What pure buys in practice (measured)

The LRM allows the compiler to elide or merge pure calls. To see whether Verilator does, the lab declares the same C function twice, once pure and once generic. Each one secretly counts its calls, a side effect a real pure function must not have, so the counter is a probe. The SV code discards one result, computes f(a) + f(a), and calls f(a) in a loop with a loop-invariant argument:

// lab/pure.sv (core)
void'(sq_pure(a));                               // result discarded: may be dropped?
r = sq_pure(a) + sq_pure(a);                     // common subexpression: may be merged?
for (int i = 0; i < 4; i++) r += sq_pure(a);   // loop-invariant: may be hoisted?
// same three lines with sq_gen (no pure)

LOG pure calls=7 r=294
LOG gen calls=7 b=294

Seven SV calls, seven C calls, with or without pure, and also with -O3. Verilator does not use the license in procedural code. Combinational logic is a different story. With assign yp = sq_pure(x) and x changing 5 times, C ran 11 times for both flavors. Verilator evaluates combinational logic as often as its scheduling needs (initial settle, re-evaluation in the same time step), and the count is an implementation detail.

The number of times C runs is not part of the SV semantics, for either flavor. Procedural code: it is whatever the LRM allows (pure: possibly fewer). Continuous assignments and always_comb: whatever the simulator's scheduler does (11 for 5 here). A stateful C model, such as a CRC register or a counter, must be called from procedural code at well-defined events (a clock edge, a transaction), never from an assign.

0.5What context costs (measured)

The book warns that context has "overhead" because the simulator must record the calling scope. The lab measures it with 5 M calls of a trivial C function (x ^ 0x5a), timed in C with clock_gettime, on the Verilator build of the lab (macOS x86_64, Verilator 5.052). The absolute values swing with machine load: a run with other builds in parallel gave 2.3 / 2.2 / 22.6 / 108 ns. The ordering and the context-vs-generic ratio held in every run, and those are what check.py asserts.

For a golden model called once per transaction, none of this matters: a DUT cycle in Verilator costs far more than 10 ns. It starts to matter when a model is called per bit or per sample in a tight loop. That is the "batching" topic of step 06 and step 08, where a call into Python costs far more than any of these (measured there).

0.6Forgetting context: one loud failure, one silent one

The book says that if a generic import calls an export, "the simulator could crash" (§12.7). On Verilator the outcome depends on what ran before, and the dangerous case doesn't crash. lab/noctx.sv has a non-context import call_export() in top that calls the export sv_hello. Two runs:

// lab/noctx.sv (core)
module other;                                     // has its own sv_hello export
  import "DPI-C" context function void touch();   // empty C function
  export "DPI-C" function sv_hello;
  function void sv_hello(); $display("LOG sv hello where=%m"); endfunction
`ifdef STALE initial touch(); `endif                // a context call BEFORE ours
endmodule
module top;
  import "DPI-C" function void call_export();      // BUG: should be context
  export "DPI-C" function sv_hello;
  function void sv_hello(); $display("LOG sv hello where=%m"); endfunction
  other o();
  initial #1 call_export();
endmodule

// run 1: no context call ever happened
%Warning: DPI C Function called by Verilog DPI import with missing 'context' keyword.
LOG c scope=NULL
%Error: unknown:0: Testbench C called 'sv_hello' but scope wasn't set, perhaps due to dpi import
call without 'context', or missing svSetScope. See IEEE 1800-2023 35.5.3.
Aborting...

// run 2 (-DSTALE): other.touch() ran at t=0
LOG c scope=top.o
LOG sv hello where=top.o.sv_hello          // WRONG instance, no warning

The rule is mechanical: if the C body (or anything it calls) calls an export, uses VPI, or calls svGetScope, the import is context. A generic import that calls an export "works" in a small test because some earlier context call happened to leave the right scope. In the full testbench it calls the export of whichever instance ran last.

In run 1 the warning comes from Verilator's runtime when C asks for the scope from a non-context call. In run 2 there is no warning at all. The LRM makes the export call from a non-context import an error, but how loudly a given simulator diagnoses it is tool-dependent. Don't rely on getting a diagnostic.

0.7The scope API (Samples 12.48–12.50)

Six functions manage the scope register; their semantics are in H.9.3 (the prototypes are in svdpi.h, Annex I). Their behavior is undefined outside a DPI context call chain (H.9.3, §35.5.3):

Sample 12.48 saves a scope in one call and jumps back into it in a later one. The lab version has two instances of block, because it exposes a trap the book's single instance hides:

// lab/setscope.c (Sample 12.48, plus restoring the scope)
static svScope my_scope;                         // an opaque pointer: safe to keep
void save_my_scope(void) { my_scope = svGetScope(); }
void c_display(void) {
  printf("LOG c called_from=%s\n", svGetNameFromScope(svGetScope()));
  svScope prev = svSetScope(my_scope);           // returns the previous scope
  printf("LOG c now_in=%s prev=%s\n", svGetNameFromScope(svGetScope()), svGetNameFromScope(prev));
  sv_display();                                  // block's export, not top's
  svSetScope(prev);                              // restore
}

LOG c called_from=top.b2         // b2's initial ran first: save_my_scope() -> b2
LOG c now_in=top.b2 prev=top.b2
LOG sv where=top.b2.sv_display
LOG c called_from=top.b1         // then b1's initial: save_my_scope() -> b1 (overwrites!)
LOG c now_in=top.b1 prev=top.b1
LOG sv where=top.b1.sv_display
LOG c called_from=top            // t=1: top calls c_display
LOG c now_in=top.b1 prev=top     // lands in the LAST saved scope
LOG sv where=top.b1.sv_display

Lookup by name is how C reaches an instance it was never called from. That is useful for broadcast-style models (exercise 7). Verilator accepts the name exactly as %m prints it, including generate blocks ("top.gen[0].u"), and rejects the internal TOP. prefix and relative names.

0.8Per-scope user data: instance state without a chandle

Step 03 gave each SV instance its own C state by returning a chandle from a constructor and passing it back on every call. The scope gives a second way that needs no extra argument: svPutUserData(scope, key, ptr) hangs a pointer on the instance, and svGetUserData(scope, key) gets it back. The key is any unique pointer. The address of a private static is the idiom, so two C libraries never collide.

// lab/setscope.c: a counter per calling instance (import is context: it reads the scope)
static int key;                                  // &key = "my" slot on any scope
int bump(void) {
  svScope s = svGetScope();
  int* n = (int*)svGetUserData(s, &key);
  if (!n) { n = (int*)calloc(1, sizeof *n); svPutUserData(s, &key, n); }
  return ++*n;
}

LOG bump where=top.b2 n=1
LOG bump where=top.b1 n=1
LOG bump where=top n=4        // top called it 4 times; b1 and b2 once each

Chandle or user data? Use the chandle when SV creates and destroys the C object explicitly: dynamic objects, classes, many models per instance. Use user data when the C state is naturally "one per module instance", such as a memory model or a per-port checker, and you want SV call sites to stay argument-free. Both leak if nobody frees them. Freeing user data at the end of simulation needs a final block that calls a context import.

LOG svtime tag=t25 rc=000 sim=25000 scaled_low=25000 scaled_real=-1 ... unit=-9 prec=-12 gunit=-9
LOG svtime tag=sub30ns rc=000 sim=30000 scaled_low=30000 scaled_real=-1 ... unit=-9 prec=-12 gunit=-9

0.9Tasks across the boundary

Both directions accept tasks as well as functions: import "DPI-C" context task and export "DPI-C" task. The LRM gives both an int return on the C side (§35.8, §35.9, H.8.2). It is not a value but a disable flag. If SV disables a block while a task call chain is inside C, the exported task returns 1. C must then clean up, call svAckDisabledState() and return 1 from the import task, so the simulator can unwind. svIsDisabledState() tells C whether that is happening. §35.9 adds three rules: once disabled, the import must not call any more exports; the values of its output/inout arguments and its result are undefined; and the simulator shall stop with a fatal error if C breaks the protocol.

// lab/xtask.c: imported task looping over a zero-time exported task
int c_task(int n) {                        // import task: returns int (disable ack), 0 = normal
  for (int i = 0; i < n; i++) {
    int o;
    sv_task(i, &o);                        // export task. LRM: returns int. Verilator: void
    printf("LOG c i=%d o=%d\n", i, o);
  }
  printf("LOG c disabled_state=%d\n", svIsDisabledState());
  return 0;
}

LOG c i=0 o=0
LOG c i=1 o=10
LOG c i=2 o=20
LOG c disabled_state=0
LOG sv calls=3 t=0

The generated header reveals the deviation: extern void sv_task(int i, int* o); for the export, and extern int c_task(int n); for the import. The book's footnote 2 says VCS also declared exported tasks as void. Portable C therefore never uses the return value of an exported task. In Verilator the disable protocol cannot trigger anyway, because an exported task can't block (0.10), so no SV disable can ever catch a call chain inside C.

0.10Exported tasks that wait: the book's model, Verilator's wall

§12.8.3 is the most ambitious use of DPI in the chapter. C reads a command file and calls exported SV tasks that consume simulation time (Sample 12.40: mem_write takes #10, mem_read takes #20). For this to work, the simulator must be able to suspend a C function mid-body while other SV processes run, and resume it later. Commercial simulators do it by giving each context task call its own stack, a coroutine. That is why the book insists that read_file be a context task "as the simulator needs to create a separate stack".

// lab/mem_task.sv: Sample 12.40 as printed (fixed OCR)
module top;
  import "DPI-C" context task read_file(string fname);
  export "DPI-C" task mem_read;
  export "DPI-C" task mem_write;
  export "DPI-C" function mem_build;
  initial read_file("mem.dat");
  int mem[];
  function void mem_build(input int size); mem = new[size]; endfunction
  task mem_read(input int addr, output int data); #20 data = mem[addr]; endtask
  task mem_write(input int addr, input int data); #10 mem[addr] = data; endtask
endmodule

%Error-UNSUPPORTED: mem_task.sv:15:5: Unsupported: Timing controls inside DPI-exported tasks
%Error-UNSUPPORTED: mem_task.sv:18:5: Unsupported: Timing controls inside DPI-exported tasks

The lab checks the three ways to wait. #5, @(posedge clk), and a delay buried in a task that the exported task calls are all rejected at compile time with the same message (lab/xtime.sv, -DAT, -DNESTED). The exported task itself is fine as long as nothing under it can block (lab/xtask.sv).

0.11The command-file memory, zero-time version (Samples 12.37–12.39, 12.42)

The book's running example is a memory model that a C program drives from a text file. This is the realistic shape of "legacy C stimulus" or "a C test program pokes the model". The zero-time version, with exported functions, runs on every simulator. The lab grows Sample 12.38 to read and write so that it can execute the file of Sample 12.42 (M 100, W 12 34, W 99 8, R 12 34):

// lab/mem_func.sv
import "DPI-C" context function int read_file(string fname);   // returns #errors
export "DPI-C" function mem_build;
export "DPI-C" function mem_read;
export "DPI-C" function mem_write;
int mem[];
function void mem_build(input int size);   mem = new[size];  endfunction
function int  mem_read(input int addr);    return mem[addr]; endfunction
function void mem_write(input int addr, input int data); mem[addr] = data; endfunction

// lab/mem_func.c (core): the book's Sample 12.37 without its two bugs
FILE* f = fopen(fname, "r");
if (!f) { printf("LOG c error=cannot_open file=%s\n", fname); return 1; }   // book: no check
while (fscanf(f, " %c", &cmd) == 1) {          // book: while (!feof(file)) cmd = fgetc(file);
  switch (cmd) {
    case 'M': fscanf(f, "%d", &a);        mem_build(a);    break;
    case 'W': fscanf(f, "%d %d", &a, &b); mem_write(a, b); break;
    case 'R': fscanf(f, "%d %d", &a, &b);
              if (mem_read(a) != b) errs++;  break;
  }
}

LOG c read addr=12 data=34 exp=34
LOG memf size=100 m12=34 m99=8 errs=0 t=0

Everything happens at t=0, which is the limitation the book fixes next with timed tasks (0.10), and which Verilator forces us to fix differently (0.13). The while (!feof()) idiom is a classic C bug. feof only becomes true after a read fails, so the loop body runs once more with cmd = EOF. Here the switch ignores it, which is why the book gets away with it. Testing the return of the read itself (fscanf(...) == 1) is the correct form. The leading space in " %c" also skips the newlines that the book's fgetc loop had to fall through.

0.12Objects behind an index (Samples 12.43–12.45)

Class methods can't be exported, and an SV class handle can't cross DPI: there is no C type for it, unlike chandle in the other direction. The book's answer is to export module-level wrapper functions and give C an integer index into a queue of handles. C says "memory 1, address 12". The wrapper does memq[1].read(12). This is the same trick as a file descriptor in Unix.

// lab/mem_oop.sv (core)
Memory memq[$];
function automatic int mem_build(input int size);  // automatic: see trap below
  Memory m = new(size);
  memq.push_back(m);
  return memq.size() - 1;                              // the "handle" C receives
endfunction
function int  mem_read(input int idx, addr);        return memq[idx].read(addr); endfunction
function void mem_write(input int idx, addr, data); memq[idx].write(addr, data); endfunction

// Sample 12.43 file: M0 1000, M1 2000, W0 12 34, W1 12 88, W0 99 18, R1 22 44, R0 12 34, R1 12 88
LOG c read mem=1 addr=22 data=0 exp=44 MISMATCH     // the book's file reads an address never written
LOG c read mem=0 addr=12 data=34 exp=34 ok
LOG c read mem=1 addr=12 data=88 exp=88 ok
LOG memoop n=2 m0_12=34 m1_12=88 m0_99=18 errs=1

Location 12 holds 34 in memory 0 and 88 in memory 1: two objects, one C program, no handles crossing the boundary. The R1 22 44 line of Sample 12.43 reads a location that no command wrote, so it is a guaranteed mismatch. The lab keeps it as a built-in negative test.

0.13The pull model: the timed memory on every simulator

To give the memory real timing (writes 10 ns, reads 20 ns) without blocking inside C, invert the control flow (Fig. 0.6). SV owns the loop and time. C becomes a small iterator over the command file plus a checker. Each C call returns immediately, so the imports are plain generic functions: no context, no exports, nothing that can go stale.

// lab/mem_pull.sv (core)
import "DPI-C" function int  cmd_next(output byte cmd, output int idx, addr, data);
import "DPI-C" function void cmd_result(int idx, addr, data, longint t);
class Memory;
  int mem[];
  function new(int size); mem = new[size]; endfunction
  task read(int addr, output int data); #20 data = mem[addr]; endtask
  task write(int addr, int data);       #10 mem[addr] = data; endtask
endclass
initial begin
  byte cmd; int idx, addr, data;
  Memory m;                         // NOT "Memory m = new(..)": static initializer
  void'(cmd_open("mem_oop.dat"));
  while (cmd_next(cmd, idx, addr, data))
    case (cmd)
      "M": begin m = new(addr); memq.push_back(m); end
      "W": memq[idx].write(addr, data);
      "R": begin memq[idx].read(addr, data); cmd_result(idx, addr, data, $time); end
    endcase
end

LOG c read mem=1 addr=22 data=0 exp=44 t=50 MISMATCH
LOG c read mem=0 addr=12 data=34 exp=34 t=70 ok
LOG c read mem=1 addr=12 data=88 exp=88 t=90 ok
LOG pull errs=1 t=90 ticks=89        // an always #1 counter kept running meanwhile

Two details in mem_pull.c are worth stealing. First, cmd_next sets *addr = *data = 0 before parsing. An output argument that C doesn't write reaches SV as whatever garbage was in the temporary. Verilator calls skip_out(k__Vcvt, &o__Vcvt) with an uninitialized local and copies it back. lab/outarg.sv starts with o = 7 and reads back 32711 and 1114656704 (the values vary per run). Outputs are not "unchanged if untouched". See step 02 on argument directions. Second, the expected values stay in C (a small queue of exp), so the checker owns the file format and SV only reports what it saw. That split, with SV owning time and C owning data and verdicts, is the same one the golden-model scoreboard of step 06 uses.

The pull model is the default design for new C/SV (and Python/SV) code. Every call is a zero-time generic function, so it is portable to every simulator, cheap (no context), immune to stale scopes, and C never needs to block. Reach for exports only when C genuinely has to call into SV mid-computation: callbacks, error reporting with $error, reading SV configuration.

0.14Book errata and dated parts (§12.7–12.8)

• io_printf (Samples 12.35, 12.41, 12.45, 12.48) is a PLI/VCS routine from veriuser.h. Use printf plus fflush(stdout), so C and SV output stay in order.
• §12.8.6 text: "a call to svGetScope" should be svSetScope (0.7).
• Sample 12.44 vs text: mem_build is void but the text says it returns the index (0.12).
• Sample 12.43: R1 22 44 reads an unwritten location, a guaranteed mismatch (0.12).
• Samples 12.37/12.41/12.45: while (!feof(file)) and an unchecked fopen; the book admits "error checking has been removed" (0.11).
• Sample 12.41: the book declares exported tasks extern int "according to the LRM", with a footnote that VCS used void. Verilator also uses void. Include the generated header and never use the return (0.9).
• Sample 12.40 / §12.8.3: legal SV, but not portable to Verilator (0.10). The pull model (0.13) is the portable form.

0.15Rules of thumb

1. Declare the innermost true flavor: pure ⊂ generic ⊂ context. Anything that reaches an export, VPI or the scope API is context, with no exceptions.
2. Never let SV semantics depend on how many times C runs. Stateful C goes in procedural code at defined events, never in assign/always_comb.
3. Include the generated Vtop__Dpi.h in every C file; never hand-write export prototypes.
4. Per-instance C state: a chandle when SV manages lifetime, svPutUserData when it is "one per instance". Not one C global holding one svScope.
5. If you call svSetScope, restore the previous scope before returning.
6. C never waits. If a C model seems to need simulation time, turn it inside out: SV loops and waits, C is an iterator (pull model).
7. Exported tasks: zero-time only (on Verilator), and called only from context task imports, never from imported functions.
8. C must write every output argument on every path.

§1Learning objectives

• Write an export "DPI-C" function and task, call it from C through the generated header, and predict which instance's copy runs.
• Classify any C routine as pure, generic or context from what its body touches, and state what each promise lets the simulator do.
• Explain the two failure modes of a missing context (fatal NULL scope vs silent stale scope) and spot them in review.
• Use svGetScope, svSetScope (and restore), svGetNameFromScope, svGetScopeFromName, svGetCallerInfo and per-scope user data.
• Know the Annex H task protocol (int disable flag, svIsDisabledState/svAckDisabledState) and where Verilator deviates (void exported tasks, no timing in exports, function→task accepted).
• Port the book's command-file memory to Verilator: zero-time exports, objects behind an index, and the timed version as a pull model.
• Choose between push and pull control flow for a C model, and explain why pull is the portable default.

Prerequisites: 01 (import, build, generated header), 02 (types, output arguments), 03 (chandle and instance state). 04 is not needed except for the string arguments in exercise 10.

§2Exercises

Solutions with code live in lab/ex/ and are built and checked by check.py. Try first, then open.

module leaf; /* import hop (context), export who */ initial #2 hop(); endmodule
module mid;  /* export who */ leaf l(); endmodule
module top;  /* import hop, pin (context), export who */
  mid m();
  initial begin #1 hop(); #2 pin(); #1 hop(); #1 $finish; end
endmodule

static svScope pinned;
void pin(void) { pinned = svGetScopeFromName("top.m"); }
void hop(void) { if (pinned) svSetScope(pinned); who(); }

// ex/ex12_8.sv
import "DPI-C" context function int unsigned shift_c(int unsigned i, int n);
export "DPI-C" function shift_sv;
function void shift_sv(input int unsigned i, input int n, output int unsigned o);
  o = (n > 0) ? i << n : (n < 0) ? i >> -n : i;
endfunction

unsigned int shift_c(unsigned int i, int n) {   // context: it calls an export
  unsigned int o;
  shift_sv(i, n, &o);                          // SV output arg -> C pointer
  return o;
}

n=4 o=00000f00   n=-4 o=0800000f   n=0 o=800000f0   n=40 o=00000000   n=-31 o=00000001

initial begin
  byte cmd; int idx, addr, data;
  void'(cmd_open("mem_oop.dat"));
  while (cmd_next(cmd, idx, addr, data))
    case (cmd)
      "M": begin Memory m = new(addr); memq.push_back(m); end
      "W": memq[idx].write(addr, data);
      "R": begin memq[idx].read(addr, data); cmd_result(idx, addr, data, $time); end
    endcase
end

// ex/pull1.sv (core)
import "DPI-C" function int cmd_next(output byte cmd, output int addr, data, exp);
while (cmd_next(cmd, addr, data, exp))
  case (cmd)
    "M": mem = new[addr];
    "W": mem_write(addr, data);             // #10
    "R": begin mem_read(addr, got);           // #20
         if (got !== exp) begin errs++; $error("addr %0d: got %0d exp %0d", addr, got, exp); end
       end
  endcase

int cmd_next(char* cmd, int* addr, int* data, int* exp) {
  *addr = *data = *exp = 0;                 // every output written on every path
  if (!f || fscanf(f, " %c", cmd) != 1) return 0;
  switch (*cmd) {
    case 'M': fscanf(f, "%d", addr); break;
    case 'W': fscanf(f, "%d %d", addr, data); break;
    case 'R': fscanf(f, "%d %d", addr, exp); break;
  }
  return 1;
}

// ex/broadcast.c (core)
static int key;
void hello(void) {                         // context, called from each unit's initial
  int* n = (int*)malloc(sizeof *n); *n = 0;
  svPutUserData(svGetScope(), &key, n);
}
int broadcast(int n) {
  svScope home = svGetScope(), s; int sum = 0; char name[64];
  for (int i = 0; i < n; i++) {
    snprintf(name, sizeof name, "top.gen[%d].u", i);
    if (!(s = svGetScopeFromName(name))) continue;
    svSetScope(s);
    int* cnt = (int*)svGetUserData(s, &key);
    sum += sv_ping(++*cnt);
  }
  svSetScope(home);                         // restore
  return sum;
}

// ex/ex12_10.sv (core)
Shift q[$];
function automatic int shift_build();
  Shift s = new(); q.push_back(s); return q.size() - 1;
endfunction
function void shift_sv(int idx, int unsigned i, int n); q[idx].shift_sv(i, n); endfunction
function void shift_print(int idx);                     q[idx].shift_print(idx); endfunction

void c_run(void) {                          // context
  int a = shift_build(), b = shift_build(), c = shift_build();
  shift_sv(a, 0x1, 4); shift_sv(b, 0x100, -8); shift_sv(c, 0xdeadbeef, 0);
  shift_print(a); shift_print(b); shift_print(c);
}

LOG ex10 idx=0 result=00000010
LOG ex10 idx=1 result=00000001
LOG ex10 idx=2 result=deadbeef

// ex/report.sv (core)
import "DPI-C" context function void c_check(int got, int exp);
export "DPI-C" function sv_report;
function void sv_report(string where, string msg);
  $error("[C model @ %s] %s", where, msg);
endfunction

void c_check(int got, int exp) {
  if (got == exp) return;
  const char* file; int line; char where[256], msg[128];
  svGetCallerInfo(&file, &line);
  snprintf(where, sizeof where, "%s:%d", file, line);
  snprintf(msg, sizeof msg, "got %d exp %d", got, exp);
  sv_report(where, msg);                    // SV copies the strings
}

[10] %Error: report.sv:8: Assertion failed in top.sv_report: [C model @ ex/report.sv:12] got 4 exp 5
-Info: ex/report.sv:8: Verilog $stop, ignored due to +verilator+error+limit
[20] %Error: report.sv:8: Assertion failed in top.sv_report: [C model @ ex/report.sv:13] got 7 exp 9

§3Quiz

§4Lab walkthrough

Run: cd tutorial/05_export_and_context/lab && python3 check.py. It builds 27 Verilator binaries in five parallel batches (about 15 s with a warm ccache, 1–2 min cold), runs them, and asserts 44 facts. Logs are in build/<name>.log, build output (including the expected compile errors) in build/<name>.build, and the generated prototypes in build/vl_<name>/Vtop__Dpi.h.

Predict first: before opening the logs, write down (1) which instance prints in scopes and setscope, (2) whether stale crashes, (3) how many C calls pure and comb make, (4) the end time of mem_pull.

What to look at: open build/vl_xtask/Vtop__Dpi.h and compare it with H.8.2 (exported task = int). In build/vl_outarg/Vtop___024root__0.cpp, find the __Vdpiimwrap_ wrapper Verilator generates around every import: the temporaries k__Vcvt and o__Vcvt are where conversions, and the output-argument garbage, come from. Then break things on purpose: remove context from scopes.sv, or swap the svSetScope(prev) restore out of setscope.c, and rerun.

New Verilator behaviors found here are also recorded in tutorial/NOTES.md.

§5Cheat sheet

Key rules

1. pure ⊂ generic ⊂ context: declare the innermost true one.
2. Calls exports, VPI or the scope API → context, always.
3. The number of C calls is not SV semantics, so keep stateful C out of assign/always_comb.
4. Always include the generated Vtop__Dpi.h.
5. Per-instance state lives on the scope or behind a chandle, never in one global svScope.
6. Restore the scope after svSetScope.
7. C never waits: invert to a pull model.
8. Exported tasks are called only from context task imports, and contain no timing in Verilator.
9. Write every output argument on every path.
10. Class handles never cross DPI: pass an index.

Spear & Tumbush, SystemVerilog for Verification, 3rd ed. (Springer, 2012), §12.7–12.8, Samples 12.32–12.50; IEEE Std 1800-2023 clause 35 and Annexes H, I. Lab: Verilator 5.052 on macOS x86_64. Every result in this guide is asserted by lab/check.py.