Next: , Previous: , Up: Defining Instruction Meta-classes   [Contents][Index]


4.2.2.5 Accessing Binary Instruction Parameters

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

Function: int qsmm_get_eh_instr_param (qsmm_t model, int bufsz, void *bufp)

This function fetches the binary parameters of an instruction class of a multinode model. The function copies such parameters associated with a processed event to a buffer bufp with size bufsz bytes. You can call this function from 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.

The size bufsz 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 bufsz is greater than the size of binary parameters, the function leaves intact the remaining content of bufp.

On success, the function returns the size of binary parameters copied to bufp. On failure, the function returns a negative error code. Currently, the function can return the following error codes.

QSMM_ERR_INVAL

The argument bufsz is less than the size of binary parameters specified when registering the instruction class by the function 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 instruction class are necessary when processing multiple event types, it is reasonable to fetch those binary parameters at the beginning of an event handler on processing events of those types. To prevent reporting QSMM_ERR_UNTIMELY and a possible invocation of a model error handler because of an inappropriate event type, use the following macro to check whether the type of an event is appropriate to call the function qsmm_get_eh_instr_param.

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 of evt type has an associated instruction class, and it is safe to call the function qsmm_get_eh_instr_param and other functions that use an instruction class context.

For example, to fetch the binary parameters of an 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=0;
    if (QSMM_HAS_INSTR_CLASS(qsmm_evt))
        qsmm_get_eh_instr_param(qsmm,sizeof(direct),&direct);
    ...
}

Next: , Previous: , Up: Defining Instruction Meta-classes   [Contents][Index]