Next: , Previous: , Up: Assembler Programs   [Contents][Index]


5.8 Loading a Parsed Program into a Node

An assembler program specifies a probability profile that can be loaded into nodes of multinode model. Loading a probability profile, which is specified by a parsed assembler program, into a node of multinode model is called assembling a node for short. The node must belong to a node class represented by an instruction class set that contains instruction classes for all user and mixed type instructions used in the assembler program. Parsed assembler programs can only be loaded into nodes of a multinode model that has the look-ahead signal segment of zero length.

Functions described further on in this section take argument flags that specifies modes of processing a parsed assembler program. This argument was introduced in QSMM version 1.15. The argument is a bitmask that can be defined as a subset of macros described below merged by bitwise “or.”

Macro: QSMM_ASM_DETERM_OPT

Impose the following restriction on an action emission matrix that corresponds to the assembler program: for every node state the action emission matrix must define deterministic choice of an instruction class, which can be emitted in that node state. This mode will be turned on implicitly if the field is_determ_opt of structure qsmm_desc_s has a non-zero value when creating the multinode model. In this mode, when processing the memory representation of an assembler program, states are assumed to begin just before user and mixed type instructions, and there is no need to mark unnamed states by stt instructions. If the assembler program contains stt instructions, they cannot be located just before jprob and casels instructions and choice instruction blocks.

Macro: QSMM_ASM_TEMPLATE

When converting the memory representation of an assembler program to the state transition matrix and the action emission matrix of a node, store that memory representation in the node as an assembler program template. The template will be automatically used when disassembling the node by the function qsmm_node_disasm. A disassembled program will be the template program for which profile probabilities in jprob and case instructions are replaced with probabilities of a type specified in the field prob_type of structure qsmm_disasm_desc_s passed to the function qsmm_node_disasm or of type QSMM_PROB_AGGR if default disassembling parameters are used. The field prob_goto_min of structure qsmm_disasm_desc_s specifies the minimum probability in jprob and case instructions that correspond to the state transition matrix. The field prob_action_min of structure qsmm_disasm_desc_s specifies the minimum probability in jprob and case instructions that correspond to the action emission matrix. Instructions with lesser probabilities are removed from the disassembled program, although they are present in the template program. Additional probabilities of types specified in the field do_calc_prob of structure qsmm_disasm_desc_s can be calculated and then printed in comments for jprob and case instructions.

When storing an assembler program template into a node, casels instructions encountered in the memory representation of the assembler program are converted to choice instruction blocks or jprob instructions. If a casels instruction uses a probabilities list that contains more than one element, the instruction is converted to a choice instruction block. Otherwise, the instruction is converted to a jprob instruction. Such conversion makes possible obtaining probabilities associated with jump labels of casels instructions when disassembling the node.

Macro: QSMM_ASM_VAR_OUT

Collect information on output probability variables and arrays in the assembler program. They all can be used to obtain probabilities learned during the node training. Output probability variables can be used to obtain probabilities that correspond to jprob and case instructions. Output probabilities arrays can be used to obtains probabilities that correspond to casels instructions and choice instruction blocks. See Output Variables, and Getting Output Probabilities Arrays, for more information.

Macro: QSMM_ASM_VAR_AUX

Permit the use of auxiliary probability variables in the assembler program. Auxiliary probability variables are probability variables that are neither controlled nor output ones. Auxiliary probability variables are used merely for convenience in jprob and case instructions and definitions of probabilities lists and are replaced with their actual values in the process of assembling the node. See Auxiliary Variables, for more information.

To load the memory representation of an assembler program into a node, the following function can be used.

Function: int qsmm_node_asm (qsmm_t model, int node, unsigned int flags, qsmm_prg_t prg, qsmm_msglist_t msglist)

This function loads a probability profile into a node of a multinode model specified by handle model, i.e. assembles the node. Argument node specifies the identifier of the node. Bitmask flags defines modes of assembling the node (see above for a description of macros that correspond to bits of this bitmask taken into account). Program prg defines the probability profile. If msglist is not NULL, then warning messages generated during the assembling will be appended to message list msglist. The function clears event history statistics that might have been collected for the node. If the node already has a probability profile loaded, then that profile will be first unloaded. To clear the event history statistics and unload the profile, this function implicitly calls the function qsmm_node_unload described in Unloading the Probability Profile.

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_NOTFOUND

A node with identifier node does not exist.

QSMM_ERR_NOSTATE

A node with identifier node does not have enough states.

QSMM_ERR_MPROF

No room in the pool of probabilities lists in normal form of a large actor that represents the environment state identification engine or the instruction emitting engine. Sizes of the pools are specified in the fields profile_pool_env_sz and profile_pool_opt_sz of structure qsmm_desc_s passed to the function qsmm_create when creating the multinode model.

QSMM_ERR_PROFSRCP

A node with identifier node is the source of probability profile for other nodes. See Memory Efficient Cloning the Probability Profile, for more information on this mode.

QSMM_ERR_PRG

An error was encountered in program prg.

QSMM_ERR_UNTIMELY

The model instance does not exist.

QSMM_ERR_UNSUPPLA

The multinode model has positive length of the look-ahead signal segment.

QSMM_ERR_STORAGE

Statistics storage failure. This could leave the model instance in indeterminate state. If the model instance is in indeterminate state, then after removing a reason of the error, the operation can be repeated, and if the function succeeds, then the model instance state will become determinate.

QSMM_ERR_NOMEM

There was not enough memory to perform the operation. This could leave the model instance in indeterminate state. If the model instance is in indeterminate state, then after removing a reason of the error, the operation can be repeated, and if the function succeeds, then the model instance state will become determinate.

To successfully load a program into a node, the node must have the sufficient number of states. Otherwise, error QSMM_ERR_NOSTATE will be raised. The number of states of a node can be set using the function qsmm_set_node_nstate, but it must not exceed the maximum number of states of nodes of instruction class set, which is specified using the function qsmm_set_nstate_max. To determine, which number of states to pass to the functions qsmm_set_node_nstate and qsmm_set_nstate_max, the following function can be used.

Function: int qsmm_get_prg_nstate (qsmm_t model, const char *instr_class_set_name, unsigned int flags, qsmm_prg_t prg, qsmm_msglist_t msglist)

This function calculates the minimum number of states required for nodes of a multinode model specified by handle model to successfully load program prg into them. Calculating is performed for nodes that belong to a node class represented by instruction class set instr_class_set_name. Modes of assembling the nodes are specified using bitmask flags (see the beginning of this section for a description of macros that correspond to bits of the bitmask taken into account). For a certainty, the value of flags passed to this function must be equal to the value of argument flags that will be passed to the function qsmm_node_asm when loading program prg into particular nodes of the model. If msglist is not 0, then warning messages generated during the calculating will be written to msglist.

On success, the function returns a non-negative number of states. 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_PRG

An error was encountered in program prg.

QSMM_ERR_UNSUPPLA

The multinode model has positive length of the look-ahead signal segment.

QSMM_ERR_NOMEM

There was not enough memory to perform the operation.

The functions qsmm_node_asm and qsmm_get_prg_nstate may generate the following warning messages.

‘nop’ instruction has been inserted

A nop instruction has been inserted at the beginning of an implicitly defined state because the state does not start with a user or mixed type instruction.

a replacement ‘nop’ instruction has been generated

After a jprob instruction, which has a jump probability greater than 0, there is a jmp instruction with a jump to that jprob instruction, and the jump location of the jprob instruction is not the next instruction. The jprob instruction was replaced with the nop instruction, and the address of the next instruction, which will be executed after that nop instruction, has been set to the jump location of the jprob instruction.

all valid outcomes have already been tested

Control will never reach an instruction after a joe instruction block because all possible outcomes of a user or mixed type instruction have already been tested in that block.

instruction does nothing and was replaced with the ‘nop’ instruction

The jump location of a jprob instruction, which has a jump probability less than 1, is that jprob instruction, or the jump location of a jprob or a joe instruction is the next instruction. The instruction was replaced with the nop instruction.

list element at index idx has no effect

A jump label at zero-based index idx in arguments of a casels instruction specifies the transfer of control to the next instruction after the casels instruction. The jump label was ignored.

nested instruction at index idx: instruction does nothing

The jump location of a case instruction at zero-based index idx within a choice instruction block is the next instruction after that choice instruction block. The case instruction was ignored.

state is not marked by an ‘stt’ instruction

The assembler wants to start assembling a state at this location, but there is no stt instruction specified here. This causes the state to be defined implicitly. The warning message will not be generated if the field is_determ_opt of structure qsmm_desc_s has a non-zero value when creating the multinode model or if the node is assembled with the QSMM_ASM_DETERM_OPT flag.

test for outcome num is ignored, because the outcome has already been tested

A joe instruction, which performs a jump on outcome num, is ignored, because there was another joe instruction before that instruction, which also performs a jump on outcome num.

test for outcome num is ignored, because the outcome is out of range

A joe instruction, which performs jump on outcome num, has been ignored, because a user or mixed type instruction, which outcome is being tested, has the number of possible outcomes less than or equal to num.

unreachable state

Control will never reach the state. This warning can only be generated if the field is_determ_opt of structure qsmm_desc_s has a non-zero value when creating the multinode model or if the node is assembled with the QSMM_ASM_DETERM_OPT flag or if the state is marked by an stt instruction.

An assembler program might have names assigned to its states by arguments of stt instructions. After loading the assembler program into a node, the index of a node state, which corresponds to the name of the state, can be retrieved using the following function.

Function: int qsmm_get_node_state_by_name (qsmm_t model, const char *state_name, int node, int *state_p)

This function sets *state_p to the index of a state of a node of a multinode model specified by handle model. The state is specified by name state_name assigned by the argument of the corresponding stt instruction in an assembler program loaded into the node. Argument node specifies the identifier of the node. If state_p is NULL, then *state_p will not be set. If state_p is not NULL, and there is no assembler program loaded into the node, or the assembler program does not contain a state named state_name, then *state_p will be set to -1.

If node uses a source probability profile provided by another node, then the function will retrieve the index of node state for an assembler program loaded into the latter node. See Memory Efficient Cloning the Probability Profile, for a detailed description of this mode.

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_NOTFOUND

A node with identifier node does not exist.

QSMM_ERR_ILSEQ

The name of node state 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 retrieve the name of a node state by its index, the following function can be used.

Function: int qsmm_get_node_state_name (qsmm_t model, int node, int state, const char **state_name_pp)

This function sets *state_name_pp to the name of a state of a node of a multinode model specified by handle model. That name is specified by the argument of a corresponding stt instruction in an assembler program loaded into the node. This node is specified by identifier node. The state is specified by index state. If state_name_pp is NULL, then *state_name_pp will not be set. If state_name_pp is not NULL, and there is no name assigned to that state in the assembler program, then *state_name_pp will be set to NULL.

If node uses a source probability profile provided by another node, then the function will retrieve the state name specified in an assembler program loaded into the latter node. See Memory Efficient Cloning the Probability Profile, for a detailed description of this mode.

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 state is negative or is greater than or equal to the number of states of a node with identifier node.

QSMM_ERR_NOTFOUND

A node with identifier node does not exist.

QSMM_ERR_ILSEQ

The name of node state cannot be converted to a multibyte string according to the current locale.

QSMM_ERR_NOMEM

There was not enough memory to perform the operation.


Next: , Previous: , Up: Assembler Programs   [Contents][Index]