Question

Use vpi_register_assertion_cb() to place an assertion callback; the prototype is:

/* typedef for vpi_register_assertion_cb callback function */
typedef PLI_INT32 (vpi_assertion_callback_func)(
    PLI_INT32 reason, /* callback reason */
    p_vpi_time cb_time, /* callback time */
    vpiHandle assertion, /* handle to assertion */
    p_vpi_attempt_info info, /* attempt related information */
    PLI_BYTE8 *user_data /* user data entered upon registration */
);

vpiHandle vpi_register_assertion_cb(
    vpiHandle assertion, /* handle to assertion */
    PLI_INT32 reason, /* reason for which callbacks needed */
    vpi_assertion_callback_func *cb_rtn,
    PLI_BYTE8 *user_data /* user data to be supplied to cb */
);

typedef struct t_vpi_assertion_step_info {
    PLI_INT32 matched_expression_count;
    vpiHandle *matched_exprs; /* array of expressions */
    p_vpi_source_info *exprs_source_info; /* array of source info */
    PLI_INT32 stateFrom, stateTo;/* identify transition */
} s_vpi_assertion_step_info, *p_vpi_assertion_step_info;

typedef struct t_vpi_attempt_info {
    union {
        vpiHandle failExpr;
        p_vpi_assertion_step_info step;
    } detail;
    s_vpi_time attemptStartTime; /* Time attempt triggered */
} s_vpi_attempt_info, *p_vpi_attempt_info;

where reason is any of the following.

cbAssertionStart
an assertion attempt has started. For most assertions one attempt starts each and every clock tick.

cbAssertionSuccess
when an assertion attempt reaches a success state.

cbAssertionFailure
when an assertion attempt fails to reach a success state.

cbAssertionStepSuccess
progress one step an attempt. By default, step callbacks are not enabled on any assertions; they are
enabled on a per-assertion/per-attempt basis (see Section 28.5.2), rather than on a per-assertion basis.

cbAssertionStepFailure
failure to progress by one step along an attempt. By default, step callbacks are not enabled on any assertions;
they are enabled on a per-assertion/per-attempt basis (see Section 28.5.2), rather than on a perassertion
basis.

cbAssertionDisable
whenever the assertion is disabled (e.g., as a result of a control action).

cbAssertionEnable
whenever the assertion is enabled.

cbAssertionReset
whenever the assertion is reset.

cbAssertionKill
when an attempt is killed (e.g., as a result of a control action).

These callbacks are specific to a given assertion; placing such a callback on one assertion does not cause the callback to trigger on an event occurring on a different assertion. If the callback is successfully placed, a handle to the callback is returned. This handle can be used to remove the callback via vpi_remove_cb(). If there were errors on placing the callback, a NULL handle is returned. As with all other calls, invoking this function with invalid arguments has unpredictable effects.

Once the callback is placed, the user-supplied function shall be called each time the specified event occurs on the given assertion. The callback shall continue to be called whenever the event occurs until the callback is removed.

The callback function shall be supplied the following arguments:

1. the reason for the callback
2. a pointer to the time of the callback
3. the handle for the assertion
4. a pointer to an attempt information structure
5. a reference to the user data supplied when the callback was registered.

The t_vpi_attempt_info attempt information structure contains details relevant to the specific event that occurred.

• On disable, enable, reset and kill callbacks, the returned p_vpi_attempt_info info pointer is NULL and no attempt information is available.
• On start and success callbacks, only the attemptStartTime field is valid.
• On a cbAssertionFailure callback, the attemptStartTime and detail.failExpr fields are valid.
• On a step callback, the attemptStartTime and detail.step fields are valid.

On a step callback, the detail describes the set of expressions matched in satisfying a step along the assertion, along with the corresponding source references. In addition, the step also identifies the source and destination “states” needed to uniquely identify the path being taken through the assertion. State ids are just integers, with 0 identifying the origin state, 1 identifying an accepting state, and any other number representing some intermediate point in the assertion. It is possible for the number of expressions in a step to be 0 (zero), which represents an unconditional transition. In the case of a failing transition, the information provided is just as that for a successful one, but the last expression in the array represents the expression where the transition failed.

NOTES

1—In a failing transition, there shall always be at least one element in the expression array.

2—Placing a step callback results in the same callback function being invoked for both success and failure steps.

3—The content of the cb_time field depends on the reason identified by the reason field, as follows:

• cbAssertionStart — cb_time is the time when the assertion attempt has been started.
• cbAssertionSuccess, cbAssertionFailure — cb_time is the time when the assertion succeeded/failed.
• cbAssertionStepSuccess, cbAssertionStepFailure — cb_time is the time when the assertion attempt step succeeded/failed.
• cbAssertionDisable, cbAssertionEnable, cbAssertionReset, cbAssertionKill — cb_time is the time when the assertion attempt was disabled/enabled/reset/killed.

4—In contrast to cb_time, the content of attemptStartTime is always the start time of the actual attempt of an assertion. It can be used as an unique ID that distinguishes the attempts of any given assertion.