GPI Library Reference

GPI Library Reference#

Cocotb contains a library called GPI (in directory src/cocotb/share/lib/gpi/) written in C++ that is an abstraction layer for the VPI, VHPI, and FLI simulator interfaces.

_images/cocotb_overview.svg

The interaction between Python and GPI is via a Python extension module called simulator (in directory src/cocotb/share/lib/simulator/) which provides routines for traversing the hierarchy, getting/setting an object’s value, registering callbacks etc.

Generic Language Interface#

This header file defines a Generic Language Interface into any simulator. 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#

Values:

enumerator GPI_AUTO#
enumerator GPI_NATIVE#
enum gpi_objtype#

Types that can be passed to the iterator.

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#

When iterating, we can chose to either get child objects, drivers or loads.

Values:

enumerator GPI_OBJECTS#
enumerator GPI_DRIVERS#
enumerator GPI_LOADS#
enumerator GPI_PACKAGE_SCOPES#
enum gpi_set_action#

Values:

enumerator GPI_DEPOSIT#
enumerator GPI_FORCE#
enumerator GPI_RELEASE#
enumerator GPI_NO_DELAY#
enum gpi_range_dir#

Values:

enumerator GPI_RANGE_DOWN#
enumerator GPI_RANGE_NO_DIR#
enumerator GPI_RANGE_UP#
enum gpi_edge#

Values:

enumerator GPI_RISING#
enumerator GPI_FALLING#
enumerator GPI_VALUE_CHANGE#

Functions

GPI_EXPORT bool gpi_has_registered_impl(void)#

Return 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 simulator.

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

Return simulation time as two uints.

Unit is the default sim unit.

GPI_EXPORT void gpi_get_sim_precision(int32_t *precision)#
GPI_EXPORT const char *gpi_get_simulator_product(void)#

Return a string with the running simulator product information.

Returns:

The simulator product string.

GPI_EXPORT const char *gpi_get_simulator_version(void)#

Return a string with the running simulator version.

Returns:

The simulator version string.

GPI_EXPORT gpi_sim_hdl gpi_get_root_handle(const char *name)#

Returns a handle to the root simulation object.

GPI_EXPORT gpi_sim_hdl gpi_get_handle_by_name(gpi_sim_hdl parent, const char *name, gpi_discovery discovery_method)#
GPI_EXPORT gpi_sim_hdl gpi_get_handle_by_index(gpi_sim_hdl parent, int32_t index)#
GPI_EXPORT gpi_iterator_hdl gpi_iterate(gpi_sim_hdl base, gpi_iterator_sel type)#

Return an iterator handle which can then be used in gpi_next calls.

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.

GPI_EXPORT gpi_sim_hdl gpi_next(gpi_iterator_hdl iterator)#
Returns:

NULL when there are no more objects.

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 const char *gpi_get_signal_value_binstr(gpi_sim_hdl gpi_hdl)#

This is all slightly verbose but it saves having to enumerate various value types.

We only care about a limited subset of values.

GPI_EXPORT const char *gpi_get_signal_value_str(gpi_sim_hdl gpi_hdl)#
GPI_EXPORT double gpi_get_signal_value_real(gpi_sim_hdl gpi_hdl)#
GPI_EXPORT long gpi_get_signal_value_long(gpi_sim_hdl gpi_hdl)#
GPI_EXPORT const char *gpi_get_signal_name_str(gpi_sim_hdl gpi_hdl)#
GPI_EXPORT const char *gpi_get_signal_type_str(gpi_sim_hdl gpi_hdl)#
GPI_EXPORT gpi_objtype gpi_get_object_type(gpi_sim_hdl gpi_hdl)#
Returns:

One of the types defined above.

GPI_EXPORT const char *gpi_get_definition_name(gpi_sim_hdl gpi_hdl)#

Get information about the definition of a handle.

GPI_EXPORT const char *gpi_get_definition_file(gpi_sim_hdl gpi_hdl)#
GPI_EXPORT int gpi_is_constant(gpi_sim_hdl gpi_hdl)#

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

GPI_EXPORT int gpi_is_indexable(gpi_sim_hdl gpi_hdl)#

Determine whether an object is indexable.

GPI_EXPORT void gpi_set_signal_value_real(gpi_sim_hdl gpi_hdl, double value, gpi_set_action action)#
GPI_EXPORT void gpi_set_signal_value_int(gpi_sim_hdl gpi_hdl, int32_t value, gpi_set_action action)#
GPI_EXPORT void gpi_set_signal_value_binstr(gpi_sim_hdl gpi_hdl, const char *str, gpi_set_action action)#
GPI_EXPORT void gpi_set_signal_value_str(gpi_sim_hdl gpi_hdl, const char *str, gpi_set_action action)#
GPI_EXPORT gpi_cb_hdl gpi_register_timed_callback(int (*gpi_function)(void*), void *gpi_cb_data, uint64_t time)#
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)#
GPI_EXPORT gpi_cb_hdl gpi_register_readonly_callback(int (*gpi_function)(void*), void *gpi_cb_data)#
GPI_EXPORT gpi_cb_hdl gpi_register_nexttime_callback(int (*gpi_function)(void*), void *gpi_cb_data)#
GPI_EXPORT gpi_cb_hdl gpi_register_readwrite_callback(int (*gpi_function)(void*), void *gpi_cb_data)#
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.