| A68k Assembler Directives

Previous | The A68k Assembler | Next

Note: This section has been written entirely by the TIGCC Team. Part of the information comes from `direct.txt` by Mathieu Lacage, but the whole text is completely rewritten and contains more details. Also, some of the directives listed here are not documented in `direct.txt`.
The `A68k` assembler supports the following assembler directives:

arithmetic operators | Arithmetic operators can be used exactly like their C counterparts, except that spaces are not allowed in an expression. But `((1+2)>>3)/4` is a perfectly legitimate `A68k` expression. Of course, you can not use anything other than `+` or `-` on labels and you cannot use arithmetic on registers at all - you will have to use the corresponding assembly instructions.
`INCLUDE "filename.h"` | Includes the file given as a parameter at the current source position. The file is read in as assembly source code, as if it was part of the current assembly source.
`INCBIN "filename.bin"` | Includes the binary content of the file given as a parameter as-is at the current location in the object file output. The file will NOT be assembled, but included as binary data.
`EVEN` | Forces alignment on an even address. The next instruction will be guaranteed to be placed at an even address. This is especially important for `dc.w` or `dc.l` directives, since accessing a word or longword at an odd address causes an address error.
`CNOP displacement,alignment` | Forces alignment on an address which is the sum of displacement, which has to be even, and a multiple of alignment, which has to be a power of 2.
`XDEF label` | Exports the label given as an argument to other object files or to the linker. This also allows linker directives like `xdef _nostub`.
`XREF label` | Imports the label given as an argument. This allows to access variables from other object files even if the '-g' switch is not specified. Since TIGCC specifies '-g' by default, there is no real need for this directive.
`PUBLIC label` | Imports or exports the label given as an argument, depending on whether it is part of the current source file or not. We recommend using `XDEF` or `XREF` instead when possible, since they clearly specify what is meant. But `PUBLIC` is useful when used in a common header file for multiple source files.
`SECTION "sectname"` | Sets the section the following code will be written to. This is especially useful to make `A68k` use the same section as `GCC`: `.data`, in order to make sure the linking order of `GCC` files first is respected. (Note: You can deliberately NOT specify `SECTION ".data"` if you want the `A68k` file to be the main file.)
`BSS` | Specifies the section the following code will be written to as a "BSS section", a section which will not be initialized at runtime, so it can contain only storage place which does not need to be initialized. Also, BSS sections are not allowed in `_nostub` mode.
`CSEG` | Creates a section called "`CODE`" where the code will be written to. This directive is not really useful in TIGCC, since both code and data are written to the `.data` section by `GCC` and `GNU as`.
`DSEG` | Creates a section called "`DATA`" where the code will be written to. Do not use this directive in TIGCC. Instead, specify `SECTION .data`, which is the section name used by `GCC` and `GNU as` for data sections.
`END` | Marks the end of the source file. This directive is now optional since v.2.71.F3c.
`DC.{B|W|L} data1,data2,...` | (Define Constant(s)) Will insert all the arguments as immediate data into the object file. For example, `DC.L $12345678` will insert the bytes `0x12`, `0x34`, `0x56` and `0x78` into the resulting object file. `DC.B 'Hello, World!',0` will insert the null-terminated string `"Hello, World!"` into the resulting object file.
`DS.{B|W|L} n` | (Define Storage) Will insert n bytes, words or longwords (depending on the size specified) of zeros (`0`, NOT `'0'`) into the resulting object file.
`DCB.{B|W|L} n,data` | (Define Constant Block) Will act as n times the `DC.B data` instruction. It will insert the immediated data specified by data n times into the resulting object file.

`macroName MACRO
instructions
ENDM`

This declares a macro so that `macroName` can be used as if it was an instruction, with the difference that unlike opcodes, macro names are case-sensitive. You can also pass arguments to a macro. Those are referenced by a macro as `\n`, where n is the number of the argument, starting from 1. `\0` indicates the instruction size. `\@` indicates the number of the current macro, which is useful to create unique labels of the form `\@label` or `\\@localLbl`. Therefore:

    PUSH MACRO
         MOVE.\0 \1,-(a7)
         ENDM

(defined in "OS.h") allows you to use: `PUSH.L #1` when in fact you mean: `MOVE.L #1,-(a7)`.

`<expression>` | Makes sure expression will be treated as a single macro parameter, even if it contains separators like commas, semicolons or whitespace.
`constant EQU value` OR: `constant = value` | Defines a symbolic constant. Wherever constant is encountered in the code, it will be replaced by value. Note that value can also be an expression, not only a single number.
`regAlias EQUR register` | Defines an alias for a register. For example, if you are using `a5` to hold the address of the jump table in your whole program, you can write `jumpTbl EQUR a5`, and then use `jumpTbl` wherever you would use `a5`.
`regListAlias EQUR regList` | Defines an alias for a list of registers, for use in the `MOVEM` instruction. The syntax of regList is the same as in the `MOVEM` instruction. For example, if you are frequently using `MOVEM.L d0-d7/a0-a6,-(a7)` and `MOVEM.L (a7)+,d0-d7/a0-a6`, you might define: `all REG d0-d7/a0-a6`, and then use `all` wherever you would use `d0-d7/a0-a6`.
`variable SET value` | Defines a symbolic variable. Wherever variable is encountered in the code, it will be replaced by value. But contrary to an `EQU` constant, a `SET` variable can be modified. It can therefore be used as a counter for example, as in: `counter SET counter+1`.
`IFEQ value instructions ENDC` | The instructions in the block will be parsed and assembled if and only if value equals 0. You can also write `ENDIF` as a synonym for `ENDC`.
`IFNE value instructions ENDC` | The instructions in the block will be parsed and assembled if and only if value does not equal 0. You can also write `ENDIF` as a synonym for `ENDC`.
`IFGE value instructions ENDC` | The instructions in the block will be parsed and assembled if and only if value is greater than or equal to 0. You can also write `ENDIF` as a synonym for `ENDC`.
`IFGT value instructions ENDC` | The instructions in the block will be parsed and assembled if and only if value is greater than 0. You can also write `ENDIF` as a synonym for `ENDC`.
`IFLE value instructions ENDC` | The instructions in the block will be parsed and assembled if and only if value is less than or equal to 0. You can also write `ENDIF` as a synonym for `ENDC`.
`IFLT value instructions ENDC` | The instructions in the block will be parsed and assembled if and only if value is less than 0. You can also write `ENDIF` as a synonym for `ENDC`.
`IFC string1,string2 instructions ENDC` | The instructions in the block will be parsed and assembled if and only if string1 and string2 are identical (after expansion of `EQU` constants). You can also write `ENDIF` as a synonym for `ENDC`.
`IFNC string1,string2 instructions ENDC` | The instructions in the block will be parsed and assembled if and only if string1 and string2 are different (after expansion of `EQU` constants). You can also write `ENDIF` as a synonym for `ENDC`.
`IFD value instructions ENDC` | The instructions in the block will be parsed and assembled if and only if value is a defined symbol. You can also write `ENDIF` as a synonym for `ENDC`.
`IFND value instructions ENDC` | The instructions in the block will be parsed and assembled if and only if value is not a defined symbol. You can also write `ENDIF` as a synonym for `ENDC`.
`NEAR [register]` | Enables the small code and data model.
`FAR` | Disables the small code and data model after a `NEAR` directive.

`ORG expression`

Places the code following the directive at the address specified by expression, which must be relocatable (that is, of the form `label+number`, where label is a backward reference, not a forward reference). If that address is located before the current position, the code previously generated there will be overwritten. If that adress is located after the current position, the space will be filled with zeros (`0`, NOT `'0'`).

`RORG offset`

Places the code following the directive at the offset offset, which must be a number, from the beginning of the current object file section. If that address is located before the current position, the code previously generated there will be overwritten. If that adress is located after the current position, the space will be filled with zeros (`0`, NOT `'0'`). However, if `RORG` is specified before the first executable instruction and in the default section (before any `SECTION`, `BSS`, `CSEG` or `DSEG` directive), no spacing will be generated, so it has the effect of adding the number address to all absolute references, thereby pre-relocating the code to that fixed address. But such an use of this directive is not useful in TIGCC, as assembly programs on the TI-89/92+ can be at any place in memory, and the linker always generates a relocation table which allows AMS to take care of the relocation automatically.

`NOLIST` | The code following this directive will not appear in the listing file created when the '-l' or '-x' switch is specified.
`LIST` | Reenables the listing of code after a `NOLIST` directive.
`PAGE` | Inserts a form feed into the listing file created when the '-l' or '-x' switch is specified.
`SPC [n]` | Skips n lines, or 1 line if n is omitted, in the listing file created when the '-l' or '-x' switch is specified.
`TTL string` OR: `TITLE string` | Sets the title on the pages of the listing file created when the '-l' or '-x' switch is specified to string. Also begins a new page when specified on the middle of a page.
`IDNT "name"` | Sets the program unit name in the S-record generated when the '-s' switch is specified, to name. The quotes can be omitted. This directive is not useful in TIGCC, since TIGCC does not use S-records.
`\localLbl` | Defines a local label, a label which can be accessed only in the space between the 2 global labels surrounding it. This mainly serves to avoid name conflicts: 2 or more local labels can have the same name as long as they are separated by a global label.
`\localLbl@labelNum` | Defines a local enumeration label, invented mainly for use in macros. The idea is that labelNum can be a variable name which can be expanded while keeping localLbl unchanged. But it is usually a better idea to use `\@label` or `\\@localLbl` instead, which will automatically generate unique labels.