---

4.2.2.4 Instruction Class Identifiers ¶

An individual instruction class has the following identifiers unique in various scopes.

• Binary parameters. This is the encoded form of parameters of an individual instruction class.

  The function qsmm_reg_instr_class_v2 (see Registering Instruction Classes) registers an individual instruction class and sets its binary parameters. That function sends an event QSMM_EVT_INSTR_CLASS_INIT to the event handler of a corresponding instruction meta-class. The event can set the text parameters of the instruction class by the function qsmm_set_mehcall_instr_param_f (see Setting Text Instruction Parameters) based on the binary parameters. An event QSMM_EVT_INSTR_CLASS_DONE sent on destroying the instruction class can uninitialize its binary parameters if they address allocated memory blocks or reference other resources.

  An event QSMM_EVT_ACTIVATE has access to the binary parameters of an individual instruction class to determine how to handle the invocation of an assembler instruction belonging to the instruction class. See Accessing Binary Instruction Parameters, for how to access the binary parameters of an individual instruction class on processing events QSMM_EVT_INSTR_CLASS_INIT, QSMM_EVT_INSTR_CLASS_DONE, and QSMM_EVT_ACTIVATE.

• Text parameters. This is the decoded form of parameters of an individual instruction class necessary for identifying instructions belonging to the instruction class in assembler programs. The text parameters have a canonical form obtained by applying a set of rules to a parameter string, such as removing all whitespace characters from it.

  The function qsmm_set_mehcall_instr_param_f (see Setting Text Instruction Parameters) called on processing an event QSMM_EVT_INSTR_CLASS_INIT usually sets the text parameters of an individual instruction class based on its binary parameters. That function converts the text parameters to the canonical form.

• Name. An instruction meta-class name, the space character, and text instruction class parameters in canonical form make up an instruction class name. This name is an assembler instruction with parameters. If an individual instruction class does not have text parameters, the assembler instruction is solely the name of the instruction meta-class.
• Index. The ordinal number of an instruction class in an instruction class set (acting as an instruction class list in this context). The function qsmm_reg_instr_class_v2 returns that ordinal number after registering an individual instruction class. API functions provide access to various parameters of an individual instruction class by its index.

  An instruction class index is the identifier of an output signal of the instruction emitting engine. Emitting the output signal corresponds to emitting an assembler instruction belonging to the instruction class. A list of signal identifiers encoding an action choice state of the environment state identification engine includes the output signal as the index of the last emitted instruction. See Figure 4.2, for the structure of the list of signal identifiers.

The following tuples containing instruction class identifiers are unique in various scopes of a multinode model.

Tuple or Identifier	Scope of Uniqueness
<instruction meta-class name, binary instruction class parameters>	instruction class set
<instruction class set name, binary instruction class parameters>	instruction meta-class
instruction class name	instruction class set
instruction class index	instruction class set

An instruction class index identifies an individual instruction class or instruction class sequence. The function qsmm_reg_instr_class_seq (see Instruction Class Sequences) returns an instruction class index for an instruction class sequence after registering it in an instruction class set. If an output signal of an instruction emitting engine is an instruction class index identifying an instruction class sequence, emitting the output signal corresponds to emitting a sequence of assembler instructions with the same effect as emitting individual assembler instructions comprising the sequence. A list of signal identifiers encoding an action choice state of the environment state identification engine includes the output signal as the index of the last emitted instruction sequence.

The following function retrieves the name of an instruction meta-class from its event handler function. The function might be useful when multiple instruction meta-classes share the same event handler function.

Function: int qsmm_get_mehcall_instr_meta_class (qsmm_mehcall_t mehcall, const char **instr_meta_class_name_pp) ¶

This function retrieves the name of an instruction meta-class associated with an event sent to an instruction meta-class event handler, where mehcall is an argument of the event handler passing information about the event. If instr_meta_class_name_pp is not NULL, the function sets *instr_meta_class_name_pp to the name of the instruction meta-class.

On success, the function returns a non-negative value. If the context of calling the function is not the event handler of an instruction meta-class, the function returns negative error code QSMM_ERR_UNTIMELY.

The function qsmm_reg_instr_class_v2 registers an individual instruction class as belonging to an instruction class set. Use the function described below to get the name of the instruction class set when processing an event by the event handler of instruction meta-class of the instruction class. You can also use this function to get the name of the instruction class set when processing an event by the event handler of the instruction class set.

Function: int qsmm_get_mehcall_instr_class_set (qsmm_mehcall_t mehcall, const char **instr_class_set_name_pp) ¶

This function retrieves the name of an instruction class set associated with an event sent to the event handler of an instruction meta-class or the instruction class set, where mehcall is an argument of that event handler passing information about the event. If instr_class_set_name_pp is not NULL, the function sets *instr_class_set_name_pp to the name of the instruction class set.

If the event handler of an instruction meta-class calls this function while processing an event QSMM_EVT_INSTR_CLASS_INIT, QSMM_EVT_INSTR_CLASS_DONE, or QSMM_EVT_ACTIVATE, the function retrieves the name of an instruction class set containing an individual instruction class associated with the event and derived from the instruction meta-class. If the event handler of an instruction class set calls this function, it retrieves the name of the instruction class set.

On success, the function returns a non-negative value. If the context of calling the 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 and not the event handler of an instruction class set, the function returns negative error code QSMM_ERR_UNTIMELY.