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.