DPI-C from scratch · Part A · Step 02

Data types: what C actually receives

Every DPI argument has two declarations, one in SystemVerilog and one in C, and no tool compares them for you unless you ask. This step maps every type that can cross the boundary, measures what Verilator really passes, and shows where the bits you did not think about end up: unused upper bits, sign bits, X and Z, and outputs nobody wrote.

Book: Spear & Tumbush 3rd ed., §12.1.3–12.1.4, §12.2.3–12.2.5 (pp. 417–427; PDF page = book page + 36)Normative: IEEE 1800-2023 §35.5, Annex H.7–H.10, Annex ISimulator: Verilator 5.052, macOS x86_64

§0 · TutorialThe step in one idea

The simulator and the C compiler each lay out data their own way, and DPI is the contract that says how a value of one is presented to the other. For small types the contract is plain C: an int is an int. For everything that has no C equivalent (vectors of arbitrary width, 4-state values, strings owned by the simulator) the contract is a canonical representation defined in IEEE 1800 Annex H and the header svdpi.h (Annex I). Learn the canonical forms once and you can pass anything a hardware testbench needs.

Three questions run through the whole step. What bits does C see? (layout, word order, unused bits, signedness). What bits does SV get back? (masking, 4-state planes, outputs C never wrote). Who guarantees it? The LRM, or just the simulator you happen to run. The difference matters: a model that works on Verilator because Verilator zeroes and masks unused bits can break on a commercial simulator that does neither, and the LRM allows both behaviors.

Every number below comes from the lab: one testbench per topic, a check.py with 72 assertions. Where the book (2012, IEEE 1800-2009, VCS-era) is wrong or dated, a Book erratum callout says so. Step 01 covered the build, linkage and the generated Vtop__Dpi.h header; this step assumes them.

0.1Three ways across the boundary

Annex H sorts every argument into one of three passing modes, and once you know the mode the C type follows mechanically (Fig. 0.1).

• By value: an input of a "small" type (the C-compatible ones: byte, shortint, int, longint, their unsigned forms, real, shortreal, chandle, string, and bit/logic scalars). C gets a copy in a register or on the stack.
• By const pointer: an input of a packed vector (any bit [N:0] or logic [N:0], including integer, time and even logic [0:0]). C gets const svBitVecVal* or const svLogicVecVal* pointing at an array of 32-bit chunks.
• By pointer: every output and inout, of any type. C gets a pointer to a temporary, writes through it, and the simulator copies the temporary back into the SV variable after C returns.

The full table, with what Verilator 5.052 generates in Vtop__Dpi.h (every row is in the lab's types or proto experiments):

0.2The integer types and the char trap

The C-compatible integer types are the boring, safe part: the round trips in the lab hit every extreme value and come back intact.

LOG sizeof char=1 short=2 int=4 longlong=8 float=4 double=8 svBit=1 svLogic=1 svBitVecVal=4 svLogicVecVal=8 ptr=8 char_signed=1
LOG byte min=-128 max=127
LOG short min=-32768 max=32767
LOG int min=-2147483648 max=2147483647
LOG long min=-9223372036854775808 max=9223372036854775807
LOG ulong max=18446744073709551615

The one trap is byte. The LRM maps it to plain char, and C leaves the signedness of plain char to the implementation: signed on x86 and on Apple ARM, unsigned on ARM Linux (and on PowerPC). The lab rebuilds the same code with -funsigned-char to emulate an ARM Linux host:

default (x86):     LOG c_byte v=-128     LOG c_enum v=-2
-funsigned-char:   LOG c_byte v=128      LOG c_enum v=254
both:              LOG byte min=-128 max=127      LOG enum v=BUSY

Read the last line carefully: the round trip still works, because the bit pattern 0x80 goes to C and comes back unchanged. What breaks is anything C computes with the value: a comparison b < 0, a widening to int, an index. That is the worst kind of bug, one that passes a loopback test and fails in the model (Exercise 9).

/* byte arrives as plain char: never compute with it directly */
int c_isneg(char b) { return (signed char)b < 0; }   /* or: int v = (signed char)b; */

Enumerations cross as their base type (typedef enum byte {...} → char), so C sees the encoding, not the name. If the C model needs the names, mirror the enum in a C header and keep the two in sync, or pass an int and convert at the boundary.

0.3real and shortreal

real is an IEEE-754 double on both sides and needs no comment: rt_real(0.1) returns 0.10000000000000001, the nearest double to 0.1. shortreal is supposed to be a C float. Verilator does not implement single precision at all: it warns SHORTREAL: Unsupported: shortreal being promoted to real and generates double in the prototype. A C file written to the LRM (float rt_sreal(float v)) still links, because the symbol name is all the linker checks, and then reads the wrong register:

C declared float :   LOG c_sreal v=-1.5881868392106856e-23     LOG sreal v=1.2731974747767896e-314
C declared double:   LOG c_sreal v=0.10000000000000001         LOG sreal v=0.10000000000000001

On x86-64 both float and double arguments travel in xmm0; the callee reads the low 32 bits of a double as a float and gets noise, and the caller reads a float's bits as a double and gets a denormal. Nothing crashes. Including the generated header turns this into a compile error (lab build types_hdr):

../../types.c:37:9: error: functions that differ only in their return type cannot be overloaded

Newer clang (16+) words the same error as error: conflicting types for 'rt_sreal'.

Note also the second line of the "double" run: the value is exactly the double 0.1, not the float 0.1 (0.100000001490116…). On Verilator a shortreal model never sees single-precision rounding, so a bit-exact float golden model cannot be checked through shortreal here.

0.4bit and logic scalars

A single-bit argument travels as a byte: svBit and svLogic are both uint8_t in svdpi.h. A 2-state bit uses values 0 and 1. A 4-state logic packs the two planes described in 0.8 into bits 0 and 1 of the byte, which gives the four constants of svdpi.h (Fig. 0.2).

Two measurements matter here. First, Verilator is a 2-state simulator: a logic that holds X or Z in the source is stored as 0, so C receives sv_0 for X, Z and 0 alike (LOG logic v0=0 v1=1 vx=0 vz=0). A literal Z argument does not even build: rt_logic(1'bz) stops Verilator with Unsupported tristate construct: ARG; the lab keeps the X and Z in variables to get past that. Second, C can write any byte into a scalar output. The book warns that this can corrupt the SV variable. Verilator masks it: the wrapper does b = (1U & b__Vcvt), so C writing 0xFE gives SV a clean 0 (LOG badbit b=0 l=0). The LRM does not require the mask, so write only sv_0…sv_x.

0.5Packed vectors: the canonical representation

A packed bit vector of any width crosses as an array of 32-bit chunks, svBitVecVal (= uint32_t). The layout is fixed by the LRM (H.7.7), independent of the simulator's internal storage:

• Chunk 0 holds bits [31:0], chunk 1 bits [63:32], and so on: little-endian by word, whatever the declared range ([0:39] or [39:0], the LSB of the value is bit 0 of chunk 0).
• The number of chunks is SV_PACKED_DATA_NELEMS(W) = $\lceil W/32 \rceil$.
• The last chunk uses only $W \bmod 32$ bits (when that is not 0). The LRM says the rest are undetermined, on input and on output.

The C side always works with three numbers: the width $W$, the chunk count $N = \lceil W/32 \rceil$, and the used bits of the last chunk $W \bmod 32$. svdpi.h gives you SV_PACKED_DATA_NELEMS(W) and SV_MASK(n) ($2^n-1$ for $n < 32$):

/* 200-bit add (lab vec.c): ripple the carry through 7 chunks, then clean the top chunk */
void c_add200(const svBitVecVal* a, const svBitVecVal* b, svBitVecVal* sum) {
  unsigned long long c = 0;
  for (int k = 0; k < 7; k++) { c += (unsigned long long)a[k] + b[k]; sum[k] = (svBitVecVal)c; c >>= 32; }
  sum[6] &= SV_MASK(200 - 6 * 32);          /* 8 used bits: never leave junk above them */
}

What about the unused bits? The book (§12.2.3) warns that "the simulator may not mask the upper bits after calling a DPI routine", so junk that C leaves there can corrupt the SV variable. The lab asks Verilator directly: C writes 0xFFFFFFFF into both chunks of a bit [39:0] output.

LOG dirty d=ffffffffff eq=1 plus1=0000000000

Verilator masks: the variable is the 40-bit all-ones value, it compares equal to 40'hFF_FFFF_FFFF, and adding 1 wraps to 0. The generated wrapper copies back with VL_SET_Q_SVBV(40, v, v__Vcvt + 0), which keeps exactly 40 bits. Commercial simulators that pass a pointer straight into their own storage (to avoid the copy) may not.

0.6Signed vectors and sign extension

Declaring a vector signed changes how SV interprets it, not how DPI lays it out. The canonical representation carries the $W$ bits and nothing else; the sign bit is just bit $W-1$, sitting in the middle of the last chunk. Nobody extends it into the unused bits for you:

c_dump_s40(-40'sd2)   →   LOG s40 w0=fffffffe w1=000000ff

Bits [63:40] of chunk 1 are zero, so (long long)v[1] << 32 | v[0] gives +1 099 511 627 774, not −2 (Exercise 6). The correct conversion masks to $W$ bits, then moves bit $W-1$ to bit 63 and shifts back arithmetically:

long long c_s40(const svBitVecVal* v) {               /* bit signed [39:0] → long long */
  unsigned long long u = ((unsigned long long)(v[1] & SV_MASK(8)) << 32) | v[0];
  return (long long)(u << 24) >> 24;                   /* 64 - 40 = 24 */
}

svdpi.h offers SV_GET_SIGNED_BITS(VALUE, N) for this, and here is a surprise: the macro, copied verbatim from Annex I into every vendor's header, tests the wrong bit.

#define SV_GET_SIGNED_BITS(VALUE, N) \
    ((N) == 32 ? (VALUE) : \
    (((VALUE) & (1 << (N))) ? ((VALUE) | ~SV_MASK(N)) : ((VALUE) & SV_MASK(N))))
                       /* ^^^^^^^^ bit N is the first UNUSED bit; the sign bit is N-1 */

LOG sign8_c raw=00000080 macro=128 right=-128
LOG sign8_c raw=000000ff macro=255 right=-1

For an 8-bit -128 the macro returns +128. It only "works" if the unused bits happen to be sign-extended already, which no simulator promises. Write the two-line version yourself.

0.7Wide vectors and the select helpers

Nothing changes past 64 bits: a 200-bit value is 7 chunks and C loops over them, as the 200-bit adder in 0.5 does (the lab checks s == a + b in SV). For field access across chunk boundaries svdpi.h provides bit- and part-select helpers that work on the canonical form, so you do not hand-code the word/offset arithmetic:

The index is the bit position in the value (bit 0 = LSB), not in the declared range. The last column of svPutPartselBit is the catch. The lab extracts a 16-bit field at bit 100 into an output and inserts 0xBEEF at bit 70 of a 200-bit output:

LOG partsel_in w0=00003039 w2=00000000 w6=00000000      ← C prints the output BEFORE writing it
LOG partsel f=dead w_ok=0 w=00000000000000000000000000002fbbc00000000000003039

The field landed correctly (0x2fbbc at hex digit 17 is 0xBEEF << 70), but the low chunk still holds 0x3039 = 12345, which is the b operand of the previous call (c_add200). The output buffer arrived with stale stack contents, svPutPartselBit touched only 16 bits, and the rest went back into SV. Section 0.9 explains why; Exercise 7 fixes it with one memset.

0.84-state vectors: aval and bval

A logic/reg vector needs two bits per bit of value. The canonical form keeps them as two parallel planes, chunk by chunk: svLogicVecVal is struct { uint32_t aval; uint32_t bval; } (identical to VPI's s_vpi_vecval), and a $W$-bit value is an array of $\lceil W/32 \rceil$ of them (Fig. 0.5). The per-bit encoding is the one in Fig. 0.2: (bval, aval) = 00 → 0, 01 → 1, 10 → Z, 11 → X.

Two shapes look alike and are not. input logic a is a scalar: one svLogic byte by value. input logic [0:0] b is a one-bit vector: const svLogicVecVal*. The lab's prototype dump confirms both (Spear's warning on p. 425 holds). Mixing them up compiles if you skip the generated header and reads garbage.

In Verilator the bval plane is always zero, because the simulator stores no X or Z to put in it. The lab passes 40'h12_3456_78zx and C reads:

LOG ldump w0.aval=34567800 w0.bval=00000000 w1.aval=00000012 w1.bval=00000000

The z and x nibbles arrive as 0 with no flag. The reverse direction loses information too: C writes aval=0x55, bval=0x33, which in a 4-state simulator is 8'b01zx_01zx; Verilator keeps only aval and SV prints 01010101.

Converting a model from 2-state to 4-state (§12.2.5) is mechanical: bit→logic and int→integer in the SV declarations; svBitVecVal→svLogicVecVal in C; read .aval where you read the word before; check .bval on inputs; write .bval = 0 on outputs unless you mean to drive X/Z.

0.9Directions: who owns which bytes

The LRM's rules for input, output and inout (§35.5.1.2 and §35.6.1 on the SV side, H.8.7–H.8.8 on the C side) are short:

• An input must not be modified by C. Packed inputs come as const pointers so the compiler enforces it; declare scalar inputs const too (Sample 12.5).
• An output has an undetermined initial value. C must not read it, and must write all of it.
• An inout starts with the current SV value; C may read and update it.
• Pointers to arguments are valid only during the call. Do not keep them.
• ref is not allowed in an import (the book says so in §12.1.3). Verilator 5.052 accepts ref int a silently and generates int* a; a commercial simulator will reject the same file.

The generated code shows how Verilator implements this. For import "DPI-C" function void c_skip_out(output int o, output bit [39:0] v) the wrapper is:

void Vtop___024unit____Vdpiimwrap_c_skip_out_TOP____024unit(IData &o, QData &v) {
    o = 0U;
    v = 0ULL;
    int o__Vcvt;                         // uninitialized local
    svBitVecVal v__Vcvt[2];              // uninitialized local
    c_skip_out(&o__Vcvt, v__Vcvt);       // C gets pointers to the locals
    o = (o__Vcvt);                       // copy back, whatever is there
    VL_SET_Q_SVBV(40, v, v__Vcvt + 0);   // copy back, masked to 40 bits
}

The lab measures every consequence:

0.10string and chandle, briefly

A string input arrives as const char* to a NUL-terminated copy owned by the simulator, valid only during the call: c_strlen("hello, DPI") returns 10 and c_strlen("") returns 0 (never NULL). If C needs the text later, it copies it (strdup). Strings going out (output arguments and string results) raise the question of who owns the memory, which is step 04's topic.

A chandle is an opaque C pointer that SV can store, copy, compare with null and hand back, but never dereference. It is how C objects get an identity in SV:

chandle h = c_new_box(42);         // C: void* c_new_box(int v) { int* p = malloc(...); *p = v; return p; }
$display(c_box_get(h));            // 42
$display(h == null, c_is_null(null));   // 0 1 : SV null arrives in C as NULL

Lifetime, per-instance state and C++ objects behind a chandle are step 03.

0.11What a function may return

A function result travels in a register, so §35.5.5 (repeated in H.8.9) limits it to "small values": void, byte, shortint, int, longint, real, shortreal, chandle, string, and scalar bit and logic. That is the whole list: a packed vector, even bit [6:0], is not on it and goes through an output argument. Verilator 5.052 is more permissive than the LRM: it also accepts packed bit results up to 32 bits (returned as an svBitVecVal), which is an extension that will not port. Its messages for the rest:

0.12Sample 12.12 on a 2-state simulator

Samples 12.11/12.12 turn the 7-bit counter (Sample 12.9) into a 4-state model that rejects X/Z on reset, load and i. The lab ports it (io_printf → printf; the chandle as void*) and drives exactly the cases the checks exist for: an uninitialized reset (X in a 4-state simulator) and a load value 7'b000_zzxx.

LOG c4 step=xreset out=1      ← reset X seen as 0: the counter counted
LOG c4 step=xload out=0       ← zzxx seen as 0000: loaded 0
LOG c4 step=reset out=0       (no "c4err" line at all)

On Verilator none of the three error branches can fire, so the model silently does something; on Questa or Xcelium the same testbench prints two errors. Reading the sample with 0.5 and 0.9 in mind also reveals two latent bugs (the subject of Exercise 12):

1. if (i->bval) tests all 32 bits of the chunk, including 25 undetermined ones. On a simulator that leaves junk there, a clean input raises an error.
2. Every error branch does return without writing count. The SV variable then receives an undetermined value (0.9). The fix is to drive X explicitly: count->aval = count->bval = SV_MASK(7).

The book also mentions vpi_control(vpiFinish, 0) to stop the simulation from C. In practice, return a status and let SV call $fatal, or use an exported SV function (step 05).

0.13Commercial simulators (not measured here)

0.14Rules that keep you safe

1. Include the simulator-generated prototype header in every DPI C file.
2. Prefer fixed-size C types for computation (int32_t, uint64_t); cast byte's char to signed char before using it.
3. Avoid shortreal in signatures.
4. Packed inputs: mask the last chunk with SV_MASK(W % 32) before using it; sign-extend by hand from bit $W-1$.
5. Packed outputs: write every chunk; write the unused bits as zero.
6. Outputs: write every output on every return path; never read one before writing it.
7. 4-state: check bval on inputs, write bval = 0 on outputs; test the X/Z paths outside Verilator.
8. Results wider than 32 bits, or 4-state, go through output arguments.

§1 · ObjectivesWhat you can do after this step

• Write the C prototype of any DPI import from its SV declaration, and check it against the simulator-generated header.
• Explain the three passing modes (by value, const pointer, pointer to a temporary) and pick the mode from type + direction.
• Read and write packed vectors of any width in canonical form: word order, chunk count, unused bits, sign extension.
• Use the svGet/PutBitsel* and svGet/PutPartsel* helpers correctly.
• Handle 4-state values through aval/bval, and know exactly what a 2-state simulator does to them.
• State the LRM's guarantees for output/inout and the consequences of breaking them, with Verilator's measured behavior.
• Recognize the platform traps: plain char, shortreal, long vs long long, shifts ≥ the word width.

Prerequisite: step 01 (build, extern "C", the generated header). Next: step 03 (C state and chandle).

§2 · Exercises12 exercises, graded, with solutions

★ basic · ★★ intermediate · ★★★ real-design. Every code solution is in lab/ex/, built by run.sh and checked by check.py. "Ex. 12.N" is an exercise from the book (which has no solutions).

import "DPI-C" function void e1(input byte unsigned a, output longint b, input bit [63:0] c,
                                output logic [3:0] d, input string e, inout bit f, output chandle g);

void e1(unsigned char a, long long* b, const svBitVecVal* c, svLogicVecVal* d,
        const char* e, svBit* f, void** g);

import "DPI-C" function int unsigned shift_c(input int unsigned i, input int n);
function automatic int unsigned shift_sv(int unsigned i, int n);   // reference
  return n >= 0 ? i << n : i >> -n;
endfunction

unsigned int shift_c(unsigned int i, int n) {
  if (n >= 32 || n <= -32) return 0;        /* SV semantics; in C this would be UB */
  return n >= 0 ? i << n : i >> -n;
}

unsigned int shift_ld_c(unsigned int i, int n, svBit ld) {
  static unsigned int reg;                  /* one register for the whole simulation */
  reg = shift_c(ld ? i : reg, n);
  return reg;
}

int c_popcount200(const svBitVecVal* v) {
  const int W = 200, N = SV_PACKED_DATA_NELEMS(W);          /* 7 chunks */
  int n = 0;
  for (int k = 0; k < N; k++) {
    svBitVecVal w = (k == N - 1 && W % 32) ? v[k] & SV_MASK(W % 32) : v[k];
    n += __builtin_popcount(w);
  }
  return n;
}

long long c_s40_bad(const svBitVecVal* v) { return (long long)((unsigned long long)v[1] << 32 | v[0]); }

long long c_s40(const svBitVecVal* v) {
  unsigned long long u = ((unsigned long long)(v[1] & SV_MASK(8)) << 32) | v[0];
  return (long long)(u << 24) >> 24;
}

void c_put16(svBitVecVal* w, const svBitVecVal* f, int lsb) {   /* output bit [199:0] w */
  svPutPartselBit(w, *f, lsb, 16);
}

  memset(w, 0, SV_PACKED_DATA_NELEMS(200) * sizeof(svBitVecVal));
  svPutPartselBit(w, *f, lsb, 16);

int c_isneg(char b) { return b < 0; }     /* import: function int c_isneg(input byte b) */

void c_mul128(unsigned long long a, unsigned long long b, svBitVecVal* p) {
  unsigned int x[2] = {(unsigned int)a, (unsigned int)(a >> 32)};
  unsigned int y[2] = {(unsigned int)b, (unsigned int)(b >> 32)};
  unsigned long long acc[4] = {0, 0, 0, 0};
  for (int i = 0; i < 2; i++) {                 /* schoolbook, 32-bit limbs */
    unsigned long long carry = 0;
    for (int j = 0; j < 2; j++) {
      unsigned long long t = (unsigned long long)x[i] * y[j] + acc[i + j] + carry;
      acc[i + j] = t & 0xFFFFFFFFu;
      carry = t >> 32;
    }
    acc[i + 2] += carry;
  }
  for (int k = 0; k < 4; k++) p[k] = (svBitVecVal)acc[k];   /* all 4 chunks written */
}

int count_xz(const svLogicVecVal* v, int width) {
  int n = 0;
  for (int k = 0; k < SV_PACKED_DATA_NELEMS(width); k++) {
    unsigned int b = v[k].bval;                                   /* X or Z ⇔ bval = 1 */
    if (k == SV_PACKED_DATA_NELEMS(width) - 1 && width % 32) b &= SV_MASK(width % 32);
    n += __builtin_popcount(b);
  }
  return n;
}

  if ((reset & 2) || (load & 2) || (i->bval & SV_MASK(7))) {
    printf("Z or X detected on an input\n");
    count->aval = count->bval = SV_MASK(7);      /* 7'bx */
    return;
  }

§3 · Quiz14 questions, self-grading

§4 · LabMeasure the mapping yourself

Everything lives in 02_data_types/lab/. Run it:

cd tutorial/02_data_types/lab
python3 check.py          # runs run.sh (18 clean builds, 2 fail on purpose; ~10-60 s with ccache), then 72 assertions
python3 check.py --no-run # re-check existing build/ logs

Predict first, then open the log: what does C see for X and Z? What happens to an output C never writes? What does a float-declared function read when Verilator passes shortreal? What is in the upper bits of a negative bit signed [39:0]?

Things to look at beyond the logs: build/vl_dir/Vtop___024unit__0.cpp (the generated wrappers of 0.9: the uninitialized temporaries and the masking copy-backs) and build/vl_types/Vtop__Dpi.h (the prototype table of 0.1, written by the tool). The junk values in dir.log (c_peek in=…, skip o=…) change from run to run; check.py asserts only that SV received exactly what C saw. One lab detail is also an SV lesson: $display(ok ? "PASS" : "FAIL") printed 1346458451, because a string literal inside an expression is an integral value ("PASS" = 0x50415353); the testbenches use an if.

§5 · Cheat sheetOne table, eight rules

1. The simulator writes the prototypes: include its header, always.
2. Three modes: small input by value, packed input by const pointer, every output/inout by pointer to a temp.
3. $N = \lceil W/32 \rceil$ chunks, chunk 0 = bits [31:0], last chunk has $W \bmod 32$ used bits.
4. Mask unused bits on read, zero them on write.
5. Sign-extend by hand from bit $W-1$.
6. Outputs are write-only and must be fully written on every return path.
7. 4-state = aval/bval planes; bval 1 means X or Z. A 2-state simulator erases them before C runs.
8. Verilator's kindness (zeroed inputs, masked outputs) is not the LRM's guarantee.

Spear & Tumbush, SystemVerilog for Verification, 3rd ed. (Springer, 2012), §12.1.3–12.1.4 and §12.2.3–12.2.5; IEEE Std 1800-2023 §35.5 and Annexes H and I. Lab: Verilator 5.052 on macOS x86_64 (Apple clang). All numbers on this page come from lab/ and are asserted by lab/check.py.