Types, outputs and a status code

Widths belong to the type

A SystemVerilog int is 32 bits, on every simulator. The C side has to use a type of the same width, and the generated header tells you which one. Do not swap int for long because it looks roomier. A C long is 32 bits on Windows and 64 bits on Linux, so the same bridge would read different bytes on each. Fixed-width types such as int64_t are the safe choice for anything wider than the argument itself.

Signedness crosses with the type. byte is signed, so the byte c8 reaches C as -56; byte unsigned sends 200. Pick the SystemVerilog type that says what the value means, and the C type follows from the header.

An output argument is an address

In status = checked_sum(100, 23, result), the two inputs are copied into C. The output is different: C receives the address of result and writes the sum through it. The integer that comes back as the return value is the status, 0 for a valid sum and 1 for a sum out of range. The status is never the sum.

Set the output on every path, failure included. A caller that forgets to check the status then sees 0 rather than whatever the variable held before the call. A stale value looks like an answer; a zero after a status of 1 is at least consistent.

Widen before you add

The range check has to happen in a wider type. Casting after a + b is too late: the 32-bit addition may already have overflowed, and C makes no promise about what it produced. Convert a to int64_t first, add b there, compare against INT_MIN and INT_MAX, and narrow only when the value fits.

const int64_t wide = a + b;  // the int addition already happened
if (wide > INT_MAX) return 1;

const int64_t wide = static_cast<int64_t>(a) + b;
if (wide > INT_MAX || wide < INT_MIN) return 1;

1. A sum that fits

   C writes the narrowed value through the pointer and returns 0.

   100 + 23	123
   status	0

2. A sum out of range

   The 64-bit sum is 2147483648, above INT_MAX. C leaves result at 0 and returns 1.

   2147483647 + 1	2147483648 in int64_t
   status / result	1 / 0

A status is the agreed answer for failure

Give every C routine one documented way to say this call failed. Here it is the return value: 0 means the output is valid and 1 means out of range. In SystemVerilog, check the status before you read the output; a zero in result is a placeholder, never a sum.

A C++ library that throws needs a wrapper. An exception that leaves the DPI routine has nowhere to go: the simulator is C code that never expected one, and the run ends. Catch the documented exceptions inside the wrapper and turn each into a status and a message. The same goes for a C library that reports errors through a global: read it in the wrapper and hand the testbench a status.

Try it

Run it, then add an underflow check with 32'sh80000000 and -1, expecting status 1 and result 0, and a boundary check with 32'sh7fffffff and 0, expecting status 0 and result 2147483647. The two reach different paths in the C routine.

Then change the output declaration to output longint result and run again. The build stops in the bridge: the header now says long long* while the definition says int*.

#include "Vtb__Dpi.h"
#include "svdpi.h"
#include <cstdint>
#include <climits>
#include <cstring>
extern "C" int checked_sum(int a, int b, int* result) {
  // Widen first: the sum of two ints always fits in 64 bits.
  const int64_t wide = static_cast<int64_t>(a) + b;
  *result = 0;                       // the output is set on every path, failure included
  if (wide > INT_MAX || wide < INT_MIN) return 1;
  *result = static_cast<int>(wide);  // narrow only after the range check
  return 0;
}

Check yourself

`timescale 1ns/1ps
module tb;
  import "DPI-C" function int checked_sum(input int a, b, output int result);
  int result, status;
  initial begin
    status = checked_sum(2147483647, 0, result);
    $display("%0d %0d", status, result);
    $finish;
  end
endmodule

#include "Vtb__Dpi.h"
#include "svdpi.h"
#include <cstdint>
#include <climits>
#include <cstring>
extern "C" int checked_sum(int a, int b, int* result) {
  // Widen first: the sum of two ints always fits in 64 bits.
  const int64_t wide = static_cast<int64_t>(a) + b;
  *result = 0;                       // the output is set on every path, failure included
  if (wide > INT_MAX || wide < INT_MIN) return 1;
  *result = static_cast<int>(wide);  // narrow only after the range check
  return 0;
}

function automatic int add_or_zero(input int a, b);
    longint w = longint'(a) + longint'(b);
    if (w > 64'sd2147483647 || w < -64'sd2147483648) return 0;
    return int'(w);
  endfunction

function automatic int add_or_zero(input int a, b);
    return plain_sum(a, b);
  endfunction

function automatic int add_or_zero(input int a, b);
    int r, s;
    s = checked_sum(a, b, r);
    return (s == 0) ? r : 0;
  endfunction

function automatic int add_or_zero(input int a, b);
    int r;
    if (checked_sum(a, b, r) != 0) return 0;
    return r;
  endfunction

#include "Vtb__Dpi.h"
#include "svdpi.h"
#include <cstdint>
#include <climits>
#include <cstring>
extern "C" int plain_sum(int a, int b) { return a + b; }
extern "C" int checked_sum(int a, int b, int* result) {
  const int64_t wide = static_cast<int64_t>(a) + b;
  *result = 0;
  if (wide > INT_MAX || wide < INT_MIN) return 1;
  *result = static_cast<int>(wide);
  return 0;
}