| \input texinfo @c -*- Texinfo -*- |
| @setfilename gasp.info |
| @c |
| @c This file documents the assembly preprocessor "GASP" |
| @c |
| @c Copyright 1994, 1995, 2000, 2002 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, 2002 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, 2002 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. |
| |
| @emph{Note} The use of @sc{gasp} has now been deprecated. Anything |
| that it could do can now be done by the macro facilities built into |
| @sc{gas} itself. At some point in the future the @{gasp} sources will |
| be removed entirely from the binutils distribution. |
| |
| 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.) |
| |
| You can write floating point constants using the same syntax recognised |
| by GAS @ref{Flonums,,Flonums,as,The GNU Assembler.}. A constraint is |
| that these constants will be interpreted as decimal values irrespective |
| of the currently selected base. |
| |
| @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 |