12.32 vpi_register_analog_systf()

vpi_register_analog_systf()

Synopsis: Register user-defined system task/function-related callbacks.

Syntax: vpi_register_analog_systf(systf_data_p)

Type Description

The VPI routine vpi_register_analog_systf() shall register callbacks for user-defined analog system tasks or functions. Callbacks can be registered to occur when a user-defined system task or function is encountered during compilation or execution of analog Verilog-AMS HDL source code. Tasks or functions can be registered with either the analog or digital domain. The registration function (vpi_register_analog_systf() or vpi_register_systf()) with which the task or function is registered shall determine the context or contexts from which the task or function can be invoked and how and when the call backs associated with the function shall be called. The task or function name shall be unique in the domain in which it is registered. That is, the same name can be shared by two sets of callbacks, provided that one set is registered in the digital domain and the other is registered in the analog.

The systf_analog_data_p argument shall point to a s_vpi_systf_analog_data structure, which is defined in vpi_user.h and listed in Figure 12-18.

typedef struct t_vpi_systf_analog_data {

p_vpi_stf_partials (*derivtf)(); /* for partial derivatives */ char *user_data;

} s_vpi_analog_systf_data, *p_vpi_analog_systf_data;

Figure 12-18: The s_vpi_analog_systf_data structure definition

12.32.1 System task and function callbacks

User-defined Verilog-AMS system tasks and functions which use VPI routines can be registered with vpi_register_systf() or vpi_register_analog_systf(). The calltf, compiletf, and sizetf system task/function-related callbacks are defined in vpi_register_systf().

The type field of the s_vpi_systf_data structure shall register the user application to be a system task or a system function. The type field value shall be an integer constant of vpiAnalogSysTask or vpiAnalogSysFunction.

The sysfunctype field of the s_vpi_analog_systf_data structure shall define the type of value which a system function shall return. The sysfunctype field shall be an integer constant of vpiIntFunc of vpiRealFunc. This field shall only be used when the type field is set to vpiAnalogSysFunction.

The compiletf, calltf, sizetf, and derivtf fields of the s_vpi_analog_systf_data structure shall be pointers to the user-provided applications which are to be invoked by the system task/function callback mechanism. One or more of the compiletf, calltf, sizetf, and derivtf fields can be set to NULL if they are not needed. Callbacks to the applications pointed to by the compiletf and sizetf fields shall occur when the simulation data structure is compiled or built (or for the first invocation if the system task or function is invoked from an interactive mode). Callbacks to the applications pointed to by the derivtf fields shall occur when registering partial derivatives for the analog system task/function arguments or return value. Callbacks to the application pointed to by the calltf routine shall occur each time the system task or function is invoked during simulation execution.

The user_data field of the s_vpi_analog_systf_data structure shall specify a user-defined value, which shall be passed back to the compiletf, sizetf, derivtf, and calltf applications when a callback occurs.

The usage of the compiletf, sizetf, and calltf routines for the analog system task/function are identical to those of digital system task/functions registered with vpi_register_systf(). Refer to the description of vpi_register_systf() for more information.

12.32.2 Declaring derivatives for analog system task/functions

Analog system tasks and functions require partial derivatives of the outputs (arguments for system tasks and the return value for system functions). Thus it is possible (though not necessary) to have a partial derivative of the returned value with respect to any or all of the arguments and a partial derivative of any particular argument with respect to any or all of the other arguments.

The derivtf field of the t_vpi_analog_systf_data structure can be called during the build process (similar to sizetf) and returns a pointer to a t_vpi_stf_partials data structure containing the required information. The purpose of this function is declarative only, it does not assign any value to the derivative being declared. Having declared a partial derivative using this function in the derivtf callback, values can then be contributed to the derivative using the vpi_put_value function in the calltf call back.

The t_vpi_stf_partials data structure is defined:

typedef struct t_vpi_stf_partials { int count;

int *derivative_of; /* 0 = returned value, 1 = 1st arg, etc. */ int *derivative_wrt; /* 1 = 1st arg, 2 = 2nd arg, etc. */

} s_vpi_stf_partials, *p_vpi_stf_partials;

This data structure declares the derivative objects for the associated analog task/function. During the call_tf phase, their handles can be retrieved via calls to vpi_handl_multi().

12.32.3 Examples

The following example illustrates the declaration and use of callbacks in an analog function $sampler() which implements a sample and hold. The task is used as follows:

/* value structure (holds the expression value) */ } s_sampler_data, *p_sampler_data;

/* Forward declarations */

static int sampler_callback(p_cb_data data);

static void schedule_callback(p_sampler_data sampler, double currTime);

/* compiletf() */

static int sampler_compiletf(p_cb_data task_cb_data) {

vpiHandle functionHandle, returnHandle, exprHandle, periodHandle; s_cb_data cb_data;

int type; p_sampler_data sampler; s_vpi_value value;

/* Retrieve handle to current function */ functionHandle = vpi_handle(vpiSysTfCall, NULL);

/* Get the handle on the expression argument*/ exprHandle = vpi_handle_by_index(functionHandle, 1); /* Check that expression argument exists */

if (!exprHandle) {

vpi_error("Not enough arguments for $sampler function.");

}

/* Check that expression argument is of real value */ type = vpi_get(vpiType, exprHandle);

if (type != vpiRealVal && type != vpiRealVar) { vpi_error("Arg #1 of $sampler should be real valued."); return 1;

}

/* Get the handle on the period argument */ periodHandle = vpi_handle_by_index(functionHandle, 2);

/* Check that period argument exists */ if (!periodHandle) {

vpi_error("Not enough arguments for $sampler function.");

}

/* Check that period argument has a real value */ type = vpi_get(vpiType, periodHandle);

if (type != vpiRealVal && type != vpiRealVar) { vpi_error("Arg #2 of $sampler should be real valued"); return 1;

}

/* Schedule callback for time = 0 */ sampler->cb_data.reason = cbEndOfCompile; sampler->cb_data.cb_rtn = sampler_postcompile_cb; sampler->cb_data.time.type = 0; sampler->cb_data.user_data = (char *) functionHandle; sampler->cb_data.time.real = 0.0; schedule_callback(sampler, 0.0);

vpi_register_cb(&sampler->cb_data);

return 0;

}

/* calltf */

static int sampler_calltf(int data, int reason) { vpiHandle funcHandle;

p_sampler_data sampler = (p_sampler_data) data; s_vpi_value value;

/* Retrieve handle to current function */ funcHandle = vpi_handle(vpiSysTfCall, NULL);

/* Set returned value to held value */ vpi_set_value(sampler->returnHandle, &sampler->value, NULL,

vpiNoDelay); return 0;

}

/* initialization callback after compile */ static int sampler_postcompile_cb(p_cb_data data) {

vpiHandle functionHandle = (vpiHandle) data; p_sampler_data sampler;

s_vpi_value value;

/* Allocate the instance data and initialize it */ sampler = (p_sampler_data)malloc(sizeof(s_sampler_data));

/*Get the handle to the returned value, no need to check that one */ sampler->returnHandle = vpi_handle_by_index(functionHandle, 0); sampler->exprHandle = vpi_handle_by_index(functionHandle, 1); sampler->periodHandle = vpi_handle_by_index(functionHandle, 2);

/* Get the period value, it is assumed to be constant */ /* (but not necessary) */

sampler->value.format = vpiRealVal; vpi_get_value(periodHandle, &value); sampler->period = value.value.real;

/* Schedule callback for time = period */ sampler->cb_data.reason = acbElapsedTime; sampler->cb_data.cb_rtn = sampler_update_cb; sampler->cb_data.time.type = vpiScaledTme; sampler->cb_data.user_data = (char *) sampler; sampler->cb_data.time.real = sampler->period;

schedule_callback(sampler, 0.0);

vpi_register_cb(&sampler->cb_data);

return 0;

}

/* timer callback */

static int sampler_update_cb(p_cb_data data) { p_sampler_data sampler = (p_sampler_data)data->user_data; s_vpi_value value;

/* Hold expression value */ vpi_get_value(sampler->exprHandle, &value);

/* Schedule next callback */ sampler->cb_data.reason = acbAbsTime; sampler->cb_data.cb_rtn = sampler_update_cb; sampler->cb_data.time.type = vpiScaledTime; sampler->cb_data.user_data = (char *) sampler; sampler->cb_data.time.real =

vpi_get_analog_time() + sampler->period; register_callback(&sampler->cb_data); return 0;