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


5.4 Disassembling a Node

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.

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.

Note the following regarding the frequencies.

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

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