A manual for the GNU assembler preprocessor.

1 files changed, 967 insertions, 0 deletions

diff --git a/gas/doc/gasp.texi b/gas/doc/gasp.texi
new file mode 100644
index 0000000..6807811
--- /dev/null
+++ b/gas/doc/gasp.texi
@@ -0,0 +1,967 @@
+\input texinfo               @c             -*- Texinfo -*-
+@finalout
+@setfilename gasp.info
+@c
+@c This file documents the assembly preprocessor "GASP"
+@c
+@c Copyright (c) 1994 Free Software Foundation, Inc.
+@c
+@c This text may be freely distributed under the terms of the GNU
+@c General Public License.
+
+@ifinfo
+@format
+START-INFO-DIR-ENTRY
+* gasp:(gasp).                     The GNU Assembler Preprocessor
+END-INFO-DIR-ENTRY
+@end format
+@end ifinfo
+
+@syncodeindex ky cp
+@syncodeindex fn cp
+
+@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 ??
+@sp 1
+@subtitle January 1994
+@author Roland Pesch
+@page
+
+@tex
+{\parskip=0pt \hfill Cygnus Support\par
+}
+@end tex
+
+@vskip 0pt plus 1filll
+Copyright @copyright{} 1994 Free Software Foundation, Inc.
+
+Permission is granted to make and distribute verbatim copies of
+this manual provided the copyright notice and this permission notice
+are preserved on all copies.
+
+Permission is granted to copy and distribute modified versions of this
+manual under the conditions for verbatim copying, provided also that
+the entire resulting derived work is distributed under the terms of a
+permission notice identical to this one.
+
+Permission is granted to copy and distribute translations of this manual
+into another language, under the above conditions for modified versions.
+@end titlepage
+
+@ifinfo
+Copyright @copyright{} 1994 Free Software Foundation, Inc.
+
+Permission is granted to make and distribute verbatim copies of
+this manual provided the copyright notice and this permission notice
+are preserved on all copies.
+
+@ignore
+Permission is granted to process this file through TeX and print the
+results, provided the printed document carries a copying permission
+notice identical to this one except for the removal of this paragraph
+(this paragraph not being relevant to the printed manual).
+@end ignore
+
+Permission is granted to copy and distribute modified versions of this
+manual under the conditions for verbatim copying, provided also that
+the entire resulting derived work is distributed under the terms of a
+permission notice identical to this one.
+
+Permission is granted to copy and distribute translations of this manual
+into another language, under the above conditions for modified versions.
+
+@node Top
+@top GASP
+
+GASP is a preprocessor for assembly programs.
+
+This file describes version ?? of GASP.
+
+Steve Chamberlain wrote GASP; Roland Pesch wrote this manual.
+
+@menu
+* Overview::                    What is GASP?
+* Invoking GASP::               Command line options.
+* Commands::                    Preprocessor commands.
+* Index::                       Index.
+@end menu
+@end ifinfo
+
+@node Overview
+@chapter What is GASP?
+
+The primary purpose of the @sc{gnu} assembler is to assemble the output of
+other programs---notably compilers.  When you have to hand-code
+specialized routines in assembly, that means the @sc{gnu} assembler is
+an unfriendly processor: it has no directives for macros, conditionals,
+or many other conveniences that you might expect.
+
+In some cases you can simply use the C preprocessor, or a generalized
+preprocessor like @sc{m4}; but this can be awkward, since none of these
+things are designed with assembly in mind.
+
+@sc{gasp} fills this need.  It is expressly designed to provide the
+facilities you need with hand-coded assembly code.  Implementing it as a
+preprocessor, rather than part of the assembler, allows the maximum
+flexibility: you can use it with hand-coded assembly, without paying a
+penalty of added complexity in the assembler you use for compiler
+output.
+
+Here is a small example to give the flavor of @sc{gasp}.  This input to
+@sc{gasp}
+
+@cartouche
+@example
+        .MACRO  saveregs from=8 to=14
+count   .ASSIGNA \from
+        ; 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
+
+        .RADIX  Q
+bar:    mov     #H'dead+12,r0
+foo     .SDATAC "hello"<12>
+        .END
+@end example
+@end cartouche
+
+@noindent
+generates this assembly program:
+
+@cartouche
+@example
+        ; save r9..r14
+        mov     r9,@@-sp
+        mov     r10,@@-sp
+        mov     r11,@@-sp
+        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
+@end example
+@end cartouche
+
+@node Invoking GASP
+@chapter Command Line Options
+
+@c FIXME!  Or is there a simpler way, calling from GAS option?
+The simplest way to use @sc{gasp} is to run it as a filter and assemble
+its output.  In Unix and its ilk, you can do this, for example:
+
+@c FIXME! GASP filename suffix convention?
+@example
+$ gasp prog.sp | as -o prog.o
+@end example
+
+Naturally, there are also a few command-line options to allow you to
+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 ]  @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?
+The input file names.  You must specify at least one input file; if you
+specify more, @sc{gasp} preprocesses them all, concatenating the output
+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 -o @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
+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
+-p}, @sc{gasp} displays the line number of each source line copied
+(immediately after the @samp{!} that marks source lines in the output).
+
+@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.
+
+@item -u
+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.
+@end ftable
+
+@node Commands
+@chapter Preprocessor Commands
+
+@sc{gasp} commands have a straightforward syntax that fits in well with
+assembly conventions.  In general, a command extends for a line, and may
+have up to three fields: an optional label, the command itself, and
+optional arguments to the command.  You can write commands in upper or
+lower case, though this manual shows them in upper case.  @xref{Syntax
+Details,, Details of the GASP syntax}, for more information.
+
+@menu
+* Conditionals::
+* Loops::
+* Variables::
+* Macros::
+* Data::
+* Listings::
+* Other Commands::
+* Syntax Details::
+@end menu
+
+@node Conditionals
+@section Conditional assembly
+
+The conditional-assembly directives allow you to include or exclude
+portions of an assembly depending on how a pair of expressions, or a
+pair of strings, compare.
+
+The overall structure of conditionals is familiar from many other
+contexts.  @code{.AIF} marks the start of a conditional, and precedes
+assembly for the case when the condition is true.   An optional
+@code{.AELSE} precedes assembly for the converse case, and an
+@code{.AENDI} marks the end of the condition.
+
+@c FIXME! Why doesn't -u turn off this check?
+You may nest conditionals up to a depth of 100; @sc{gasp} rejects
+nesting beyond that, because it may indicate a bug in your macro
+structure.
+
+@c FIXME! Why isn't there something like cpp's -D option?  Conditionals
+@c        would be much more useful if there were.
+Conditionals are primarily useful inside macro definitions, where you
+often need different effects depending on argument values.
+@xref{Macros,, Defining your own directives}, for details about defining
+macros.
+
+@ftable @code
+@item .AIF @var{expra} @var{cmp} @var{exprb}
+@itemx .AIF "@var{stra}" @var{cmp} "@var{strb}"
+
+The governing condition goes on the same line as the @code{.AIF}
+preprocessor command.  You may compare either two strings, or two
+expressions.
+
+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).
+
+When you compare two expressions, @emph{both expressions must be
+absolute} (@pxref{Expressions,, Arithmetic expressions in GASP}).  You
+can use these @var{cmp} comparison operators with expressions:
+
+@ftable @code
+@item EQ
+Are @var{expra} and @var{exprb} equal?  (For strings, are @var{stra} and
+@var{strb} identical?)
+
+@item NE
+Are @var{expra} and @var{exprb} different?  (For strings, are @var{stra}
+and @var{strb} different?
+
+@item LT
+Is @var{expra} less than @var{exprb}?  (Not allowed for strings.)
+
+@item LE
+Is @var{expra} less than or equal to @var{exprb}?  (Not allowed for strings.)
+
+@item GT
+Is @var{expra} greater than @var{exprb}?  (Not allowed for strings.)
+
+@item GE
+Is @var{expra} greater than or equal to @var{exprb}?  (Not allowed for
+strings.)
+@end ftable
+
+@item .AELSE
+Marks the start of assembly code to be included if the condition fails.
+Optional, and only allowed within a conditional (between @code{.AIF} and
+@code{.AENDI}).
+
+@item .AENDI
+Marks the end of a conditional assembly.
+@end ftable
+
+@node Loops
+@section Repetitive sections of assembly
+
+Two preprocessor directives allow you to repeatedly issue copies of the
+same block of assembly code.
+
+@ftable @code
+@item .AREPEAT @var{aexp}
+@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
+copies as @var{aexp} (which must be an absolute expression).  For
+example, this repeats two assembly statements three times in succession:
+
+@cartouche
+@example
+        .AREPEAT        3
+        rotcl   r2
+        div1    r0,r1
+        .AENDR
+@end example
+@end cartouche
+
+@item .AWHILE @var{expra} @var{cmp} @var{exprb}
+@itemx .AENDW
+@itemx .AWHILE @var{stra} @var{cmp} @var{strb}
+@itemx .AENDW
+To repeat a block of assembly depending on a conditional test, rather
+than repeating it for a specific number of times, use @code{.AWHILE}.
+@code{.AENDW} marks the end of the repeated block.  The conditional
+comparison works exactly the same way as for @code{.AIF}, with the same
+comparison operators (@pxref{Conditionals,, Conditional assembly}).
+
+Since the terms of the comparison must be absolute expression,
+@code{.AWHILE} is primarily useful within macros.  @xref{Macros,,
+Defining your own directives}.
+@end ftable
+
+@cindex loops, breaking out of
+@cindex breaking out of loops
+You can use the @code{.EXITM} preprocessor directive to break out of
+loops early (as well as to break out of macros).  @xref{Macros,,
+Defining your own directives}.
+
+@node Variables
+@section Preprocessor variables
+
+You can use variables in @sc{gasp} to represent the results of
+expressions, strings, or registers.  
+
+There are two kinds of preprocessor variable: 
+
+@c FIXME!  Is this crud true about conditional comparisons vs variables?
+@enumerate
+@item
+Variables defined with @code{.EQU} or @code{.ASSIGN}.  To evaluate this
+kind of variable in your assembly output, simply mention its name.  For
+example, these two lines define and use a variable @samp{eg}:
+
+@cartouche
+@example
+eg     .EQU   FLIP-64
+       @dots{}
+       mov.l  eg,r0
+@end example
+@end cartouche
+
+@emph{Do not use} this kind of variable in conditional expressions or
+while loops; @sc{gasp} only evaluates these variables when writing
+assembly output.
+
+@item
+Variables defined as macro arguments, or with @code{.ASSIGNC} or
+@code{.ASSIGNA}.  To evaluate this kind of variable, write @samp{\&} before
+the variable name; for example,
+
+@cartouche
+@example
+opcit  .ASSIGNA  47
+       @dots{}
+       .AWHILE  \&opcit GT 0
+       @dots{}
+       .AENDW
+@end example
+@end cartouche
+@end enumerate
+
+@ftable @code
+@item @var{pvar} .EQU @var{expr}
+@c FIXME!  Anything to beware of re GAS directive of same name?
+Assign preprocessor variable @var{pvar} the value of the expression
+@var{expr}.  There are no restrictions on redefinition; use @samp{.EQU}
+with the same @var{pvar} as often as you find it convenient.
+
+@item @var{pvar} .ASSIGN @var{expr}
+Almost the same as @code{.EQU}, save that you may not redefine
+@var{pvar} using @code{.ASSIGN} once it has a value.
+@c FIXME!!  Supposed to work this way, apparently, but on 9feb94 works
+@c          just like .EQU
+
+@item @var{pvar} .ASSIGNA @var{aexpr}
+Define a variable with a numeric value, for use during preprocessing.
+@var{aexpr} must be an absolute expression.  You can redefine variables
+with @code{.ASSIGNA} at any time.
+
+@item @var{pvar} .ASSIGNC "@var{str}"
+Define a variable with a string value, for use during preprocessing.
+You can redefine variables with @code{.ASSIGNC} at any time.
+
+@item @var{pvar} .REG (@var{register})
+Use @code{.REG} to define a variable that represents a register.  In
+particular, @var{register} is @emph{not evaluated} as an expression.
+You may use @code{.REG} at will to redefine register variables.
+@end ftable
+
+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; the first example above could have started @samp{eg:}
+with the same effect.
+
+@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
+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
+        mov     r\FROM,r10
+COUNT   .ASSIGNA        \FROM+1
+        .AWHILE \&COUNT LE \TO
+        add     r\&COUNT,r10
+COUNT   .ASSIGNA        \&COUNT+1
+        .AENDW
+        .ENDM
+@end example
+@end cartouche
+
+@noindent
+With that definition, @samp{SUM 0,5} generates this assembly output:
+
+@cartouche
+@example
+        ; 0 5
+        mov     r0,r10
+        add     r1,r10
+        add     r2,r10
+        add     r3,r10
+        add     r4,r10
+        add     r5,r10
+@end example
+@end cartouche
+
+@ftable @code
+@item .MACRO @var{macname}
+@itemx .MACRO @var{macname} @var{macargs} @dots{}
+Begin the definition of a macro called @var{macname}.  If your macro
+definition requires arguments, specify their names after the macro name,
+separated by commas or spaces.  You can supply a default value for any
+macro argument by following the name with @samp{=@var{deflt}}.  For
+example, these are all valid @code{.MACRO} statements:
+
+@table @code
+@item .MACRO COMM
+Begin the definition of a macro called @code{COMM}, which takes no
+arguments.
+
+@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}.
+
+@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}).
+@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.
+
+@item @var{name} .MACRO
+@itemx @var{name} .MACRO ( @var{macargs} @dots{} )
+@c FIXME check: I think no error _and_ no args recognized if I use form
+@c       NAME  .MACRO   ARG ARG
+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.
+
+@item .ENDM
+Mark the end of a macro definition.
+
+@item .EXITM
+Exit early from the current macro definition, @code{.AREPEAT} loop, or
+@code{.AWHILE} loop.
+
+@cindex number of macros executed
+@cindex macros, count executed
+@item \@@
+@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}.
+@end ftable
+
+@node Data
+@section Data output
+
+In assembly code, you often need to specify working areas of memory;
+depending on the application, you may want to initialize such memory or
+not.  @sc{gasp} provides preprocessor directives to help you avoid
+repetitive coding for both purposes.
+
+You can use labels as usual to mark the data areas.
+
+@menu
+* Initialized::
+* Uninitialized::
+@end menu
+
+@node Initialized
+@subsection Initialized data
+
+These are the @sc{gasp} directives for initialized data, and the standard
+@sc{gnu} assembler directives they expand to:
+
+@ftable @code
+@item .DATA @var{expr}, @var{expr}, @dots{}
+@itemx .DATA.B @var{expr}, @var{expr}, @dots{}
+@itemx .DATA.W @var{expr}, @var{expr}, @dots{}
+@itemx .DATA.L @var{expr}, @var{expr}, @dots{}
+Evaluate arithmetic expressions @var{expr}, and emit the corresponding
+@code{as} directive (labelled with @var{lab}).  The unqualified
+@code{.DATA} emits @samp{.long}; @code{.DATA.B} emits @samp{.byte};
+@code{.DATA.W} emits @samp{.short}; and @code{.DATA.L} emits
+@samp{.long}.
+
+For example, @samp{foo .DATA 1,2,3} emits @samp{foo: .long 1,2,3}.
+
+@item .DATAB @var{repeat}, @var{expr}
+@itemx .DATAB.B @var{repeat}, @var{expr}
+@itemx .DATAB.W @var{repeat}, @var{expr}
+@itemx .DATAB.L @var{repeat}, @var{expr}
+@c FIXME! Looks like gasp accepts and ignores args after 2nd.
+Make @code{as} emit @var{repeat} copies of the value of the expression
+@var{expr} (using the @code{as} directive @code{.fill}).
+@samp{.DATAB.B} repeats one-byte values; @samp{.DATAB.W} repeats
+two-byte values; and @samp{.DATAB.L} repeats four-byte values.
+@samp{.DATAB} without a suffix repeats four-byte values, just like
+@samp{.DATAB.L}.
+
+@c FIXME! Allowing zero might be useful for edge conditions in macros.
+@var{repeat} must be an absolute expression with a positive value.
+
+@item .SDATA "@var{str}" @dots{}
+String data.  Emits a concatenation of bytes, precisely as you specify
+them (in particular, @emph{nothing is added to mark the end} of the
+string).  @xref{Constants,, String and numeric constants}, for details
+about how to write strings.  @code{.SDATA} concatenates multiple
+arguments, making it easy to switch between string representations.  You
+can use commas to separate the individual arguments for clarity, if you
+choose.
+
+@item .SDATAB @var{repeat}, "@var{str}" @dots{}
+Repeated string data.  The first argument specifies how many copies of
+the string to emit; the remaining arguments specify the string, in the
+same way as the arguments to @code{.SDATA}.
+
+@item .SDATAZ "@var{str}" @dots{}
+Zero-terminated string data.  Just like @code{.SDATA}, except that
+@code{.SDATAZ} writes a zero byte at the end of the string.
+
+@item .SDATAC "@var{str}" @dots{}
+Count-prefixed string data.  Just like @code{.SDATA}, except that
+@sc{gasp} precedes the string with a leading one-byte count.  For
+example, @samp{.SDATAC "HI"} generates @samp{.byte 2,72,73}.  Since the
+count field is only one byte, you can only use @code{.SDATAC} for
+strings less than 256 bytes in length.
+@end ftable
+
+@node Uninitialized
+@subsection Uninitialized data
+
+@c FIXME!  .space different on some platforms, notably HPPA.  Config?
+Use the @code{.RES}, @code{.SRES}, @code{.SRESC}, and @code{.SRESZ}
+directives to reserve memory and leave it uninitialized.  @sc{gasp}
+resolves these directives to appropriate calls of the @sc{gnu}
+@code{as} @code{.space} directive.
+
+@ftable @code
+@item .RES @var{count}
+@itemx .RES.B @var{count}
+@itemx .RES.W @var{count}
+@itemx .RES.L @var{count}
+Reserve room for @var{count} uninitialized elements of data.  The
+suffix specifies the size of each element: @code{.RES.B} reserves
+@var{count} bytes, @code{.RES.W} reserves @var{count} pairs of bytes,
+and @code{.RES.L} reserves @var{count} quartets.  @code{.RES} without a
+suffix is equivalent to @code{.RES.L}.
+
+@item .SRES @var{count}
+@itemx .SRES.B @var{count}
+@itemx .SRES.W @var{count}
+@itemx .SRES.L @var{count}
+@c FIXME!  This is boring.  Shouldn't it at least have a different
+@c         default size?  (e.g. the "S" suggests "string", for which .B
+@c         would be more appropriate)
+@code{.SRES} is a synonym for @samp{.RES}.
+
+@item .SRESC @var{count}
+@itemx .SRESC.B @var{count}
+@itemx .SRESC.W @var{count}
+@itemx .SRESC.L @var{count}
+Like @code{.SRES}, but reserves space for @code{@var{count}+1} elements.
+
+@item .SRESZ @var{count}
+@itemx .SRESZ.B @var{count}
+@itemx .SRESZ.W @var{count}
+@itemx .SRESZ.L @var{count}
+Like @code{.SRES}, but reserves space for @code{@var{count}+1} elements.
+@end ftable
+
+@node Listings
+@section Assembly listing control
+
+The @sc{gasp} listing-control directives map straightforwardly to
+related @sc{gnu} @code{as} directives.
+
+@ftable @code
+@item .PRINT LIST
+@itemx .PRINT NOLIST
+Print control.  This directive emits the @sc{gnu} @code{as} directive
+@code{.list} or @code{.nolist}, according to its argument.  @xref{List,,
+@code{.list}, as.info, Using as}, for details on how these directives
+interact.
+
+@item .FORM LIN=@var{ln}
+@itemx .FORM COL=@var{cols}
+@itemx .FORM LIN=@var{ln} COL=@var{cols}
+Specify the page size for assembly listings: @var{ln} represents the
+number of lines, and @var{cols} the number of columns.  You may specify
+either page dimension independently, or both together.  If you do not
+specify the number of lines, @sc{gasp} assumes 60 lines; if you do not
+specify the number of columns, @sc{gasp} assumes 132 columns.
+(Any values you may have specified in previous instances of @code{.FORM}
+do @emph{not} carry over as defaults.)  Emits the @code{.psize}
+assembler directive.
+
+@item .HEADING @var{string}
+Specify @var{string} as the title of your assembly listings.  Emits
+@samp{.title "@var{string}"}.
+
+@item .PAGE
+Force a new page in assembly listings.  Emits @samp{.eject}.
+@end ftable
+
+@node Other Commands
+@section Miscellaneous commands
+
+@ftable @code
+@item .ORG
+@c FIXME!  This is very strange, since _GAS_ understands .org
+This command is recognized, but not yet implemented.  @sc{gasp}
+generates an error message for programs that use @code{.ORG}.
+
+@item .RADIX @var{s}
+@c FIXME no test cases in testsuite/gasp
+@sc{gasp} understands numbers in any of base two, eight, ten, or
+sixteen.  You can encode the base explicitly in any numeric constant
+(@pxref{Constants,, String and numeric constants}).  If you write
+numbers without an explicit indication of the base, the most recent
+@samp{.RADIX @var{s}} command determines how they are interpreted.
+@var{s} is a single letter, one of the following:
+
+@table @code
+@item .RADIX B
+Base 2.
+
+@item .RADIX Q
+Base 8.
+
+@item .RADIX D
+Base 10.  This is the original default radix.
+
+@item .RADIX H
+Base 16.
+@end table
+
+You may specify the argument @var{s} in lower case (any of @samp{bqdh})
+with the same effects.
+
+@item .EXPORT @var{name}
+@itemx .GLOBAL @var{name}
+@c FIXME! No test cases in testsuite/gasp
+Declare @var{name} global (emits @samp{.global @var{name}}).  The two
+directives are synonymous.
+
+@item .PROGRAM
+No effect: @sc{gasp} accepts this directive, and silently ignores it.
+
+@item .END
+Mark end of each preprocessor file.  @sc{gasp} issues a warning if it
+reaches end of file without seeing this command.
+
+@item .INCLUDE "@var{str}"
+Preprocess the file named by @var{str}, as if its contents appeared
+where the @code{.INCLUDE} directive does.  @sc{gasp} imposes a maximum
+limit of 30 stacked include files, as a sanity check.
+@c FIXME!  Why is include depth not affected by -u?
+
+@item .ALIGN @var{size}
+@c FIXME! Why is this not utterly pointless?
+Evaluate the absolute expression @var{size}, and emit the assembly
+instruction @samp{.align @var{size}} using the result.
+@end ftable
+
+@node Syntax Details
+@section Details of the GASP syntax
+
+Since @sc{gasp} is meant to work with assembly code, its statement
+syntax has no surprises for the assembly programmer.
+
+@cindex whitespace
+@emph{Whitespace} (blanks or tabs; @emph{not} newline) is partially
+significant, in that it delimits up to three fields in a line.  The
+amount of whitespace does not matter; you may line up fields in separate
+lines if you wish, but @sc{gasp} does not require that.
+
+@cindex fields of @sc{gasp} source line
+@cindex label field
+The @emph{first field}, an optional @dfn{label}, must be flush left in a
+line (with no leading whitespace) if it appears at all.  You may use a
+colon after the label if you wish; @sc{gasp} neither requires the colon
+nor objects to it (but will not include it as part of the label name).
+
+@cindex directive field
+The @emph{second field}, which must appear after some whitespace,
+contains a @sc{gasp} or assembly @dfn{directive}.
+
+@cindex argument fields
+Any @emph{further fields} on a line are @dfn{arguments} to the
+directive; you can separate them from one another using either commas or
+whitespace.
+
+@menu
+* Markers::
+* Constants::
+* Symbols::
+* Expressions::
+* String Builtins::
+@end menu
+
+@node Markers
+@subsection Special syntactic markers
+
+@sc{gasp} 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, @samp{\@@}, works only within macro definitions;
+@pxref{Macros,, Defining your own directives}.)
+
+@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:
+
+@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
+
+@example
+        .MACRO  SUM FROM=0, TO=9
+        ; \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.
+@end table
+
+@cindex continuation character
+@kindex +
+To @emph{continue a statement} on the next line of the file, begin the
+second line with the character @samp{+}.
+
+@cindex literal copy to output
+@cindex copying literally to output
+@cindex preprocessing, avoiding
+@cindex avoiding preprocessing
+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.
+
+@cindex symbol separator
+@cindex text, separating from symbols
+@cindex symbols, separating from text
+To @emph{separate a preprocessor variable} from text to appear
+immediately after its value, write a single quote (@code{'}).  For
+example, @samp{.SDATA "\P'1"} writes a string built by concatenating the
+value of @code{P} and the digit @samp{1}.  (You cannot achieve this by
+writing just @samp{\P1}, since @samp{P1} is itself a valid name for a
+preprocessor variable.)
+
+@node Constants
+@subsection String and numeric constants
+
+There are two ways of writing @dfn{string constants} in @sc{gasp}: as
+literal text, and by numeric byte value.  Specify a string literal
+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.
+
+@c Details of numeric notation, e.g. base prefixes
+You can write @dfn{numeric constants} either in a specific base, or in
+whatever base is currently selected (either 10, or selected by the most
+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
+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.)
+
+@c FIXME! What are rules for recognizing number in deflt base?  Whatever
+@c        is left over after parsing other things??
+
+@node Symbols
+@subsection Symbols
+
+@sc{gasp} recognizes symbol names that start with any alphabetic character,
+@samp{_}, or @samp{$}, and continue with any of the same characters or
+with digits.  Label names follow the same rules.
+
+@node Expressions
+@subsection Arithmetic expressions in GASP
+
+@cindex absolute expressions
+@cindex relocatable expressions
+There are two kinds of expressions, depending on their result:
+@dfn{absolute} expressions, which resolve to a constant (that is, they
+do not involve any values unknown to @sc{gasp}), and @dfn{relocatable}
+expressions, which must reduce to the form
+
+@example
+@var{addsym}+@var{const}-@var{subsym}
+@end example
+
+@noindent
+where @var{addsym} and @var{subsym} are assembly symbols of unknown
+value, and @var{const} is a constant.
+
+Arithmetic for @sc{gasp} 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.
+
+@enumerate
+@item
+Single-argument @code{+} (identity), @code{-} (arithmetic opposite), or
+@code{~} (bitwise negation).  @emph{The argument must be an absolute
+expression.}
+
+@item
+@code{*} (multiplication) and @code{/} (division).  @emph{Both arguments
+must be absolute expressions.}
+
+@item
+@code{+} (addition) and @code{-} (subtraction).  @emph{At least one argument
+must be absolute.}
+@c FIXME!  Actually, subtraction doesn't check for this.
+
+@item
+@code{&} (bitwise and).  @emph{Both arguments must be absolute.}
+
+@item
+@c FIXME!  I agree ~ is a better notation than ^ for xor, but is the
+@c         improvement worth differing from C?
+@code{|} (bitwise or) and @code{~} (bitwise exclusive or; @code{^} in
+C).  @emph{Both arguments must be absolute.}
+@end enumerate
+
+@node String Builtins
+@subsection String primitives
+
+You can use these primitives to manipulate strings (in the argument
+field of @sc{gasp} statements):
+
+@ftable @code
+@item .LEN("@var{str}")
+The length of string @code{"@var{str}"}, as an absolute expression.  For
+example, @samp{.RES.B .LEN("sample")} reserves six bytes of memory.
+
+@item .INSTR("@var{string}", "@var{seg}", @var{ix})
+Search for the first occurrence of @var{seg} after position @var{ix} of
+@var{string}.  For example, @samp{.INSTR("ABCDEFG", "CDE", 0)} evaluates
+to the absolute result @code{2}.
+
+The result is @code{-1} if @var{seg} does not occur in @var{string}
+after position @var{ix}.
+
+@item .SUBSTR("@var{string}",@var{start},@var{len})
+The substring of @var{string} beginning at byte number @var{start} and
+extending for @var{len} bytes.
+@end ftable
+
+@node Index
+@unnumbered Index
+
+@printindex cp
+@bye