From 87462f1e05e51bddca94cd3c6b1aded4eed99635 Mon Sep 17 00:00:00 2001 From: Roland Pesch Date: Tue, 29 Mar 1994 03:08:48 +0000 Subject: [PATCH] Last-minute updates on Steve's last-minute changes. TeX formatting remains to be checked. --- gas/doc/gasp.texi | 204 +++++++++++++++++++++++++++++++++++----------- 1 file changed, 158 insertions(+), 46 deletions(-) diff --git a/gas/doc/gasp.texi b/gas/doc/gasp.texi index 854cfb8653f..95a64d55adb 100644 --- a/gas/doc/gasp.texi +++ b/gas/doc/gasp.texi @@ -29,7 +29,7 @@ END-INFO-DIR-ENTRY @title GASP, an assembly preprocessor @subtitle for GASP version 1 @sp 1 -@subtitle January 1994 +@subtitle March 1994 @author Roland Pesch @page @@ -120,7 +120,7 @@ Here is a small example to give the flavor of @sc{gasp}. This input to @example .MACRO saveregs from=8 to=14 count .ASSIGNA \from - ; save r\from..r\to + ! save r\from..r\to .AWHILE \&count LE \to mov r\&count,@@-sp count .ASSIGNA \&count + 1 @@ -140,7 +140,7 @@ generates this assembly program: @cartouche @example - ; save r12..r14 + ! save r12..r14 mov r12,@@-sp mov r13,@@-sp mov r14,@@-sp @@ -167,13 +167,15 @@ request variations on this basic theme. Here is the full set of possibilities for the @sc{gasp} command line. @example -gasp [ -c ] [ -o @var{outfile} ] [ -p ] [ -s ] [ -u ] +gasp [ -a | --alternate ] + [ -c @var{char} | --commentchar @var{char} ] + [ -d | --debug ] [ -h | --help ] + [ -o @var{outfile} | --output @var{outfile} ] + [ -p | --print ] [ -s | --copysource ] + [ -u | --unreasonable ] [ -v | --version ] @var{infile} @dots{} @end example -@c FIXME!! Aren't all GNU programs supposed to have a -V or --version -@c option, that reports version info and exits? - @ftable @code @item @var{infile} @dots{} @c FIXME! Why not stdin as default infile? @@ -184,46 +186,83 @@ in the order you list the @var{infile} arguments. Mark the end of each input file with the preprocessor command @code{.END}. @xref{Other Commands,, Miscellaneous commands}. -@item -c -@c FIXME! Shouldn't there be an option to set the prefix char so it can -@c always be the comment char for whatever assembly version we have? -Copy the source lines to the output file. Use this option -to see the effect of each preprocessor line on the @sc{gasp} output. -@sc{gasp} marks the lines copied from the source file with @samp{!} at -the beginning, to help you distinguish them from the rest of the output. +@item -a +@itemx --alternate +Use alternative macro syntax. @xref{Alternate,, Alternate macro +syntax}, for a discussion of how this syntax differs from the default +@sc{gasp} syntax. + +@cindex comment character, changing +@cindex semicolon, as comment +@cindex exclamation mark, as comment +@cindex shriek, as comment +@cindex bang, as comment +@cindex @code{!} default comment char +@cindex @code{;} as comment char +@item -c '@var{char}' +@itemx --commentchar '@var{char}' +Use @var{char} as the comment character. The default comment character +is @samp{!}. For example, to use a semicolon as the comment character, +specify @w{@samp{-c ';'}} on the @sc{gasp} command line. Since +assembler command characters often have special significance to command +shells, it is a good idea to quote or escape @var{char} when you specify +a comment character. + +For the sake of simplicity, all examples in this manual use the default +comment character @samp{!}. + +@item -d +@itemx --debug +Show debugging statistics. In this version of @sc{gasp}, this option +produces statistics about the string buffers that @sc{gasp} allocates +internally. For each defined buffersize @var{s}, @sc{gasp} shows the +number of strings @var{n} that it allocated, with a line like this: + +@example +strings size @var{s} : @var{n} +@end example + +@noindent +@sc{gasp} displays these statistics on the standard error stream, when +done preprocessing. + +@item -h +@itemx --help +Display a summary of the @sc{gasp} command line options. @item -o @var{outfile} +@itemx --output @var{outfile} Write the output in a file called @var{outfile}. If you do not use the @samp{-o} option, @sc{gasp} writes its output on the standard output stream. @item -p +@itemx --print Print line numbers. @sc{gasp} obeys this option @emph{only} if you also -specify @samp{-c} to copy source lines to its output. With @samp{-c +specify @samp{-s} to copy source lines to its output. With @samp{-s -p}, @sc{gasp} displays the line number of each source line copied -(immediately after the @samp{!} that marks source lines in the output). +(immediately after the comment character at the beginning of the line). @item -s -Show statistics. In this version of @sc{gasp}, this option produces -statistics about the string buffers that @sc{gasp} allocates internally. -For each defined buffersize @var{s}, @sc{gasp} shows the number of -strings @var{n} that it allocated, with a line like this: - -@example -strings size @var{s} : @var{n} -@end example - -@noindent -@sc{gasp} displays these statistics on the standard error stream, when -done preprocessing. +@itemx --copysource +Copy the source lines to the output file. Use this option +to see the effect of each preprocessor line on the @sc{gasp} output. +@sc{gasp} places a comment character (@samp{!} by default) at +the beginning of each source line it copies, so that you can use this +option and still assemble the result. @item -u +@itemx --unreasonable Bypass ``unreasonable expansion'' limit. Since you can define @sc{gasp} macros inside other macro definitions, the preprocessor normally includes a sanity check. If your program requires more than 1,000 nested expansions, @sc{gasp} normally exits with an error message. Use this option to turn off this check, allowing unlimited nested expansions. + +@item -v +@itemx --version +Display the @sc{gasp} version number. @end ftable @node Commands @@ -245,6 +284,7 @@ Details,, Details of the GASP syntax}, for more information. * Listings:: * Other Commands:: * Syntax Details:: +* Alternate:: @end menu @node Conditionals @@ -457,7 +497,7 @@ consecutive registers: @cartouche @example .MACRO SUM FROM=0, TO=9 - ; \FROM \TO + ! \FROM \TO mov r\FROM,r10 COUNT .ASSIGNA \FROM+1 .AWHILE \&COUNT LE \TO @@ -473,7 +513,7 @@ With that definition, @samp{SUM 0,5} generates this assembly output: @cartouche @example - ; 0 5 + ! 0 5 mov r0,r10 add r1,r10 add r2,r10 @@ -529,7 +569,7 @@ a preprocessor variable, write @samp{\&@var{varname}}.) An alternative form of introducing a macro definition: specify the macro name in the label position, and the arguments (if any) between parentheses after the name. Defaulting rules and usage work the same -way as for the alternate macro definition syntax. +way as for the other macro definition syntax. @item .ENDM Mark the end of a macro definition. @@ -544,6 +584,17 @@ Exit early from the current macro definition, @code{.AREPEAT} loop, or @sc{gasp} maintains a counter of how many macros it has executed in this pseudo-variable; you can copy that number to your output with @samp{\@@}, but @emph{only within a macro definition}. + +@item LOCAL @var{name} [ , @dots{} ] +@emph{Warning: @code{LOCAL} is only available if you select ``alternate +macro syntax'' with @samp{-a} or @samp{--alternate}.} @xref{Alternate,, +Alternate macro syntax}. + +Generate a string replacement for each of the @var{name} arguments, and +replace any instances of @var{name} in each macro expansion. The +replacement string is unique in the assembly, and different for each +separate macro expansion. @code{LOCAL} allows you to write macros that +define symbols, without fear of conflict between separate macro expansions. @end ftable @node Data @@ -701,6 +752,10 @@ Force a new page in assembly listings. Emits @samp{.eject}. @section Miscellaneous commands @ftable @code +@item .ALTERNATE +Use the alternate macro syntax henceforth in the assembly. +@xref{Alternate,, Alternate macro syntax}. + @item .ORG @c FIXME! This is very strange, since _GAS_ understands .org This command is recognized, but not yet implemented. @sc{gasp} @@ -804,29 +859,37 @@ special marker, @samp{\@@}, works only within macro definitions; @cindex comments The trailing part of any @sc{gasp} source line may be a @dfn{comment}. -A comment begins with the first unquoted @samp{;} or @samp{\;}, and -extends to the end of a line. The two kinds of comment markers lead to -slightly different treatment: +A comment begins with the first unquoted comment character (@samp{!} by +default), or an escaped or doubled comment character (@samp{\!} or +@samp{!!} by default), and extends to the end of a line. You can +specify what comment character to use with the @samp{-c} option +(@pxref{Invoking GASP,, Command Line Options}). The two kinds of +comment markers lead to slightly different treatment: @table @code -@item ; -Generate an assembly comment in the @sc{gasp} output. @sc{gasp} evaluates any -preprocessor variables (macro arguments, or variables defined with -@code{.ASSIGNA} or @code{.ASSIGNC}) present. For example, a macro that -begins like this +@item ! +A single, un-escaped comment character generates an assembly comment in +the @sc{gasp} output. @sc{gasp} evaluates any preprocessor variables +(macro arguments, or variables defined with @code{.ASSIGNA} or +@code{.ASSIGNC}) present. For example, a macro that begins like this @example .MACRO SUM FROM=0, TO=9 - ; \FROM \TO + ! \FROM \TO @end example @noindent issues as the first line of output a comment that records the values you used to call the macro. -@item \; -This marks a @sc{gasp} source comment. @sc{gasp} does not copy such -comments to the assembly output. +@c comments, preprocessor-only +@c preprocessor-only comments +@c GASP-only comments +@item \! +@itemx !! +Either an escaped comment character, or a double comment character, +marks a @sc{gasp} source comment. @sc{gasp} does not copy such comments +to the assembly output. @end table @cindex continuation character @@ -841,8 +904,8 @@ second line with the character @samp{+}. Occasionally you may want to prevent @sc{gasp} from preprocessing some particular bit of text. To @emph{copy literally} from the @sc{gasp} source to its output, place @samp{\(} before the string to copy, and -@samp{)} at the end. For example, write @samp{\(\;)} if you need the -characters @samp{\;} in your assembly output. +@samp{)} at the end. For example, write @samp{\(\!)} if you need the +characters @samp{\!} in your assembly output. @cindex symbol separator @cindex text, separating from symbols @@ -863,7 +926,9 @@ between double quotes (@code{"@var{str}"}). Specify an individual numeric byte value as an absolute expression between angle brackets (@code{<@var{expr}>}. Directives that output strings allow you to specify any number of either kind of value, in whatever order is -convenient, and concatenate the result. +convenient, and concatenate the result. (Alternate syntax mode +introduces a number of alternative string notations; @pxref{Alternate,, +Alternate macro syntax}.) @c Details of numeric notation, e.g. base prefixes You can write @dfn{numeric constants} either in a specific base, or in @@ -960,6 +1025,53 @@ The substring of @var{string} beginning at byte number @var{start} and extending for @var{len} bytes. @end ftable +@node Alternate +@section Alternate macro syntax + +If you specify @samp{-a} or @samp{--alternate} on the @sc{gasp} command +line, the preprocessor uses somewhat different syntax. This syntax is +reminiscent of the syntax of Phar Lap macro assembler, but it +is @emph{not} meant to be a full emulation of Phar Lap or similar +assemblers. In particular, @sc{gasp} does not support directives such +as @code{DB} and @code{IRP}, even in alternate syntax mode. + +In particular, @samp{-a} (or @samp{--alternate}) elicits these +differences: + +@table @emph +@item Preprocessor directives +You can use @sc{gasp} preprocessor directives without a leading @samp{.} +dot. For example, you can write @samp{SDATA} with the same effect as +@samp{.SDATA}. + +@item LOCAL +One additional directive, @code{LOCAL}, is available. @xref{Macros,, +Defining your own directives}, for an explanation of how to use +@code{LOCAL}. + +@item String delimiters +You can write strings delimited in two other ways besides +@code{"@var{string}"}: + +@table @code +@item '@var{string}' +You can delimit strings with single-quote charaters. + +@item <@var{string}> +You can delimit strings with matching angle brackets. + +@item single-character string escape +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 @samp{!} (an exclamation mark). For example, you can +write @samp{<4.3 !> 5.4!!>} to get the literal text @samp{4.3 > 5.4!}. +@end table + +@item Expression results as strings +You can write @samp{%@var{expr}} to evaluate the expression @var{expr} +and use the result as a string. +@end table + @node Index @unnumbered Index -- 2.30.2