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


5.6 Printing an Assembler Program

To get a string representation of an instruction of an assembler program, the following function can be used.

Function: int qsmm_instr_str (char *bufp, int bufsz, qsmm_instr_t instr, struct qsmm_dump_instr_desc_s *desc_p)

This function stores in buffer bufp of size bufsz bytes a string representation of instruction instr generated according to parameters specified in *desc_p. If desc_p is NULL, then default parameters of generating the string representation will be used. The function may change either *desc_p or the instance of structure qsmm_dump_instr_desc_s where the default parameters are stored (when desc_p is NULL).

On success, the function returns a non-negative number of bytes required for a string representation of the instruction, not counting trailing byte 0. The returned value greater than or equal to bufsz indicates that the string representation was truncated. If bufsz is greater than 0, then the truncated string representation of length bufsz–1 bytes will be written to bufp and terminated with byte 0. It is allowed to pass 0 for both bufp and bufsz to determine the length of the string representation of an instruction.

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

QSMM_ERR_INVAL

The value of bufsz is less than 0, or the value of bufsz is greater than 0 and bufp is NULL, or desc_p is not NULL and parameters specified in *desc_p are invalid, or desc_p is NULL and the default parameters are invalid.

QSMM_ERR_NOMEM

There was not enough memory to perform the operation.

There is an instance of structure qsmm_dump_instr_desc_s defined within the library, where the default parameters of generating a string representation of instruction are stored. To get a pointer to that instance, the following function can be used.

Function: struct qsmm_dump_instr_desc_s * qsmm_get_default_dump_instr_desc ()

This function returns a pointer to default parameters of generating a string representation of an assembler instruction. The parameters can be changed using that pointer. The function never returns 0.

A structure, which specifies parameters of generating a string representation of instruction, is described below.

Structure: qsmm_dump_instr_desc_s

This structure specifies parameters of generating a string representation of an assembler instruction. It contains the following fields.

Field: char is_line_after_comment_above

If not 0, then if there is a comment above the instruction stored with the instruction and the field do_print_comment_above has a non-zero value, then insert an empty line after the comment and before the instruction. This field is also used in a similar way to determine whether to insert an empty line after a comment above a definition of a probability variable or a probabilities list in an assembler program and before the definition. The default is to insert an empty line.

Field: char is_line_after_multiline_comment_right

If not 0 and the field do_print_comment_right has a non-zero value, then insert an empty line after an instruction, a jump label (in arguments of casels instruction), the definition of a probability variable, a probabilities list, or its element that has a multiline comment to the right if the next line in the assembler program contains a comment to the right. The default is to insert an empty line.

Field: char is_space_after_comma

If not 0, then insert a space after every comma not within string literals in instruction parameters. This field is also used in a similar way to determine whether to insert a space after every comma in definitions of probabilities lists in an assembler program. The default is to insert a space.

Field: char do_print_label

If not 0 and the instruction has a location label defined, then print the location label to the left of the instruction. If there are several location labels defined for the instruction, then all the labels except for the last one will be printed on separate lines. If there is no room between the last label and an instruction name, then the last label will also be printed on a separate line. The default is to print location labels.

Field: char do_print_name

If not 0, then print an instruction name. The default is to print.

Field: char do_print_param

If not 0, then print instruction parameters. The default is to print.

Field: char do_print_comment_above

If not 0 and there is a comment above the instruction stored with the instruction, then print that comment. This field is also used in a similar way to determine whether to print comments above definitions of probability variables and probabilities lists in an assembler program. The default is to print the comments.

Field: char do_print_comment_right

If not 0 and there is a comment to the right of an instruction or a jump label (in arguments of casels instruction) stored with the instruction or the jump label, then print that comment. This field is also used in a similar way to determine whether to print comments to the right of definitions of probability variables, probabilities lists and their elements in an assembler program. The default is to print the comments.

Field: char do_print_var

If not 0, then if there is a name of probability variable stored in a jprob or a case instruction and the value of field prob_type is equal to QSMM_PROB_PROFILE, then print that name of variable. Otherwise, print a probability. This field also determines whether to print names of probability variables in definitions of probabilities lists in an assembler program where those names were provided in the program source text. The default is to print names of probability variables when possible.

Field: char do_print_state_name

If not 0, then if there is a state name stored with an stt instruction and the field do_print_param has a non-zero value, then print the state name in that instruction. The default is to print state names.

Field: char do_print_prob[QSMM_PROB_COUNT]

An array that specifies additional types of probabilities to print in comments for jprob and case instructions to the right. 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, the index of the element is not equal to the value of field prob_type, and the value of field do_print_comment_right is non-zero, then probabilities of the corresponding type will be printed in the comments. When dumping an instruction of a program disassembled using an assembler program template, if that instruction is used in the template in an ambiguous context, then ‘?’ will be printed for the probabilities. The default is not to print probabilities in the comments.

Field: int prob_prec

The number of digits after the decimal point to print for probabilities in jprob and case instructions and comments for those instructions to the right according to the value of field do_print_prob. It is also the number of digits after the decimal point to print for probabilities in definitions of probability variables, probabilities lists and their elements in an assembler program. If is a non-negative number, then fixed-point notation will be used. If is a negative number, then exponential notation with the number of digits after the decimal point equal to the absolute value of the field will be used. The default number of digits to print after the decimal point is equal to 2.

Field: int col_name

If is a positive number, then a column to align the start of instruction name to. If not a positive number, then do not perform the alignment. This field also indicates a column to align the start of ‘.data’ and ‘.code’ directives, a column to align the start of comments above instructions, definitions of probability variables and probabilities lists, a column to align the start of a tail comment in an assembler program if the assembler program contains that comment. If not a positive number, then ‘.data’ and ‘.code’ directives and the comments will be aligned to column 1. The default is to align to column 9.

Field: int col_param

If is a positive number, then a column to align the start of instruction parameters to. If not a positive number, then do not perform the alignment. The default is to align to column 17.

Field: int col_comment

If is a positive number, then a column to align the start of a comment to the right of instruction to. If not a positive number, then do not perform the alignment. The default is to align to column 33.

Field: int margin_right

If is a positive number, then a right margin column to use for comments. Longer comments will be split into multiple lines. If not a positive number, then do not split comments into multiple lines based on a right margin column. The default is not to split.

Field: int margin_right_param

If is a positive number, then a right margin column to use for lists of arguments of user and casels instructions. Longer lists will be split into multiple lines. Commas not within string literals (those literals can be parts of arguments of user instructions) are used as places, at which splitting can be performed. If not a positive number, then do not split the lists into multiple lines based on a right margin column. The default right margin column is 30.

Field: int nline_comment_right

The function qsmm_instr_str sets the value of this field. The function writes here the number of lines in a comment to the right of the instruction or the last jump label in arguments of a casels instruction. If the field do_print_comment_right has zero value, the instruction or the last jump label does not have a comment to the right, or the instruction is a user instruction, which arguments list was split into multiple lines and which has a comment to the right with the number of lines less than the number of lines of the arguments list, then 0 will be written here. If the field do_print_comment_right has a non-zero value and the instruction or the last jump label has a comment to the right, which was split into multiple lines according to the value of field margin_right, then a value greater than 1 will be written here (with the exception of a user instruction with a comment to the right that occupies the number of lines less than the number of lines of arguments list of the instruction). The value of this field is used by the function qsmm_prg_dump to insert an empty line after an instruction that has a multiline comment to the right when the next instruction has a comment to the right.

Field: int nline_param

The function qsmm_instr_str sets the value of this field. The function writes here the number of lines of arguments list of an instruction printed. The value of this field is used by the function qsmm_prg_dump to determine whether to insert empty lines around multiline instructions.

Field: enum qsmm_prob_e prob_type

A type of probabilities to print in jprob and case instructions. See Generating an Optimal Action, for a description of elements of enumeration qsmm_prob_e. When dumping an instruction of a program disassembled using an assembler program template, if that instruction is used in the template in an ambiguous context, then ‘?’ will be printed for the probability. The default type of probabilities is QSMM_PROB_AGGR.

Note: when converting a disassembled program or its specific instructions to a string representation, be sure to set the fields do_print_prob and prob_type of structure qsmm_dump_instr_desc_s to values consistent with values of fields do_calc_prob and prob_type of structure qsmm_disasm_desc_s used when disassembling the program. Otherwise, zero probabilities will be printed.

To dump a program to a stream, the following function can be used.

Function: int qsmm_prg_dump (qsmm_prg_t prg, struct qsmm_dump_prg_desc_s *desc_p, FILE *filep)

This function dumps program prg to stream filep according to parameters specified in *desc_p. If desc_p is NULL, then default parameters of dumping a program will be used.

In the current implementation, *desc_p (if desc_p is not NULL) or the instance of structure qsmm_dump_prg_desc_s where the default parameters are stored (if desc_p is NULL), are not modified as a result of the function call. However, in future versions of the package those variables could be modified by the function, e.g. statistics on the dumping 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

Argument desc_p is not NULL and parameters specified in *desc_p are invalid, or desc_p is NULL and default parameters, a pointer to which is returned by the function qsmm_get_default_dump_prg_desc, are invalid.

QSMM_ERR_NOMEM

There was not enough memory to perform the operation.

There is an instance of structure qsmm_dump_prg_desc_s defined within the library, where the default parameters of dumping a program are stored. To get a pointer to that instance, the following function can be used.

Function: struct qsmm_dump_prg_desc_s * qsmm_get_default_dump_prg_desc ()

This function returns a pointer to default parameters of dumping an assembler program. The parameters can be changed using that pointer. The function never returns 0.

A structure, which specifies parameters of dumping a program, is described below.

Structure: qsmm_dump_prg_desc_s

This structure specifies parameters of dumping an assembler program. It contains the following fields.

Field: char do_print_vars

If not 0 and the program contains definitions of probability variables and/or probabilities lists, then dump a “data” section with those definitions. The default is to dump.

Field: char is_line_before_label

If not 0, then insert an empty line before a line with a location label definition. If an instruction has several location labels defined (which are dumped on separate lines), then an empty line will be inserted only before a line with the first location label definition. The default is to insert.

Field: char is_line_before_isolated_comment

If not 0, then insert an empty line before a comment above an instruction or a definition of a probability variable or a probabilities list if the instruction or the definition has that comment, and insert an empty line before a comment at the end of the program if the program contains that comment and the field do_print_comment_tail has a non-zero value. The default is to insert.

Field: char are_lines_around_choice

If not 0, then insert empty lines before and after choice instruction blocks. The default is to insert.

Field: char are_lines_around_multiline_param

If not 0, then insert empty lines before and after multiline user and casels instructions. The default is to insert.

Field: char do_print_comment_tail

If not 0 and the program contains a comment at the end, then dump that comment. The default is to dump.

Field: int col_var_type

If is a positive number, then a column to align the start of ‘prob’, ‘probeq’, and ‘probls’ keywords to. If not a positive number, then do not perform the alignment. The default is to align to column 17.

Field: int col_var_val

If is a positive number, then a column to align the start of a probability variable or probabilities list value to. If not a positive number, then do not perform the alignment. The default is to align to column 25.

Field: int col_var_comment

If is a positive number, then a column to align the start of a comment to the right of definition of a probability variable, a probabilities list, or its element. If not a positive number, then do not perform the alignment. The default is to align to column 33.

Field: int margin_right_ls

If is a positive number, then a right margin column to use for probabilities lists defined with the help of ‘probls’ keywords. Longer lists will be split into multiple lines. If not a positive number, then do not split the lists into multiple lines based on a right margin column. The default right margin column is 30.

Field: struct qsmm_dump_instr_desc_s * dump_instr_desc_p

If not 0, then parameters of dumping instructions of the program. If is 0, then use default parameters returned by the function qsmm_get_default_dump_instr_desc.


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