diff options
Diffstat (limited to 'gas/doc/gasp.texi')
| -rw-r--r-- | gas/doc/gasp.texi | 1086 |
1 files changed, 0 insertions, 1086 deletions
diff --git a/gas/doc/gasp.texi b/gas/doc/gasp.texi deleted file mode 100644 index 64cd6f44b17..00000000000 --- a/gas/doc/gasp.texi +++ /dev/null @@ -1,1086 +0,0 @@ -\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 |