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
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 [ -a | --alternate ]
171 [ -c @var{char} | --commentchar @var{char} ]
172 [ -d | --debug ] [ -h | --help ]
173 [ -o @var{outfile} | --output @var{outfile} ]
174 [ -p | --print ] [ -s | --copysource ]
175 [ -u | --unreasonable ] [ -v | --version ]
180 @item @var{infile} @dots{}
181 @c FIXME! Why not stdin as default infile?
182 The input file names. You must specify at least one input file; if you
183 specify more, @sc{gasp} preprocesses them all, concatenating the output
184 in the order you list the @var{infile} arguments.
186 Mark the end of each input file with the preprocessor command
187 @code{.END}. @xref{Other Commands,, Miscellaneous commands}.
191 Use alternative macro syntax. @xref{Alternate,, Alternate macro
192 syntax}, for a discussion of how this syntax differs from the default
195 @cindex comment character, changing
196 @cindex semicolon, as comment
197 @cindex exclamation mark, as comment
198 @cindex shriek, as comment
199 @cindex bang, as comment
200 @cindex @code{!} default comment char
201 @cindex @code{;} as comment char
202 @item -c '@var{char}'
203 @itemx --commentchar '@var{char}'
204 Use @var{char} as the comment character. The default comment character
205 is @samp{!}. For example, to use a semicolon as the comment character,
206 specify @w{@samp{-c ';'}} on the @sc{gasp} command line. Since
207 assembler command characters often have special significance to command
208 shells, it is a good idea to quote or escape @var{char} when you specify
211 For the sake of simplicity, all examples in this manual use the default
212 comment character @samp{!}.
216 Show debugging statistics. In this version of @sc{gasp}, this option
217 produces statistics about the string buffers that @sc{gasp} allocates
218 internally. For each defined buffersize @var{s}, @sc{gasp} shows the
219 number of strings @var{n} that it allocated, with a line like this:
222 strings size @var{s} : @var{n}
226 @sc{gasp} displays these statistics on the standard error stream, when
231 Display a summary of the @sc{gasp} command line options.
233 @item -o @var{outfile}
234 @itemx --output @var{outfile}
235 Write the output in a file called @var{outfile}. If you do not use the
236 @samp{-o} option, @sc{gasp} writes its output on the standard output
241 Print line numbers. @sc{gasp} obeys this option @emph{only} if you also
242 specify @samp{-s} to copy source lines to its output. With @samp{-s
243 -p}, @sc{gasp} displays the line number of each source line copied
244 (immediately after the comment character at the beginning of the line).
248 Copy the source lines to the output file. Use this option
249 to see the effect of each preprocessor line on the @sc{gasp} output.
250 @sc{gasp} places a comment character (@samp{!} by default) at
251 the beginning of each source line it copies, so that you can use this
252 option and still assemble the result.
255 @itemx --unreasonable
256 Bypass ``unreasonable expansion'' limit. Since you can define @sc{gasp}
257 macros inside other macro definitions, the preprocessor normally
258 includes a sanity check. If your program requires more than 1,000
259 nested expansions, @sc{gasp} normally exits with an error message. Use
260 this option to turn off this check, allowing unlimited nested
265 Display the @sc{gasp} version number.
269 @chapter Preprocessor Commands
271 @sc{gasp} commands have a straightforward syntax that fits in well with
272 assembly conventions. In general, a command extends for a line, and may
273 have up to three fields: an optional label, the command itself, and
274 optional arguments to the command. You can write commands in upper or
275 lower case, though this manual shows them in upper case. @xref{Syntax
276 Details,, Details of the GASP syntax}, for more information.
291 @section Conditional assembly
293 The conditional-assembly directives allow you to include or exclude
294 portions of an assembly depending on how a pair of expressions, or a
295 pair of strings, compare.
297 The overall structure of conditionals is familiar from many other
298 contexts. @code{.AIF} marks the start of a conditional, and precedes
299 assembly for the case when the condition is true. An optional
300 @code{.AELSE} precedes assembly for the converse case, and an
301 @code{.AENDI} marks the end of the condition.
303 @c FIXME! Why doesn't -u turn off this check?
304 You may nest conditionals up to a depth of 100; @sc{gasp} rejects
305 nesting beyond that, because it may indicate a bug in your macro
308 @c FIXME! Why isn't there something like cpp's -D option? Conditionals
309 @c would be much more useful if there were.
310 Conditionals are primarily useful inside macro definitions, where you
311 often need different effects depending on argument values.
312 @xref{Macros,, Defining your own directives}, for details about defining
316 @item .AIF @var{expra} @var{cmp} @var{exprb}
317 @itemx .AIF "@var{stra}" @var{cmp} "@var{strb}"
319 The governing condition goes on the same line as the @code{.AIF}
320 preprocessor command. You may compare either two strings, or two
323 When you compare strings, only two conditional @var{cmp} comparison
324 operators are available: @samp{EQ} (true if @var{stra} and @var{strb}
325 are identical), and @samp{NE} (the converse).
327 When you compare two expressions, @emph{both expressions must be
328 absolute} (@pxref{Expressions,, Arithmetic expressions in GASP}). You
329 can use these @var{cmp} comparison operators with expressions:
333 Are @var{expra} and @var{exprb} equal? (For strings, are @var{stra} and
334 @var{strb} identical?)
337 Are @var{expra} and @var{exprb} different? (For strings, are @var{stra}
338 and @var{strb} different?
341 Is @var{expra} less than @var{exprb}? (Not allowed for strings.)
344 Is @var{expra} less than or equal to @var{exprb}? (Not allowed for strings.)
347 Is @var{expra} greater than @var{exprb}? (Not allowed for strings.)
350 Is @var{expra} greater than or equal to @var{exprb}? (Not allowed for
355 Marks the start of assembly code to be included if the condition fails.
356 Optional, and only allowed within a conditional (between @code{.AIF} and
360 Marks the end of a conditional assembly.
364 @section Repetitive sections of assembly
366 Two preprocessor directives allow you to repeatedly issue copies of the
367 same block of assembly code.
370 @item .AREPEAT @var{aexp}
372 If you simply need to repeat the same block of assembly over and over a
373 fixed number of times, sandwich one instance of the repeated block
374 between @code{.AREPEAT} and @code{.AENDR}. Specify the number of
375 copies as @var{aexp} (which must be an absolute expression). For
376 example, this repeats two assembly statements three times in succession:
387 @item .AWHILE @var{expra} @var{cmp} @var{exprb}
389 @itemx .AWHILE @var{stra} @var{cmp} @var{strb}
391 To repeat a block of assembly depending on a conditional test, rather
392 than repeating it for a specific number of times, use @code{.AWHILE}.
393 @code{.AENDW} marks the end of the repeated block. The conditional
394 comparison works exactly the same way as for @code{.AIF}, with the same
395 comparison operators (@pxref{Conditionals,, Conditional assembly}).
397 Since the terms of the comparison must be absolute expression,
398 @code{.AWHILE} is primarily useful within macros. @xref{Macros,,
399 Defining your own directives}.
402 @cindex loops, breaking out of
403 @cindex breaking out of loops
404 You can use the @code{.EXITM} preprocessor directive to break out of
405 loops early (as well as to break out of macros). @xref{Macros,,
406 Defining your own directives}.
409 @section Preprocessor variables
411 You can use variables in @sc{gasp} to represent strings, registers, or
412 the results of expressions.
414 You must distinguish two kinds of variables:
417 Variables defined with @code{.EQU} or @code{.ASSIGN}. To evaluate this
418 kind of variable in your assembly output, simply mention its name. For
419 example, these two lines define and use a variable @samp{eg}:
429 @emph{Do not use} this kind of variable in conditional expressions or
430 while loops; @sc{gasp} only evaluates these variables when writing
434 Variables for use during preprocessing. You can define these
435 with @code{.ASSIGNC} or @code{.ASSIGNA}. To evaluate this
436 kind of variable, write @samp{\&} before the variable name; for example,
448 @sc{gasp} treats macro arguments almost the same way, but to evaluate
449 them you use the prefix @samp{\} rather than @samp{\&}.
450 @xref{Macros,, Defining your own directives}.
454 @item @var{pvar} .EQU @var{expr}
455 @c FIXME! Anything to beware of re GAS directive of same name?
456 Assign preprocessor variable @var{pvar} the value of the expression
457 @var{expr}. There are no restrictions on redefinition; use @samp{.EQU}
458 with the same @var{pvar} as often as you find it convenient.
460 @item @var{pvar} .ASSIGN @var{expr}
461 Almost the same as @code{.EQU}, save that you may not redefine
462 @var{pvar} using @code{.ASSIGN} once it has a value.
463 @c FIXME!! Supposed to work this way, apparently, but on 9feb94 works
466 @item @var{pvar} .ASSIGNA @var{aexpr}
467 Define a variable with a numeric value, for use during preprocessing.
468 @var{aexpr} must be an absolute expression. You can redefine variables
469 with @code{.ASSIGNA} at any time.
471 @item @var{pvar} .ASSIGNC "@var{str}"
472 Define a variable with a string value, for use during preprocessing.
473 You can redefine variables with @code{.ASSIGNC} at any time.
475 @item @var{pvar} .REG (@var{register})
476 Use @code{.REG} to define a variable that represents a register. In
477 particular, @var{register} is @emph{not evaluated} as an expression.
478 You may use @code{.REG} at will to redefine register variables.
481 All these directives accept the variable name in the ``label'' position,
482 that is at the left margin. You may specify a colon after the variable
483 name if you wish; the first example above could have started @samp{eg:}
484 with the same effect.
486 @c pagebreak makes for better aesthetics---ensures macro and expansion together
489 @section Defining your own directives
491 The commands @code{.MACRO} and @code{.ENDM} allow you to define macros
492 that generate assembly output. You can use these macros with a syntax
493 similar to built-in @sc{gasp} or assembler directives. For example,
494 this definition specifies a macro @code{SUM} that adds together a range of
495 consecutive registers:
499 .MACRO SUM FROM=0, TO=9
502 COUNT .ASSIGNA \FROM+1
503 .AWHILE \&COUNT LE \TO
505 COUNT .ASSIGNA \&COUNT+1
512 With that definition, @samp{SUM 0,5} generates this assembly output:
527 @item .MACRO @var{macname}
528 @itemx .MACRO @var{macname} @var{macargs} @dots{}
529 Begin the definition of a macro called @var{macname}. If your macro
530 definition requires arguments, specify their names after the macro name,
531 separated by commas or spaces. You can supply a default value for any
532 macro argument by following the name with @samp{=@var{deflt}}. For
533 example, these are all valid @code{.MACRO} statements:
537 Begin the definition of a macro called @code{COMM}, which takes no
540 @item .MACRO PLUS1 P, P1
541 @itemx .MACRO PLUS1 P P1
542 Either statement begins the definition of a macro called @code{PLUS1},
543 which takes two arguments; within the macro definition, write
544 @samp{\P} or @samp{\P1} to evaluate the arguments.
546 @item .MACRO RESERVE_STR P1=0 P2
547 Begin the definition of a macro called @code{RESERVE_STR}, with two
548 arguments. The first argument has a default value, but not the second.
549 After the definition is complete, you can call the macro either as
550 @samp{RESERVE_STR @var{a},@var{b}} (with @samp{\P1} evaluating to
551 @var{a} and @samp{\P2} evaluating to @var{b}), or as @samp{RESERVE_STR
552 ,@var{b}} (with @samp{\P1} evaluating as the default, in this case
553 @samp{0}, and @samp{\P2} evaluating to @var{b}).
556 When you call a macro, you can specify the argument values either by
557 position, or by keyword. For example, @samp{SUM 9,17} is equivalent to
558 @samp{SUM TO=17, FROM=9}. Macro arguments are preprocessor variables
559 similar to the variables you define with @samp{.ASSIGNA} or
560 @samp{.ASSIGNC}; in particular, you can use them in conditionals or for
561 loop control. (The only difference is the prefix you write to evaluate
562 the variable: for a macro argument, write @samp{\@var{argname}}, but for
563 a preprocessor variable, write @samp{\&@var{varname}}.)
565 @item @var{name} .MACRO
566 @itemx @var{name} .MACRO ( @var{macargs} @dots{} )
567 @c FIXME check: I think no error _and_ no args recognized if I use form
568 @c NAME .MACRO ARG ARG
569 An alternative form of introducing a macro definition: specify the macro
570 name in the label position, and the arguments (if any) between
571 parentheses after the name. Defaulting rules and usage work the same
572 way as for the other macro definition syntax.
575 Mark the end of a macro definition.
578 Exit early from the current macro definition, @code{.AREPEAT} loop, or
581 @cindex number of macros executed
582 @cindex macros, count executed
584 @sc{gasp} maintains a counter of how many macros it has
585 executed in this pseudo-variable; you can copy that number to your
586 output with @samp{\@@}, but @emph{only within a macro definition}.
588 @item LOCAL @var{name} [ , @dots{} ]
589 @emph{Warning: @code{LOCAL} is only available if you select ``alternate
590 macro syntax'' with @samp{-a} or @samp{--alternate}.} @xref{Alternate,,
591 Alternate macro syntax}.
593 Generate a string replacement for each of the @var{name} arguments, and
594 replace any instances of @var{name} in each macro expansion. The
595 replacement string is unique in the assembly, and different for each
596 separate macro expansion. @code{LOCAL} allows you to write macros that
597 define symbols, without fear of conflict between separate macro expansions.
603 In assembly code, you often need to specify working areas of memory;
604 depending on the application, you may want to initialize such memory or
605 not. @sc{gasp} provides preprocessor directives to help you avoid
606 repetitive coding for both purposes.
608 You can use labels as usual to mark the data areas.
616 @subsection Initialized data
618 These are the @sc{gasp} directives for initialized data, and the standard
619 @sc{gnu} assembler directives they expand to:
622 @item .DATA @var{expr}, @var{expr}, @dots{}
623 @itemx .DATA.B @var{expr}, @var{expr}, @dots{}
624 @itemx .DATA.W @var{expr}, @var{expr}, @dots{}
625 @itemx .DATA.L @var{expr}, @var{expr}, @dots{}
626 Evaluate arithmetic expressions @var{expr}, and emit the corresponding
627 @code{as} directive (labelled with @var{lab}). The unqualified
628 @code{.DATA} emits @samp{.long}; @code{.DATA.B} emits @samp{.byte};
629 @code{.DATA.W} emits @samp{.short}; and @code{.DATA.L} emits
632 For example, @samp{foo .DATA 1,2,3} emits @samp{foo: .long 1,2,3}.
634 @item .DATAB @var{repeat}, @var{expr}
635 @itemx .DATAB.B @var{repeat}, @var{expr}
636 @itemx .DATAB.W @var{repeat}, @var{expr}
637 @itemx .DATAB.L @var{repeat}, @var{expr}
638 @c FIXME! Looks like gasp accepts and ignores args after 2nd.
639 Make @code{as} emit @var{repeat} copies of the value of the expression
640 @var{expr} (using the @code{as} directive @code{.fill}).
641 @samp{.DATAB.B} repeats one-byte values; @samp{.DATAB.W} repeats
642 two-byte values; and @samp{.DATAB.L} repeats four-byte values.
643 @samp{.DATAB} without a suffix repeats four-byte values, just like
646 @c FIXME! Allowing zero might be useful for edge conditions in macros.
647 @var{repeat} must be an absolute expression with a positive value.
649 @item .SDATA "@var{str}" @dots{}
650 String data. Emits a concatenation of bytes, precisely as you specify
651 them (in particular, @emph{nothing is added to mark the end} of the
652 string). @xref{Constants,, String and numeric constants}, for details
653 about how to write strings. @code{.SDATA} concatenates multiple
654 arguments, making it easy to switch between string representations. You
655 can use commas to separate the individual arguments for clarity, if you
658 @item .SDATAB @var{repeat}, "@var{str}" @dots{}
659 Repeated string data. The first argument specifies how many copies of
660 the string to emit; the remaining arguments specify the string, in the
661 same way as the arguments to @code{.SDATA}.
663 @item .SDATAZ "@var{str}" @dots{}
664 Zero-terminated string data. Just like @code{.SDATA}, except that
665 @code{.SDATAZ} writes a zero byte at the end of the string.
667 @item .SDATAC "@var{str}" @dots{}
668 Count-prefixed string data. Just like @code{.SDATA}, except that
669 @sc{gasp} precedes the string with a leading one-byte count. For
670 example, @samp{.SDATAC "HI"} generates @samp{.byte 2,72,73}. Since the
671 count field is only one byte, you can only use @code{.SDATAC} for
672 strings less than 256 bytes in length.
676 @subsection Uninitialized data
678 @c FIXME! .space different on some platforms, notably HPPA. Config?
679 Use the @code{.RES}, @code{.SRES}, @code{.SRESC}, and @code{.SRESZ}
680 directives to reserve memory and leave it uninitialized. @sc{gasp}
681 resolves these directives to appropriate calls of the @sc{gnu}
682 @code{as} @code{.space} directive.
685 @item .RES @var{count}
686 @itemx .RES.B @var{count}
687 @itemx .RES.W @var{count}
688 @itemx .RES.L @var{count}
689 Reserve room for @var{count} uninitialized elements of data. The
690 suffix specifies the size of each element: @code{.RES.B} reserves
691 @var{count} bytes, @code{.RES.W} reserves @var{count} pairs of bytes,
692 and @code{.RES.L} reserves @var{count} quartets. @code{.RES} without a
693 suffix is equivalent to @code{.RES.L}.
695 @item .SRES @var{count}
696 @itemx .SRES.B @var{count}
697 @itemx .SRES.W @var{count}
698 @itemx .SRES.L @var{count}
699 @c FIXME! This is boring. Shouldn't it at least have a different
700 @c default size? (e.g. the "S" suggests "string", for which .B
701 @c would be more appropriate)
702 @code{.SRES} is a synonym for @samp{.RES}.
704 @item .SRESC @var{count}
705 @itemx .SRESC.B @var{count}
706 @itemx .SRESC.W @var{count}
707 @itemx .SRESC.L @var{count}
708 Like @code{.SRES}, but reserves space for @code{@var{count}+1} elements.
710 @item .SRESZ @var{count}
711 @itemx .SRESZ.B @var{count}
712 @itemx .SRESZ.W @var{count}
713 @itemx .SRESZ.L @var{count}
714 Like @code{.SRES}, but reserves space for @code{@var{count}+1} elements.
718 @section Assembly listing control
720 The @sc{gasp} listing-control directives map straightforwardly to
721 related @sc{gnu} @code{as} directives.
726 Print control. This directive emits the @sc{gnu} @code{as} directive
727 @code{.list} or @code{.nolist}, according to its argument. @xref{List,,
728 @code{.list}, as.info, Using as}, for details on how these directives
731 @item .FORM LIN=@var{ln}
732 @itemx .FORM COL=@var{cols}
733 @itemx .FORM LIN=@var{ln} COL=@var{cols}
734 Specify the page size for assembly listings: @var{ln} represents the
735 number of lines, and @var{cols} the number of columns. You may specify
736 either page dimension independently, or both together. If you do not
737 specify the number of lines, @sc{gasp} assumes 60 lines; if you do not
738 specify the number of columns, @sc{gasp} assumes 132 columns.
739 (Any values you may have specified in previous instances of @code{.FORM}
740 do @emph{not} carry over as defaults.) Emits the @code{.psize}
743 @item .HEADING @var{string}
744 Specify @var{string} as the title of your assembly listings. Emits
745 @samp{.title "@var{string}"}.
748 Force a new page in assembly listings. Emits @samp{.eject}.
752 @section Miscellaneous commands
756 Use the alternate macro syntax henceforth in the assembly.
757 @xref{Alternate,, Alternate macro syntax}.
760 @c FIXME! This is very strange, since _GAS_ understands .org
761 This command is recognized, but not yet implemented. @sc{gasp}
762 generates an error message for programs that use @code{.ORG}.
765 @c FIXME no test cases in testsuite/gasp
766 @sc{gasp} understands numbers in any of base two, eight, ten, or
767 sixteen. You can encode the base explicitly in any numeric constant
768 (@pxref{Constants,, String and numeric constants}). If you write
769 numbers without an explicit indication of the base, the most recent
770 @samp{.RADIX @var{s}} command determines how they are interpreted.
771 @var{s} is a single letter, one of the following:
781 Base 10. This is the original default radix.
787 You may specify the argument @var{s} in lower case (any of @samp{bqdh})
788 with the same effects.
790 @item .EXPORT @var{name}
791 @itemx .GLOBAL @var{name}
792 @c FIXME! No test cases in testsuite/gasp
793 Declare @var{name} global (emits @samp{.global @var{name}}). The two
794 directives are synonymous.
797 No effect: @sc{gasp} accepts this directive, and silently ignores it.
800 Mark end of each preprocessor file. @sc{gasp} issues a warning if it
801 reaches end of file without seeing this command.
803 @item .INCLUDE "@var{str}"
804 Preprocess the file named by @var{str}, as if its contents appeared
805 where the @code{.INCLUDE} directive does. @sc{gasp} imposes a maximum
806 limit of 30 stacked include files, as a sanity check.
807 @c FIXME! Why is include depth not affected by -u?
809 @item .ALIGN @var{size}
810 @c FIXME! Why is this not utterly pointless?
811 Evaluate the absolute expression @var{size}, and emit the assembly
812 instruction @samp{.align @var{size}} using the result.
816 @section Details of the GASP syntax
818 Since @sc{gasp} is meant to work with assembly code, its statement
819 syntax has no surprises for the assembly programmer.
822 @emph{Whitespace} (blanks or tabs; @emph{not} newline) is partially
823 significant, in that it delimits up to three fields in a line. The
824 amount of whitespace does not matter; you may line up fields in separate
825 lines if you wish, but @sc{gasp} does not require that.
827 @cindex fields of @sc{gasp} source line
829 The @emph{first field}, an optional @dfn{label}, must be flush left in a
830 line (with no leading whitespace) if it appears at all. You may use a
831 colon after the label if you wish; @sc{gasp} neither requires the colon
832 nor objects to it (but will not include it as part of the label name).
834 @cindex directive field
835 The @emph{second field}, which must appear after some whitespace,
836 contains a @sc{gasp} or assembly @dfn{directive}.
838 @cindex argument fields
839 Any @emph{further fields} on a line are @dfn{arguments} to the
840 directive; you can separate them from one another using either commas or
852 @subsection Special syntactic markers
854 @sc{gasp} recognizes a few special markers: to delimit comments, to
855 continue a statement on the next line, to separate symbols from other
856 characters, and to copy text to the output literally. (One other
857 special marker, @samp{\@@}, works only within macro definitions;
858 @pxref{Macros,, Defining your own directives}.)
861 The trailing part of any @sc{gasp} source line may be a @dfn{comment}.
862 A comment begins with the first unquoted comment character (@samp{!} by
863 default), or an escaped or doubled comment character (@samp{\!} or
864 @samp{!!} by default), and extends to the end of a line. You can
865 specify what comment character to use with the @samp{-c} option
866 (@pxref{Invoking GASP,, Command Line Options}). The two kinds of
867 comment markers lead to slightly different treatment:
871 A single, un-escaped comment character generates an assembly comment in
872 the @sc{gasp} output. @sc{gasp} evaluates any preprocessor variables
873 (macro arguments, or variables defined with @code{.ASSIGNA} or
874 @code{.ASSIGNC}) present. For example, a macro that begins like this
877 .MACRO SUM FROM=0, TO=9
882 issues as the first line of output a comment that records the
883 values you used to call the macro.
885 @c comments, preprocessor-only
886 @c preprocessor-only comments
887 @c GASP-only comments
890 Either an escaped comment character, or a double comment character,
891 marks a @sc{gasp} source comment. @sc{gasp} does not copy such comments
892 to the assembly output.
895 @cindex continuation character
897 To @emph{continue a statement} on the next line of the file, begin the
898 second line with the character @samp{+}.
900 @cindex literal copy to output
901 @cindex copying literally to output
902 @cindex preprocessing, avoiding
903 @cindex avoiding preprocessing
904 Occasionally you may want to prevent @sc{gasp} from preprocessing some
905 particular bit of text. To @emph{copy literally} from the @sc{gasp}
906 source to its output, place @samp{\(} before the string to copy, and
907 @samp{)} at the end. For example, write @samp{\(\!)} if you need the
908 characters @samp{\!} in your assembly output.
910 @cindex symbol separator
911 @cindex text, separating from symbols
912 @cindex symbols, separating from text
913 To @emph{separate a preprocessor variable} from text to appear
914 immediately after its value, write a single quote (@code{'}). For
915 example, @samp{.SDATA "\P'1"} writes a string built by concatenating the
916 value of @code{P} and the digit @samp{1}. (You cannot achieve this by
917 writing just @samp{\P1}, since @samp{P1} is itself a valid name for a
918 preprocessor variable.)
921 @subsection String and numeric constants
923 There are two ways of writing @dfn{string constants} in @sc{gasp}: as
924 literal text, and by numeric byte value. Specify a string literal
925 between double quotes (@code{"@var{str}"}). Specify an individual
926 numeric byte value as an absolute expression between angle brackets
927 (@code{<@var{expr}>}. Directives that output strings allow you to
928 specify any number of either kind of value, in whatever order is
929 convenient, and concatenate the result. (Alternate syntax mode
930 introduces a number of alternative string notations; @pxref{Alternate,,
931 Alternate macro syntax}.)
933 @c Details of numeric notation, e.g. base prefixes
934 You can write @dfn{numeric constants} either in a specific base, or in
935 whatever base is currently selected (either 10, or selected by the most
936 recent @code{.RADIX}).
938 To write a number in a @emph{specific base}, use the pattern
939 @code{'@var{s}@var{ddd}}: a single quote, followed by a base specifier
940 character @var{s}, followed by digits @var{ddd}. The base specifier
941 character matches those you can specify with @code{.RADIX}: @samp{B} for
942 base 2, @samp{Q} for base 8, @samp{D} for base 10, and @samp{H} for base
943 16. (You can write this character in lower case if you prefer.)
945 @c FIXME! What are rules for recognizing number in deflt base? Whatever
946 @c is left over after parsing other things??
951 @sc{gasp} recognizes symbol names that start with any alphabetic character,
952 @samp{_}, or @samp{$}, and continue with any of the same characters or
953 with digits. Label names follow the same rules.
956 @subsection Arithmetic expressions in GASP
958 @cindex absolute expressions
959 @cindex relocatable expressions
960 There are two kinds of expressions, depending on their result:
961 @dfn{absolute} expressions, which resolve to a constant (that is, they
962 do not involve any values unknown to @sc{gasp}), and @dfn{relocatable}
963 expressions, which must reduce to the form
966 @var{addsym}+@var{const}-@var{subsym}
970 where @var{addsym} and @var{subsym} are assembly symbols of unknown
971 value, and @var{const} is a constant.
973 Arithmetic for @sc{gasp} expressions follows very similar rules to C.
974 You can use parentheses to change precedence; otherwise, arithmetic
975 primitives have decreasing precedence in the order of the following
980 Single-argument @code{+} (identity), @code{-} (arithmetic opposite), or
981 @code{~} (bitwise negation). @emph{The argument must be an absolute
985 @code{*} (multiplication) and @code{/} (division). @emph{Both arguments
986 must be absolute expressions.}
989 @code{+} (addition) and @code{-} (subtraction). @emph{At least one argument
991 @c FIXME! Actually, subtraction doesn't check for this.
994 @code{&} (bitwise and). @emph{Both arguments must be absolute.}
997 @c FIXME! I agree ~ is a better notation than ^ for xor, but is the
998 @c improvement worth differing from C?
999 @code{|} (bitwise or) and @code{~} (bitwise exclusive or; @code{^} in
1000 C). @emph{Both arguments must be absolute.}
1003 @node String Builtins
1004 @subsection String primitives
1006 You can use these primitives to manipulate strings (in the argument
1007 field of @sc{gasp} statements):
1010 @item .LEN("@var{str}")
1011 Calculate the length of string @code{"@var{str}"}, as an absolute
1012 expression. For example, @samp{.RES.B .LEN("sample")} reserves six
1015 @item .INSTR("@var{string}", "@var{seg}", @var{ix})
1016 Search for the first occurrence of @var{seg} after position @var{ix} of
1017 @var{string}. For example, @samp{.INSTR("ABCDEFG", "CDE", 0)} evaluates
1018 to the absolute result @code{2}.
1020 The result is @code{-1} if @var{seg} does not occur in @var{string}
1021 after position @var{ix}.
1023 @item .SUBSTR("@var{string}",@var{start},@var{len})
1024 The substring of @var{string} beginning at byte number @var{start} and
1025 extending for @var{len} bytes.
1029 @section Alternate macro syntax
1031 If you specify @samp{-a} or @samp{--alternate} on the @sc{gasp} command
1032 line, the preprocessor uses somewhat different syntax. This syntax is
1033 reminiscent of the syntax of Phar Lap macro assembler, but it
1034 is @emph{not} meant to be a full emulation of Phar Lap or similar
1035 assemblers. In particular, @sc{gasp} does not support directives such
1036 as @code{DB} and @code{IRP}, even in alternate syntax mode.
1038 In particular, @samp{-a} (or @samp{--alternate}) elicits these
1042 @item Preprocessor directives
1043 You can use @sc{gasp} preprocessor directives without a leading @samp{.}
1044 dot. For example, you can write @samp{SDATA} with the same effect as
1048 One additional directive, @code{LOCAL}, is available. @xref{Macros,,
1049 Defining your own directives}, for an explanation of how to use
1052 @item String delimiters
1053 You can write strings delimited in two other ways besides
1054 @code{"@var{string}"}:
1057 @item '@var{string}'
1058 You can delimit strings with single-quote charaters.
1060 @item <@var{string}>
1061 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!}.
1070 @item Expression results as strings
1071 You can write @samp{%@var{expr}} to evaluate the expression @var{expr}
1072 and use the result as a string.