gasp.texi

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

\input texinfo               @c             -*- Texinfo -*-
@setfilename gasp.info
@c
@c This file documents the assembly preprocessor "GASP"
@c
@c Copyright 1994, 1995, 2000 Free Software Foundation, Inc.
@c
@c    Permission is granted to copy, distribute and/or modify this document
@c    under the terms of the GNU Free Documentation License, Version 1.1
@c    or any later version published by the Free Software Foundation;
@c    with no Invariant Sections, with no Front-Cover Texts, and with no
@c    Back-Cover Texts.  A copy of the license is included in the
@c    section entitled "GNU Free Documentation 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, 2000 Free Software Foundation, Inc.

      Permission is granted to copy, distribute and/or modify this document
      under the terms of the GNU Free Documentation License, Version 1.1
      or any later version published by the Free Software Foundation;
      with no Invariant Sections, with no Front-Cover Texts, and with no
      Back-Cover Texts.  A copy of the license is included in the
      section entitled "GNU Free Documentation License".

@end titlepage

@ifinfo
Copyright @copyright{} 1994, 1995, 2000 Free Software Foundation, Inc.

@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, distribute and/or modify this document
      under the terms of the GNU Free Documentation License, Version 1.1
      or any later version published by the Free Software Foundation;
      with no Invariant Sections, with no Front-Cover Texts, and with no
      Back-Cover Texts.  A copy of the license is included in the
      section entitled "GNU Free Documentation License".


@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.
* GNU Free Documentation License::  GNU Free Documentation License
* 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