.\" You may copy, distribute and modify under the terms of the LDP General .\" Public License as specified in the LICENSE file that comes with the .\" gnumaniak distribution .\" .\" The author kindly requests that no comments regarding the "better" .\" suitability or up-to-date notices of any info documentation alternative .\" is added without contacting him first. .\" .\" (C) 2000 Ragnar Hojland Espinosa .\" .\" gprof man page .\" man pages are NOT obsolete! .\" .TH GASP 1 "November 2000" "gprof 2.10.1" .SH NAME \fBgprof\fR \- GNU Profiler .SH SYNOPSIS .B gprof .RB [ \-abchilsTvwxyzDLT ] .RB [ \-efnpqACEFJNOPQZ [ \fINAME\fR ]] .RB [ "\-I \fIDIRS\fR" ] .RB [ \-d [ \fINUMBER\fR ]] .RB [ "\-k \fIFROM\fB/\fITO\fR" ]] .RB [ "\-m \fIMIN_COUNT\fR" ] .RB [ "\-t \fITABLE_LENGHT\fR" ] .RB [ \-\-unreasonable ] .I INFILE... .B gasp .RB [ \-hv ] .RB [ \-\-help ] .RB [ \-\-version ] .SH DESCRIPTION .B gasp preprocesses each \fIINFILE\fR argument and concatenates the results to standard output, for direct consumption by \fBas\fR(1). Since \fBas\fR is targeted to assemble the output generated by other programs, it doesn't have common facilities such as macros or conditionals that are generally useful when writing assembler by hand. \fBgasp\fR provides this missing functionality. .SH OPTIONS .TP .B \-a, \-\-alternate Use alternative macro syntax. .TP .B \-c \fICHAR\fB, \-\-commentchar \fICHAR Use \fICHAR\fR as the comment character. The default comment character is `\fB!\fR'. .TP .B \-d, \-\-debug Show debugging statistics about the string buffers that \fBgasp\fR allocates internally. For each defined buffersize \fIS\fR, it shows the number of strings \fIN\fR that it allocated, in the format .sp .nf strings size \fIS\fR : \fIN\fR .fi .sp These statistics are written to stderr, when done preprocessing. .TP .B \-o \fIOUTFILE\fB, \-\-output \fIOUTFILE Write the output generated by \fBgasp\fR to \fIOUTFILE\fR. The default is to write to standard output. .TP .B \-p, \-\-print Print commented line numbers. Ignored unless \fB\-s\fR is specified. .TP .B \-s, \-\-copysource Print commented source lines. .TP .B \-u, \-\-unreasonable Allow unlimited ("unreasonable") nested expansions. Since you can define \fBgasp\fR macros inside other macro definitions, the preprocessor normally includes a sanity check. If you require more than 1000 nested expansions, \fBgasp\fR normally exits with an error message. Use this option to turn off this check, allowing unlimited nested expansions. .TP .B \-M, \-\-mri Enter MRI compatibility mode, required to use the Microtec Research ASM68K assembler syntax and pseudo ops. .TP .B \-D\fINAME\fB=\fIVALUE Define the preprocessor constant \fINAME\fR, with value \fIVALUE\fR. .TP .B \-I\fIPATH Add \fIPATH\fR to the include path list. .TP .B "\-h, \-\-help" Print a usage message on standard output and exit successfully. .TP .B "\-v, \-\-version" Print version information on standard output then exit successfully. .SH PREPROCESSOR COMMANDS Commands are case-insensitive, and each extends for a line divided in three fields: an optional label, the command itself, and optional argument(s) to the command. .SS Conditionals These directives allow you to include or exclude portions of assembly depending on how a pair of strings or absolute expressions compare. Max conditional nesting is 100. .TP .B .AIF \fIARG1 CMP ARG2 .PD 0 .TP .B .AIF \fB"\fIARG1\fB"\fI CMP \fB"\fIARG2\fB" .sp Available \fICMP\fR comparision operators available with strings and absolute expressions: .sp .RS .TP .B EQ Are \fIARG1\fR and \fIARG2\fR equal? .TP .B NE Are \fIARG1\fR and \fIARG2\fR different? .PP .sp Available \fICMP\fR comparision operators available with absolute expressions only: .sp .TP .B LT Is \fIARG1\fR less than \fIARG2?\fR .TP .B LE Is \fIARG1\fR less than or equal to \fIARG2\fR .TP .B GT Is \fIARG1\fR greater than \fIARG2\fR? .TP .B GE Is \fIARG1\fR greater than or equal to \fIARG2\fR? .RE .PD 1 .TP .B .AELSE Marks the start of assembly code to be included if the condition fails. Optional, and only allowed within a conditional (between \fB.AIF\fR and \fB.AENDI\fR) .TP .B .AENDI Marks the end of an \fB.AIF\fR conditional block. .PP .SS Loops These directives allow you repeat portions of code. .TP .B .AREPEAT \fIEXPR .PD 0 .TP .B .AENDR .PD 1 .br Repeats the assemby code between the \fB.AREPEAT\fR and \fB.AENDR\fR macros as many times as specified by the absolute expression \fIEXPR\fR. .TP .B .AWHILE \fIARG1 CMP ARG2 .PD 0 .TP .B .AENDW .PD 1 .br Repeats the assembly code between the \fB.AWHILE\fR and \fB.AENDW\fR macros as long as the \fICMP\fR conditional comparision holds true. The format for \fICMP\fR is the same as for \fB.AIF\fR. .TP .B .EXITM Break out of the loop. .SS Variables Variables can represent strings, registers or the results of expressions. There are two kinds of variables: \fB\(bu\fR\ Variables defined with \fB.EQU\fR or \fB.ASSIGN\fR. To evaluate this kind of variable in your assembly output, simply mention its name. These variabes are only evaluated when writing the assembly output, so they shouldn't be used in conditional expressions or \fB.AWHILE\fR loops. .sp .nf foo .EQU FLIP-64 bar: .EQU FLIP-64 mov.l foo, r0 .fi .sp \fB\(bu\fR\ Variables for use during preprocessing, defined with .BR ".ASSIGNC" " or " ".ASSIGNA" . To evaluate this kind of variable, use the prefix `\fB\e&\fR'. .sp .nf opcit .ASSIGNA 47 .AWHILE \e&opcit GT 0 .AENDW .fi .sp Macro arguments are treated almost the same way, but to evaluate them you use the prefix `\fB\e\fR' instead. .TP .B \fIPVAR\fB .EQU \fIEXPR Assign preprocessor variable PVAR the value of the expression EXPR. No restrictions on redefinition. .TP .B \fIPVAR\fB .ASSIGN \fIEXPR Like \fB.EQU\fR, but you may not redefine \fIPVAR\fB. .TP .B \fIPVAR\fB .ASSIGNA \fIAEXPR Define a variable with a numeric value, for use during preprocessing. \fIAEXPR\fR must be an absolute expression. No restrictions on redefinition. .TP .B \fIPVAR\fB .ASSIGNC "\fISTR\fR" Define a variable with a string value, for use during preprocessing. No restrictions on redefinition. .TP .B \fIPVAR\fB .REG (\fIREGISTER\fB) Define a variable that represents a register. In particular, \fIREGISTER\fR is \fBnot evaluated\fR as an expression. No restrictions on redefinition. .PP All these directives accept the variable name in the "label" position, that is at the left margin. You may specify a colon after the variable name if you wish, as in `bar' above. .SS Macro Definition The directives \fB.MACRO\fR and \fB.ENDM\fR allow you to define your own macros that generate assembly output. .TP .B .MACRO \fINAME .PD 0 .TP .B .MACRO \fINAME \fR[\fBARG\fR[\fB=\fIDEFAULT_VALUE\fR]\fB, ...\fR] .PD 1 Begin the definition of a macro called \fINAME\fR. If your macro definition requires arguments, specify their names after the macro name, separated by commas or spaces. When you call a macro, you can specify the argument values either by position, or by keyword. For example, `SUM 9, 17' is equivalent to `SUM TO=17, FROM=9'. Macro arguments are preprocessor variables similar to the variables you define with .BR .ASSIGNA " or " .ASSIGNC ", " so you can use them in conditionals or loop control. The only difference is the prefix you write to evaluate the variable: for a macro argument use `\fB\eARG\fR', but for a preprocessor variable use `\fB\e&VAR\fR'. .TP .B \fINAME\fB .MACRO .PD 0 .TP .B \fINAME\fB .MACRO ( \fR[\fBARG\fR[\fB=\fIDEFAULT_VALUE\fR]\fB, ...\fR]\fB ) .PD 1 An alternative form of introducing a macro definition: specify the macro name in the label position, and any arguments between parentheses after the name. .TP .B .ENDM Mark the end of a macro definition. .TP .B .EXITM Exit early from the current macro definition, or macro loop. .TP .B \e@ This pseudo-variable represents the number of macros \fBgasp\fR has executed. You may use this variable only within a macro definition. .TP .B LOCAL \fINAME\fR[\fB, \fINAME...\fR] Generate an unique string for each \fINAME\fR argument, and replace any instances of \fINAME\fR in macro expansions. This allows you to write macros that define symbols without fear of conflict between macro expansions, since the strings are different for each expansion. Only available if you specify \fB\-\-alternate\fB. .SS Data These directives allow you to specify working areas of memory. The directives that initialize memory are: .TP .B .DATA \fIEXPR\fR[\fB, \fIEXPR...\fR] .PD 0 .TP .B .DATA.B \fIEXPR\fR[\fB, \fIEXPR...\fR] .TP .B .DATA.W \fIEXPR\fR[\fB, \fIEXPR...\fR] .TP .B .DATA.L \fIEXPR\fR[\fB, \fIEXPR...\fR] .PD 1 Evaluate arithmetic \fIEXPR\fR expressions, and emit the corresponding \fBas\fR directive (labelled with \fBLAB\fR). The unqualified \fB.DATA\fR emits \fB.long\fR; \fB.DATA.B\fR emits \fB.byte\fR; \fB.DATA.W\fR emits \fB.short\fR; and \fB.DATA.L\fR emits \fB.long\fR. For example, `foo .DATA 1,2,3' emits `foo: .long 1,2,3'. .TP .B .DATAB \fIREPEAT\fB, \fIEXPR .PD 0 .TP .B .DATAB.B \fIREPEAT\fB, \fIEXPR .TP .B .DATAB.W \fIREPEAT\fB, \fIEXPR .TP .B .DATAB.L \fIREPEAT\fB, \fIEXPR .PD 1 Emit \fIREPEAT\fR copies of the value of the expression \fIEXPR\fR (using the \fBas\fR directive \fB.fill\fR), being \fIREPEAT\fR an absolute expression with an absolute value. \fB.DATAB.B\fR repeats one-byte values; \fB.DATAB.W\fR repeats two-byte values; and \fB.DATAB.L\fR repeats four-byte values. \fB.DATAB\fR without a suffix repeats four-byte values, just like \fB.DATAB.L\fR. .TP .B .SDATA\ "\fISTR\fB"\fI... String data. Emits a concatenation of bytes (no end of string marks are added, unlike in \fB.SDATAZ\fR) of each \fISTR\fR argument given, and optionally separated by commas. .TP .B .SDATAB \fIREPEAT\fB,\ "\fISTR\fB"\fI... Repeated string data. \fIREPEAT\fR specifies how many copies of the concatenation of every \fISTR\fR argument are emitted. .TP .B .SDATAZ\ "\fISTR\fR"\fI... Zero-terminated string data. Like \fB.SDATA\fR, except that a zero byte is written at the end of the string. .TP .B .SDATAC\ "\fISTR\fR"\fI... Count-prefixed string data. Like \fB.SDATA\fR, but precede the string with a leading one-byte count. For example, `.SDATAC "HI"' generates `.byte 2,72,73'. Since the count field is only one byte, you can only use \fB.SDATAC\fR for strings less than 256 bytes in length. .PP Use the .BR .RES ", " .SRES ", " .SRESC ", and " .SRESZ directives to reserve memory and leave it uninitialized. \fBgasp\fR resolves these directives to appropriate calls of the GNU \fBas .space\fR directive. .TP .B .RES \fICOUNT .PD 0 .TP .B .RES.B \fICOUNT .TP .B .RES.W \fICOUNT .TP .B .RES.L \fICOUNT .PD 1 Reserve room for \fICOUNT\fR uninitialized elements of data. The suffix specifies the size of each element: \fB.RES.B\fR reserves \fICOUNT\fR bytes, .B .RES.W reserves \fBCOUNT\fR pairs of bytes, and .B .RES.L reserves \fICOUNT\fR quartets. .B .RES without a suffix is equivalent to .B .RES.L .TP .B .SRES \fICOUNT .PD 0 .TP .B .SRES.B \fICOUNT .TP .B .SRES.W \fICOUNT .TP .B .SRES.L \fICOUNT .PD 1 .B .SRES is a synonym for .BR .RES . .TP .B .SRESC \fICOUNT .PD 0 .TP .B .SRESC.B \fICOUNT .TP .B .SRESC.W \fICOUNT .TP .B .SRESC.L \fICOUNT .PD 1 Like \fB.SRES\fR, but reserves space for `\fICOUNT\fR+1' elements. .TP .B .SRESZ \fICOUNT .PD 0 .TP .B .SRESZ.B \fICOUNT .TP .B .SRESZ.W \fICOUNT .TP .B .SRESZ.L \fICOUNT .PD 1 .B .SRESZ is a synonym for .BR .SRESC . .SS Listings These directives control \fBas\fR listing directives. .TP .B .PRINT LIST .PD 0 .TP .B .PRINT NOLIST .PD 1 Emits \fB.list\fR or \fB.nolist\fR, according to its argument. .TP .B .FORM LIN=\fILN .PD 0 .TP .B .FORM COL=\fICOLS .TP .B .FORM LIN=\fILN\fB COL=\fICOLS\fR .PD 1 Specify the page size for assembly listings, of \fILN\fR lines and \fICOLS\fR columns (default: 60x132). You may specify either, or both. Any values you may have specified in previous instances of \fB.FORM\fR do not carry over as defaults. Emits the .B .psizef GNU \fBas\fR directive. .TP .B .HEADING \fISTRING Specify \fISTRING\fR as the title of your assembly listings. Emits `\fB.title "\fISTRING\fB"\fR'. .TP .B .PAGE Force a new page in the listing. Emits \fB.eject\fR. .SH MISCELLANEOUS COMMANDS .TP .B .ALTERNATE Use the alternate macro syntax henceforth in the assembly. .TP .B .ORG This command is recognized, but not yet implemented. \fBgasp\fR generates an error message for programs that use \fB.ORG\fR. .TP .B .RADIX \fIS\fR Specify the default radix for numbers without an explicitly encoded base (default: \fBD\fR). \fIS\fR is a case-insensitive letter: .RS .TP .B .RADIX B Base 2. .TP .B .RADIX Q Base 8. .TP .B .RADIX D Base 10. .TP .B .RADIX H Base 16. .RE .TP .B .EXPORT \fINAME .PD 0 .TP .B .GLOBAL \fINAME .PD 1 Declare \fINAME\fR global (emits \fB.global \fINAME\fR). .TP .B .PROGRAM Ignored. .TP .B .END Mark end of each preprocessor file. A warning is issued if the end of file is reached without seeing this command. .TP .B .INCLUDE "\fISTR\fB" Preprocess the filename \fISTR\fR as if its contents appeared where the \fB.INCLUDE\fR directive does. Maximum include depth is 30. .TP .B .ALIGN \fISIZE Evaluate the absolute expression \fISIZE\fR, and emit \fB.align \fIevaluated_expression\fR. .SH GASP SYNTAX Whitespace (blanks or tabs; not newlines) is partially significant, in that it delimits up to three fields in a line. The amount of whitespace does not matter. \fB\(bu\fR\ First field, an optional "label", must be flush left in a line (with no leading whitespace) if it appears at all, with an optional colon after the label name. \fB\(bu\fR\ Second field, which must appear after some whitespace, contains a \fBgasp\fR or \fBas\fR directive. \fB\(bu\fR\ Further fields on a line are arguments to the directive, separated by either commas or whitespace. .SS Special syntactic markers \fBgasp\fR recognizes a few special markers: to delimit comments, to continue a statement on the next line, to separate symbols from other characters, and to copy text to the output literally (One other special marker, `\fB\@f\fR', works only within macro definitions) The trailing part of any source line may be a comment. A comment begins with the first unquoted comment character (`\fB!\fR' by default), or an escaped or doubled comment character (`\fB\e!\fR' or `\fB!!\fR' by default), and extends to the end of a line. The two kinds of comment markers lead to slightly different treatment: .RS .TP .B ! A single, un-escaped comment character generates an assembly comment in the \fBgasp\fR output. \fBgasp\fR evaluates any preprocessor variables (macro arguments, or variables defined with .BR .ASSIGNA " or " .ASSIGNC ) present. For example, a macro that begins like this .sp .nf .MACRO SUM FROM=0, TO=9 ! \eFROM \eTO .fi .sp issues as the first line of output a comment that records the values you used to call the macro. .TP .B \e! .PD 0 .TP .B !! .PD 1 Either an escaped comment character, or a double comment character, marks a \fBgasp\fR source comment. \fBgasp\fR does not copy such comments to the assembly output. .RE To continue a statement on the next line of the file, begin the second line with the character `\fB+\fR'. Occasionally you may want to prevent \fBgasp\fR from preprocessing some particular bit of text. To \fBcopy literally\fR from the \fBgasp\fR source to its output, place `\fB\e(\fR' before the string to copy, and `\fB)\fR' at the end. For example, write `\e(\e!)' if you need the characters `\fB\e!\fR' in your assembly output. To separate a preprocessor variable from text to appear immediately after its value, write a single quote ('\fB'\fR'). For example, `.SDATA "\P'1"' writes a string built by concatenating the value of `P' and the digit `1' (You cannot achieve this by writing just `\eP1', since `P1' is itself a valid name for a preprocessor variable) .SS String and numeric constants There are two ways of writing string constants: as literal text, and by numeric byte value. Specify a string literal between double quotes (\fB"\fISTR\fB"\fR). Specify an individual numeric byte value as an absolute expression between angle brackets (\fB<\fIEXPR\fB>\fR). Directives that output strings allow you to specify any number of either kind of value, in whatever order is convenient, and concatenate the result. You can write numeric constants either in a specific base, or in whatever base is currently selected by the last \fB.RADIX\fR directive. To write a number in a specific base, use the pattern `\fIS\fB'\fIDDD\fR': a base specifier character \fIS\fR, followed by a single quote followed by digits \fIDDD\fR. The base specifier character matches those you can specify with \fB.RADIX\fR. .SS Symbols Valid symbols start with any alphabetic character, `\fB_\fR' or `\fB$\fR', and continue with any of them or with digits. .SS Arithmetic Expressions There are two kinds of expressions, depending on their result: absolute expressions, which resolve to a constant (that is, they do not involve any values unknown to \fBgasp\fR), and relocatable expressions, which must reduce to the form .sp .nf \fIADDSYM\fB+\fICONST\fB-\fISUBSYM .fi .sp where \fIADDSYM\fR and \fISUBSYM\fR are assembly symbols of unknown value, and \fICONST\fR is a constant. Arithmetic for \fBgasp\fR expressions follows very similar rules to C. You can use parentheses to change precedence; otherwise, arithmetic primitives have decreasing precedence in the order of the following list. \fB\(bu\fR\ 1. Single-argument `+' (identity), `-' (arithmetic opposite), or `~' (bitwise negation). The argument must be an absolute expression. \fB\(bu\fR\ 2. `*' (multiplication) and `/' (division). Both arguments must be absolute expressions. \fB\(bu\fR\ 3. `+' (addition) and `-' (subtraction). At least one argument must be absolute. \fB\(bu\fR\ 4. `&' (bitwise and). Both arguments must be absolute. \fB\(bu\fR\ 5. `|' (bitwise or) and `~' (bitwise exclusive or; `^' in C). Both arguments must be absolute. .SS String Primitives You can use these primitives to manipulate strings (in the argument field of \fBgasp\fR statements): .TP .B .LEN("\fISTR\fB") Calculate the length of string \fB"\fISTR\fB"\fR, as an absolute expression. For example, `.RES.B .LEN("sample")' reserves six bytes of memory. .TP .B .INSTR("\fISTR\fB", "\fISEG\fB", \fIIX\fB) Search for the first occurrence of \fISEG\fR after position \fIIX\fR of \fISTR\fR. The result is -1 if \fISEG\fR does not occur in \fISTR\fR after position \fIIX\fR. .TP .B .SUBSTR("\fISTR\fB", \fISTART\fB, \fILEN\fB) The substring of \fISTR\fR beginning at byte number \fISTART\fR and extending for \fILEN\fR bytes. .SH ALTERNATE MACRO SYNTAX When the \fB\-\-alternate\fR option is specified, an alternate macro sytax is used by \fBgasp\fR. This syntax reminiscent of the syntax of Phar Lap macro assembler, but it is not meant to be a full emulation of Phar Lap or similar assemblers. In particular, \fBgasp\fR does not support directives such as DB and IRP. \fB\(bu\fR\ You can use preprocessor directives without a leading `\fB.\fR' dot. For example, you can write `SDATA' with the same effect as .SDATA'. \fB\(bu\fR\ LOCAL is available. \fB\(bu\fR\ You can write strings delimited like "STRING", 'STRING', or \fB\(bu\fR\ To include any single character literally in a string (even if the character would otherwise have some special meaning), you can prefix the character with `\fB!\fR'. For example, `"hello !"world!"". \fB\(bu\fR\ You can write \fB%\fIEXPR\fR to evaluate the expression \fIEXPR\fR and use the result as a string. .SH EXAMPLES If we feed \fBfasp\fR with this .sp .nf .MACRO saveregs from=8 to=14 count .ASSIGNA \efrom ! save r\efrom..r\eto .AWHILE \e&count LE \eto mov r\e&count,@-sp count .ASSIGNA \e&count + 1 .AENDW .ENDM saveregs from=12 bar: mov #H'dead+10,r0 foo .SDATAC "hello"<10> .END .fi .sp it generates this GNU \fBas\fR code: .sp .nf ! save r12..r14 mov r12,@-sp mov r13,@-sp mov r14,@-sp bar: mov #57005+10,r0 foo: .byte 6,104,101,108,108,111,10 .fi .SH SEE ALSO \fBas\fR(1) .SH NOTES Report bugs to and .br Man page by Ragnar Hojland Espinosa