GPI Library Reference

Cocotb contains a library called GPI (in directory 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 cocotb/share/lib/simulator/) which provides routines for traversing the hierarchy, getting/setting an object’s value, registering callbacks etc.

Defines

GPI_EXPORT COCOTB_IMPORT

Typedefs

typedef struct GpiObjHdl *gpi_sim_hdl
typedef struct GpiCbHdl *gpi_cb_hdl
typedef struct GpiIterator *gpi_iterator_hdl
typedef enum gpi_event_e gpi_event_t
typedef enum gpi_objtype_e gpi_objtype_t
typedef enum gpi_iterator_sel_e gpi_iterator_sel_t
typedef enum gpi_set_action_e gpi_set_action_t
typedef enum gpi_edge gpi_edge_e

Enums

enum gpi_event_e

Values:

enumerator SIM_INFO
enumerator SIM_TEST_FAIL
enumerator SIM_FAIL
enum gpi_objtype_e

Values:

enumerator GPI_UNKNOWN
enumerator GPI_MEMORY
enumerator GPI_MODULE
enumerator GPI_NET
enumerator GPI_REGISTER
enumerator GPI_ARRAY
enumerator GPI_ENUM
enumerator GPI_STRUCTURE
enumerator GPI_REAL
enumerator GPI_INTEGER
enumerator GPI_STRING
enumerator GPI_GENARRAY
enum gpi_iterator_sel_e

Values:

enumerator GPI_OBJECTS
enumerator GPI_DRIVERS
enumerator GPI_LOADS
enum gpi_set_action_e

Values:

enumerator GPI_DEPOSIT
enumerator GPI_FORCE
enumerator GPI_RELEASE
enum gpi_edge

Values:

enumerator GPI_RISING
enumerator GPI_FALLING

Functions

GPI_EXPORT bool gpi_has_registered_impl(void)

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

Useful for checking if a simulator is running.

GPI_EXPORT void gpi_sim_end(void)
GPI_EXPORT void gpi_get_sim_time(uint32_t *high, uint32_t *low)
GPI_EXPORT void gpi_get_sim_precision(int32_t *precision)
GPI_EXPORT const char *gpi_get_simulator_product(void)

Returns a string with the running simulator product information.

Returns

simulator product string

GPI_EXPORT const char *gpi_get_simulator_version(void)

Returns a string with the running simulator version.

Returns

simulator version string

GPI_EXPORT gpi_sim_hdl gpi_get_root_handle(const char *name)
GPI_EXPORT gpi_sim_hdl gpi_get_handle_by_name(gpi_sim_hdl parent, const char *name)
GPI_EXPORT gpi_sim_hdl gpi_get_handle_by_index(gpi_sim_hdl parent, int32_t index)
GPI_EXPORT void gpi_free_handle(gpi_sim_hdl gpi_hdl)
GPI_EXPORT gpi_iterator_hdl gpi_iterate(gpi_sim_hdl base, gpi_iterator_sel_t type)
GPI_EXPORT gpi_sim_hdl gpi_next(gpi_iterator_hdl iterator)
GPI_EXPORT int gpi_get_num_elems(gpi_sim_hdl gpi_sim_hdl)
GPI_EXPORT int gpi_get_range_left(gpi_sim_hdl gpi_sim_hdl)
GPI_EXPORT int gpi_get_range_right(gpi_sim_hdl gpi_sim_hdl)
GPI_EXPORT const char *gpi_get_signal_value_binstr(gpi_sim_hdl gpi_hdl)
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_t gpi_get_object_type(gpi_sim_hdl gpi_hdl)
GPI_EXPORT const char *gpi_get_definition_name(gpi_sim_hdl gpi_hdl)
GPI_EXPORT const char *gpi_get_definition_file(gpi_sim_hdl gpi_hdl)
GPI_EXPORT int gpi_is_constant(gpi_sim_hdl gpi_hdl)
GPI_EXPORT int gpi_is_indexable(gpi_sim_hdl gpi_hdl)
GPI_EXPORT void gpi_set_signal_value_real(gpi_sim_hdl gpi_hdl, double value, gpi_set_action_t action)
GPI_EXPORT void gpi_set_signal_value_int(gpi_sim_hdl gpi_hdl, int32_t value, gpi_set_action_t action)
GPI_EXPORT void gpi_set_signal_value_binstr(gpi_sim_hdl gpi_hdl, const char *str, gpi_set_action_t action)
GPI_EXPORT void gpi_set_signal_value_str(gpi_sim_hdl gpi_hdl, const char *str, gpi_set_action_t action)
GPI_EXPORT gpi_cb_hdl gpi_register_timed_callback(int (*gpi_function)(const void*), void *gpi_cb_data, uint64_t time)
GPI_EXPORT gpi_cb_hdl gpi_register_value_change_callback(int (*gpi_function)(const void*), void *gpi_cb_data, gpi_sim_hdl gpi_hdl, int edge)
GPI_EXPORT gpi_cb_hdl gpi_register_readonly_callback(int (*gpi_function)(const void*), void *gpi_cb_data)
GPI_EXPORT gpi_cb_hdl gpi_register_nexttime_callback(int (*gpi_function)(const void*), void *gpi_cb_data)
GPI_EXPORT gpi_cb_hdl gpi_register_readwrite_callback(int (*gpi_function)(const void*), void *gpi_cb_data)
GPI_EXPORT void gpi_deregister_callback(gpi_cb_hdl gpi_hdl)
GPI_EXPORT void *gpi_get_callback_data(gpi_cb_hdl gpi_hdl)