1 \input texinfo @c -*- Texinfo -*-
4 @c This file documents the assembly preprocessor "GASP"
6 @c Copyright (c) 1994 Free Software Foundation, Inc.
8 @c This text may be freely distributed under the terms of the GNU
9 @c General Public License.
14 * gasp: (gasp). The GNU Assembler Preprocessor
23 @setchapternewpage odd
27 @title GASP, an assembly preprocessor
28 @subtitle for GASP version 1
35 {\parskip=0pt \hfill Cygnus Support\par
39 @vskip 0pt plus 1filll
40 Copyright @copyright{} 1994 Free Software Foundation, Inc.
42 Permission is granted to make and distribute verbatim copies of
43 this manual provided the copyright notice and this permission notice
44 are preserved on all copies.
46 Permission is granted to copy and distribute modified versions of this
47 manual under the conditions for verbatim copying, provided also that
48 the entire resulting derived work is distributed under the terms of a
49 permission notice identical to this one.
51 Permission is granted to copy and distribute translations of this manual
52 into another language, under the above conditions for modified versions.
56 Copyright @copyright{} 1994 Free Software Foundation, Inc.
58 Permission is granted to make and distribute verbatim copies of
59 this manual provided the copyright notice and this permission notice
60 are preserved on all copies.
63 Permission is granted to process this file through TeX and print the
64 results, provided the printed document carries a copying permission
65 notice identical to this one except for the removal of this paragraph
66 (this paragraph not being relevant to the printed manual).
69 Permission is granted to copy and distribute modified versions of this
70 manual under the conditions for verbatim copying, provided also that
71 the entire resulting derived work is distributed under the terms of a
72 permission notice identical to this one.
74 Permission is granted to copy and distribute translations of this manual
75 into another language, under the above conditions for modified versions.
80 GASP is a preprocessor for assembly programs.
82 This file describes version 1 of GASP.
84 Steve Chamberlain wrote GASP; Roland Pesch wrote this manual.
87 * Overview:: What is GASP?
88 * Invoking GASP:: Command line options.
89 * Commands:: Preprocessor commands.
95 @chapter What is GASP?
97 The primary purpose of the @sc{gnu} assembler is to assemble the output of
98 other programs---notably compilers. When you have to hand-code
99 specialized routines in assembly, that means the @sc{gnu} assembler is
100 an unfriendly processor: it has no directives for macros, conditionals,
101 or many other conveniences that you might expect.
103 In some cases you can simply use the C preprocessor, or a generalized
104 preprocessor like @sc{m4}; but this can be awkward, since none of these
105 things are designed with assembly in mind.
107 @sc{gasp} fills this need. It is expressly designed to provide the
108 facilities you need with hand-coded assembly code. Implementing it as a
109 preprocessor, rather than part of the assembler, allows the maximum
110 flexibility: you can use it with hand-coded assembly, without paying a
111 penalty of added complexity in the assembler you use for compiler
114 Here is a small example to give the flavor of @sc{gasp}. This input to
119 .MACRO saveregs from=8 to=14
122 .AWHILE \&count LE \to
124 count .ASSIGNA \&count + 1
130 bar: mov #H'dead+10,r0
131 foo .SDATAC "hello"<10>
137 generates this assembly program:
146 bar: mov #57005+10,r0
147 foo: .byte 6,104,101,108,108,111,10
152 @chapter Command Line Options
154 @c FIXME! Or is there a simpler way, calling from GAS option?
155 The simplest way to use @sc{gasp} is to run it as a filter and assemble
156 its output. In Unix and its ilk, you can do this, for example:
158 @c FIXME! GASP filename suffix convention?
160 $ gasp prog.asm | as -o prog.o
163 Naturally, there are also a few command-line options to allow you to
164 request variations on this basic theme. Here is the full set of
165 possibilities for the @sc{gasp} command line.
168 gasp [ -a | --alternate ]
169 [ -c @var{char} | --commentchar @var{char} ]
170 [ -d | --debug ] [ -h | --help ]
171 [ -o @var{outfile} | --output @var{outfile} ]
172 [ -p | --print ] [ -s | --copysource ]
173 [ -u | --unreasonable ] [ -v | --version ]
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}.
189 Use alternative macro syntax. @xref{Alternate,, Alternate macro
190 syntax}, for a discussion of how this syntax differs from the default
193 @cindex comment character, changing
194 @cindex semicolon, as comment
195 @cindex exclamation mark, as comment
196 @cindex shriek, as comment
197 @cindex bang, as comment
198 @cindex @code{!} default comment char
199 @cindex @code{;} as comment char
200 @item -c '@var{char}'
201 @itemx --commentchar '@var{char}'
202 Use @var{char} as the comment character. The default comment character
203 is @samp{!}. For example, to use a semicolon as the comment character,
204 specify @w{@samp{-c ';'}} on the @sc{gasp} command line. Since
205 assembler command characters often have special significance to command
206 shells, it is a good idea to quote or escape @var{char} when you specify
209 For the sake of simplicity, all examples in this manual use the default
210 comment character @samp{!}.
214 Show debugging statistics. In this version of @sc{gasp}, this option
215 produces statistics about the string buffers that @sc{gasp} allocates
216 internally. For each defined buffersize @var{s}, @sc{gasp} shows the
217 number of strings @var{n} that it allocated, with a line like this:
220 strings size @var{s} : @var{n}
224 @sc{gasp} displays these statistics on the standard error stream, when
229 Display a summary of the @sc{gasp} command line options.
231 @item -o @var{outfile}
232 @itemx --output @var{outfile}
233 Write the output in a file called @var{outfile}. If you do not use the
234 @samp{-o} option, @sc{gasp} writes its output on the standard output
239 Print line numbers. @sc{gasp} obeys this option @emph{only} if you also
240 specify @samp{-s} to copy source lines to its output. With @samp{-s
241 -p}, @sc{gasp} displays the line number of each source line copied
242 (immediately after the comment character at the beginning of the line).
246 Copy the source lines to the output file. Use this option
247 to see the effect of each preprocessor line on the @sc{gasp} output.
248 @sc{gasp} places a comment character (@samp{!} by default) at
249 the beginning of each source line it copies, so that you can use this
250 option and still assemble the result.
253 @itemx --unreasonable
254 Bypass ``unreasonable expansion'' limit. Since you can define @sc{gasp}
255 macros inside other macro definitions, the preprocessor normally
256 includes a sanity check. If your program requires more than 1,000
257 nested expansions, @sc{gasp} normally exits with an error message. Use
258 this option to turn off this check, allowing unlimited nested
263 Display the @sc{gasp} version number.
267 @chapter Preprocessor Commands
269 @sc{gasp} commands have a straightforward syntax that fits in well with
270 assembly conventions. In general, a command extends for a line, and may
271 have up to three fields: an optional label, the command itself, and
272 optional arguments to the command. You can write commands in upper or
273 lower case, though this manual shows them in upper case. @xref{Syntax
274 Details,, Details of the GASP syntax}, for more information.
289 @section Conditional assembly
291 The conditional-assembly directives allow you to include or exclude
292 portions of an assembly depending on how a pair of expressions, or a
293 pair of strings, compare.
295 The overall structure of conditionals is familiar from many other
296 contexts. @code{.AIF} marks the start of a conditional, and precedes
297 assembly for the case when the condition is true. An optional
298 @code{.AELSE} precedes assembly for the converse case, and an
299 @code{.AENDI} marks the end of the condition.
301 @c FIXME! Why doesn't -u turn off this check?
302 You may nest conditionals up to a depth of 100; @sc{gasp} rejects
303 nesting beyond that, because it may indicate a bug in your macro
306 @c FIXME! Why isn't there something like cpp's -D option? Conditionals
307 @c would be much more useful if there were.
308 Conditionals are primarily useful inside macro definitions, where you
309 often need different effects depending on argument values.
310 @xref{Macros,, Defining your own directives}, for details about defining
314 @item .AIF @var{expra} @var{cmp} @var{exprb}
315 @itemx .AIF "@var{stra}" @var{cmp} "@var{strb}"
317 The governing condition goes on the same line as the @code{.AIF}
318 preprocessor command. You may compare either two strings, or two
321 When you compare strings, only two conditional @var{cmp} comparison
322 operators are available: @samp{EQ} (true if @var{stra} and @var{strb}
323 are identical), and @samp{NE} (the opposite).
325 When you compare two expressions, @emph{both expressions must be
326 absolute} (@pxref{Expressions,, Arithmetic expressions in GASP}). You
327 can use these @var{cmp} comparison operators with expressions:
331 Are @var{expra} and @var{exprb} equal? (For strings, are @var{stra} and
332 @var{strb} identical?)
335 Are @var{expra} and @var{exprb} different? (For strings, are @var{stra}
336 and @var{strb} different?
339 Is @var{expra} less than @var{exprb}? (Not allowed for strings.)
342 Is @var{expra} less than or equal to @var{exprb}? (Not allowed for strings.)
345 Is @var{expra} greater than @var{exprb}? (Not allowed for strings.)
348 Is @var{expra} greater than or equal to @var{exprb}? (Not allowed for
353 Marks the start of assembly code to be included if the condition fails.
354 Optional, and only allowed within a conditional (between @code{.AIF} and
358 Marks the end of a conditional assembly.
362 @section Repetitive sections of assembly
364 Two preprocessor directives allow you to repeatedly issue copies of the
365 same block of assembly code.
368 @item .AREPEAT @var{aexp}
370 If you simply need to repeat the same block of assembly over and over a
371 fixed number of times, sandwich one instance of the repeated block
372 between @code{.AREPEAT} and @code{.AENDR}. Specify the number of
373 copies as @var{aexp} (which must be an absolute expression). For
374 example, this repeats two assembly statements three times in succession:
385 @item .AWHILE @var{expra} @var{cmp} @var{exprb}
387 @itemx .AWHILE @var{stra} @var{cmp} @var{strb}
389 To repeat a block of assembly depending on a conditional test, rather
390 than repeating it for a specific number of times, use @code{.AWHILE}.
391 @code{.AENDW} marks the end of the repeated block. The conditional
392 comparison works exactly the same way as for @code{.AIF}, with the same
393 comparison operators (@pxref{Conditionals,, Conditional assembly}).
395 Since the terms of the comparison must be absolute expression,
396 @code{.AWHILE} is primarily useful within macros. @xref{Macros,,
397 Defining your own directives}.
400 @cindex loops, breaking out of
401 @cindex breaking out of loops
402 You can use the @code{.EXITM} preprocessor directive to break out of
403 loops early (as well as to break out of macros). @xref{Macros,,
404 Defining your own directives}.
407 @section Preprocessor variables
409 You can use variables in @sc{gasp} to represent strings, registers, or
410 the results of expressions.
412 You must distinguish two kinds of variables:
415 Variables defined with @code{.EQU} or @code{.ASSIGN}. To evaluate this
416 kind of variable in your assembly output, simply mention its name. For
417 example, these two lines define and use a variable @samp{eg}:
427 @emph{Do not use} this kind of variable in conditional expressions or
428 while loops; @sc{gasp} only evaluates these variables when writing
432 Variables for use during preprocessing. You can define these
433 with @code{.ASSIGNC} or @code{.ASSIGNA}. To evaluate this
434 kind of variable, write @samp{\&} before the variable name; for example,
446 @sc{gasp} treats macro arguments almost the same way, but to evaluate
447 them you use the prefix @samp{\} rather than @samp{\&}.
448 @xref{Macros,, Defining your own directives}.
452 @item @var{pvar} .EQU @var{expr}
453 @c FIXME! Anything to beware of re GAS directive of same name?
454 Assign preprocessor variable @var{pvar} the value of the expression
455 @var{expr}. There are no restrictions on redefinition; use @samp{.EQU}
456 with the same @var{pvar} as often as you find it convenient.
458 @item @var{pvar} .ASSIGN @var{expr}
459 Almost the same as @code{.EQU}, save that you may not redefine
460 @var{pvar} using @code{.ASSIGN} once it has a value.
461 @c FIXME!! Supposed to work this way, apparently, but on 9feb94 works
464 @item @var{pvar} .ASSIGNA @var{aexpr}
465 Define a variable with a numeric value, for use during preprocessing.
466 @var{aexpr} must be an absolute expression. You can redefine variables
467 with @code{.ASSIGNA} at any time.
469 @item @var{pvar} .ASSIGNC "@var{str}"
470 Define a variable with a string value, for use during preprocessing.
471 You can redefine variables with @code{.ASSIGNC} at any time.
473 @item @var{pvar} .REG (@var{register})
474 Use @code{.REG} to define a variable that represents a register. In
475 particular, @var{register} is @emph{not evaluated} as an expression.
476 You may use @code{.REG} at will to redefine register variables.
479 All these directives accept the variable name in the ``label'' position,
480 that is at the left margin. You may specify a colon after the variable
481 name if you wish; the first example above could have started @samp{eg:}
482 with the same effect.
484 @c pagebreak makes for better aesthetics---ensures macro and expansion together
487 @section Defining your own directives
489 The commands @code{.MACRO} and @code{.ENDM} allow you to define macros
490 that generate assembly output. You can use these macros with a syntax
491 similar to built-in @sc{gasp} or assembler directives. For example,
492 this definition specifies a macro @code{SUM} that adds together a range of
493 consecutive registers:
497 .MACRO SUM FROM=0, TO=9
500 COUNT .ASSIGNA \FROM+1
501 .AWHILE \&COUNT LE \TO
503 COUNT .ASSIGNA \&COUNT+1
510 With that definition, @samp{SUM 0,5} generates this assembly output:
525 @item .MACRO @var{macname}
526 @itemx .MACRO @var{macname} @var{macargs} @dots{}
527 Begin the definition of a macro called @var{macname}. If your macro
528 definition requires arguments, specify their names after the macro name,
529 separated by commas or spaces. You can supply a default value for any
530 macro argument by following the name with @samp{=@var{deflt}}. For
531 example, these are all valid @code{.MACRO} statements:
535 Begin the definition of a macro called @code{COMM}, which takes no
538 @item .MACRO PLUS1 P, P1
539 @itemx .MACRO PLUS1 P P1
540 Either statement begins the definition of a macro called @code{PLUS1},
541 which takes two arguments; within the macro definition, write
542 @samp{\P} or @samp{\P1} to evaluate the arguments.
544 @item .MACRO RESERVE_STR P1=0 P2
545 Begin the definition of a macro called @code{RESERVE_STR}, with two
546 arguments. The first argument has a default value, but not the second.
547 After the definition is complete, you can call the macro either as
548 @samp{RESERVE_STR @var{a},@var{b}} (with @samp{\P1} evaluating to
549 @var{a} and @samp{\P2} evaluating to @var{b}), or as @samp{RESERVE_STR
550 ,@var{b}} (with @samp{\P1} evaluating as the default, in this case
551 @samp{0}, and @samp{\P2} evaluating to @var{b}).
554 When you call a macro, you can specify the argument values either by
555 position, or by keyword. For example, @samp{SUM 9,17} is equivalent to
556 @samp{SUM TO=17, FROM=9}. Macro arguments are preprocessor variables
557 similar to the variables you define with @samp{.ASSIGNA} or
558 @samp{.ASSIGNC}; in particular, you can use them in conditionals or for
559 loop control. (The only difference is the prefix you write to evaluate
560 the variable: for a macro argument, write @samp{\@var{argname}}, but for
561 a preprocessor variable, write @samp{\&@var{varname}}.)
563 @item @var{name} .MACRO
564 @itemx @var{name} .MACRO ( @var{macargs} @dots{} )
565 @c FIXME check: I think no error _and_ no args recognized if I use form
566 @c NAME .MACRO ARG ARG
567 An alternative form of introducing a macro definition: specify the macro
568 name in the label position, and the arguments (if any) between
569 parentheses after the name. Defaulting rules and usage work the same
570 way as for the other macro definition syntax.
573 Mark the end of a macro definition.
576 Exit early from the current macro definition, @code{.AREPEAT} loop, or
579 @cindex number of macros executed
580 @cindex macros, count executed
582 @sc{gasp} maintains a counter of how many macros it has
583 executed in this pseudo-variable; you can copy that number to your
584 output with @samp{\@@}, but @emph{only within a macro definition}.
586 @item LOCAL @var{name} [ , @dots{} ]
587 @emph{Warning: @code{LOCAL} is only available if you select ``alternate
588 macro syntax'' with @samp{-a} or @samp{--alternate}.} @xref{Alternate,,
589 Alternate macro syntax}.
591 Generate a string replacement for each of the @var{name} arguments, and
592 replace any instances of @var{name} in each macro expansion. The
593 replacement string is unique in the assembly, and different for each
594 separate macro expansion. @code{LOCAL} allows you to write macros that
595 define symbols, without fear of conflict between separate macro expansions.
601 In assembly code, you often need to specify working areas of memory;
602 depending on the application, you may want to initialize such memory or
603 not. @sc{gasp} provides preprocessor directives to help you avoid
604 repetitive coding for both purposes.
606 You can use labels as usual to mark the data areas.
614 @subsection Initialized data
616 These are the @sc{gasp} directives for initialized data, and the standard
617 @sc{gnu} assembler directives they expand to:
620 @item .DATA @var{expr}, @var{expr}, @dots{}
621 @itemx .DATA.B @var{expr}, @var{expr}, @dots{}
622 @itemx .DATA.W @var{expr}, @var{expr}, @dots{}
623 @itemx .DATA.L @var{expr}, @var{expr}, @dots{}
624 Evaluate arithmetic expressions @var{expr}, and emit the corresponding
625 @code{as} directive (labelled with @var{lab}). The unqualified
626 @code{.DATA} emits @samp{.long}; @code{.DATA.B} emits @samp{.byte};
627 @code{.DATA.W} emits @samp{.short}; and @code{.DATA.L} emits
630 For example, @samp{foo .DATA 1,2,3} emits @samp{foo: .long 1,2,3}.
632 @item .DATAB @var{repeat}, @var{expr}
633 @itemx .DATAB.B @var{repeat}, @var{expr}
634 @itemx .DATAB.W @var{repeat}, @var{expr}
635 @itemx .DATAB.L @var{repeat}, @var{expr}
636 @c FIXME! Looks like gasp accepts and ignores args after 2nd.
637 Make @code{as} emit @var{repeat} copies of the value of the expression
638 @var{expr} (using the @code{as} directive @code{.fill}).
639 @samp{.DATAB.B} repeats one-byte values; @samp{.DATAB.W} repeats
640 two-byte values; and @samp{.DATAB.L} repeats four-byte values.
641 @samp{.DATAB} without a suffix repeats four-byte values, just like
644 @c FIXME! Allowing zero might be useful for edge conditions in macros.
645 @var{repeat} must be an absolute expression with a positive value.
647 @item .SDATA "@var{str}" @dots{}
648 String data. Emits a concatenation of bytes, precisely as you specify
649 them (in particular, @emph{nothing is added to mark the end} of the
650 string). @xref{Constants,, String and numeric constants}, for details
651 about how to write strings. @code{.SDATA} concatenates multiple
652 arguments, making it easy to switch between string representations. You
653 can use commas to separate the individual arguments for clarity, if you
656 @item .SDATAB @var{repeat}, "@var{str}" @dots{}
657 Repeated string data. The first argument specifies how many copies of
658 the string to emit; the remaining arguments specify the string, in the
659 same way as the arguments to @code{.SDATA}.
661 @item .SDATAZ "@var{str}" @dots{}
662 Zero-terminated string data. Just like @code{.SDATA}, except that
663 @code{.SDATAZ} writes a zero byte at the end of the string.
665 @item .SDATAC "@var{str}" @dots{}
666 Count-prefixed string data. Just like @code{.SDATA}, except that
667 @sc{gasp} precedes the string with a leading one-byte count. For
668 example, @samp{.SDATAC "HI"} generates @samp{.byte 2,72,73}. Since the
669 count field is only one byte, you can only use @code{.SDATAC} for
670 strings less than 256 bytes in length.
674 @subsection Uninitialized data
676 @c FIXME! .space different on some platforms, notably HPPA. Config?
677 Use the @code{.RES}, @code{.SRES}, @code{.SRESC}, and @code{.SRESZ}
678 directives to reserve memory and leave it uninitialized. @sc{gasp}
679 resolves these directives to appropriate calls of the @sc{gnu}
680 @code{as} @code{.space} directive.
683 @item .RES @var{count}
684 @itemx .RES.B @var{count}
685 @itemx .RES.W @var{count}
686 @itemx .RES.L @var{count}
687 Reserve room for @var{count} uninitialized elements of data. The
688 suffix specifies the size of each element: @code{.RES.B} reserves
689 @var{count} bytes, @code{.RES.W} reserves @var{count} pairs of bytes,
690 and @code{.RES.L} reserves @var{count} quartets. @code{.RES} without a
691 suffix is equivalent to @code{.RES.L}.
693 @item .SRES @var{count}
694 @itemx .SRES.B @var{count}
695 @itemx .SRES.W @var{count}
696 @itemx .SRES.L @var{count}
697 @c FIXME! This is boring. Shouldn't it at least have a different
698 @c default size? (e.g. the "S" suggests "string", for which .B
699 @c would be more appropriate)
700 @code{.SRES} is a synonym for @samp{.RES}.
702 @item .SRESC @var{count}
703 @itemx .SRESC.B @var{count}
704 @itemx .SRESC.W @var{count}
705 @itemx .SRESC.L @var{count}
706 Like @code{.SRES}, but reserves space for @code{@var{count}+1} elements.
708 @item .SRESZ @var{count}
709 @itemx .SRESZ.B @var{count}
710 @itemx .SRESZ.W @var{count}
711 @itemx .SRESZ.L @var{count}
712 Like @code{.SRES}, but reserves space for @code{@var{count}+1} elements.
716 @section Assembly listing control
718 The @sc{gasp} listing-control directives correspond to
719 related @sc{gnu} @code{as} directives.
724 Print control. This directive emits the @sc{gnu} @code{as} directive
725 @code{.list} or @code{.nolist}, according to its argument. @xref{List,,
726 @code{.list}, as.info, Using as}, for details on how these directives
729 @item .FORM LIN=@var{ln}
730 @itemx .FORM COL=@var{cols}
731 @itemx .FORM LIN=@var{ln} COL=@var{cols}
732 Specify the page size for assembly listings: @var{ln} represents the
733 number of lines, and @var{cols} the number of columns. You may specify
734 either page dimension independently, or both together. If you do not
735 specify the number of lines, @sc{gasp} assumes 60 lines; if you do not
736 specify the number of columns, @sc{gasp} assumes 132 columns.
737 (Any values you may have specified in previous instances of @code{.FORM}
738 do @emph{not} carry over as defaults.) Emits the @code{.psize}
741 @item .HEADING @var{string}
742 Specify @var{string} as the title of your assembly listings. Emits
743 @samp{.title "@var{string}"}.
746 Force a new page in assembly listings. Emits @samp{.eject}.
750 @section Miscellaneous commands
754 Use the alternate macro syntax henceforth in the assembly.
755 @xref{Alternate,, Alternate macro syntax}.
758 @c FIXME! This is very strange, since _GAS_ understands .org
759 This command is recognized, but not yet implemented. @sc{gasp}
760 generates an error message for programs that use @code{.ORG}.
763 @c FIXME no test cases in testsuite/gasp
764 @sc{gasp} understands numbers in any of base two, eight, ten, or
765 sixteen. You can encode the base explicitly in any numeric constant
766 (@pxref{Constants,, String and numeric constants}). If you write
767 numbers without an explicit indication of the base, the most recent
768 @samp{.RADIX @var{s}} command determines how they are interpreted.
769 @var{s} is a single letter, one of the following:
779 Base 10. This is the original default radix.
785 You may specify the argument @var{s} in lower case (any of @samp{bqdh})
786 with the same effects.
788 @item .EXPORT @var{name}
789 @itemx .GLOBAL @var{name}
790 @c FIXME! No test cases in testsuite/gasp
791 Declare @var{name} global (emits @samp{.global @var{name}}). The two
792 directives are synonymous.
795 No effect: @sc{gasp} accepts this directive, and silently ignores it.
798 Mark end of each preprocessor file. @sc{gasp} issues a warning if it
799 reaches end of file without seeing this command.
801 @item .INCLUDE "@var{str}"
802 Preprocess the file named by @var{str}, as if its contents appeared
803 where the @code{.INCLUDE} directive does. @sc{gasp} imposes a maximum
804 limit of 30 stacked include files, as a sanity check.
805 @c FIXME! Why is include depth not affected by -u?
807 @item .ALIGN @var{size}
808 @c FIXME! Why is this not utterly pointless?
809 Evaluate the absolute expression @var{size}, and emit the assembly
810 instruction @samp{.align @var{size}} using the result.
814 @section Details of the GASP syntax
816 Since @sc{gasp} is meant to work with assembly code, its statement
817 syntax has no surprises for the assembly programmer.
820 @emph{Whitespace} (blanks or tabs; @emph{not} newline) is partially
821 significant, in that it delimits up to three fields in a line. The
822 amount of whitespace does not matter; you may line up fields in separate
823 lines if you wish, but @sc{gasp} does not require that.
825 @cindex fields of @sc{gasp} source line
827 The @emph{first field}, an optional @dfn{label}, must be flush left in a
828 line (with no leading whitespace) if it appears at all. You may use a
829 colon after the label if you wish; @sc{gasp} neither requires the colon
830 nor objects to it (but will not include it as part of the label name).
832 @cindex directive field
833 The @emph{second field}, which must appear after some whitespace,
834 contains a @sc{gasp} or assembly @dfn{directive}.
836 @cindex argument fields
837 Any @emph{further fields} on a line are @dfn{arguments} to the
838 directive; you can separate them from one another using either commas or
850 @subsection Special syntactic markers
852 @sc{gasp} recognizes a few special markers: to delimit comments, to
853 continue a statement on the next line, to separate symbols from other
854 characters, and to copy text to the output literally. (One other
855 special marker, @samp{\@@}, works only within macro definitions;
856 @pxref{Macros,, Defining your own directives}.)
859 The trailing part of any @sc{gasp} source line may be a @dfn{comment}.
860 A comment begins with the first unquoted comment character (@samp{!} by
861 default), or an escaped or doubled comment character (@samp{\!} or
862 @samp{!!} by default), and extends to the end of a line. You can
863 specify what comment character to use with the @samp{-c} option
864 (@pxref{Invoking GASP,, Command Line Options}). The two kinds of
865 comment markers lead to slightly different treatment:
869 A single, un-escaped comment character generates an assembly comment in
870 the @sc{gasp} output. @sc{gasp} evaluates any preprocessor variables
871 (macro arguments, or variables defined with @code{.ASSIGNA} or
872 @code{.ASSIGNC}) present. For example, a macro that begins like this
875 .MACRO SUM FROM=0, TO=9
880 issues as the first line of output a comment that records the
881 values you used to call the macro.
883 @c comments, preprocessor-only
884 @c preprocessor-only comments
885 @c GASP-only comments
888 Either an escaped comment character, or a double comment character,
889 marks a @sc{gasp} source comment. @sc{gasp} does not copy such comments
890 to the assembly output.
893 @cindex continuation character
895 To @emph{continue a statement} on the next line of the file, begin the
896 second line with the character @samp{+}.
898 @cindex literal copy to output
899 @cindex copying literally to output
900 @cindex preprocessing, avoiding
901 @cindex avoiding preprocessing
902 Occasionally you may want to prevent @sc{gasp} from preprocessing some
903 particular bit of text. To @emph{copy literally} from the @sc{gasp}
904 source to its output, place @samp{\(} before the string to copy, and
905 @samp{)} at the end. For example, write @samp{\(\!)} if you need the
906 characters @samp{\!} in your assembly output.
908 @cindex symbol separator
909 @cindex text, separating from symbols
910 @cindex symbols, separating from text
911 To @emph{separate a preprocessor variable} from text to appear
912 immediately after its value, write a single quote (@code{'}). For
913 example, @samp{.SDATA "\P'1"} writes a string built by concatenating the
914 value of @code{P} and the digit @samp{1}. (You cannot achieve this by
915 writing just @samp{\P1}, since @samp{P1} is itself a valid name for a
916 preprocessor variable.)
919 @subsection String and numeric constants
921 There are two ways of writing @dfn{string constants} in @sc{gasp}: as
922 literal text, and by numeric byte value. Specify a string literal
923 between double quotes (@code{"@var{str}"}). Specify an individual
924 numeric byte value as an absolute expression between angle brackets
925 (@code{<@var{expr}>}. Directives that output strings allow you to
926 specify any number of either kind of value, in whatever order is
927 convenient, and concatenate the result. (Alternate syntax mode
928 introduces a number of alternative string notations; @pxref{Alternate,,
929 Alternate macro syntax}.)
931 @c Details of numeric notation, e.g. base prefixes
932 You can write @dfn{numeric constants} either in a specific base, or in
933 whatever base is currently selected (either 10, or selected by the most
934 recent @code{.RADIX}).
936 To write a number in a @emph{specific base}, use the pattern
937 @code{@var{s}'@var{ddd}}: a base specifier character @var{s}, followed
938 by a single quote followed by digits @var{ddd}. The base specifier
939 character matches those you can specify with @code{.RADIX}: @samp{B} for
940 base 2, @samp{Q} for base 8, @samp{D} for base 10, and @samp{H} for base
941 16. (You can write this character in lower case if you prefer.)
943 @c FIXME! What are rules for recognizing number in deflt base? Whatever
944 @c is left over after parsing other things??
949 @sc{gasp} recognizes symbol names that start with any alphabetic character,
950 @samp{_}, or @samp{$}, and continue with any of the same characters or
951 with digits. Label names follow the same rules.
954 @subsection Arithmetic expressions in GASP
956 @cindex absolute expressions
957 @cindex relocatable expressions
958 There are two kinds of expressions, depending on their result:
959 @dfn{absolute} expressions, which resolve to a constant (that is, they
960 do not involve any values unknown to @sc{gasp}), and @dfn{relocatable}
961 expressions, which must reduce to the form
964 @var{addsym}+@var{const}-@var{subsym}
968 where @var{addsym} and @var{subsym} are assembly symbols of unknown
969 value, and @var{const} is a constant.
971 Arithmetic for @sc{gasp} expressions follows very similar rules to C.
972 You can use parentheses to change precedence; otherwise, arithmetic
973 primitives have decreasing precedence in the order of the following
978 Single-argument @code{+} (identity), @code{-} (arithmetic opposite), or
979 @code{~} (bitwise negation). @emph{The argument must be an absolute
983 @code{*} (multiplication) and @code{/} (division). @emph{Both arguments
984 must be absolute expressions.}
987 @code{+} (addition) and @code{-} (subtraction). @emph{At least one argument
989 @c FIXME! Actually, subtraction doesn't check for this.
992 @code{&} (bitwise and). @emph{Both arguments must be absolute.}
995 @c FIXME! I agree ~ is a better notation than ^ for xor, but is the
996 @c improvement worth differing from C?
997 @code{|} (bitwise or) and @code{~} (bitwise exclusive or; @code{^} in
998 C). @emph{Both arguments must be absolute.}
1001 @node String Builtins
1002 @subsection String primitives
1004 You can use these primitives to manipulate strings (in the argument
1005 field of @sc{gasp} statements):
1008 @item .LEN("@var{str}")
1009 Calculate the length of string @code{"@var{str}"}, as an absolute
1010 expression. For example, @samp{.RES.B .LEN("sample")} reserves six
1013 @item .INSTR("@var{string}", "@var{seg}", @var{ix})
1014 Search for the first occurrence of @var{seg} after position @var{ix} of
1015 @var{string}. For example, @samp{.INSTR("ABCDEFG", "CDE", 0)} evaluates
1016 to the absolute result @code{2}.
1018 The result is @code{-1} if @var{seg} does not occur in @var{string}
1019 after position @var{ix}.
1021 @item .SUBSTR("@var{string}",@var{start},@var{len})
1022 The substring of @var{string} beginning at byte number @var{start} and
1023 extending for @var{len} bytes.
1027 @section Alternate macro syntax
1029 If you specify @samp{-a} or @samp{--alternate} on the @sc{gasp} command
1030 line, the preprocessor uses somewhat different syntax. This syntax is
1031 reminiscent of the syntax of Phar Lap macro assembler, but it
1032 is @emph{not} meant to be a full emulation of Phar Lap or similar
1033 assemblers. In particular, @sc{gasp} does not support directives such
1034 as @code{DB} and @code{IRP}, even in alternate syntax mode.
1036 In particular, @samp{-a} (or @samp{--alternate}) elicits these
1040 @item Preprocessor directives
1041 You can use @sc{gasp} preprocessor directives without a leading @samp{.}
1042 dot. For example, you can write @samp{SDATA} with the same effect as
1046 One additional directive, @code{LOCAL}, is available. @xref{Macros,,
1047 Defining your own directives}, for an explanation of how to use
1051 @item String delimiters
1052 You can write strings delimited in these other ways besides
1053 @code{"@var{string}"}:
1056 @item '@var{string}'
1057 You can delimit strings with single-quote charaters.
1059 @item <@var{string}>
1060 You can delimit strings with matching angle brackets.
1063 @item single-character string escape
1064 To include any single character literally in a string (even if the
1065 character would otherwise have some special meaning), you can prefix the
1066 character with @samp{!} (an exclamation mark). For example, you can
1067 write @samp{<4.3 !> 5.4!!>} to get the literal text @samp{4.3 > 5.4!}.
1069 @item Expression results as strings
1070 You can write @samp{%@var{expr}} to evaluate the expression @var{expr}
1071 and use the result as a string.