Next: Inspecting an Assembler Program, Previous: Assembler Instructions, Up: Assembler Programs [Contents][Index]

The state transition matrix and the action emission matrix of a node can be converted to a representation in the form of an assembler program. This conversion process is called disassembling a node.

In practice, disassembling a node is typically performed after training the node.
Before the training, an assembler program, which specifies a probability profile for the state transition matrix and the action emission matrix of the node, could be loaded into the node.
In this case, to simplify the analysis of results of training the node, it is often desirable for a developer to obtain a disassembled program, which is an assembler program previously loaded into the node, but with profile probabilities in `jprob`

and `case`

instructions changed to probabilities learned while training the node.
This mode of disassembling a node is implemented starting from QSMM version 1.15 and is called disassembling using an assembler program template.
To turn this mode on, pass the `QSMM_ASM_TEMPLATE`

flag to the function `qsmm_node_asm`

when loading an assembler program into a node that will be disassembled later (see Loading a Parsed Program into a Node).
If an assembler program was not previously loaded into a node or was loaded without specification of the `QSMM_ASM_TEMPLATE`

flag, then disassembling the node can only be performed in classic mode, which was the only mode implemented in QSMM before version 1.15.

To disassemble a node, the following function can be used.

- Function:
*int***qsmm_node_disasm***(qsmm_t*`model`, int`node`, struct qsmm_disasm_desc_s *`desc_p`, qsmm_prg_t *`prg_p`) This function disassembles a node of a multinode model specified by handle

`model`and stores the allocated handle of a disassembled program in *`prg_p`. Argument`node`specifies the identifier of the node. If`desc_p`is not`NULL`

, then *`desc_p`specifies disassembling parameters. If`desc_p`is`NULL`

, then default disassembling parameters will be used.If

`node`is previously assembled with the`QSMM_ASM_TEMPLATE`

flag or if`node`uses a source probability profile provided by another node assembled with the`QSMM_ASM_TEMPLATE`

flag, then the disassembled program will be an assembler program stored in a node assembled with the`QSMM_ASM_TEMPLATE`

flag as the template assembler program. In the disassembled program profile probabilities in`jprob`

and`case`

instructions of the template assembler program are replaced with probabilities of type`desc_p->prob_type`

(if`desc_p`is not`NULL`

) or of type`QSMM_PROB_AGGR`

(if`desc_p`is`NULL`

).In the current implementation, if

`desc_p`is not`NULL`

, then *`desc_p`will not be modified as a result of the function call. However, in future versions of the package the contents of *`desc_p`could be modified by the function, e.g. statistics on the disassembling process could be written there.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`

Either argument

`prg_p`is`NULL`

or parameters specified in *`desc_p`(if`desc_p`is not`NULL`

) are invalid.`QSMM_ERR_NOTFOUND`

A node with identifier

`node`does not exist.`QSMM_ERR_UNTIMELY`

The model instance does not exist.

`QSMM_ERR_STORAGE`

Statistics storage failure. This could leave the model instance in indeterminate state.

`QSMM_ERR_NOMEM`

There was not enough memory to perform the operation. This could leave the model instance in indeterminate state.

A structure, a pointer to which is an argument of function `qsmm_node_disasm`

, is described below.

- Structure:
**qsmm_disasm_desc_s** This structure specifies parameters of disassembling. It contains the following fields.

- Field:
*char***use_stt_start** If not 0, then generate an

`stt`

instruction at the beginning of an assembler program when the program starts with a`lookup`

instruction, and generate`stt`

and`nop1`

instructions at the beginning of a program when the program starts with a`jprob`

instruction or a`choice`

instruction block. The default is not to generate. The value of this field is ignored if a node is disassembled using an assembler program template.

- Field:
*char***use_stt_state** If not 0, then generate

`stt`

instructions at the beginnings of states. The default is not to generate. The value of this field is ignored if a node is disassembled using an assembler program template.

- Field:
*char***use_stt_lookup** If not 0, then generate

`stt`

instructions before`lookup`

instructions. The default is not to generate. The value of this field is ignored if a node is disassembled using an assembler program template.

- Field:
*char***use_stt_abort** If not 0, then generate

`stt`

instructions before`abort`

instructions. This will not be very useful unless there is not more than one`abort`

instruction in the program, which is controlled by the field`use_abort_1`

. The default is not to generate. The value of this field is ignored if a node is disassembled using an assembler program template.

- Field:
*char***use_choice** If not 0, then generate a

`choice`

instruction block instead of a contiguous block of`jprob`

instructions when the number of`jprob`

instructions in the block is greater than one. The default is to generate. The value of this field is ignored if a node is disassembled using an assembler program template.

- Field:
*char***use_abort_1** If is 0, then generate each time an

`abort`

instruction just after a user instruction when it is not known what to execute after the user instruction. If not 0, then generate each time a jump after such user instruction to a single`abort`

instruction at the end of the program and generate a jump to the program start after that`abort`

instruction. If not 0 and there are no jumps to an`abort`

instruction at the end of the program, then that`abort`

instruction followed by a jump to the program start will not be generated. The default is to generate an`abort`

instruction just after a user instruction. The value of this field is ignored if a node is disassembled using an assembler program template.

- Field:
*char***do_retain_goto_1** If not 0, then retain the most probable transition to another state for a quadruple that consists of a source state, a user or mixed type instruction invoked, an outcome of that instruction, and the contents of the look-ahead signal segment when discarding transitions with probabilities less than specified in the field

`prob_goto_min`

. This ensures that for every quadruple there remains at least one transition to another state. The field`prob_type`

specifies a type of probabilities being analyzed. The default is not to retain the most probable transition. The value of this field is ignored if a node is disassembled using an assembler program template.

- Field:
*char***do_retain_action_1** If not 0, then retain the most probable user or mixed type instruction that can be executed in a state when discarding instructions with probabilities less than specified in the field

`prob_action_min`

. This ensures that for every state there remains at least one user or mixed type instruction that can be executed in the state, i.e. the state will not be removed because it does not contain user or mixed type instructions. The field`prob_type`

specifies a type of probabilities being analyzed. The default is not to retain the most probable user or mixed type instruction. The value of this field is ignored if a node is disassembled using an assembler program template.

- Field:
*char***do_calc_prob[QSMM_PROB_COUNT]** An array that specifies additional types of probabilities to calculate for

`jprob`

and`case`

instructions, which can be printed in comments for those instructions. Indices of the array are the elements of enumeration`qsmm_prob_e`

(except for the last element) described in Generating an Optimal Action. If an element of the array has a non-zero value, then probabilities of the corresponding type will be calculated and stored in the instructions. Probabilities of a type specified in the field`prob_type`

are calculated always, regardless of the value of field`do_calc_prob`

. The default is not to calculate probabilities of additional types.

- Field:
*long***fq_goto_min** The minimum frequency of transition to another state for a quadruple that consists of a source state, a user or mixed type instruction invoked, an outcome of that instruction, and the contents of the look-ahead signal segment. Transitions with lesser frequencies are discarded out of hand. The frequencies might not be incremented for transitions performed deterministically. It is not recommended to set this field to a positive value when disassembling a node, into which an assembler program was loaded, because the assembler program might define deterministic transitions, which frequencies could be zero and which would be discarded. The default minimum frequency is 0. The value of this field is ignored if a node is disassembled using an assembler program template.

- Field:
*long***fq_action_min** The minimum frequency of invocation of user or mixed type instruction in a state. Instructions invoked lesser number of times are discarded out of hand. The frequencies might not be incremented for instruction invocations performed deterministically. It is not recommended to set this field to a positive value when disassembling a node, into which an assembler program was loaded, because the assembler program might define deterministic instruction invocations which frequencies could be zero. The default minimum frequency is 0. The value of this field is ignored if a node is disassembled using an assembler program template.

- Field:
*double***prob_goto_min** When disassembling a node using an assembler program template, this field specifies the minimum probability in

`jprob`

and`case`

instructions that correspond to the state transition matrix of the node. Instructions with lesser probabilities will be removed from the disassembled program, although they are present in the assembler program template.When disassembling a node without using an assembler program template, this field specifies the minimum probability of transition to another state for a quadruple that consists of a source state, a user or mixed type instruction invoked, an outcome of that instruction, and the contents of the look-ahead signal segment. Transitions with lesser probabilities are discarded after discarding transitions with frequencies less than a frequency specified in the field

`fq_goto_min`

and after renormalizing transition probabilities. When discarding transitions with lesser probabilities, if`do_retain_goto_1`

is not 0, then the most probable transition will be retained.The field

`prob_type`

specifies a type of probabilities being analyzed. The default minimum probability is 0.

- Field:
*double***prob_action_min** When disassembling a node using an assembler program template, this field specifies the minimum probability in

`jprob`

and`case`

instructions that correspond to the action emission matrix of the node. Instructions with lesser probabilities will be removed from the disassembled program, although they are present in the assembler program template.When disassembling a node without using an assembler program template, this field specifies the minimum probability of invocation of user or mixed type instruction in a state. Instructions with lesser invocation probabilities are discarded after discarding instructions with frequencies less than a frequency specified in the field

`fq_action_min`

and after renormalizing the invocation probabilities. When discarding instructions with lesser invocation probabilities, if`do_retain_action_1`

is not 0, then the most probable instruction will be retained.The field

`prob_type`

specifies a type of probabilities being analyzed. The default minimum probability is 0.

- Field:
*enum qsmm_prob_e***prob_type** A type of probabilities to calculate for

`jprob`

and`case`

instructions.When disassembling a node using an assembler program template, those probabilities are compared with probabilities in the fields

`prob_goto_min`

and`prob_action_min`

to determine whether to discard specific`jprob`

and`case`

instructions.When disassembling a node without using an assembler program template, this field specifies the type of probability, by which

`jprob`

and`case`

instructions within corresponding instruction blocks are sorted in descending order. This field also specifies the type of probabilities of transitions to other states and the type of probabilities of invocation of user and mixed type instructions, which are compared with probabilities in the fields`prob_goto_min`

and`prob_action_min`

to perform discarding when necessary.See Generating an Optimal Action, for a description of elements of enumeration

`qsmm_prob_e`

. The default type of probabilities is`QSMM_PROB_AGGR`

.

- Field:

An instance of structure `qsmm_disasm_desc_s`

, a pointer to which is passed to the function `qsmm_node_disasm`

, should be zeroed using the function `memset`

before setting values of structure fields.

When disassembling a node without using an assembler program template, the following comments are generated for instructions in a disassembled program.

- At the beginnings of states: the index of a state and the number of times control was transferred to the state.
- For user and mixed type instructions: the number of instruction invocations (calls).
- For
`jmp`

,`joe`

,`jprob`

, and`case`

instructions: the number of jumps performed.

Note the following regarding the frequencies.

- Frequencies less than 2 are not printed in comments.
- If an assembler program, which defines deterministic state transitions and/or instruction invocations, is loaded into the node, then frequencies printed in comments will be inaccurate.
- Frequencies printed in comments may be inconsistent among themselves if some instructions are discarded according to parameters of disassembling.
- Probabilities of type
`QSMM_PROB_FQ`

are calculated on the basis of frequencies of non-deterministic choices made and sometimes can be less by 1 than the values expected due to the of way how the frequencies are incremented.

When disassembling a node without using an assembler program template, to generate the most probable completely deterministic program, set the fields `prob_goto_min`

, `prob_action_min`

, `do_retain_goto_1`

, and `do_retain_action_1`

of structure `qsmm_disasm_desc_s`

to 1.

Below there is given an example of calling the function `qsmm_node_disasm`

to generate a program for subsequent assembling.
It is assumed that there is no assembler program loaded into a node for which the function `qsmm_node_disasm`

is called.

qsmm_prg_t prg=0; struct qsmm_disasm_desc_s disasm_desc; memset(&disasm_desc,0,sizeof(disasm_desc)); // Insert `stt' instructions at appropriate places. disasm_desc.use_stt_start=1; disasm_desc.use_stt_state=1; disasm_desc.use_stt_lookup=1; disasm_desc.use_stt_abort=1; // Make probabilistic jumps to look intelligible. disasm_desc.use_choice=1; // Simplify handling unexplored control paths. disasm_desc.use_abort_1=1;

// Do not produce code that was never executed. disasm_desc.fq_goto_min=1; disasm_desc.fq_action_min=1;

// Do not generate probabilistic jumps with // rounded probabilities less than 1%. disasm_desc.prob_goto_min=0.005; disasm_desc.prob_action_min=0.005; qsmm_node_disasm(qsmm,node,&disasm_desc,&prg);

To disassemble a node assembled with the `QSMM_ASM_TEMPLATE`

flag, the above example can be reduced to the lesser number of lines because assignments to other fields are ignored in this mode.

qsmm_prg_t prg=0; struct qsmm_disasm_desc_s disasm_desc; memset(&disasm_desc,0,sizeof(disasm_desc)); // Remove `jprob' and `case' instructions with // rounded probabilities less than 1%. disasm_desc.prob_goto_min=0.005; disasm_desc.prob_action_min=0.005; qsmm_node_disasm(qsmm,node,&disasm_desc,&prg);