[ ÎÏ×ÏÓÔÉ/++ | ÆÏÒÕÍ | wiki | ÔÅÇÉ ]

### éÎÔÅÒÁËÔÉ×ÎÁÑ ÓÉÓÔÅÍÁ ÐÒÏÓÍÏÔÒÁ ÓÉÓÔÅÍÎÙÈ ÒÕËÏ×ÏÄÓÔ× (man-Ï×)

 ôÅÍÁ îÁÂÏÒ ëÁÔÅÇÏÒÉÑ Solaris man FreeBSD man òÁÚÎÙÅ man òÕÓÓËÉÅ man Linux man POSIX man All 1 2 3 4 5 6 7 8 9 [CÐÉÓÏË ÒÕËÏ×ÏÄÓÔ× | ðÅÞÁÔØ]
gasp (1)
• >> gasp (1) ( Linux man: ëÏÍÁÎÄÙ É ÐÒÉËÌÁÄÎÙÅ ÐÒÏÇÒÁÍÍÙ ÐÏÌØÚÏ×ÁÔÅÌØÓËÏÇÏ ÕÒÏ×ÎÑ )
•

## NAME

gasp - GNU Assembler Preprocessor



## SYNOPSIS

gasp [-adpsu] [-c CHAR] [-o OUTFILE] [--alternate] [--commentchar CHAR] [--copysource] [--debug] [-output OUTFILE] [--print] [--unreasonable] INFILE...

gasp [-hv] [--help] [--version]

## DESCRIPTION

gasp preprocesses each INFILE argument and concatenates the results to standard output, for direct consumption by as(1).

Since as is targeted to assemble the output generated by other programs, it doesn't have common facilities such as macros or conditionals that are generally useful when writing assembler by hand. gasp provides this missing functionality.

## OPTIONS

-a, --alternate
Use alternative macro syntax.
-c CHAR, --commentchar CHAR
Use CHAR as the comment character. The default comment character is !'.
-d, --debug
Show debugging statistics. This option produces statistics about the string buffers that gasp allocates internally For each defined buffersize S, it shows the number of strings N that it allocated, in the format

   strings size S : N


These statistics are written to standard error stream, when done preprocessing.

-o OUTFILE, --output OUTFILE
Write the output generated by gasp to OUTFILE. The default is to write to standard output.
-p, --print
Print commented line numbers. No effect if -s is not specified.
-s, --copysource
Print commented source lines.
-u, --unreasonable
Bypass "unreasonable expansion" limit. Since you can define gasp macros inside other macro definitions, the preprocessor normally includes a sanity check. If your program requires more than 1000 nested expansions, gasp normally exits with an error message. Use this option to turn off this check, allowing unlimited nested expansions.
-h, --help
Print a usage message on standard output and exit successfully.
-v, --version
Print version information on standard output then exit successfully.

## PREPROCESSOR COMMANDS

Commands are case-insensitive, and each extends for a line divided in three fields: an optional label, the command itself, and optional argument(s) to the command.

### Conditionals

These directives allow you to include or exclude portions of assembly depending on how a pair of strings or absolute expressions compare.
.AIF ARG1 CMP ARG2
.AIF ARG1 CMP ARG2

Available CMP comparision operators available with strings and absolute expressions:

EQ
Are ARG1 and ARG2 equal?
NE
Are ARG1 and ARG2 different?

Available CMP comparision operators available with absolute expressions only:

LT
Is ARG1 less than ARG2?
LE
Is ARG1 less than or equal to ARG2
GT
Is ARG1 greater than ARG2?
GE
Is ARG1 greater than or equal to ARG2?
.AELSE
Marks the start of assembly code to be included if the condition fails. Optional, and only allowed within a conditional (between .AIF and .AENDI)
.AENDI
Marks the end of an .AIF conditional block.

### Loops

These directives allow you repeat portions of code.
.AREPEAT EXPR
.AENDR

Repeats the assemby code between the .AREPEAT and .AENDR macros as many times as specified by the absolute expression EXPR.
.AWHILE ARG1 CMP ARG2
.AENDW

Repeats the assembly code between the .AWHILE and .AENDW macros as long as the CMP conditional comparision holds true. The format for CMP is the same as for .AIF.
.EXITM
Break out of the loop.

### Variables

Variables can represent strings, registers or the results of expressions. There are two kinds of variables:

* Variables defined with .EQU or .ASSIGN. To evaluate this kind of variable in your assembly output, simply mention its name. These variabes are only evaluated when writing the assembly output, so they shouldn't be used in conditional expressions or .AWHILE loops.

   foo  .EQU   FLIP-64
bar: .EQU   FLIP-64
mov.l  foo, r0


* Variables for use during preprocessing, defined with .ASSIGNC or .ASSIGNA. To evaluate this kind of variable, write \&' before the variable name.

   opcit  .ASSIGNA  47
.AWHILE \&opcit GT 0
.AENDW


Macro arguments are treated almost the same way, but to evaluate them you use the prefix \' rather than \&'

PVAR .EQU EXPR
Assign preprocessor variable PVAR the value of the expression EXPR. There are no restrictions on redefinition.
PVAR .ASSIGN EXPR
Almost the same as .EQU, save that you may not redefine PVAR.
PVAR .ASSIGNA AEXPR
Define a variable with a numeric value, for use during preprocessing. AEXPR must be an absolute expression. There are no restrictions on redefinition.
PVAR .ASSIGNC STR
Define a variable with a string value, for use during preprocessing. There are no restrictions on redefinition.
PVAR .REG (REGISTER)
Define a variable that represents a register. In particular, REGISTER is not evaluated as an expression. There are no restrictions on redefinition.

All these directives accept the variable name in the "label" position, that is at the left margin. You may specify a colon after the variable name if you wish, as in bar' above.

### Macro Definition

The directives .MACRO and .ENDM allow you to define your own macros that generate assembly output.
.MACRO NAME
.MACRO NAME [ARG[=VALUE]...]
Begin the definition of a macro called NAME. If your macro definition requires arguments, specify their names after the macro name, separated by commas or spaces. Default values for macros arguments may be specified in the format ARG=VALUE.

When you call a macro, you can specify the argument values either by position, or by keyword. For example, SUM 9, 17' is equivalent to SUM TO=17, FROM=9'. Macro arguments are preprocessor variables similar to the variables you define with .ASSIGNA or .ASSIGNC; in particular, you can use them in conditionals or loop control. The only difference is the prefix you write to evaluate the variable: for a macro argument, write \ARG', but for a preprocessor variable, write \&VAR'.

NAME .MACRO
NAME .MACRO ( [ARG[=VALUE]...] )
An alternative form of introducing a macro definition: specify the macro name in the label position, and any arguments between parentheses after the name.
.ENDM
Mark the end of a macro definition.
.EXITM
Exit early from the current macro definition, or macro loop.
\@
gasp maintains a counter of how many macros it has executed in this pseudo-variable; you can copy that number to your output with \@', but only within a macro definition.
LOCAL NAME[, NAME...]
Generate a string replacement for each of the NAME argument, and replace any instances of NAME in each macro expansion. The replacement string is unique in the assembly, and different for each separate macro expansion. LOCAL allows you to write macros that define symbols, without fear of conflict between separate macro expansions.

This is only available if you specify --alternate.

### Data

These directives allow you to specify working areas of memory. The directives that initialize memory are:
.DATA EXPR[, EXPR...]
.DATA.B EXPR[, EXPR...]
.DATA.W EXPR[, EXPR...]
.DATA.L EXPR[, EXPR...]
Evaluate arithmetic EXPR expressions, and emit the corresponding as directive (labelled with LAB). The unqualified .DATA emits .long; .DATA.B emits .byte; .DATA.W emits .short; and .DATA.L emits .long.

For example, foo .DATA 1,2,3' emits foo: .long 1,2,3'.

.DATAB REPEAT, EXPR
.DATAB.B REPEAT, EXPR
.DATAB.W REPEAT, EXPR
.DATAB.L REPEAT, EXPR
Emit REPEAT copies of the value of the expression EXPR (using the as directive .fill), being REPEAT an absolute expression with an absolute value. .DATAB.B repeats one-byte values; .DATAB.W repeats two-byte values; and .DATAB.L repeats four-byte values. .DATAB without a suffix repeats four-byte values, just like .DATAB.L.
.SDATA STR...
String data. Emits a concatenation of bytes (no end of string marks are added, unlike in .SDATAZ) of each STR argument given, and optionally separated by commas.
.SDATAB REPEATSTR...
Repeated string data. REPEAT specifies how many copies of the concatenation of every STR argument are emitted.
.SDATAZ STR...
Zero-terminated string data. Like .SDATA, except that a zero byte is written at the end of the string.
.SDATAC STR...
Count-prefixed string data. Like .SDATA, except that gasp precedes the string with a leading one-byte count. For example, .SDATAC "HI"' generates .byte 2,72,73'. Since the count field is only one byte, you can only use .SDATAC for strings less than 256 bytes in length.

Use the .RES, .SRES, .SRESC, and .SRESZ directives to reserve memory and leave it uninitialized. gasp resolves these directives to appropriate calls of the GNU as .space directive.

.RES COUNT
.RES.B COUNT
.RES.W COUNT
.RES.L COUNT
Reserve room for COUNT uninitialized elements of data. The suffix specifies the size of each element: .RES.B reserves COUNT bytes, .RES.W reserves COUNT pairs of bytes, and .RES.L reserves COUNT quartets. .RES without a suffix is equivalent to .RES.L
.SRES COUNT
.SRES.B COUNT
.SRES.W COUNT
.SRES.L COUNT
.SRES is a synonym for .RES.
.SRESC COUNT
.SRESC.B COUNT
.SRESC.W COUNT
.SRESC.L COUNT
Like .SRES, but reserves space for COUNT+1' elements.
.SRESZ COUNT
.SRESZ.B COUNT
.SRESZ.W COUNT
.SRESZ.L COUNT
.SRESZ is a synonym for .SRESC.

### Listings

These directives control as listing directives.
.PRINT LIST
.PRINT NOLIST
Print control. This directive emits the GNU as directive .list or .nolist, according to its argument.
.FORM LIN=LN
.FORM COL=COLS
.FORM LIN=LN COL=COLS
Specify the page size for assembly listings: LN represents the number of lines, and COLS the number of columns. You may specify either page dimension independently, or both together. By default, 60 lines and 132 columns are used. Any values you may have specified in previous instances of .FORM do not carry over as defaults. Emits the .psizef GNU as directive.
Specify STRING as the title of your assembly listings. Emits .title "STRING"'.
.PAGE
Force a new page in assembly listings. Emits .eject.

## MISCELLANEOUS COMMANDS

.ALTERNATE
Use the alternate macro syntax henceforth in the assembly.
.ORG
This command is recognized, but not yet implemented. gasp generates an error message for programs that use .ORG.
gasp understands numbers in any of base 2, 8, 10 or 16. You can encode the base explicitly in any numeric constant. If you write numbers without an explicit indication of the base, the most recent .RADIX S command determines how they are interpreted. S is a case-insensitive letter:
Base 2.
Base 8.
Base 10. This is the original default radix.
Base 16.
.EXPORT NAME
.GLOBAL NAME
Declare NAME global (emits .global NAME). The two directives are synonymous.
.PROGRAM
No effect: silently ignored.
.END
Mark end of each preprocessor file. A warning is issued if the end of file is reached without seeing this command.
.INCLUDE STR
Preprocess the file named by STR, as if its contents appeared where the .INCLUDE directive does. gasp imposes a maximum limit of 30 stacked include files, as a sanity check.
.ALIGN SIZE
Evaluate the absolute expression SIZE, and emit the assembly instruction .align SIZE using the result.

## GASP SYNTAX

Whitespace (blanks or tabs; not newline) is partially significant, in that it delimits up to three fields in a line. The amount of whitespace does not matter.

* First field, an optional "label", must be flush left in a line (with no leading whitespace) if it appears at all, with an optional color after the label name.

* Second field, which must appear after some whitespace, contains a gasp or as directive.

* Further fields on a line are arguments to the directive, separated by either commas or whitespace.

### Special syntactic markers

gasp recognizes a few special markers: to delimit comments, to continue a statement on the next line, to separate symbols from other characters, and to copy text to the output literally (One other special marker, @f', works only within macro definitions)

The trailing part of any source line may be a comment. A comment begins with the first unquoted comment character (!' by default), or an escaped or doubled comment character (\!' or !!' by default), and extends to the end of a line. The two kinds of comment markers lead to slightly different treatment:

!
A single, un-escaped comment character generates an assembly comment in the gasp output. gasp evaluates any preprocessor variables (macro arguments, or variables defined with .ASSIGNA or .ASSIGNC) present. For example, a macro that begins like this

   .MACRO  SUM FROM=0, TO=9
! \FROM \TO


issues as the first line of output a comment that records the values you used to call the macro.

\!
!!
Either an escaped comment character, or a double comment character, marks a gasp source comment. fasp does not copy such comments to the assembly output.

To continue a statement on the next line of the file, begin the second line with the character +'. Occasionally you may want to prevent gasp from preprocessing some particular bit of text. To copy literally from the gasp source to its output, place \(' before the string to copy, and )' at the end. For example, write \(\!)' if you need the characters \!' in your assembly output.

To separate a preprocessor variable from text to appear immediately after its value, write a single quote ('''). For example, .SDATA "P'1"' writes a string built by concatenating the value of P' and the digit 1' (You cannot achieve this by writing just \P1', since P1' is itself a valid name for a preprocessor variable)

### String and numeric constants

There are two ways of writing string constants: as literal text, and by numeric byte value. Specify a string literal between double quotes ("STR"). Specify an individual numeric byte value as an absolute expression between angle brackets (<EXPR>). Directives that output strings allow you to specify any number of either kind of value, in whatever order is convenient, and concatenate the result.

You can write numeric constants either in a specific base, or in whatever base is currently selected by the last .RADIX directive.

To write a number in a specific base, use the pattern S'DDD': a base specifier character S, followed by a single quote followed by digits DDD. The base specifier character matches those you can specify with .RADIX.

### Symbols

gasp recognizes symbol and label names that start with any alphabetic character, _', or \$', and continue with any of the same characters or with digits.

### Arithmetic Expressions

There are two kinds of expressions, depending on their result: absolute expressions, which resolve to a constant (that is, they do not involve any values unknown to gasp), and relocatable expressions, which must reduce to the form

   ADDSYM+CONST-SUBSYM


where ADDSYM and SUBSYM are assembly symbols of unknown value, and CONST is a constant.

Arithmetic for gasp expressions follows very similar rules to C. You can use parentheses to change precedence; otherwise, arithmetic primitives have decreasing precedence in the order of the following list.

* 1. Single-argument +' (identity), -' (arithmetic opposite), or ~' (bitwise negation). The argument must be an absolute expression.

* 2. *' (multiplication) and /' (division). Both arguments must be absolute expressions.

* 3. +' (addition) and -' (subtraction). At least one argument must be absolute.

* 4. &' (bitwise and). Both arguments must be absolute.

* 5. |' (bitwise or) and ~' (bitwise exclusive or; ^' in C). Both arguments must be absolute.

### String Primitives

You can use these primitives to manipulate strings (in the argument field of gasp statements):
.LEN(STR)
Calculate the length of string "STR", as an absolute expression. For example, .RES.B .LEN("sample")' reserves six bytes of memory.
.INSTR(STR, SEG, IX)
Search for the first occurrence of SEG after position IX of STR. The result is -1 if SEG does not occur in STR after position IX.
.SUBSTR(STR, START, LEN)
The substring of STR beginning at byte number START and extending for LEN bytes.

## ALTERNATE MACRO SYNTAX

When the --alternate option is specified, an alternate macro sytax is used by gasp. This syntax reminiscent of the syntax of Phar Lap macro assembler, but it is not meant to be a full emulation of Phar Lap or similar assemblers. In particular, GASP does not support directives such as DB and IRP.

* You can use GASP preprocessor directives without a leading .' dot. For example, you can write SDATA' with the same effect as .SDATA'.

* One additional directive, LOCAL, is available.

* You can write strings delimited like "STRING", 'STRING', or <STRING>

* To include any single character literally in a string (even if the character would otherwise have some special meaning), you can prefix the character with !'. For example, "hello !"world!"".

* You can write %EXPR to evaluate the expression EXPR and use the result as a string.

## EXAMPLES

If we feed fasp with this

           .MACRO  saveregs from=8 to=14
count   .ASSIGNA \from
! save r\from..r\to
.AWHILE  \&count LE \to
mov     r\&count,@-sp
count   .ASSIGNA  \&count + 1
.AENDW
.ENDM

saveregs from=12

foo     .SDATAC "hello"<10>
.END


it generates this as program:

           ! save r12..r14
mov     r12,@-sp
mov     r13,@-sp
mov     r14,@-sp

bar:    mov     #57005+10,r0
foo:    .byte   6,104,101,108,108,111,10
`

as(1)

## NOTES

Report bugs to <bug-gnu-utils@gnu.org> and <hjl@lucon.org>
Man page by Ragnar Hojland Espinosa <ragnar@macula.net>

## Index

NAME
SYNOPSIS
DESCRIPTION
OPTIONS
PREPROCESSOR COMMANDS
Conditionals
Loops
Variables
Macro Definition
Data
Listings
MISCELLANEOUS COMMANDS
GASP SYNTAX
Special syntactic markers
String and numeric constants
Symbols
Arithmetic Expressions
String Primitives
ALTERNATE MACRO SYNTAX
EXAMPLES