Next: , Previous: , Up: Defining Instruction Class Sets   [Contents][Index]


4.2.3.4 Registering Instruction Classes

Every instruction class is an entity related to two other entities: an instruction meta-class and instruction class set. An instruction class is a subclass of an instruction meta-class and is an element of an instruction class set. Identical subclasses of an instruction meta-class can be the elements of multiple instruction class sets. Registering an instruction class must not violate uniqueness constraints listed in Instruction Class Identifiers.

Use the following function to register an instruction class.

Function: int qsmm_reg_instr_class_v2 (qsmm_t model, const char *instr_meta_class_name, const char *instr_class_set_name, int rez1, size_t param_bin_sz, const void *param_bin_p, qsmm_sig_t *instr_class_p)

This function registers an instruction class of a multinode model. The instruction class becomes a subclass of instr_meta_class_name instruction meta-class and an element of instr_class_set_name instruction class set. The arguments param_bin_p and param_bin_sz specify the content and size in bytes of a buffer with binary instruction class parameters. The function copies the buffer to an internal structure. If param_bin_sz is 0, then param_bin_p can be NULL. The argument rez1 is for future use and must be equal to 0.

The function sends an event QSMM_EVT_INSTR_CLASS_INIT to an instruction meta-class event handler. This event can trigger setting text instruction class parameters by the function qsmm_set_eh_instr_param_str_f and the number of instruction outcomes by the function qsmm_set_eh_noutcome.

On success, the function returns a non-negative value and, if instr_class_p is not NULL, sets *instr_class_p to an instruction class index—a number that uniquely identifies a registered instruction class in the instruction class set. On failure, the function returns a negative error code. Currently, the function can return the following error codes.

QSMM_ERR_NOTFOUND

The instruction meta-class instr_meta_class_name or instruction class set instr_class_set_name does not exist.

QSMM_ERR_TYPE

An entity named instr_meta_class_name is not an instruction meta-class, or an entity named instr_class_set_name is not an instruction class set.

QSMM_ERR_EXIST

The instruction class set instr_class_set_name already contains an instruction class derived from the instruction meta-class instr_meta_class_name with the same binary or text parameters. The arguments param_bin_p and param_bin_sz specify the binary parameters. The instruction meta-class event handler can set the text parameters by the function qsmm_set_eh_instr_param_str_f on processing an event QSMM_EVT_INSTR_CLASS_INIT sent by the function qsmm_reg_instr_class_v2.

QSMM_ERR_UNTIMELY

The model instance already exists—cannot change model structure.

QSMM_ERR_VIOLNODE

There exist nodes belonging to a node class represented by the instruction class set instr_class_set_name—cannot change the instruction class set.

QSMM_ERR_NOMEM

There was not enough memory to perform the operation.

Use the following macros to register an instruction class belonging to an instruction class set in the event handler of this instruction class set on processing an event QSMM_EVT_ENT_INIT. The macros expect that the name of the event handler function is equal to the name of the instruction class set and the variable qsmm holding the handle of a multinode model is accessible in the event handler function. Normally, that variable is an event handler function argument.

Macro: QSMM_REG_INSTR_CLASS (meta_class_name)

This macro registers an instruction class derived from an instruction meta-class meta_class_name without binary parameters.

The macro expands to:

qsmm_reg_instr_class_v2((qsmm),#meta_class_name,__FUNCTION__,0,0,0,0)
Macro: QSMM_REG_INSTR_CLASS_PARAM (meta_class_name, param_bin)

This macro registers an instruction class derived from an instruction meta-class meta_class_name with binary parameters in a variable param_bin.

The macro expands to:

qsmm_reg_instr_class_v2((qsmm), #meta_class_name, __FUNCTION__, 0,
                        sizeof(param_bin), &(param_bin), 0)

The binary parameters of an instruction class to register by the macro QSMM_REG_INSTR_CLASS_PARAM must be a variable and not a constant. This is because the macro takes the address of a variable using ‘&’. If you need to specify a constant as the binary parameters, assign the constant to a variable of an appropriate type and pass this variable to QSMM_REG_INSTR_CLASS_PARAM.

For example, to use the element DIRECT_NORTH of direct_e enumeration mentioned in Accessing Binary Instruction Parameters as a binary parameter of an instruction class derived from the instruction meta-class ‘move’, write:

const enum direct_e direct=DIRECT_NORTH;
QSMM_REG_INSTR_CLASS_PARAM(move,direct);

Use the following lines to register instruction classes derived from the instruction meta-class ‘move’ for all movement directions declared by the enumeration direct_e:

for (enum direct_e direct=0; direct<DIRECT_COUNT; direct++)
    QSMM_REG_INSTR_CLASS_PARAM(move,direct);

Use the following function to get the total number of instruction classes contained in an instruction class set. An instruction class index returned by the function qsmm_reg_instr_class_v2 is never greater than or equal to the size of an instruction class set.

Function: int qsmm_get_instr_class_set_sz_v2 (qsmm_t model, const char *instr_class_set_name, int rez1, unsigned int flags, qsmm_sig_t *n_instr_class_p)

This function retrieves the number of instruction classes contained in an instruction class set instr_class_set_name in a multinode model.

If flags contain bitmask QSMM_EXCEPT_NOTFOUND, and the instruction class set does not exist, the function reports QSMM_ERR_NOTFOUND. If flags contain bitmask QSMM_EXCEPT_TYPE, and an entity named instr_class_set_name is not an instruction class set, the function reports QSMM_ERR_TYPE. Bitmask QSMM_EXCEPT_ALL includes QSMM_EXCEPT_NOTFOUND and QSMM_EXCEPT_TYPE.

The argument rez1 is for future use and must be equal to 0.

On success, the function returns a non-negative value and sets *n_instr_class_p if n_instr_class_p is not NULL. If an entity named instr_class_set_name exists and is an instruction class set, the function sets *n_instr_class_p to the number of instruction classes in the instruction class set. If the entity does not exist, and flags do not contain QSMM_EXCEPT_NOTFOUND, the function sets *n_instr_class_p to QSMM_SIG_INVALID. If the entity exists but is not an instruction class set, and flags do not contain QSMM_EXCEPT_TYPE, the function sets *n_instr_class_p to QSMM_SIG_INVALID.

If n_instr_class_p is not NULL, and *n_instr_class_p is 0 or QSMM_SIG_INVALID or would be set to one of these values if n_instr_class_p were not NULL, the function returns 0. If the instruction class set contains a single instruction class, the function returns 1. If the instruction class set contains multiple instruction classes, the function returns 2.

On failure, the function returns a negative error code. Currently, the function can return the following error codes.

QSMM_ERR_NOTFOUND

The instruction class set instr_class_set_name does not exist. The function reports this error if flags include bitmask QSMM_EXCEPT_NOTFOUND. Otherwise, the function sets *n_instr_class_p to QSMM_SIG_INVALID (if n_instr_class_p is not NULL) and returns 0.

QSMM_ERR_TYPE

An entity named instr_class_set_name is not an instruction class set. The entity is an instruction meta-class. The function reports this error if flags include bitmask QSMM_EXCEPT_TYPE. Otherwise, the function sets *n_instr_class_p to QSMM_SIG_INVALID (if n_instr_class_p is not NULL) and returns 0.

QSMM_ERR_NOMEM

There was not enough memory to perform the operation.

Use the following functions to get an instruction class index by an instruction class name.

Function: int qsmm_find_instr_class_in_set_f_v2 (qsmm_t model, qsmm_sig_t *instr_class_p, const char *instr_class_set_name, int rez1, unsigned int flags, const char *fmt, ...)
Function: int qsmm_find_instr_class_in_set_fv_v2 (qsmm_t model, qsmm_sig_t *instr_class_p, const char *instr_class_set_name, int rez1, unsigned int flags, const char *fmt, va_list ap)

These functions retrieve the index of an instruction class in an instruction class set instr_class_set_name in a multinode model by the name of the instruction class. That index as well as name in canonical form uniquely identify the instruction class in the instruction class set. An instruction meta-class name optionally followed by at least one whitespace character and text instruction class parameters make up an instruction class name.

The function qsmm_find_instr_class_in_set_f_v2 formats an instruction class name according to the argument fmt and subsequent arguments interpreted as in the function printf. The function qsmm_find_instr_class_in_set_fv_v2 formats an instruction class name according to the arguments fmt and ap interpreted as in the function vprintf.

Before searching the instruction class in the set, the functions convert the formatted name to canonical form: they remove whitespace characters before the instruction meta-class name, replace whitespace characters after the instruction meta-class name with a single space character, and convert the text parameters of that instruction class to their canonical form according to rules described in Setting Text Instruction Parameters.

If flags contain bitmask QSMM_EXCEPT_NOTFOUND, and the instruction class not found in the instruction class set, the functions report QSMM_ERR_NOTFOUND. The argument rez1 is for future use and must be equal to 0.

On success, the functions return a non-negative value and set *instr_class_p if instr_class_p is not NULL. If the instruction class found in the instruction class set, the functions set *instr_class_p to the index of that instruction class. If the instruction class set exists, but the instruction class not found in it, and flags do not contain QSMM_EXCEPT_NOTFOUND, the functions set *instr_class_p to QSMM_SIG_INVALID.

On failure, the functions return a negative error code. Currently, the functions can return the following error codes.

QSMM_ERR_NOTFOUND

The instruction class set instr_class_set_name does not exist, or the instruction class not found in the instruction class set. In the latter case, the functions report this error if flags include bitmask QSMM_EXCEPT_NOTFOUND; otherwise, the functions set *instr_class_p to QSMM_SIG_INVALID (if instr_class_p is not NULL) and return a non-negative value.

QSMM_ERR_TYPE

An entity named instr_class_set_name is not an instruction class set. The entity is an instruction meta-class.

QSMM_ERR_INVAL

An instruction class name has invalid format.

QSMM_ERR_ILSEQ

Unable to convert an instruction class name to a wide string according to a current locale.

QSMM_ERR_NOMEM

There was not enough memory to perform the operation.

Use the following functions to get information about an instruction class specified by its index.

Function: int qsmm_get_instr_class_name (qsmm_t model, const char *instr_class_set_name, qsmm_sig_t instr_class, const char **instr_class_name_pp)

This function retrieves the canonicalized name of an instruction class specified by its index instr_class in an instruction class set instr_class_set_name in a multinode model. That canonicalized name is the name of an instruction meta-class optionally followed by the space character and the text parameters of this instruction class in their canonical form. The function sets *instr_class_name_pp to the canonicalized name if instr_class_name_pp is not NULL. A pointer returned in *instr_class_name_pp is valid until the next call to this function for this instruction class.

The function returns a non-negative value on success or a negative error code on failure. Currently, the function can return the following error codes.

QSMM_ERR_INVAL

The argument instr_class is greater than or equal to the number of instruction classes in the instruction class set instr_class_set_name.

QSMM_ERR_NOTFOUND

The instruction class set instr_class_set_name does not exist.

QSMM_ERR_TYPE

An entity named instr_class_set_name is not an instruction class set. The entity is an instruction meta-class.

QSMM_ERR_ILSEQ

Unable to convert the canonicalized name of an instruction class to a multibyte string according to a current locale.

QSMM_ERR_NOMEM

There was not enough memory to perform the operation.

Function: int qsmm_get_instr_class_meta_name (qsmm_t model, const char *instr_class_set_name, qsmm_sig_t instr_class, const char **instr_meta_class_name_pp)

This function retrieves the name of the instruction meta-class of an instruction class specified by its index instr_class in an instruction class set instr_class_set_name in a multinode model. The function sets *instr_meta_class_name_pp to the instruction meta-class name if instr_meta_class_name_pp is not NULL.

The function returns a non-negative value on success or a negative error code on failure. Currently, the function can return the following error codes.

QSMM_ERR_INVAL

The argument instr_class is greater than or equal to the number of instruction classes in the instruction class set instr_class_set_name.

QSMM_ERR_NOTFOUND

The instruction class set instr_class_set_name does not exist.

QSMM_ERR_TYPE

An entity named instr_class_set_name is not an instruction class set. The entity is an instruction meta-class.

QSMM_ERR_NOMEM

There was not enough memory to perform the operation.

Function: int qsmm_get_instr_class_param_str (qsmm_t model, const char *instr_class_set_name, qsmm_sig_t instr_class, const char **param_str_pp)

This function retrieves the canonicalized text parameters of an instruction class specified by its index instr_class in an instruction class set instr_class_set_name in a multinode model. The function sets *param_str_pp to the canonicalized text parameters if param_str_pp is not NULL. If the instruction class does not have text parameters, or its canonicalized text parameters are the empty string, the function sets *param_str_pp to NULL. A pointer returned in *param_str_pp is valid until the next call to this function or the function qsmm_get_eh_instr_param_str for the instruction class.

If the canonicalized text parameters have positive length, the function returns a positive value. If the instruction class does not have text parameters, or its canonicalized text parameters are the empty string, the function returns 0. On failure, the function returns a negative error code. Currently, the function can return the following error codes.

QSMM_ERR_INVAL

The argument instr_class is greater than or equal to the number of instruction classes in the instruction class set instr_class_set_name.

QSMM_ERR_NOTFOUND

The instruction class set instr_class_set_name does not exist.

QSMM_ERR_TYPE

An entity named instr_class_set_name is not an instruction class set. The entity is an instruction meta-class.

QSMM_ERR_ILSEQ

Unable to convert the canonicalized text parameters of an instruction class to a multibyte string according to a current locale.

QSMM_ERR_NOMEM

There was not enough memory to perform the operation.

Function: int qsmm_get_instr_class_param_bin (qsmm_t model, const char *instr_class_set_name, qsmm_sig_t instr_class, size_t *param_bin_sz_p, const void **param_bin_pp)

This function retrieves the binary parameters of an instruction class specified by its index instr_class in an instruction class set instr_class_set_name in a multinode model. If param_bin_sz_p is not NULL, the function sets *param_bin_sz_p to the size of those binary parameters in bytes. If param_bin_pp is not NULL, the function sets *param_bin_pp to a pointer to those binary parameters. If the instruction class does not have binary parameters (i.e. their size is 0), the function sets *param_bin_pp to NULL.

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

QSMM_ERR_INVAL

The argument instr_class is greater than or equal to the number of instruction classes in the instruction class set instr_class_set_name.

QSMM_ERR_NOTFOUND

The instruction class set instr_class_set_name does not exist.

QSMM_ERR_TYPE

An entity named instr_class_set_name is not an instruction class set. The entity is an instruction meta-class.

QSMM_ERR_NOMEM

There was not enough memory to perform the operation.

Function: int qsmm_get_instr_class_noutcome_v2 (qsmm_t model, const char *instr_class_set_name, int rez1, qsmm_sig_t instr_class, qsmm_sig_t *noutcome_p)

This function retrieves the number of outcomes of an instruction class specified by its index instr_class in an instruction class set instr_class_set_name in a multinode model. If noutcome_p is not NULL, the function sets *noutcome_p to the number of outcomes. That number equal to 0 has special meaning described in Setting the Number of Instruction Outcomes. The argument rez1 is for future use and must be equal to 0.

If the instruction class has multiple outcomes, the function returns 2. If the instruction class has a single outcome, the function returns 1. If the instruction class has special number of outcomes 0, the function returns 0. On failure, the function returns a negative error code. Currently, the function can return the following error codes.

QSMM_ERR_INVAL

The argument instr_class is greater than or equal to the number of instruction classes in the instruction class set instr_class_set_name.

QSMM_ERR_NOTFOUND

The instruction class set instr_class_set_name does not exist.

QSMM_ERR_TYPE

An entity named instr_class_set_name is not an instruction class set. The entity is an instruction meta-class.

QSMM_ERR_NOMEM

There was not enough memory to perform the operation.


Next: , Previous: , Up: Defining Instruction Class Sets   [Contents][Index]