1 \input texinfo @c -*- Texinfo -*-
5 @c This file documents the assembly preprocessor "GASP"
7 @c Copyright (c) 1994 Free Software Foundation, Inc.
9 @c This text may be freely distributed under the terms of the GNU
10 @c General Public License.
15 * gasp: (gasp). The GNU Assembler Preprocessor
23 @setchapternewpage odd
29 @title GASP, an assembly preprocessor
30 @subtitle for GASP version 1
32 @subtitle January 1994
37 {\parskip=0pt \hfill Cygnus Support\par
41 @vskip 0pt plus 1filll
42 Copyright @copyright{} 1994 Free Software Foundation, Inc.
44 Permission is granted to make and distribute verbatim copies of
45 this manual provided the copyright notice and this permission notice
46 are preserved on all copies.
48 Permission is granted to copy and distribute modified versions of this
49 manual under the conditions for verbatim copying, provided also that
50 the entire resulting derived work is distributed under the terms of a
51 permission notice identical to this one.
53 Permission is granted to copy and distribute translations of this manual
54 into another language, under the above conditions for modified versions.
58 Copyright @copyright{} 1994 Free Software Foundation, Inc.
60 Permission is granted to make and distribute verbatim copies of
61 this manual provided the copyright notice and this permission notice
62 are preserved on all copies.
65 Permission is granted to process this file through TeX and print the
66 results, provided the printed document carries a copying permission
67 notice identical to this one except for the removal of this paragraph
68 (this paragraph not being relevant to the printed manual).
71 Permission is granted to copy and distribute modified versions of this
72 manual under the conditions for verbatim copying, provided also that
73 the entire resulting derived work is distributed under the terms of a
74 permission notice identical to this one.
76 Permission is granted to copy and distribute translations of this manual
77 into another language, under the above conditions for modified versions.
82 GASP is a preprocessor for assembly programs.
84 This file describes version 1 of GASP.
86 Steve Chamberlain wrote GASP; Roland Pesch wrote this manual.
89 * Overview:: What is GASP?
90 * Invoking GASP:: Command line options.
91 * Commands:: Preprocessor commands.
97 @chapter What is GASP?
99 The primary purpose of the @sc{gnu} assembler is to assemble the output of
100 other programs---notably compilers. When you have to hand-code
101 specialized routines in assembly, that means the @sc{gnu} assembler is
102 an unfriendly processor: it has no directives for macros, conditionals,
103 or many other conveniences that you might expect.
105 In some cases you can simply use the C preprocessor, or a generalized
106 preprocessor like @sc{m4}; but this can be awkward, since none of these
107 things are designed with assembly in mind.
109 @sc{gasp} fills this need. It is expressly designed to provide the
110 facilities you need with hand-coded assembly code. Implementing it as a
111 preprocessor, rather than part of the assembler, allows the maximum
112 flexibility: you can use it with hand-coded assembly, without paying a
113 penalty of added complexity in the assembler you use for compiler
116 Here is a small example to give the flavor of @sc{gasp}. This input to
121 .MACRO saveregs from=8 to=14
124 .AWHILE \&count LE \to
126 count .ASSIGNA \&count + 1
132 bar: mov #H'dead+10,r0
133 foo .SDATAC "hello"<10>
139 generates this assembly program:
148 bar: mov #57005+10,r0
149 foo: .byte 6,104,101,108,108,111,10
154 @chapter Command Line Options
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:
160 @c FIXME! GASP filename suffix convention?
162 $ gasp prog.asm | as -o prog.o
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.
170 gasp [ -c ] [ -o @var{outfile} ] [ -p ] [ -s ] [ -u ]
174 @c FIXME!! Aren't all GNU programs supposed to have a -V or --version
175 @c option, that reports version info and exits?
178 @item @var{infile} @dots{}
179 @c FIXME! Why not stdin as default infile?
180 The input file names. You must specify at least one input file; if you
181 specify more, @sc{gasp} preprocesses them all, concatenating the output
182 in the order you list the @var{infile} arguments.
184 Mark the end of each input file with the preprocessor command
185 @code{.END}. @xref{Other Commands,, Miscellaneous commands}.
188 @c FIXME! Shouldn't there be an option to set the prefix char so it can
189 @c always be the comment char for whatever assembly version we have?
190 Copy the source lines to the output file. Use this option
191 to see the effect of each preprocessor line on the @sc{gasp} output.
192 @sc{gasp} marks the lines copied from the source file with @samp{!} at
193 the beginning, to help you distinguish them from the rest of the output.
195 @item -o @var{outfile}
196 Write the output in a file called @var{outfile}. If you do not use the
197 @samp{-o} option, @sc{gasp} writes its output on the standard output
201 Print line numbers. @sc{gasp} obeys this option @emph{only} if you also
202 specify @samp{-c} to copy source lines to its output. With @samp{-c
203 -p}, @sc{gasp} displays the line number of each source line copied
204 (immediately after the @samp{!} that marks source lines in the output).
207 Show statistics. In this version of @sc{gasp}, this option produces
208 statistics about the string buffers that @sc{gasp} allocates internally.
209 For each defined buffersize @var{s}, @sc{gasp} shows the number of
210 strings @var{n} that it allocated, with a line like this:
213 strings size @var{s} : @var{n}
217 @sc{gasp} displays these statistics on the standard error stream, when
221 Bypass ``unreasonable expansion'' limit. Since you can define @sc{gasp}
222 macros inside other macro definitions, the preprocessor normally
223 includes a sanity check. If your program requires more than 1,000
224 nested expansions, @sc{gasp} normally exits with an error message. Use
225 this option to turn off this check, allowing unlimited nested
230 @chapter Preprocessor Commands
232 @sc{gasp} commands have a straightforward syntax that fits in well with
233 assembly conventions. In general, a command extends for a line, and may
234 have up to three fields: an optional label, the command itself, and
235 optional arguments to the command. You can write commands in upper or
236 lower case, though this manual shows them in upper case. @xref{Syntax
237 Details,, Details of the GASP syntax}, for more information.
251 @section Conditional assembly
253 The conditional-assembly directives allow you to include or exclude
254 portions of an assembly depending on how a pair of expressions, or a
255 pair of strings, compare.
257 The overall structure of conditionals is familiar from many other
258 contexts. @code{.AIF} marks the start of a conditional, and precedes
259 assembly for the case when the condition is true. An optional
260 @code{.AELSE} precedes assembly for the converse case, and an
261 @code{.AENDI} marks the end of the condition.
263 @c FIXME! Why doesn't -u turn off this check?
264 You may nest conditionals up to a depth of 100; @sc{gasp} rejects
265 nesting beyond that, because it may indicate a bug in your macro
268 @c FIXME! Why isn't there something like cpp's -D option? Conditionals
269 @c would be much more useful if there were.
270 Conditionals are primarily useful inside macro definitions, where you
271 often need different effects depending on argument values.
272 @xref{Macros,, Defining your own directives}, for details about defining
276 @item .AIF @var{expra} @var{cmp} @var{exprb}
277 @itemx .AIF "@var{stra}" @var{cmp} "@var{strb}"
279 The governing condition goes on the same line as the @code{.AIF}
280 preprocessor command. You may compare either two strings, or two
283 When you compare strings, only two conditional @var{cmp} comparison
284 operators are available: @samp{EQ} (true if @var{stra} and @var{strb}
285 are identical), and @samp{NE} (the converse).
287 When you compare two expressions, @emph{both expressions must be
288 absolute} (@pxref{Expressions,, Arithmetic expressions in GASP}). You
289 can use these @var{cmp} comparison operators with expressions:
293 Are @var{expra} and @var{exprb} equal? (For strings, are @var{stra} and
294 @var{strb} identical?)
297 Are @var{expra} and @var{exprb} different? (For strings, are @var{stra}
298 and @var{strb} different?
301 Is @var{expra} less than @var{exprb}? (Not allowed for strings.)
304 Is @var{expra} less than or equal to @var{exprb}? (Not allowed for strings.)
307 Is @var{expra} greater than @var{exprb}? (Not allowed for strings.)
310 Is @var{expra} greater than or equal to @var{exprb}? (Not allowed for
315 Marks the start of assembly code to be included if the condition fails.
316 Optional, and only allowed within a conditional (between @code{.AIF} and
320 Marks the end of a conditional assembly.
324 @section Repetitive sections of assembly
326 Two preprocessor directives allow you to repeatedly issue copies of the
327 same block of assembly code.
330 @item .AREPEAT @var{aexp}
332 If you simply need to repeat the same block of assembly over and over a
333 fixed number of times, sandwich one instance of the repeated block
334 between @code{.AREPEAT} and @code{.AENDR}. Specify the number of
335 copies as @var{aexp} (which must be an absolute expression). For
336 example, this repeats two assembly statements three times in succession:
347 @item .AWHILE @var{expra} @var{cmp} @var{exprb}
349 @itemx .AWHILE @var{stra} @var{cmp} @var{strb}
351 To repeat a block of assembly depending on a conditional test, rather
352 than repeating it for a specific number of times, use @code{.AWHILE}.
353 @code{.AENDW} marks the end of the repeated block. The conditional
354 comparison works exactly the same way as for @code{.AIF}, with the same
355 comparison operators (@pxref{Conditionals,, Conditional assembly}).
357 Since the terms of the comparison must be absolute expression,
358 @code{.AWHILE} is primarily useful within macros. @xref{Macros,,
359 Defining your own directives}.
362 @cindex loops, breaking out of
363 @cindex breaking out of loops
364 You can use the @code{.EXITM} preprocessor directive to break out of
365 loops early (as well as to break out of macros). @xref{Macros,,
366 Defining your own directives}.
369 @section Preprocessor variables
371 You can use variables in @sc{gasp} to represent strings, registers, or
372 the results of expressions.
374 You must distinguish two kinds of variables:
377 Variables defined with @code{.EQU} or @code{.ASSIGN}. To evaluate this
378 kind of variable in your assembly output, simply mention its name. For
379 example, these two lines define and use a variable @samp{eg}:
389 @emph{Do not use} this kind of variable in conditional expressions or
390 while loops; @sc{gasp} only evaluates these variables when writing
394 Variables for use during preprocessing. You can define these
395 with @code{.ASSIGNC} or @code{.ASSIGNA}. To evaluate this
396 kind of variable, write @samp{\&} before the variable name; for example,
408 @sc{gasp} treats macro arguments almost the same way, but to evaluate
409 them you use the prefix @samp{\} rather than @samp{\&}.
410 @xref{Macros,, Defining your own directives}.
414 @item @var{pvar} .EQU @var{expr}
415 @c FIXME! Anything to beware of re GAS directive of same name?
416 Assign preprocessor variable @var{pvar} the value of the expression
417 @var{expr}. There are no restrictions on redefinition; use @samp{.EQU}
418 with the same @var{pvar} as often as you find it convenient.
420 @item @var{pvar} .ASSIGN @var{expr}
421 Almost the same as @code{.EQU}, save that you may not redefine
422 @var{pvar} using @code{.ASSIGN} once it has a value.
423 @c FIXME!! Supposed to work this way, apparently, but on 9feb94 works
426 @item @var{pvar} .ASSIGNA @var{aexpr}
427 Define a variable with a numeric value, for use during preprocessing.
428 @var{aexpr} must be an absolute expression. You can redefine variables
429 with @code{.ASSIGNA} at any time.
431 @item @var{pvar} .ASSIGNC "@var{str}"
432 Define a variable with a string value, for use during preprocessing.
433 You can redefine variables with @code{.ASSIGNC} at any time.
435 @item @var{pvar} .REG (@var{register})
436 Use @code{.REG} to define a variable that represents a register. In
437 particular, @var{register} is @emph{not evaluated} as an expression.
438 You may use @code{.REG} at will to redefine register variables.
441 All these directives accept the variable name in the ``label'' position,
442 that is at the left margin. You may specify a colon after the variable
443 name if you wish; the first example above could have started @samp{eg:}
444 with the same effect.
446 @c pagebreak makes for better aesthetics---ensures macro and expansion together
449 @section Defining your own directives
451 The commands @code{.MACRO} and @code{.ENDM} allow you to define macros
452 that generate assembly output. You can use these macros with a syntax
453 similar to built-in @sc{gasp} or assembler directives. For example,
454 this definition specifies a macro @code{SUM} that adds together a range of
455 consecutive registers:
459 .MACRO SUM FROM=0, TO=9
462 COUNT .ASSIGNA \FROM+1
463 .AWHILE \&COUNT LE \TO
465 COUNT .ASSIGNA \&COUNT+1
472 With that definition, @samp{SUM 0,5} generates this assembly output:
487 @item .MACRO @var{macname}
488 @itemx .MACRO @var{macname} @var{macargs} @dots{}
489 Begin the definition of a macro called @var{macname}. If your macro
490 definition requires arguments, specify their names after the macro name,
491 separated by commas or spaces. You can supply a default value for any
492 macro argument by following the name with @samp{=@var{deflt}}. For
493 example, these are all valid @code{.MACRO} statements:
497 Begin the definition of a macro called @code{COMM}, which takes no
500 @item .MACRO PLUS1 P, P1
501 @itemx .MACRO PLUS1 P P1
502 Either statement begins the definition of a macro called @code{PLUS1},
503 which takes two arguments; within the macro definition, write
504 @samp{\P} or @samp{\P1} to evaluate the arguments.
506 @item .MACRO RESERVE_STR P1=0 P2
507 Begin the definition of a macro called @code{RESERVE_STR}, with two
508 arguments. The first argument has a default value, but not the second.
509 After the definition is complete, you can call the macro either as
510 @samp{RESERVE_STR @var{a},@var{b}} (with @samp{\P1} evaluating to
511 @var{a} and @samp{\P2} evaluating to @var{b}), or as @samp{RESERVE_STR
512 ,@var{b}} (with @samp{\P1} evaluating as the default, in this case
513 @samp{0}, and @samp{\P2} evaluating to @var{b}).
516 When you call a macro, you can specify the argument values either by
517 position, or by keyword. For example, @samp{SUM 9,17} is equivalent to
518 @samp{SUM TO=17, FROM=9}. Macro arguments are preprocessor variables
519 similar to the variables you define with @samp{.ASSIGNA} or
520 @samp{.ASSIGNC}; in particular, you can use them in conditionals or for
521 loop control. (The only difference is the prefix you write to evaluate
522 the variable: for a macro argument, write @samp{\@var{argname}}, but for
523 a preprocessor variable, write @samp{\&@var{varname}}.)
525 @item @var{name} .MACRO
526 @itemx @var{name} .MACRO ( @var{macargs} @dots{} )
527 @c FIXME check: I think no error _and_ no args recognized if I use form
528 @c NAME .MACRO ARG ARG
529 An alternative form of introducing a macro definition: specify the macro
530 name in the label position, and the arguments (if any) between
531 parentheses after the name. Defaulting rules and usage work the same
532 way as for the alternate macro definition syntax.
535 Mark the end of a macro definition.
538 Exit early from the current macro definition, @code{.AREPEAT} loop, or
541 @cindex number of macros executed
542 @cindex macros, count executed
544 @sc{gasp} maintains a counter of how many macros it has
545 executed in this pseudo-variable; you can copy that number to your
546 output with @samp{\@@}, but @emph{only within a macro definition}.
552 In assembly code, you often need to specify working areas of memory;
553 depending on the application, you may want to initialize such memory or
554 not. @sc{gasp} provides preprocessor directives to help you avoid
555 repetitive coding for both purposes.
557 You can use labels as usual to mark the data areas.
565 @subsection Initialized data
567 These are the @sc{gasp} directives for initialized data, and the standard
568 @sc{gnu} assembler directives they expand to:
571 @item .DATA @var{expr}, @var{expr}, @dots{}
572 @itemx .DATA.B @var{expr}, @var{expr}, @dots{}
573 @itemx .DATA.W @var{expr}, @var{expr}, @dots{}
574 @itemx .DATA.L @var{expr}, @var{expr}, @dots{}
575 Evaluate arithmetic expressions @var{expr}, and emit the corresponding
576 @code{as} directive (labelled with @var{lab}). The unqualified
577 @code{.DATA} emits @samp{.long}; @code{.DATA.B} emits @samp{.byte};
578 @code{.DATA.W} emits @samp{.short}; and @code{.DATA.L} emits
581 For example, @samp{foo .DATA 1,2,3} emits @samp{foo: .long 1,2,3}.
583 @item .DATAB @var{repeat}, @var{expr}
584 @itemx .DATAB.B @var{repeat}, @var{expr}
585 @itemx .DATAB.W @var{repeat}, @var{expr}
586 @itemx .DATAB.L @var{repeat}, @var{expr}
587 @c FIXME! Looks like gasp accepts and ignores args after 2nd.
588 Make @code{as} emit @var{repeat} copies of the value of the expression
589 @var{expr} (using the @code{as} directive @code{.fill}).
590 @samp{.DATAB.B} repeats one-byte values; @samp{.DATAB.W} repeats
591 two-byte values; and @samp{.DATAB.L} repeats four-byte values.
592 @samp{.DATAB} without a suffix repeats four-byte values, just like
595 @c FIXME! Allowing zero might be useful for edge conditions in macros.
596 @var{repeat} must be an absolute expression with a positive value.
598 @item .SDATA "@var{str}" @dots{}
599 String data. Emits a concatenation of bytes, precisely as you specify
600 them (in particular, @emph{nothing is added to mark the end} of the
601 string). @xref{Constants,, String and numeric constants}, for details
602 about how to write strings. @code{.SDATA} concatenates multiple
603 arguments, making it easy to switch between string representations. You
604 can use commas to separate the individual arguments for clarity, if you
607 @item .SDATAB @var{repeat}, "@var{str}" @dots{}
608 Repeated string data. The first argument specifies how many copies of
609 the string to emit; the remaining arguments specify the string, in the
610 same way as the arguments to @code{.SDATA}.
612 @item .SDATAZ "@var{str}" @dots{}
613 Zero-terminated string data. Just like @code{.SDATA}, except that
614 @code{.SDATAZ} writes a zero byte at the end of the string.
616 @item .SDATAC "@var{str}" @dots{}
617 Count-prefixed string data. Just like @code{.SDATA}, except that
618 @sc{gasp} precedes the string with a leading one-byte count. For
619 example, @samp{.SDATAC "HI"} generates @samp{.byte 2,72,73}. Since the
620 count field is only one byte, you can only use @code{.SDATAC} for
621 strings less than 256 bytes in length.
625 @subsection Uninitialized data
627 @c FIXME! .space different on some platforms, notably HPPA. Config?
628 Use the @code{.RES}, @code{.SRES}, @code{.SRESC}, and @code{.SRESZ}
629 directives to reserve memory and leave it uninitialized. @sc{gasp}
630 resolves these directives to appropriate calls of the @sc{gnu}
631 @code{as} @code{.space} directive.
634 @item .RES @var{count}
635 @itemx .RES.B @var{count}
636 @itemx .RES.W @var{count}
637 @itemx .RES.L @var{count}
638 Reserve room for @var{count} uninitialized elements of data. The
639 suffix specifies the size of each element: @code{.RES.B} reserves
640 @var{count} bytes, @code{.RES.W} reserves @var{count} pairs of bytes,
641 and @code{.RES.L} reserves @var{count} quartets. @code{.RES} without a
642 suffix is equivalent to @code{.RES.L}.
644 @item .SRES @var{count}
645 @itemx .SRES.B @var{count}
646 @itemx .SRES.W @var{count}
647 @itemx .SRES.L @var{count}
648 @c FIXME! This is boring. Shouldn't it at least have a different
649 @c default size? (e.g. the "S" suggests "string", for which .B
650 @c would be more appropriate)
651 @code{.SRES} is a synonym for @samp{.RES}.
653 @item .SRESC @var{count}
654 @itemx .SRESC.B @var{count}
655 @itemx .SRESC.W @var{count}
656 @itemx .SRESC.L @var{count}
657 Like @code{.SRES}, but reserves space for @code{@var{count}+1} elements.
659 @item .SRESZ @var{count}
660 @itemx .SRESZ.B @var{count}
661 @itemx .SRESZ.W @var{count}
662 @itemx .SRESZ.L @var{count}
663 Like @code{.SRES}, but reserves space for @code{@var{count}+1} elements.
667 @section Assembly listing control
669 The @sc{gasp} listing-control directives map straightforwardly to
670 related @sc{gnu} @code{as} directives.
675 Print control. This directive emits the @sc{gnu} @code{as} directive
676 @code{.list} or @code{.nolist}, according to its argument. @xref{List,,
677 @code{.list}, as.info, Using as}, for details on how these directives
680 @item .FORM LIN=@var{ln}
681 @itemx .FORM COL=@var{cols}
682 @itemx .FORM LIN=@var{ln} COL=@var{cols}
683 Specify the page size for assembly listings: @var{ln} represents the
684 number of lines, and @var{cols} the number of columns. You may specify
685 either page dimension independently, or both together. If you do not
686 specify the number of lines, @sc{gasp} assumes 60 lines; if you do not
687 specify the number of columns, @sc{gasp} assumes 132 columns.
688 (Any values you may have specified in previous instances of @code{.FORM}
689 do @emph{not} carry over as defaults.) Emits the @code{.psize}
692 @item .HEADING @var{string}
693 Specify @var{string} as the title of your assembly listings. Emits
694 @samp{.title "@var{string}"}.
697 Force a new page in assembly listings. Emits @samp{.eject}.
701 @section Miscellaneous commands
705 @c FIXME! This is very strange, since _GAS_ understands .org
706 This command is recognized, but not yet implemented. @sc{gasp}
707 generates an error message for programs that use @code{.ORG}.
710 @c FIXME no test cases in testsuite/gasp
711 @sc{gasp} understands numbers in any of base two, eight, ten, or
712 sixteen. You can encode the base explicitly in any numeric constant
713 (@pxref{Constants,, String and numeric constants}). If you write
714 numbers without an explicit indication of the base, the most recent
715 @samp{.RADIX @var{s}} command determines how they are interpreted.
716 @var{s} is a single letter, one of the following:
726 Base 10. This is the original default radix.
732 You may specify the argument @var{s} in lower case (any of @samp{bqdh})
733 with the same effects.
735 @item .EXPORT @var{name}
736 @itemx .GLOBAL @var{name}
737 @c FIXME! No test cases in testsuite/gasp
738 Declare @var{name} global (emits @samp{.global @var{name}}). The two
739 directives are synonymous.
742 No effect: @sc{gasp} accepts this directive, and silently ignores it.
745 Mark end of each preprocessor file. @sc{gasp} issues a warning if it
746 reaches end of file without seeing this command.
748 @item .INCLUDE "@var{str}"
749 Preprocess the file named by @var{str}, as if its contents appeared
750 where the @code{.INCLUDE} directive does. @sc{gasp} imposes a maximum
751 limit of 30 stacked include files, as a sanity check.
752 @c FIXME! Why is include depth not affected by -u?
754 @item .ALIGN @var{size}
755 @c FIXME! Why is this not utterly pointless?
756 Evaluate the absolute expression @var{size}, and emit the assembly
757 instruction @samp{.align @var{size}} using the result.
761 @section Details of the GASP syntax
763 Since @sc{gasp} is meant to work with assembly code, its statement
764 syntax has no surprises for the assembly programmer.
767 @emph{Whitespace} (blanks or tabs; @emph{not} newline) is partially
768 significant, in that it delimits up to three fields in a line. The
769 amount of whitespace does not matter; you may line up fields in separate
770 lines if you wish, but @sc{gasp} does not require that.
772 @cindex fields of @sc{gasp} source line
774 The @emph{first field}, an optional @dfn{label}, must be flush left in a
775 line (with no leading whitespace) if it appears at all. You may use a
776 colon after the label if you wish; @sc{gasp} neither requires the colon
777 nor objects to it (but will not include it as part of the label name).
779 @cindex directive field
780 The @emph{second field}, which must appear after some whitespace,
781 contains a @sc{gasp} or assembly @dfn{directive}.
783 @cindex argument fields
784 Any @emph{further fields} on a line are @dfn{arguments} to the
785 directive; you can separate them from one another using either commas or
797 @subsection Special syntactic markers
799 @sc{gasp} recognizes a few special markers: to delimit comments, to
800 continue a statement on the next line, to separate symbols from other
801 characters, and to copy text to the output literally. (One other
802 special marker, @samp{\@@}, works only within macro definitions;
803 @pxref{Macros,, Defining your own directives}.)
806 The trailing part of any @sc{gasp} source line may be a @dfn{comment}.
807 A comment begins with the first unquoted @samp{;} or @samp{\;}, and
808 extends to the end of a line. The two kinds of comment markers lead to
809 slightly different treatment:
813 Generate an assembly comment in the @sc{gasp} output. @sc{gasp} evaluates any
814 preprocessor variables (macro arguments, or variables defined with
815 @code{.ASSIGNA} or @code{.ASSIGNC}) present. For example, a macro that
819 .MACRO SUM FROM=0, TO=9
824 issues as the first line of output a comment that records the
825 values you used to call the macro.
828 This marks a @sc{gasp} source comment. @sc{gasp} does not copy such
829 comments to the assembly output.
832 @cindex continuation character
834 To @emph{continue a statement} on the next line of the file, begin the
835 second line with the character @samp{+}.
837 @cindex literal copy to output
838 @cindex copying literally to output
839 @cindex preprocessing, avoiding
840 @cindex avoiding preprocessing
841 Occasionally you may want to prevent @sc{gasp} from preprocessing some
842 particular bit of text. To @emph{copy literally} from the @sc{gasp}
843 source to its output, place @samp{\(} before the string to copy, and
844 @samp{)} at the end. For example, write @samp{\(\;)} if you need the
845 characters @samp{\;} in your assembly output.
847 @cindex symbol separator
848 @cindex text, separating from symbols
849 @cindex symbols, separating from text
850 To @emph{separate a preprocessor variable} from text to appear
851 immediately after its value, write a single quote (@code{'}). For
852 example, @samp{.SDATA "\P'1"} writes a string built by concatenating the
853 value of @code{P} and the digit @samp{1}. (You cannot achieve this by
854 writing just @samp{\P1}, since @samp{P1} is itself a valid name for a
855 preprocessor variable.)
858 @subsection String and numeric constants
860 There are two ways of writing @dfn{string constants} in @sc{gasp}: as
861 literal text, and by numeric byte value. Specify a string literal
862 between double quotes (@code{"@var{str}"}). Specify an individual
863 numeric byte value as an absolute expression between angle brackets
864 (@code{<@var{expr}>}. Directives that output strings allow you to
865 specify any number of either kind of value, in whatever order is
866 convenient, and concatenate the result.
868 @c Details of numeric notation, e.g. base prefixes
869 You can write @dfn{numeric constants} either in a specific base, or in
870 whatever base is currently selected (either 10, or selected by the most
871 recent @code{.RADIX}).
873 To write a number in a @emph{specific base}, use the pattern
874 @code{'@var{s}@var{ddd}}: a single quote, followed by a base specifier
875 character @var{s}, followed by digits @var{ddd}. The base specifier
876 character matches those you can specify with @code{.RADIX}: @samp{B} for
877 base 2, @samp{Q} for base 8, @samp{D} for base 10, and @samp{H} for base
878 16. (You can write this character in lower case if you prefer.)
880 @c FIXME! What are rules for recognizing number in deflt base? Whatever
881 @c is left over after parsing other things??
886 @sc{gasp} recognizes symbol names that start with any alphabetic character,
887 @samp{_}, or @samp{$}, and continue with any of the same characters or
888 with digits. Label names follow the same rules.
891 @subsection Arithmetic expressions in GASP
893 @cindex absolute expressions
894 @cindex relocatable expressions
895 There are two kinds of expressions, depending on their result:
896 @dfn{absolute} expressions, which resolve to a constant (that is, they
897 do not involve any values unknown to @sc{gasp}), and @dfn{relocatable}
898 expressions, which must reduce to the form
901 @var{addsym}+@var{const}-@var{subsym}
905 where @var{addsym} and @var{subsym} are assembly symbols of unknown
906 value, and @var{const} is a constant.
908 Arithmetic for @sc{gasp} expressions follows very similar rules to C.
909 You can use parentheses to change precedence; otherwise, arithmetic
910 primitives have decreasing precedence in the order of the following
915 Single-argument @code{+} (identity), @code{-} (arithmetic opposite), or
916 @code{~} (bitwise negation). @emph{The argument must be an absolute
920 @code{*} (multiplication) and @code{/} (division). @emph{Both arguments
921 must be absolute expressions.}
924 @code{+} (addition) and @code{-} (subtraction). @emph{At least one argument
926 @c FIXME! Actually, subtraction doesn't check for this.
929 @code{&} (bitwise and). @emph{Both arguments must be absolute.}
932 @c FIXME! I agree ~ is a better notation than ^ for xor, but is the
933 @c improvement worth differing from C?
934 @code{|} (bitwise or) and @code{~} (bitwise exclusive or; @code{^} in
935 C). @emph{Both arguments must be absolute.}
938 @node String Builtins
939 @subsection String primitives
941 You can use these primitives to manipulate strings (in the argument
942 field of @sc{gasp} statements):
945 @item .LEN("@var{str}")
946 Calculate the length of string @code{"@var{str}"}, as an absolute
947 expression. For example, @samp{.RES.B .LEN("sample")} reserves six
950 @item .INSTR("@var{string}", "@var{seg}", @var{ix})
951 Search for the first occurrence of @var{seg} after position @var{ix} of
952 @var{string}. For example, @samp{.INSTR("ABCDEFG", "CDE", 0)} evaluates
953 to the absolute result @code{2}.
955 The result is @code{-1} if @var{seg} does not occur in @var{string}
956 after position @var{ix}.
958 @item .SUBSTR("@var{string}",@var{start},@var{len})
959 The substring of @var{string} beginning at byte number @var{start} and
960 extending for @var{len} bytes.