Next: Parsing an Assembler Program, Previous: Inspecting an Assembler Program, Up: Assembler Programs [Contents][Index]
Use the following function to get a string representation of an assembler instruction.
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.
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.
This structure specifies the parameters of generating a string representation of an assembler instruction. The structure contains the following fields.
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.
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.
If not 0, insert a space after every comma outside string literals in instruction parameters. The default is to insert a space.
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.
If not 0, print an instruction name. The default is to print.
If not 0, print instruction parameters. The default is to print.
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.
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.
[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.17 does not correctly assign the comments below instructions to these instructions while parsing an assembler program.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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
.
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
andprob_type
ofqsmm_dump_instr_desc_s
structure to values consistent with the fieldsdo_calc_prob
andprob_type
ofqsmm_disasm_desc_s
structure used when disassembling the program. Otherwise, the functionqsmm_instr_str
orqsmm_prg_dump
may print zero probabilities.
Use the following function to dump a program to a stream.
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.
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.
This structure specifies the parameters of dumping an assembler program. The structure contains the following fields.
If not 0 and the program contains the definitions of probability variables, dump a “data” section with those definitions. The default is to dump.
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.
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.
If not 0, insert empty lines before and after choice
instruction blocks.
The default is to insert.
If not 0, insert empty lines before and after multi-line user instructions. The default is to insert.
If not 0 and the program contains a comment at its end, dump this comment. The default is to dump.
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.
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.
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.
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
.
Next: Parsing an Assembler Program, Previous: Inspecting an Assembler Program, Up: Assembler Programs [Contents][Index]