Disassembling a Node (QSMM Programmer Manual)

5.4 Disassembling a Node

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.

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.