DPI-C tutorial · Part A · Step 04 · Spear & Tumbush §12.4–12.6

Arrays, structs and strings across the boundary

Scalars cross DPI by value. Everything bigger crosses by reference: C gets a pointer or a handle into storage that SystemVerilog owns. This step is about what that storage looks like, who may touch it, and for how long.

Prereqs: 02 Data types (svBitVecVal, aval/bval), 03 State and handlesBook pages: PDF = book + 36Solutions are hidden: think first

§0 · TutorialThe one rule: SystemVerilog owns the storage

A golden model rarely works on one number. It takes a packet, a frame of samples, a header, a matrix of coefficients, and returns another one. In the first three steps every argument was a scalar or a packed vector of a known width. Now we pass aggregates: unpacked arrays of fixed and unknown size, packed arrays of wide elements, structs and strings.

All of them obey one rule, and the rest of this page is detail around it: SystemVerilog owns every byte that crosses the boundary. C receives a pointer (fixed-size arrays, packed structs), a handle to a descriptor (open arrays) or a const char* (strings). That access is valid only for the duration of the call. C cannot allocate an array and give it to SV; SV cannot keep a pointer into C memory. Spear says it in one line under Sample 12.19: "There is no way to allocate an array in C and reference it in SystemVerilog." If C needs the data later, it copies. If SV needs C's data, C writes it into an SV-owned argument or returns a string that SV immediately copies.

The second theme is layout. For a few types (int, byte, longint, real, packed vectors in canonical form) the C view is fixed by IEEE 1800 Annex H (H.7.3, H.7.4, H.7.7). So is the element order of an unpacked array: lower index first, whatever the declared direction (H.7.3, H.7.6). For the rest (whether a whole open array is in C layout, how a simulator stores an unpacked array of bit [12:0]) the standard gives you access functions instead of a layout, and portable code uses them (H.12.3–H.12.6). The lab measures where Verilator 5.052 differs from what you might assume, and where it does not implement the standard at all (dynamic arrays, queues and unpacked structs as DPI arguments).

0.1Fixed-size unpacked arrays (Samples 12.18–12.21)

The simplest aggregate is an unpacked array with constant bounds in the import declaration. H.7.3 and H.11.4 map it to a C array of the element type, which C sees as a pointer to the first element. Each element is represented exactly as a scalar argument of that type would be (step 02): int is an int, byte is a char, a packed bit [31:0] is one svBitVecVal word, a packed logic [31:0] is one svLogicVecVal (an aval/bval pair).

// fib.sv (Samples 12.19 / 12.21, in a module instead of a program)
import "DPI-C" function void fib2(output bit   [31:0] data[20]);
import "DPI-C" function void fib4(output logic [31:0] data[20]);
import "DPI-C" function int  sum8(input int v[8]);
import "DPI-C" function void bytes_in(input byte b[4], output int packed_le);

// fib.c (Samples 12.18 / 12.20). Verilator compiles .c as C++: wrap in extern "C".
void fib2(svBitVecVal data[20]) {          // [20] is documentation: C sees svBitVecVal*
  data[0] = 1;
  data[1] = 1;
  for (int i = 2; i < 20; i++) data[i] = data[i-1] + data[i-2];
}
void fib4(svLogicVecVal data[20]) {        // 4-state: write aval AND bval
  data[0].aval = 1; data[0].bval = 0;
  data[1].aval = 1; data[1].bval = 0;
  for (int i = 2; i < 20; i++) {
    data[i].aval = data[i-1].aval + data[i-2].aval;
    data[i].bval = 0;
  }
}
int  sum8(const int* v)                     { int s = 0; for (int i = 0; i < 8; i++) s += v[i]; return s; }
void bytes_in(const char* b, int* packed_le) { memcpy(packed_le, b, 4); }

Do not guess the C prototype: Verilator writes it for you in V<top>__Dpi.h (step 01). For this file it generated, verbatim:

extern void bytes_in(const char* b, int* packed_le);
extern void fib2(svBitVecVal* data);
extern void fib4(svLogicVecVal* data);
extern int sum8(const int* v);

Note the const on input arrays and its absence on output. Include the header in your C file and the compiler checks your definition against it. The run prints:

LOG fib2 d0=1 d1=1 d19=6765
LOG fib4 d19=6765 unknown=0
LOG sum8 sum=140
LOG bytes_in le=44332211

bytes_in shows that a byte array is a plain char array in memory, one byte per element: copying four of them into an int on a little-endian x86 host puts b[0] in the least significant byte.

0.2Directions: who copies what, and when

For aggregates the direction means more than for scalars. The LRM lets the simulator pass arrays either by pointer to the actual or by pointer to a temporary that it copies in before the call and out after it. The rules C can rely on are the ones that hold in both implementations:

• input: C may read, must not write (the prototype is const).
• inout: C reads the current SV value and may write; whatever it does not write keeps its value.
• output: the value C sees on entry is undefined, and after return the whole argument is the result. Anything C did not write is undefined too.

The last rule bites. The lab's outdir.sv fills three arrays with 5, then calls a C function that writes only element 1 with 7:

LOG c_sees out0=0                                  <- output open array: C sees a zeroed temporary
LOG outdir out=0,7,0 io=5,7,5 outf0_is5=0 outf1=7  <- output: unwritten elements LOST; inout: kept

With an output open array Verilator hands C a zero-filled temporary and copies all of it back, so the 5s become 0. With an output fixed array the unwritten element came back as stack garbage (not 5; the exact value is not reproducible and the check only asserts "not 5"). With inout the untouched elements keep their 5. The practical rule: use output only when C writes every element; otherwise use inout. Exercise 10 shows a subtler version: a function that returns an error code before touching its output still overwrites it.

0.3Open arrays: one C function for any size

A fixed-size formal ties the C code to one array size and, worse, to a layout you reverse-engineered. Spear's §12.5 calls that "fragile". The alternative is the open array: write the unpacked dimension(s) as [] in the import, and the same C function accepts any actual size and any range. C now receives an svOpenArrayHandle. It is not a pointer to data; it is an opaque handle to a descriptor that the simulator builds for this call: element type and width, number of unpacked dimensions, the declared range of each dimension, and where the data lives.

// openarr.sv (Samples 12.22 / 12.24, corrected)
import "DPI-C" function void fib_oa(output bit [31:0] data[]);   // one [] = 1 unpacked dim
import "DPI-C" function void query(input int a[][], output int q[11]);
import "DPI-C" function void mydisplay(inout int a[][]);         // [][] = 2 unpacked dims
module top;
  bit [31:0] fibs[20];
  int a[6:1][8:3];          // descending, not 0-based: the C side must not care
  int up[0:2][0:3];         // ascending
  ...

void fib_oa(const svOpenArrayHandle h) {            // Sample 12.23, corrected
  svBitVecVal* d = (svBitVecVal*)svGetArrayPtr(h);  // contiguous storage (may be NULL, see 0.4)
  int n = svSize(h, 1);
  d[0] = 1; d[1] = 1;
  for (int i = 2; i < n; i++) d[i] = d[i-1] + d[i-2];
}

The descriptor is read with the query functions of H.12.2 (Spear's Table 12.3). Dimensions are numbered from 1, outermost first. Here is what C sees for the two arrays above, measured:

The sign of svIncrement surprises people: it is +1 for the "Verilog-style" descending range [6:1] and −1 for [0:2]. Despite the name it is not the step that walks from left to right (that step is −1 for [6:1]); it is the Verilog notion of "is the range written big-endian". You will rarely need it: iterate from svLow to svHigh and you are always right. The sizes check out: $6 \times 6 \times 4 = 144$ bytes and $3 \times 4 \times 4 = 48$.

0.4Reaching the elements

H.12.4 and H.12.5 offer two ways in (Spear's Table 12.4):

• void* svGetArrayPtr(h): the address of the whole array, only if the simulator stores it in the standard C layout; otherwise NULL. Verilator's runtime returns NULL when the variable is not flagged as C layout and, in the same case, svSizeOfArray returns 0.
• void* svGetArrElemPtr1(h, i), …Ptr2(h, i, j), …Ptr3 and the variadic svGetArrElemPtr(h, i, …): the address of one element, addressed with the SV indices (6..1, 8..3 in our example). Out of range returns NULL.

The element-pointer form is the portable one, because it does not assume an order in memory. How much does that matter? The lab asks Verilator where things are, for int v[10:1] (filled with v[i] = i) and for a[6:1][8:3] after mydisplay stored a[i][j] = i*j:

LOG flat v0=1 v_last=10 v_at_low=0 m0=3 m1=4 m6=6

Offset 0 holds v[1], the low index, even though the declaration starts at 10. In two dimensions the storage is row-major starting at the low corner: m0 = a[1][3] = 3, m1 = a[1][4] = 4, m6 = a[2][3] = 6. A C programmer who reads [10:1] as "element 10 comes first" is wrong, and not only in Verilator: H.7.3 and H.7.6(c) fix the order for every tool, "elements with lower indices go first", the element with SV index min(L,R) has C index 0. Still write svGetArrElemPtr1(h, i) with SV indices: it is correct for any range and survives arrays that are not in C layout.

int sum_oa(const svOpenArrayHandle h) {             // any size, any range, any direction
  int s = 0;
  for (int i = svLow(h, 1); i <= svHigh(h, 1); i++)
    s += *(int*)svGetArrElemPtr1(h, i);
  return s;
}
int probe_oob(const svOpenArrayHandle h) {          // index 0 does not exist in [10:1]
  return svGetArrElemPtr1(h, 0) == NULL ? -1 : 0;
}

LOG sum_oa fixed=55
%Warning: DPI svOpenArrayHandle function index 1 out of bounds; 0 outside [10:1].
LOG oob ret=-1

0.5Multi-dimensional open arrays (Samples 12.24–12.25)

Each [] in the formal is one unpacked dimension. The actual must have the same number of unpacked dimensions; their sizes and ranges are free. Spear's example walks a 2-D array with svLow/svHigh and writes it back through inout:

void mydisplay(const svOpenArrayHandle h) {         // Sample 12.25 (io_printf -> printf)
  for (int i = svLow(h, 1); i <= svHigh(h, 1); i++)
    for (int j = svLow(h, 2); j <= svHigh(h, 2); j++) {
      int* a = (int*)svGetArrElemPtr2(h, i, j);     // SV indices, both dimensions
      *a = i * j;
    }
}

SV filled a[i][j] = i + j before the call; the C side saw a[6][3] = 9 and replaced every element with i*j; back in SV, a[6][3] = 18, a[1][3] = 3, a[4][8] = 32. This is also the answer to Spear's Ex. 12.7 (what do the query functions return for Sample 12.24): svLeft(h,1)=6, svLeft(h,2)=8, svRight(h,1)=1, svRight(h,2)=3, svSize(h,1)=6, svSize(h,2)=6, svDimensions(h)=2, svSizeOfArray(h)=144; all measured in the table of 0.3.

Passing a 2-D array to a 1-D open formal (or the opposite) is a compile-time mismatch. Calling svGetArrElemPtr1 on a 2-D handle is caught at run time: Verilator warns "called on 2 dimensional array using 1 dimensional function" and returns NULL.

0.6Dynamic arrays, queues and slices as actuals

IEEE 1800-2023 §35.6.1 says "it is sometimes permissible to pass a dynamic array as an actual argument" to an import, under the same rules as for native subroutines (§7.7); by those rules a queue qualifies too, an associative array does not. Commercial simulators accept both. That is the main reason open arrays exist in a testbench: a packet is usually a byte payload[] or a byte q[$]. Verilator 5.052 implements only fixed-size actuals. The lab builds the same call with four actuals:

Commercial simulators accept all four. On Verilator the workaround is to move the data through a fixed-size buffer and pass the count explicitly; a wrapper function in SV keeps the call sites clean (Exercise 9 sums a 1000-element dynamic array through a 256-element chunk buffer and gets 499500, like d.sum()). It costs one copy, which is what a commercial simulator usually does internally anyway.

0.7Packed elements: one packed dimension of any width (Samples 12.26–12.27)

An open array has exactly one packed dimension (the element's bits) plus one or more unpacked ones. The actual may have several packed dimensions as long as they flatten to the same total width: Spear passes bit [1:0][0:3][6:-1] bpack[9:1] (2·4·8 = 64 bits) to a bit [63:0] b64[] formal.

void view_pack(const svOpenArrayHandle h) {         // Sample 12.27, corrected
  for (int i = svLow(h, 1); i <= svHigh(h, 1); i++) {   // book: i < svHigh -> skips bpack[9]
    unsigned long long v = *(unsigned long long*)svGetArrElemPtr1(h, i);
    printf("C: b64[%d]=%016llx\n", i, v);
  }
}

LOG sv bpack2=1234567890abcdef bpack2_0=90abcdef bpack2_0_0=90
LOG c b64_1=0000000000000001
LOG c b64_2=1234567890abcdef
LOG c b64_9=0000000000000009

Reading a 64-bit element through an unsigned long long* works because Verilator stores a 64-bit element as a 64-bit integer. That is an accident of this element width. H.7.7 defines a canonical representation for packed data (svBitVecVal words, 32 bits each, least significant word first). For an array passed to an open-array formal, H.7.3 says packed elements are "in canonical form", and H.12.3 lets a simulator use a compacted storage instead only if it then refuses direct pointers: H.12.4 says svGetArrElemPtr* "shall return NULL if the representation of the array elements differs" from that of a single value. The lab asks Verilator how many bytes each element really takes:

So the "obvious" code below is wrong for anything under 33 bits. With b8 = '{11, 22, 33, 44} it returns 44332211: it read four 1-byte elements as one word.

int raw8(const svOpenArrayHandle b) {               // BUG: assumes canonical layout
  return *(svBitVecVal*)svGetArrElemPtr1(b, 0);    // Verilator: 4 elements at once -> 0x44332211
}

The portable path copies an element into (or out of) canonical form, whatever the simulator does internally:

svBitVecVal e[4];                                   // 100 bits -> 4 words, LSW first
svGetBitArrElem1VecVal(e, h, i);                    // copy element i OUT, canonical
svPutBitArrElem1VecVal(h, e, i);                    // copy element i IN
svGetLogicArrElem1VecVal(&lv, h, i);                // 4-state flavor: svLogicVecVal
svBit b = svGetBitArrElem1(h, i);                   // 1-bit elements: bit m[]

The lab sums three 100-bit elements with a 32-bit carry chain over the canonical words and gets 3ffffffff0000000100000002, identical to SV's own w[0]+w[1]+w[2]; svPutBitArrElem1VecVal writes f0000000000000000cafef00d into w[1]; and svGetLogicArrElem1VecVal on a logic [7:0] element returns aval=a5 with bval overwritten to 0 (the lab pre-poisons it with 0xDEAD).

0.8Structs (Samples 12.28–12.29)

A packed struct is, for DPI, just a packed vector of its total width: it crosses as svBitVecVal* (or svLogicVecVal* if any member is 4-state) in canonical form. The first member declared occupies the most significant bits. Spear's pixel struct packed { bit [7:0] r, g, b; } is 24 bits with r in [23:16], g in [15:8], b in [7:0], all inside word 0.

typedef struct { unsigned char b, g, r; } *p_rgb;   // Sample 12.28: overlay, reversed order
void invert(svBitVecVal* v) {
  p_rgb rgb = (p_rgb)v;                             // little-endian: byte 0 = bits [7:0] = b
  rgb->r = ~rgb->r; rgb->g = ~rgb->g; rgb->b = ~rgb->b;
}
void invert_bits(svBitVecVal* v) { *v = ~*v & 0x00FFFFFFu; }   // portable: shifts and masks

LOG invert r=ed g=cb b=a9          <- 12,34,56 inverted (book version, x86)
LOG invert_bits r=12 g=34 b=56     <- inverted back (portable version)

The book's overlay works, and the book is honest about why: the struct lists the bytes backwards because x86 is little-endian. It is still a trap: it breaks on a big-endian host, and for a struct wider than 32 bits it depends on how fields straddle 32-bit words. The robust method treats the struct as a bit vector and extracts fields by bit position, with shifts or with Annex H's part-select helpers svGetPartselBit(dst, src, lsb, width) / svPutPartselBit(dst, value, lsb, width) (width ≤ 32).

typedef struct packed { bit [47:0] dst, src; bit [15:0] etype; } eth_hdr_t;   // 112 bits
import "DPI-C" function int  etype_of(input eth_hdr_t h);    // C: const svBitVecVal* h (4 words)
import "DPI-C" function void make_hdr(output eth_hdr_t h);

int etype_of(const svBitVecVal* h) { svBitVecVal e; svGetPartselBit(&e, h, 0, 16); return e; }
void make_hdr(svBitVecVal* h) {                     // dst=[111:64] src=[63:16] etype=[15:0]
  svPutPartselBit(h, 0x86DD,      0, 16);
  svPutPartselBit(h, 0xA0A0A0A0, 16, 32);  svPutPartselBit(h, 0xB0B0,     48, 16);
  svPutPartselBit(h, 0x55667788, 64, 32);  svPutPartselBit(h, 0x1122,     96, 16);
}

LOG etype c=00000800
LOG make_hdr dst=112255667788 src=b0b0a0a0a0a0 etype=86dd

Unpacked structs are different: the LRM allows them as DPI arguments when every member is a DPI-compatible type, mapped to a C struct with the same members (and the C compiler's padding). Verilator does not implement it:

%Error-UNSUPPORTED: structs.sv:10:50: Unsupported: DPI argument of type REFDTYPE 'ups_t'

Use a packed struct (a bit vector), or pass the members as separate arguments. Classes never cross: Spear's §12.6 already says to pack a class into a struct and unpack it on return (Sample 12.29's pack()/unpack() methods); that remains the pattern, and in UVM the pack_ints/unpack_ints field automation does the same job.

0.9Strings: in, out, returned (Samples 12.30–12.31)

An SV string is a dynamic object in the simulator's heap; C sees it as a NUL-terminated const char*. The generated prototypes tell the whole story:

extern int c_strlen(const char* s);                 // input string
extern const char* hex_static(int v);               // function string
extern void name_of(int code, const char** name);   // output string
extern void upcase(const char** s);                 // inout string

The ownership rules from §35.5.1.4 / H.6.6 (memory) and H.8.10 (strings), which every example in the lab follows:

• input: the pointer belongs to SV and is valid only during the call. C must not free it, must not write through it, and must copy the text if it needs it after returning (keep() uses strdup; SV then reassigns its variable and kept() still returns first).
• returned and output: C provides the pointer and keeps owning the memory; SV copies the characters into its own string and never frees C's pointer. So C must return memory that is still alive after the function returns: a string literal, a static buffer, or the heap. Never a local array.
• inout: C reads *s (SV's text) and, to change it, stores a new pointer in *s; SV copies from there. C never writes into SV's buffer.

const char* hex_static(int v) {                     // Sample 12.30: a static buffer is alive after return
  static char s[12];
  snprintf(s, sizeof s, "%08x", v);
  return s;
}
void name_of(int code, const char** name) {         // output: point at long-lived storage
  static const char* names[] = {"IDLE", "BUSY", "DONE"};
  *name = (code >= 0 && code < 3) ? names[code] : "???";
}

Spear worries (before Sample 12.31) that a static buffer breaks when one statement calls the function twice, e.g. $display(print(a), print(b)): if the simulator kept the pointers instead of copying, both would show the second result. His fix is a ring of buffers. Verilator copies a returned string into a std::string immediately, so even the single static buffer works there:

LOG static_two a=00001111 b=00002222     <- two calls in one $display, one static buffer
LOG ring a=00000001 b=00000002           <- Sample 12.31's ring buffer, same result

Do not rely on that if the code has to run elsewhere: when the copy happens is an implementation detail, Spear wrote Sample 12.31 because he met simulators where it mattered, and a ring of N buffers costs nothing. The real trap is the local array:

const char* to_hex(int v) {                         // ex/bug_str.c
  char s[12];                                       // dies when the function returns
  snprintf(s, sizeof s, "%08x", v);
  return s;
}

clang catches it at build time: warning: address of stack memory associated with local variable 's' returned [-Wreturn-stack-address]. Verilator shows C compiler warnings only in its build log, so read it (or add -CFLAGS -Werror=return-stack-address).

0.10Verilator 5.052 vs the LRM, for aggregates

§1 · ObjectivesWhat you can do after this step

• Write the import and the C prototype for fixed-size arrays of any element type, and say what the C pointer points at (Fig. 0.2).
• Choose input / inout / output for an array knowing exactly what C sees on entry and what SV gets back.
• Write C code for an open array that works for any size, any range, any direction (svLow…svHigh, svGetArrElemPtr*), and predict every query function for a given declaration.
• Explain why a raw element pointer is unsafe for packed elements narrower than 33 bits in Verilator, and use the canonical Get/Put…VecVal copies instead.
• Pass packed structs of any width and extract fields by bit position; know that Verilator rejects unpacked structs.
• Pass strings in all directions without dangling pointers or leaks.
• Work around Verilator's missing support for dynamic arrays and queues as open-array actuals.

Prerequisites: 02 (canonical svBitVecVal/svLogicVecVal, type table) and 03 (C-side state and lifetimes).

§2 · Exercises12 graded exercises, with solutions

★ basic · ★★ intermediate · ★★★ real design. Every solution with code is in lab/ex/ and checked by check.py; the numbers quoted come from the run.

import "DPI-C" function longint ex1_sum(input int a[]);

long long ex1_sum(const svOpenArrayHandle h) {
  long long s = 0;
  for (int i = svLow(h, 1); i <= svHigh(h, 1); i++) s += *(int*)svGetArrElemPtr1(h, i);
  return s;
}

int sum_bug(const svOpenArrayHandle h) {
  int s = 0;
  for (int i = 0; i < svSize(h, 1); i++) s += *(int*)svGetArrElemPtr1(h, i);
  return s;
}

void ex5_hist(const svOpenArrayHandle data, const svOpenArrayHandle hist) {
  for (int b = svLow(hist, 1); b <= svHigh(hist, 1); b++) *(int*)svGetArrElemPtr1(hist, b) = 0;
  for (int i = svLow(data, 1); i <= svHigh(data, 1); i++) {
    unsigned char v = *(unsigned char*)svGetArrElemPtr1(data, i);   // byte is SIGNED char
    (*(int*)svGetArrElemPtr1(hist, v >> 4))++;
  }
}

void ex7_swap_macs(svBitVecVal* h) {                // dst = [111:64], src = [63:16]
  svBitVecVal dl, dh, sl, shi;
  svGetPartselBit(&dl, h, 64, 32); svGetPartselBit(&dh, h, 96, 16);
  svGetPartselBit(&sl, h, 16, 32); svGetPartselBit(&shi, h, 48, 16);
  svPutPartselBit(h, sl, 64, 32);  svPutPartselBit(h, shi, 96, 16);
  svPutPartselBit(h, dl, 16, 32);  svPutPartselBit(h, dh, 48, 16);
}

const char* to_hex(int v) {
  char s[12];
  snprintf(s, sizeof s, "%08x", v);
  return s;
}

import "DPI-C" function int ex9_sum_n(input int chunk[256], input int n);
function automatic longint sum_dyn(const ref int d[]);
  int chunk[256];
  longint s = 0;
  for (int base = 0; base < d.size(); base += 256) begin
    int n = (d.size() - base < 256) ? d.size() - base : 256;
    for (int k = 0; k < n; k++) chunk[k] = d[base + k];
    s += ex9_sum_n(chunk, n);
  end
  return s;
endfunction

int ex10_matmul(const svOpenArrayHandle a, const svOpenArrayHandle b, const svOpenArrayHandle c) {
  int n = svSize(a, 1), k = svSize(a, 2), m = svSize(b, 2);
  if (svSize(b, 1) != k || svSize(c, 1) != n || svSize(c, 2) != m) return -1;
  for (int i = 0; i < n; i++)                       // 0-based OFFSETS, converted below
    for (int j = 0; j < m; j++) {
      int s = 0;
      for (int t = 0; t < k; t++)
        s += *(int*)svGetArrElemPtr2(a, svLow(a, 1) + i, svLow(a, 2) + t) *
             *(int*)svGetArrElemPtr2(b, svLow(b, 1) + t, svLow(b, 2) + j);
      *(int*)svGetArrElemPtr2(c, svLow(c, 1) + i, svLow(c, 2) + j) = s;
    }
  return 0;
}

void ex11_xor(const svOpenArrayHandle w, svBitVecVal* x) {   // x: 4 canonical words
  svBitVecVal e[4];
  memset(x, 0, 4 * sizeof(svBitVecVal));
  for (int i = svLow(w, 1); i <= svHigh(w, 1); i++) {
    svGetBitArrElem1VecVal(e, w, i);                // canonical copy, never a raw pointer
    for (int k = 0; k < 4; k++) x[k] ^= e[k];
  }
}

void ex12_shift_all(const svOpenArrayHandle v, int n) {
  for (int i = svLow(v, 1); i <= svHigh(v, 1); i++) {
    unsigned* p = (unsigned*)svGetArrElemPtr1(v, i);
    if (n >= 32 || n <= -32) *p = 0;                // C: shifting by >= the width is UB
    else if (n > 0) *p <<= n;
    else if (n < 0) *p >>= -n;
  }
}

§3 · Quiz14 questions, self-grading

§4 · LabEverything above, measured

Directory 04_arrays_structs_strings/lab/. One self-checking testbench per topic, top module top, Verilator 5.052 (--binary --timing, flags in ../../common/lab.sh).

cd tutorial/04_arrays_structs_strings/lab
python3 check.py          # builds everything in parallel, runs, asserts (69 checks)
python3 check.py --no-run # re-check the logs in build/ only

Predict before you run: (1) the eleven query values for int up[0:2][0:3]; (2) whether static_two prints two different strings; (3) the bytes per element for bit [12:0]; (4) which of the four kinds builds fail.

Things worth opening by hand: build/vl_strings/Vtop__Dpi.h (the string prototypes), build/k_dyn.build (the unsupported message), and build/bug_str.build (clang's warning, buried in the make output).

§5 · Cheat sheetOne table, ten rules

1. SV owns all argument storage; C borrows it until return.
2. Read the prototype from V<top>__Dpi.h, and #include it.
3. output = C writes everything; otherwise inout.
4. Open-array loops run svLow…<= svHigh on SV indices.
5. svIncrement is not a loop step.
6. Memory order of unpacked arrays is the simulator's business: use svGetArrElemPtr* unless you checked svGetArrayPtr.
7. Packed elements: canonical copies (…VecVal), not raw pointers.
8. Packed structs: bit positions, first member = MSBs.
9. Verilator: no dynamic arrays, queues, slices or unpacked structs as DPI arguments; no 4-state.
10. Strings: copy what comes in, return what stays alive.