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

LIBPYTHON_LOC

The absolute path to the Python library associated with the current Python installation; i.e. libpython.so or python.dll on Windows. This is determined with cocotb-config --libpython during build.

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.

Defines

GPI_EXPORT COCOTB_IMPORT

Typedefs

typedef struct GpiObjHdl *gpi_sim_hdl

typedef struct GpiCbHdl *gpi_cb_hdl

typedef struct GpiIterator *gpi_iterator_hdl

Enums

enum gpi_discovery

Object discovery method when searching by name.

Values:

enumerator GPI_AUTO

enumerator GPI_NATIVE

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_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

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

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

enum gpi_edge

Type of value change to match when registering for callback.

Values:

enumerator GPI_RISING

enumerator GPI_FALLING

enumerator GPI_VALUE_CHANGE

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_sim_end(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.

group Simulation Object Query

These functions are for getting handles to simulation objects.

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.

group General Object Properties

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

Functions

GPI_EXPORT gpi_objtype gpi_get_object_type(gpi_sim_hdl gpi_hdl)

Returns:

The type of the simulation object.

GPI_EXPORT const char *gpi_get_definition_name(gpi_sim_hdl gpi_hdl)

Returns:

Definition name of the simulation object.

GPI_EXPORT const char *gpi_get_definition_file(gpi_sim_hdl gpi_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 gpi_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 gpi_hdl)

Determine whether an object is indexable.

Returns:

1 if the object value is indexable, 0 otherwise.

group Signal Object Properties

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

Functions

GPI_EXPORT const char *gpi_get_signal_value_binstr(gpi_sim_hdl gpi_hdl)

Get signal object value as a binary string.

Parameters:

gpi_hdl – Signal object handle.

Returns:

Object value.

GPI_EXPORT const char *gpi_get_signal_value_str(gpi_sim_hdl gpi_hdl)

Get signal object value as a byte array.

Parameters:

gpi_hdl – Signal object handle.

Returns:

Object value. Null-terminated byte array.

GPI_EXPORT double gpi_get_signal_value_real(gpi_sim_hdl gpi_hdl)

Get signal object value as a real.

Parameters:

gpi_hdl – Signal object handle.

Returns:

Object value.

GPI_EXPORT long gpi_get_signal_value_long(gpi_sim_hdl gpi_hdl)

Get signal object value as a long.

Parameters:

gpi_hdl – Signal object handle.

Returns:

Object value.

GPI_EXPORT const char *gpi_get_signal_name_str(gpi_sim_hdl gpi_hdl)

Get signal object name.

Parameters:

gpi_hdl – Signal object handle.

Returns:

Object name.

GPI_EXPORT const char *gpi_get_signal_type_str(gpi_sim_hdl gpi_hdl)

Get signal object type as a string.

Parameters:

gpi_hdl – Signal object handle.

Returns:

Object type as a string.

GPI_EXPORT void gpi_set_signal_value_real(

gpi_sim_hdl gpi_hdl,

double value,

gpi_set_action action

)

Set signal object value with a real.

Parameters:

• gpi_hdl – Signal object handle.

• value – Object value.

• action – Action to use.

GPI_EXPORT void gpi_set_signal_value_int(

gpi_sim_hdl gpi_hdl,

int32_t value,

gpi_set_action action

)

Set signal object value with an int.

Parameters:

• gpi_hdl – Signal object handle.

• value – Object value.

• action – Action to use.

GPI_EXPORT void gpi_set_signal_value_binstr(

gpi_sim_hdl gpi_hdl,

const char *str,

gpi_set_action action

)

Set signal object value with a binary string.

Parameters:

• gpi_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 gpi_hdl,

const char *str,

gpi_set_action action

)

Set signal object value with a byte array.

Parameters:

• gpi_hdl – Signal object handle.

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

• action – Action to use.

group Simulation Object Iteration

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

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.

group Simulation Callbacks

These functions are for registering and controlling callbacks.

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 gpi_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.

• gpi_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_remove_cb(gpi_cb_hdl cb_hdl)

Remove callback.

The callback will not fire after this function is called. The argument 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.