3 TRICORE ASSEMBLY LANGUAGE

This chapter contains the following sections:

Introduction

Built-in Assembly Functions
Overview of Built-in Assembly Functions
Detailed Description of Built-in Assembly Functions

Assembler Directives and Controls
Overview of Assembler Directives
Detailed Description of Assembler Directives
Overview of Assembler Controls
Detailed Description of Assembler Controls

3.1 Introduction

This chapter contains a detailed description of all built-in assembly functions directives and controls. For a description of the TriCore instruction set, refer to the TriCore Architecture v1.3 Manual [2000, Infineon].

3.2 Built-in Assembly Functions

3.2.1 Overview of Built-in Assembly Functions

The built-in assembler functions are grouped into the following types:

The following tables provide an overview of all built-in assembler functions.

Overview of mathematical functions

Function Description
@ABS (expr) Absolute value
@ACS (expr) Arc cosine
@ASN (expr) Arc sine
@AT2 (expr1,expr2) Arc tangent
@ATN (expr) Arc tangent
@CEL (expr) Ceiling function
@COH (expr) Hyperbolic cosine
@COS (expr) Cosine
@FLR (expr) Floor function
@L10 (expr) Log base 10
@LOG (expr) Natural logarithm
@MAX (expr,[,...,exprN]) Maximum value
@MIN (expr,[,...,exprN]) Minimum value
@POW (expr1,expr2) Raise to a power
@RND () Random value
@SGN (expr) Returns the sign of an expression as -1, 0 or 1
@SIN (expr) Sine
@SNH (expr) Hyperbolic sine
@SQT (expr) Square root
@TAN (expr) Tangent
@TNH (expr) Hyperbolic tangent
@XPN (expr) Exponential function (raise e to a power)

Overview of conversion functions

Function Description
@CVF (expr) Convert integer to floating-point
@CVI (expr) Convert floating-point to integer
@FLD (base,value,
width[,start])
Shift and mask operation
@FRACT(expr) Convert floating-point to 32-bit fractional
@SFRACT(expr) Convert floating-point to 16-bit fractional
@LNG (expr) Concatenate to double word
@LUN (expr) Convert long fractional to floating-point
@RVB (expr1[,expr2]) Reverse order of bits in field
@UNF (expr) Convert fractional to floating-point
@LSB (expr) Get least significant byte of a word
@MSB (expr) Get most significant byte of a word

Overview of string functions

Function Description
@CAT(str1,str2) Concatenate strings
@LEN (string) Length of string
@POS (str1,str2[,strt]) Position of substring in string
@SCP (str1,str2) Returns 1 if two strings are equal
@SUB (str1,expr,expr) Returns a sbustring

Overview of macro functions

Function Description
@ARG (symbol|expr) Test if macro argument is present
@CNT () Return number of macro arguments
@MAC (symbol) Test if macro is defined
@MXP () Test if macro expansion is active

Overview of address calculation functions

Function Description
@HI (expr) Returns upper 16 bits of expression value
@HIS (expr) Returns upper 16 bits of expression value, adjusted for signed addition
@LO (expr) Returns lower 16 bits of expression value
@LOS (expr) Returns lower 16 bits of expression value, adjusted for signed addition

Overview of assembler mode functions

Function Description
@ASPCP() Returns the name of the pcp assembler executable
@ASTC () Returns the name of the assembler executable
@CPU (string) Test if CPU type is selected
@DEF (symbol) Returns 1 if symbol has been defined
@EXP (expr) Expression check
@INT (expr) Integer check
@LST () LIST control flag value

3.2.2 Detailed Description of Built-in Assembly Functions

@ABS( expression)

Returns the absolute value of expression as an integer value.

Example:

@ACS( expression)

Returns the arc cosine of expression as a floating-point value in the range zero to pi. The result of expression must be between -1 and 1.

Example:

@ARG( symbol | expression)

Returns an integer 1 if the macro argument represented by symbol or expression is present, 0 otherwise. If the argument is a symbol it must be single-quoted and refer to a dummy argument name. If the argument is an expression it refers to the ordinal position of the argument in the macro dummy argument list. The assembler issues a warning if this function is used when no macro expansion is active.

Example:

@ASN( expression)

Returns the arc sine of expression as a floating-point value in the range -pi/2 to pi/2. The result of expression must be between -1 and 1.

Example:

@ASPCP()

Returns the name of the PCP assembler executable. This is 'aspcp' for the PCP assembler.

Example:

@ASTC()

Returns the name of the assembler executable. This is 'astc' for the TriCore assembler.

Example:

@AT2( expr1,expr2)

Returns the arc tangent of expr1/expr2 as a floating-point value in the range -pi to pi. Expr1 and expr2 must be separated by a comma.

Example:

@ATN( expression)

Returns the arc tangent of expression as a floating-point value in the range -pi/2 to pi/2.

Example:

@CAT(string1,string2)

Concatenates the two strings into one string. The two strings must be enclosed in single or double quotes.

Example:

@CEL( expression)

Returns a floating-point value which represents the smallest integer greater than or equal to expression.

Example:

@CNT()

Returns the number of arguments of the current macro expansion as an integer. The assembler issues a warning if this function is used when no macro expansion is active.

Example:

@COH( expression)

Returns the hyperbolic cosine of expression as a floating-point value.

Example:

@COS( expression)

Returns the cosine of expression as a floating-point value.

Example:

@CPU( string)

Returns an integer 1 if string corresponds to the selected CPU type; 0 otherwise. See also the assembler option -C (Select CPU).

Example:

@CVF( expression)

Converts the result of expression to a floating-point value.

Example:

@CVI( expression)

Converts the result of expression to an integer value. This function should be used with caution since the conversions can be inexact (e.g., floating-point values are truncated).

Example:

@DEF( symbol)

Returns an integer 1 if symbol has been defined, 0 otherwise. symbol may be any label not associated with a .MACRO or .SDECL directive. If symbol is quoted it is looked up as a .DEFINE symbol; if it is not quoted it is looked up as an ordinary label.

Example:

@EXP( expression)

Returns 0 if the evaluation of expression would normally result in an error. Returns 1 if the expression can be evaluated correctly. With the @EXP function, you prevent the assembler of generating an error if expression contains an error. No test is made by the assembler for warnings. The expression may be relative or absolute.

Example:

@FLD( base,value,width[,start])

Shift and mask value into base for width bits beginning at bit start. If start is omitted, zero (least significant bit) is assumed. All arguments must be positive integers and none may be greater than the target word size. Returns the shifted and masked value.

Example:

@FLR( expression)

Returns a floating-point value which represents the largest integer less than or equal to expression.

Example:

@FRACT(expression)

This function returns the 32-bit fractional representation of the floating point expression. The expression must be in the reange [-1,+1>.

Example:

@HI(expression)

Returns the upper 16 bits of a value. @HI(expression) is equivalent to ((expression>>16) & 0xffff).

Example:

@HIS( expression)

Returns the upper 16 bits of a value, adjusted for a signed addition. @HIS(expression) is equivalent to (((expression+0x800)>>16) & 0xffff).

Example:

@INT( expression)

Returns an integer 1 if expression has an integer result; otherwise, it returns a 0. The expression may be relative or absolute.

Example:

@L10( expression)

Returns the base 10 logarithm of expression as a floating-point value. expression must be greater than zero.

Example:

@LEN( string)

Returns the length of string as an integer.

Example:

@LNG( expr1,expr2)

Concatenates the 16-bit expr1 and expr2 into a 32-bit word value such that expr1 is the high half and expr2 is the low half.

Example:

@LO(expression)

Returns the lower 16 bits of a value. @LO(expression) is equivalent to expression & 0xffff).

Example:

@LOG( expression)

Returns the natural logarithm of expression as a floating-point value. expression must be greater than zero.

Example:

@LOS( expression)

Returns the lower 16 bits of a value, adjusted for a signed addition. @LOS(expression) is equivalent to (((expression+0x8000) & 0xffff) - 0x8000).

Example:

@LSB( expression)

Returns the least significant byte of the result of the expression.
expression is interpreted as a half word (16 bit).

Example:

@LST()

Returns the value of the $LIST ON/OFF control flag as an integer. Whenever a $LIST ON control is encountered in the assembler source, the flag is incremented; when a $LIST OFF control is encountered, the flag is decremented.

Example:

@LUN( expression)

Converts the 32-bit expression to a floating-point value. expression should represent a binary fraction.

Example:

@MAC( symbol)

Returns an integer 1 if symbol has been defined as a macro name, 0 otherwise.

Example:

@MAX( expr1[,exprN]...)

Returns the greatest of expr1,...,exprN as a floating-point value.

Example:

@MIN( expr1[,exprN]...)

Returns the least of expr1,...,exprN as a floating-point value.

Example:

@MSB( expression)

Returns the most significant byte of the result of the expression.
expression is interpreted as a half word (16 bit).

Example:

@MXP()

Returns an integer 1 if the assembler is expanding a macro, 0 otherwise.

Example:

@POS( str1,str2[,start])

Returns the position of str2 in str1 as an integer, starting at position start. If start is not given the search begins at the beginning of str1. If the start argument is specified it must be a positive integer and cannot exceed the length of the source string. Note that the first position in a string is position 0.

Example:

@POW( expr1,expr2)

Returns expr1 raised to the power expr2 as a floating-point value. expr1 and expr2 must be separated by a comma.

Example:

@RND()

Returns a random value in the range 0.0 to 1.0.

Example:

@RVB( expr1,expr2)

Reverse the order of bits in expr1 delimited by the number of bits in expr2. If expr2 is omitted the field is bounded by the target word size. Both expressions must be 16-bit integer values.

Example:

@SCP( str1,str2)

Returns an integer 1 if the two strings compare, 0 otherwise. The two strings must be separated by a comma.

Example:

@SFRACT(expression)

This function returns the 16-bit fractional representation of the floating point expression. The expression must be in the reange [-1,+1>.

Example:

@SGN( expression)

Returns the sign of expression as an integer: -1 if the argument is negative, 0 if zero, 1 if positive. The expression may be relative or absolute.

Example:

@SIN( expression)

Returns the sine of expression as a floating-point value.

Example:

@SNH( expression)

Returns the hyperbolic sine of expression as a floating-point value.

Example:

@SQT( expression)

Returns the square root of expression as a floating-point value. expression must be positive.

Example:

@SUB( string,expression1,expression2)

Returns the substring from string as a string. Expression1 is the starting position wihtin string, and expression2 is the length of the desired string. The assembler issues an error if either expression1 or expression2 exceeds the length of string. Note that the first position in a string is position 0.

Example:

@TAN( expression)

Returns the tangent of expression as a floating-point value.

Example:

@TNH( expression)

Returns the hyperbolic tangent of expression as a floating-point value.

Example:

@UNF( expression)

Converts expression to a floating-point value. expression should represent a 16-bit binary fraction.

Example:

@XPN( expression)

Returns the exponential function (base e raised to the power of expression) as a floating-point value.

Example:

3.3 Assembler Directives and Controls

3.3.1 O verview of Assembler Directives

Assembler directives are grouped in the following categories:

The following tables provide an overview of all assembler directives.

Overview of assembly control directives

Directive Description
.COMMENT Start comment lines
.DEFINE Define substitution string
.END End of source program
.FAIL Programmer generated error message
.INCLUDE Include secondary file
.MESSAGE Programmer generated message
.NAME Identification for object file (instead of file name)
.ORG Initialize memory space and location counters to create a nameless section
.SDECL Declare a section with name, type and attributes
.SECT Activate a declared section
.UNDEF Undefine DEFINE symbol
.WARNING Programmer generated warning

Overview of symbol definition directives

Directive Description
.EQU Assign permanent value to a symbol
.EXTERN External symbol declaration
.GLOBAL Global section symbol declaration
.LOCAL Local symbol declaration
.SET Set temporary value to a symbol
.SIZE Set size of symbol in the ELF symbol table
.TYPE Set symbol type in the ELF symbol table

Overview of data definition / storage allocation directives

Directive Description
.ALIGN Define alignment
.ACCUM Define 64-bit constant of 18 + 46 bits format
.ASCII / .ASCIIZ Define ASCII string without / with ending NULL byte
.BYTE Define constant byte
.FLOAT / .DOUBLE Define a 32-bit / 64-bit floating point constant
.FRACT / .SFRACT Define a 16-bit / 32-bit constant fraction
.SPACE Define storage
.WORD / .HALF Define a word / half-word constant

O verview of macro and conditional assembly directives

Directive Description
.DUP / .ENDM Duplicate sequence of source lines
.DUPA / .ENDM Duplicate sequence with arguments
.DUPC / .ENDM Duplicate sequence with characters
.DUPF / .ENDM Duplicate sequence in loop
.EXITM Exit macro
.IF / .ELIF / .ELSE / .ENDIF Conditional assembly
.MACRO/ENDM Define macro
.PMACRO Purge macro definition

Overview of debug directives

Function Description
.CALLS Passes call information to object file. Used by the linker to build a call graph.
.SYMB Passes debug information to object file. Used by CrossView Pro for debugging.

3.3.2 Detailed Description of Assembler Directives

Some assembler directives can be preceeded with a label. If you do not preceede an assembler directive with a label, you must use white space instead (spaces or tabs). The assembler recognizes both upper and lower case for directives.

.ACCUM

Syntax

[label:] .ACCUM argument[,argument]...

Description

With the .ACCUM directive (Define 64-bit Constant) the assembler allocates and initializes two words of memory (64 bits) for each argument. Use commas to separate multiple arguments.

An argument can be:

Multiple arguments are stored in successive address locations in sets of two bytes. If an argument is NULL its corresponding address location is filled with zeros.

If the evaluated expression is out of the range [-217, 217>, the assembler issues a warning and saturates the fractional value.

Example

ACC:  .ACCUM  0.1,0.2,0.3

Related information

.SPACE (Define storage)

.FRACT / .SFRACT (Define 32-hit / 16-bit constant fraction)

.ALIGN

Syntax

Description

With the ALIGN directive you instruct the assembler to align the location counter. Default the assembler aligns on one byte.

When the assembler encounters the ALIGN directive, it advances the location counter to an address that is aligned as specified by expression and places the next instruction on that address. The assembler fills the 'gap' with NOP instructions. If the location counter is already aligned on the specified alignment, it remains unchanged.

The expression must be a power of two: 2, 4, 8, 16, ... If you specify another value, the assembler changes the alignment to the next higher power of two and issues a warning.

The assembler aligns sections automatically to the largest alignment value occurring in that secton.

A label is not allowed with this directive.

Example

Related information

-

.ASCII/.ASCIIZ

Syntax

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

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

Description

With the .ASCII or .ASCIIZ directive the assembler allocates and initializes memory each string.

The .ASCII directive does not add a NULL byte to the end of the string.
The .ASCIIZ directive does add a NULL byte to the end of the string. Use commas to separate multiple strings.

Example

STRING:  .ASCII  "Hello world"
STRING:  .ASCIIZ "Hello world"

With the .BYTE directive you can obain exactly the same effect:

STRING:  .BYTE  "Hello world"    ; without a NULL byte
STRING:  .BYTE  "Hello world",0  ; with a NULL byte

Related information

.SPACE (Define storage)

,BYTE (Define a constant byte)
.WORD / .HALF (Define a word / halfword)

.BYTE

Syntax

[label] .BYTE argument[ ,argument]...

Description

With the .BYTE directive (Define Constant Byte) the assembler allocates and initializes a byte of memory for each argument.

An argument can be:

Multiple arguments are stored in successive byte locations. If an argument is NULL its corresponding byte location is filled with zeros.

If you specify label, it gets the value of the location counter at the start of the directive processing.

Integer arguments are stored as is, but must be byte values (within the range 0-255); floating-point numbers are not allowed. If the evaluated expression is out of the range [-256, +255] the assembler issues an error. For negative values within that range, the assembler adds 256 to the specified value (for example, -254 is stored as 2).

In case of single and multiple character strings, each character is stored in consecutive bytes whose lower seven bits represent the ASCII value of the character. The standard C escape sequences are allowed:

Example

TABLE  .BYTE  'two',0,'strings',0
CHARS  .BYTE  'A','B','C','D'

Related information

.SPACE (Define storage)

.ASCII / .ASCIIZ (Define ASCII string without ending NULL)
.WORD / .HALF (Define a word / halfword)

.CALLS

Syntax

Description

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

When you compile with the option -g (include debugging information), the compiler inserts these directives to pass call tree information. Normally it is not necessary to use the .CALLS directive in hand coded assembly.

A label is not allowed with this directive.

Example

To indicate that the function main calls the function nfunc:

Related information

-

.COMMENT

Syntax

Description

With the COMMENT directive (Start Comment Lines) you can 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.

Example

Related information

-

.DEFINE

Syntax

Description

With the .DEFINE directive you define a substitution string that you can use on all following source lines. The assembler searches all succeeding lines for an occurrence of symbol, and replaces it with string.

This directive is useful for providing better documentation in the source program. Symbol must adhere to the restrictions for labels. That is, a symbol can consist of letters, digits and underscore characters (_), and the first character cannot be a digit.

The assembler issues a warning if you redefine an existing symbol.

Macros represent a special case. .DEFINE directive translations are 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.

Example

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

then the source line below:

would be transformed by the assembler to the following:

Related information

.UNDEF (Undefine .DEFINE symbol)
.SET (Set temporary value to a symbol)

.DUP / .ENDM

Syntax

[label] .DUP expression
.
.
.ENDM

Description

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). You can nest the .DUP directive to any level.

If you specify label, it gets the value of the location counter at the start of the DUP directive processing.

Example

Consider the following source input statements,

This is expanded as follows:

Related information

.DUPA (Duplicate Sequence with Arguments),
.DUPC (Duplicate Sequence with Characters),
.DUPF (Duplicate Sequence in Loop),
.MACRO (Define Macro)

.DUPA / .ENDM

Syntax

[label] .DUPA dummy ,argument[,argument]...
.
.
.ENDM

Description

With the .DUPA and .ENDM directives (Duplicate Sequence with Arguments) you can repeat a block of source statements for each argument. For each repetition, every occurrence of the dummy parameter within the block is replaced with each succeeding argument string. If an argument includes an embedded blank or other assembler-significant character, it must be enclosed with single quotes.

If you specify label, it gets the value of the location counter at the start of the DUPA directive processing.

Example

Consider the following source input statements,

This is expanded as follows:

Related information

.DUP (Duplicate Sequence of Source Lines),
.DUPC (Duplicate Sequence with Characters),
.DUPF (Duplicate Sequence in Loop),
.MACRO (Define Macro)

.DUPC / .ENDM

Syntax

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

Description

With the .DUPC and .ENDM directives (Duplicate Sequence with Characters) you can repeat a block of source statements 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 empty, then the block is skipped.

If you specify label, it gets the value of the location counter at the start of the DUPC directive processing.

Example

Consider the following source input statements,

This is expanded as follows:

Related information

.DUP (Duplicate Sequence of Source Lines),
.DUPA (Duplicate Sequence with Arguments),
.DUPF (Duplicate Sequence in Loop),
.MACRO (Define Macro)

.DUPF / .ENDM

Syntax

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

Description

With the .DUPF and .ENDM directives (Duplicate Sequence in Loop) you can repeat a block of source statements (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.

If you specify label, it gets the value of the location counter at the start of the DUPF directive processing.

Example

Consider the following source input statements,

This is expanded as follows:

Related information

.DUP (Duplicate Sequence of Source Lines),
.DUPA (Duplicate Sequence with Arguments),
.DUPC (Duplicate Sequence with Characters),
.MACRO (Define Macro)

.END

Syntax

Description

With the optional END directive you tell the assembler that the logical end of the source program is reached. If the assembler finds assembly source lines beyond the .END directive, it ignores those lines and issues a warning.

The expression is only permitted here for compatibility reasons. It is ignored during assembly.

You cannot use the END directive in a macro expansion.

A label is not allowed with this directive.

Example

Related information

-

.EQU

Syntax

symbol .EQU expression

Description

With the .EQU directive you assign the value of expression to symbol permanently. Once defined, you cannot redefine the symbol.

The expression can be relative or absolute and forward references are allowed.

Example

To assign the value 0x4000 permanently to the symbol A_D_PORT:

You cannot redefine the symbol A_D_PORT after this.

Related information

.SET (Set temporary value to a symbol)

.EXITM

Syntax

Description

With the .EXITM directive (Exit Macro) the assembler will immediately terminate a macro expansion. It is useful when you use it with the conditional assembly directive .IF to terminate macro expansion when, for example, error conditions are detected.

A label is not allowed with this directive.

Example

CALC  .MACRO  XVAL,YVAL
      .IF     XVAL<0
      .FAIL   'Macro parameter value out of range'
      .EXITM  ;Exit macro
      .ENDIF
      .
      .
      .
      .ENDM

Related information

.DUP (Duplicate Sequence of Source Lines),
.DUPA (Duplicate Sequence with Arguments),
.DUPC (Duplicate Sequence with Characters),
.DUPF (Duplicate Sequence in Loop),
.MACRO (Define Macro)

.EXTERN

Syntax

Description

With the .EXTERN directive (External Symbol Declaration) you 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 with the .GLOBAL directive.

If you do not use the .EXTERN directive to specify that a symbol is defined externally and the symbol is not defined within the current module, the assembler issues a warning and inserts the .EXTERN directive for that symbol.

A label is not allowed with this directive.

Example

Related information

.GLOBAL (Global symbol declaration)
.LOCAL (Local symbol declaration)

.FAIL

Syntax

Description

With the .FAIL directive (Programmer Generated Error) you tell the assembler to output an error message during the assembling process.

The total error count will be incremented as with any other error. The .FAIL directive is for example useful in combination with conditional assembly for exceptional condition checking. The assembly process proceeds normally after the error has been printed.

Optionally, you can specify an arbitrary number of strings and expressions, in any order but separated by commas, to describe the nature of the generated error. The assembler outputs a space between each argument.

A label is not allowed with this directive.

Example

Related information

.MESSAGE (Programmer Generated Message),
.WARNING (Programmer Generated Warning)

.FLOAT/.DOUBLE

Syntax

[label] .FLOAT argument[ ,argument]...

[label] .DOUBLE argument[,argument]...

Description

With the .FLOAT or .DOUBLE directive the assembler allocates and initializes one word (32 bits) or a double-word (64 bits) of memory for each argument.

An argument can be:

You can represent a constant as a signed whole number with fraction or with the 'e' format as used in the C language. 12.457 and +0.27E-13 are legal floating-point constants.

If you specify label, it gets the value of the location counter at the start of the directive processing.

If the evaluated argument is too large to be represented in a single word / double-word, the assembler issues an error.

Examples

FLT:  .FLOAT  12.457,+0.27E-13
DBL:  .DOUBLE  12.457,+0.27E-13

Related information

.SPACE (Define storage)

.FRACT/.SFRACT

Syntax

[label:] .FRACT argument[,argument]...

[label:] .SFRACT argument[,argument]...

Description

With the .FRACT or .SFRACT directive the assembler allocates and initializes one word of memory (32 bits) or a halfword (16 bits) for each argument. Use commas to separate multiple arguments.

An argument can be:

Multiple arguments are stored in successive address locations in sets of two bytes. If an argument is NULL its corresponding address location is filled with zeros.

If the evaluated argument is out of the range [-1, +1> , the assembler issues a warning and saturates the fractional value.

Example

FRCT:   .FRACT   0.1,0.2,0.3
SFRCT:  .SFRACT  0.1,0.2,0.3

Related information

.SPACE (Define storage)

,ACCUM (Define 64-bit constant in 18+46 bits format)

.GLOBAL

Syntax

Description

With the .GLOBAL directive (Global Section Symbol Declaration) you declare one of more symbols as global. This means that the specified symbols are defined within the current section or module, and that those definitions should be accessible by all modules.

Only symbols that are defined with the .EQU directive can be made global.

If the symbols that appear in the operand field are not used in the module, the assembler gives a warning.

A label is not allowed with this directive.

Example

      .SDECL  ".data.io",DATA
      .SECT   ".data.io"
      .GLOBAL LOOPA   ; LOOPA will be globally
                      ; accessible by other modules
LOOPA .HALF   0x100   ; assigns the value 0x100 to LOOPA

Related information

.EXTERN (External symbol declaration)
.LOCAL (Local symbol declaration)

.IF / .ELIF / .ELSE / .ENDIF

Syntax

Description

With the .IF/ .ENDIF directives you can create a part of conditional assembly code. The assembler assembles only the code that it reaches.

The expression must evaluate to an absolute integer and cannot contain forward references. If expression evaluates to zero, the .IF-condition is considered FALSE. Any non-zero result of expression is considered as TRUE.

You can nest .IF directives to any level. The .ELSE, .ELIF and .ENDIF directives always refer to the nearest previous .IF directive.

A label is not allowed with this directive.

Example

Suppose you have an assemble source file with specific code for a test version, for a demo version and for the final version. Within the assembly source you define this code conditionally as follows:

Before assembling the file you can set the values of the symbols .TEST and .DEMO in the assembly source before the .IF directive is reached. For example, to assemble the demo version:

You can also define the symbols on the command line with the option -D:

Related information

-

.INCLUDE

Syntax

Description

With the .INCLUDE directive you direct the assembler to include another file before the resulting file is assembled. The .INCLUDE directive works similarly to the #include statement in C.

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 order in which the assembler searches for include files is:

1. The current directory if only a filename is given, unless the <string> syntax is used, or in the directory specified in string if you specify both a pathname and a filename.

2. The path that is specified with the assembler option -I.

3. The path that is specified in the environment variable ASTCINC when the product was installed.

4. The default directory ...\ctc\include.

A label is not allowed with this directive.

Example

.INCLUDE 'storage\mem.asm'    ; include file
.INCLUDE <data.asm>           ; Do not look in
                              ; current directory

Related information

Assembler option -I (Add directory to include file search path) in section 4.2, Assembler Options, of Chapter Tool Options.

.LOCAL

Syntax

Description

By default, labels in a module are defined "global". With the .LOCAL directive (Local Section Symbol Declaration) you declare one of more symbols as local. This means that the specified symbols are explicitly local to the section or module in which you define them.

If the symbols that appear in the operand field are not used in the module, the assembler gives a warning.

A label is not allowed with this directive.

Example

      .SDECL  ".data.io",DATA
      .SECT   ".data.io"
      .LOCAL  LOOPA   ; LOOPA is local to this section

LOOPA .HALF   0x100   ; assigns the value 0x100 to LOOPA

Related information

.EXTERN (External symbol declaration)
.GLOBAL (Global symbol declaration)

.MACRO / .ENDM

Syntax

macro_name .MACRO [dumarg[,dumarg]...]
.
macro_definition_statements
.
.
.ENDM

Description

With the .MACRO directive you define a macro. Macros provide a shorthand method for handling a repeated pattern of code or group of instructions. You can define the pattern as a macro, and then call the macro at the points in the program where the pattern would repeat. The .ENDM directive indicates the end of the macro.

The definition of a macro consists of three parts:

The dummy arguments are symbolic names that the macro processor replaces with the literal arguments when the macro is expanded (called). Each dummy argument must follow the same rules as symbol names. Dummy argument names cannot start with a percent sign (%).

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

Example

The macro definition:

CONSTD  .MACRO  reg,value                    ;header
    mov.u   reg,#lo(value)                   ;body
    addih   reg,reg,#hi(value)
    .ENDM                                    ;terminator

The macro call:

    .SDECL  ".data",DATA
    .SECT   ".data"
    CONSTD  d4,0x12345678
    .END

The macro expands as follows:

    mov.u   d4,#lo(0x12345678)
    addih   d4,d4,#hi(0x12345678)

Related information

.DUP (Duplicate Sequence of Source Lines),
.DUPA (Duplicate Sequence with Arguments),
.DUPC (Duplicate Sequence with Characters),
.DUPF (Duplicate Sequence in Loop)

Section 4.9, Macro Operations, in Chapter Assembly Language of the User's Guide.

.MESSAGE

Syntax

Description

With the .MESSAGE directive (Programmer Generated Message) you tell the assembler to output an information message durring assembly.

The error and warning counts will not be affected. The .MESSAGE directive is for example useful in combination with conditional assembly for informational purposes. The assembly proceeds normally after the message has been printed.

Optionally, you can specify an arbitrary number of strings and expressions, in any order but separated by commas, to describe the nature of the message. The assembler outputs a space between each argument.

A label is not allowed with this directive.

Example

Within single quotes, the defined symbol LONG is not expanded. Within double quotes the symbol LONG is expanded. So, the actual message is printed as:

Related information

.FAIL (Programmer Generated Error)
.WARNING (Programmer Generated Warning)

.NAME

Syntax

Description

With the .NAME directive you give an identification to the generated object file. The linker and or debugger uses this identification (instead of the file name) to refer to the file.

When you use the control program cctc, this name may become a random name.

Example

Suppose the assembler assembles the file test.src and generates test.o. To change the identification (used by the linker and debugger) from the name "test" into "strcat":

.ORG

Syntax

Description

With the .ORG directive you can specify an absolute location (abs_loc) in memory of a section. This is the same as a .SDECL/.SECT without a section name.

This directive uses the following arguments:

abs-loc Initial value to assign to the run-time location counter. abs-loc must be an absolute expression. If abs_loc is not specified, then the value is zero.

sect_type An optional section type:

code code section
data data section

attribute An optional section attribute:

Code attibutes:
init section is copied from ROM to RAM at startup
noread section can be executed from but not read

Data attibutes:
noclear section is not cleared during startup
max data overlay with other parts with the same
name, is implicit a type of 'noclear'
rom data section remains in ROM

A label is not allowed with this directive.

Example

Related information

.SDECL (Declare section name and attributes)
.SECT (Activate a declared section)

.PMACRO

Syntax

Description

With the .PMACRO directive you tell the assembler to purge the specified macro from the macro table, reclaiming the macro table space.

A label is not allowed with this directive.

Example

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

Related information

.MACRO (Define Macro)

.SDECL

Syntax

Description

With the .SDECL directive you can define a section with a name, type and optional attributes. Before any code or data can be placed in a section, you must use the .SECT directive to activate the section.

This directive uses the following arguments:

type: A section type:

code code section
data data section

attribute: An optional section attribute:

Code attibutes:
init section is copied from ROM to RAM at startup
noread section can be executed from but not read

Data attibutes:
noclear section is not cleared during startup
max data overlay with other parts with the same
name, is implicit a type of 'noclear'
rom data section remains in ROM

Sections with attribute noclear are not zeroed at startup. This is a default attribute for data sections. You can only use this attribute with a data type section. This attribute is only useful with BSS sections, which are cleared at startup by default.

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

Sections with the attribute rom 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 attribute max, the linker generates a section with a size that is the largest of the sizes in the individual object modules. The attribute max only applies to data sections.

The name of a section can have a special meaning for locating sections. The name of code sections should always start with ".text" (or ".pcptext" for PCP code). With data sections, the prefix in the name is important. The prefix determines if the section is initialized, constant or uninitialized and which addressing mode is used.

Name prefix Type of DATA section
.data initialized
.zdata initialized, abs 18 addressing
.sdata initialized, a0 addressing
.data_a8 initialized, a8 addressing
.data_a9 initialized, a9 addressing
.rodata constant data
.zrodata constant data, abs 18 addressing
.srodata constant data, a0 addressing
.rodata_a8 constant data, a8 addressing
.rodata_a9 constant data, a9 addressing
.bss uninitialized
.zbss uninitialized, abs 18 addressing
.sbss uninitialized, a0 addressing
.bss_a8 uninitialized, a8 addressing
.bss_a9 uninitialized, a9 addressing
.ldata a1 addressing (read only constants, literal data)
.pcpdata pcp data

Table 3-1: Data section name prefixes

Note that the compiler uses the following name convention:

Examples:

.SECT (Activate a declared section)
.ORG (Initalize a nameless section)

.SECT

Syntax

Description:

With the .SECT directive you activate a previously declared section with the name name. Before you can activate a section, you must define the section with the .SDECL directive. You can activate a section as many times as you need.

With the section attribute RESET you can reset counting storage allocation in data sections that have section attribute max.

Examples:

.SDECL (Declare a section with name, type and attributes)
.ORG (Initalize a nameless section)

.SET

Syntax

symbol .SET expression

.SET symbol expression

Description

With the .SET directive you assign the value of expression to symbol temporarily. If a symbol was defined with the .SET directive, you can redefine that symbol in another part of the assembly source, using the .SET.

The .SET directive is useful in establishing temporary or reusable counters within macros. Expression must be absolute and forward references are allowed.

Example

COUNT .SET  0  ; Initialize COUNT. Later on you can
               ; assign other values to the symbol COUNT.

Related information

.EQU (Assign permanent value to a symbol)

.SIZE

Syntax

Description

With the .SIZE directive you set the size of the specified symbol to the value represented by expression.

The .SIZE directive may occur anywhere in the source file unless the specified symbol is a function. In this case, the .SIZE directive must occur after the function has been defined.

Example

main:
   .      ; function main
   .
   ret
   .SIZE main,(*-main)

Related information

.TYPE (Set Symbol Type)

.SPACE

Syntax

[label] .SPACE expression

Description

With the .SPACE directive (Define Storage) the assembler reserves a block of bytes in memory. The reserved block of memory is not initialized to any value.

With expression you specify the number of bytes you want to reserve, and how much the location counter will advance. 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).

If you specify label, it gets the value of the location counter at the start of the directive processing.

Example

S_BUF  .SPACE  12     ; Sample buffer

Related information

.ASCII / .ASCIIZ (Define ASCII string without ending NULL)
,BYTE (Define a constant byte)
,FLOAT / .DOUBLE (Define a 32-bit / 64-bit floating point constant)
.WORD / .HALF (Define a word / halfword)

.SYMB

Syntax

Description

When you compile with the option -g (include debugging information), the compiler inserts the .SYMB directives to pass high-level language symbolic debug information via the assembler (and linker) 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 and is documented here for completeness only.

Example

If you compile a C file test.c with the -g option, you might find the following .SYMB directives in your assembly listing file:

Related information

-

.TYPE

Syntax

symbol .TYPE typeid

Description

With the .TYPE directive you set a symbol's type to the specified value in the ELF symbol table. Valid symbol types are:

FUNC The symbol is associated with a function or other executable code.

OBJECT The symbol is associated with an object such as a variable, an array, or a structure.

FILE The symbol name represents the filename of the compilation unit.

Example

Afunc   .TYPE   FUNC

Related information

.SIZE (Set Symbol Size)

.UNDEF

Syntax

Description

With the .UNDEF directive you can undefine a substitution string that was previously defined with the .DEFINE directive. The substitution string associated with symbol is released, and symbol will no longer represent a valid .DEFINE substitution.

A label is not allowed with this directive.

Example

Related information

.DEFINE (Define Substitution String)

.WARNING

Syntax

Description

With the .WARNING directive (Programmer Generated Warning) you tell the assembler to output a warning message during the assembling process.

The total warning count will be incremented as with any other warning. The .WARNING directive is for example useful in combination with conditional assembly for exceptional condition checking. The assembly process proceeds normally after the warning has been printed.

Optionally, you can specify an arbitrary number of strings and expressions, in any order but separated by commas, to describe the nature of the generated warning. The assembler outputs a space between each argument.

A label is not allowed with this directive.

Example

Related information

.FAIL (Programmer Generated Error),
.MESSAGE (Programmer Generated Message)

.WORD/.HALF

Syntax

[label] .WORD argument[ ,argument]...

[label] .HALF argument[ ,argument]...

Description

With the .WORD or .HALF directive the assembler allocates and initializes one word (32 bits) or a halfword (16 bits) of memory for each argument.

An argument can be:

Multiple arguments are stored in successive byte locations. If an argument is NULL its corresponding byte location is filled with zeros.

If you specify label, it gets the value of the location counter at the start of the directive processing.

In case of single and multiple character strings, each character is stored in consecutive bytes whose lower seven bits represent the ASCII value of the character. The standard C escape sequences are allowed:

If the evaluated argument is too large to be represent in a word / halfword, the assembler issues an error.

Examples

WRD:  .WORD  14,1635,0x34266243,'ABCD'
HLF:  .HALF  14,1635,0x2662,'AB'

With the .BYTE directive you can obain exactly the same effect:

WRD:  .BYTE  14,0,0,0,1635%256,6,0,0,
              0x43,0x62,0x26,0x34,'D','C','B','A'
HLF:  .BYTE  14,0,1635%256,6,0x62,0x26,'B','A'

Related information

.SPACE (Define storage)

.ASCII / .ASCIIZ (Define ASCII string without ending NULL)
,BYTE (Define a constant byte)

3.3.3 Overview of Assembler Controls

The following tables provide an overview of all assembler controls.

Overview of assembler listing controls

Function Description
$LIST ON / OFF Generation of assembly list file temporary ON/OFF
$LIST "flags" Exclude / include lines in assembly list file
$PAGE Generate formfeed in assembly list file
$PAGE settings Define page layout for assemly list file
$PRINT Specify alternative name for assembly list file
$NOPRINT Disable list file generation
$PRCTL Send control string to printer
$STITLE Set program subtitle in header of assembly list file
$TITLE Set program title in headerof assembly list file

Overview of miscellaneous assembler controls

Function Description
$CASE ON / OFF Case sensitive user names ON/OFF
DEBUG ON / OFF Generation of symbolic debug ON/OFF
DEBUG flags Select debug information
$FPU Allow single precision floating point instructions
$HW_ONLY Prevent substitution of assembly instructions by smaller or faster instructions
$IDENT LOCAL / GLOBAL Assembler treats labels by default as local or global
$MMU Allow memory management instructions
$OBJECT Alternative name for the generated object file
$TCdefect ON / OFF Enable/disable assembler check for specified functional problem
$TC2 Allow TriCore 2 instructions
$WARNING OFF Suppress all or some warnings

3.3.4 Detailed Description of Assembler Controls

The assembler recognizes both upper and lower case for controls.

$CASE ON / OFF

Syntax

Description

With the $CASE ON and $CASE OFF controls you specify whether the assembler operates in case sensitive mode or not. Default the assembler operates in case sensitive mode.

Example

Related option

Assembler option -c (Switch to case insensitive mode) in section 4.2, Assembler Options, of Chapter Tool Options.

Related information

-

$DEBUG ON / OFF

Syntax

Description

With the $DEBUG ON and $DEBUG OFF controls you turn the generation of debug infomation on or off. ($DEBUG ON is similar to the assembler option -gl).

If you use $DEBUG control with flags, you can set the following flags:

Debug information that is generated by the C compiler, is always passed to the object file.

Example

Related option

Assembler option -g (Select debug information) in section 4.2, Assembler Options, of Chapter Tool Options.

Related information

-

$FPU

Syntax

Description

With the $FPU control you instruct the assembler to accept and encode single precision floating point instructions in the assembly source file.

When you use this control, the define __FPU__ is set to 1. Default the define __FPU__ is set to 0 which tells the assembler not to accept single precision floating point instructions.

Example

Related option

Assembler option --fpu-present (Allow the use of single precision floating point instructions) in section 4.2, Assembler Options, of Chapter Tool Options.

Related information

-

$HW_ONLY

Syntax

Description

Normally the assembler replaces instructions by other, smaller or faster instructions. For example, the instruction jeq d0,#0,label1 is replaced by jz d0,label1.

With the $HW_ONLY control you instruct the assembler to encode all instruction as they are. The assembler does not substitute instructions with other, faster or smaller instructions.

Example

Related option

Assembler option -Og (Allow generic instructions) in section 4.2, Assembler Options, of Chapter Tool Options.

Related information

-

$IDENT

Syntax

Description

With the controls $IDENT LOCAL and $IDENT GLOBAL you tell the assembler how to treat symbols that you have not specified explicitly as local or global with the assembler directives .LOCAL or .GLOBAL.

Default the assembler treats all symbols as local symbols unless you have defined them explicitly as global.

Example

Related option

Assembler option -i (Treat labels by default local / global) in section 4.2, Assembler Options, of Chapter Tool Options.

Related information

Assembler directive .LOCAL (Local symbol declaration)
Assembler directive .GLOBAL (Global symbol declaration)

$LIST ON / OFF

Syntax

Description

If you generate a list file with the assembler option - l, you can use the $LIST ON and $LIST OFF controls to specify which source lines the assembler must write to the list file. Without the command line option -l, the $LIST ON and $LIST OFF controls have no effect.

The $LIST ON control actually increments a counter that is checked for a positive value and is symmetrical with respect to the $LIST OFF control. Note the following sequence:

The listing still would not be disabled until another NOLIST control was issued.

A label is not allowed with this control.

Example

Suppose you assemble the following assembly source with the assembler option -l:

The assembler generates a list file with the following lines:

Related option

Assembler option -l (Generate list file) in section 4.2, Assembler Options, of Chapter Tool Options.

Related information

Assembler control $LIST (Exclude / include lines in assembly list file)

Assembler function @LST() in section 3.2, Built-in Asembly Functions.

$LIST flags

Syntax

Description

If you generate a list file with the assembler option - l, you can use the $LIST controls to specify which type of source lines the assembler must exclude from the list file. Without the command line option -l, the $LIST control has no effect.

You can set the following flags to remove or include lines:

If you do not specify this control or the assembler option -Lflag, the assembler uses the default: -LcDEGilMnPqsVWXy.

Example

To exclude assembly files with controls from the list file:

Related option

Assembler option -L (List file formatting options) in section 4.2, Assembler Options, of Chapter Tool Options.

Related information

Assembler control $LIST ON / OFF (Assembly list file ON / OFF)

Assembler function @LST() in section 3.2, Built-in Asembly Functions.

$MMU

Syntax

Description

With the $MMU control you instruct the assembler to accept and encode memory management instructions in the assembly source file.

When you use this control, the define __MMU__ is set to 1.

Example

Related option

Assembler option --mmu-present (Allow the use of memory management instructions) in section 4.2, Assembler Options, of Chapter Tool Options.

Related information

-

$OBJECT

Syntax

Description

With the $OBJECT control you can specify an alternative name for the generated object file. With the $OBJECT OFF control, the assembler does not generate an object file at all.

Example

Related option

Assembler option -o (Define output filename) in section 4.2, Assembler Options, of Chapter Tool Options.

Related information

-

$PAGE

Syntax

Description

If you generate a list file with the assembler option - l, you can use the $PAGE control to format the generated list file.

width Number of characters on a line (1-255). Default is 132.

length Number of lines per page (10-255). Default is 66. As a special case a page length of 0 (zero) turns off all headers, titles, subtitles, and page breaks.

blanktop Number of blank lines at the top of the page. Default = 0.
Specify a value so that blanktop + blankbtm <= length - 10.

blankbtm Number of blank lines at the bottom of the page. Default = 0.
Specify a value so that blanktop + blankbtm <= length - 10.

blankleft Number of blank columns at the left of the page. Default = 0. Specify a value smaller than width.

If you use the $PAGE control without arguments, it causes a 'formfeed': the next source line is printed on the next page in the list file. The $PAGE control itself is not printed.

You can omit an argument by using two adjacent commas. If the remaining arguments after an argument are all empty, you can omit them.

Example

Related option

-

Related information

Assembler control $STITLE (Set program subtitle in header of list file)
Assembler control $TITLE (Set program title in header of list file)

Assembler option -l (Generate list file) in Section 4.2, Assembler Options, of Chapter Tool Options.

Assembler option -L (List file formatting options) in Section 4.2, Assembler Options, of Chapter Tool Options.

$PRCTL

Syntax

Description

If you generate a list file with the assembler option - l, you can use the $PRCTL control to send control strings to the printer.

The $PRCTL control simply concatenates its arguments and sends them to the listing file (the control line itself is not printed unless there is an error).

You can specify the following arguments:

exp a byte expression which may be used to encode non-printing control characters, such as ESC.

string an assembler string. which may be of arbitrary length, up to the maximum assembler-defined limits.

The $PRCTL control can appear anywhere in the source file; the assembler sends out the control string at the corresponding place in the listing file.

If a $PRCTL control is the last line in the last input file to be processed, the assembler insures that all error summaries, symbol tables, and cross-references have been printed before sending out the control string. In this manner, you can use a PRCTL control to restore a printer to a previous mode after printing is done.

Similarly, if the $PRCTL control appears as the first line in the first input file, the assembler sends out the control string before page headings or titles.

Example

Related option

-

Related information

Assembler option -l (Generate list file) in Section 4.2, Assembler Options, of Chapter Tool Options.

$PRINT / $NOPRINT

Syntax

Description

If you generate a list file with the assembler option - l, you can use the $PRINT control to specify an alternative name for the assembly list file.

With the $NOPRINT control, you overrule the assembler option -l and no list file is generated at all.

Example

Related option

-

Related information

Assembler option -l (Generate list file) in Section 4.2, Assembler Options, of Chapter Tool Options.

$STITLE

Syntax

Description

If you generate a list file with the assembler option - l, you can use the $STITLE control to specify the program subtitle which is printed at the top of all succeeding pages in the assembler list file below the title.

The specified subtitle is valid until the assembler encouters a new STITLE control. Default, the subtitle is empty.

The $STITLE control itself will not be printed in the source listing.

If the page width is too small for the title to fit in the header, it will be truncated.

Example

The header of the second page in the list file will now be:

TASKING TriCore Assembler vx.yrz Build nnn SN 00000000
This is the title                                         Page 2
This is the subtitle

Related option

-

Related information

Assembler control $TITLE (Set program title in header of list file)

Assembler option -l (Generate list file) in Section 4.2, Assembler Options, of Chapter Tool Options.

$TC

Syntax

Description

With this control you can enable or disable specific CPU functional problem checks.

To enable the assembler checks for all TriCore CPU TC112 problems (respectively TC113 problems) at once, use the control $TC112_DEFECTS (respectively $TC113_DEFECTS).

Example

Related option

Assembler option --silicon-bug (Check on CPU functional defect) in section 4.2, Assembler Options, of Chapter Tool Options.

Related information

See Chapter 8 , CPU Functional Problems, for more information about the individual problems.

$TC2

Syntax

Description

With the $TC2 control you instruct the assembler to accept and encode TriCore 2 instructions in the assembly source file.

When you use this control, the define __TC2__ is set to 1.

Example

Related option

Assembler option --is-tricore2 (Allow the use of TriCore 2 instructions) in section 4.2, Assembler Options, of Chapter Tool Options.

Related information

-

$TITLE

Syntax

Description

If you generate a list file with the assembler option - l, you can use the $TITLE control to specify the program title which is printed at the top of each page in the assembler list file.

Default, the title is empty.

If the page width is too small for the title to fit in the header, it will be truncated.

Example

The header of the list file will now be:

TASKING TriCore Assembler vx.yrz Build nnn SN 00000000
This is the title                                         Page 1

Related option

-

Related information

STITLE (Set program subtitle in assembly list file)

$WARNING OFF

Syntax

Description

With the $WARNING OFF control you can suppresses all warning messages or specific warning messages.

Example

Related option

Assembler option -w (Suppress some or all warnings) in section 4.2, Assembler Options, of Chapter Tool Options.

Related information

-


Copyright © 2003 Altium BV