diff options
Diffstat (limited to 'gas/doc/gasp.texi')
| -rw-r--r-- | gas/doc/gasp.texi | 1086 |
1 files changed, 1086 insertions, 0 deletions
diff --git a/gas/doc/gasp.texi b/gas/doc/gasp.texi new file mode 100644 index 0000000000..64cd6f44b1 --- /dev/null +++ b/gas/doc/gasp.texi @@ -0,0 +1,1086 @@ +\input texinfo @c -*- Texinfo -*- +@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 + +@finalout +@setchapternewpage odd +@settitle GASP +@titlepage +@c FIXME boring title +@title GASP, an assembly preprocessor +@subtitle for GASP version 1 +@sp 1 +@subtitle March 1994 +@author Roland Pesch +@page + +@tex +{\parskip=0pt \hfill Cygnus Support\par +} +@end tex + +@vskip 0pt plus 1filll +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 +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, 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 +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 1 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=12 + +bar: mov #H'dead+10,r0 +foo .SDATAC "hello"<10> + .END +@end example +@end cartouche + +@noindent +generates this assembly program: + +@cartouche +@example + ! 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 +@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.asm | 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 [ -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 + +@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 -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{-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 comment character at the beginning of the line). + +@item -s +@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 +@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:: +* Alternate:: +@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 opposite). + +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 @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 strings, registers, or +the results of expressions. + +You must distinguish two kinds of 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 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 +@example +opcit .ASSIGNA 47 + @dots{} + .AWHILE \&opcit GT 0 + @dots{} + .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 +@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. + +@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. 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 + 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, 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}). +@end table + +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{} ) +@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 other 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}. + +@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 +@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 correspond 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 .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} +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 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 ! +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 +@end example + +@noindent +issues as the first line of output a comment that records the +values you used to call the macro. + +@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 +@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. (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 +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 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.) + +@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}") +Calculate 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 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 |