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
27 @title GASP, an assembly preprocessor
28 @c FIXME! Get a version number, global-replace '??'
29 @subtitle for GASP version ??
31 @subtitle January 1994
36 {\parskip=0pt \hfill Cygnus Support\par
40 @vskip 0pt plus 1filll
41 Copyright @copyright{} 1994 Free Software Foundation, Inc.
43 Permission is granted to make and distribute verbatim copies of
44 this manual provided the copyright notice and this permission notice
45 are preserved on all copies.
47 Permission is granted to copy and distribute modified versions of this
48 manual under the conditions for verbatim copying, provided also that
49 the entire resulting derived work is distributed under the terms of a
50 permission notice identical to this one.
52 Permission is granted to copy and distribute translations of this manual
53 into another language, under the above conditions for modified versions.
57 Copyright @copyright{} 1994 Free Software Foundation, Inc.
59 Permission is granted to make and distribute verbatim copies of
60 this manual provided the copyright notice and this permission notice
61 are preserved on all copies.
64 Permission is granted to process this file through TeX and print the
65 results, provided the printed document carries a copying permission
66 notice identical to this one except for the removal of this paragraph
67 (this paragraph not being relevant to the printed manual).
70 Permission is granted to copy and distribute modified versions of this
71 manual under the conditions for verbatim copying, provided also that
72 the entire resulting derived work is distributed under the terms of a
73 permission notice identical to this one.
75 Permission is granted to copy and distribute translations of this manual
76 into another language, under the above conditions for modified versions.
81 GASP is a preprocessor for assembly programs.
83 This file describes version ?? of GASP.
85 Steve Chamberlain wrote GASP; Roland Pesch wrote this manual.
88 * Overview:: What is GASP?
89 * Invoking GASP:: Command line options.
90 * Commands:: Preprocessor commands.
96 @chapter What is GASP?
98 The primary purpose of the @sc{gnu} assembler is to assemble the output of
99 other programs---notably compilers. When you have to hand-code
100 specialized routines in assembly, that means the @sc{gnu} assembler is
101 an unfriendly processor: it has no directives for macros, conditionals,
102 or many other conveniences that you might expect.
104 In some cases you can simply use the C preprocessor, or a generalized
105 preprocessor like @sc{m4}; but this can be awkward, since none of these
106 things are designed with assembly in mind.
108 @sc{gasp} fills this need. It is expressly designed to provide the
109 facilities you need with hand-coded assembly code. Implementing it as a
110 preprocessor, rather than part of the assembler, allows the maximum
111 flexibility: you can use it with hand-coded assembly, without paying a
112 penalty of added complexity in the assembler you use for compiler
115 Here is a small example to give the flavor of @sc{gasp}. This input to
120 .MACRO saveregs from=8 to=14
123 .AWHILE \&count LE \to
125 count .ASSIGNA \&count + 1
131 bar: mov #H'dead+10,r0
132 foo .SDATAC "hello"<10>
138 generates this assembly program:
147 bar: mov #57005+10,r0
148 foo: .byte 6,104,101,108,108,111,10
153 @chapter Command Line Options
155 @c FIXME! Or is there a simpler way, calling from GAS option?
156 The simplest way to use @sc{gasp} is to run it as a filter and assemble
157 its output. In Unix and its ilk, you can do this, for example:
159 @c FIXME! GASP filename suffix convention?
161 $ gasp prog.asm | as -o prog.o
164 Naturally, there are also a few command-line options to allow you to
165 request variations on this basic theme. Here is the full set of
166 possibilities for the @sc{gasp} command line.
169 gasp [ -c ] [ -o @var{outfile} ] [ -p ] [ -s ] [ -u ]
173 @c FIXME!! Aren't all GNU programs supposed to have a -V or --version
174 @c option, that reports version info and exits?
177 @item @var{infile} @dots{}
178 @c FIXME! Why not stdin as default infile?
179 The input file names. You must specify at least one input file; if you
180 specify more, @sc{gasp} preprocesses them all, concatenating the output
181 in the order you list the @var{infile} arguments.
183 Mark the end of each input file with the preprocessor command
184 @code{.END}. @xref{Other Commands,, Miscellaneous commands}.
187 @c FIXME! Shouldn't there be an option to set the prefix char so it can
188 @c always be the comment char for whatever assembly version we have?
189 Copy the source lines to the output file. Use this option
190 to see the effect of each preprocessor line on the @sc{gasp} output.
191 @sc{gasp} marks the lines copied from the source file with @samp{!} at
192 the beginning, to help you distinguish them from the rest of the output.
194 @item -o @var{outfile}
195 Write the output in a file called @var{outfile}. If you do not use the
196 @samp{-o} option, @sc{gasp} writes its output on the standard output
200 Print line numbers. @sc{gasp} obeys this option @emph{only} if you also
201 specify @samp{-c} to copy source lines to its output. With @samp{-c
202 -p}, @sc{gasp} displays the line number of each source line copied
203 (immediately after the @samp{!} that marks source lines in the output).
206 Show statistics. In this version of @sc{gasp}, this option produces
207 statistics about the string buffers that @sc{gasp} allocates internally.
208 For each defined buffersize @var{s}, @sc{gasp} shows the number of
209 strings @var{n} that it allocated, with a line like this:
212 strings size @var{s} : @var{n}
216 @sc{gasp} displays these statistics on the standard error stream, when
220 Bypass ``unreasonable expansion'' limit. Since you can define @sc{gasp}
221 macros inside other macro definitions, the preprocessor normally
222 includes a sanity check. If your program requires more than 1,000
223 nested expansions, @sc{gasp} normally exits with an error message. Use
224 this option to turn off this check, allowing unlimited nested
229 @chapter Preprocessor Commands
231 @sc{gasp} commands have a straightforward syntax that fits in well with
232 assembly conventions. In general, a command extends for a line, and may
233 have up to three fields: an optional label, the command itself, and
234 optional arguments to the command. You can write commands in upper or
235 lower case, though this manual shows them in upper case. @xref{Syntax
236 Details,, Details of the GASP syntax}, for more information.
250 @section Conditional assembly
252 The conditional-assembly directives allow you to include or exclude
253 portions of an assembly depending on how a pair of expressions, or a
254 pair of strings, compare.
256 The overall structure of conditionals is familiar from many other
257 contexts. @code{.AIF} marks the start of a conditional, and precedes
258 assembly for the case when the condition is true. An optional
259 @code{.AELSE} precedes assembly for the converse case, and an
260 @code{.AENDI} marks the end of the condition.
262 @c FIXME! Why doesn't -u turn off this check?
263 You may nest conditionals up to a depth of 100; @sc{gasp} rejects
264 nesting beyond that, because it may indicate a bug in your macro
267 @c FIXME! Why isn't there something like cpp's -D option? Conditionals
268 @c would be much more useful if there were.
269 Conditionals are primarily useful inside macro definitions, where you
270 often need different effects depending on argument values.
271 @xref{Macros,, Defining your own directives}, for details about defining
275 @item .AIF @var{expra} @var{cmp} @var{exprb}
276 @itemx .AIF "@var{stra}" @var{cmp} "@var{strb}"
278 The governing condition goes on the same line as the @code{.AIF}
279 preprocessor command. You may compare either two strings, or two
282 When you compare strings, only two conditional @var{cmp} comparison
283 operators are available: @samp{EQ} (true if @var{stra} and @var{strb}
284 are identical), and @samp{NE} (the converse).
286 When you compare two expressions, @emph{both expressions must be
287 absolute} (@pxref{Expressions,, Arithmetic expressions in GASP}). You
288 can use these @var{cmp} comparison operators with expressions:
292 Are @var{expra} and @var{exprb} equal? (For strings, are @var{stra} and
293 @var{strb} identical?)
296 Are @var{expra} and @var{exprb} different? (For strings, are @var{stra}
297 and @var{strb} different?
300 Is @var{expra} less than @var{exprb}? (Not allowed for strings.)
303 Is @var{expra} less than or equal to @var{exprb}? (Not allowed for strings.)
306 Is @var{expra} greater than @var{exprb}? (Not allowed for strings.)
309 Is @var{expra} greater than or equal to @var{exprb}? (Not allowed for
314 Marks the start of assembly code to be included if the condition fails.
315 Optional, and only allowed within a conditional (between @code{.AIF} and
319 Marks the end of a conditional assembly.
323 @section Repetitive sections of assembly
325 Two preprocessor directives allow you to repeatedly issue copies of the
326 same block of assembly code.
329 @item .AREPEAT @var{aexp}
331 If you simply need to repeat the same block of assembly over and over a
332 fixed number of times, sandwich one instance of the repeated block
333 between @code{.AREPEAT} and @code{.AENDR}. Specify the number of
334 copies as @var{aexp} (which must be an absolute expression). For
335 example, this repeats two assembly statements three times in succession:
346 @item .AWHILE @var{expra} @var{cmp} @var{exprb}
348 @itemx .AWHILE @var{stra} @var{cmp} @var{strb}
350 To repeat a block of assembly depending on a conditional test, rather
351 than repeating it for a specific number of times, use @code{.AWHILE}.
352 @code{.AENDW} marks the end of the repeated block. The conditional
353 comparison works exactly the same way as for @code{.AIF}, with the same
354 comparison operators (@pxref{Conditionals,, Conditional assembly}).
356 Since the terms of the comparison must be absolute expression,
357 @code{.AWHILE} is primarily useful within macros. @xref{Macros,,
358 Defining your own directives}.
361 @cindex loops, breaking out of
362 @cindex breaking out of loops
363 You can use the @code{.EXITM} preprocessor directive to break out of
364 loops early (as well as to break out of macros). @xref{Macros,,
365 Defining your own directives}.
368 @section Preprocessor variables
370 You can use variables in @sc{gasp} to represent strings, registers, or
371 the results of expressions.
373 You must distinguish two kinds of variables:
374 @c FIXME! Is this crud true about conditional comparisons vs 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. These are defined as macro
395 arguments, or with @code{.ASSIGNC} or @code{.ASSIGNA}. To evaluate this
396 kind of variable, write @samp{\&} before the variable name; for example,
410 @item @var{pvar} .EQU @var{expr}
411 @c FIXME! Anything to beware of re GAS directive of same name?
412 Assign preprocessor variable @var{pvar} the value of the expression
413 @var{expr}. There are no restrictions on redefinition; use @samp{.EQU}
414 with the same @var{pvar} as often as you find it convenient.
416 @item @var{pvar} .ASSIGN @var{expr}
417 Almost the same as @code{.EQU}, save that you may not redefine
418 @var{pvar} using @code{.ASSIGN} once it has a value.
419 @c FIXME!! Supposed to work this way, apparently, but on 9feb94 works
422 @item @var{pvar} .ASSIGNA @var{aexpr}
423 Define a variable with a numeric value, for use during preprocessing.
424 @var{aexpr} must be an absolute expression. You can redefine variables
425 with @code{.ASSIGNA} at any time.
427 @item @var{pvar} .ASSIGNC "@var{str}"
428 Define a variable with a string value, for use during preprocessing.
429 You can redefine variables with @code{.ASSIGNC} at any time.
431 @item @var{pvar} .REG (@var{register})
432 Use @code{.REG} to define a variable that represents a register. In
433 particular, @var{register} is @emph{not evaluated} as an expression.
434 You may use @code{.REG} at will to redefine register variables.
437 All these directives accept the variable name in the ``label'' position,
438 that is at the left margin. You may specify a colon after the variable
439 name if you wish; the first example above could have started @samp{eg:}
440 with the same effect.
443 @section Defining your own directives
445 The commands @code{.MACRO} and @code{.ENDM} allow you to define macros
446 that generate assembly output, and that you can use with a syntax
447 similar to built-in @sc{gasp} or assembler directives. For example,
448 this definition specifies a macro @code{SUM} that adds together a range of
449 consecutive registers:
453 .MACRO SUM FROM=0, TO=9
456 COUNT .ASSIGNA \FROM+1
457 .AWHILE \&COUNT LE \TO
459 COUNT .ASSIGNA \&COUNT+1
466 With that definition, @samp{SUM 0,5} generates this assembly output:
481 @item .MACRO @var{macname}
482 @itemx .MACRO @var{macname} @var{macargs} @dots{}
483 Begin the definition of a macro called @var{macname}. If your macro
484 definition requires arguments, specify their names after the macro name,
485 separated by commas or spaces. You can supply a default value for any
486 macro argument by following the name with @samp{=@var{deflt}}. For
487 example, these are all valid @code{.MACRO} statements:
491 Begin the definition of a macro called @code{COMM}, which takes no
494 @item .MACRO PLUS1 P, P1
495 @itemx .MACRO PLUS1 P P1
496 Either statement begins the definition of a macro called @code{PLUS1},
497 which takes two arguments; within the macro definition, these arguments
498 are evaluated as @samp{\&P} and @samp{\&P1}.
500 @item .MACRO RESERVE_STR P1=0 P2
501 Begin the definition of a macro called @code{RESERVE_STR}, with two
502 arguments. The first argument has a default value, but not the second.
503 After the definition is complete, you can call the macro either as
504 @samp{RESERVE_STR @var{a},@var{b}} (with @samp{\&P1} evaluating to
505 @var{a} and @samp{\&P2} evaluating to @var{b}), or as @samp{RESERVE_STR
506 ,@var{b}} (with @samp{\&P1} evaluating as the default, in this case
507 @samp{0}, and @samp{\&P2} evaluating to @var{b}).
510 When you call a macro, the values are assigned by position to each
511 argument name. Macro arguments are preprocessor variables in the same
512 way as variables you define with @samp{.ASSIGNA} or @samp{.ASSIGNC}, and
513 you can therefore use them in conditionals or for loop control.
515 @item @var{name} .MACRO
516 @itemx @var{name} .MACRO ( @var{macargs} @dots{} )
517 @c FIXME check: I think no error _and_ no args recognized if I use form
518 @c NAME .MACRO ARG ARG
519 An alternative form of introducing a macro definition: specify the macro
520 name in the label position, and the arguments (if any) between
521 parentheses after the name. Defaulting rules and usage work the same
522 way as for the alternate macro definition syntax.
525 Mark the end of a macro definition.
528 Exit early from the current macro definition, @code{.AREPEAT} loop, or
531 @cindex number of macros executed
532 @cindex macros, count executed
534 @sc{gasp} maintains a counter of how many macros it has
535 executed in this pseudo-variable; you can copy that number to your
536 output with @samp{\@@}, but @emph{only within a macro definition}.
542 In assembly code, you often need to specify working areas of memory;
543 depending on the application, you may want to initialize such memory or
544 not. @sc{gasp} provides preprocessor directives to help you avoid
545 repetitive coding for both purposes.
547 You can use labels as usual to mark the data areas.
555 @subsection Initialized data
557 These are the @sc{gasp} directives for initialized data, and the standard
558 @sc{gnu} assembler directives they expand to:
561 @item .DATA @var{expr}, @var{expr}, @dots{}
562 @itemx .DATA.B @var{expr}, @var{expr}, @dots{}
563 @itemx .DATA.W @var{expr}, @var{expr}, @dots{}
564 @itemx .DATA.L @var{expr}, @var{expr}, @dots{}
565 Evaluate arithmetic expressions @var{expr}, and emit the corresponding
566 @code{as} directive (labelled with @var{lab}). The unqualified
567 @code{.DATA} emits @samp{.long}; @code{.DATA.B} emits @samp{.byte};
568 @code{.DATA.W} emits @samp{.short}; and @code{.DATA.L} emits
571 For example, @samp{foo .DATA 1,2,3} emits @samp{foo: .long 1,2,3}.
573 @item .DATAB @var{repeat}, @var{expr}
574 @itemx .DATAB.B @var{repeat}, @var{expr}
575 @itemx .DATAB.W @var{repeat}, @var{expr}
576 @itemx .DATAB.L @var{repeat}, @var{expr}
577 @c FIXME! Looks like gasp accepts and ignores args after 2nd.
578 Make @code{as} emit @var{repeat} copies of the value of the expression
579 @var{expr} (using the @code{as} directive @code{.fill}).
580 @samp{.DATAB.B} repeats one-byte values; @samp{.DATAB.W} repeats
581 two-byte values; and @samp{.DATAB.L} repeats four-byte values.
582 @samp{.DATAB} without a suffix repeats four-byte values, just like
585 @c FIXME! Allowing zero might be useful for edge conditions in macros.
586 @var{repeat} must be an absolute expression with a positive value.
588 @item .SDATA "@var{str}" @dots{}
589 String data. Emits a concatenation of bytes, precisely as you specify
590 them (in particular, @emph{nothing is added to mark the end} of the
591 string). @xref{Constants,, String and numeric constants}, for details
592 about how to write strings. @code{.SDATA} concatenates multiple
593 arguments, making it easy to switch between string representations. You
594 can use commas to separate the individual arguments for clarity, if you
597 @item .SDATAB @var{repeat}, "@var{str}" @dots{}
598 Repeated string data. The first argument specifies how many copies of
599 the string to emit; the remaining arguments specify the string, in the
600 same way as the arguments to @code{.SDATA}.
602 @item .SDATAZ "@var{str}" @dots{}
603 Zero-terminated string data. Just like @code{.SDATA}, except that
604 @code{.SDATAZ} writes a zero byte at the end of the string.
606 @item .SDATAC "@var{str}" @dots{}
607 Count-prefixed string data. Just like @code{.SDATA}, except that
608 @sc{gasp} precedes the string with a leading one-byte count. For
609 example, @samp{.SDATAC "HI"} generates @samp{.byte 2,72,73}. Since the
610 count field is only one byte, you can only use @code{.SDATAC} for
611 strings less than 256 bytes in length.
615 @subsection Uninitialized data
617 @c FIXME! .space different on some platforms, notably HPPA. Config?
618 Use the @code{.RES}, @code{.SRES}, @code{.SRESC}, and @code{.SRESZ}
619 directives to reserve memory and leave it uninitialized. @sc{gasp}
620 resolves these directives to appropriate calls of the @sc{gnu}
621 @code{as} @code{.space} directive.
624 @item .RES @var{count}
625 @itemx .RES.B @var{count}
626 @itemx .RES.W @var{count}
627 @itemx .RES.L @var{count}
628 Reserve room for @var{count} uninitialized elements of data. The
629 suffix specifies the size of each element: @code{.RES.B} reserves
630 @var{count} bytes, @code{.RES.W} reserves @var{count} pairs of bytes,
631 and @code{.RES.L} reserves @var{count} quartets. @code{.RES} without a
632 suffix is equivalent to @code{.RES.L}.
634 @item .SRES @var{count}
635 @itemx .SRES.B @var{count}
636 @itemx .SRES.W @var{count}
637 @itemx .SRES.L @var{count}
638 @c FIXME! This is boring. Shouldn't it at least have a different
639 @c default size? (e.g. the "S" suggests "string", for which .B
640 @c would be more appropriate)
641 @code{.SRES} is a synonym for @samp{.RES}.
643 @item .SRESC @var{count}
644 @itemx .SRESC.B @var{count}
645 @itemx .SRESC.W @var{count}
646 @itemx .SRESC.L @var{count}
647 Like @code{.SRES}, but reserves space for @code{@var{count}+1} elements.
649 @item .SRESZ @var{count}
650 @itemx .SRESZ.B @var{count}
651 @itemx .SRESZ.W @var{count}
652 @itemx .SRESZ.L @var{count}
653 Like @code{.SRES}, but reserves space for @code{@var{count}+1} elements.
657 @section Assembly listing control
659 The @sc{gasp} listing-control directives map straightforwardly to
660 related @sc{gnu} @code{as} directives.
665 Print control. This directive emits the @sc{gnu} @code{as} directive
666 @code{.list} or @code{.nolist}, according to its argument. @xref{List,,
667 @code{.list}, as.info, Using as}, for details on how these directives
670 @item .FORM LIN=@var{ln}
671 @itemx .FORM COL=@var{cols}
672 @itemx .FORM LIN=@var{ln} COL=@var{cols}
673 Specify the page size for assembly listings: @var{ln} represents the
674 number of lines, and @var{cols} the number of columns. You may specify
675 either page dimension independently, or both together. If you do not
676 specify the number of lines, @sc{gasp} assumes 60 lines; if you do not
677 specify the number of columns, @sc{gasp} assumes 132 columns.
678 (Any values you may have specified in previous instances of @code{.FORM}
679 do @emph{not} carry over as defaults.) Emits the @code{.psize}
682 @item .HEADING @var{string}
683 Specify @var{string} as the title of your assembly listings. Emits
684 @samp{.title "@var{string}"}.
687 Force a new page in assembly listings. Emits @samp{.eject}.
691 @section Miscellaneous commands
695 @c FIXME! This is very strange, since _GAS_ understands .org
696 This command is recognized, but not yet implemented. @sc{gasp}
697 generates an error message for programs that use @code{.ORG}.
700 @c FIXME no test cases in testsuite/gasp
701 @sc{gasp} understands numbers in any of base two, eight, ten, or
702 sixteen. You can encode the base explicitly in any numeric constant
703 (@pxref{Constants,, String and numeric constants}). If you write
704 numbers without an explicit indication of the base, the most recent
705 @samp{.RADIX @var{s}} command determines how they are interpreted.
706 @var{s} is a single letter, one of the following:
716 Base 10. This is the original default radix.
722 You may specify the argument @var{s} in lower case (any of @samp{bqdh})
723 with the same effects.
725 @item .EXPORT @var{name}
726 @itemx .GLOBAL @var{name}
727 @c FIXME! No test cases in testsuite/gasp
728 Declare @var{name} global (emits @samp{.global @var{name}}). The two
729 directives are synonymous.
732 No effect: @sc{gasp} accepts this directive, and silently ignores it.
735 Mark end of each preprocessor file. @sc{gasp} issues a warning if it
736 reaches end of file without seeing this command.
738 @item .INCLUDE "@var{str}"
739 Preprocess the file named by @var{str}, as if its contents appeared
740 where the @code{.INCLUDE} directive does. @sc{gasp} imposes a maximum
741 limit of 30 stacked include files, as a sanity check.
742 @c FIXME! Why is include depth not affected by -u?
744 @item .ALIGN @var{size}
745 @c FIXME! Why is this not utterly pointless?
746 Evaluate the absolute expression @var{size}, and emit the assembly
747 instruction @samp{.align @var{size}} using the result.
751 @section Details of the GASP syntax
753 Since @sc{gasp} is meant to work with assembly code, its statement
754 syntax has no surprises for the assembly programmer.
757 @emph{Whitespace} (blanks or tabs; @emph{not} newline) is partially
758 significant, in that it delimits up to three fields in a line. The
759 amount of whitespace does not matter; you may line up fields in separate
760 lines if you wish, but @sc{gasp} does not require that.
762 @cindex fields of @sc{gasp} source line
764 The @emph{first field}, an optional @dfn{label}, must be flush left in a
765 line (with no leading whitespace) if it appears at all. You may use a
766 colon after the label if you wish; @sc{gasp} neither requires the colon
767 nor objects to it (but will not include it as part of the label name).
769 @cindex directive field
770 The @emph{second field}, which must appear after some whitespace,
771 contains a @sc{gasp} or assembly @dfn{directive}.
773 @cindex argument fields
774 Any @emph{further fields} on a line are @dfn{arguments} to the
775 directive; you can separate them from one another using either commas or
787 @subsection Special syntactic markers
789 @sc{gasp} recognizes a few special markers: to delimit comments, to
790 continue a statement on the next line, to separate symbols from other
791 characters, and to copy text to the output literally. (One other
792 special marker, @samp{\@@}, works only within macro definitions;
793 @pxref{Macros,, Defining your own directives}.)
796 The trailing part of any @sc{gasp} source line may be a @dfn{comment}.
797 A comment begins with the first unquoted @samp{;} or @samp{\;}, and
798 extends to the end of a line. The two kinds of comment markers lead to
799 slightly different treatment:
803 Generate an assembly comment in the @sc{gasp} output. @sc{gasp} evaluates any
804 preprocessor variables (macro arguments, or variables defined with
805 @code{.ASSIGNA} or @code{.ASSIGNC}) present. For example, a macro that
809 .MACRO SUM FROM=0, TO=9
814 issues as the first line of output a comment that records the
815 values you used to call the macro.
818 This marks a @sc{gasp} source comment. @sc{gasp} does not copy such
819 comments to the assembly output.
822 @cindex continuation character
824 To @emph{continue a statement} on the next line of the file, begin the
825 second line with the character @samp{+}.
827 @cindex literal copy to output
828 @cindex copying literally to output
829 @cindex preprocessing, avoiding
830 @cindex avoiding preprocessing
831 Occasionally you may want to prevent @sc{gasp} from preprocessing some
832 particular bit of text. To @emph{copy literally} from the @sc{gasp}
833 source to its output, place @samp{\(} before the string to copy, and
834 @samp{)} at the end. For example, write @samp{\(\;)} if you need the
835 characters @samp{\;} in your assembly output.
837 @cindex symbol separator
838 @cindex text, separating from symbols
839 @cindex symbols, separating from text
840 To @emph{separate a preprocessor variable} from text to appear
841 immediately after its value, write a single quote (@code{'}). For
842 example, @samp{.SDATA "\P'1"} writes a string built by concatenating the
843 value of @code{P} and the digit @samp{1}. (You cannot achieve this by
844 writing just @samp{\P1}, since @samp{P1} is itself a valid name for a
845 preprocessor variable.)
848 @subsection String and numeric constants
850 There are two ways of writing @dfn{string constants} in @sc{gasp}: as
851 literal text, and by numeric byte value. Specify a string literal
852 between double quotes (@code{"@var{str}"}). Specify an individual
853 numeric byte value as an absolute expression between angle brackets
854 (@code{<@var{expr}>}. Directives that output strings allow you to
855 specify any number of either kind of value, in whatever order is
856 convenient, and concatenate the result.
858 @c Details of numeric notation, e.g. base prefixes
859 You can write @dfn{numeric constants} either in a specific base, or in
860 whatever base is currently selected (either 10, or selected by the most
861 recent @code{.RADIX}).
863 To write a number in a @emph{specific base}, use the pattern
864 @code{'@var{s}@var{ddd}}: a single quote, followed by a base specifier
865 character @var{s}, followed by digits @var{ddd}. The base specifier
866 character matches those you can specify with @code{.RADIX}: @samp{B} for
867 base 2, @samp{Q} for base 8, @samp{D} for base 10, and @samp{H} for base
868 16. (You can write this character in lower case if you prefer.)
870 @c FIXME! What are rules for recognizing number in deflt base? Whatever
871 @c is left over after parsing other things??
876 @sc{gasp} recognizes symbol names that start with any alphabetic character,
877 @samp{_}, or @samp{$}, and continue with any of the same characters or
878 with digits. Label names follow the same rules.
881 @subsection Arithmetic expressions in GASP
883 @cindex absolute expressions
884 @cindex relocatable expressions
885 There are two kinds of expressions, depending on their result:
886 @dfn{absolute} expressions, which resolve to a constant (that is, they
887 do not involve any values unknown to @sc{gasp}), and @dfn{relocatable}
888 expressions, which must reduce to the form
891 @var{addsym}+@var{const}-@var{subsym}
895 where @var{addsym} and @var{subsym} are assembly symbols of unknown
896 value, and @var{const} is a constant.
898 Arithmetic for @sc{gasp} expressions follows very similar rules to C.
899 You can use parentheses to change precedence; otherwise, arithmetic
900 primitives have decreasing precedence in the order of the following
905 Single-argument @code{+} (identity), @code{-} (arithmetic opposite), or
906 @code{~} (bitwise negation). @emph{The argument must be an absolute
910 @code{*} (multiplication) and @code{/} (division). @emph{Both arguments
911 must be absolute expressions.}
914 @code{+} (addition) and @code{-} (subtraction). @emph{At least one argument
916 @c FIXME! Actually, subtraction doesn't check for this.
919 @code{&} (bitwise and). @emph{Both arguments must be absolute.}
922 @c FIXME! I agree ~ is a better notation than ^ for xor, but is the
923 @c improvement worth differing from C?
924 @code{|} (bitwise or) and @code{~} (bitwise exclusive or; @code{^} in
925 C). @emph{Both arguments must be absolute.}
928 @node String Builtins
929 @subsection String primitives
931 You can use these primitives to manipulate strings (in the argument
932 field of @sc{gasp} statements):
935 @item .LEN("@var{str}")
936 Calculate the length of string @code{"@var{str}"}, as an absolute
937 expression. For example, @samp{.RES.B .LEN("sample")} reserves six
940 @item .INSTR("@var{string}", "@var{seg}", @var{ix})
941 Search for the first occurrence of @var{seg} after position @var{ix} of
942 @var{string}. For example, @samp{.INSTR("ABCDEFG", "CDE", 0)} evaluates
943 to the absolute result @code{2}.
945 The result is @code{-1} if @var{seg} does not occur in @var{string}
946 after position @var{ix}.
948 @item .SUBSTR("@var{string}",@var{start},@var{len})
949 The substring of @var{string} beginning at byte number @var{start} and
950 extending for @var{len} bytes.