4.2.2.5 Accessing Binary Instruction Parameters ¶

The function qsmm_reg_instr_class_v2 registers an individual instruction class and sets its binary parameters. The purpose of the following function is to fetch the binary parameters to a buffer by the event handler of an instruction meta-class. The buffer might be a variable or a structure instance.

Function: int qsmm_get_mehcall_instr_param_bin (qsmm_mehcall_t mehcall, size_t buf_sz, size_t *param_sz_p, void *bufp) ¶

This function fetches the binary parameters of an individual instruction class associated with an event sent to the event handler of an instruction meta-class, where mehcall is an argument of that event handler passing information about the event. The function supports events QSMM_EVT_INSTR_CLASS_INIT, QSMM_EVT_INSTR_CLASS_DONE, and QSMM_EVT_ACTIVATE.

If buf_sz is not (size_t) -1, and bufp is not NULL, the function copies the binary parameters to a buffer bufp with size buf_sz bytes. In this case, buf_sz must be greater than or equal to the size of binary parameters specified when registering the instruction class by the function qsmm_reg_instr_class_v2. If buf_sz is greater than the size of binary parameters, qsmm_get_mehcall_instr_param_bin leaves intact remaining content of bufp.

If param_sz_p is not NULL, this function sets *param_sz_p equal to the size of binary parameters. You can call the function with a non-NULL param_sz_p, buf_sz equal to (size_t) -1, and bufp equal to NULL for retrieving the size of binary parameters.

On success, the function returns a positive value if the instruction class has binary parameters (i.e. their size is positive) or returns 0 if the instruction class does not have binary parameters (i.e. their size is 0). On failure, the function returns a negative error code. Currently, the function can return the following error codes.

QSMM_ERR_INVAL

The argument buf_sz is not equal to (size_t) -1 and is less than the size of binary parameters specified when registering the instruction class by qsmm_reg_instr_class_v2.

QSMM_ERR_UNTIMELY

The context of calling this function is not the event handler of an instruction meta-class on processing an event QSMM_EVT_INSTR_CLASS_INIT, QSMM_EVT_INSTR_CLASS_DONE, or QSMM_EVT_ACTIVATE.

Because the binary parameters of an individual instruction class are necessary when processing multiple event types, it is reasonable to fetch the binary parameters at the beginning of an event handler on processing the events. To prevent reporting QSMM_ERR_UNTIMELY along with a possible invocation of a model error handler because of an inappropriate event type, use the following macro to check if the type of an event is appropriate to call the function qsmm_get_mehcall_instr_param_bin.

Macro: QSMM_HAS_INSTR_CLASS (evt) ¶

This macro expands to:

((evt)==QSMM_EVT_INSTR_CLASS_INIT ||
 (evt)==QSMM_EVT_INSTR_CLASS_DONE ||
 (evt)==QSMM_EVT_ACTIVATE)

The purpose of this macro is to check whether an event with type evt has an associated individual instruction class, and it is safe to call the function qsmm_get_mehcall_instr_param_bin and other functions that use an instruction class context.

For example, to fetch the binary parameters of an individual instruction class at the beginning of event handler of ‘move’ instruction meta-class, declare an enumeration for possible movement directions and define the instruction meta-class as follows:

enum direct_e {
    DIRECT_NORTH,  // move one step up
    DIRECT_EAST,   // move one step right
    DIRECT_SOUTH,  // move one step down
    DIRECT_WEST,   // move one step left
    DIRECT_COUNT   // number of movement directions
};

...

static QSMM_INSTR_META_CLASS(move) {
    enum direct_e direct=DIRECT_COUNT;
    if (QSMM_HAS_INSTR_CLASS(mehcall->evt))
        qsmm_get_mehcall_instr_param_bin(
            mehcall, sizeof(direct), 0, &direct);
    ...
}