7 ASSEMBLER DIRECTIVES

This chapter contains the following sections:

Overview
Debugging
Assembly Control
Symbol Definition
Data Definition/Storage Allocation
Listing Control and Options
Object File Control

Macros and Conditional Assembly
Structured Programming
Directives
ALIGN Directive
BADDR Directive
BSB Directive
BSC Directive
BSM Directive
BUFFER Directive
CALLS Directive
COMMENT Directive
DC Directive
DCB Directive
DEFINE Directive
DS Directive
DSM Directive
DSR Directive
DUP Directive
DUPA Directive
DUPC Directive
DUPF Directive
END Directive
ENDBUF Directive
ENDIF Directive
ENDM Directive
ENDSEC Directive
EQU Directive
EXITM Directive
EXTERN Directive
FAIL Directive
FORCE Directive
GLOBAL Directive
GSET Directive
IF Directive
INCLUDE Directive
LIST Directive
LOCAL Directive
MACRO Directive
MSG Directive
NOLIST Directive
OPT Directive
ORG Directive
PAGE Directive
PMACRO Directive
PRCTL Directive
RADIX Directive
SCSJMP Directive
SCSREG Directive
SECTION Directive
SET Directive
STITLE Directive
SYMB Directive
TABS Directive
TITLE Directive
UNDEF Directive
VOID Directive
WARN Directive

7.1 Overview

Assembler directives, or pseudo instructions, are used to control the assembly process. Rather than being translated into a DSP56xxx 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.

There are some implementation differences between the TASKING DSP56xxx assembler and the Motorola CLAS assembler as described in the Appendix Migration from Motorola CLAS. The following directives are new:

ALIGN - Specify alignment

EXTERN - Declare extern symbols

SYMB - Pass high-level language debug information to the object file

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

VOID - Control DO loop optimization.

Assembler directives can be grouped by function into eight types:

1. Debugging

2. Assembly control

3. Symbol definition

4. Data definition/storage allocation

5. Listing control and options

6. Object file control

7. Macros and conditional assembly

8. Structured programming

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 for overlaying overlay sections.

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/ELSE/ENDIF constructs and MACRO/DUP definitions.

DEFINE - Define substitution string

END - End of source program

FAIL - Programmer generated error message

FORCE - Set operand forcing mode

HIMEM - Accepted for compatibility and ignored

INCLUDE - Include secondary file

LOMEM - Accepted for compatibility and ignored

MODE - Accepted for compatibility. A warning is issued when it is used.

MSG - Programmer generated message

ORG - Initialize memory space and location counters. The syntax of the ORG directive is extended for type checking. The overlay specification part of the ORG directive is accepted for compatibility. When it is supplied the assembler issues a warning.

RADIX - Change input radix for constants

RDIRECT - Accepted for compatibility and ignored

SCSJMP - Set structured control branching mode

SCSREG - Reassign structured control statement register

UNDEF - Undefine DEFINE symbol

VOID - Control DO loop optimization

WARN - Programmer generated warning

7.1.3 Symbol Definition

The directives used to control symbol definition are:

ENDSEC - End section

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

GSET - Set global symbol to a value; accepts forward references

LOCAL - Local symbol declaration

SECTION - Start section. Section scoping is resolved on module basis by the assembler and not on program basis by the linker. The results may differ from those with the Motorola CLAS assembler.

SET - Set symbol to a value; accepts forward references

XDEF - The assembler treats this directive as GLOBAL directive. A warning is issued when the XDEF directive is used.

XREF - The assembler treats this directive as EXTERN directive. A warning is issued when the XREF directive is used.

7.1.4 Data Definition/Storage Allocation

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

BADDR - Set buffer address

BSB - Block storage bit-reverse

BSC - Block storage of constant

BSM - Block storage modulo

BUFFER - Start buffer

DC - Define constant

DCB - Define constant byte

DS - Define storage

DSM - Define modulo storage

DSR - Define reverse carry storage

ENDBUF - End buffer

7.1.5 Listing Control and Options

The directives used to control the output listing are:

LIST - List the assembly

LSTCOL - Accepted for compatibility and ignored

NOLIST - Stop assembly listing

OPT - Assembler options. Not all options of the OPT directive are supported due to the different architecture of the TASKING assembler. Options that are not recognized are ignored.

PAGE - Top of page/size page

PRCTL - Send control string to printer

STITLE - Initialize program subtitle

TABS - Set listing tab stops

TITLE - Initialize program title

7.1.6 Object File Control

The following object file control directives are not supported. A warning is issued when the assembler encounters them in the input file.

COBJ - Accepted for compatibility

IDENT - Accepted for compatibility

SYMOBJ - Accepted for compatibility

7.1.7 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

MACLIB - Accepted for compatibility and ignored

MACRO - Macro definition

PMACRO - Purge macro definition

7.1.8 Structured Programming

The directives used for structured programming are:

.BREAK - Exit from structured loop construct

.CONTINUE - Continue next iteration of structured loop

.ELSE - Perform following statements when .IF false

.ENDF - End of .FOR loop

.ENDI - End of .IF condition

.ENDL - End of hardware loop

.ENDW - End of .WHILE loop

.FOR - Begin .FOR loop

.IF - Begin .IF condition

.LOOP - Begin hardware loop

.REPEAT - Begin .REPEAT loop

.UNTIL - End of .REPEAT loop

.WHILE - Begin .WHILE loop

7.2 Directives

The rest of this chapter contains individual descriptions of each of the assembler directives, listed alphabetically. They include usage guidelines, functional descriptions, and examples. Some directives require a label field, while in many cases a label is optional. If the description of an assembler directive does not indicate a mandatory or optional label field, then a label is not allowed on the same line as the directive.

Structured programming directives are discussed separately in Chapter 8, Structured Control Statements.

ALIGN

Syntax:

ALIGN expression

ALIGN CACHE (as563 only)

Description:

Align the location counter. The expression must be represented by a value of 2k. The default alignment is on a multiple of 1 word. 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.

With ALIGN CACHE the as563 assembler aligns the current location on a code cache boundary. The assembler inserts a gap at the start of the section so that the current location is aligned on a cache boundary. This alignment can only be done once per section.

Modulo- and reverse-carry buffers must be aligned on an address that equals to the first power of 2 greater than or equal to the given buffer expression. For example:

Depending on the section type the assembler has two cases for these directives:

- 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:

DSP563xx only:

BADDR

Syntax:

BADDR {M | R},expression

Description:

Set buffer address. The BADDR directive sets the run-time location counter to the address of a buffer of the give type, the length of which in words is equal to the value of expression. The buffer type may be either Modulo or Reverse-carry. If the run-time location counter is not zero, this directive first advances the run-time location counter to a base address that is a multiple of 2k, where 2k>= expression. An error will be issued if there is insufficient memory remaining to establish a valid base address. Unlike other buffer allocation directives, the run-time location counter is not advanced by the value of the integer expression in the operand field; the location counter remains at the buffer base address. The block of memory intended for the buffer is not initialized to any value.

The result of expression may have any memory space attribute but must be an absolute integer greater than zero and cannot contain any forward references to address labels (labels that have not yet been defined). If a Modulo buffer is specified, the expression must fall within the range 2 <= expression <= m, where m is the maximum address of the target DSP. If a Reverse-carry buffer is designated and expression is not a power of two a warning will be issued.

A label is not allowed with this directive.

Examples:

      ORG X:$100
      BADDR M,24  ;Circular buffer MOD 24
M_BUF DS  24

BSM , BSB , BUFFER , DSM , DSR

BSB

Syntax:

[label] BSB expression[,expression]

Description:

Block Storage Bit-Reverse. The BSB directive causes the assembler to allocate and initialize a block of words for a reverse-carry buffer. The number of words in the block is given by the first expression, which must evaluate to an absolute integer. Each word is assigned the initial value of the second expression. If there is no second expression, an initial value of zero is assumed. If the run-time location counter is not zero, this directive first advances the run-time location counter to a base address that is a multiple of 2k, where 2k is greater than or equal to the value of the first expression. An error will occur if the first expression contains address labels that are not yet defined (forward references) or if the expression has a value of less than or equal to zero. Also, if the first expression is not a power of two a warning will be generated. Both expressions can have any memory space attribute.

label, if present, will be assigned the value of the run-time location counter after a valid base address has been established.

Only one word of object code will be shown on the listing, regardless of how large the first expression is. However, the run-time location counter will be advanced by the number of words generated.

Examples:

BUFFER  BSB  BUFSIZ     ;Initialize buffer to zeros

BSC , BSM , DC

BSC

Syntax:

[label] BSC expression[,expression]

Description:

Block Storage of Constant. The BSC directive causes the assembler to allocate and initialize a block of words. The number of words in the block is given by the first expression, which must evaluate to an absolute integer. Each word is assigned the initial value of the second expression. If there is no second expression, an initial value of zero is assumed. If the first expression contains address labels that are not yet defined (forward references) or if the expression has a value of less than or equal to zero, an error will be generated. Both expressions can have any memory space attribute.

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

Only one word of object code will be shown on the listing, regardless of how large the first expression is. However, the run-time location counter will be advanced by the number of words generated.

Examples:

TOP    equ $0F
BOTTOM equ $0A
aLabel BSC  TOP-BOTTOM,$055

BSB , BSM , DC

BSM

Syntax:

[label] BSM expression[,expression]

Description:

Block Storage Modulo. The BSM directive causes the assembler to allocate and initialize a block of words for a modulo buffer. The number of words in the block is given by the first expression, which must evaluate to an absolute integer. Each word is assigned the initial value of the second expression. If there is no second expression, an initial value of zero is assumed. If the run-time location counter is not zero, this directive first advances the run-time location counter to a base address that is a multiple of 2k, where 2k is greater than or equal to the value of the first expression. An error will occur if the first expression contains address labels that are not yet defined (forward references), has a value of less than or equal to zero, or falls outside the range 2 <= expression <= m, where m is the maximum address of the target DSP. Both expressions can have any memory space attribute.

label, if present, will be assigned the value of the run-time location counter after a valid base address has been established.

Only one word of object code will be shown on the listing, regardless of how large the first expression is. However, the run-time location counter will be advanced by the number of words generated.

Examples:

BUFFER  BSM  BUFSIZ,$FFFFFFFF
        ;Initialize buffer to all ones

BSB , BSC , DC

BUFFER

Syntax:

BUFFER {M | R},expression

Description:

Start Buffer. The BUFFER directive indicates the start of a buffer of the given type. Data is allocated for the buffer until an ENDBUF directive is encountered. Instructions and most data definition directives may appear between the BUFFER and ENDBUF pair, although BUFFER directives may not be nested and certain types of directives such as ORG, SECTION, and other buffer allocation directives may not be used. The expression represents the buffer size. If less data is allocated than the size of the buffer, the remaining buffer locations will be uninitialized. If more data is allocated than the specified size of the buffer, an error is issued.

The BUFFER directive sets the run-time location counter to the address of a buffer of the given type, the length of which in words is equal to the value of expression. The buffer type may be either Modulo or Reverse-carry. If the run-time location counter is not zero, this directive first advances the run-time location counter to a base address that is a multiple of 2k, where 2k >= expression. An error will be issued if there is insufficient memory remaining to establish a valid base address. Unlike other buffer allocation directives, the run-time location counter is not advanced by the value of the integer expression in the operand field; the location counter remains at the buffer base address.

The result of expression may have any memory space attribute but must be an absolute integer greater than zero and cannot contain any forward references to address labels (labels that have not yet been defined). If a Modulo buffer is specified, the expression must fall within the range 2 <= expression <= m, where m is the maximum address of the target DSP. If a Reverse-carry buffer is designated and expression is not a power of two a warning will be issued.

For example:

Depending on the section type the assembler has two cases for these directives.

- 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.

A label is not allowed with this directive.

Examples:

      ORG  X:$100
      BUFFER M,24  ;Circular buffer MOD 24
M_BUF DC   0.5,0.5,0.5,0.5
      DS  20       ;Remainder uninitialized
      ENDBUF

BADDR , BSM , BSB , DSM , DSR , ENDBUF

CALLS

Syntax:

CALLS 'caller', 'callee' [, 'callee' ]...

Description:

Create a flow graph reference between caller and callees. The linker needs this information to build a flow graph, which steers the overlay algorithm. caller and callee are names of functions.

The CALLS directive should be used in hand coded assembly when the assembly code calls a C function. Make sure that the hand coded CALLS directive connects to the compiler generated call graph, i.e. the name of the caller must also be named as a callee in another CALLS directive.

Examples:

CALLS 'main', 'nfunc'

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/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.
         *

DC

Syntax:

[label] DC arg[,arg]...

Description:

Define Constant. The DC directive allocates and initializes a word of memory for each arg argument. arg may be a numeric constant, a single or multiple character string constant, a symbol, or an expression. The DC 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. If the DC directive is used in L memory, the arguments will be evaluated and stored as long word quantities. Otherwise, an error will occur if the evaluated argument value is too large to represent in a single DSP word.

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; floating point numbers are converted to binary values. 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' = $000052

2. Multiple character strings represent words whose bytes are composed of concatenated sequences of the ASCII representation of the characters in the string (unless the NOPS option is specified; see the OPT directive). If the number of characters is not an even multiple of the number of bytes per DSP word, then the last word will have the remaining characters left aligned and the rest of the word will be zero-filled. If the NOPS option is given, each character in the string is stored in a word whose lower seven bits represent the ASCII value of the character.

Example:

Examples:

TABLE  DC  1426,253,$2662,'ABCD'
CHARS  DC  'A','B','C','D'

BSC , DCB

DCB

Syntax:

[label] DCB arg[,arg]...

Description:

Define Constant Byte. The DCB directive allocates and initializes a byte of memory for each arg argument. arg may be a byte integer constant, a single or multiple character string constant, a symbol, or a byte expression. The DCB directive may have one or more arguments separated by commas. Multiple arguments are stored in successive byte locations. If multiple arguments are present, one or more of them can be null (two adjacent commas), in which case the corresponding byte location will be filled with zeros.

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); floating point numbers are not allowed. 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' = $000052

2. Multiple character strings represent words whose bytes are composed of concatenated sequences of the ASCII representation of the characters in the string (unless the NOPS option is specified; see the OPT directive). If the number of characters is not an even multiple of the number of bytes per DSP word, then the last word will have the remaining characters left aligned and the rest of the word will be zero-filled. If the NOPS option is given, each character in the string is stored in a word whose lower seven bits represent the ASCII value of the character.

Example:

Examples:

TABLE  DCB  'two',0,'strings',0
CHARS  DCB  'A','B','C','D'

BSC , DC

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 non-local labels. That is, the first of which must be alphabetic, 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.

DEFINE directive symbols that are defined within a section will only apply to that section. See the SECTION directive.

A label is not allowed with this directive.

Examples:

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:

UNDEF

DS

Syntax:

[label] DS expression

Description:

Define Storage. The DS directive reserves a block of memory the length of which in words 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. expression can have any memory space attribute. 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  DS  12     ; Sample buffer

DSM , DSR

DSM

Syntax:

[label] DSM expression

Description:

Define Modulo Storage. The DSM directive reserves a block of memory the length of which in words is equal to the value of expression. If the run-time location counter is not zero, this directive first advances the run-time location counter to a base address that is a multiple of 2k, where 2k >= expression. An error will be issued if there is insufficient memory remaining to establish a valid base address. Next the run-time location counter is advanced by the value of the integer expression in the operand field. expression can have any memory space attribute. The block of memory reserved is not initialized to any given value. The result of expression must be an absolute integer greater than zero and cannot contain any forward references to address labels (labels that have not yet been defined). The expression also must fall within the range 2 <= expression <= m, where m is the maximum address of the target DSP.

For example:

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.

label, if present, will be assigned the value of the run-time location counter after a valid base address has been established.

Examples:

       ORG  X:$100
M_BUF  DSM  24       ; Circular buffer MOD 24

DS , DSR

DSR

Syntax:

[label] DSR expression

Description:

Define Reverse Carry Storage. The DSR directive reserves a block of memory the length of which in words is equal to the value of expression. If the run-time location counter is not zero, this directive first advances the run-time location counter to a base address that is a multiple of 2k, where 2k >= expression. An error will be issued if there is insufficient memory remaining to establish a valid base address. Next the run-time location counter is advanced by the value of the integer expression in the operand field. expression can have any memory space attribute. The block of memory reserved is not initialized to any given value. The result of expression must be an absolute integer greater than zero and cannot contain any forward references to address labels (labels that have not yet been defined). Since the DSR directive is useful mainly for generating FFT buffers, if expression is not a power of two a warning will be generated.

For example:

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.

label, if present, will be assigned the value of the run-time location counter after a valid base address has been established.

Examples:

      ORG  X:$100
R_BUF DSR  8     ; Reverse carry buffer for
                 ; 16 point FFT

DS , DSM

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. expression can have any memory space attribute. 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,

would generate the following in the source listing:

Note that the lines

will only be shown on the source listing if the MD option is enabled. The lines

will only be shown on the source listing if the MEX option is enabled.

See the OPT directive in this chapter for more information on the MD and MEX options.

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,

then the assembler source listing would show

Note that the lines

will only be shown on the source listing if the MD option is enabled.

The lines

will only be shown on the source listing if the MEX option is enabled.

See the OPT directive in this chapter for more information on the MD and MEX options.

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,

then the assembler source listing would show

Note that the lines

will only be shown on the source listing if the MD option is enabled.

The lines

will only be shown on the source listing if the MEX option is enabled.

See the OPT directive in this chapter for more information on the MD and MEX options.

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 ties 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,

then the assembler source listing would show

Note that the lines

will only be shown on the source listing if the MD option is enabled. The lines

will only be shown on the source listing if the MEX option is enabled.

See the OPT directive in this chapter for more information on the MD and MEX options.

DUP , DUPA , DUPC , ENDM , MACRO

END

Syntax:

END [expression]

Description:

End of Source Program. The optional END directive indicates that the logical end of the source program has been encountered. The expression is only permitted here for compatibility reasons. It is ignored during assembly. The END directive cannot be used in a macro expansion.

A label is not allowed with this directive.

Examples:

END           ;End of source program

ENDBUF

Syntax:

ENDBUF

Description:

End Buffer. The ENDBUF directive is used to signify the end of a buffer block. The run-time location counter will remain just beyond the end of the buffer when the ENDBUF directive is encountered.

A label is not allowed with this directive.

Examples:

     ORG    :$100
BUF  BUFFER  R,64    ;uninitialized
                     ;reverse-carry buffer
     ENDBUF

BUFFER

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
DEBUG     ;Enter debug mode
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_SYM  MACRO  REG1,REG2   ;swap REG1,REG2 
    MOVE  R\?REG1,X0         ;using X0 as temp
    MOVE  R\?REG2,R\?REG1
    MOVE  X0,R\?REG2
    ENDM

DUP , DUPA , DUPC , MACRO

ENDSEC

Syntax:

ENDSEC

Description:

End Section. Every SECTION directive must be terminated by an ENDSEC directive.

A label is not allowed with this directive.

Examples:

        SECTION  COEFF
        ORG      Y:
VALUES  BSC      $100        ;Initialize to zero
        ENDSEC

SECTION

EQU

Syntax:

label EQU [{X: | Y: | L: | P: | E:}] expression

Description:

Equate Symbol to a Value. The EQU directive assigns the value and memory space attribute of expression to the symbol label. If expression has a memory space attribute of None, then it can optionally be preceded by any of the indicated memory space qualifiers to force a memory space attribute. An error will occur if the expression has a memory space attribute other than None and it is different than the forcing memory space attribute. The optional forcing memory space attribute is useful to assign a memory space attribute to an expression that consists only of constants but is intended to refer to a fixed address in a memory space.

The EQU directive is one of the directives that assigns a value other than the program counter to the label. The label cannot be redefined anywhere else in the program (or section, if SECTION directives are being used). The expression may be relative or absolute, and forward references are allowed.

Examples:

This would assign the value $4000 with a memory space attribute of X 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
      FAIL   'Macro parameter value out of range'
      EXITM  ;Exit macro
      ENDIF
      .
      .
      .
      ENDM

DUP , DUPA , DUPC , MACRO

EXTERN

Syntax:

EXTERN [(attrib[,attrib]...)] [mem:]symbol[,[mem:]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:

mem corresponds to one of the DSP memory spaces (X, Y, L, P, E).

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:

SECTION  FILER
EXTERN   AA,CC,DD        ;defined elsewhere
EXTERN   (near) Y:EE     ;short addressable external
                         ;symbol in Y memory
  .
  .
  .
ENDSEC

GLOBAL , SECTION

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 with no intervening white space, 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'

MSG , WARN

FORCE

Syntax:

FORCE {NEAR | FAR | NONE}

Description:

Set Operand Forcing Mode. The FORCE directive causes the assembler to force all immediate, memory, and address operands to the specified mode as if an explicit forcing operator were used. Note that if a relocatable operand value forced short is determined to be too large for the instruction word, an error will occur at link time, not during assembly. Explicit forcing operators override the effect of this directive.

For compatibility reasons the FORCE directive also accepts the arguments SHORT instead of NEAR and LONG instead of FAR.

A label is not allowed with this directive.

Examples:

FORCE  NEAR  ;force operands short

< , > , #< , #>

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 sections. This directive is not only valid if used within a program block bounded by the SECTION and ENDSEC directives, but also valid within the module body. If the symbols that appear in the operand field are not defined in the section, 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.

Examples:

SECTION  IO
GLOBAL   LOOPA     ;LOOPA will be globally
.                  ;accessible by other sections
.
.
ENDSEC

EXTERN , LOCAL , SECTION

GSET

Syntax:

label GSET expression

GSET label expression

Description:

Set Global Symbol to a Value. The GSET directive is used to assign the value of the expression in the operand field to the label. The GSET directive functions somewhat like the EQU directive. However, labels defined via the GSET directive can have their values redefined in another part of the program (but only through the use of another GSET or SET directive). The GSET directive is useful for resetting a global GSET symbol within a scope, where the SET symbol would otherwise be considered local. The expression in the operand field of a GSET may have forward references.

Examples:

COUNT  GSET  0     ; Initialize COUNT

EQU , SET

IF

Syntax:

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

Description:

Conditional Assembly. Part of a program that is to be conditionally assembled must be bounded by an IF-ENDIF directive pair. If the optional ELSE 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     @LST>0
DUP    @LST          ; Unwind LIST directive stack
NOLIST
ENDM
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'     ; Unix example
INCLUDE 'storage\mem.asm'    ; PC example
INCLUDE <data.asm>           ; Do not look in
                             ; current directory

LIST

Syntax:

LIST

Description:

List the Assembly. Print the listing from this point on. The LIST directive will not be printed, but the subsequent source lines will be output to the source listing. When the -l command line option has not been given, the LIST directive has no effect.

The LIST directive actually increments a counter that is checked for a positive value and is symmetrical with respect to the NOLIST directive. Note the following sequence:

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

A label is not allowed with this directive.

Examples:

IF  LISTON
LIST               ; Turn the listing back on
ENDIF

NOLIST

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 section, 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 on module level are defined "global" by default). This directive is not only valid if used within a program block bounded by the SECTION and ENDSEC directives, but also valid within the module body. The LOCAL directive must appear in the same scope as where symbol is defined in the section. If the symbols that appear in the operand field are not defined in the section, an error will be generated.

A label is not allowed with this directive.

Examples:

SECTION  IO
LOCAL  LOOPA       ;LOOPA local to this section
.
.
ENDSEC

SECTION, 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. Dummy argument names that are preceded by an underscore are not allowed. In the dummy argument list, the dummy arguments are separated by commas. The dummy argument list is separated from the MACRO directive 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_SYM  MACRO  REG1,REG2     ;swap REG1,REG2
    MOVE  R\?REG1,X0           ;using X0 as temp
    MOVE  R\?REG2,R\?REG1
    MOVE  X0,R\?REG2
    ENDM

DUP , DUPA , DUPC , DUPF , ENDM

MSG

Syntax:

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

Description:

Programmer Generated Message. The MSG directive will cause a message to be output by the assembler. The error and warning counts will not be affected. The MSG 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 with no intervening white space, can be specified optionally to describe the nature of the message.

A label is not allowed with this directive.

Examples:

MSG  'Generating sine tables'

FAIL , WARN

NOLIST

Syntax:

NOLIST

Description:

Stop Assembly Listing. Do not print the listing from this point on (including the NOLIST directive). Subsequent source lines will not be printed.

The NOLIST directive actually decrements a counter that is checked for a positive value and is symmetrical with respect to the LIST directive. Note the following sequence:

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

A label is not allowed with this directive.

Examples:

IF   LISTOFF
NOLIST              ; Turn the listing off
ENDIF

LIST , OPT

OPT

Syntax:

OPT option[,option]... [comment]

Description:

Assembler Options. The OPT directive is used to designate the assembler options. Assembler options are given in the operand field of the source input file and are separated by commas. For most options there is an equivalent command line option (see Chapter 2 ). All options have a default condition. Some options are reset to their default condition at the end of pass one. All options can have the prefix NO attached to them, which then reverses their meaning.

Options are read left-to-right, i.e. the rightmost takes precedence.

Options can be grouped by function into five different types:

1. Listing options

2. Parsing options

3. Code generation

4. Restriction handling

5. Optimizations

(module) means: last OPT directive counts
(flow) means: switchable on the fly, during parsing.

A label is not allowed with this directive.

Listing Options (module)

These options control what is reported in the listing file:

CC - Show cycle count

CPP - List cpp line information

CTRL - List controls

EMPTY - List empty lines

EQU - List equates

HLL - List high level language debug information

MD - List macro/dup definitions

MEX - List macro/dup expansions

MU - List section summary

SDEF - List symbol definitions

SECT - List section directives

WRAP - List wrapped part of source line

Parsing Options (flow)

These options control the parsing of the assembler:

AE - Check address expressions (W123)

IC - Ignore case in symbol names (before any symbol definition)

MSW - Warn on memory space incompatibilities (W124)

SVO - Preserve object file on errors (module)

UR - Flag unresolved references (W118)

W - Display warning messages

Wnum - Display warning message number num

Code Generation (module)

These options deal with code generation:

CACHE128 - Select code page size of 128 (as563 only)

CACHE256 - Select code page size of 256 (as563 only)

JMPABS - Select the absolute branch mode. (flow)
(as563 only)

JMPREL - Select the relative branch mode. (flow)
(as563 only)

PS - Pack strings

SBM - Create constant values for 16-bit mode
(as563 only)

XLL - Generate assembly level debug information

Restriction Handling (module)

These options deal with pipeline restrictions:

RP - Remove all pipeline restrictions

RPDO - Remove DO/ENDDO pipeline restrictions

RPRN - Remove Rn, Nn and Mn pipeline restrictions

RPSP - Remove stack restrictions

Optimizations (module)

These options deal with assembler optimizations:

OP - Perform all optimizations

OPHLL - Move symbolic debug locations

OPJMP - Perform branch optimization

OPNOP - Remove NOP instructions (flow)

OPPM - Move parallelization

OPREP - Single instruction DO to REP (flow)

OPSP - Split parallel instruction before optimization

OPSPEED - Optimize for speed at the cost of code size

ORDER - Keep instructions in the same order (flow)

Detailed description of assembler options

Following are descriptions of the individual options. An option is specified default if it is the behaviour of the assembler when you specify neither the OPT option nor its corresponding command line option.

AE Check address expressions for appropriate arithmetic operations. For example, this will check that only valid add or subtract operations are performed on address terms. This option is equivalent to W123.

CACHE128 Select code page size of 128 (as563 only).

CACHE256 Select code page size of 256 (as563 only).

CC Show cycle count (-LY).

CPP List source lines containing C preprocessor line information (#line directives) (-LI).

CTRL List source lines containing assembler controls (-LC, default).

EMPTY List empty source lines (-LN).

EQU List source lines containing assembler equates (lines with EQU or '=') (-LQ, default).

HLL List high level language symbolic debug information (lines with SYMB directive) (-LS).

IC Ignore case in symbol, section, and macro names. This directive must be issued before any symbols, sections, or macros are defined. (same as -c)

JMPABS Select the absolute branch mode (as563 only) (-Ja).

JMPREL Select the relative branch mode as563 only) (-Jr).

MD List macro/dup definitions (-LM, default).

MEX List macro/dup expansions (-LX, default).

MSW Issue warning on memory space incompatibilities. This option is equivalent to W124.

MU List section summary. The size of each section is listed (-t).

NOAE Do not check address expressions. This option is equivalent to NOW123 (-w123).

NOCC Hide cycle count (-Ly).

NOCPP Do not list source lines containing C preprocessor line information (-Li, default).

NOCTRL Do not list source lines containing assembler controls (-Lc).

NOEMPTY Do not list empty source lines (-Ln, default).

NOEQU Do not list source lines containing assembler equates (-Lq).

NOHLL Do not list high level language symbolic debug information (-Ls, default).

NOIC (default) Operate case sensitive in symbol, section, and macro names. This directive must be issued before any symbols, sections, or macros are defined.

NOJMPABS (default) Default branch mode (as563 only).

NOJMPREL (default) Default branch mode (as563 only).

NOMD Do not list macro/dup definitions (-Lm).

NOMEX Do not list macro/dup expansions (-Lx).

NOMSW Do not issue warning on memory space incompatibilities. This option is equivalent to NOW124 (-w124).

NOMU (default) Do not list section size summary.

NOOP Do not perform any optimizations (-OGJMNPRS). This is the same as specifying NOOPHLL, NOOPJMP, NOOPNOP, NOOPPM, NOOPSPEED, NOOPREP and NOOPSP.

NOOPHLL Retain symbolic debug locations (-OG, default).

NOOPJMP Do not perform branch optimization (-OJ, default).

NOOPNOP Do not perform NOP removal (-ON, default).

NOOPPM Do not perform parallel move optimization (-OM, default).

NOOPREP Do not perform single instruction DO to REP optimization (-OR, default).

NOOPSP Do not split parallel move instructions before performing optimizations (-OS, default).

NOOPSPEED
Do not perform speed optimization (-OP).

NOORDER End an instruction sequence started by ORDER.

NOPS Do not pack strings in DC and DCB directive. Individual bytes in strings will be stored one byte per word.

NORP Do not generate instructions to accommodate pipeline delay (-RDRS, default).

NORPDO Do not remove DO/ENDDO restrictions (-RD, default).

NORPRN Do not remove Rn, Nn, and Mn register restrictions (-RR, default).

NORPSP Do not remove stack restrictions (-RS, default).

NOSDEF Do not list source lines containing symbol definition directives (-Le).

NOSECT Do not list source lines containing section directives (-Ld).

NOSVO Remove object file on errors. Normally any object file produced by the assembler is preserved if errors occur during assembly. This option must be given before any code or data is generated (-e).

NOUR Do not flag unresolved external references. This option is equivalent to NOW118 (-w118).

NOW Do not print warning messages (-w).

NOWnum Do not print warning message with number num (-wnum).

NOWRAP Do not list wrapped part of source lines (-Lw).

NOXLL (default) Do not generate assembly level debug information.

OP Perform all optimizations ( -O ). This is the same as specifying OPHLL, OPJMP, OPNOP, OPPM, OPSPEED, OPREP and NOOPSP.

OPHLL Move symbolic debug locations to perform better parallel move optimization (-Og).

OPJMP Perform branch optimization (-Oj). The assembler tries to replace branches with shorter or faster functionally equivalent branches.

OPNOP Remove existing NOP instructions (-On).

OPPM Perform parallel move optimization (-Om).

OPREP Replace a single instruction DO loop with a REP instruction (-Or).

OPSP Split parallel move instructions before performing optimizations (-Os).

OPSPEED Optimize for speed at the cost of code size (-Op, default).

ORDER Mark the begin of an instruction sequence in which the instructions must be kept in the same order. The instruction sequence must end with an OPT NOORDER directive.

PS (default) Pack strings in DC and DCB directive. Individual bytes in strings will be packed into consecutive target words for the length of the string.

RP Remove all pipeline restrictions. Generate NOP instructions to accommodate pipeline delay. The assembler will output a NOP instruction into the output stream and the issues a warning that it has done so (-R).

RPDO Remove DO/ENDDO restrictions (-Rd).

RPRN Remove Rn, Nn, and Mn register restrictions. If an address register is loaded in one instruction then the contents of the register is not available for use as a pointer until after the next instruction. Ordinarily when the assembler detects this condition it issues a warning message. The RPRN option will cause the assembler to output a NOP instruction into the output stream and the assembler issues a warning that it has done so (-Rr).

RPSP Remove stack restrictions (-Rs).

SDEF List source lines containing symbol definition directives (-LE, default).

SECT List source lines containing section directives (-LD, default).

SVO (default) Preserve object file on errors. This option must be given before any code or data is generated.

UR Generate a warning at assembly time for each unresolved external reference. This option is equivalent to W118.

W Print all warning messages.

Wnum Print warning message with number num.

WRAP List wrapped part of source line (-LW, default).

XLL Generate assembly level debug information (-g).

Examples:

OPT  OPNOP,XLL   ;NOP removal and assembly debug
OPT  RP,MU       ;Remove restrictions, 
                 ;list section summary

ORG

Syntax:

ORG mem[mapcnt]:[abs-loc][,overlay]

ORG mem[[,name][,attrib]...]:[abs-loc][,overlay]

where,
mapcnt is defined as:
[rlc][map]
or: [map][(rce)]

Description:

Initialize Memory Space and Location Counters. The ORG directive is used to determine in which section the code following the directive, up to the next ORG directive, will be located. The absolute location of the section in memory can be set using this directive.

To uniquely identify a section between different object files sections can be given names. This name can be any character string, as long as it does not start with a space. When a section does not have a name, it is called a nameless section.

The ORG directive has two possibilities. The first is Motorola compatible, the second introduces named sections. The Motorola compatible variant defines a nameless section. The section attributes are as defined by the mapping attribute. There is no possibility to state that this entire section is located in short addressable memory, other than to give an absolute location in short memory. As these sections do not have a name, the linker cannot concatenate these sections with equivalent section definitions between different object files.

The second variant defines a named section. The name gives the linker the possibility to concatenate these sections from different object files. Every definition of a named section should use the same section attributes.

A label is not allowed with this directive.

mem This defines in which memory space (X, Y, L, P or E) the section is located. Currently the E memory space is not supported.

rlc Which run-time counter H, L. or default (if neither H or L is specified), that is associated with mem, will be used as the run-time location counter:

1. not giving a location counter equals to using the location counter '0',

2. the 'L' location counter equals to the location counter '1', and

3. the 'H' location counter equals to the location counter '2'.

map Indicates the run-time physical mapping to DSP memory: I - internal, E - external, R - ROM, A - port A, B - port B. If not present, no explicit mapping is done.

rce Non-negative absolute integer expression representing the counter number to be used as the run-time location counter. Must be enclosed in parentheses. Should not exceed the value 65535.

name The name defines the section name. This is a string of printable characters. The only exception is that it may not start with a space. In the latter case the name will not be written into the object file.

attrib The attributes conform to the possibilities given by the Motorola type ORG, but are written with entire words instead of letters. Possibilities are:

abs-loc Initial value to assign to the run-time counter used as the rlc. abs-loc must be an absolute expression.

overlay The overlay part is not supported. When encountered it is skipped and a warning is issued. Overlay descriptions can be described to the locator using the locator description file.

A previously defined section can be continued by giving its name or, for the Motorola ORG-variant, by giving its memory space and location counter.

A named section cannot be continued by only giving its memory space. This will continue the named section with location counter zero!

Examples:

ORG P:$1000
ORG PHE:

Definitions Continuation

Chapter Software Concept and Appendix Migration from Motorola CLAS.

PAGE

Syntax:

PAGE [exp1[,exp2,..., exp5]]

Description:

Top of Page/Size Page. The PAGE directive has two forms:

1. If no arguments are supplied, then the assembler will advance the listing to the top of the next page. In this case, the PAGE directive will not be output.

2. The PAGE directive with arguments can be used to specify the printed format of the output listing. Arguments may be any positive absolute integer expression. The arguments in the operand field (as explained below) are separated by commas. Any argument can be left as the default or last set value by omitting the argument and using two adjacent commas. The PAGE directive with arguments will not cause a page eject and will be printed in the source listing.

A label is not allowed with this directive.

The arguments in order are:

PAGE_WIDTH exp1

PAGE_LENGTH exp2

BLANK_TOP exp3

BLANK_BOTTOM exp4

BLANK_LEFT exp5

The following relationship must be maintained:

Examples:

PAGE  132,,3,3   ;Set width to 132, 
                 ;3 line top/bottom margins
PAGE             ;Page eject

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

PRCTL

Syntax:

PRCTL exp|string[,exp|string]...

Description:

Send Control String to Printer. PRCTL simply concatenates its arguments and ships them to the listing file (the directive line itself is not printed unless there is an error). exp is a byte expression and string is an assembler string. A byte expression would be used to encode non-printing control characters, such as ESC. The string may be of arbitrary length, up to the maximum assembler-defined limits.

PRCTL may appear anywhere in the source file and the control string will be output at the corresponding place in the listing file. However, if a PRCTL directive 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. This is so a PRCTL directive can be used to restore a printer to a previous mode after printing is done. Similarly, if the PRCTL directive appears as the first line in the first input file, the control string will be output before page headings or titles.

The PRCTL directive only works if the -l command line option is given; otherwise it is ignored.

A label is not allowed with this directive.

Examples:

PRCTL  $1B,'E'  ;Reset HP LaserJet printer

RADIX

Syntax:

RADIX expression

Description:

Change Input Radix for Constants. Changes the input base of constants to the result of expression. The absolute integer expression must evaluate to one of the legal constant bases (2, 10, or 16). The default radix is 10. The RADIX directive allows the programmer to specify constants in a preferred radix without a leading radix indicator. The radix prefix for base 10 numbers is the grave accent (`). Note that if a constant us used to alter the radix, it must be in the appropriate input base at the time the RADIX directive is encountered.

A label is not allowed with this directive.

Examples:

_RAD10     DC  10   ; Evaluates to hex A
    RADIX  2
_RAD2      DC  10   ; Evaluates to hex 2
    RADIX  `16
_RAD16     DC  10   ; Evaluates to hex 10
    RADIX  3        ; Bad radix expression

SCSJMP

Syntax:

SCSJMP {NEAR | FAR | NONE}

Description:

Set Structured Control Statement Branching Mode. The SCSJMP directive analogous to the FORCE directive, but it only applies to branches generated automatically by structured control statements (see Chapter 8 ). There is no explicit way, as with a forcing operator, to force a branch short or long when it is produced by a structured control statement. This directive will cause all branches resulting from subsequent structured control statements to be forced to the specified mode.

Just like the FORCE pseudo-op, errors can result if a value is too large to be forced short. For relocatable code, the error may not occur until the linking phase.

For compatibility reasons the SCSJMP directive also accepts the arguments SHORT instead of NEAR and LONG instead of FAR.

A label is not allowed with this directive.

Examples:

SCSJMP   NEAR   ;force all subsequent SCS 
                ;jumps short

FORCE , SCSREG

SCSREG

Syntax:

SCSREG [srcreg[,dstreg[,tmpreg[,extreg]]]]

Description:

Reassign Structured Control Statement Registers. The SCSREG directive reassigns the registers used by structured control statement (SCS) directives (see Chapter 8 ). It is convenient for reclaiming default SCS registers when they are needed as application operands within a structured control construct. srcreg is ordinarily the source register for SCS data moves. dstreg is the destination register. tmpreg is a temporary register for swapping SCS operands. extreg is an extra register for complex SCS operations. With no arguments SCSREG resets the SCS registers to their default assignments.

The SCSREG directive should be used judiciously to avoid register context errors during SCS expansion. Source and destination registers may not necessarily be used strictly as source and destination operands. The assembler does no checking of reassigned registers beyond validity for the target processor. Errors can result when a structured control statement is expanded and an improper register reassignment has occurred. It is recommended that the MEX option (see the OPT directive) be used to examine structured control statement expansion for relevant constructs to determine default register usage and applicable reassignment strategies.

A label is not allowed with this directive.

Examples:

SCSREG   Y0,B     ;Reassign SCS source and 
                  ;dest. registers

OPT (MEX), SCSJMP

SECTION

Syntax:

SECTION scope_name
.
.
section source statements
.
.
ENDSEC

Description:

Start Scope. The SECTION directive defines the start of a scope. All symbols that are defined within a scope have the scope_name associated with them as their scope name. This serves to protect them from like-named symbols elsewhere in the program. A symbol defined inside any given scope is private to that scope.

Symbols within a scope are generally distinct from other symbols used elsewhere in the source program, even if the symbol name is the same. This is true as long as the scope name associated with each symbol is unique and the symbol is not declared public (GLOBAL). Symbols that are defined outside of a scope are considered global symbols and have no explicit scope name associated with them. Global symbols may be referenced freely from inside or outside of any scope, as long as the global symbol name does not conflict with another symbol by the same name in a given scope.

The division of a program into scopes controls not only labels and symbols, but also macros and DEFINE directive symbols. Macros defined within a scope are private to that scope and are distinct from macros defined in other scopes even if they have the same macro name. Macros defined outside of scopes are considered global and may be used within any scope. Similarly, DEFINE directive symbols defined within a scope are private to that scope and DEFINE directive symbols defined outside of any scope are globally applied. There are no directives that correspond to GLOBAL for macros or DEFINE symbols, and therefore, macros and DEFINE symbols defined in a scope can never be accessed globally. If global accessibility is desired, the macros and DEFINE symbols should be defined outside of any scope.

Section scopes can be nested to any level. When the assembler encounters a nested scope, the current scope is stacked and the new scope is used. When the ENDSEC directive of the nested scope is encountered, the assembler restores the old scope and uses it. The ENDSEC directive always applies to the most previous SECTION directive. Nesting scopes provides a measure of scoping for symbol names, in that symbols defined within a given scope are visible to other scopes nested within it. For example, if scope B is nested inside scope A, then a symbol defined in scope A can be used in scope B without GLOBALing in scope A or EXTERNing in scope B.

Scopes may also be split into separate parts. That is, scope_name can be used multiple times with SECTION and ENDSEC directive pairs. If this occurs, then these separate (but identically named) scopes can access each others symbols freely without the use of the GLOBAL and EXTERN directives. If the GLOBAL and EXTERN directives are used within one scope, they apply to all scopes with the same scope name. The reuse of the scope name is allowed to permit the program source to be arranged in an arbitrary manner (for example, all statements that reserve X space storage locations grouped together), but retain the privacy of the symbols for each scope.

A label is not allowed with this directive.

Examples:

SECTION  TABLES      ;TABLES will be the scope name

ORG , GLOBAL , LOCAL , EXTERN

SET

Syntax:

label SET expression

SET label 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 label. The SET directive functions somewhat like the EQU directive. However, labels 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.

Examples:

COUNT  SET  0    ; Initialize COUNT

EQU , GSET

STITLE

Syntax:

STITLE [string]

Description:

Initialize Program Sub-Title. The STITLE directive initializes the program subtitle to the string in the operand field. The subtitle will be printed on the top of all succeeding pages until another STITLE directive is encountered. The subtitle is initially blank. The STITLE directive will not be printed in the source listing. An STITLE directive with no string argument causes the current subtitle to be blank.

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

A label is not allowed with this directive.

Examples:

STITLE  'COLLECT SAMPLES'

TITLE

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.

TABS

Syntax:

TABS tabstops

Description:

Set Listing Tab Stops. The TABS directive allows resetting the listing file tab stops from the default value of 8.

A label is not allowed with this directive.

Examples:

TABS  4    ;Set listing file tab stops to 4

TITLE

Syntax:

TITLE [string]

Description:

Initialize Program Title. The TITLE directive initializes the program title to the string in the operand field. The program title will be printed on the first page of the list file. The title is initially blank. The TITLE directive will not be printed in the source listing. A TITLE directive with no string argument causes the current title to be blank. For titles on succeeding pages use the STITLE directive.

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

A label is not allowed with this directive.

Examples:

TITLE  'FIR FILTER'

STITLE

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

VOID

Syntax:

label VOID register [, register]...

Description:

The VOID directive defines which registers may contain unknown values when the label is reached. The assembler may use this information when optimizing the assembly program.

Examples:

When you use the VOID directive at a DO loop label, the assembler tries to duplicate instructions from the loop head to the loop tail and prior to the loop.

The following example,

    DO    #10,label
    move  x:(r1)+,a
    ; ... some other code
    lsl   b
label:    void  r1,a

can be optimized to:

    move  x:(r1)+,a
    DO    #10,label
    ; ... some other code
    lsl   b  x:(r1)+,a
label:    void  r1,a

WARN

Syntax:

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

Description:

Programmer Generated Warning. The WARN 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 WARN 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 with no intervening white space, can be specified optionally to describe the nature of the generated warning.

A label is not allowed with this directive.

Examples:

WARN  'parameter too large'

FAIL , MSG


Copyright © 2002 Altium BV