API

API#

C++ types and callbacks in the spice_vpi namespace. Source is under cpp/.

namespace spice_vpi#

Functions

static vpiHandle distinct_handle(vpiHandle net, vpiHandle other)#
static std::string to_lower_copy(std::string s)#
static vpiHandle lookup_by_name(const std::string &name, vpiHandle scope)#
static std::string parent_path(const std::string &instance_name)#
static std::string instance_leaf(const std::string &instance_name)#
static std::string trailing_digits(const std::string &name)#
static vpiHandle scan_scope_alias(vpiHandle scope, vpiHandle net, const std::string &port_name)#
static vpiHandle lookup_named_alias(vpiHandle net, const std::string &name, const std::string &parent)#
static vpiHandle find_top_alias(vpiHandle net, const std::string &port_name, const std::string &instance_name)#
static void put_instance_and_top(vpiHandle inst, vpiHandle top, s_vpi_value *val, PLI_INT32 flags)#
int ng_sync(double actual_time, double *delta_time, double old_delta_time, int redostep, int identification_number, int location, void *user_data)#

NGSPICE callback functions for communication with the SPICE simulator.

These functions are called by NGSPICE during simulation to:

  • Synchronize time steps between HDL and SPICE

  • Exchange signal data between simulators

  • Handle NGSPICE output and status

NGSPICE synchronization callback

Called by NGSPICE at each simulation step to coordinate timing and handle redo operations when HDL signals change.

Parameters:

  • actual_time – Current SPICE simulation time

  • delta_time – Pointer to next time step delta

  • old_delta_time – Previous time step delta

  • redostep – Redo step flag

  • identification_number – Identification number

  • location – Location indicator (0=end step, 1=begin step)

  • user_data – User data pointer

Returns:

0 for normal operation, 1 for redo request

int ng_srcdata(double *vp, double time, char *source, int id, void *udp)#

NGSPICE source data callback.

Called by NGSPICE to get input signal values from HDL simulator.

Parameters:

  • vp – Pointer to voltage value to be set

  • time – Current SPICE time

  • source – Source name (signal name)

  • id – Source identifier

  • udp – User data pointer

Returns:

0 on success

int ng_printf(char *output, int ident, void *userdata)#

NGSPICE printf callback.

Called by NGSPICE to output messages and status information.

Parameters:

  • output – Output string from NGSPICE

  • ident – Indentation level

  • userdata – User data pointer

Returns:

0 on success

int ng_exit(int status, bool immediate, bool quit, int id, void *data)#

NGSPICE exit callback.

Called when NGSPICE simulation terminates.

Parameters:

  • status – Exit status

  • immediate – Immediate exit flag

  • quit – Quit flag

  • id – Process identifier

  • data – User data pointer

Returns:

0 on success

void register_vpi_callbacks(void)#

Register VPI callbacks.

Registers all necessary VPI callbacks with the HDL simulator. This function is called during VPI initialization.

auto vpi_port_change_cb(p_cb_data cb_data_p)#

Port change callback.

Called when HDL signals change. Triggers synchronization with SPICE simulator.

Parameters:

cb_data_p – Callback data structure

Returns:

0 on success

auto vpi_timestep_cb(p_cb_data cb_data_p)#

Timestep callback.

Called at each HDL time step to synchronize with SPICE and update signal values.

Parameters:

cb_data_p – Callback data structure

Returns:

0 on success

auto vpi_start_of_sim_cb(p_cb_data cb_data_p)#

VPI callback functions for HDL simulator integration.

These functions are called by the VPI interface during HDL simulation to:

  • Initialize and cleanup the SPICE bridge

  • Handle signal changes and time synchronization

  • Manage simulation flow between HDL and SPICE

Start of simulation callback

Called when HDL simulation starts. Initializes NGSPICE, sets up ports, and starts the co-simulation.

Parameters:

cb_data_p – Callback data structure

Returns:

0 on success, non-zero on error

auto vpi_end_of_sim_cb(p_cb_data cb_data_p)#

End of simulation callback.

Called when HDL simulation ends. Cleans up NGSPICE and saves results.

Parameters:

cb_data_p – Callback data structure

Returns:

0 on success

class AnalogDigitalInterface#
#include <AnalogDigitalInterface.h>

Manages the interface between analog (SPICE) and digital (HDL) signals.

This class handles:

  • Port discovery and management

  • Signal conversion between analog voltages and digital logic levels

  • Thread-safe access to port data

  • Synchronization between SPICE and HDL simulators

Public Functions

explicit AnalogDigitalInterface(const Config::Settings &config)#

Constructor.

Parameters:

config – Configuration settings to use for signal conversion

vpiHandle add_port(vpiHandle port, const std::string &instance_name = {})#

Add a port to be managed by this interface.

Parameters:

port – VPI handle to the port

Returns:

Distinct parent/TOP net cocotb samples, or nullptr

void set_analog_input(const char *name, double *value)#

Set analog input value (from digital side)

Parameters:

  • name – Port name

  • value – Pointer to receive the analog value

void analog_outputs_update()#

Update analog output values from SPICE.

void set_digital_output()#

Set digital output values (to digital side)

inline void set_always_put_outputs(bool always)#
void digital_input_update(vpiHandle handle)#

Update when digital input changes (called from VPI callback)

Parameters:

handle – VPI handle to the changed signal

std::vector<std::string> get_analog_input_names() const#

Get all analog input names (for SPICE iteration)

Returns:

Vector of port names

void print_status() const#

Print debug status information.

void update_all_digital_inputs()#

Update all digital inputs.

class Config#
#include <Config.h>

Configuration manager for SPICE-VPI bridge.

Handles reading and validating environment variables and configuration

Public Static Functions

static Settings load_from_environment()#

Load configuration from environment variables.

Throws:

std::runtime_error – if required environment variables are missing

Returns:

Configuration settings

static void validate(const Settings &settings)#

Validate configuration settings.

Parameters:

settings – Configuration to validate

Throws:

std::invalid_argument – if configuration is invalid

struct Settings#

Public Members

std::string spice_netlist_path#
std::vector<std::string> hdl_instance_names#
bool full_path_discovery = false#
double vcc_voltage = 1.0#
double logic_threshold_low = 0.3#
double logic_threshold_high = 0.7#
double min_analog_change_threshold = 1e-9#
unsigned long long time_precision = 1e12#
template<typename TimeT>
class TimeBarrier#
#include <TimeBarrier.h>

Two-party virtual-time synchronization barrier with shutdown support.

Coordinates time progression between two simulation engines (HDL and SPICE). Each engine calls update() with its current time. If one engine gets ahead, it blocks until the other catches up or shutdown is called.

Template Parameters:

TimeT – Time type (typically unsigned long long for femtosecond precision)

Public Functions

inline TimeBarrier()#
bool update(int engine_id, TimeT current_time)#

Update time for one engine and wait for synchronization.

Parameters:

  • engine_id – Engine identifier (HDL_ENGINE_ID or SPICE_ENGINE_ID)

  • current_time – Current virtual time for this engine

Returns:

false if barrier was shut down before sync completed

void update_no_wait(int engine_id, TimeT current_time)#

Update time without waiting for synchronization.

Parameters:

  • engine_id – Engine identifier

  • current_time – Current virtual time for this engine

TimeT get_time(int engine_id) const#

Get current time for specified engine.

Parameters:

engine_id – Engine identifier

Returns:

Current time for the engine

void shutdown()#

Signal shutdown to wake all waiting threads.

bool is_shutdown() const#

Check if barrier has been shut down.

void set_needs_redo(bool needs_redo)#
bool needs_redo() const#
void set_next_spice_step_time(TimeT time)#
TimeT get_next_spice_step_time() const#
void request_spice_point(TimeT time)#
TimeT get_hdl_request_time() const#

Public Static Attributes

static constexpr int HDL_ENGINE_ID = 0#
static constexpr int SPICE_ENGINE_ID = 1#