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

You can convert the state transition matrix and action emission matrix of a node to an assembler program—disassemble the node.

You typically disassemble a node after executing or training it.
Before executing the node, you can load into it an assembler program specifying a probability profile for the state transition matrix and action emission matrix.
To simplify the analysis of results of training the node, it might be desirable 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.
To turn on this mode—disassembling using an assembler program template,—pass the `QSMM_ASM_TEMPLATE`

flag to the function `qsmm_node_asm`

when loading an assembler program into a node you are going to disassemble later (see Loading a Parsed Program into a Node).
If a node does not have an assembler program loaded, or the node has an assembler program loaded without specifying the `QSMM_ASM_TEMPLATE`

flag, you can only disassemble the node in classic mode.

Use the following function to disassemble a node.

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

`model`and stores the allocated handle of a disassembled program in *`prg_p`if`prg_p`is not`NULL`

. The argument`node`specifies the identifier of this node. If`desc_p`is not`NULL`

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

, the function uses default disassembling parameters.If the function

`qsmm_node_asm`

previously assembled the node with the`QSMM_ASM_TEMPLATE`

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

flag, the disassembled program is a template assembler program with replaced probabilities in`jprob`

and`case`

instructions. If`desc_p`is not`NULL`

, probabilities of`desc_p->prob_type`

type replace profile probabilities in those`jprob`

and`case`

instructions. If`desc_p`is`NULL`

, probabilities of`QSMM_PROB_AGGR`

type replace the profile probabilities.In the current implementation, the function does not modify *

`desc_p`if`desc_p`is not`NULL`

. However, in a future implementation, the function may modify *`desc_p`, for example, to store there statistics on the disassembling process.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_INVAL`

The argument

`desc_p`is not`NULL`

, and parameters in *`desc_p`are invalid.`QSMM_ERR_UNTIMELY`

The model instance does not exist.

`QSMM_ERR_CALLBACK`

A helper function for computing the relative probability of an output signal reported an error by returning

`NaN`

. The function`qsmm_actor_calc_action_prob`

calls the helper function.`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_STORAGE`

,`QSMM_ERR_STATS`

,`QSMM_ERR_ILSEQ`

, and`QSMM_ERR_NOMEM`

can leave the model instance in inconsistent state.

The description of a structure passed to the function `qsmm_node_disasm`

is below.

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

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

`stt`

instruction at the beginning of an assembler program if it started with a`lookup`

instruction, and generate`stt`

and`nop1`

instructions at the beginning of an assembler program if it started with a`jprob`

instruction or`choice`

instruction block. The default is not to generate. The disassembler ignores this field when disassembling a node using an assembler program template.

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

`stt`

instructions at the beginnings of states. The default is not to generate. The disassembler ignores this field when disassembling a node using an assembler program template.

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

`stt`

instructions before`lookup`

instructions. The default is not to generate. The disassembler ignores this field when disassembling a node using an assembler program template.

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

`stt`

instructions before`abort`

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

instruction in an assembler program (the field`use_abort_1`

sets this mode). The default is not to generate. The disassembler ignores this field when disassembling a node using an assembler program template.

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

`choice`

instruction blocks instead of contiguous blocks of`jprob`

instructions when the number of`jprob`

instructions in a block is greater than one. The default is to generate. The disassembler ignores this field when disassembling a node using an assembler program template.

- Field:
*char***use_abort_1** If is 0, and there is no information what to execute after a user or mixed-type instruction, generate an

`abort`

instruction after the user or mixed-type instruction. If not 0, generate a jump after this user or mixed-type instruction to a single`abort`

instruction at the end of an assembler program and generate a jump to the start of this assembler program after this`abort`

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

instruction at the program end, skip generating that`abort`

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

instruction after a user or mixed-type instruction. The disassembler ignores this field when disassembling a node using an assembler program template.

- Field:
*char***do_retain_goto_1** If not 0, retain the most probable transition to a target state for every quadruple consisting of a source state, a user or mixed-type instruction emitted in the source state, the outcome of this instruction, and the content of look-ahead signal segment when discarding transitions with probabilities less than specified in the field

`prob_goto_min`

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

specifies the type of analyzed probabilities. The default is not to retain the most probable transition. The disassembler ignores this field when disassembling a node using an assembler program template.

- Field:
*char***do_retain_action_1** If not 0, retain the most probable user or mixed-type instruction emittable in every state when discarding instructions with probabilities less than specified in the field

`prob_action_min`

. This retaining ensures that for every state there remains at least one emittable user or mixed-type instruction—the disassembler will not remove a state because the state is without emittable user and mixed-type instructions. The field`prob_type`

specifies the type of analyzed probabilities. The default is not to retain the most probable user or mixed-type instruction. The disassembler ignores this field when disassembling a node using an assembler program template.

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

`jprob`

and`case`

instructions optionally printed in comments for those instructions. The indices of this array are the elements of`qsmm_prob_e`

enumeration (except for its last element) described in Emitting an Output Signal. If an element of this array is non-zero, the disassembler calculates probabilities of a corresponding type and stores them in the instructions. The disassembler calculates probabilities of a type specified in the field`prob_type`

regardless of`do_calc_prob`

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

- Field:
*long***fq_goto_min** The minimum frequency of a transition to a target state for a quadruple consisting of a source state, a user or mixed-type instruction emitted in the source state, the outcome of this instruction, and the content of look-ahead signal segment. The disassembler discards transitions performed lesser numbers of times. The default minimum frequency is 0. The disassembler ignores this field when disassembling a node using an assembler program template.

- Field:
*long***fq_action_min** The minimum frequency of emitting a user or mixed-type instruction in a state. The disassembler discards instructions emitted lesser numbers of times. The default minimum frequency is 0. The disassembler ignores this field when disassembling a node using an assembler program template.

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

`jprob`

and`case`

instructions corresponding to the state transition matrix. The disassembler removes instructions containing lesser probabilities from a disassembled program, although those instructions were in the assembler program template.When disassembling a node without using an assembler program template, this field specifies the minimum probability of a transition to a target state for a quadruple consisting of a source state, a user or mixed-type instruction emitted in the source state, the outcome of this instruction, and the content of look-ahead signal segment. The disassembler discards transitions with lesser probabilities 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, the disassembler retains most probable transitions.The field

`prob_type`

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

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

`jprob`

and`case`

instructions corresponding to the action emission matrix. The disassembler removes instructions containing lesser probabilities from a disassembled program, although those instructions were in the assembler program template.When disassembling a node without using an assembler program template, this field specifies the minimum probability of emitting a user or mixed-type instruction in a state. The disassembler discards instructions with lesser emitting probabilities after discarding instructions with frequencies less than a frequency specified in the field

`fq_action_min`

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

is not 0, the disassembler retains most probable instructions.The field

`prob_type`

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

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

`jprob`

and`case`

instructions.When disassembling a node using an assembler program template, the disassembler compares those probabilities 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 probabilities for sorting

`jprob`

and`case`

instructions in descending order within corresponding instruction blocks. This field also specifies the type of state transition probabilities and instruction emission probabilities for comparing with probabilities in the fields`prob_goto_min`

and`prob_action_min`

.See Emitting an Output Signal, for the description of elements of

`qsmm_prob_e`

enumeration. The default type of probabilities is`QSMM_PROB_AGGR`

.

- Field:

Zero by the function `memset`

an instance of `qsmm_disasm_desc_s`

structure before setting the fields of this instance passed to the function `qsmm_node_disasm`

.

When disassembling a node without using an assembler program template, the disassembler generates the following comments for instructions in a disassembled program:

- At the beginnings of states: the index of a state and the number of transfers of control 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 that include the numbers of transfers of control to states, the numbers of instruction invocations, and the numbers of jumps performed:

- The disassembler does not include frequencies less than 2 in comments.
- Frequencies printed in comments may be inconsistent among themselves if the disassembler discarded some instructions according to disassembling parameters.

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

, `prob_action_min`

, `do_retain_goto_1`

, and `do_retain_action_1`

of `qsmm_disasm_desc_s`

structure.

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

to generate a program for subsequent assembling.
A disassembled node does not have an assembler program loaded.

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; // Improve the readability of probabilistic jumps. disasm_desc.use_choice=1; // Simplify handling unexplored control paths. disasm_desc.use_abort_1=1;

// Do not generate never executed code. disasm_desc.fq_goto_min=1; disasm_desc.fq_action_min=1;

// Do not generate probabilistic jumps for // 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);

An example of calling the function `qsmm_node_disasm`

for a node assembled with the `QSMM_ASM_TEMPLATE`

flag occupies a lesser number of lines because the disassembler uses a small subset of fields of `qsmm_disasm_desc_s`

structure 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);

Refer to the files `tests/disasm2.c` and `tests/lookup2.c` for the methods of assembling a previously disassembled program.