Printing an Assembler Program (QSMM Programmer Manual)

5.6 Printing an Assembler Program

Use the following function to get a string representation of an assembler instruction.

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

This function stores in a buffer bufp with size bufsz bytes a string representation of an instruction instr. If desc_p is not NULL, the function generates the string representation according to parameters in *desc_p. If desc_p is NULL, the function generates the string representation according to default parameters. The function may change either *desc_p or those default parameters.

On success, the function returns a non-negative number of bytes required to store the string representation not counting finalizing byte 0. If bufsz is less than INT_MAX, a returned value greater than or equal to bufsz indicates the truncation of a string representation. In this case, if bufsz is positive, the function stores in bufp a truncated string representation with length bufsz–1 bytes and terminates a stored string with byte 0. The function supports passing 0 for both bufp and bufsz to determine the length of a string representation.

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

QSMM_ERR_INVAL: The argument bufsz is positive, but bufp is NULL.
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.

The QSMM library contains an instance of qsmm_dump_instr_desc_s structure holding the default parameters of generating string representations of assembler instructions. Use the following function to get a pointer to this instance.

Function: struct qsmm_dump_instr_desc_s * qsmm_get_default_dump_instr_desc (): This function returns a pointer to the default parameters of generating string representations of assembler instructions. You can change those parameters via this pointer. The function never returns NULL.

The description of a structure specifying the parameters of generating string representations of instructions is below.

Structure: qsmm_dump_instr_desc_s

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

Field: char is_line_after_comment_above: If this field is not 0, the field do_print_comment_above is not 0, and the instruction has a comment above itself, insert an empty line after the comment and before the instruction. The function qsmm_prg_dump uses this field in a similar way to determine whether to insert an empty line after a comment preceding a definition of a probability variable. The default is to insert an empty line.

Field: char is_line_after_multiline_comment_right: If this field is not 0, and the field do_print_comment_right is not 0, insert an empty line after an instruction with a multi-line comment to the right or after a definition of a probability variable with a multi-line comment to the right if the next line in the assembler program contains a comment to the right. If an instruction name or instruction parameters are too long, the function qsmm_instr_str may put this multi-line comment below the instruction. The default is to insert an empty line.

Field: char is_space_after_comma: If not 0, insert a space after every comma outside string literals in instruction parameters. The default is to insert a space.

Field: char do_print_label: If not 0 and the instruction has a location label assigned, print the location label to the left of the instruction. If the instruction has multiple location labels assigned, print all those labels except for the last one on separate lines. If there is no room between the last label and an instruction name, print the last label on a separate line too. The default is to print location labels.

Field: char do_print_name: If not 0, print an instruction name. The default is to print.

Field: char do_print_param: If not 0, print instruction parameters. The default is to print.

Field: char do_print_comment_above: If not 0 and the instruction has a comment above itself, print this comment. The function qsmm_prg_dump uses this field in a similar way to determine whether to print comments above the definitions of probability variables. The default is to print the comments.

Field: char do_print_comment_right: If not 0 and the instruction has a comment to the right, print this comment. The function qsmm_prg_dump uses this field in a similar way to determine whether to print comments to the right of definitions of probability variables. The default is to print the comments.

Field: char do_print_comment_below: [New in QSMM 1.17] If not 0, the instruction has a comment to the right, and an instruction name or instruction parameters are too long, put this comment below the instruction. The function qsmm_instr_str considers the instruction name or parameters too long if the comment to the right is going to start at a column greater than specified in the field col_comment, and that field is positive. The function qsmm_instr_str indents the comment below the instruction at column col_comment. The default is not to move below an instruction a comment to the right of this instruction.

Warning: QSMM 1.18 does not correctly assign the comments below instructions to these instructions while parsing an assembler program.

Field: char do_print_var: If not 0, a jprob or case instruction uses the name of a probability variable, and the field prob_type is equal to QSMM_PROB_PROFILE, print that name in the instruction. Otherwise, print a probability. The default is to print the names of probability variables when possible.

Field: char do_print_state_name: If this field is not 0, the field do_print_param is not 0, and an stt instruction has a state name, print the state name in the instruction. The default is to print state names.

Field: char do_print_prob[QSMM_PROB_COUNT]: An array specifying additional types of probabilities to print in a comment for a jprob or case instruction to the right. If an instruction name or instruction parameters are too long, the function qsmm_instr_str may put this comment below the instruction. 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 the field do_print_comment_right is not 0, an element of this array is not 0, and the index of this element is not equal to the field prob_type, qsmm_instr_str prints a probability of a corresponding type in the comment. When printing an instruction of a program disassembled using an assembler program template, if the instruction has ambiguous context in the template, qsmm_instr_str prints ‘?’ for the probabilities in the comment. 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 a probability in a jprob or case instruction according to the field prob_type and for probabilities in a comment to the right of this instruction according to the field do_print_prob. If an instruction name or instruction parameters are too long, the function qsmm_instr_str may put this comment below the instruction. The field prob_prec also specifies the number of digits after the decimal point printed by the function qsmm_prg_dump for probabilities in the definitions of probability variables. If this field is non-negative, use fixed-point notation. If this field is negative, use exponential notation with the number of digits after the decimal point equal to the absolute value of this field. The default number of digits to print after the decimal point is 2.

Field: long col_name: If this field is positive, it specifies alignment column for an instruction name. If this field is not positive, do not align the instruction name. This field also specifies a column for the function qsmm_prg_dump to indent ‘.data’ and ‘.code’ directives, comments above instructions and above the definitions of probability variables, and a tail comment in an assembler program. If this field is not positive, do not indent ‘.data’ and ‘.code’ directives and the comments (start them at column 1). The default alignment column is 9.

Field: long col_param: If this field is positive, it specifies alignment column for instruction parameters and, if the parameters occupy multiple lines, a column to indent them on the following lines. If this field is not positive, do not align or indent the instruction parameters. The default alignment column is 17.

Field: long col_comment: If this field is positive, it specifies alignment column for a comment to the right of an instruction. If an instruction name or instruction parameters are too long, the function qsmm_instr_str may put this comment below the instruction. If this field is not positive, do not align the comment. The default alignment column is 33.

Field: long margin_right: If this field is positive, it specifies a right margin column for comments. The functions qsmm_instr_str and qsmm_prg_dump split longer comments into multiple lines. If this field is not positive, do not split comments into multiple lines based on a right margin column. The default is not to split.

Field: long margin_right_param: If this field is positive, it specifies a right margin column for the parameters of a user instruction. The function qsmm_instr_str splits long parameters into multiple lines and uses the positions of commas outside string literals as allowed split positions. If this field is not positive, do not split the parameters into multiple lines based on a right margin column. The default right margin column is 30.

Field: long nline_comment_right: Output parameter. The function qsmm_instr_str stores here the number of lines in a comment to the right of an instruction. If an instruction name or instruction parameters are too long, qsmm_instr_str may put this comment below the instruction. If the field do_print_comment_right is 0, the instruction does not have the comment, or it occupies the number of lines less than the number of lines occupied by instruction parameters, qsmm_instr_str stores 0 here. If do_print_comment_right is not 0, the instruction has this comment possibly split into multiple lines according to the field margin_right, and the number of lines occupied by the comment is greater than or equal to the number of lines occupied by the instruction parameters, qsmm_instr_str stores a positive value here. The function qsmm_prg_dump reads this field to insert an empty line after an instruction with a multi-line comment to the right if the next instruction has a comment to the right.

Field: long nline_param: Output parameter. The function qsmm_instr_str stores here the number of printed lines of instruction parameters. The function qsmm_prg_dump reads this field to determine whether to insert empty lines around multi-line instructions.

Field: size_t out_sz: Output parameter. [New in QSMM 1.17] The number of bytes occupied by a string representation printed by the function qsmm_instr_str not counting finalizing byte 0. That number does not depend on buffer size passed to qsmm_instr_str.

Field: enum qsmm_prob_e prob_type: The type of a probability to print in a jprob or case instruction. See Emitting an Output Signal, for the description of elements of qsmm_prob_e enumeration. When printing an instruction of a program disassembled using an assembler program template, if the instruction has ambiguous context in the template, the function qsmm_instr_str prints ‘?’ 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 qsmm_dump_instr_desc_s structure to values consistent with the fields do_calc_prob and prob_type of qsmm_disasm_desc_s structure used when disassembling the program. Otherwise, the function qsmm_instr_str or qsmm_prg_dump may print zero probabilities.

Use the following function to dump a program to a stream.

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

This function dumps a program prg to a stream filep. If desc_p is not NULL, the function dumps the program according to parameters in *desc_p. If desc_p is NULL, the function dumps the program according to default parameters.

In the current implementation, the function does not modify *desc_p or those default parameters. However, in a future implementation, the function may modify them, for example, to store there statistics on the dumping process.

This function calls the function qsmm_instr_str to obtain string representations of individual assembler instructions and passes to the latter function the field dump_instr_desc_p of qsmm_dump_prg_desc_s structure as the parameters of generating those string representations.

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_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.

The QSMM library contains an instance of qsmm_dump_prg_desc_s structure holding the default parameters of dumping a program. Use the following function to get a pointer to this instance.

Function: struct qsmm_dump_prg_desc_s * qsmm_get_default_dump_prg_desc (): This function returns a pointer to the default parameters of dumping an assembler program. You can change those parameters via this pointer. The function never returns NULL.

The description of a structure specifying the parameters of dumping a program is below.

Structure: qsmm_dump_prg_desc_s

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

Field: char do_print_vars: If not 0 and the program contains the definitions of probability variables, dump a “data” section with those definitions. The default is to dump.

Field: char is_line_before_label: If not 0, insert an empty line before a line with a location label definition. If an instruction has multiple location labels assigned (dumped on separate lines), the function qsmm_prg_dump inserts an empty line 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, insert an empty line before a comment above an instruction or the definition of a probability variable, and insert an empty line before a comment at the program end if the field do_print_comment_tail is not 0. The default is to insert.

Field: char are_lines_around_choice: If not 0, insert empty lines before and after choice instruction blocks. The default is to insert.

Field: char are_lines_around_multiline_param: If not 0, insert empty lines before and after multi-line user instructions. The default is to insert.

Field: char do_print_comment_tail: If not 0 and the program contains a comment at its end, dump this comment. The default is to dump.

Field: int col_var_type: If this field is positive, it specifies alignment column for ‘prob’ keywords. If this field is not positive, do not align those keywords. The default alignment column is 17.

Field: int col_var_val: If this field is positive, it specifies alignment column for the values of probability variables. If this field is not positive, do not align those values. The default alignment column is 25.

Field: int col_var_comment: If this field is positive, it specifies alignment column for comments to the right of definitions of probability variables. If this field is not positive, do not align those comments. The default alignment column is 33.

Field: struct qsmm_dump_instr_desc_s * dump_instr_desc_p: If this field is not NULL, it specifies the parameters of dumping assembler instructions by the function qsmm_instr_str. If this field is NULL, qsmm_instr_str uses default parameters returned by the function qsmm_get_default_dump_instr_desc.