A C reference model behind DPI

Why the model is in C

U9.2's model was a SystemVerilog class. Teams reach for C or C++ for three reasons. The model already exists: architects wrote it to explore the design and it encodes their intent. It must be fast: an image filter or a cipher round is a lot of arithmetic per transaction. Or it is shared: the same file runs in the software team's tests, the firmware simulator and the bench.

The Direct Programming Interface (DPI) is the SystemVerilog feature that lets the two languages call each other. An import "DPI-C" declaration describes a C function to SystemVerilog, which can then call it like its own function. The simulator compiles the C file into the same executable, so a call costs about as much as a C function call.

These imports are functions, so a call takes no simulation time and this model is untimed. Everything U9.2 said still applies: ask it at the event the design acts on.

An import function cannot wait, and the C side cannot see the bench's clock. A C model that needs time would call back into SystemVerilog through an export "DPI-C" task, from an import declared as a context task. A reference model rarely needs that: keep it untimed and let the scoreboard decide when to ask.

The C file and the SystemVerilog wrapper

The model has six functions. alu_model_new allocates a struct and returns it; SystemVerilog keeps the pointer in a chandle, a variable type that holds a C pointer it never looks inside. Every other function takes that handle first.

// model.c: the pipeline's reference model in C, built together with main.sv.
// Each instance keeps its own state in a struct; SystemVerilog holds it as a chandle.
#include <stdlib.h>
#include "svdpi.h"
#include "Vtb__Dpi.h"   // prototypes generated from the imports: a mismatch fails the build

typedef struct {
  int      mode;        // 0 add 1, 1 double, 2 halve, 3 invert
  unsigned beats;       // data beats seen since new or reset
} alu_model_t;

void* alu_model_new(void) {
  // calloc: mode 0 and no beats, the design's power-up state
  return calloc(1, sizeof(alu_model_t));
}
void alu_model_reset(void* h) {
  alu_model_t* m = (alu_model_t*)h;
  m->mode = 0;
  m->beats = 0;
}
void alu_model_set_mode(void* h, int mode) { ((alu_model_t*)h)->mode = mode & 3; }
int  alu_model_beats(void* h) { return (int)((alu_model_t*)h)->beats; }
void alu_model_free(void* h) { free(h); }

// One data beat. SystemVerilog passes a byte, which arrives as a C char.
int alu_model_step(void* h, char x) {
  alu_model_t* m = (alu_model_t*)h;
  m->beats++;
  switch (m->mode) {
    case 0:  return (unsigned char)(x + 1);
    case 1:  return (unsigned char)(x * 2);
    case 2:  return (unsigned char)(x >> 1);   // char is signed with gcc on x86-64: c8 arrives as -56
    default: return (unsigned char)~x;
  }
}

The wrapper class in main.sv has the same methods as U9.2's alu_model: set_mode and step, plus reset, beats and free. Because the scoreboard only calls methods, swapping a SystemVerilog model for a C one changes no scoreboard code. That is the reason to wrap the imports in a class rather than calling them from the scoreboard directly.

Including Vtb__Dpi.h matters. Verilator writes that header from the import declarations. If the C definition does not match, for example unsigned char x against input byte x, the build fails with conflicting types instead of passing garbage at run time.

Where the state lives

The model's mode and its beat count live in C memory, in one struct per alu_model_new call. A global variable would be shared by every caller.

The example shows all three. After the checks, the test creates a second instance and puts it in mode 1: it doubles 7 to 14 while the first instance, still in mode 3, inverts 7 to 248. Then the first instance is reset: it is back in mode 0, so 7 gives 8, and its beat count starts again at 1.

A handle is valid only between new and free. C does not check: a step after free reads released memory and may even return plausible values. So the wrapper sets h = null in free and checks the handle before every call; a late call stops with a UVM_FATAL before it reaches C.

This pipeline has no reset input, so the example shows only the model's side: reset() returns one instance to its power-up state. A design with a reset defines what happens to work in flight; some discard it, others finish it. Call reset() at the event where the design resets its mode, and treat the queued predictions by the same rule (U10.2).

The beat that disagrees

Run the example. Four beats match. The beat 200 in mode 2 does not: y=100, model said 228 for the beat taken at 65 ns. Which one is right? The specification says the bytes are unsigned and halving is a logical shift, so 200 halves to 100. The design is right.

The model's C code is also correct for what it receives. The fault is at the hand-off. input byte x declares a signed 8-bit value, so 200 (hex c8) crosses as -56. With this toolchain (g++ on x86-64) char is signed and x >> 1 on a negative value shifts in the sign bit; C leaves both choices to the implementation. The result is -28, hex e4, which reads as 228 when it is narrowed to an unsigned byte.

import "DPI-C" function int
  alu_model_step(input chandle h, input byte x);
// model.c
int alu_model_step(void* h, char x);

import "DPI-C" function int
  alu_model_step(input chandle h, input byte unsigned x);
// model.c
int alu_model_step(void* h, unsigned char x);

Only one mode and half the inputs expose this. Add, double and invert give the same low eight bits for a signed or unsigned byte, so they all match. A test that never halved a large value would pass for ever. When a model and the RTL disagree, check the hand-off types first: width, signedness and which end of an array is index 0.

Try it

The scoreboard is U9.2's, unchanged; only alu_model now forwards to C. The one UVM_ERROR is the beat 200 in mode 2: y=100, model said 228. The last three lines show the state on the C side: the beat count, a second instance with its own mode, and a reset.

Change the script to halve 127 and then 128 and see where the disagreement starts. Which modes can never show it?

// model.c: the pipeline's reference model in C, built together with main.sv.
// Each instance keeps its own state in a struct; SystemVerilog holds it as a chandle.
#include <stdlib.h>
#include "svdpi.h"
#include "Vtb__Dpi.h"   // prototypes generated from the imports: a mismatch fails the build

typedef struct {
  int      mode;        // 0 add 1, 1 double, 2 halve, 3 invert
  unsigned beats;       // data beats seen since new or reset
} alu_model_t;

void* alu_model_new(void) {
  // calloc: mode 0 and no beats, the design's power-up state
  return calloc(1, sizeof(alu_model_t));
}
void alu_model_reset(void* h) {
  alu_model_t* m = (alu_model_t*)h;
  m->mode = 0;
  m->beats = 0;
}
void alu_model_set_mode(void* h, int mode) { ((alu_model_t*)h)->mode = mode & 3; }
int  alu_model_beats(void* h) { return (int)((alu_model_t*)h)->beats; }
void alu_model_free(void* h) { free(h); }

// One data beat. SystemVerilog passes a byte, which arrives as a C char.
int alu_model_step(void* h, char x) {
  alu_model_t* m = (alu_model_t*)h;
  m->beats++;
  switch (m->mode) {
    case 0:  return (unsigned char)(x + 1);
    case 1:  return (unsigned char)(x * 2);
    case 2:  return (unsigned char)(x >> 1);   // char is signed with gcc on x86-64: c8 arrives as -56
    default: return (unsigned char)~x;
  }
}

Check yourself

module tb;
  bit [7:0]     v;
  byte          s;           // what an "input byte" import argument carries
  byte unsigned u;           // what an "input byte unsigned" argument carries
  int           a, b;
  initial begin
    v = 8'hC8;
    s = v;
    u = v;
    a = s;
    b = u;
    $display("%0d %0d %02h %02h", a, b, 8'(a >>> 1), 8'(b >>> 1));
    $finish;
  end
endmodule

function new(); endfunction
  function void      set_mode(bit [1:0] m); if (h == null) h = alu_model_new(); alu_model_set_mode(h, m); endfunction
  function bit [7:0] step(bit [7:0] x);     if (h == null) h = alu_model_new(); return alu_model_step(h, x); endfunction

function new(); h = alu_model_new(); endfunction
  function void      set_mode(bit [1:0] m); alu_model_set_mode(h, m); endfunction
  function bit [7:0] step(bit [7:0] x);     return alu_model_step(h, x); endfunction

function new(); h = alu_model_new(); alu_model_reset(h); endfunction
  function void      set_mode(bit [1:0] m); alu_model_set_mode(h, m); endfunction
  function bit [7:0] step(bit [7:0] x);     return alu_model_step(h, x); endfunction

function new(); endfunction
  function void      set_mode(bit [1:0] m); shared_set_mode(m); endfunction
  function bit [7:0] step(bit [7:0] x);     return shared_step(x); endfunction

// model.c: the pipeline's reference model in C, built together with main.sv.
// Each instance keeps its own state in a struct; SystemVerilog holds it as a chandle.
#include <stdlib.h>
#include "svdpi.h"
#include "Vtb__Dpi.h"   // prototypes generated from the imports: a mismatch fails the build

typedef struct {
  int      mode;        // 0 add 1, 1 double, 2 halve, 3 invert
  unsigned beats;       // data beats seen since new or reset
} alu_model_t;

void* alu_model_new(void) {
  // calloc: mode 0 and no beats, the design's power-up state
  return calloc(1, sizeof(alu_model_t));
}
void alu_model_reset(void* h) {
  alu_model_t* m = (alu_model_t*)h;
  m->mode = 0;
  m->beats = 0;
}
void alu_model_set_mode(void* h, int mode) { ((alu_model_t*)h)->mode = mode & 3; }
int  alu_model_beats(void* h) { return (int)((alu_model_t*)h)->beats; }
void alu_model_free(void* h) { free(h); }

// One data beat. SystemVerilog passes a byte, which arrives as a C char.
int alu_model_step(void* h, char x) {
  alu_model_t* m = (alu_model_t*)h;
  m->beats++;
  switch (m->mode) {
    case 0:  return (unsigned char)(x + 1);
    case 1:  return (unsigned char)(x * 2);
    case 2:  return (unsigned char)(x >> 1);   // char is signed with gcc on x86-64: c8 arrives as -56
    default: return (unsigned char)~x;
  }
}

// For comparison: the same model with its mode in one C global.
static int shared_mode = 0;
void shared_set_mode(int mode) { shared_mode = mode & 3; }
int  shared_step(char x) {
  switch (shared_mode) {
    case 0:  return (unsigned char)(x + 1);
    case 1:  return (unsigned char)(x * 2);
    case 2:  return (unsigned char)(x >> 1);
    default: return (unsigned char)~x;
  }
}

Practice

• Three channels and a model that disagrees Fix · Medium