7 ASSEMBLER DIRECTIVES

This chapter contains the following sections:

Overview
Debugging
Assembly Control
Symbol Definition
Data Definition/Storage Allocation
Macros and Conditional Assembly
.Directives
.ACCUM Directive
.ALIGN Directive
.ASCII Directive
.ASCIIZ Directive
.BYTE Directive
.CALLS Directive
.COMMENT Directive
.DEFINE Directive
.DOUBLE Directive
.DUP Directive
.DUPA Directive
.DUPC Directive
.DUPF Directive
.END Directive
.ENDIF Directive
.ENDM Directive
.EQU Directive
.EXITM Directive
.EXTERN Directive
.FAIL Directive
.FLOAT Directive
.FRACT Directive
.GLOBAL Directive
.HALF Directive
.IF Directive
.INCLUDE Directive
.LOCAL Directive
.MACRO Directive
.MESSAGE Directive
.NAME Directive
.ORG Directive
.PMACRO Directive
.SDECL Directive
.SECT Directive
.SET Directive
.SFRACT Directive
.SPACE Directive
.SYMB Directive
.UNDEF Directive
.WARNING Directive
.WORD Directive

7.1 Overview

Assembler directives, or pseudo instructions, are used to control the assembly process. Rather than being translated into a TriCore or PCP machine instruction, assembler directives are interpreted by the assembler. The directives perform actions such as assembly control, listing control, defining symbols or changing the location counter. Upper and lower case letters are considered equivalent for assembler directives.

All directives valid for the TriCore assembler astri also apply to the PCP assembler aspcp, unless explicitly stated otherwise.

Assembler directives can be grouped by function into five types:

1. Debugging

2. Assembly control

3. Symbol definition

4. Data definition/storage allocation

5. Macros and conditional assembly

7.1.1 Debugging

The compiler generates the following directives to pass high level language symbolic debug information via the assembler into the object file:

.CALLS - Pass call information to object file. Used to build a call tree at link time.

.SYMB - Pass symbolic debug information

7.1.2 Assembly Control

The directives used for assembly control are:

.ALIGN - Specify alignment

.COMMENT - Start comment lines. This directive is not permitted in .IF/.ELIF/.ELSE/.ENDIF constructs and .MACRO/.DUP definitions.

.DEFINE - Define substitution string

.END - End of source program

.FAIL - Programmer generated error message

.INCLUDE - Include secondary file

.MESSAGE - Programmer generated message

.NAME - Identification name for object file

.ORG - Define a nameless section

.SDECL - Define section name and attributes

.SECT - Activate section

.UNDEF - Undefine .DEFINE symbol

.WARNING - Programmer generated warning

7.1.3 Symbol Definition

The directives used to control symbol definition are:

.EQU - Equate symbol to a value;
accepts forward references

.EXTERN - External symbol declaration;
also permitted in module body

.GLOBAL - Global symbol declaration;
also permitted in module body

.LOCAL - Local symbol declaration

.SET - Set symbol to a value;
accepts forward references

7.1.4 Data Definition/Storage Allocation

The directives used to control constant data definition and storage allocation are:

.ACCUM - Define 64-bit constant of 17Q46 format

.ASCII - Define ASCII string

.ASCIIZ - Define NULL padded ASCII string

.BYTE - Define constant byte

.DOUBLE - Define 64-bit floating-point constant

.FLOAT - Define 32-bit floating-point constant

.FRACT - Define 32-bit constant fraction

.HALF - Define constant half word

.SFRACT - Define 16-bit constant fraction

.SPACE - Define storage

.WORD - Define constant word

7.1.5 Macros and Conditional Assembly

The directives used for macros and conditional assembly are:

.DUP - Duplicate sequence of source lines

.DUPA - Duplicate sequence with arguments

.DUPC - Duplicate sequence with characters

.DUPF - Duplicate sequence in loop

.ENDIF - End of conditional assembly

.ENDM - End of macro definition

.EXITM - Exit macro

.IF - Conditional assembly directive

.MACRO - Macro definition

.PMACRO - Purge macro definition

7.2 Directives

The rest of this chapter contains an alphabetical list of the assembler directives.

.ACCUM

Syntax:

[label:] .ACCUM arg[,arg]...

Description:

Define 64-bit constant(s) of 17Q46 format. The .ACCUM directive allocates and initializes two words (64-bits) of memory for each arg argument. arg can be a constant, a symbol, or an expression.The .ACCUM directive may have one or more arguments separated by commas. Multiple arguments are stored in successive address locations. If multiple arguments are present, one or more of them can be null (two adjacent commas), in which case the corresponding address location will be filled with zeros. An error will occur if the evaluated argument value is out of the range [-217, 217>.

label, if present, will be assigned the value of the run-time location counter at the start of the directive processing.

Examples:

ACC:  .accum  0.1,0.2,0.3

.fract , .sfract

.ALIGN

Syntax:

.ALIGN expression

Description:

Align the location counter. The expression must be represented by a value of 2k. The default alignment is on a multiple of 1 byte. expression must be greater than 0. If expression is not a value of 2k, a warning is issued and the alignment will be set to the next 2k value. Alignment will be performed once at the place where you write the .align pseudo. The start of a section is aligned automatically to the largest alignment value occurring in that section.

Depending on the section type the assembler has two cases for this directive.

- Relocatable sections
The section will be aligned on the calculated alignment boundary. A gap is generated depending on the current relative location counter for this section.

- Absolute sections
The section location is not changed.
A gap is generated according to the current absolute address.

Examples:

.align 4         ;align at 4 bytes
lab1: .align 6   ;not a 2k value.
                 ;a warning is issued
                 ;lab1 is aligned on 8 bytes

.ASCII

Syntax:

[label:] .ASCII string [, string]...

Description:

Define list of ASCII characters. The .ASCII directive allocates and initializes an array of memory for each string argument. No NULL byte is added to the end of the array. Therefore, the behavior is identical to the .BYTE directive with a string argument.

Examples:

HELLO: .ascii "Hello world"
       ;Is the same as  .byte "Hello world"

.asciiz, .byte

.ASCIIZ

Syntax:

[label:] .ASCIIZ string [, string]...

Description:

Define list of ASCII characters. The .ASCIIZ directive allocates and initializes an array of memory for each string argument. A NULL byte is added to the end of each array.

Examples:

HELLO: .asciiz "Hello world"
       ;Is the same as  .byte "Hello world",0

.ascii , .byte

.BYTE

Syntax:

[label:] .BYTE arg[,arg]...

Description:

Define Constant Byte. The .BYTE directive allocates and initializes a byte of memory for each arg argument. arg can be a numeric constant, a single or multiple character string constant, a symbol, or an expression. The .BYTE directive may have one or more arguments separated by commas. Multiple arguments are stored in successive address locations. If multiple arguments are present, one or more of them can be null (two adjacent commas), in which case the corresponding address location will be filled with zeros. An error will occur if the evaluated argument value is too large to represent in a single byte.

label, if present, will be assigned the value of the run-time location counter at the start of the directive processing.

Integer arguments are stored as is, but must be byte values (e.g. within the range 0-255). Single and multiple character strings are handled in the following manner:

1. Single character strings are stored in a byte whose bits represent the ASCII value of the character.

Example: 'R' = 0x52

2. Multiple character strings represent bytes composed of the ASCII representation of the characters in the string.

Example:

Examples:

TABLE:  .byte 14,253,0x62,'ABCD'
CHARS:  .byte 'A','B','C','D'

.space , .half , .word

.CALLS

Syntax:

.CALLS 'caller', 'callee'

Description:

Create a flow graph reference between caller and callees. The linker needs this information to build a flow graph. caller and callee are names of functions.

Examples:

.calls 'main', 'nfunc'

See also the section Linker Output in the chapter Linker.

.COMMENT

Syntax:

.COMMENT delimiter
.
.
delimiter

Description:

Start Comment Lines. The .COMMENT directive is used to define one or more lines as comments. The first non-blank character after the .COMMENT directive is the comment delimiter. The two delimiters are used to define the comment text. The line containing the second comment delimiter will be considered the last line of the comment. The comment text can include any printable characters and the comment text will be produced in the source listing as it appears in the source file.

A label is not allowed with this directive.

This directive is not permitted in .IF/.ELIF/.ELSE/.ENDIF constructs and .MACRO/.DUP definitions.

Examples:

.comment     + This is a one line comment +
.comment     * This is a multiple line 
               comment. Any number of lines
               can be placed between the two
               delimiters.
             *

.DEFINE

Syntax:

.DEFINE symbol string

Description:

Define Substitution String. The .DEFINE directive is used to define substitution strings that will be used on all following source lines. All succeeding lines will be searched for an occurrence of symbol, which will be replaced by string. This directive is useful for providing better documentation in the source program. symbol must adhere to the restrictions for labels. That is, the first character must be alphabetic or the underscore (_), and the remainder of which must be either alphanumeric or the underscore (_). A warning will result if a new definition of a previously defined symbol is attempted.

Macros represent a special case. .DEFINE directive translations will be applied to the macro definition as it is encountered. When the macro is expanded any active .DEFINE directive translations will again be applied.

A label is not allowed with this directive.

Examples:

If the following .DEFINE directive occurred in the first part of the source program:

     .define ARRAYSIZ '10 * SAMPLSIZ'

then the source line below:

     .space  ARRAYSIZ

would be transformed by the assembler to the following:

     .space 10 * SAMPLSIZ

.undef

.DOUBLE

Syntax:

[label:] .DOUBLE arg[,arg]...

Description:

Define 64-bit floating-point constant(s) in IEEE-754 double precision format. The .DOUBLE directive allocates and initializes a double-word (64-bits) of memory for each arg argument. arg can be a constant, a symbol, or an expression. The constant can be expressed as a signed whole number with fraction or the "e" format as that in the C language. 12.457 and +0.27E-13 are legal floating-point constants.

The .DOUBLE directive may have one or more arguments separated by commas. Multiple arguments are stored in successive address locations. If multiple arguments are present, one or more of them can be null (two adjacent commas), in which case the corresponding address location will be filled with zeros. An error will occur if the evaluated argument value is too large to represent in a single word.

label, if present, will be assigned the value of the run-time location counter at the start of the directive processing.

Examples:

DBL:  .double  0.1,0.2,0.3

.float

.DUP

Syntax:

[label:] .DUP expression
.
.
.ENDM

Description:

Duplicate Sequence of Source Lines. The sequence of source lines between the .DUP and .ENDM directives will be duplicated by the number specified by the integer expression. If the expression evaluates to a number less than or equal to 0, the sequence of lines will not be included in the assembler output. The expression result must be an absolute integer and cannot contain any forward references to address labels (labels that have not already been defined). The .DUP directive may be nested to any level.

label, if present, will be assigned the value of the run-time location counter at the start of the .DUP directive processing.

Examples:

The sequence of source input statements,

    COUNT .set 3
          .dup COUNT          ; NOP BY COUNT
          NOP
          .endm

would generate the following in the source listing:

     COUNT .set 3
          .dup COUNT          ; NOP BY COUNT
          NOP
          .endm

     ;    NOP
     ;    NOP
     ;    NOP

.dupa , .dupc , .dupf , .endm , .macro

.DUPA

Syntax:

[label:] .DUPA dummy,arg[,arg]...
.
.
.ENDM

Description:

Duplicate Sequence With Arguments. The block of source statements defined by the .DUPA and .ENDM directives will be repeated for each argument. For each repetition, every occurrence of the dummy parameter within the block is replaced with each succeeding argument string. If the argument string is a null, then the block is repeated with each occurrence of the dummy parameter removed. If an argument includes an embedded blank or other assembler-significant character, it must be enclosed with single quotes.

label, if present, will be assigned the value of the run-time location counter at the start of the .DUPA directive processing.

Examples:

If the input source file contained the following statements,

     .dupa VALUE,12,32,34
     .byte VALUE
     .endm

then the assembler source listing would show

     .dupa VALUE,12,32,34
     .byte VALUE
     .endm

     ;     .byte  12
     ;     .byte  32
     ;     .byte  34

.dup , .dupc , .dupf , .endm , .macro

.DUPC

Syntax:

[label:] .DUPC dummy,string
.
.
.ENDM

Description:

Duplicate Sequence With Characters. The block of source statements defined by the .DUPC and .ENDM directives will be repeated for each character of string. For each repetition, every occurrence of the dummy parameter within the block is replaced with each succeeding character in the string. If the string is null, then the block is skipped.

label, if present, will be assigned the value of the run-time location counter at the start of the .DUPC directive processing.

Examples:

If the input source file contained the following statements,

     .dupc VALUE,'123'
     .byte VALUE
     .endm

then the assembler source listing would show

     .dupc VALUE,'123'
     .byte VALUE
     .endm

     ;     .byte  1
     ;     .byte  2
     ;     .byte  3

.dup , .dupa , .dupf , .endm , .macro

.DUPF

Syntax:

[label:] .DUPF dummy,[start],end[,increment]
.
.
.ENDM

Description:

Duplicate Sequence In Loop. The block of source statements defined by the .DUPF and .ENDM directives will be repeated in general (end - start) + 1 times when increment is 1. start is the starting value for the loop index; end represents the final value. increment is the increment for the loop index; it defaults to 1 if omitted (as does the start value). The dummy parameter holds the loop index value and may be used within the body of instructions.

label, if present, will be assigned the value of the run-time location counter at the start of the .DUPF directive processing.

Examples:

If the input source file contained the following statements,

     .dupf NUM,0,3
     .WORD NUM
     .endm

then the assembler source listing would show

     .dupf NUM,0,3
     .WORD NUM
     .endm

     ;     .WORD  0
     ;     .WORD  1
     ;     .WORD  2
     ;     .WORD  3

.dup , .dupa , .dupc , .endm , .macro

.END

Syntax:

.END

Description:

End of Source Program. The optional .END directive indicates that the logical end of the source program has been encountered. The .END directive cannot be used in a macro expansion.

A label is not allowed with this directive.

Examples:

.end       ;End of source program

.ENDIF

Syntax:

.ENDIF

Description:

End Of Conditional Assembly. The .ENDIF directive is used to signify the end of the current level of conditional assembly. Conditional assembly directives can be nested to any level, but the .ENDIF directive always refers to the most previous .IF directive.

A label is not allowed with this directive.

Examples:

.if  DEB
; Report building of the debug version
.message  'Debug Version'
.endif 

.if

.ENDM

Syntax:

.ENDM

Description:

End of Macro Definition. Every .MACRO, .DUP, .DUPA, and .DUPC directive must be terminated by an .ENDM directive.

A label is not allowed with this directive.

Examples:

SWAP_MEM .macro REG1,REG2       ;swap memory contents
     LD.W  D0,[A\REG1]          ;using D0 as temp
     LD.W  D1,[A\REG2]          ;using D1 as temp
     ST.W  [A\REG1],D1
     ST.W  [A\REG2],D0
     .endm

.dup , .dupa , .dupc , .macro

.EQU

Syntax:

name .EQU expression

Description:

Equate Symbol to a Value. The .EQU directive assigns the value of expression to the symbol name.

The .EQU directive is one of the directives that assigns a value other than the program counter to the name. The symbol name cannot be redefined anywhere else in the program. The expression may be relative or absolute, and forward references are allowed.

An .EQU symbol can be made global.

Examples:

     A_D_PORT .equ 0x4000

This would assign the value 0x4000 to the symbol A_D_PORT.

.set

.EXITM

Syntax:

.EXITM

Description:

Exit Macro. The .EXITM directive will cause immediate termination of a macro expansion. It is useful when used with the conditional assembly directive .IF to terminate macro expansion when error conditions are detected.

A label is not allowed with this directive.

Examples:

CALC .macro XVAL,YVAL
     .if XVAL<0
     .message  'Macro parameter value out of range'
     .exitm      ;Exit macro
     .endif
     .
     .
     .
     .endm

.dup , .dupa , .dupc , .macro

.EXTERN

Syntax:

.EXTERN [(attrib[,attrib]...)] symbol[ ,symbol]...

Description:

External Symbol Declaration. The .EXTERN directive is used to specify that the list of symbols is referenced in the current module, but is not defined within the current module. These symbols must either have been defined outside of any module or declared as globally accessible within another module using the .GLOBAL directive.

The optional argument attrib can be one of the following symbol attributes:

If the .EXTERN directive is not used to specify that a symbol is defined externally and the symbol is not defined within the current module, a warning is generated, and an .EXTERN symbol is inserted.

A label is not allowed with this directive.

Examples:

.extern AA,CC,DD               ;defined elsewhere
.extern (ABS24) EE             ;within direct addr.
                               ;code memory (astri)
.extern (CODE,FPI) FF          ;within TriCore
                               ;code memory (aspcp)

.global

.FAIL

Syntax:

.FAIL [{str | exp}[,{str | exp}]...]

Description:

Programmer Generated Error. The .FAIL directive will cause an error message to be output by the assembler. The total error count will be incremented as with any other error. The .FAIL directive is normally used in conjunction with conditional assembly directives for exceptional condition checking. The assembly proceeds normally after the error has been printed. An arbitrary number or strings and expressions, in any order but separated by commas, can be specified optionally to describe the nature of the generated error.

A label is not allowed with this directive.

Examples:

.fail 'Parameter out of range'

.message, .warning

.FLOAT

Syntax:

[label:] .FLOAT arg[,arg]...

Description:

Define 32-bit floating-point constant(s) in IEEE-754 single precision format. The .FLOAT directive allocates and initializes a word (32-bits) of memory for each arg argument. arg can be a constant, a symbol, or an expression. The constant can be expressed as signed whole number with fraction or the "e" format as that in the C language. 12.457 and +0.27E-13 are legal floating-point constants.

The .FLOAT directive may have one or more arguments separated by commas. Multiple arguments are stored in successive address locations. If multiple arguments are present, one or more of them can be null (two adjacent commas), in which case the corresponding address location will be filled with zeros. An error will occur if the evaluated argument value is too large to represent in a single word.

label, if present, will be assigned the value of the run-time location counter at the start of the directive processing.

Examples:

flt:  .float  0.1,0.2,0.3

.double

.FRACT

Syntax:

[label:] .FRACT arg[,arg]...

Description:

Define 32-bit constant fraction of Q31. The .FRACT directive allocates and initializes a word (32-bits) of memory for each arg argument. arg can be a constant, a symbol, or an expression.

The .FRACT directive may have one or more arguments separated by commas. Multiple arguments are stored in successive address locations. If multiple arguments are present, one or more of them can be null (two adjacent commas), in which case the corresponding address location will be filled with zeros. An error will occur if the evaluated argument value is out the range of [-1,1>.

label, if present, will be assigned the value of the run-time location counter at the start of the directive processing.

Examples:

FRCT:  .fract  0.1,0.2,0.3

.accum , .sfract

.GLOBAL

Syntax:

.GLOBAL symbol[, symbol]...

Description:

Global Section Symbol Declaration. The .GLOBAL directive is used to specify that the list of symbols is defined within the current section or module, and that those definitions should be accessible by all modules. If the symbols that appear in the operand field are not defined in the module, an error will be generated. Symbols that are defined "global" are accessible from other modules using the .EXTERN directive.

A label is not allowed with this directive.

Only program labels and .EQU labels can be made global.

Examples:

.global LOOPA      ;LOOPA will be globally
                   ;accessible by other modules

.extern, .local

.HALF

Syntax:

[label:] .HALF arg[,arg]...

Description:

Define Constant Half Word. The .HALF directive allocates and initializes a half-word of memory for each arg argument. arg can be a numeric constant, a single or double character string constant, a symbol, or an expression. The .HALF directive may have one or more arguments separated by commas. Multiple arguments are stored in successive address locations. If multiple arguments are present, one or more of them can be null (two adjacent commas), in which case the corresponding address location will be filled with zeros. An error will occur if the evaluated argument value is too large to represent in a single half-word.

label, if present, will be assigned the value of the run-time location counter at the start of the directive processing.

Half-word values are stored in memory with the least segnificant 8 bits on the lowest address (little endian).

Integer arguments are stored as is. Single and multiple character strings are handled in the following manner:

1. Single character strings are stored in a half-word whose lower seven bits represent the ASCII value of the character.

Example: 'R' = 0x52

2. Multiple character strings consisting of more than two characters are not allowed. Two-character strings are stored as if the ASCII value of the first character is the high byte value of the half-word. The second character is used as the low byte.

Example:

Examples:

TABLE:  .half 14,1635,0x2662,'AB'

is equal to

TABLE:  .byte 14,0,1635%256,6,0x62,0x26,'B','A'

.byte , .space , .word

.IF

Syntax:

.IF expression
.
.
[.ELIF expression] (the .ELIF directive is optional)
.
.
[.ELSE] (the .ELSE directive is optional)
.
.
.ENDIF

Description:

Conditional Assembly Directive. Part of a program that is to be conditionally assembled must be bounded by an IF-ENDIF directive pair. If the optional .ELSE or .ELIF (can be read as 'else if') directive is not present, then the source statements following the .IF directive and up to the next .ENDIF directive will be included as part of the source file being assembled only if the expression has a nonzero result. If the expression has a value of zero, the source file will be assembled as if those statements between the .IF and the .ENDIF directives were never encountered. If the .ELSE directive is present and expression has a nonzero result, then the statements between the .IF and .ELSE directives will be assembled, and the statements between the .ELSE and .ENDIF directives will be skipped. Alternatively, if expression has a value of zero, then the statements between the .IF and .ELSE directives will be skipped, and the statements between the .ELSE and .ENDIF directives will be assembled.

The expression must have an absolute integer result and is considered true if it has a nonzero result. The expression is false only if it has a result of 0. Because of the nature of the directive, expression must be known on pass one (no forward references allowed). .IF directives can be nested to any level. The .ELSE directive will always refer to the nearest previous .IF directive as will the .ENDIF directive.

A label is not allowed with this directive.

Examples:

.if XVAL<0
.message  'Please select larger value for XVAL'
.endif

.endif

.INCLUDE

Syntax:

.INCLUDE string | < string>

Description:

Include Secondary File. This directive is inserted into the source program at any point where a secondary file is to be included in the source input stream. The string specifies the filename of the secondary file. The filename must be compatible with the operating system and can include a directory specification.

The file is searched for first in the current directory, unless the <string> syntax is used, or in the directory specified in string. If the file is not found, and the -I option was used on the command line that invoked the assembler, then the string specified with the -I option is prefixed to string and that directory is searched. If the <string > syntax is given, the file is searched for only in the directories specified with the -I option.

A label is not allowed with this directive.

Examples:

.include 'headers/io.asm'
.include <data.asm>               ; Do not look in
                                  ; current directory

.LOCAL

Syntax:

.LOCAL symbol[,symbol]...

Description:

Local Section Symbol Declaration. The .LOCAL directive is used to specify that the list of symbols is defined within the current module, and that those definitions are explicitly local to that section or module. It is useful in cases where a symbol may not be exported outside of the module (as labels in a module are defined "global" by default). If the symbols that appear in the operand field are not defined in the module, an error will be generated.

A label is not allowed with this directive.

Examples:

.local LOOPA     ;LOOPA local to this module

.global

.MACRO

Syntax:

name .MACRO [dummy argument list]
.
macro definition statements
.
.
.endm

Description:

Macro Definition. The dummy argument list has the form:

The required name is the symbol by which the macro will be called.

The definition of a macro consists of three parts: the header, which assigns a name to the macro and defines the dummy arguments; the body, which consists of prototype or skeleton source statements; and the terminator. The header is the .MACRO directive, its name, and the dummy argument list. The body contains the pattern of standard source statements. The terminator is the .ENDM directive.

The dummy arguments are symbolic names that the macro processor will replace with arguments when the macro is expanded (called). Each dummy argument must obey the same rules as symbol names. Within each of the three dummy argument field, the dummy arguments are separated by commas. The dummy argument fields are separated by one or more blanks.

Macro definitions may be nested but the nested macro will not be defined until the primary macro is expanded.

Chapter 6, Macro Operations, contains a complete description of macros.

Examples:

SWAP_MEM .macro REG1,REG2       ;swap memory contents
     LD.W  D0,[A\REG1]          ;using D0 as temp
     LD.W  D1,[A\REG2]          ;using D1 as temp
     ST.W  [A\REG1],D1
     ST.W  [A\REG2],D0
     .endm

.dup , .dupa , .dupc , .dupf , .endm

.MESSAGE

Syntax:

.MESSAGE [{str | exp}[,{str | exp}]...]

Description:

Programmer Generated Message. The .MESSAGE directive will cause a message to be output by the assembler. The error and warning counts will not be affected. The .MESSAGE directive is normally used in conjunction with conditional assembly directives for informational purposes. The assembly proceeds normally after the message has been printed. An arbitrary number of strings and expressions, in any order but separated by commas, can be specified optionally to describe the nature of the message.

A label is not allowed with this directive.

Examples:

.message  'Generating tables'

.fail , .warning

.NAME

Syntax:

.NAME "str"

Description:

The .NAME directive is used by the assembler to give an identification to the produced object file. The linker and locator can then use this information to identify the source within the map files. Also a debugger may display the value as a 'module' name.

When this directive is omitted, the assembler will use the module's source name as an identification. When using the control program, this name might become a 'random' name.

Examples:

.name  "strcat"      ;object is identified by the
                     ;name "strcat"

.ORG

Syntax:

.ORG [abs-loc][,sect_type][,attrib]...

Description:

The .ORG directive is used to define a nameless section. This is the same as a .SDECL/.SECT without a section name. The absolute location of the section in memory can be set using this directive.

abs-loc Initial value to assign to the runtime location counter. abs-loc must be an absolute expression.

sect_type An optional section type:

code a code section
data a data section

attrib An optional section attribute:

abs24 direct addressable code (astri only)
abs18 direct addressable data (astri only)
fpi addressable through FPI bus (aspcp only)
clear clear section during program startup
noclear section is not cleared during startup
init initialization data copied from ROM
to RAM at startup
max common, overlay with other parts
with the same name, is implicit a
type of 'noclear'
romdata section contains data instead of
executable code

Examples:

; define a section on location 100 decimal
.org   100

; define a relocatable nameless section
.org

; define a relocatable data section
.org   ,data

; define a data section on 0x8000
.org   0x8000,data

.sdecl

.PMACRO

Syntax:

.PMACRO symbol[,symbol]...

Description:

Purge Macro Definition. The specified macro definition will be purged from the macro table, allowing the macro table space to be reclaimed.

A label is not allowed with this directive.

Examples:

.pmacro MAC1,MAC2

This statement would cause the macros named MAC1 and MAC2 to be purged.

.macro

.SDECL

Syntax:

.SDECL section, type [, attr]... [AT address]

Description:

Use this directive to define section names and declaration attributes. Before any code or data can be placed in a section, you must use the .SECT directive to activate the section. The definition can have declaration attributes and must have a section type (type).

The section type can be:

type: DATA | CODE

The section declaration attribute can be:

attr:

For each group one attribute can be specified at the most. The ABS24 and ABS18 attributes specify direct addressable CODE or DATA memory for the astri assembler. FPI is only valid for the aspcp assembler; this attribute specifies that a section must be accessed through the FPI bus. This section will not be located in PCP internal memory, but in TriCore memory.

CLEAR sections are zeroed at startup. This attribute can only be used on a DATA type section.

Sections with the NOCLEAR attribute are not zeroed at startup. This is a default attribute for DATA sections. The attribute can only be used for DATA sections.

The INIT attribute defines that the DATA section contains initialization data, which is copied from ROM to RAM at program startup.

ROMDATA sections (allowed on DATA and CODE sections) contain data to be placed in ROM. This ROM area is not executable.

When DATA sections with the same name occur in different object modules with the MAX attribute, the linker generates a section of which the size is the maximum of the sizes in the individual object modules. The MAX attribute only applies to DATA sections.

Examples:

.sdecl  ".text", DATA      ;declare section
     ;.text
.sect    ".text"
     ;switch to section
     ;.text

.sect , .org
See the paragraph Section Names in the chapter Software Concept for detailed information about sections, section types and section attributes.

.SECT

Syntax:

.SECT "str" [, RESET]

Description:

The .SECT directive flags the assembler that another section, with name str, becomes active. Before a section can be activated for the first time, it must be defined first, by the .SDECL directive. Subsequent activations can be done by the .SECT directive only.

You can use the section attribute RESET to reset counting storage allocation in DATA sections with section attribute MAX.

Examples:

.sdecl  ".text", DATA     ;declare section
     ;.text
.sect   ".text"
     ;switch to section
     ;.text

.sdecl
See the paragraph Section Names in the chapter Software Concept for detailed information about sections.

.SET

Syntax:

name .SET expression

Description:

Set Symbol to a Value. The .SET directive is used to assign the value of the expression in the operand field to the symbol name. The .SET directive functions somewhat like the .EQU directive. However, symbols defined via the .SET directive can have their values redefined in another part of the program (but only through the use of another .SET directive). The .SET directive is useful in establishing temporary or reusable counters within macros. The expression in the operand field of a .SET may have forward references.

.SET symbols cannot be made global.

Examples:

COUNT  .set 0     ; Initialize COUNT

.equ

.SFRACT

Syntax:

[label:] .SFRACT arg[,arg]...

Description:

Define 16-bit constant fraction of Q15 format. The .SFRACT directive allocates and initializes a half word (16-bits) of memory for each arg argument. arg can be a constant, a symbol, or an expression.

The .SFRACT directive may have one or more arguments separated by commas. Multiple arguments are stored in successive address locations. If multiple arguments are present, one or more of them can be null (two adjacent commas), in which case the corresponding address location will be filled with zeros. An error will occur if the evaluated argument value is out the range of [-1,1>.

label, if present, will be assigned the value of the run-time location counter at the start of the directive processing.

Examples:

SFRCT:  .sfract  0.1,0.2,0.3

.accum , .fract

.SPACE

Syntax:

[label:] .SPACE expression

Description:

Define Storage. The .SPACE directive reserves a block of memory the length of which in bytes is equal to the value of expression. This directive causes the run-time location counter to be advanced by the value of the absolute integer expression in the operand field. The block of memory reserved is not initialized to any value. The expression must be an integer greater than zero and cannot contain any forward references to address labels (labels that have not yet been defined).

label, if present, will be assigned the value of the run-time location counter at the start of the directive processing.

Examples:

S_BUF:  .space 12          ; Sample buffer

.byte , .half , .word

.SYMB

Syntax:

.SYMB string, expression [, abs_expr] [, abs_expr]

Description:

The .SYMB directive is used for passing high-level language symbolic debug information via the assembler (and linker/locator) to the debugger. expression can be any expression. abs_expr can be any expression resulting in an absolute value.

The .SYMB directive is not meant for 'hand coded' assembly files. It is documented for completeness only and is supposed to be 'internal' to the tool chain.

.UNDEF

Syntax:

.UNDEF symbol

Description:

Undefine .DEFINE Symbol. The .UNDEF directive causes the substitution string associated with symbol to be released, and symbol will no longer represent a valid .DEFINE substitution. See the .DEFINE directive for more information.

A label is not allowed with this directive.

Examples:

.undef DEBUG       ; Undefines the DEBUG
                   ; substitution string

.define

.WARNING

Syntax:

.WARNING [{str | exp}[,{str | exp}]...]

Description:

Programmer Generated Warning. The .WARNING directive will cause a warning message to be output by the assembler. The total warning count will be incremented as with any other warning. The .WARNING directive is normally used in conjunction with conditional assembly directives for exceptional condition checking. The assembly proceeds normally after the warning has been printed. An arbitrary number of strings and expressions, in any order but separated by commas, can be specified optionally to describe the nature of the generated warning.

A label is not allowed with this directive.

Examples:

.warning  'parameter too large'

.fail , .message

.WORD

Syntax:

[label:] .WORD arg[,arg]...

Description:

Define Constant Word. The .WORD directive allocates and initializes a word of memory for each arg argument. arg can be a numeric constant, a single or double character string constant, a symbol, or an expression. The .WORD directive may have one or more arguments separated by commas. Multiple arguments are stored in successive address locations. If multiple arguments are present, one or more of them can be null (two adjacent commas), in which case the corresponding address location will be filled with zeros. An error will occur if the evaluated argument value is too large to represent in a single word.

label, if present, will be assigned the value of the run-time location counter at the start of the directive processing.

Word values are stored in memory with the least significant 8 bits on the lowest address (little endian).

Integer arguments are stored as is. Single and multiple character strings are handled in the following manner:

1. Single character strings are stored in a word whose lower seven bits represent the ASCII value of the character.

Example: 'R' = 0x52

2. Multiple character strings consisting of more than four characters are not allowed. Four-character strings are stored as if the ASCII value of the first character is the high byte value of the word. The last character is used as the low byte.

Example:

Examples:

TABLE:  .word 14,1635,0x34266243,'ABCD'

is equal to

TABLE:  .byte 14,0,0,0,1635%256,6,0,0,
              0x43,0x62,0x26,0x34,'D','C','B','A'

.byte , .half , .space


Copyright © 2002 Altium BV