1087 lines
37 KiB
Plaintext
1087 lines
37 KiB
Plaintext
\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
|