1447 lines
54 KiB
Plaintext
1447 lines
54 KiB
Plaintext
\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
|
|
|
|
@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 GNU Free Documentation License
|
|
@chapter GNU Free Documentation License
|
|
|
|
GNU Free Documentation License
|
|
|
|
Version 1.1, March 2000
|
|
|
|
Copyright (C) 2000 Free Software Foundation, Inc.
|
|
59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
|
|
|
|
Everyone is permitted to copy and distribute verbatim copies
|
|
of this license document, but changing it is not allowed.
|
|
|
|
|
|
0. PREAMBLE
|
|
|
|
The purpose of this License is to make a manual, textbook, or other
|
|
written document "free" in the sense of freedom: to assure everyone
|
|
the effective freedom to copy and redistribute it, with or without
|
|
modifying it, either commercially or noncommercially. Secondarily,
|
|
this License preserves for the author and publisher a way to get
|
|
credit for their work, while not being considered responsible for
|
|
modifications made by others.
|
|
|
|
This License is a kind of "copyleft", which means that derivative
|
|
works of the document must themselves be free in the same sense. It
|
|
complements the GNU General Public License, which is a copyleft
|
|
license designed for free software.
|
|
|
|
We have designed this License in order to use it for manuals for free
|
|
software, because free software needs free documentation: a free
|
|
program should come with manuals providing the same freedoms that the
|
|
software does. But this License is not limited to software manuals;
|
|
it can be used for any textual work, regardless of subject matter or
|
|
whether it is published as a printed book. We recommend this License
|
|
principally for works whose purpose is instruction or reference.
|
|
|
|
|
|
1. APPLICABILITY AND DEFINITIONS
|
|
|
|
This License applies to any manual or other work that contains a
|
|
notice placed by the copyright holder saying it can be distributed
|
|
under the terms of this License. The "Document", below, refers to any
|
|
such manual or work. Any member of the public is a licensee, and is
|
|
addressed as "you".
|
|
|
|
A "Modified Version" of the Document means any work containing the
|
|
Document or a portion of it, either copied verbatim, or with
|
|
modifications and/or translated into another language.
|
|
|
|
A "Secondary Section" is a named appendix or a front-matter section of
|
|
the Document that deals exclusively with the relationship of the
|
|
publishers or authors of the Document to the Document's overall subject
|
|
(or to related matters) and contains nothing that could fall directly
|
|
within that overall subject. (For example, if the Document is in part a
|
|
textbook of mathematics, a Secondary Section may not explain any
|
|
mathematics.) The relationship could be a matter of historical
|
|
connection with the subject or with related matters, or of legal,
|
|
commercial, philosophical, ethical or political position regarding
|
|
them.
|
|
|
|
The "Invariant Sections" are certain Secondary Sections whose titles
|
|
are designated, as being those of Invariant Sections, in the notice
|
|
that says that the Document is released under this License.
|
|
|
|
The "Cover Texts" are certain short passages of text that are listed,
|
|
as Front-Cover Texts or Back-Cover Texts, in the notice that says that
|
|
the Document is released under this License.
|
|
|
|
A "Transparent" copy of the Document means a machine-readable copy,
|
|
represented in a format whose specification is available to the
|
|
general public, whose contents can be viewed and edited directly and
|
|
straightforwardly with generic text editors or (for images composed of
|
|
pixels) generic paint programs or (for drawings) some widely available
|
|
drawing editor, and that is suitable for input to text formatters or
|
|
for automatic translation to a variety of formats suitable for input
|
|
to text formatters. A copy made in an otherwise Transparent file
|
|
format whose markup has been designed to thwart or discourage
|
|
subsequent modification by readers is not Transparent. A copy that is
|
|
not "Transparent" is called "Opaque".
|
|
|
|
Examples of suitable formats for Transparent copies include plain
|
|
ASCII without markup, Texinfo input format, LaTeX input format, SGML
|
|
or XML using a publicly available DTD, and standard-conforming simple
|
|
HTML designed for human modification. Opaque formats include
|
|
PostScript, PDF, proprietary formats that can be read and edited only
|
|
by proprietary word processors, SGML or XML for which the DTD and/or
|
|
processing tools are not generally available, and the
|
|
machine-generated HTML produced by some word processors for output
|
|
purposes only.
|
|
|
|
The "Title Page" means, for a printed book, the title page itself,
|
|
plus such following pages as are needed to hold, legibly, the material
|
|
this License requires to appear in the title page. For works in
|
|
formats which do not have any title page as such, "Title Page" means
|
|
the text near the most prominent appearance of the work's title,
|
|
preceding the beginning of the body of the text.
|
|
|
|
|
|
2. VERBATIM COPYING
|
|
|
|
You may copy and distribute the Document in any medium, either
|
|
commercially or noncommercially, provided that this License, the
|
|
copyright notices, and the license notice saying this License applies
|
|
to the Document are reproduced in all copies, and that you add no other
|
|
conditions whatsoever to those of this License. You may not use
|
|
technical measures to obstruct or control the reading or further
|
|
copying of the copies you make or distribute. However, you may accept
|
|
compensation in exchange for copies. If you distribute a large enough
|
|
number of copies you must also follow the conditions in section 3.
|
|
|
|
You may also lend copies, under the same conditions stated above, and
|
|
you may publicly display copies.
|
|
|
|
|
|
3. COPYING IN QUANTITY
|
|
|
|
If you publish printed copies of the Document numbering more than 100,
|
|
and the Document's license notice requires Cover Texts, you must enclose
|
|
the copies in covers that carry, clearly and legibly, all these Cover
|
|
Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on
|
|
the back cover. Both covers must also clearly and legibly identify
|
|
you as the publisher of these copies. The front cover must present
|
|
the full title with all words of the title equally prominent and
|
|
visible. You may add other material on the covers in addition.
|
|
Copying with changes limited to the covers, as long as they preserve
|
|
the title of the Document and satisfy these conditions, can be treated
|
|
as verbatim copying in other respects.
|
|
|
|
If the required texts for either cover are too voluminous to fit
|
|
legibly, you should put the first ones listed (as many as fit
|
|
reasonably) on the actual cover, and continue the rest onto adjacent
|
|
pages.
|
|
|
|
If you publish or distribute Opaque copies of the Document numbering
|
|
more than 100, you must either include a machine-readable Transparent
|
|
copy along with each Opaque copy, or state in or with each Opaque copy
|
|
a publicly-accessible computer-network location containing a complete
|
|
Transparent copy of the Document, free of added material, which the
|
|
general network-using public has access to download anonymously at no
|
|
charge using public-standard network protocols. If you use the latter
|
|
option, you must take reasonably prudent steps, when you begin
|
|
distribution of Opaque copies in quantity, to ensure that this
|
|
Transparent copy will remain thus accessible at the stated location
|
|
until at least one year after the last time you distribute an Opaque
|
|
copy (directly or through your agents or retailers) of that edition to
|
|
the public.
|
|
|
|
It is requested, but not required, that you contact the authors of the
|
|
Document well before redistributing any large number of copies, to give
|
|
them a chance to provide you with an updated version of the Document.
|
|
|
|
|
|
4. MODIFICATIONS
|
|
|
|
You may copy and distribute a Modified Version of the Document under
|
|
the conditions of sections 2 and 3 above, provided that you release
|
|
the Modified Version under precisely this License, with the Modified
|
|
Version filling the role of the Document, thus licensing distribution
|
|
and modification of the Modified Version to whoever possesses a copy
|
|
of it. In addition, you must do these things in the Modified Version:
|
|
|
|
A. Use in the Title Page (and on the covers, if any) a title distinct
|
|
from that of the Document, and from those of previous versions
|
|
(which should, if there were any, be listed in the History section
|
|
of the Document). You may use the same title as a previous version
|
|
if the original publisher of that version gives permission.
|
|
B. List on the Title Page, as authors, one or more persons or entities
|
|
responsible for authorship of the modifications in the Modified
|
|
Version, together with at least five of the principal authors of the
|
|
Document (all of its principal authors, if it has less than five).
|
|
C. State on the Title page the name of the publisher of the
|
|
Modified Version, as the publisher.
|
|
D. Preserve all the copyright notices of the Document.
|
|
E. Add an appropriate copyright notice for your modifications
|
|
adjacent to the other copyright notices.
|
|
F. Include, immediately after the copyright notices, a license notice
|
|
giving the public permission to use the Modified Version under the
|
|
terms of this License, in the form shown in the Addendum below.
|
|
G. Preserve in that license notice the full lists of Invariant Sections
|
|
and required Cover Texts given in the Document's license notice.
|
|
H. Include an unaltered copy of this License.
|
|
I. Preserve the section entitled "History", and its title, and add to
|
|
it an item stating at least the title, year, new authors, and
|
|
publisher of the Modified Version as given on the Title Page. If
|
|
there is no section entitled "History" in the Document, create one
|
|
stating the title, year, authors, and publisher of the Document as
|
|
given on its Title Page, then add an item describing the Modified
|
|
Version as stated in the previous sentence.
|
|
J. Preserve the network location, if any, given in the Document for
|
|
public access to a Transparent copy of the Document, and likewise
|
|
the network locations given in the Document for previous versions
|
|
it was based on. These may be placed in the "History" section.
|
|
You may omit a network location for a work that was published at
|
|
least four years before the Document itself, or if the original
|
|
publisher of the version it refers to gives permission.
|
|
K. In any section entitled "Acknowledgements" or "Dedications",
|
|
preserve the section's title, and preserve in the section all the
|
|
substance and tone of each of the contributor acknowledgements
|
|
and/or dedications given therein.
|
|
L. Preserve all the Invariant Sections of the Document,
|
|
unaltered in their text and in their titles. Section numbers
|
|
or the equivalent are not considered part of the section titles.
|
|
M. Delete any section entitled "Endorsements". Such a section
|
|
may not be included in the Modified Version.
|
|
N. Do not retitle any existing section as "Endorsements"
|
|
or to conflict in title with any Invariant Section.
|
|
|
|
If the Modified Version includes new front-matter sections or
|
|
appendices that qualify as Secondary Sections and contain no material
|
|
copied from the Document, you may at your option designate some or all
|
|
of these sections as invariant. To do this, add their titles to the
|
|
list of Invariant Sections in the Modified Version's license notice.
|
|
These titles must be distinct from any other section titles.
|
|
|
|
You may add a section entitled "Endorsements", provided it contains
|
|
nothing but endorsements of your Modified Version by various
|
|
parties--for example, statements of peer review or that the text has
|
|
been approved by an organization as the authoritative definition of a
|
|
standard.
|
|
|
|
You may add a passage of up to five words as a Front-Cover Text, and a
|
|
passage of up to 25 words as a Back-Cover Text, to the end of the list
|
|
of Cover Texts in the Modified Version. Only one passage of
|
|
Front-Cover Text and one of Back-Cover Text may be added by (or
|
|
through arrangements made by) any one entity. If the Document already
|
|
includes a cover text for the same cover, previously added by you or
|
|
by arrangement made by the same entity you are acting on behalf of,
|
|
you may not add another; but you may replace the old one, on explicit
|
|
permission from the previous publisher that added the old one.
|
|
|
|
The author(s) and publisher(s) of the Document do not by this License
|
|
give permission to use their names for publicity for or to assert or
|
|
imply endorsement of any Modified Version.
|
|
|
|
|
|
5. COMBINING DOCUMENTS
|
|
|
|
You may combine the Document with other documents released under this
|
|
License, under the terms defined in section 4 above for modified
|
|
versions, provided that you include in the combination all of the
|
|
Invariant Sections of all of the original documents, unmodified, and
|
|
list them all as Invariant Sections of your combined work in its
|
|
license notice.
|
|
|
|
The combined work need only contain one copy of this License, and
|
|
multiple identical Invariant Sections may be replaced with a single
|
|
copy. If there are multiple Invariant Sections with the same name but
|
|
different contents, make the title of each such section unique by
|
|
adding at the end of it, in parentheses, the name of the original
|
|
author or publisher of that section if known, or else a unique number.
|
|
Make the same adjustment to the section titles in the list of
|
|
Invariant Sections in the license notice of the combined work.
|
|
|
|
In the combination, you must combine any sections entitled "History"
|
|
in the various original documents, forming one section entitled
|
|
"History"; likewise combine any sections entitled "Acknowledgements",
|
|
and any sections entitled "Dedications". You must delete all sections
|
|
entitled "Endorsements."
|
|
|
|
|
|
6. COLLECTIONS OF DOCUMENTS
|
|
|
|
You may make a collection consisting of the Document and other documents
|
|
released under this License, and replace the individual copies of this
|
|
License in the various documents with a single copy that is included in
|
|
the collection, provided that you follow the rules of this License for
|
|
verbatim copying of each of the documents in all other respects.
|
|
|
|
You may extract a single document from such a collection, and distribute
|
|
it individually under this License, provided you insert a copy of this
|
|
License into the extracted document, and follow this License in all
|
|
other respects regarding verbatim copying of that document.
|
|
|
|
|
|
7. AGGREGATION WITH INDEPENDENT WORKS
|
|
|
|
A compilation of the Document or its derivatives with other separate
|
|
and independent documents or works, in or on a volume of a storage or
|
|
distribution medium, does not as a whole count as a Modified Version
|
|
of the Document, provided no compilation copyright is claimed for the
|
|
compilation. Such a compilation is called an "aggregate", and this
|
|
License does not apply to the other self-contained works thus compiled
|
|
with the Document, on account of their being thus compiled, if they
|
|
are not themselves derivative works of the Document.
|
|
|
|
If the Cover Text requirement of section 3 is applicable to these
|
|
copies of the Document, then if the Document is less than one quarter
|
|
of the entire aggregate, the Document's Cover Texts may be placed on
|
|
covers that surround only the Document within the aggregate.
|
|
Otherwise they must appear on covers around the whole aggregate.
|
|
|
|
|
|
8. TRANSLATION
|
|
|
|
Translation is considered a kind of modification, so you may
|
|
distribute translations of the Document under the terms of section 4.
|
|
Replacing Invariant Sections with translations requires special
|
|
permission from their copyright holders, but you may include
|
|
translations of some or all Invariant Sections in addition to the
|
|
original versions of these Invariant Sections. You may include a
|
|
translation of this License provided that you also include the
|
|
original English version of this License. In case of a disagreement
|
|
between the translation and the original English version of this
|
|
License, the original English version will prevail.
|
|
|
|
|
|
9. TERMINATION
|
|
|
|
You may not copy, modify, sublicense, or distribute the Document except
|
|
as expressly provided for under this License. Any other attempt to
|
|
copy, modify, sublicense or distribute the Document is void, and will
|
|
automatically terminate your rights under this License. However,
|
|
parties who have received copies, or rights, from you under this
|
|
License will not have their licenses terminated so long as such
|
|
parties remain in full compliance.
|
|
|
|
|
|
10. FUTURE REVISIONS OF THIS LICENSE
|
|
|
|
The Free Software Foundation may publish new, revised versions
|
|
of the GNU Free Documentation License from time to time. Such new
|
|
versions will be similar in spirit to the present version, but may
|
|
differ in detail to address new problems or concerns. See
|
|
http://www.gnu.org/copyleft/.
|
|
|
|
Each version of the License is given a distinguishing version number.
|
|
If the Document specifies that a particular numbered version of this
|
|
License "or any later version" applies to it, you have the option of
|
|
following the terms and conditions either of that specified version or
|
|
of any later version that has been published (not as a draft) by the
|
|
Free Software Foundation. If the Document does not specify a version
|
|
number of this License, you may choose any version ever published (not
|
|
as a draft) by the Free Software Foundation.
|
|
|
|
|
|
ADDENDUM: How to use this License for your documents
|
|
|
|
To use this License in a document you have written, include a copy of
|
|
the License in the document and put the following copyright and
|
|
license notices just after the title page:
|
|
|
|
@smallexample
|
|
Copyright (c) YEAR YOUR NAME.
|
|
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 the Invariant Sections being LIST THEIR TITLES, with the
|
|
Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST.
|
|
A copy of the license is included in the section entitled "GNU
|
|
Free Documentation License".
|
|
@end smallexample
|
|
|
|
If you have no Invariant Sections, write "with no Invariant Sections"
|
|
instead of saying which ones are invariant. If you have no
|
|
Front-Cover Texts, write "no Front-Cover Texts" instead of
|
|
"Front-Cover Texts being LIST"; likewise for Back-Cover Texts.
|
|
|
|
If your document contains nontrivial examples of program code, we
|
|
recommend releasing these examples in parallel under your choice of
|
|
free software license, such as the GNU General Public License,
|
|
to permit their use in free software.
|
|
|
|
@node Index
|
|
@unnumbered Index
|
|
|
|
@printindex cp
|
|
|
|
@contents
|
|
@bye
|