Next: , Previous: , Up: Instruction Class Set Definition   [Contents][Index]


4.4.4 Registering Instruction Classes

Every instruction class is an entity related to two other entities: an instruction meta-class and an 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 several instruction class sets.

To register an instruction class, the following function can be used.

Function: int qsmm_reg_instr_class (qsmm_t model, const char *instr_class_set_name, const char *instr_meta_class_name, int instr_param_sz, const void *instr_param_p)

This function registers an instruction class of a multinode model specified by handle model. The instruction class is registered as being a subclass of instruction meta-class instr_meta_class_name and an element of instruction class set instr_class_set_name. Arguments instr_param_p and instr_param_sz specify the content and the size in bytes of a buffer with a binary representation of instruction class parameters. If instr_param_sz is 0, then instr_param_p can be NULL.

When registering the instruction class, the function qsmm_reg_instr_class sends event QSMM_EVT_INSTR_CLASS_INIT to the event handler function of the instruction meta-class, which might set a text representation of instruction class parameters using the function qsmm_set_eh_instr_param_str_f and the number of instruction outcomes using the function qsmm_set_eh_noutcome.

On success, the function returns a non-negative number that uniquely identifies the registered instruction class in the instruction class set. On failure, the function returns a negative error code. Currently, the following error codes can be returned.

QSMM_ERR_UNTIMELY

The model instance already exists, so changing model structure is not allowed.

QSMM_ERR_NOTFOUND

Instruction meta-class named instr_meta_class_name or instruction class set named 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

An instruction class with the same binary or text representation of parameters is already registered for pair <instr_meta_class_name, instr_class_set_name>. The binary representation is passed via arguments instr_param_p and instr_param_sz. The text representation might be set in the event handler function of instruction meta-class instr_meta_class_name while processing event QSMM_EVT_INSTR_CLASS_INIT, which is sent by the function qsmm_reg_instr_class.

QSMM_ERR_VIOLNODE

There exist nodes that belong to a node class represented by instruction class set instr_class_set_name. Therefore, changing the instruction class set is not allowed.

QSMM_ERR_NOMEM

There was not enough memory to perform the operation.

To register an instruction class, which belongs to an instruction class set, in the event handler function of the instruction class set during processing event QSMM_EVT_ENT_INIT, the following macros can be used.

Macro: QSMM_REG_INSTR_CLASS (instr_meta_class_name)

This macro registers an instruction class which is a subclass of instruction meta-class instr_meta_class_name and which has no binary parameters.

The macro is expanded to:

qsmm_reg_instr_class((qsmm), __FUNCTION__,
                     #instr_meta_class_name, 0, 0)
Macro: QSMM_REG_INSTR_CLASS_PARAM (instr_meta_class_name, instr_param)

This macro registers an instruction class which is a subclass of instruction meta-class instr_meta_class_name and which has binary parameters specified in variable instr_param.

The macro is expanded to:

qsmm_reg_instr_class((qsmm), __FUNCTION__, #instr_meta_class_name,
                     sizeof(instr_param), &(instr_param))

These macros are to be expanded from the event handler function of an instruction class set. The name of the event handler function must coincide with the name of the instruction class set, and normally it does coincide. There must be the variable qsmm, which is a handle of multinode model, defined in a function from which the macros are expanded. Normally, that variable is an argument of the event handler function.

A binary representation of parameters of an instruction class to be registered by the macro QSMM_REG_INSTR_CLASS_PARAM must be a variable, not a constant. It is because the size of the binary representation has to be determined, and it is done using the sizeof operator for the variable. If you need to specify a constant for a binary representation of instruction class parameters, then assign that constant to a variable of appropriate type and use that variable as an argument of macro QSMM_REG_INSTR_CLASS_PARAM.

For example, to use element DIRECT_NORTH of enumeration direct_e as a binary parameter of an instruction class which is a subclass of instruction meta-class ‘move’, the following lines of code could be used:

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

An instruction class is uniquely identified in an instruction class set by a non-negative number. That number cannot be greater than or equal to the total number of instruction classes contained in the instruction class set. To get the total number of instruction classes in the set, the following function can be used.

Function: int qsmm_get_instr_class_set_sz (qsmm_t model, const char *instr_class_set_name)

This function returns the number of instruction classes contained in instruction class set instr_class_set_name of a multinode model specified by handle model.

On success, a non-negative value is returned. On failure, a negative error code is returned. Currently, the following error codes can be returned.

QSMM_ERR_NOTFOUND

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.

To get a non-negative number that uniquely identifies an instruction class with a specified name in an instruction class set, the following functions can be used.

Function: int qsmm_find_instr_class_in_set_f (qsmm_t model, const char *instr_class_set_name, const char *fmt, ...)
Function: int qsmm_find_instr_class_in_set_fv (qsmm_t model, const char *instr_class_set_name, const char *fmt, va_list ap)

These functions return a number that uniquely identifies an instruction class in instruction class set instr_class_set_name of a multinode model specified by handle model. The instruction class is specified by its name which is the name of a corresponding instruction meta-class optionally followed by at least one whitespace character and a text representation of instruction class parameters.

The function qsmm_find_instr_class_in_set_f formats an instruction class name according to argument fmt and subsequent arguments; their meaning is the same as in the function printf. The function qsmm_find_instr_class_in_set_fv formats an instruction class name according to arguments fmt and ap; their meaning is the same as in the function vprintf.

Before searching the instruction class in the set, the formatted name is converted to a canonical form: extra whitespace characters before and after the name of instruction meta-class are removed, and text representation of instruction class parameters is normalized according to rules described in Setting the Instruction Parameters String.

On success, the functions return a non-negative value. On failure, a negative error code is returned. Currently, the following error codes can be returned.

QSMM_ERR_NOTFOUND

Instruction class set instr_class_set_name does not exist, or the instruction class is not found in this instruction class set.

QSMM_ERR_INVAL

The name of instruction class has invalid format.

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

The name of instruction class cannot be converted to a wide string according to the current locale.

QSMM_ERR_NOMEM

There was not enough memory to perform the operation.

To get information about an instruction class specified by a number, which uniquely identifies it in an instruction class set, the following functions can be used.

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

This function sets *instr_class_name_pp to the canonicalized name of an instruction class. That canonicalized name is the name of a corresponding instruction meta-class optionally followed by a whitespace character and normalized text representation of instruction class parameters. If instr_class_name_pp is NULL, then *instr_class_name_pp will not be set. A pointer returned in *instr_class_name_pp will be valid until the next call to this function. The instruction class is specified by non-negative number instr_class that uniquely identifies it in instruction class set instr_class_set_name of a multinode model specified by handle model.

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

QSMM_ERR_INVAL

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

QSMM_ERR_NOTFOUND

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

The canonicalized name of instruction class cannot be converted to a multibyte string according to the 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, int instr_class, const char **instr_meta_class_name_pp)

This function sets *instr_meta_class_name_pp to the name of the instruction meta-class of an instruction class. If instr_meta_class_name_pp is NULL, then *instr_meta_class_name_pp will not be set. The instruction class is specified by non-negative number instr_class that uniquely identifies it in instruction class set instr_class_set_name of a multinode model specified by handle model.

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

QSMM_ERR_INVAL

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

QSMM_ERR_NOTFOUND

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, int instr_class, const char **param_str_pp)

This function sets *param_str_pp to a normalized text representation of parameters of an instruction class. If param_str_pp is NULL, then *param_str_pp will not be set. A pointer returned in *param_str_pp will be valid until the next call to the function qsmm_get_instr_class_param_str or qsmm_get_eh_instr_param_str for the instruction class. If param_str_pp is not NULL, and the instruction class does not have text parameters, then *param_str_pp will be set to NULL. The instruction class is specified by non-negative number instr_class that uniquely identifies it in instruction class set instr_class_set_name of a multinode model specified by handle model.

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

QSMM_ERR_INVAL

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

QSMM_ERR_NOTFOUND

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

A normalized text representation of instruction class parameters cannot be converted to a multibyte string according to the current locale.

QSMM_ERR_NOMEM

There was not enough memory to perform the operation.

Function: int qsmm_get_instr_class_param (qsmm_t model, const char *instr_class_set_name, int instr_class, const void **buf_pp)

This function retrieves a binary representation of parameters of an instruction class. The instruction class is specified by non-negative number instr_class that uniquely identifies it in instruction class set instr_class_set_name of a multinode model specified by handle model. If buf_pp is not NULL, then *buf_pp will be set to the pointer to a binary representation of parameters of that instruction class. If the instruction class does not have binary parameters (i.e. their size is 0), and buf_pp is not NULL, then *buf_pp will be set to NULL.

On success, the function returns a non-negative size in bytes of a binary representation of parameters of the instruction class. On failure, the function returns a negative error code. Currently, the following error codes can be returned.

QSMM_ERR_INVAL

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

QSMM_ERR_NOTFOUND

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 (qsmm_t model, const char *instr_class_set_name, int instr_class)

This function returns the number of instruction outcomes of an instruction class. The instruction class is specified by non-negative number instr_class that uniquely identifies it in instruction class set instr_class_set_name of a multinode model specified by handle model. The number of outcomes equal to 0 has special meaning described in Setting the Number of Instruction Outcomes.

On success, a non-negative value is returned. On failure, a negative error code is returned. Currently, the following error codes can be returned.

QSMM_ERR_INVAL

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

QSMM_ERR_NOTFOUND

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: Instruction Class Set Definition   [Contents][Index]