\input texinfo @c -*- Texinfo -*-
-@finalout
@setfilename gasp.info
@c
@c This file documents the assembly preprocessor "GASP"
@ifinfo
@format
START-INFO-DIR-ENTRY
-* gasp:(gasp). The GNU Assembler Preprocessor
+* gasp: (gasp). The GNU Assembler Preprocessor
END-INFO-DIR-ENTRY
@end format
@end ifinfo
@syncodeindex ky cp
@syncodeindex fn cp
+@finalout
@setchapternewpage odd
@settitle GASP
@titlepage
@c FIXME boring title
@title GASP, an assembly preprocessor
-@c FIXME! Get a version number, global-replace '??'
-@subtitle for GASP version ??
+@subtitle for GASP version 1
@sp 1
-@subtitle January 1994
+@subtitle March 1994
@author Roland Pesch
@page
@end tex
@vskip 0pt plus 1filll
-Copyright @copyright{} 1994 Free Software Foundation, Inc.
+Copyright @copyright{} 1994, 1995 Free Software Foundation, Inc.
Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
@end titlepage
@ifinfo
-Copyright @copyright{} 1994 Free Software Foundation, Inc.
+Copyright @copyright{} 1994, 1995 Free Software Foundation, Inc.
Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
GASP is a preprocessor for assembly programs.
-This file describes version ?? of GASP.
+This file describes version 1 of GASP.
Steve Chamberlain wrote GASP; Roland Pesch wrote this manual.
@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
.AENDW
.ENDM
- saveregs from=9
- saveregs 1,5
+ saveregs from=12
- .RADIX Q
-bar: mov #H'dead+12,r0
-foo .SDATAC "hello"<12>
+bar: mov #H'dead+10,r0
+foo .SDATAC "hello"<10>
.END
@end example
@end cartouche
@cartouche
@example
- ; save r9..r14
- mov r9,@@-sp
- mov r10,@@-sp
- mov r11,@@-sp
+ ! save r12..r14
mov r12,@@-sp
mov r13,@@-sp
mov r14,@@-sp
- ; save r1..r5
- mov r1,@@-sp
- mov r2,@@-sp
- mov r3,@@-sp
- mov r4,@@-sp
- mov r5,@@-sp
bar: mov #57005+10,r0
foo: .byte 6,104,101,108,108,111,10
@c FIXME! GASP filename suffix convention?
@example
-$ gasp prog.sp | as -o prog.o
+$ gasp prog.asm | as -o prog.o
@end example
Naturally, there are also a few command-line options to allow you to
possibilities for the @sc{gasp} command line.
@example
-gasp [ -c ] [ -o @var{outfile} ] [ -p ] [ -s ] [ -u ] @var{infile} @dots{}
+gasp [ -a | --alternate ]
+ [ -c @var{char} | --commentchar @var{char} ]
+ [ -d | --debug ] [ -h | --help ] [ -M | --mri ]
+ [ -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?
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 -M
+@itemx --mri
+Use MRI compatibility mode. Using this option causes @sc{gasp} to
+accept the syntax and pseudo-ops used by the Microtec Research
+@code{ASM68K} assembler.
@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
* Listings::
* Other Commands::
* Syntax Details::
+* Alternate::
@end menu
@node Conditionals
When you compare strings, only two conditional @var{cmp} comparison
operators are available: @samp{EQ} (true if @var{stra} and @var{strb}
-are identical), and @samp{NE} (the converse).
+are identical), and @samp{NE} (the opposite).
When you compare two expressions, @emph{both expressions must be
absolute} (@pxref{Expressions,, Arithmetic expressions in GASP}). You
@itemx .AENDR
If you simply need to repeat the same block of assembly over and over a
fixed number of times, sandwich one instance of the repeated block
-between these @code{.AREPEAT} and @code{.AENDR}. Specify the number of
+between @code{.AREPEAT} and @code{.AENDR}. Specify the number of
copies as @var{aexp} (which must be an absolute expression). For
example, this repeats two assembly statements three times in succession:
the results of expressions.
You must distinguish two kinds of variables:
-@c FIXME! Is this crud true about conditional comparisons vs variables?
@enumerate
@item
Variables defined with @code{.EQU} or @code{.ASSIGN}. To evaluate this
assembly output.
@item
-Variables for use during preprocessing. These are defined as macro
-arguments, or with @code{.ASSIGNC} or @code{.ASSIGNA}. To evaluate this
+Variables for use during preprocessing. You can define these
+with @code{.ASSIGNC} or @code{.ASSIGNA}. To evaluate this
kind of variable, write @samp{\&} before the variable name; for example,
@cartouche
.AENDW
@end example
@end cartouche
+
+@sc{gasp} treats macro arguments almost the same way, but to evaluate
+them you use the prefix @samp{\} rather than @samp{\&}.
+@xref{Macros,, Defining your own directives}.
@end enumerate
@ftable @code
name if you wish; the first example above could have started @samp{eg:}
with the same effect.
+@c pagebreak makes for better aesthetics---ensures macro and expansion together
+@page
@node Macros
@section Defining your own directives
The commands @code{.MACRO} and @code{.ENDM} allow you to define macros
-that generate assembly output, and that you can use with a syntax
+that generate assembly output. You can use these macros with a syntax
similar to built-in @sc{gasp} or assembler directives. For example,
this definition specifies a macro @code{SUM} that adds together a range of
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
@cartouche
@example
- ; 0 5
+ ! 0 5
mov r0,r10
add r1,r10
add r2,r10
@item .MACRO PLUS1 P, P1
@itemx .MACRO PLUS1 P P1
Either statement begins the definition of a macro called @code{PLUS1},
-which takes two arguments; within the macro definition, these arguments
-are evaluated as @samp{\&P} and @samp{\&P1}.
+which takes two arguments; within the macro definition, write
+@samp{\P} or @samp{\P1} to evaluate the arguments.
@item .MACRO RESERVE_STR P1=0 P2
Begin the definition of a macro called @code{RESERVE_STR}, with two
arguments. The first argument has a default value, but not the second.
After the definition is complete, you can call the macro either as
-@samp{RESERVE_STR @var{a},@var{b}} (with @samp{\&P1} evaluating to
-@var{a} and @samp{\&P2} evaluating to @var{b}), or as @samp{RESERVE_STR
-,@var{b}} (with @samp{\&P1} evaluating as the default, in this case
-@samp{0}, and @samp{\&P2} evaluating to @var{b}).
+@samp{RESERVE_STR @var{a},@var{b}} (with @samp{\P1} evaluating to
+@var{a} and @samp{\P2} evaluating to @var{b}), or as @samp{RESERVE_STR
+,@var{b}} (with @samp{\P1} evaluating as the default, in this case
+@samp{0}, and @samp{\P2} evaluating to @var{b}).
@end table
-When you call a macro, the values are assigned by position to each
-argument name. Macro arguments are preprocessor variables in the same
-way as variables you define with @samp{.ASSIGNA} or @samp{.ASSIGNC}, and
-you can therefore use them in conditionals or for loop control.
+When you call a macro, you can specify the argument values either by
+position, or by keyword. For example, @samp{SUM 9,17} is equivalent to
+@samp{SUM TO=17, FROM=9}. Macro arguments are preprocessor variables
+similar to the variables you define with @samp{.ASSIGNA} or
+@samp{.ASSIGNC}; in particular, you can use them in conditionals or for
+loop control. (The only difference is the prefix you write to evaluate
+the variable: for a macro argument, write @samp{\@var{argname}}, but for
+a preprocessor variable, write @samp{\&@var{varname}}.)
@item @var{name} .MACRO
@itemx @var{name} .MACRO ( @var{macargs} @dots{} )
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.
@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
@node Listings
@section Assembly listing control
-The @sc{gasp} listing-control directives map straightforwardly to
+The @sc{gasp} listing-control directives correspond to
related @sc{gnu} @code{as} directives.
@ftable @code
@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}
@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
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
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
recent @code{.RADIX}).
To write a number in a @emph{specific base}, use the pattern
-@code{'@var{s}@var{ddd}}: a single quote, followed by a base specifier
-character @var{s}, followed by digits @var{ddd}. The base specifier
+@code{@var{s}'@var{ddd}}: a base specifier character @var{s}, followed
+by a single quote followed by digits @var{ddd}. The base specifier
character matches those you can specify with @code{.RADIX}: @samp{B} for
base 2, @samp{Q} for base 8, @samp{D} for base 10, and @samp{H} for base
16. (You can write this character in lower case if you prefer.)
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}.
+
+@need 2000
+@item String delimiters
+You can write strings delimited in these 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.
+@end table
+
+@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!}.
+
+@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
@printindex cp
+
+@contents
@bye
projects / thirdparty / binutils-gdb.git / blobdiff