GPI Library Reference

cocotb contains a native library called GPI (Generic Procedural Interface) that is an abstraction layer for the VPI, VHPI, and FLI simulator interfaces.

The interaction between cocotb’s Python and GPI is via a Python extension module called the PyGPI.

Environment Variables

GPI_USERS

A list of native libraries to load, and optionally functions in those libraries to call, once the GPI is initialized.

This list is ;-separated. Each element of the list contains a path to a library to load. These paths can be full paths (e.g. /usr/local/lib/libstuff.so), in which case the exact library will be loaded, or the basename (e.g. libstuff.so), in which case your operating system’s dynamic library lookup will be used.

Optionally, after the path in each element, a function in that library to call can be specified by name by suffixing the path with a , character followed by the function name.

For example:

• GPI_USERS=/usr/local/lib/libstuff.so;libotherstuff.so,entry_func

Attention

This means that paths which contain the characters ; and , cannot be used in this variable. Instead of using a full path, use the basename, and use environment variables like PATH or LD_LIBRARY_PATH to modify your operating system’s library search path.

When using the Makefile-based Build System and Test Runner or Python Test Runner this defaults to load libpython and then the PyGPI entry point. You can get the default PyGPI entry point at other times by calling cocotb-config --pygpi-entry-point from the shell or cocotb_tools.config.pygpi_entry_point() from Python.

GPI_EXTRA

A comma-separated list of extra libraries that are dynamically loaded at runtime. A function from each of these libraries will be called as an entry point prior to elaboration, allowing these libraries to register system functions and callbacks. Note that HDL objects cannot be accessed at this time. An entry point function must be named following a : separator, which follows an existing simulator convention.

For example:

• GPI_EXTRA=libnameA.so:entryA,libnameB.so:entryB will first load libnameA.so with entry point entryA , then load libnameB.so with entry point entryB.

Changed in version 1.4: Support for the custom entry point via : was added. Previously : was used as a separator between libraries instead of ,.

Changed in version 1.5: Library name must be fully specified. This allows using relative or absolute paths in library names, and loading from libraries that aren’t prefixed with “lib”. Paths should not contain commas.

C API

Generic Procedural Interface

This header file defines the GPI to interface with any simulator that supports VPI, VHPI, or FLI.

Implementations need to implement the underlying functions in gpi_priv.h. The functions are essentially a limited subset of VPI/VHPI/FLI.

Implementation-specific notes

By amazing coincidence, VPI and VHPI are strikingly similar which is obviously reflected by this header file. Unfortunately, this means that proprietary, non-standard, less featured language interfaces (for example Mentor FLI) may have to resort to some hackery.

Because of the lack of ability to register a callback on event change using the FLI, we have to create a process with the signal on the sensitivity list to imitate a callback.

User Handles

These types and functions are about handles the GPI provides to users for interacting with GPI-managed objects.

typedef struct GpiObjHdl *gpi_sim_hdl

Handle to simulation object, such as a signal.

typedef struct GpiIterator *gpi_iterator_hdl

Handle to iterator object.

Used to iterate over child handles of a smulation object.

typedef struct GpiCbHdl *gpi_cb_hdl

Handle to callback object.

GPI Functionality

Simulator Control and Interrogation

group Simulator Control and Interrogation

These functions are for controlling and querying simulator state and information.

Functions

GPI_EXPORT bool gpi_has_registered_impl(void)

Check if there is a registered GPI implementation.

Useful for checking if a simulator is running.

Returns:

1 if there is a registered GPI implementation, 0 otherwise.

GPI_EXPORT void gpi_finish(void)

Stop the simulation after control returns to the GPI.

GPI_EXPORT void gpi_get_sim_time(uint32_t *high, uint32_t *low)

Get the simulation time as two 32-bit uints.

The value is in default simulation time units, which can be retrieved with gpi_get_sim_precision.

Parameters:

• high – Location to return high bits of current simulation time.

• low – Location to return low bits of current simulation time.

GPI_EXPORT void gpi_get_sim_precision(int32_t *precision)

Get the simulation time precision.

Parameters:

precision – Location to return time precision. The value is scientific notation in terms of seconds. So a value of -9 is nanosecond precision.

GPI_EXPORT const char *gpi_get_simulator_product(void)

Get the running simulator product information.

Returns:

The simulator product string.

GPI_EXPORT const char *gpi_get_simulator_version(void)

Get the running simulator version string.

Returns:

The simulator version string.

GPI_EXPORT int gpi_get_simulator_args(int *argc, char const *const **argv)

Return the arguments to the simulator executable call.

Parameters:

• argc – Pointer to store argument count.

• argv – Pointer to store argument values.

Returns:

Zero on success, non-zero on failure.

Simulation Object Query

group Simulation Object Query

These functions are for getting handles to simulation objects.

Enums

enum gpi_discovery

Object discovery method when searching by name.

Values:

enumerator GPI_AUTO

enumerator GPI_NATIVE

Functions

GPI_EXPORT gpi_sim_hdl gpi_get_root_handle(const char *name)

Get a handle to the root simulation object.

Parameters:

name – Name of the root object, or NULL.

Returns:

Handle to simulation object or NULL if not found.

GPI_EXPORT gpi_sim_hdl gpi_get_handle_by_name(

gpi_sim_hdl parent,

const char *name,

gpi_discovery discovery_method

)

Get a handle to a child simulation object by its name.

Parameters:

• parent – Parent object handle.

• name – Name of the child object. This should not be a path, but only the name of a direct child object.

• discovery_method – Object discovery method.

Returns:

Handle to simulation object or NULL if not found.

GPI_EXPORT gpi_sim_hdl gpi_get_handle_by_index(

gpi_sim_hdl parent,

int32_t index

)

Get a handle to a child simulation object by its index.

Parameters:

• parent – Parent indexable object handle.

• index – Index of the child object.

Returns:

Handle to simulation object or NULL if not found.

General Object Properties

group General Object Properties

These functions are for getting and setting properties of a simulation object.

Enums

enum gpi_objtype

GPI simulation object types.

Values:

enumerator GPI_UNKNOWN

enumerator GPI_MEMORY

enumerator GPI_MODULE

enumerator GPI_ARRAY

enumerator GPI_ENUM

enumerator GPI_STRUCTURE

enumerator GPI_REAL

enumerator GPI_INTEGER

enumerator GPI_STRING

enumerator GPI_GENARRAY

enumerator GPI_PACKAGE

enumerator GPI_PACKED_STRUCTURE

enumerator GPI_LOGIC

enumerator GPI_LOGIC_ARRAY

enum gpi_range_dir

Direction of range constraint of an object.

Values:

enumerator GPI_RANGE_DOWN

enumerator GPI_RANGE_NO_DIR

enumerator GPI_RANGE_UP

Functions

GPI_EXPORT gpi_objtype gpi_get_object_type(gpi_sim_hdl obj_hdl)

Returns:

The type of the simulation object.

GPI_EXPORT const char *gpi_get_definition_name(gpi_sim_hdl obj_hdl)

Returns:

Definition name of the simulation object.

GPI_EXPORT const char *gpi_get_definition_file(gpi_sim_hdl obj_hdl)

Returns:

Definition file of the simulation object.

GPI_EXPORT int gpi_get_num_elems(gpi_sim_hdl gpi_sim_hdl)

Returns:

The number of objects in the collection of the handle.

GPI_EXPORT int gpi_get_range_left(gpi_sim_hdl gpi_sim_hdl)

Returns:

The left side of the range constraint.

GPI_EXPORT int gpi_get_range_right(gpi_sim_hdl gpi_sim_hdl)

Returns:

The right side of the range constraint.

GPI_EXPORT gpi_range_dir gpi_get_range_dir(gpi_sim_hdl gpi_sim_hdl)

Returns:

The direction of the range constraint: +1 for ascending, -1 for descending, 0 for undefined.

GPI_EXPORT int gpi_is_constant(gpi_sim_hdl obj_hdl)

Determine whether an object value is constant (parameters / generics etc).

Returns:

1 if the object value is constant, 0 otherwise.

GPI_EXPORT int gpi_is_indexable(gpi_sim_hdl obj_hdl)

Determine whether an object is indexable.

Returns:

1 if the object value is indexable, 0 otherwise.

GPI_EXPORT int gpi_is_signed(gpi_sim_hdl obj_hdl)

Determine whether integer object is signed.

Returns:

1 if the integer object is signed, 0 if unsigned, -1 if unknown or not applicable.

Signal Object Properties

group Signal Object Properties

These functions are for getting and setting properties of a signal object.

Enums

enum gpi_set_action

Action to use when setting object value.

Values:

enumerator GPI_DEPOSIT

enumerator GPI_FORCE

enumerator GPI_RELEASE

enumerator GPI_NO_DELAY

Functions

GPI_EXPORT const char *gpi_get_signal_value_binstr(gpi_sim_hdl sig_hdl)

Get signal object value as a binary string.

Parameters:

sig_hdl – Signal object handle.

Returns:

Object value.

GPI_EXPORT const char *gpi_get_signal_value_str(gpi_sim_hdl sig_hdl)

Get signal object value as a byte array.

Parameters:

sig_hdl – Signal object handle.

Returns:

Object value. Null-terminated byte array.

GPI_EXPORT double gpi_get_signal_value_real(gpi_sim_hdl sig_hdl)

Get signal object value as a real.

Parameters:

sig_hdl – Signal object handle.

Returns:

Object value.

GPI_EXPORT long gpi_get_signal_value_long(gpi_sim_hdl sig_hdl)

Get signal object value as a long.

Parameters:

sig_hdl – Signal object handle.

Returns:

Object value.

GPI_EXPORT const char *gpi_get_signal_name_str(gpi_sim_hdl sig_hdl)

Get signal object name.

Parameters:

sig_hdl – Signal object handle.

Returns:

Object name.

GPI_EXPORT const char *gpi_get_signal_type_str(gpi_sim_hdl sig_hdl)

Get signal object type as a string.

Parameters:

sig_hdl – Signal object handle.

Returns:

Object type as a string.

GPI_EXPORT void gpi_set_signal_value_real(

gpi_sim_hdl sig_hdl,

double value,

gpi_set_action action

)

Set signal object value with a real.

Parameters:

• sig_hdl – Signal object handle.

• value – Object value.

• action – Action to use.

GPI_EXPORT void gpi_set_signal_value_int(

gpi_sim_hdl sig_hdl,

int32_t value,

gpi_set_action action

)

Set signal object value with an int.

Parameters:

• sig_hdl – Signal object handle.

• value – Object value.

• action – Action to use.

GPI_EXPORT void gpi_set_signal_value_binstr(

gpi_sim_hdl sig_hdl,

const char *str,

gpi_set_action action

)

Set signal object value with a binary string.

Parameters:

• sig_hdl – Signal object handle.

• str – Object value. Null-terminated string of binary characters in [1, 0, x, z].

• action – Action to use.

GPI_EXPORT void gpi_set_signal_value_str(

gpi_sim_hdl sig_hdl,

const char *str,

gpi_set_action action

)

Set signal object value with a byte array.

Parameters:

• sig_hdl – Signal object handle.

• str – Object value. Null-terminated byte array.

• action – Action to use.

Simulation Object Iteration

group Simulation Object Iteration

These functions are for iterating over simulation object handles to discover child objects.

Enums

enum gpi_iterator_sel

Types of child objects to search for when iterating.

Values:

enumerator GPI_OBJECTS

enumerator GPI_DRIVERS

enumerator GPI_LOADS

enumerator GPI_PACKAGE_SCOPES

Functions

GPI_EXPORT gpi_iterator_hdl gpi_iterate(

gpi_sim_hdl base,

gpi_iterator_sel type

)

Start iteration on a simulation object.

Unlike vpi_iterate() the iterator handle may only be NULL if the type is not supported. If no objects of the requested type are found, an empty iterator is returned.

Parameters:

• base – Simulation object to iterate over.

• type – Iteration type.

Returns:

An iterator handle which can then be used with gpi_next.

GPI_EXPORT gpi_sim_hdl gpi_next(gpi_iterator_hdl iterator)

Get next object in iteration.

Parameters:

iterator – Iterator handle.

Returns:

Object handle, or NULL when there are no more objects.

Simulation Callbacks

group Simulation Callbacks

These functions are for registering and controlling callbacks.

Typedefs

typedef void (*gpi_finalize_callback)(void *cb_data)

Type of a GPI finalization callback.

Param cb_data:

Pointer to user data to be passed to callback function.

Enums

enum gpi_edge

Type of value change to match when registering for callback.

Values:

enumerator GPI_VALUE_CHANGE

enumerator GPI_RISING

enumerator GPI_FALLING

Functions

GPI_EXPORT gpi_cb_hdl gpi_register_timed_callback(

int (*gpi_function)(void*),

void *gpi_cb_data,

uint64_t time

)

Register a timed callback.

Parameters:

• gpi_function – Callback function pointer.

• gpi_cb_data – Pointer to user data to be passed to callback function.

• time – Time delay in simulation time units.

Returns:

Handle to callback object.

GPI_EXPORT gpi_cb_hdl gpi_register_value_change_callback(

int (*gpi_function)(void*),

void *gpi_cb_data,

gpi_sim_hdl sig_hdl,

gpi_edge edge

)

Register a value change callback.

Parameters:

• gpi_function – Callback function pointer.

• gpi_cb_data – Pointer to user data to be passed to callback function.

• sig_hdl – Simulation object to monitor for value change.

• edge – Type of value change to monitor for.

Returns:

Handle to callback object.

GPI_EXPORT gpi_cb_hdl gpi_register_readonly_callback(

int (*gpi_function)(void*),

void *gpi_cb_data

)

Register a readonly simulation phase callback.

Callback will be called when simulation next enters the readonly phase.

Parameters:

• gpi_function – Callback function pointer.

• gpi_cb_data – Pointer to user data to be passed to callback function.

Returns:

Handle to callback object.

GPI_EXPORT gpi_cb_hdl gpi_register_nexttime_callback(

int (*gpi_function)(void*),

void *gpi_cb_data

)

Register a next timestep simulation phase callback.

Callback will be called when simulation next enters the next timestep.

Parameters:

• gpi_function – Callback function pointer.

• gpi_cb_data – Pointer to user data to be passed to callback function.

Returns:

Handle to callback object.

GPI_EXPORT gpi_cb_hdl gpi_register_readwrite_callback(

int (*gpi_function)(void*),

void *gpi_cb_data

)

Register a readwrite simulation phase callback.

Callback will be called when simulation next enters the readwrite phase.

Parameters:

• gpi_function – Callback function pointer.

• gpi_cb_data – Pointer to user data to be passed to callback function.

Returns:

Handle to callback object.

GPI_EXPORT int gpi_register_start_of_sim_time_callback(

int (*cb)(void*),

void *cb_data

)

Register a callback to run at the start of simulation time.

Parameters:

• cb – Callback function pointer.

• cb_data – Pointer to user data to be passed to callback function.

Returns:

Zero on success, non-zero on failure.

GPI_EXPORT int gpi_register_end_of_sim_time_callback(

void (*cb)(void*),

void *cb_data

)

Register a callback to run at the end of simulation time.

Parameters:

• cb – Callback function pointer.

• cb_data – Pointer to user data to be passed to callback function.

Returns:

Zero on success, non-zero on failure.

GPI_EXPORT int gpi_register_finalize_callback(

gpi_finalize_callback cb,

void *cb_data

)

Register a callback to run just before the GPI terminates.

Parameters:

• cb – Callback function pointer.

• cb_data – Pointer to user data to be passed to callback function.

Returns:

Handle to callback object.

GPI_EXPORT int gpi_remove_cb(gpi_cb_hdl cb_hdl)

Remove callback.

The callback will not fire after this function is called. The handle is no longer valid if this function succeeds.

Parameters:

cb_hdl – The handle to the callback to remove.

Returns:

0 on successful removal, 1 otherwise.

GPI_EXPORT void gpi_get_cb_info(

gpi_cb_hdl cb_hdl,

int (**cb_func)(void*),

void **cb_data

)

Retrieve user callback information from callback handle.

This function cannot fail.

Parameters:

• cb_hdl – The handle to the callback.

• cb_func – Where the user callback function should be placed.

• cb_data – Where the user callback function data should be placed.

Logging Dependency Injection

group GPI Logging Dependency Injection

These functions are for registering logging implementations into the GPI for its logging.

Typedefs

typedef void (*gpi_log_handler_ftype)(void *userdata, const char *name, enum gpi_log_level level, const char *pathname, const char *funcname, long lineno, const char *msg, va_list args)

Type of a logger handler function.

Param userdata:

Private implementation data registered with this function

Param name:

Name of the logger

Param level:

Level at which to log the message

Param pathname:

Name of the file where the call site is located

Param funcname:

Name of the function where the call site is located

Param lineno:

Line number of the call site

Param msg:

The message to log, uses C-sprintf-style format specifier

Param args:

Additional arguments; formatted and inserted in message according to format specifier in msg argument

Enums

enum gpi_log_level

Named logging level.

The native logger only logs level names at these log level values. They were specifically chosen to align with the default level values in the Python logging module. Implementers of custom loggers should emit human readable level names for these value, but may support other values.

Values:

enumerator GPI_NOTSET

Lets the parent logger in the hierarchy decide the effective log level.

By default this behaves like INFO.

enumerator GPI_TRACE

Prints TRACE by default.

Information about execution of simulator callbacks and Python/simulator contexts.

enumerator GPI_DEBUG

Prints DEBUG by default.

Verbose information, useful for debugging.

enumerator GPI_INFO

Prints INFO by default.

Information about major events in the current program.

enumerator GPI_WARNING

Prints WARN by default.

Encountered a recoverable bug, or information about surprising behavior.

enumerator GPI_ERROR

Prints ERROR by default. An unrecoverable error.

enumerator GPI_CRITICAL

Prints CRITICAL by default.

An unrecoverable error, to be followed by immediate simulator shutdown.

Functions

GPI_EXPORT void gpi_get_log_handler(

gpi_log_handler_ftype *handler,

void **userdata

)

Retrieve the current log handler.

Parameters:

• handler – Location to return current log handler function.

• userdata – Location to return log handler userdata.

GPI_EXPORT void gpi_set_log_handler(

gpi_log_handler_ftype handler,

void *userdata

)

Set custom log handler.

Parameters:

• handler – Logger handler function.

• userdata – Data passed to the above functions.

GPI_EXPORT int gpi_native_logger_set_level(enum gpi_log_level level)

Set minimum logging level of the native logger.

If a logging request occurs where the logging level is lower than the level set by this function, it is not logged. Only affects the native logger.

Parameters:

level – Logging level

Returns:

Previous logging level