[ First ] [ Previous ] [ Next ] [ Last ] [ Manuals ]

Chapter 3. Using Directives

This chapter describes the directives that are available for the assembler.

NOTE

Some directives are not available for every assembler.

By default, most directives must begin with a period (.). However if you clear the Directives begin with '.' checkbox of the Assembler settings panel, you can omit the period.

NOTE

You can specify several preprocessor directives using the C/C++ preprocessor format.

This chapter discusses the following topics:

Macro Directives
Conditional Preprocessor Directives
Section Control Directives
Scope Control Directives
Symbol Definition Directives
Data Declaration Directives
Assembler Control Directives
Debugging Directives

Macro Directives

The following directives let you create macros:

macro
endm
mexit
#define

For more information on macros, see "Using Macros".

macro

label .macro [ parameter ] [ ,parameter ] ...

Begins the definition of a macro named label, with the specified parameters.

`end`m

.endm

Ends a macro definition.

mexit

.mexit

Causes the assembler to stop macro processing before the .endm statement is reached and resume execution with the statement following the macro call.

#define

#define name [ (parms) ] assembly_statement [ ; ] [ \ ]
assembly_statement [ ; ] [ \ ]
assembly_statement
parms ::= parameter [ ,parameter ]...

Defines a macro named name with the specified parameters. You can extend assembly_statement by typing a backslash (\) and continuing the statement on the next physical line. You also can specify multiple assembly statements in the macro by typing a semicolon (;) followed by a backslash (\) and typing a new assembly statement on the next physical line. For more information, see "Defining a macro with the #define directive".

NOTE

The #define directive is a preprocessor directive.

Conditional Preprocessor Directives

Conditional directives create a conditional assembly block. If you wrap some code with .ifdef and .endif you can control whether that code is included in compilation. This is useful for making several different builds that are slightly different.

You must use conditional directives together to form a complete block. The assembler also contains several variations of .if to make it easier to make blocks that test strings for equality, test whether a symbol is defined, and so on.

NOTE

You can specify several of the conditional preprocessor directives using the C/C++ preprocessor format:

#if #ifdef #ifndef #else #elif #endif

These directives function identically whether preceded by a pound sign (#) or a period with two exceptions. You cannot use the pound sign form of the directive in a macro, and the period (.) form of the #elif directive is .elseif.

This section discusses the following topics:

if
ifdef
ifndef
ifc
ifnc
endif
elseif
else
Other conditional preprocessor directives

if

.if bool-expr

Specifies the beginning of a conditional assembly block, where bool-expr is a Boolean expression. If bool-expr is true, the assembler processes the statements associated with the .if directive. If bool-expr is false, the assembler skips the statements associated with the .if directive.

Each .if directive must have a matching .endif directive.

NOTE

A Boolean expression is a special type of arithmetic expression. The assembler interprets a Boolean expression that evaluates to zero as false and a Boolean expression that evaluates to a nonzero result as true. For more information on expressions, see "Expressions".

ifdef

.ifdef symbol

Specifies the beginning of a conditional assembly block and tests whether symbol is already defined. If symbol was defined previously, the assembler processes the statements associated with the .ifdef directive. If symbol is not yet defined, the assembler skips the statements associated with the .ifdef directive.

Each .ifdef directive must have a matching .endif directive.

ifndef

.ifndef symbol

Specifies the beginning of a conditional assembly block and tests whether symbol is not yet defined. If symbol is not yet defined, the assembler processes the statements associated with the .ifndef directive. If symbol is already defined, the assembler skips the statements associated with the .ifndef directive.

Each .ifndef directive must have a matching .endif directive.

ifc

.ifc string1, string2

Specifies the beginning of a conditional assembly block and tests whether string1 and string2 are equal. The comparison is case-sensitive. If the strings are equal, the assembler processes the statements associated with the .ifc directive. If the strings are not equal, the assembler skips the statements associated with the .ifc directive.

Each .ifc directive must have a matching .endif directive.

ifnc

.ifnc string1, string2

Specifies the beginning of a conditional assembly block and tests whether string1 and string2 are not equal. The comparison is case-sensitive. If the strings are not equal, the assembler processes the statements associated with the .ifnc directive. If the strings are equal, the assembler skips the statements associated with the .ifnc directive.

Each .ifnc directive must have a matching .endif directive.

endif

.endif

Specifies the end of a conditional assembly block. Each type of .if directive must have a matching .endif directive.

elseif

.elseif bool-expr

You can use the .elseif directive to create a series of directives that together comprise a logical multilevel if-then-else statement, the syntax of which follows:

  .if bool-expr statement-group   [ .elseif bool-expr statement-group ]...
  [ .else statement-group ]
  .endif

In the preceding syntax statement, bool-expr is any Boolean expression and statement-group is any group of assembly language statements.

Expanding the syntax as follows helps to explain the flow of the statement:

  .if bool-expr-1   statement-group-1
  .elseif bool-expr-2
  statement-group-2
  .elseif bool-expr-3
  statement-group-3
  .elseif bool-expr-4
  statement-group-4
  .else
  statement-group-5
  .endif

In the preceding syntax statement, if bool-expr-1 is true, the assembler executes statement-group-1 (the first group of conditional assembly language statements) and goes to the .endif directive. If bool-expr-1 is false, the assembler skips statement-group-1 and tests bool-expr-2 in the first .elseif directive.

If bool-expr-2 is true, the assembler executes statement-group-2 and goes to the .endif directive. If bool-expr-2 is false, the assembler skips statement-group-2 and tests bool-expr-3 in the second .elseif directive.

The assembler continues evaluating the Boolean expressions in succeeding .elseif directives until it comes to a Boolean expression that evaluates to true. If none of the .elseif directives have a Boolean expression that evaluates to true, the assembler processes the statements associated with the .else directive, if there is one.

else

.else

Marks the beginning of a conditional assembly block to execute if the Boolean expressions for an .if directive and its associated .elseif directives are false.

NOTE

Using an .else directive is optional.

Other conditional preprocessor directives

For compatibility with other assemblers, the assembler also supports the following directives:

.ifeq (if equal)
.ifne (if not equal)
.iflt (if less than)
.ifle (if less than or equal)
.ifgt (if greater than)
.ifge (if greater than or equal)

Section Control Directives

The following directives identify the different sections of an assembly file:

text
data
rodata
bss
sdata
sdata2
sbss
debug
previous
offset
section

text

.text

Specifies an executable code section. This must be in front of the actual code in a file.

data

.data

Specifies an initialized read-write data section.

rodata

.rodata

Specifies an initialized read-only data section.

bss

.bss

Specifies an uninitialized read-write data section.

sdata

.sdata

Specifies a small data section as initialized and read-write.

sdata2

.sdata2

Specifies a small data section as initialized and read-only.

sbss

.sbss

Specifies a small data section as uninitialized and read-write.

debug

.debug

Specifies a debug section. If you enable the debugger, the assembler automatically generates some debug information for your project. However, you use special directives in the debug section that provide the debugger with more detailed information. For more information on the debug directives, see "Debugging Directives."

.previous

Reverts to the previous section. This switch toggles between the current section and the previous section.

offset

.offset [expression]

Defines a record. The optional parameter expression specifies the initial location counter. The record definition extends until the start of the next section.

Within a record, you can use only the following directives:

.equ .set .textequ

.align .org .space

.byte .short .long

.space .ascii .asciz

.float .double

The data declaration directives (like .byte and .short) update the location counter but do not allocate any storage.

Listing 3.1 shows a sample record definition.

A record definition with the offset directive:

					.offset
top:					.short				0
left:					.short				0 
bottom:					.short				0
right:					.short				0
rectSize					.equ				*

section

For the ELF (Executable and Linkable Format) object file format, the .section directive has the following syntax:

.section name [ ,alignment ] [ ,type ] [ ,flags ]

Defines a section in an object file. Use this directive to create arbitrary relocatable sections, including sections to be loaded at an absolute address.

Table 3.1 describes the syntax elements for the ELF .section directive.

Syntax descriptions for ELF .section directive:

Syntax Element
Description

name

The name of the section.

alignment

Specifies the alignment boundary of the section.

type

Numeric value that indicates the ELF section type. The default value for type is the type of the code section. For more information, see Table 3.2.

flags

Numeric value that indicates the ELF section flags. The default value for flags is the value of the flags of the code section. For more information, see Table 3.3.

Syntax Element	Description
name	The name of the section.
alignment	Specifies the alignment boundary of the section.
type	Numeric value that indicates the ELF section type. The default value for type is the type of the code section. For more information, see `Table 3.2`.
flags	Numeric value that indicates the ELF section flags. The default value for flags is the value of the flags of the code section. For more information, see `Table 3.3`.

The following example specifies a section named vector with an alignment of 4 bytes:

.section vector,4

Table 3.2 defines the ELF section types.

ELF section types:

Type
Name
Description

0

NULL

Indicates that the section header is inactive.

1

PROGBITS

Indicates that the section contains information defined by the program.

2

SYMTAB

Indicates that the section contains a symbol table.

3

STRTAB

Indicates that the section contains a string table.

4

RELA

Indicates that the section contains relocation entries with explicit addends.

5

HASH

Indicates that the section contains a symbol hash table.

6

DYNAMIC

Indicates that the section contains information used for dynamic linking.

7

NOTE

Indicates that the section contains information that marks the file, often for compatibility purposes between programs.

8

NOBITS

Indicates that the section occupies no space in the object file.

9

REL

Indicates that the section contains relocation entries without explicit addends.

10

SHLIB

Indicates that the section has unspecified semantics and, therefore, does not conform to the Application Binary Interface (ABI) standard.

11

DYNSYM

Indicates that the section contains a minimal set of symbols used for dynamic linking.

Type	Name	Description
0	NULL	Indicates that the section header is inactive.
1	PROGBITS	Indicates that the section contains information defined by the program.
2	SYMTAB	Indicates that the section contains a symbol table.
3	STRTAB	Indicates that the section contains a string table.
4	RELA	Indicates that the section contains relocation entries with explicit addends.
5	HASH	Indicates that the section contains a symbol hash table.
6	DYNAMIC	Indicates that the section contains information used for dynamic linking.
7	NOTE	Indicates that the section contains information that marks the file, often for compatibility purposes between programs.
8	NOBITS	Indicates that the section occupies no space in the object file.
9	REL	Indicates that the section contains relocation entries without explicit addends.
10	SHLIB	Indicates that the section has unspecified semantics and, therefore, does not conform to the Application Binary Interface (ABI) standard.
11	DYNSYM	Indicates that the section contains a minimal set of symbols used for dynamic linking.

Table 3.3 defines the ELF section flags.

ELF section flags:

Flag
Name
Description

0x00000001

WRITE

Indicates that the section contains data that is writable during execution.

0x00000002

ALLOC

Indicates that the section occupies memory during execution.

0x00000004

EXECINSTR

Indicates that the section contains executable machine instructions.

0xF0000000

MASKPROC

Indicates that the bits specified in this mask are reserved for processor-specific purposes.

Flag	Name	Description
0x00000001	WRITE	Indicates that the section contains data that is writable during execution.
0x00000002	ALLOC	Indicates that the section occupies memory during execution.
0x00000004	EXECINSTR	Indicates that the section contains executable machine instructions.
0xF0000000	MASKPROC	Indicates that the bits specified in this mask are reserved for processor-specific purposes.

Scope Control Directives

The assembler provides the following directives that let you import and export labels:

global
extern
public

For more information on labels, see "Labels".

NOTE

You cannot import or export equates or local labels.

global

.global label [ ,label ]

Instructs the assembler to export the specified labels, that is, make them available to other files.

Use the .extern or .public directive to reference the labels in another file.

extern

.extern label [ ,label ]

Instructs the assembler to import the specified labels, that is, to find the label definitions in another file.

Use the .global or .public directive to export the labels from another file.

public

.public label [ ,label ]

Declares that the specified labels are public. If the labels are already defined in the same file, the assembler exports them, that is, makes them available to other files. If the equates are not already defined, the assembler imports them, that is, finds the label definitions in another file.

Symbol Definition Directives

You can use the following directives to create equates:

set
equal sign (=)
equ
textequ

set

equate .set expression

Temporarily assigns the value expression to equate. You can change the value of equate after defining it.

equal sign (=)

equate = expression

Temporarily assigns the value expression to equate. You can change the value of equate after defining it.

NOTE

This directive is equivalent to .set and is available only for compatibility with assemblers provided by other companies.

equ

equate .equ expression

Permanently assigns the value expression to equate. You cannot change the value of equate after defining it.

textequ

equate .textequ "string"

Substitutes equate with the text you specify in string. You can use this directive, which helps to port existing code, to give new names to machine instructions, directives, and operands.

Whenever you use equate, the assembler replaces it with string before performing any other processing on that source line. Listing 3.2 shows examples of .textequ statements.

textequ examples:
dc.b .textequ ".byte" endc .textequ ".endif"

Data Declaration Directives

The assembler provides the following types of directives that initialize data:

Integer Directives
String Directives
Floating-Point Directives

Integer Directives

The following directives initialize blocks of integer data:

byte
short
long
space
fill

byte

[ label ] .byte expression [ ,expression ]

Declares an initialized block of bytes with the name label. The assembler allocates one byte for each expression. Each expression must fit in a byte.

short

[ label ] .short expression [ ,expression ]

Declares an initialized block of 16-bit short integers with the name label. The assembler allocates 16 bits for each expression. Each expression must fit in 16 bits.

long

[ label ] .long expression [ ,expression ]

Declares an initialized block of 32-bit short integers with the name label. The assembler allocates 32 bits for each expression. Each expression must fit in 32 bits.

space

[ label ] .space expression

Declares a block of zero-initialized bytes with the name label. The assembler allocates a block expression bytes long and initializes each byte to zero.

fill

[ label ] .fill expression

Declares a block of zero-initialized bytes with the name label. The assembler allocates a block expression bytes long and initializes each byte to zero.

String Directives

The following directives initialize blocks of character data:

ascii
asciz

A string can contain any of the escape sequences shown in Table 3.4.

Escape sequences:

Sequence
Description

\b
Backspace

\n
Line feed (ASCII character 10)

\r
Return (ASCII character 13)

\t
Tab

\"
Double quote

\\
Backslash

\nnn
Octal value of \nnn

Sequence	Description
\b	Backspace
\n	Line feed (ASCII character 10)
\r	Return (ASCII character 13)
\t	Tab
\"	Double quote
\\	Backslash
\nnn	Octal value of \nnn

ascii

[ label ] .ascii "string"

Declares a block of storage for the string string with the name label. The assembler allocates a byte for each character in string.

asciz

[ label ] .asciz "string"

Declares a zero-terminated block of storage for the string string with the name label. The assembler allocates a byte for each character in string. The assembler then allocates an extra byte at the end and initializes the byte to zero.

Floating-Point Directives

The following directives initialize blocks of floating-point data:

float
double

float

[ label ] .float value [ ,value ]

Declares an initialized block of 32-bit floating-point numbers with the name label. The assembler allocates 32 bits for each value value. Each value must fit in the specified size.

double

[ label ] .double value [ ,value ]

Declares an initialized block of 64-bit floating-point numbers with the name label. The assembler allocates 64 bits for each value value. Each value must fit in the specified size.

Assembler Control Directives

These directives let you control how the assembler emits code:

align
endian
error
include
pragma
org
option

align

.align expression

Aligns the location counter to the next multiple of the expression. The expression must be a power of 2, such as 2, 4, 8, 16, or 32.

endian

.endian big | little

Specifies the byte ordering for the target processor.

NOTE

You can use this directive only for processors that allow you to change the byte ordering.

error

.error "error"

Prints error to the Errors & Warnings window in the CodeWarrior IDE.

include

.include filename

Causes the assembler to switch input to filename. The assembler takes input from the specified file. When the assembler reaches the end of the file, it begins taking input from the assembly statement line that follows the .include directive.

The file specified by filename can contain an .include directive for another file.

pragma

.pragma pragma-type setting

Tells the assembler to assemble the code using a particular pragma setting.

org

.org expression

Changes the location counter to the value of expression. The addresses of the subsequent assembly statements start at the new value of the location counter. The value of expression must be greater than the current value of the location counter.

option

.option keyword setting

Sets the assembler options as described in Table 3.5. Specifying reset sets the option to its previous setting. Using reset a second time resets the option to the setting before the current setting.

Option keywords:

Keyword
Description

alignment off | on | reset
Controls whether data is aligned on natural boundary. This does not correspond to any option in the Assembler settings panel.

branchsize 8 | 16 | 32
Specifies the size of forward branch displacement. This keyword applies only to the x86 and 68K assemblers. This does not correspond any option in the Assembler settings panel.

case off | on | reset
Specifies whether identifiers are case sensitive. If this option is on, identifiers are case sensitive. If this option is off, identifiers are not case sensitive. This corresponds to the Case-sensitive identifiers checkbox of the Assembler settings panel, described in "Case-sensitive identifiers".

colon off | on | reset
Specifies whether labels must end with a colon (:). If this option is on, you must specify each label with a colon at the end. If this option is off, you can omit the colon from the end of label names that start in the first column. (This option corresponds to the Labels must end with ':' checkbox of the Assembler settings panel, described in "Labels must end with ':'".)

no_at_macros off | on
If this option is on, the assembler does not allow macros that use $AT. If this option is off, the assembler produces a warning if a macro uses $AT.

period off | on | reset
Specifies whether the assembler requires a period (.) in directive names. If this option is on, each directive must start with a period. If this option is off, you can omit the period in front of a directive. This corresponds to the Directives begin with '.' checkbox of the Assembler settings panel, described in "Directives begin with '.'".

reorder off | on | reset
Specifies whether the assembler inserts a NOP (no operation) instruction after jumps and branches. If this option is on, the assembler inserts a NOP instruction. If this option is off, the assembler does not insert a NOP instruction, and you can substitute an instruction of your choice after jumps and branches.

space off | on | reset
Specifies whether the assembler allows a space in an operand field. If this option is on, operand fields can contain spaces. If this option is off, a space in the operand field signals the start of a comment. (This option corresponds to the Allow space in operand field checkbox of the Assembler settings panel, described in "Allow space in operand field".)

Keyword	Description
alignment off \| on \| reset	Controls whether data is aligned on natural boundary. This does not correspond to any option in the Assembler settings panel.
branchsize 8 \| 16 \| 32	Specifies the size of forward branch displacement. This keyword applies only to the x86 and 68K assemblers. This does not correspond any option in the Assembler settings panel.
case off \| on \| reset	Specifies whether identifiers are case sensitive. If this option is on, identifiers are case sensitive. If this option is off, identifiers are not case sensitive. This corresponds to the `Case-sensitive identifiers` checkbox of the Assembler settings panel, described in `"Case-sensitive identifiers"`.
colon off \| on \| reset	Specifies whether labels must end with a colon (:). If this option is on, you must specify each label with a colon at the end. If this option is off, you can omit the colon from the end of label names that start in the first column. (This option corresponds to the `Labels must end with ':'` checkbox of the Assembler settings panel, described in `"Labels must end with ':'"`.)
`no_at_macros off \| on`	If this option is on, the assembler does not allow macros that use $AT. If this option is off, the assembler produces a warning if a macro uses $AT.
period off \| on \| reset	Specifies whether the assembler requires a period (.) in directive names. If this option is on, each directive must start with a period. If this option is off, you can omit the period in front of a directive. This corresponds to the `Directives begin with '.'` checkbox of the Assembler settings panel, described in `"Directives begin with '.'"`.
reorder off \| on \| reset	Specifies whether the assembler inserts a NOP (no operation) instruction after jumps and branches. If this option is on, the assembler inserts a NOP instruction. If this option is off, the assembler does not insert a NOP instruction, and you can substitute an instruction of your choice after jumps and branches.
space off \| on \| reset	Specifies whether the assembler allows a space in an operand field. If this option is on, operand fields can contain spaces. If this option is off, a space in the operand field signals the start of a comment. (This option corresponds to the `Allow space in operand field` checkbox of the Assembler settings panel, described in `"Allow space in operand field"`.)

Debugging Directives

When you enable the debugger, the assembler automatically generates some debug information for your project. However, you can use the following directives in the debug section to provide the debugger with more detailed information:

file
function
line
size
type

NOTE

The preceding directives are allowed only in the .debug and .text sections of an assembly file.

For the debugging directives to work, you must enable debugging for the particular file that contains them (in the Project window).

file

.file "filename"

Specifies the name of the file containing the source code. This directive allows generated assembly to be correlated with the source code.

NOTE

The .file directive must precede the other debugging directives in the assembly language file.

function

.function "func", label, length

Specifies that the subroutine func begins at label and is length bytes long.

line

.line number

Specifies the absolute line number in the current source file that generated the subsequent code or data. The first line in the file is numbered 1.

size

.size symbol, expression

Specifies that symbol is expression bytes long.

type

.type symbol, type

Specifies that symbol is of type type, where type can be either @function (a function) or @object (a variable).

[ First ] [ Previous ] [ Next ] [ Last ] [ Manuals ]

Visit the Metrowerks website at: http://www.metrowerks.com
For assistance contact Metrowerks Technical Support at: cw_support@metrowerks.com
Copyright © 2000, Metrowerks Corp. All rights reserved.

Last updated: July 20, 2000

`.equ`	`.set`	`.textequ`
`.align`	`.org`	`.space`
`.byte`	`.short`	`.long`
`.space`	`.ascii`	`.asciz`
`.float`	`.double`