gasp.texi

来自「基于4个mips核的noc设计」· TEXI 代码 · 共 1,447 行 · 第 1/4 页

@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