Question

DPI defines a small set of functions to help programmers work with DPI context tasks and functions. The term scope is used in the task or function names for consistency with other SystemVerilog terminology. The terms scope and context are equivalent for DPI tasks and functions.

There are functions that allow the user to retrieve and manipulate the current operational scope. It is an error to use these functions with any C code that is not executing under a call to a DPI context imported task or function.

There are also functions that provide users with the power to set data specific to C models into the SystemVerilog simulator for later retrieval. These are the “put” and “get” user data functions, which are similar to facilities provided in VPI and PLI.

The put and get user data functions are flexible and allow for a number of use models. Users might wish to share user data across multiple context imported functions defined in the same SV scope. Users might wish to have unique data storage on a per function basis. Shared or unique data storage is controllable by a userdefined key.

To achieve shared data storage, a related set of context imported tasks and functions should all use the same userKey. To achieve unique data storage, a context import task or function should use a unique key. Note that it is a requirement on the user that such a key be truly unique from all other keys that could possibly be used by C code. This includes completely unknown C code that could be running in the same simulation. It is suggested that taking addresses of static C symbols (such as a function pointer, or address of some static C data) always be done for user key generation. Generating keys based on arbitrary integers is not a safe practice.

Note that it is never possible to share user data storage across different contexts. For example, if a Verilog module m declares a context imported task or function f, and m is instantiated more than once in the System- Verilog design, then f shall execute under different values of svScope. No such executing instances of f can share user data with each other, at least not using the system-provided user data storage area accessible via svPutUserData().

A user wanting to share a data area across multiple contexts must do so by allocating the common data area, then storing the pointer to it individually for each of the contexts in question via multiple calls to svPutUser- Data(). This is because, although a common user key can be used, the data must be associated with the individual scopes (denoted by svScope) of those contexts.

/* Functions for working with DPI context functions */
/* Retrieve the active instance scope currently associated with the executing
* imported function.
* Unless a prior call to svSetScope has occurred, this is the scope of the
* function’s declaration site, not call site.
* The return value is undefined if this function is invoked from a non-context
* imported function.
*/
svScope svGetScope();
/* Set context for subsequent export function execution.
* This function must be called before calling an export function, unless
* the export function is called while executing an extern function. In that
* case the export function shall inherit the scope of the surrounding extern
* function. This is known as the “default scope”.
* The return is the previous active scope (as per svGetScope)
*/
svScope svSetScope(const svScope scope);
/* Gets the fully qualified name of a scope handle */
const char* svGetNameFromScope(const svScope);
/* Retrieve svScope to instance scope of an arbitrary function declaration.
* (can be either module, program, interface, or generate scope)
* The return value shall be NULL for unrecognized scope names.
*/
svScope svGetScopeFromName(const char* scopeName);
/* Store an arbitrary user data pointer for later retrieval by svGetUserData()
* The userKey is generated by the user. It must be guaranteed by the user to
* be unique from all other userKey’s for all unique data storage requirements
* It is recommended that the address of static functions or variables in the
* user’s C code be used as the userKey.
* It is illegal to pass in NULL values for either the scope or userData
* arguments. It is also an error to call svPutUserData() with an invalid
* svScope. This function returns -1 for all error cases, 0 upon success. It is
* suggested that userData values of 0 (NULL) not be used as otherwise it can
* be impossible to discern error status returns when calling svGetUserData()
*/
int svPutUserData(const svScope scope, void *userKey, void* userData);
/* Retrieve an arbitrary user data pointer that was previously
* stored by a call to svPutUserData(). See the comment above
* svPutUserData() for an explanation of userKey, as well as
* restrictions on NULL and illegal svScope and userKey values.
* This function returns NULL for all error cases, and a non-Null
* user data pointer upon success.
* This function also returns NULL in the event that a prior call
* to svPutUserData() was never made.
*/
void* svGetUserData(const svScope scope, void* userKey);
/* Returns the file and line number in the SV code from which the extern call
* was made. If this information available, returns TRUE and updates fileName
* and lineNumber to the appropriate values. Behavior is unpredictable if
* fileName or lineNumber are not appropriate pointers. If this information is
* not available return FALSE and contents of fileName and lineNumber not
* modified. Whether this information is available or not is implementation
* specific. Note that the string provided (if any) is owned by the SV
* implementation and is valid only until the next call to any SV function.
* Applications must not modify this string or free it
*/
int svGetCallerInfo(char **fileName, int *lineNumber);