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


5.8 Loading a Parsed Program into a Node

An assembler program specifies a probability profile loadable into the nodes of a multinode model. Assembling a node is loading into it a probability profile specified by a memory representation of an assembler program. The instruction class set of this node contains instruction classes for all user and mixed-type instructions used in the assembler program. The assembler supports loading assembler programs into the nodes of a multinode model with zero-length look-ahead signal segment only.

Warning: if the environment state identification engine is a small actor (the field is_large_env of qsmm_desc_s structure passed to the function qsmm_create is zero), and it uses a built-in function for computing the relative probability of an output signal, the adaptive behavior of assembler programs specifying nondeterministic state transitions is generally ill-defined. Similarly, if the instruction emitting engine is a small actor (the field is_large_opt of qsmm_desc_s is zero), and it uses a built-in function for computing the relative probability of an output signal, the adaptive behavior of assembler programs specifying nondeterministic instruction emissions is also generally ill-defined. Therefore, tend to using large actors for the environment state identification engine and instruction emitting engine in these cases. The behavior is ill-defined, because profile probabilities act as output signal weights, and the explanation in Number of Output Signals applies.

The functions qsmm_node_asm and qsmm_get_prg_nstate_v2 described further on in this section take the argument flags specifying the modes of processing a memory representation of an assembler program. That argument is a bitmask defined as a subset of macros described below merged by bitwise “or.”

Macro: QSMM_ASM_DETERM_OPT

Impose the following restriction on a probability profile for the action emission matrix: for every node state, the probability profile must define deterministic choice of an instruction class emitted in the node state. Setting the field is_determ_opt of qsmm_desc_s structure to a non-zero value when creating a multinode model also turns on this mode but for all nodes in the multinode model. In this mode, the assembler considers that states begin just before user and mixed-type instructions, and there is no need to mark unnamed states by stt instructions. If you use stt instructions in this mode, you cannot place them just before jprob instructions and choice instruction blocks.

Macro: QSMM_ASM_TEMPLATE

Store the memory representation of an assembler program in the node as a template. The function qsmm_node_disasm automatically uses the template when disassembling the node: a disassembled program is the template program with profile probabilities in jprob and case instructions replaced with probabilities that have a type specified in the field prob_type of qsmm_disasm_desc_s structure passed to qsmm_node_disasm or the type QSMM_PROB_AGGR when using default disassembling parameters. The field prob_goto_min of qsmm_disasm_desc_s specifies a minimum probability in jprob and case instructions corresponding to the state transition matrix. The field prob_action_min of qsmm_disasm_desc_s specifies a minimum probability in jprob and case instructions corresponding to the action emission matrix. The disassembler removes jprob and case instructions containing lesser probabilities from the disassembled program, although those instructions were in the template program. The disassembler can calculate additional probabilities with types specified by the field do_calc_prob of qsmm_disasm_desc_s for subsequent adding to comments for jprob and case instructions.

Macro: QSMM_ASM_VAR_OUT

Collect information on output probability variables and output probabilities arrays in the assembler program. You use them to fetch probabilities learned while executing or training the node. Output probability variables contain probabilities for jprob and case instructions. Output probabilities arrays contain probabilities for choice instruction blocks. See Output Variables, and Output Arrays, for more information.

Macro: QSMM_ASM_VAR_AUX

Allow using auxiliary probability variables in the assembler program. Those variables act as constants and are neither controlled nor output variables. The disassembler merely replaces the occurrences of auxiliary probability variables in jprob and case instructions with the values of those variables specified by ‘prob’ keywords. See Auxiliary Variables, for more information.

Use the following function to load a parsed assembler program into a node.

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

This function assembles a node of a multinode model—loads a probability profile specified by a program prg into the node. The argument node specifies the identifier of this node. The argument flags specifies assembling modes (see above for the description of macros corresponding to the bits of this bitmask taken into account). If msglist is not NULL, the function adds to a message list msglist warning messages generated while assembling.

The function clears event history statistics collected for the node. If the node already has a probability profile loaded, the function first unloads the profile. To clear the event history statistics and unload the profile, this function calls the function qsmm_node_unload.

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_NOTFOUND

A node with identifier node does not exist.

QSMM_ERR_PRG

The program prg has an error. If the multinode model has an error handler assigned, it receives a message list with at least one error message.

QSMM_ERR_UNTIMELY

The model instance does not exist.

QSMM_ERR_PROFSRCP

The node is a probability profile source for other nodes. See Memory Efficient Cloning the Probability Profile, for more information on this mode.

QSMM_ERR_NOSTATE

The node does not have enough states.

QSMM_ERR_MPROF

No room in the pool of probabilities lists in normal form for a large actor representing the environment state identification engine or instruction emitting engine. The fields profile_pool_env_sz and profile_pool_opt_sz of qsmm_desc_s structure passed to the function qsmm_create specify the sizes of those pools.

QSMM_ERR_UNSUPPLA

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

QSMM_ERR_STORAGE

A Storage API function reported storage failure.

QSMM_ERR_STATS

Inconsistent statistics on an action choice state or cycle type detected.

QSMM_ERR_ILSEQ

Unable to convert a multibyte string to a wide string or vice versa according to a current locale.

QSMM_ERR_NOMEM

There was not enough memory to perform the operation.

Errors QSMM_ERR_MPROF, QSMM_ERR_STORAGE, QSMM_ERR_STATS, QSMM_ERR_ILSEQ, and QSMM_ERR_NOMEM can leave the probability profile of this node in inconsistent state. If after removing a reason of this error a repeated call to this function succeeds, the probability profile becomes consistent.

In the current implementation, to load an assembler program into a node, it must have a sufficient number of states. Otherwise, the function qsmm_node_asm reports QSMM_ERR_NOSTATE. The function qsmm_set_node_nstate can set the number of states of a node. That number may not exceed the maximum number of states specified by the function qsmm_set_nstate_max for the instruction class set of this node. Use the following function to determine the number of states for passing to qsmm_set_node_nstate and qsmm_set_nstate_max.

Function: int qsmm_get_prg_nstate_v2 (qsmm_t model, const char *instr_class_set_name, int rez1, unsigned int flags, qsmm_prg_t prg, qsmm_msglist_t msglist, qsmm_sig_t *nstate_p)

This function calculates the minimum number of states required for nodes of a multinode model to load a program prg into them. The argument instr_class_set_name specifies the name of instruction class set of those nodes. If msglist is not NULL, the function adds to a message list msglist warning messages generated during the calculation.

The argument flags specifies assembling modes (see the beginning of this section for the description of macros corresponding to the bits of this bitmask taken into account). Additionally, flags can contain bitmask QSMM_EXCEPT_NOTFOUND or QSMM_EXCEPT_TYPE (or QSMM_EXCEPT_ALL including both of them). 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. For certainty, the argument flags passed to this function should be equal to the argument flags passed to the function qsmm_node_asm when loading the program prg into particular nodes of this model.

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

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 *nstate_p to QSMM_SIG_INVALID (if nstate_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 *nstate_p to QSMM_SIG_INVALID (if nstate_p is not NULL) and returns 0.

QSMM_ERR_PRG

The program prg has an error. If the multinode model has an error handler assigned, it receives a message list with at least one error message.

QSMM_ERR_UNSUPPLA

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

QSMM_ERR_ILSEQ

Unable to convert a multibyte string to a wide string or vice versa according to a current locale.

QSMM_ERR_NOMEM

There was not enough memory to perform the operation.

The functions qsmm_node_asm and qsmm_get_prg_nstate_v2 can generate the following warning messages.

‘nop’ instruction inserted

The assembler inserted a nop instruction at the beginning of an implicitly defined state because the state does not start with a user or mixed-type instruction.

‘stt’ instruction expected

The assembler expects the beginning of a state in the assembler program, but there is no stt instruction at that place. The assembler defines the state implicitly. If the place has the definitions of location labels, the assembler may expect the beginning of a state at that place based on the structure of assembler program fragments containing jumps to those location labels. The assembler does not generate this warning if the field is_determ_opt of qsmm_desc_s structure passed to the function qsmm_create is non-zero, or the function qsmm_node_asm receives QSMM_ASM_DETERM_OPT in flags.

all valid outcomes already tested

Control never reaches an instruction after a joe instruction block because the block contains tests for all possible outcomes of a user or mixed-type instruction.

ignoring the test for outcome num because such test already exists

The assembler ignores the joe instruction performing a jump on outcome num because there was an earlier joe instruction also performing a jump on outcome num.

ignoring the test for outcome num because the outcome is out of range

The assembler ignores the joe instruction performing a jump on outcome num because that joe instruction tests the outcome of a user or mixed-type instruction with the number of possible outcomes less than or equal to num.

instruction has no effect because jump probability is 0

The assembler ignores this jprob or case instruction because it specifies a jump with probability 0.

instruction has no effect because of a jump beneath the ‘choice’ block

The assembler ignores this case instruction because it specifies a jump beneath a containing choice instruction block.

instruction has no effect because of a jump to the next instruction

The assembler ignores this jprob or joe instruction because it specifies a jump to the next instruction.

instruction has no effect because of a possible jump to itself

The assembler ignores this jprob instruction because it specifies a jump to itself with probability less than 1.

instruction is replaceable with a ‘jmp’ instruction

Beneath the jprob instruction with jump probability greater than 0 there is a jmp instruction transferring control to that jprob instruction. The jprob instruction does not specify a possible jump to this jmp instruction. The assembler replaces the jprob instruction with a nop instruction and sets its next instruction address equal to the jump location of that jprob instruction. Simply put, you can replace the jprob and jmp instructions with a single jmp instruction.

unreachable state

Control never reaches the state. The assembler generates this warning only when an stt instruction marks the beginning of that state, the field is_determ_opt of qsmm_desc_s structure passed to the function qsmm_create is non-zero, or the function qsmm_node_asm receives QSMM_ASM_DETERM_OPT in flags.

An assembler program can have names assigned to its states by the arguments of stt instructions. Use the following function to retrieve the index of a state of a node by the name of this state after loading an assembler program into the node.

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

This function retrieves the index of a state of a node of a multinode model by the name of this state. The argument state_name specifies that name assigned by an stt instruction marking the beginning of this state in an assembler program loaded into the node. The argument node specifies the identifier of this node.

On success, the function returns a non-negative value and sets *state_p if state_p is not NULL. If the state exists, the function sets *state_p to the index of that state. If the node does not have an assembler program loaded, or the assembler program does not define a state named state_name, the function sets *state_p to QSMM_SIG_INVALID.

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

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

QSMM_ERR_NOTFOUND

A node with identifier node does not exist.

QSMM_ERR_ILSEQ

Unable to convert state_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 function to retrieve the name of a node state by its index.

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

This function retrieves the name of a state of a node of a multinode model by the index of this state. An stt instruction in an assembler program loaded into the node assigns that name to the state. The argument node specifies the identifier of this node. The argument state specifies the index of this state.

On success, the function returns a non-negative value and sets *state_name_pp if state_name_pp is not NULL. If the state has a name assigned by the argument of an stt instruction, the function sets *state_name_pp to this name. If the state does not have an assigned name, the function sets *state_name_pp to NULL.

If the node uses a source probability profile provided by another node, the function retrieves a 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.

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

QSMM_ERR_INVAL

The argument state is greater than or equal to the number of node states.

QSMM_ERR_NOTFOUND

A node with identifier node does not exist.

QSMM_ERR_ILSEQ

Unable to convert a state name to a multibyte string according to a current locale.

QSMM_ERR_NOMEM

There was not enough memory to perform the operation.


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