Commit | Line | Data |
---|---|---|
252b5132 RH |
1 | \input texinfo @c -*- Texinfo -*- |
2 | @setfilename gasp.info | |
3 | @c | |
4 | @c This file documents the assembly preprocessor "GASP" | |
5 | @c | |
3f965e60 | 6 | @c Copyright 1994, 1995, 2000, 2002 Free Software Foundation, Inc. |
252b5132 | 7 | @c |
cf055d54 NC |
8 | @c Permission is granted to copy, distribute and/or modify this document |
9 | @c under the terms of the GNU Free Documentation License, Version 1.1 | |
10 | @c or any later version published by the Free Software Foundation; | |
11 | @c with no Invariant Sections, with no Front-Cover Texts, and with no | |
12 | @c Back-Cover Texts. A copy of the license is included in the | |
13 | @c section entitled "GNU Free Documentation License". | |
252b5132 RH |
14 | |
15 | @ifinfo | |
16 | @format | |
17 | START-INFO-DIR-ENTRY | |
18 | * gasp: (gasp). The GNU Assembler Preprocessor | |
19 | END-INFO-DIR-ENTRY | |
20 | @end format | |
21 | @end ifinfo | |
22 | ||
23 | @syncodeindex ky cp | |
24 | @syncodeindex fn cp | |
25 | ||
26 | @finalout | |
27 | @setchapternewpage odd | |
28 | @settitle GASP | |
29 | @titlepage | |
30 | @c FIXME boring title | |
31 | @title GASP, an assembly preprocessor | |
32 | @subtitle for GASP version 1 | |
33 | @sp 1 | |
34 | @subtitle March 1994 | |
35 | @author Roland Pesch | |
36 | @page | |
37 | ||
38 | @tex | |
39 | {\parskip=0pt \hfill Cygnus Support\par | |
40 | } | |
41 | @end tex | |
42 | ||
43 | @vskip 0pt plus 1filll | |
3f965e60 | 44 | Copyright @copyright{} 1994, 1995, 2000, 2002 Free Software Foundation, Inc. |
252b5132 | 45 | |
cf055d54 NC |
46 | Permission is granted to copy, distribute and/or modify this document |
47 | under the terms of the GNU Free Documentation License, Version 1.1 | |
48 | or any later version published by the Free Software Foundation; | |
49 | with no Invariant Sections, with no Front-Cover Texts, and with no | |
50 | Back-Cover Texts. A copy of the license is included in the | |
51 | section entitled "GNU Free Documentation License". | |
252b5132 | 52 | |
252b5132 RH |
53 | @end titlepage |
54 | ||
55 | @ifinfo | |
3f965e60 | 56 | Copyright @copyright{} 1994, 1995, 2000, 2002 Free Software Foundation, Inc. |
252b5132 RH |
57 | |
58 | @ignore | |
59 | Permission is granted to process this file through TeX and print the | |
60 | results, provided the printed document carries a copying permission | |
61 | notice identical to this one except for the removal of this paragraph | |
62 | (this paragraph not being relevant to the printed manual). | |
63 | @end ignore | |
64 | ||
cf055d54 NC |
65 | Permission is granted to copy, distribute and/or modify this document |
66 | under the terms of the GNU Free Documentation License, Version 1.1 | |
67 | or any later version published by the Free Software Foundation; | |
68 | with no Invariant Sections, with no Front-Cover Texts, and with no | |
69 | Back-Cover Texts. A copy of the license is included in the | |
70 | section entitled "GNU Free Documentation License". | |
252b5132 | 71 | |
252b5132 RH |
72 | |
73 | @node Top | |
74 | @top GASP | |
75 | ||
76 | GASP is a preprocessor for assembly programs. | |
77 | ||
78 | This file describes version 1 of GASP. | |
79 | ||
80 | Steve Chamberlain wrote GASP; Roland Pesch wrote this manual. | |
81 | ||
82 | @menu | |
83 | * Overview:: What is GASP? | |
84 | * Invoking GASP:: Command line options. | |
85 | * Commands:: Preprocessor commands. | |
cf055d54 | 86 | * GNU Free Documentation License:: GNU Free Documentation License |
252b5132 RH |
87 | * Index:: Index. |
88 | @end menu | |
89 | @end ifinfo | |
90 | ||
91 | @node Overview | |
92 | @chapter What is GASP? | |
93 | ||
94 | The primary purpose of the @sc{gnu} assembler is to assemble the output of | |
95 | other programs---notably compilers. When you have to hand-code | |
96 | specialized routines in assembly, that means the @sc{gnu} assembler is | |
97 | an unfriendly processor: it has no directives for macros, conditionals, | |
98 | or many other conveniences that you might expect. | |
99 | ||
100 | In some cases you can simply use the C preprocessor, or a generalized | |
101 | preprocessor like @sc{m4}; but this can be awkward, since none of these | |
102 | things are designed with assembly in mind. | |
103 | ||
104 | @sc{gasp} fills this need. It is expressly designed to provide the | |
105 | facilities you need with hand-coded assembly code. Implementing it as a | |
106 | preprocessor, rather than part of the assembler, allows the maximum | |
107 | flexibility: you can use it with hand-coded assembly, without paying a | |
108 | penalty of added complexity in the assembler you use for compiler | |
109 | output. | |
110 | ||
3f965e60 NC |
111 | @emph{Note} The use of @sc{gas} has now been deprecated. Anything |
112 | that it could do can now be done by the macro facilities built into | |
113 | @sc{gas} itself. At some point in the future the @{gasp} sources will | |
114 | be removed entirely from the binutils distribution. | |
115 | ||
252b5132 RH |
116 | Here is a small example to give the flavor of @sc{gasp}. This input to |
117 | @sc{gasp} | |
118 | ||
119 | @cartouche | |
120 | @example | |
121 | .MACRO saveregs from=8 to=14 | |
122 | count .ASSIGNA \from | |
123 | ! save r\from..r\to | |
124 | .AWHILE \&count LE \to | |
125 | mov r\&count,@@-sp | |
126 | count .ASSIGNA \&count + 1 | |
127 | .AENDW | |
128 | .ENDM | |
129 | ||
130 | saveregs from=12 | |
131 | ||
132 | bar: mov #H'dead+10,r0 | |
133 | foo .SDATAC "hello"<10> | |
134 | .END | |
135 | @end example | |
136 | @end cartouche | |
137 | ||
138 | @noindent | |
139 | generates this assembly program: | |
140 | ||
141 | @cartouche | |
142 | @example | |
143 | ! save r12..r14 | |
144 | mov r12,@@-sp | |
145 | mov r13,@@-sp | |
146 | mov r14,@@-sp | |
147 | ||
148 | bar: mov #57005+10,r0 | |
149 | foo: .byte 6,104,101,108,108,111,10 | |
150 | @end example | |
151 | @end cartouche | |
152 | ||
153 | @node Invoking GASP | |
154 | @chapter Command Line Options | |
155 | ||
156 | @c FIXME! Or is there a simpler way, calling from GAS option? | |
157 | The simplest way to use @sc{gasp} is to run it as a filter and assemble | |
158 | its output. In Unix and its ilk, you can do this, for example: | |
159 | ||
160 | @c FIXME! GASP filename suffix convention? | |
161 | @example | |
162 | $ gasp prog.asm | as -o prog.o | |
163 | @end example | |
164 | ||
165 | Naturally, there are also a few command-line options to allow you to | |
166 | request variations on this basic theme. Here is the full set of | |
167 | possibilities for the @sc{gasp} command line. | |
168 | ||
169 | @example | |
170 | gasp [ -a | --alternate ] | |
171 | [ -c @var{char} | --commentchar @var{char} ] | |
172 | [ -d | --debug ] [ -h | --help ] [ -M | --mri ] | |
173 | [ -o @var{outfile} | --output @var{outfile} ] | |
174 | [ -p | --print ] [ -s | --copysource ] | |
175 | [ -u | --unreasonable ] [ -v | --version ] | |
176 | @var{infile} @dots{} | |
177 | @end example | |
178 | ||
179 | @ftable @code | |
180 | @item @var{infile} @dots{} | |
181 | @c FIXME! Why not stdin as default infile? | |
182 | The input file names. You must specify at least one input file; if you | |
183 | specify more, @sc{gasp} preprocesses them all, concatenating the output | |
184 | in the order you list the @var{infile} arguments. | |
185 | ||
186 | Mark the end of each input file with the preprocessor command | |
187 | @code{.END}. @xref{Other Commands,, Miscellaneous commands}. | |
188 | ||
189 | @item -a | |
190 | @itemx --alternate | |
191 | Use alternative macro syntax. @xref{Alternate,, Alternate macro | |
192 | syntax}, for a discussion of how this syntax differs from the default | |
193 | @sc{gasp} syntax. | |
194 | ||
195 | @cindex comment character, changing | |
196 | @cindex semicolon, as comment | |
197 | @cindex exclamation mark, as comment | |
198 | @cindex shriek, as comment | |
199 | @cindex bang, as comment | |
200 | @cindex @code{!} default comment char | |
201 | @cindex @code{;} as comment char | |
202 | @item -c '@var{char}' | |
203 | @itemx --commentchar '@var{char}' | |
204 | Use @var{char} as the comment character. The default comment character | |
205 | is @samp{!}. For example, to use a semicolon as the comment character, | |
206 | specify @w{@samp{-c ';'}} on the @sc{gasp} command line. Since | |
207 | assembler command characters often have special significance to command | |
208 | shells, it is a good idea to quote or escape @var{char} when you specify | |
209 | a comment character. | |
210 | ||
211 | For the sake of simplicity, all examples in this manual use the default | |
212 | comment character @samp{!}. | |
213 | ||
214 | @item -d | |
215 | @itemx --debug | |
216 | Show debugging statistics. In this version of @sc{gasp}, this option | |
217 | produces statistics about the string buffers that @sc{gasp} allocates | |
218 | internally. For each defined buffersize @var{s}, @sc{gasp} shows the | |
219 | number of strings @var{n} that it allocated, with a line like this: | |
220 | ||
221 | @example | |
222 | strings size @var{s} : @var{n} | |
223 | @end example | |
224 | ||
225 | @noindent | |
226 | @sc{gasp} displays these statistics on the standard error stream, when | |
227 | done preprocessing. | |
228 | ||
229 | @item -h | |
230 | @itemx --help | |
231 | Display a summary of the @sc{gasp} command line options. | |
232 | ||
233 | @item -M | |
234 | @itemx --mri | |
235 | Use MRI compatibility mode. Using this option causes @sc{gasp} to | |
236 | accept the syntax and pseudo-ops used by the Microtec Research | |
237 | @code{ASM68K} assembler. | |
238 | ||
239 | @item -o @var{outfile} | |
240 | @itemx --output @var{outfile} | |
241 | Write the output in a file called @var{outfile}. If you do not use the | |
242 | @samp{-o} option, @sc{gasp} writes its output on the standard output | |
243 | stream. | |
244 | ||
245 | @item -p | |
246 | @itemx --print | |
247 | Print line numbers. @sc{gasp} obeys this option @emph{only} if you also | |
248 | specify @samp{-s} to copy source lines to its output. With @samp{-s | |
249 | -p}, @sc{gasp} displays the line number of each source line copied | |
250 | (immediately after the comment character at the beginning of the line). | |
251 | ||
252 | @item -s | |
253 | @itemx --copysource | |
254 | Copy the source lines to the output file. Use this option | |
255 | to see the effect of each preprocessor line on the @sc{gasp} output. | |
256 | @sc{gasp} places a comment character (@samp{!} by default) at | |
257 | the beginning of each source line it copies, so that you can use this | |
258 | option and still assemble the result. | |
259 | ||
260 | @item -u | |
261 | @itemx --unreasonable | |
262 | Bypass ``unreasonable expansion'' limit. Since you can define @sc{gasp} | |
263 | macros inside other macro definitions, the preprocessor normally | |
264 | includes a sanity check. If your program requires more than 1,000 | |
265 | nested expansions, @sc{gasp} normally exits with an error message. Use | |
266 | this option to turn off this check, allowing unlimited nested | |
267 | expansions. | |
268 | ||
269 | @item -v | |
270 | @itemx --version | |
271 | Display the @sc{gasp} version number. | |
272 | @end ftable | |
273 | ||
274 | @node Commands | |
275 | @chapter Preprocessor Commands | |
276 | ||
277 | @sc{gasp} commands have a straightforward syntax that fits in well with | |
278 | assembly conventions. In general, a command extends for a line, and may | |
279 | have up to three fields: an optional label, the command itself, and | |
280 | optional arguments to the command. You can write commands in upper or | |
281 | lower case, though this manual shows them in upper case. @xref{Syntax | |
282 | Details,, Details of the GASP syntax}, for more information. | |
283 | ||
284 | @menu | |
285 | * Conditionals:: | |
286 | * Loops:: | |
287 | * Variables:: | |
288 | * Macros:: | |
289 | * Data:: | |
290 | * Listings:: | |
291 | * Other Commands:: | |
292 | * Syntax Details:: | |
293 | * Alternate:: | |
294 | @end menu | |
295 | ||
296 | @node Conditionals | |
297 | @section Conditional assembly | |
298 | ||
299 | The conditional-assembly directives allow you to include or exclude | |
300 | portions of an assembly depending on how a pair of expressions, or a | |
301 | pair of strings, compare. | |
302 | ||
303 | The overall structure of conditionals is familiar from many other | |
304 | contexts. @code{.AIF} marks the start of a conditional, and precedes | |
305 | assembly for the case when the condition is true. An optional | |
306 | @code{.AELSE} precedes assembly for the converse case, and an | |
307 | @code{.AENDI} marks the end of the condition. | |
308 | ||
309 | @c FIXME! Why doesn't -u turn off this check? | |
310 | You may nest conditionals up to a depth of 100; @sc{gasp} rejects | |
311 | nesting beyond that, because it may indicate a bug in your macro | |
312 | structure. | |
313 | ||
314 | @c FIXME! Why isn't there something like cpp's -D option? Conditionals | |
315 | @c would be much more useful if there were. | |
316 | Conditionals are primarily useful inside macro definitions, where you | |
317 | often need different effects depending on argument values. | |
318 | @xref{Macros,, Defining your own directives}, for details about defining | |
319 | macros. | |
320 | ||
321 | @ftable @code | |
322 | @item .AIF @var{expra} @var{cmp} @var{exprb} | |
323 | @itemx .AIF "@var{stra}" @var{cmp} "@var{strb}" | |
324 | ||
325 | The governing condition goes on the same line as the @code{.AIF} | |
326 | preprocessor command. You may compare either two strings, or two | |
327 | expressions. | |
328 | ||
329 | When you compare strings, only two conditional @var{cmp} comparison | |
330 | operators are available: @samp{EQ} (true if @var{stra} and @var{strb} | |
331 | are identical), and @samp{NE} (the opposite). | |
332 | ||
333 | When you compare two expressions, @emph{both expressions must be | |
334 | absolute} (@pxref{Expressions,, Arithmetic expressions in GASP}). You | |
335 | can use these @var{cmp} comparison operators with expressions: | |
336 | ||
337 | @ftable @code | |
338 | @item EQ | |
339 | Are @var{expra} and @var{exprb} equal? (For strings, are @var{stra} and | |
340 | @var{strb} identical?) | |
341 | ||
342 | @item NE | |
343 | Are @var{expra} and @var{exprb} different? (For strings, are @var{stra} | |
344 | and @var{strb} different? | |
345 | ||
346 | @item LT | |
347 | Is @var{expra} less than @var{exprb}? (Not allowed for strings.) | |
348 | ||
349 | @item LE | |
350 | Is @var{expra} less than or equal to @var{exprb}? (Not allowed for strings.) | |
351 | ||
352 | @item GT | |
353 | Is @var{expra} greater than @var{exprb}? (Not allowed for strings.) | |
354 | ||
355 | @item GE | |
356 | Is @var{expra} greater than or equal to @var{exprb}? (Not allowed for | |
357 | strings.) | |
358 | @end ftable | |
359 | ||
360 | @item .AELSE | |
361 | Marks the start of assembly code to be included if the condition fails. | |
362 | Optional, and only allowed within a conditional (between @code{.AIF} and | |
363 | @code{.AENDI}). | |
364 | ||
365 | @item .AENDI | |
366 | Marks the end of a conditional assembly. | |
367 | @end ftable | |
368 | ||
369 | @node Loops | |
370 | @section Repetitive sections of assembly | |
371 | ||
372 | Two preprocessor directives allow you to repeatedly issue copies of the | |
373 | same block of assembly code. | |
374 | ||
375 | @ftable @code | |
376 | @item .AREPEAT @var{aexp} | |
377 | @itemx .AENDR | |
378 | If you simply need to repeat the same block of assembly over and over a | |
379 | fixed number of times, sandwich one instance of the repeated block | |
380 | between @code{.AREPEAT} and @code{.AENDR}. Specify the number of | |
381 | copies as @var{aexp} (which must be an absolute expression). For | |
382 | example, this repeats two assembly statements three times in succession: | |
383 | ||
384 | @cartouche | |
385 | @example | |
386 | .AREPEAT 3 | |
387 | rotcl r2 | |
388 | div1 r0,r1 | |
389 | .AENDR | |
390 | @end example | |
391 | @end cartouche | |
392 | ||
393 | @item .AWHILE @var{expra} @var{cmp} @var{exprb} | |
394 | @itemx .AENDW | |
395 | @itemx .AWHILE @var{stra} @var{cmp} @var{strb} | |
396 | @itemx .AENDW | |
397 | To repeat a block of assembly depending on a conditional test, rather | |
398 | than repeating it for a specific number of times, use @code{.AWHILE}. | |
399 | @code{.AENDW} marks the end of the repeated block. The conditional | |
400 | comparison works exactly the same way as for @code{.AIF}, with the same | |
401 | comparison operators (@pxref{Conditionals,, Conditional assembly}). | |
402 | ||
403 | Since the terms of the comparison must be absolute expression, | |
404 | @code{.AWHILE} is primarily useful within macros. @xref{Macros,, | |
405 | Defining your own directives}. | |
406 | @end ftable | |
407 | ||
408 | @cindex loops, breaking out of | |
409 | @cindex breaking out of loops | |
410 | You can use the @code{.EXITM} preprocessor directive to break out of | |
411 | loops early (as well as to break out of macros). @xref{Macros,, | |
412 | Defining your own directives}. | |
413 | ||
414 | @node Variables | |
415 | @section Preprocessor variables | |
416 | ||
417 | You can use variables in @sc{gasp} to represent strings, registers, or | |
418 | the results of expressions. | |
419 | ||
420 | You must distinguish two kinds of variables: | |
421 | @enumerate | |
422 | @item | |
423 | Variables defined with @code{.EQU} or @code{.ASSIGN}. To evaluate this | |
424 | kind of variable in your assembly output, simply mention its name. For | |
425 | example, these two lines define and use a variable @samp{eg}: | |
426 | ||
427 | @cartouche | |
428 | @example | |
429 | eg .EQU FLIP-64 | |
430 | @dots{} | |
431 | mov.l eg,r0 | |
432 | @end example | |
433 | @end cartouche | |
434 | ||
435 | @emph{Do not use} this kind of variable in conditional expressions or | |
436 | while loops; @sc{gasp} only evaluates these variables when writing | |
437 | assembly output. | |
438 | ||
439 | @item | |
440 | Variables for use during preprocessing. You can define these | |
441 | with @code{.ASSIGNC} or @code{.ASSIGNA}. To evaluate this | |
442 | kind of variable, write @samp{\&} before the variable name; for example, | |
443 | ||
444 | @cartouche | |
445 | @example | |
446 | opcit .ASSIGNA 47 | |
447 | @dots{} | |
448 | .AWHILE \&opcit GT 0 | |
449 | @dots{} | |
450 | .AENDW | |
451 | @end example | |
452 | @end cartouche | |
453 | ||
454 | @sc{gasp} treats macro arguments almost the same way, but to evaluate | |
455 | them you use the prefix @samp{\} rather than @samp{\&}. | |
456 | @xref{Macros,, Defining your own directives}. | |
457 | @end enumerate | |
458 | ||
459 | @ftable @code | |
460 | @item @var{pvar} .EQU @var{expr} | |
461 | @c FIXME! Anything to beware of re GAS directive of same name? | |
462 | Assign preprocessor variable @var{pvar} the value of the expression | |
463 | @var{expr}. There are no restrictions on redefinition; use @samp{.EQU} | |
464 | with the same @var{pvar} as often as you find it convenient. | |
465 | ||
466 | @item @var{pvar} .ASSIGN @var{expr} | |
467 | Almost the same as @code{.EQU}, save that you may not redefine | |
468 | @var{pvar} using @code{.ASSIGN} once it has a value. | |
469 | @c FIXME!! Supposed to work this way, apparently, but on 9feb94 works | |
470 | @c just like .EQU | |
471 | ||
472 | @item @var{pvar} .ASSIGNA @var{aexpr} | |
473 | Define a variable with a numeric value, for use during preprocessing. | |
474 | @var{aexpr} must be an absolute expression. You can redefine variables | |
475 | with @code{.ASSIGNA} at any time. | |
476 | ||
477 | @item @var{pvar} .ASSIGNC "@var{str}" | |
478 | Define a variable with a string value, for use during preprocessing. | |
479 | You can redefine variables with @code{.ASSIGNC} at any time. | |
480 | ||
481 | @item @var{pvar} .REG (@var{register}) | |
482 | Use @code{.REG} to define a variable that represents a register. In | |
483 | particular, @var{register} is @emph{not evaluated} as an expression. | |
484 | You may use @code{.REG} at will to redefine register variables. | |
485 | @end ftable | |
486 | ||
487 | All these directives accept the variable name in the ``label'' position, | |
488 | that is at the left margin. You may specify a colon after the variable | |
489 | name if you wish; the first example above could have started @samp{eg:} | |
490 | with the same effect. | |
491 | ||
492 | @c pagebreak makes for better aesthetics---ensures macro and expansion together | |
493 | @page | |
494 | @node Macros | |
495 | @section Defining your own directives | |
496 | ||
497 | The commands @code{.MACRO} and @code{.ENDM} allow you to define macros | |
498 | that generate assembly output. You can use these macros with a syntax | |
499 | similar to built-in @sc{gasp} or assembler directives. For example, | |
500 | this definition specifies a macro @code{SUM} that adds together a range of | |
501 | consecutive registers: | |
502 | ||
503 | @cartouche | |
504 | @example | |
505 | .MACRO SUM FROM=0, TO=9 | |
506 | ! \FROM \TO | |
507 | mov r\FROM,r10 | |
508 | COUNT .ASSIGNA \FROM+1 | |
509 | .AWHILE \&COUNT LE \TO | |
510 | add r\&COUNT,r10 | |
511 | COUNT .ASSIGNA \&COUNT+1 | |
512 | .AENDW | |
513 | .ENDM | |
514 | @end example | |
515 | @end cartouche | |
516 | ||
517 | @noindent | |
518 | With that definition, @samp{SUM 0,5} generates this assembly output: | |
519 | ||
520 | @cartouche | |
521 | @example | |
522 | ! 0 5 | |
523 | mov r0,r10 | |
524 | add r1,r10 | |
525 | add r2,r10 | |
526 | add r3,r10 | |
527 | add r4,r10 | |
528 | add r5,r10 | |
529 | @end example | |
530 | @end cartouche | |
531 | ||
532 | @ftable @code | |
533 | @item .MACRO @var{macname} | |
534 | @itemx .MACRO @var{macname} @var{macargs} @dots{} | |
535 | Begin the definition of a macro called @var{macname}. If your macro | |
536 | definition requires arguments, specify their names after the macro name, | |
537 | separated by commas or spaces. You can supply a default value for any | |
538 | macro argument by following the name with @samp{=@var{deflt}}. For | |
539 | example, these are all valid @code{.MACRO} statements: | |
540 | ||
541 | @table @code | |
542 | @item .MACRO COMM | |
543 | Begin the definition of a macro called @code{COMM}, which takes no | |
544 | arguments. | |
545 | ||
546 | @item .MACRO PLUS1 P, P1 | |
547 | @itemx .MACRO PLUS1 P P1 | |
548 | Either statement begins the definition of a macro called @code{PLUS1}, | |
549 | which takes two arguments; within the macro definition, write | |
550 | @samp{\P} or @samp{\P1} to evaluate the arguments. | |
551 | ||
552 | @item .MACRO RESERVE_STR P1=0 P2 | |
553 | Begin the definition of a macro called @code{RESERVE_STR}, with two | |
554 | arguments. The first argument has a default value, but not the second. | |
555 | After the definition is complete, you can call the macro either as | |
556 | @samp{RESERVE_STR @var{a},@var{b}} (with @samp{\P1} evaluating to | |
557 | @var{a} and @samp{\P2} evaluating to @var{b}), or as @samp{RESERVE_STR | |
558 | ,@var{b}} (with @samp{\P1} evaluating as the default, in this case | |
559 | @samp{0}, and @samp{\P2} evaluating to @var{b}). | |
560 | @end table | |
561 | ||
562 | When you call a macro, you can specify the argument values either by | |
563 | position, or by keyword. For example, @samp{SUM 9,17} is equivalent to | |
564 | @samp{SUM TO=17, FROM=9}. Macro arguments are preprocessor variables | |
565 | similar to the variables you define with @samp{.ASSIGNA} or | |
566 | @samp{.ASSIGNC}; in particular, you can use them in conditionals or for | |
567 | loop control. (The only difference is the prefix you write to evaluate | |
568 | the variable: for a macro argument, write @samp{\@var{argname}}, but for | |
569 | a preprocessor variable, write @samp{\&@var{varname}}.) | |
570 | ||
571 | @item @var{name} .MACRO | |
572 | @itemx @var{name} .MACRO ( @var{macargs} @dots{} ) | |
573 | @c FIXME check: I think no error _and_ no args recognized if I use form | |
574 | @c NAME .MACRO ARG ARG | |
575 | An alternative form of introducing a macro definition: specify the macro | |
576 | name in the label position, and the arguments (if any) between | |
577 | parentheses after the name. Defaulting rules and usage work the same | |
578 | way as for the other macro definition syntax. | |
579 | ||
580 | @item .ENDM | |
581 | Mark the end of a macro definition. | |
582 | ||
583 | @item .EXITM | |
584 | Exit early from the current macro definition, @code{.AREPEAT} loop, or | |
585 | @code{.AWHILE} loop. | |
586 | ||
587 | @cindex number of macros executed | |
588 | @cindex macros, count executed | |
589 | @item \@@ | |
590 | @sc{gasp} maintains a counter of how many macros it has | |
591 | executed in this pseudo-variable; you can copy that number to your | |
592 | output with @samp{\@@}, but @emph{only within a macro definition}. | |
593 | ||
594 | @item LOCAL @var{name} [ , @dots{} ] | |
595 | @emph{Warning: @code{LOCAL} is only available if you select ``alternate | |
596 | macro syntax'' with @samp{-a} or @samp{--alternate}.} @xref{Alternate,, | |
597 | Alternate macro syntax}. | |
598 | ||
599 | Generate a string replacement for each of the @var{name} arguments, and | |
600 | replace any instances of @var{name} in each macro expansion. The | |
601 | replacement string is unique in the assembly, and different for each | |
602 | separate macro expansion. @code{LOCAL} allows you to write macros that | |
603 | define symbols, without fear of conflict between separate macro expansions. | |
604 | @end ftable | |
605 | ||
606 | @node Data | |
607 | @section Data output | |
608 | ||
609 | In assembly code, you often need to specify working areas of memory; | |
610 | depending on the application, you may want to initialize such memory or | |
611 | not. @sc{gasp} provides preprocessor directives to help you avoid | |
612 | repetitive coding for both purposes. | |
613 | ||
614 | You can use labels as usual to mark the data areas. | |
615 | ||
616 | @menu | |
617 | * Initialized:: | |
618 | * Uninitialized:: | |
619 | @end menu | |
620 | ||
621 | @node Initialized | |
622 | @subsection Initialized data | |
623 | ||
624 | These are the @sc{gasp} directives for initialized data, and the standard | |
625 | @sc{gnu} assembler directives they expand to: | |
626 | ||
627 | @ftable @code | |
628 | @item .DATA @var{expr}, @var{expr}, @dots{} | |
629 | @itemx .DATA.B @var{expr}, @var{expr}, @dots{} | |
630 | @itemx .DATA.W @var{expr}, @var{expr}, @dots{} | |
631 | @itemx .DATA.L @var{expr}, @var{expr}, @dots{} | |
632 | Evaluate arithmetic expressions @var{expr}, and emit the corresponding | |
633 | @code{as} directive (labelled with @var{lab}). The unqualified | |
634 | @code{.DATA} emits @samp{.long}; @code{.DATA.B} emits @samp{.byte}; | |
635 | @code{.DATA.W} emits @samp{.short}; and @code{.DATA.L} emits | |
636 | @samp{.long}. | |
637 | ||
638 | For example, @samp{foo .DATA 1,2,3} emits @samp{foo: .long 1,2,3}. | |
639 | ||
640 | @item .DATAB @var{repeat}, @var{expr} | |
641 | @itemx .DATAB.B @var{repeat}, @var{expr} | |
642 | @itemx .DATAB.W @var{repeat}, @var{expr} | |
643 | @itemx .DATAB.L @var{repeat}, @var{expr} | |
644 | @c FIXME! Looks like gasp accepts and ignores args after 2nd. | |
645 | Make @code{as} emit @var{repeat} copies of the value of the expression | |
646 | @var{expr} (using the @code{as} directive @code{.fill}). | |
647 | @samp{.DATAB.B} repeats one-byte values; @samp{.DATAB.W} repeats | |
648 | two-byte values; and @samp{.DATAB.L} repeats four-byte values. | |
649 | @samp{.DATAB} without a suffix repeats four-byte values, just like | |
650 | @samp{.DATAB.L}. | |
651 | ||
652 | @c FIXME! Allowing zero might be useful for edge conditions in macros. | |
653 | @var{repeat} must be an absolute expression with a positive value. | |
654 | ||
655 | @item .SDATA "@var{str}" @dots{} | |
656 | String data. Emits a concatenation of bytes, precisely as you specify | |
657 | them (in particular, @emph{nothing is added to mark the end} of the | |
658 | string). @xref{Constants,, String and numeric constants}, for details | |
659 | about how to write strings. @code{.SDATA} concatenates multiple | |
660 | arguments, making it easy to switch between string representations. You | |
661 | can use commas to separate the individual arguments for clarity, if you | |
662 | choose. | |
663 | ||
664 | @item .SDATAB @var{repeat}, "@var{str}" @dots{} | |
665 | Repeated string data. The first argument specifies how many copies of | |
666 | the string to emit; the remaining arguments specify the string, in the | |
667 | same way as the arguments to @code{.SDATA}. | |
668 | ||
669 | @item .SDATAZ "@var{str}" @dots{} | |
670 | Zero-terminated string data. Just like @code{.SDATA}, except that | |
671 | @code{.SDATAZ} writes a zero byte at the end of the string. | |
672 | ||
673 | @item .SDATAC "@var{str}" @dots{} | |
674 | Count-prefixed string data. Just like @code{.SDATA}, except that | |
675 | @sc{gasp} precedes the string with a leading one-byte count. For | |
676 | example, @samp{.SDATAC "HI"} generates @samp{.byte 2,72,73}. Since the | |
677 | count field is only one byte, you can only use @code{.SDATAC} for | |
678 | strings less than 256 bytes in length. | |
679 | @end ftable | |
680 | ||
681 | @node Uninitialized | |
682 | @subsection Uninitialized data | |
683 | ||
684 | @c FIXME! .space different on some platforms, notably HPPA. Config? | |
685 | Use the @code{.RES}, @code{.SRES}, @code{.SRESC}, and @code{.SRESZ} | |
686 | directives to reserve memory and leave it uninitialized. @sc{gasp} | |
687 | resolves these directives to appropriate calls of the @sc{gnu} | |
688 | @code{as} @code{.space} directive. | |
689 | ||
690 | @ftable @code | |
691 | @item .RES @var{count} | |
692 | @itemx .RES.B @var{count} | |
693 | @itemx .RES.W @var{count} | |
694 | @itemx .RES.L @var{count} | |
695 | Reserve room for @var{count} uninitialized elements of data. The | |
696 | suffix specifies the size of each element: @code{.RES.B} reserves | |
697 | @var{count} bytes, @code{.RES.W} reserves @var{count} pairs of bytes, | |
698 | and @code{.RES.L} reserves @var{count} quartets. @code{.RES} without a | |
699 | suffix is equivalent to @code{.RES.L}. | |
700 | ||
701 | @item .SRES @var{count} | |
702 | @itemx .SRES.B @var{count} | |
703 | @itemx .SRES.W @var{count} | |
704 | @itemx .SRES.L @var{count} | |
705 | @c FIXME! This is boring. Shouldn't it at least have a different | |
706 | @c default size? (e.g. the "S" suggests "string", for which .B | |
707 | @c would be more appropriate) | |
708 | @code{.SRES} is a synonym for @samp{.RES}. | |
709 | ||
710 | @item .SRESC @var{count} | |
711 | @itemx .SRESC.B @var{count} | |
712 | @itemx .SRESC.W @var{count} | |
713 | @itemx .SRESC.L @var{count} | |
714 | Like @code{.SRES}, but reserves space for @code{@var{count}+1} elements. | |
715 | ||
716 | @item .SRESZ @var{count} | |
717 | @itemx .SRESZ.B @var{count} | |
718 | @itemx .SRESZ.W @var{count} | |
719 | @itemx .SRESZ.L @var{count} | |
720 | Like @code{.SRES}, but reserves space for @code{@var{count}+1} elements. | |
721 | @end ftable | |
722 | ||
723 | @node Listings | |
724 | @section Assembly listing control | |
725 | ||
726 | The @sc{gasp} listing-control directives correspond to | |
727 | related @sc{gnu} @code{as} directives. | |
728 | ||
729 | @ftable @code | |
730 | @item .PRINT LIST | |
731 | @itemx .PRINT NOLIST | |
732 | Print control. This directive emits the @sc{gnu} @code{as} directive | |
733 | @code{.list} or @code{.nolist}, according to its argument. @xref{List,, | |
734 | @code{.list}, as.info, Using as}, for details on how these directives | |
735 | interact. | |
736 | ||
737 | @item .FORM LIN=@var{ln} | |
738 | @itemx .FORM COL=@var{cols} | |
739 | @itemx .FORM LIN=@var{ln} COL=@var{cols} | |
740 | Specify the page size for assembly listings: @var{ln} represents the | |
741 | number of lines, and @var{cols} the number of columns. You may specify | |
742 | either page dimension independently, or both together. If you do not | |
743 | specify the number of lines, @sc{gasp} assumes 60 lines; if you do not | |
744 | specify the number of columns, @sc{gasp} assumes 132 columns. | |
745 | (Any values you may have specified in previous instances of @code{.FORM} | |
746 | do @emph{not} carry over as defaults.) Emits the @code{.psize} | |
747 | assembler directive. | |
748 | ||
749 | @item .HEADING @var{string} | |
750 | Specify @var{string} as the title of your assembly listings. Emits | |
751 | @samp{.title "@var{string}"}. | |
752 | ||
753 | @item .PAGE | |
754 | Force a new page in assembly listings. Emits @samp{.eject}. | |
755 | @end ftable | |
756 | ||
757 | @node Other Commands | |
758 | @section Miscellaneous commands | |
759 | ||
760 | @ftable @code | |
761 | @item .ALTERNATE | |
762 | Use the alternate macro syntax henceforth in the assembly. | |
763 | @xref{Alternate,, Alternate macro syntax}. | |
764 | ||
765 | @item .ORG | |
766 | @c FIXME! This is very strange, since _GAS_ understands .org | |
767 | This command is recognized, but not yet implemented. @sc{gasp} | |
768 | generates an error message for programs that use @code{.ORG}. | |
769 | ||
770 | @item .RADIX @var{s} | |
771 | @c FIXME no test cases in testsuite/gasp | |
772 | @sc{gasp} understands numbers in any of base two, eight, ten, or | |
773 | sixteen. You can encode the base explicitly in any numeric constant | |
774 | (@pxref{Constants,, String and numeric constants}). If you write | |
775 | numbers without an explicit indication of the base, the most recent | |
776 | @samp{.RADIX @var{s}} command determines how they are interpreted. | |
777 | @var{s} is a single letter, one of the following: | |
778 | ||
779 | @table @code | |
780 | @item .RADIX B | |
781 | Base 2. | |
782 | ||
783 | @item .RADIX Q | |
784 | Base 8. | |
785 | ||
786 | @item .RADIX D | |
787 | Base 10. This is the original default radix. | |
788 | ||
789 | @item .RADIX H | |
790 | Base 16. | |
791 | @end table | |
792 | ||
793 | You may specify the argument @var{s} in lower case (any of @samp{bqdh}) | |
794 | with the same effects. | |
795 | ||
796 | @item .EXPORT @var{name} | |
797 | @itemx .GLOBAL @var{name} | |
798 | @c FIXME! No test cases in testsuite/gasp | |
799 | Declare @var{name} global (emits @samp{.global @var{name}}). The two | |
800 | directives are synonymous. | |
801 | ||
802 | @item .PROGRAM | |
803 | No effect: @sc{gasp} accepts this directive, and silently ignores it. | |
804 | ||
805 | @item .END | |
806 | Mark end of each preprocessor file. @sc{gasp} issues a warning if it | |
807 | reaches end of file without seeing this command. | |
808 | ||
809 | @item .INCLUDE "@var{str}" | |
810 | Preprocess the file named by @var{str}, as if its contents appeared | |
811 | where the @code{.INCLUDE} directive does. @sc{gasp} imposes a maximum | |
812 | limit of 30 stacked include files, as a sanity check. | |
813 | @c FIXME! Why is include depth not affected by -u? | |
814 | ||
815 | @item .ALIGN @var{size} | |
816 | @c FIXME! Why is this not utterly pointless? | |
817 | Evaluate the absolute expression @var{size}, and emit the assembly | |
818 | instruction @samp{.align @var{size}} using the result. | |
819 | @end ftable | |
820 | ||
821 | @node Syntax Details | |
822 | @section Details of the GASP syntax | |
823 | ||
824 | Since @sc{gasp} is meant to work with assembly code, its statement | |
825 | syntax has no surprises for the assembly programmer. | |
826 | ||
827 | @cindex whitespace | |
828 | @emph{Whitespace} (blanks or tabs; @emph{not} newline) is partially | |
829 | significant, in that it delimits up to three fields in a line. The | |
830 | amount of whitespace does not matter; you may line up fields in separate | |
831 | lines if you wish, but @sc{gasp} does not require that. | |
832 | ||
833 | @cindex fields of @sc{gasp} source line | |
834 | @cindex label field | |
835 | The @emph{first field}, an optional @dfn{label}, must be flush left in a | |
836 | line (with no leading whitespace) if it appears at all. You may use a | |
837 | colon after the label if you wish; @sc{gasp} neither requires the colon | |
838 | nor objects to it (but will not include it as part of the label name). | |
839 | ||
840 | @cindex directive field | |
841 | The @emph{second field}, which must appear after some whitespace, | |
842 | contains a @sc{gasp} or assembly @dfn{directive}. | |
843 | ||
844 | @cindex argument fields | |
845 | Any @emph{further fields} on a line are @dfn{arguments} to the | |
846 | directive; you can separate them from one another using either commas or | |
847 | whitespace. | |
848 | ||
849 | @menu | |
850 | * Markers:: | |
851 | * Constants:: | |
852 | * Symbols:: | |
853 | * Expressions:: | |
854 | * String Builtins:: | |
855 | @end menu | |
856 | ||
857 | @node Markers | |
858 | @subsection Special syntactic markers | |
859 | ||
860 | @sc{gasp} recognizes a few special markers: to delimit comments, to | |
861 | continue a statement on the next line, to separate symbols from other | |
862 | characters, and to copy text to the output literally. (One other | |
863 | special marker, @samp{\@@}, works only within macro definitions; | |
864 | @pxref{Macros,, Defining your own directives}.) | |
865 | ||
866 | @cindex comments | |
867 | The trailing part of any @sc{gasp} source line may be a @dfn{comment}. | |
868 | A comment begins with the first unquoted comment character (@samp{!} by | |
869 | default), or an escaped or doubled comment character (@samp{\!} or | |
870 | @samp{!!} by default), and extends to the end of a line. You can | |
871 | specify what comment character to use with the @samp{-c} option | |
872 | (@pxref{Invoking GASP,, Command Line Options}). The two kinds of | |
873 | comment markers lead to slightly different treatment: | |
874 | ||
875 | @table @code | |
876 | @item ! | |
877 | A single, un-escaped comment character generates an assembly comment in | |
878 | the @sc{gasp} output. @sc{gasp} evaluates any preprocessor variables | |
879 | (macro arguments, or variables defined with @code{.ASSIGNA} or | |
880 | @code{.ASSIGNC}) present. For example, a macro that begins like this | |
881 | ||
882 | @example | |
883 | .MACRO SUM FROM=0, TO=9 | |
884 | ! \FROM \TO | |
885 | @end example | |
886 | ||
887 | @noindent | |
888 | issues as the first line of output a comment that records the | |
889 | values you used to call the macro. | |
890 | ||
891 | @c comments, preprocessor-only | |
892 | @c preprocessor-only comments | |
893 | @c GASP-only comments | |
894 | @item \! | |
895 | @itemx !! | |
896 | Either an escaped comment character, or a double comment character, | |
897 | marks a @sc{gasp} source comment. @sc{gasp} does not copy such comments | |
898 | to the assembly output. | |
899 | @end table | |
900 | ||
901 | @cindex continuation character | |
902 | @kindex + | |
903 | To @emph{continue a statement} on the next line of the file, begin the | |
904 | second line with the character @samp{+}. | |
905 | ||
906 | @cindex literal copy to output | |
907 | @cindex copying literally to output | |
908 | @cindex preprocessing, avoiding | |
909 | @cindex avoiding preprocessing | |
910 | Occasionally you may want to prevent @sc{gasp} from preprocessing some | |
911 | particular bit of text. To @emph{copy literally} from the @sc{gasp} | |
912 | source to its output, place @samp{\(} before the string to copy, and | |
913 | @samp{)} at the end. For example, write @samp{\(\!)} if you need the | |
914 | characters @samp{\!} in your assembly output. | |
915 | ||
916 | @cindex symbol separator | |
917 | @cindex text, separating from symbols | |
918 | @cindex symbols, separating from text | |
919 | To @emph{separate a preprocessor variable} from text to appear | |
920 | immediately after its value, write a single quote (@code{'}). For | |
921 | example, @samp{.SDATA "\P'1"} writes a string built by concatenating the | |
922 | value of @code{P} and the digit @samp{1}. (You cannot achieve this by | |
923 | writing just @samp{\P1}, since @samp{P1} is itself a valid name for a | |
924 | preprocessor variable.) | |
925 | ||
926 | @node Constants | |
927 | @subsection String and numeric constants | |
928 | ||
929 | There are two ways of writing @dfn{string constants} in @sc{gasp}: as | |
930 | literal text, and by numeric byte value. Specify a string literal | |
931 | between double quotes (@code{"@var{str}"}). Specify an individual | |
932 | numeric byte value as an absolute expression between angle brackets | |
933 | (@code{<@var{expr}>}. Directives that output strings allow you to | |
934 | specify any number of either kind of value, in whatever order is | |
935 | convenient, and concatenate the result. (Alternate syntax mode | |
936 | introduces a number of alternative string notations; @pxref{Alternate,, | |
937 | Alternate macro syntax}.) | |
938 | ||
939 | @c Details of numeric notation, e.g. base prefixes | |
940 | You can write @dfn{numeric constants} either in a specific base, or in | |
941 | whatever base is currently selected (either 10, or selected by the most | |
942 | recent @code{.RADIX}). | |
943 | ||
944 | To write a number in a @emph{specific base}, use the pattern | |
945 | @code{@var{s}'@var{ddd}}: a base specifier character @var{s}, followed | |
946 | by a single quote followed by digits @var{ddd}. The base specifier | |
947 | character matches those you can specify with @code{.RADIX}: @samp{B} for | |
948 | base 2, @samp{Q} for base 8, @samp{D} for base 10, and @samp{H} for base | |
949 | 16. (You can write this character in lower case if you prefer.) | |
950 | ||
1ac57253 BE |
951 | You can write floating point constants using the same syntax recognised |
952 | by GAS @ref{Flonums,,Flonums,as,The GNU Assembler.}. A constraint is | |
953 | that these constants will be interpreted as decimal values irrespective | |
954 | of the currently selected base. | |
955 | ||
252b5132 RH |
956 | @c FIXME! What are rules for recognizing number in deflt base? Whatever |
957 | @c is left over after parsing other things?? | |
958 | ||
959 | @node Symbols | |
960 | @subsection Symbols | |
961 | ||
962 | @sc{gasp} recognizes symbol names that start with any alphabetic character, | |
963 | @samp{_}, or @samp{$}, and continue with any of the same characters or | |
964 | with digits. Label names follow the same rules. | |
965 | ||
966 | @node Expressions | |
967 | @subsection Arithmetic expressions in GASP | |
968 | ||
969 | @cindex absolute expressions | |
970 | @cindex relocatable expressions | |
971 | There are two kinds of expressions, depending on their result: | |
972 | @dfn{absolute} expressions, which resolve to a constant (that is, they | |
973 | do not involve any values unknown to @sc{gasp}), and @dfn{relocatable} | |
974 | expressions, which must reduce to the form | |
975 | ||
976 | @example | |
977 | @var{addsym}+@var{const}-@var{subsym} | |
978 | @end example | |
979 | ||
980 | @noindent | |
981 | where @var{addsym} and @var{subsym} are assembly symbols of unknown | |
982 | value, and @var{const} is a constant. | |
983 | ||
984 | Arithmetic for @sc{gasp} expressions follows very similar rules to C. | |
985 | You can use parentheses to change precedence; otherwise, arithmetic | |
986 | primitives have decreasing precedence in the order of the following | |
987 | list. | |
988 | ||
989 | @enumerate | |
990 | @item | |
991 | Single-argument @code{+} (identity), @code{-} (arithmetic opposite), or | |
992 | @code{~} (bitwise negation). @emph{The argument must be an absolute | |
993 | expression.} | |
994 | ||
995 | @item | |
996 | @code{*} (multiplication) and @code{/} (division). @emph{Both arguments | |
997 | must be absolute expressions.} | |
998 | ||
999 | @item | |
1000 | @code{+} (addition) and @code{-} (subtraction). @emph{At least one argument | |
1001 | must be absolute.} | |
1002 | @c FIXME! Actually, subtraction doesn't check for this. | |
1003 | ||
1004 | @item | |
1005 | @code{&} (bitwise and). @emph{Both arguments must be absolute.} | |
1006 | ||
1007 | @item | |
1008 | @c FIXME! I agree ~ is a better notation than ^ for xor, but is the | |
1009 | @c improvement worth differing from C? | |
1010 | @code{|} (bitwise or) and @code{~} (bitwise exclusive or; @code{^} in | |
1011 | C). @emph{Both arguments must be absolute.} | |
1012 | @end enumerate | |
1013 | ||
1014 | @node String Builtins | |
1015 | @subsection String primitives | |
1016 | ||
1017 | You can use these primitives to manipulate strings (in the argument | |
1018 | field of @sc{gasp} statements): | |
1019 | ||
1020 | @ftable @code | |
1021 | @item .LEN("@var{str}") | |
1022 | Calculate the length of string @code{"@var{str}"}, as an absolute | |
1023 | expression. For example, @samp{.RES.B .LEN("sample")} reserves six | |
1024 | bytes of memory. | |
1025 | ||
1026 | @item .INSTR("@var{string}", "@var{seg}", @var{ix}) | |
1027 | Search for the first occurrence of @var{seg} after position @var{ix} of | |
1028 | @var{string}. For example, @samp{.INSTR("ABCDEFG", "CDE", 0)} evaluates | |
1029 | to the absolute result @code{2}. | |
1030 | ||
1031 | The result is @code{-1} if @var{seg} does not occur in @var{string} | |
1032 | after position @var{ix}. | |
1033 | ||
1034 | @item .SUBSTR("@var{string}",@var{start},@var{len}) | |
1035 | The substring of @var{string} beginning at byte number @var{start} and | |
1036 | extending for @var{len} bytes. | |
1037 | @end ftable | |
1038 | ||
1039 | @node Alternate | |
1040 | @section Alternate macro syntax | |
1041 | ||
1042 | If you specify @samp{-a} or @samp{--alternate} on the @sc{gasp} command | |
1043 | line, the preprocessor uses somewhat different syntax. This syntax is | |
1044 | reminiscent of the syntax of Phar Lap macro assembler, but it | |
1045 | is @emph{not} meant to be a full emulation of Phar Lap or similar | |
1046 | assemblers. In particular, @sc{gasp} does not support directives such | |
1047 | as @code{DB} and @code{IRP}, even in alternate syntax mode. | |
1048 | ||
1049 | In particular, @samp{-a} (or @samp{--alternate}) elicits these | |
1050 | differences: | |
1051 | ||
1052 | @table @emph | |
1053 | @item Preprocessor directives | |
1054 | You can use @sc{gasp} preprocessor directives without a leading @samp{.} | |
1055 | dot. For example, you can write @samp{SDATA} with the same effect as | |
1056 | @samp{.SDATA}. | |
1057 | ||
1058 | @item LOCAL | |
1059 | One additional directive, @code{LOCAL}, is available. @xref{Macros,, | |
1060 | Defining your own directives}, for an explanation of how to use | |
1061 | @code{LOCAL}. | |
1062 | ||
1063 | @need 2000 | |
1064 | @item String delimiters | |
1065 | You can write strings delimited in these other ways besides | |
1066 | @code{"@var{string}"}: | |
1067 | ||
1068 | @table @code | |
1069 | @item '@var{string}' | |
1070 | You can delimit strings with single-quote charaters. | |
1071 | ||
1072 | @item <@var{string}> | |
1073 | You can delimit strings with matching angle brackets. | |
1074 | @end table | |
1075 | ||
1076 | @item single-character string escape | |
1077 | To include any single character literally in a string (even if the | |
1078 | character would otherwise have some special meaning), you can prefix the | |
1079 | character with @samp{!} (an exclamation mark). For example, you can | |
1080 | write @samp{<4.3 !> 5.4!!>} to get the literal text @samp{4.3 > 5.4!}. | |
1081 | ||
1082 | @item Expression results as strings | |
1083 | You can write @samp{%@var{expr}} to evaluate the expression @var{expr} | |
1084 | and use the result as a string. | |
1085 | @end table | |
1086 | ||
cf055d54 NC |
1087 | @node GNU Free Documentation License |
1088 | @chapter GNU Free Documentation License | |
1089 | ||
1090 | GNU Free Documentation License | |
1091 | ||
1092 | Version 1.1, March 2000 | |
1093 | ||
1094 | Copyright (C) 2000 Free Software Foundation, Inc. | |
1095 | 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA | |
1096 | ||
1097 | Everyone is permitted to copy and distribute verbatim copies | |
1098 | of this license document, but changing it is not allowed. | |
1099 | ||
1100 | ||
1101 | 0. PREAMBLE | |
1102 | ||
1103 | The purpose of this License is to make a manual, textbook, or other | |
1104 | written document "free" in the sense of freedom: to assure everyone | |
1105 | the effective freedom to copy and redistribute it, with or without | |
1106 | modifying it, either commercially or noncommercially. Secondarily, | |
1107 | this License preserves for the author and publisher a way to get | |
1108 | credit for their work, while not being considered responsible for | |
1109 | modifications made by others. | |
1110 | ||
1111 | This License is a kind of "copyleft", which means that derivative | |
1112 | works of the document must themselves be free in the same sense. It | |
1113 | complements the GNU General Public License, which is a copyleft | |
1114 | license designed for free software. | |
1115 | ||
1116 | We have designed this License in order to use it for manuals for free | |
1117 | software, because free software needs free documentation: a free | |
1118 | program should come with manuals providing the same freedoms that the | |
1119 | software does. But this License is not limited to software manuals; | |
1120 | it can be used for any textual work, regardless of subject matter or | |
1121 | whether it is published as a printed book. We recommend this License | |
1122 | principally for works whose purpose is instruction or reference. | |
1123 | ||
1124 | ||
1125 | 1. APPLICABILITY AND DEFINITIONS | |
1126 | ||
1127 | This License applies to any manual or other work that contains a | |
1128 | notice placed by the copyright holder saying it can be distributed | |
1129 | under the terms of this License. The "Document", below, refers to any | |
1130 | such manual or work. Any member of the public is a licensee, and is | |
1131 | addressed as "you". | |
1132 | ||
1133 | A "Modified Version" of the Document means any work containing the | |
1134 | Document or a portion of it, either copied verbatim, or with | |
1135 | modifications and/or translated into another language. | |
1136 | ||
1137 | A "Secondary Section" is a named appendix or a front-matter section of | |
1138 | the Document that deals exclusively with the relationship of the | |
1139 | publishers or authors of the Document to the Document's overall subject | |
1140 | (or to related matters) and contains nothing that could fall directly | |
1141 | within that overall subject. (For example, if the Document is in part a | |
1142 | textbook of mathematics, a Secondary Section may not explain any | |
1143 | mathematics.) The relationship could be a matter of historical | |
1144 | connection with the subject or with related matters, or of legal, | |
1145 | commercial, philosophical, ethical or political position regarding | |
1146 | them. | |
1147 | ||
1148 | The "Invariant Sections" are certain Secondary Sections whose titles | |
1149 | are designated, as being those of Invariant Sections, in the notice | |
1150 | that says that the Document is released under this License. | |
1151 | ||
1152 | The "Cover Texts" are certain short passages of text that are listed, | |
1153 | as Front-Cover Texts or Back-Cover Texts, in the notice that says that | |
1154 | the Document is released under this License. | |
1155 | ||
1156 | A "Transparent" copy of the Document means a machine-readable copy, | |
1157 | represented in a format whose specification is available to the | |
1158 | general public, whose contents can be viewed and edited directly and | |
1159 | straightforwardly with generic text editors or (for images composed of | |
1160 | pixels) generic paint programs or (for drawings) some widely available | |
1161 | drawing editor, and that is suitable for input to text formatters or | |
1162 | for automatic translation to a variety of formats suitable for input | |
1163 | to text formatters. A copy made in an otherwise Transparent file | |
1164 | format whose markup has been designed to thwart or discourage | |
1165 | subsequent modification by readers is not Transparent. A copy that is | |
1166 | not "Transparent" is called "Opaque". | |
1167 | ||
1168 | Examples of suitable formats for Transparent copies include plain | |
1169 | ASCII without markup, Texinfo input format, LaTeX input format, SGML | |
1170 | or XML using a publicly available DTD, and standard-conforming simple | |
1171 | HTML designed for human modification. Opaque formats include | |
1172 | PostScript, PDF, proprietary formats that can be read and edited only | |
1173 | by proprietary word processors, SGML or XML for which the DTD and/or | |
1174 | processing tools are not generally available, and the | |
1175 | machine-generated HTML produced by some word processors for output | |
1176 | purposes only. | |
1177 | ||
1178 | The "Title Page" means, for a printed book, the title page itself, | |
1179 | plus such following pages as are needed to hold, legibly, the material | |
1180 | this License requires to appear in the title page. For works in | |
1181 | formats which do not have any title page as such, "Title Page" means | |
1182 | the text near the most prominent appearance of the work's title, | |
1183 | preceding the beginning of the body of the text. | |
1184 | ||
1185 | ||
1186 | 2. VERBATIM COPYING | |
1187 | ||
1188 | You may copy and distribute the Document in any medium, either | |
1189 | commercially or noncommercially, provided that this License, the | |
1190 | copyright notices, and the license notice saying this License applies | |
1191 | to the Document are reproduced in all copies, and that you add no other | |
1192 | conditions whatsoever to those of this License. You may not use | |
1193 | technical measures to obstruct or control the reading or further | |
1194 | copying of the copies you make or distribute. However, you may accept | |
1195 | compensation in exchange for copies. If you distribute a large enough | |
1196 | number of copies you must also follow the conditions in section 3. | |
1197 | ||
1198 | You may also lend copies, under the same conditions stated above, and | |
1199 | you may publicly display copies. | |
1200 | ||
1201 | ||
1202 | 3. COPYING IN QUANTITY | |
1203 | ||
1204 | If you publish printed copies of the Document numbering more than 100, | |
1205 | and the Document's license notice requires Cover Texts, you must enclose | |
1206 | the copies in covers that carry, clearly and legibly, all these Cover | |
1207 | Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on | |
1208 | the back cover. Both covers must also clearly and legibly identify | |
1209 | you as the publisher of these copies. The front cover must present | |
1210 | the full title with all words of the title equally prominent and | |
1211 | visible. You may add other material on the covers in addition. | |
1212 | Copying with changes limited to the covers, as long as they preserve | |
1213 | the title of the Document and satisfy these conditions, can be treated | |
1214 | as verbatim copying in other respects. | |
1215 | ||
1216 | If the required texts for either cover are too voluminous to fit | |
1217 | legibly, you should put the first ones listed (as many as fit | |
1218 | reasonably) on the actual cover, and continue the rest onto adjacent | |
1219 | pages. | |
1220 | ||
1221 | If you publish or distribute Opaque copies of the Document numbering | |
1222 | more than 100, you must either include a machine-readable Transparent | |
1223 | copy along with each Opaque copy, or state in or with each Opaque copy | |
1224 | a publicly-accessible computer-network location containing a complete | |
1225 | Transparent copy of the Document, free of added material, which the | |
1226 | general network-using public has access to download anonymously at no | |
1227 | charge using public-standard network protocols. If you use the latter | |
1228 | option, you must take reasonably prudent steps, when you begin | |
1229 | distribution of Opaque copies in quantity, to ensure that this | |
1230 | Transparent copy will remain thus accessible at the stated location | |
1231 | until at least one year after the last time you distribute an Opaque | |
1232 | copy (directly or through your agents or retailers) of that edition to | |
1233 | the public. | |
1234 | ||
1235 | It is requested, but not required, that you contact the authors of the | |
1236 | Document well before redistributing any large number of copies, to give | |
1237 | them a chance to provide you with an updated version of the Document. | |
1238 | ||
1239 | ||
1240 | 4. MODIFICATIONS | |
1241 | ||
1242 | You may copy and distribute a Modified Version of the Document under | |
1243 | the conditions of sections 2 and 3 above, provided that you release | |
1244 | the Modified Version under precisely this License, with the Modified | |
1245 | Version filling the role of the Document, thus licensing distribution | |
1246 | and modification of the Modified Version to whoever possesses a copy | |
1247 | of it. In addition, you must do these things in the Modified Version: | |
1248 | ||
1249 | A. Use in the Title Page (and on the covers, if any) a title distinct | |
1250 | from that of the Document, and from those of previous versions | |
1251 | (which should, if there were any, be listed in the History section | |
1252 | of the Document). You may use the same title as a previous version | |
1253 | if the original publisher of that version gives permission. | |
1254 | B. List on the Title Page, as authors, one or more persons or entities | |
1255 | responsible for authorship of the modifications in the Modified | |
1256 | Version, together with at least five of the principal authors of the | |
1257 | Document (all of its principal authors, if it has less than five). | |
1258 | C. State on the Title page the name of the publisher of the | |
1259 | Modified Version, as the publisher. | |
1260 | D. Preserve all the copyright notices of the Document. | |
1261 | E. Add an appropriate copyright notice for your modifications | |
1262 | adjacent to the other copyright notices. | |
1263 | F. Include, immediately after the copyright notices, a license notice | |
1264 | giving the public permission to use the Modified Version under the | |
1265 | terms of this License, in the form shown in the Addendum below. | |
1266 | G. Preserve in that license notice the full lists of Invariant Sections | |
1267 | and required Cover Texts given in the Document's license notice. | |
1268 | H. Include an unaltered copy of this License. | |
1269 | I. Preserve the section entitled "History", and its title, and add to | |
1270 | it an item stating at least the title, year, new authors, and | |
1271 | publisher of the Modified Version as given on the Title Page. If | |
1272 | there is no section entitled "History" in the Document, create one | |
1273 | stating the title, year, authors, and publisher of the Document as | |
1274 | given on its Title Page, then add an item describing the Modified | |
1275 | Version as stated in the previous sentence. | |
1276 | J. Preserve the network location, if any, given in the Document for | |
1277 | public access to a Transparent copy of the Document, and likewise | |
1278 | the network locations given in the Document for previous versions | |
1279 | it was based on. These may be placed in the "History" section. | |
1280 | You may omit a network location for a work that was published at | |
1281 | least four years before the Document itself, or if the original | |
1282 | publisher of the version it refers to gives permission. | |
1283 | K. In any section entitled "Acknowledgements" or "Dedications", | |
1284 | preserve the section's title, and preserve in the section all the | |
1285 | substance and tone of each of the contributor acknowledgements | |
1286 | and/or dedications given therein. | |
1287 | L. Preserve all the Invariant Sections of the Document, | |
1288 | unaltered in their text and in their titles. Section numbers | |
1289 | or the equivalent are not considered part of the section titles. | |
1290 | M. Delete any section entitled "Endorsements". Such a section | |
1291 | may not be included in the Modified Version. | |
1292 | N. Do not retitle any existing section as "Endorsements" | |
1293 | or to conflict in title with any Invariant Section. | |
1294 | ||
1295 | If the Modified Version includes new front-matter sections or | |
1296 | appendices that qualify as Secondary Sections and contain no material | |
1297 | copied from the Document, you may at your option designate some or all | |
1298 | of these sections as invariant. To do this, add their titles to the | |
1299 | list of Invariant Sections in the Modified Version's license notice. | |
1300 | These titles must be distinct from any other section titles. | |
1301 | ||
1302 | You may add a section entitled "Endorsements", provided it contains | |
1303 | nothing but endorsements of your Modified Version by various | |
1304 | parties--for example, statements of peer review or that the text has | |
1305 | been approved by an organization as the authoritative definition of a | |
1306 | standard. | |
1307 | ||
1308 | You may add a passage of up to five words as a Front-Cover Text, and a | |
1309 | passage of up to 25 words as a Back-Cover Text, to the end of the list | |
1310 | of Cover Texts in the Modified Version. Only one passage of | |
1311 | Front-Cover Text and one of Back-Cover Text may be added by (or | |
1312 | through arrangements made by) any one entity. If the Document already | |
1313 | includes a cover text for the same cover, previously added by you or | |
1314 | by arrangement made by the same entity you are acting on behalf of, | |
1315 | you may not add another; but you may replace the old one, on explicit | |
1316 | permission from the previous publisher that added the old one. | |
1317 | ||
1318 | The author(s) and publisher(s) of the Document do not by this License | |
1319 | give permission to use their names for publicity for or to assert or | |
1320 | imply endorsement of any Modified Version. | |
1321 | ||
1322 | ||
1323 | 5. COMBINING DOCUMENTS | |
1324 | ||
1325 | You may combine the Document with other documents released under this | |
1326 | License, under the terms defined in section 4 above for modified | |
1327 | versions, provided that you include in the combination all of the | |
1328 | Invariant Sections of all of the original documents, unmodified, and | |
1329 | list them all as Invariant Sections of your combined work in its | |
1330 | license notice. | |
1331 | ||
1332 | The combined work need only contain one copy of this License, and | |
1333 | multiple identical Invariant Sections may be replaced with a single | |
1334 | copy. If there are multiple Invariant Sections with the same name but | |
1335 | different contents, make the title of each such section unique by | |
1336 | adding at the end of it, in parentheses, the name of the original | |
1337 | author or publisher of that section if known, or else a unique number. | |
1338 | Make the same adjustment to the section titles in the list of | |
1339 | Invariant Sections in the license notice of the combined work. | |
1340 | ||
1341 | In the combination, you must combine any sections entitled "History" | |
1342 | in the various original documents, forming one section entitled | |
1343 | "History"; likewise combine any sections entitled "Acknowledgements", | |
1344 | and any sections entitled "Dedications". You must delete all sections | |
1345 | entitled "Endorsements." | |
1346 | ||
1347 | ||
1348 | 6. COLLECTIONS OF DOCUMENTS | |
1349 | ||
1350 | You may make a collection consisting of the Document and other documents | |
1351 | released under this License, and replace the individual copies of this | |
1352 | License in the various documents with a single copy that is included in | |
1353 | the collection, provided that you follow the rules of this License for | |
1354 | verbatim copying of each of the documents in all other respects. | |
1355 | ||
1356 | You may extract a single document from such a collection, and distribute | |
1357 | it individually under this License, provided you insert a copy of this | |
1358 | License into the extracted document, and follow this License in all | |
1359 | other respects regarding verbatim copying of that document. | |
1360 | ||
1361 | ||
1362 | 7. AGGREGATION WITH INDEPENDENT WORKS | |
1363 | ||
1364 | A compilation of the Document or its derivatives with other separate | |
1365 | and independent documents or works, in or on a volume of a storage or | |
1366 | distribution medium, does not as a whole count as a Modified Version | |
1367 | of the Document, provided no compilation copyright is claimed for the | |
1368 | compilation. Such a compilation is called an "aggregate", and this | |
1369 | License does not apply to the other self-contained works thus compiled | |
1370 | with the Document, on account of their being thus compiled, if they | |
1371 | are not themselves derivative works of the Document. | |
1372 | ||
1373 | If the Cover Text requirement of section 3 is applicable to these | |
1374 | copies of the Document, then if the Document is less than one quarter | |
1375 | of the entire aggregate, the Document's Cover Texts may be placed on | |
1376 | covers that surround only the Document within the aggregate. | |
1377 | Otherwise they must appear on covers around the whole aggregate. | |
1378 | ||
1379 | ||
1380 | 8. TRANSLATION | |
1381 | ||
1382 | Translation is considered a kind of modification, so you may | |
1383 | distribute translations of the Document under the terms of section 4. | |
1384 | Replacing Invariant Sections with translations requires special | |
1385 | permission from their copyright holders, but you may include | |
1386 | translations of some or all Invariant Sections in addition to the | |
1387 | original versions of these Invariant Sections. You may include a | |
1388 | translation of this License provided that you also include the | |
1389 | original English version of this License. In case of a disagreement | |
1390 | between the translation and the original English version of this | |
1391 | License, the original English version will prevail. | |
1392 | ||
1393 | ||
1394 | 9. TERMINATION | |
1395 | ||
1396 | You may not copy, modify, sublicense, or distribute the Document except | |
1397 | as expressly provided for under this License. Any other attempt to | |
1398 | copy, modify, sublicense or distribute the Document is void, and will | |
1399 | automatically terminate your rights under this License. However, | |
1400 | parties who have received copies, or rights, from you under this | |
1401 | License will not have their licenses terminated so long as such | |
1402 | parties remain in full compliance. | |
1403 | ||
1404 | ||
1405 | 10. FUTURE REVISIONS OF THIS LICENSE | |
1406 | ||
1407 | The Free Software Foundation may publish new, revised versions | |
1408 | of the GNU Free Documentation License from time to time. Such new | |
1409 | versions will be similar in spirit to the present version, but may | |
1410 | differ in detail to address new problems or concerns. See | |
1411 | http://www.gnu.org/copyleft/. | |
1412 | ||
1413 | Each version of the License is given a distinguishing version number. | |
1414 | If the Document specifies that a particular numbered version of this | |
1415 | License "or any later version" applies to it, you have the option of | |
1416 | following the terms and conditions either of that specified version or | |
1417 | of any later version that has been published (not as a draft) by the | |
1418 | Free Software Foundation. If the Document does not specify a version | |
1419 | number of this License, you may choose any version ever published (not | |
1420 | as a draft) by the Free Software Foundation. | |
1421 | ||
1422 | ||
1423 | ADDENDUM: How to use this License for your documents | |
1424 | ||
1425 | To use this License in a document you have written, include a copy of | |
1426 | the License in the document and put the following copyright and | |
1427 | license notices just after the title page: | |
1428 | ||
1429 | @smallexample | |
1430 | Copyright (c) YEAR YOUR NAME. | |
1431 | Permission is granted to copy, distribute and/or modify this document | |
1432 | under the terms of the GNU Free Documentation License, Version 1.1 | |
1433 | or any later version published by the Free Software Foundation; | |
1434 | with the Invariant Sections being LIST THEIR TITLES, with the | |
1435 | Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST. | |
1436 | A copy of the license is included in the section entitled "GNU | |
1437 | Free Documentation License". | |
1438 | @end smallexample | |
1439 | ||
1440 | If you have no Invariant Sections, write "with no Invariant Sections" | |
1441 | instead of saying which ones are invariant. If you have no | |
1442 | Front-Cover Texts, write "no Front-Cover Texts" instead of | |
1443 | "Front-Cover Texts being LIST"; likewise for Back-Cover Texts. | |
1444 | ||
1445 | If your document contains nontrivial examples of program code, we | |
1446 | recommend releasing these examples in parallel under your choice of | |
1447 | free software license, such as the GNU General Public License, | |
1448 | to permit their use in free software. | |
1449 | ||
252b5132 RH |
1450 | @node Index |
1451 | @unnumbered Index | |
1452 | ||
1453 | @printindex cp | |
1454 | ||
1455 | @contents | |
1456 | @bye |