6 ASSEMBLER DIRECTIVES

This chapter contains the following sections:

Introduction
Directives Overview
Debugging
Location Counter
Directives
ALIGN Directive
ASCII Directive
ASCIZ Directive
BIT Directive
BITADDR Directive
BSEG Directive
CALLS Directive
CODE Directive
COMMENT Directive
CSEG Directive
DATA Directive
DB Directive
DBIT Directive
DBSEG Directive
DD Directive
DEFINE Directive
DS Directive
DSEG Directive
DUP Directive
DUPA Directive
DUPC Directive
DUPF Directive
DW Directive
EDATA Directive
END Directive
ENDIF Directive
ENDM Directive
EQU Directive
ERROR Directive
ESEG Directive
EXITM Directive
EXTRN Directive
FAIL Directive
HCODE Directive
HCSEG Directive
HDATA Directive
HSEG Directive
IDATA Directive
IF Directive
INCLUDE Directive
ISEG Directive
LOCAL Directive
MACRO Directive
MSG Directive
NAME Directive
ORG Directive
PMACRO Directive
PUBLIC Directive
RADIX Directive
RSEG Directive
SEGMENT Directive
SET Directive
SYMB Directive
UNDEF Directive
USING Directive
WARN Directive
XDATA Directive
XSEG Directive
XSHORT Directive
XSSEG Directive

6.1 Introduction

Assembler directives, or pseudo instructions, are used to control the assembly process. Rather than being translated into an XA machine instruction, assembler directives are interpreted by the assembler. Only the DB, DW and DD directives actually cause code to be generated. The other directives perform actions such as defining or switching sections, defining symbols or changing the location counter. Upper and lower case letters are considered equivalent for assembler directives.

6.2 Directives Overview

Directive Description
DEBUGGING
ERROR Stop assembly on ERROR.
SYMB string, expr [,abs_expr] [,abs_expr] Generate hll symbol info record.
CALLS 'caller', 'callee'[, nr ]... [, 'callee'[, nr ]... ]... Create call graph.
SYMBOL DEFINITION
name SEGMENT type [attr]... Declare relocatable section.
equ-name EQU expression Assign expression to name.
set-name SET expression Define symbol for expression.
name CODE expression Assign CODE address to name.
name HCODE expression Assign HCODE address to name.
name DATA expression Assign DATA address to name.
name EDATA expression Assign EDATA address to name.
name IDATA expression Assign IDATA address to name.
name XDATA expression Assign XDATA address to name.
name XSHORT expression Assign XDATA SHORT address to name.
name HDATA expression Assign HDATA address to name.
bit-name BIT bit-address Assign bit address to name.
name BITADDR expression Assign DATA BITADDRESSABLE address to name.

STORAGE INITIALIZATION AND RESERVATION
[label:] DS abs_expr Reserve bytes.
[label:] DBIT abs_expr Reserve bits.
[label:] DB arg [,...] 1-byte  initialization.
[label:] DW arg [,...] 2-byte  initialization.
[label:] DD arg [,...] 4-byte  initialization.
[label:] ASCII string [,...] Create a string.
[label:] ASCIZ string [,...] Create null-padded string.
PROGRAM LINKAGE
LOCAL name [,...] Define symbols to be local
PUBLIC name [,...] Define symbols to be public
EXTRN type (sym[,sym]...) [,type (sym[,sym]...)]... Set symbols to be defined extern.
NAME module-name Define module name.
ASSEMBLY CONTROL
ALIGN expression Align location counter.
COMMENT delimiter text delimiter Start comment lines.
DEFINE symbol string Define substitution string.
END End assembly.
FAIL [{str | exp}[,{ str | exp}]...] Programmer generated error message.
INCLUDE string | <string > Include secondary file
MSG [{str | exp}[,{ str | exp}]...] Programmer generated message.
ORG expression Modify location counter.
RADIX expression Change input radix for constants.
UNDEF symbol Undefine DEFINE symbol.
WARN [{str | exp}[,{ str | exp}]...] Programmer generated warning.

SECTION SELECTION
[name] RSEG section_name Select relocatable section.
[name] CSEG [AT address] [attr] Select absolute CODE section.
[name] HCSEG [AT address] [attr] Select absolute HCODE section.
[name] DSEG [AT address] [attr] Select absolute DATA section.
[name] EDSEG [AT address] [attr] Select absolute EDATA section.
[name] ISEG [AT address] [attr] Select absolute IDATA section.
[name] XSEG [AT address] [attr] Select absolute XDATA section.
[name] XSSEG [AT address] [attr] Select absolute XSHORT section.
[name] HSEG [AT address] [attr] Select absolute HDATA section.
[name] BSEG [AT address] [attr] Select absolute BIT section.
[name] DBSEG [AT address] [attr] Select absolute BITADDR section.
MACROS AND CONDITIONAL ASSEMBLY
[label:] DUP expression Duplicate sequence of source lines.
[label:] DUPA dummy,arg[, arg]... Duplicate sequence with arguments.
[label:] DUPC dummy,string Duplicate sequence with characters.
[label:] DUPF dummy,[start],end[,increment] Duplicate sequence in loop.
ENDIF End of conditional assembly.
ENDM End of macro definition.
EXITM Exit macro.
IF expression
statements
[ELSE]
statments
ENDIF
Conditional assembly.
name MACRO [dummy argument list] Macro definition.
PMACRO symbol[,symbol]... Purge macro definition.
REGISTER BANK
USING expression Ignored, TASKING asm51 compatibility.

Table 6-1: asxa directives

6.3 Debugging

The compiler generates SYMB, CALLS and ERROR directives to pass high level language symbolic debug information via the assembler into the object file. The SYMB and ERROR directives are not meant for 'hand coded' assembly files. They are documented for completeness only and are supposed to be 'internal' to the tool chain. 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.

6.4 Location Counter

The location counter keeps track of the current offset within the current section that is being assembled. This value, symbolized by the character '$', is considered as an offset and can only be used in the same context where offset is allowed.

6.5 Directives

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

ALIGN

Syntax:

ALIGN expression

Description:

Align the location counter. Alignment makes the expr low order bits zero. The value represents the power of 2 (i.e. 2expr). The default alignment is on a multiple of 1 byte (the default value of expr is 0). So ALIGN 3 aligns the location counter at a multiple of 8. 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. Note that the section attribute PAGE aligns the section on a value of 256 (equivalent to ALIGN 8).

Examples:

ALIGN 2     ;align at 4 bytes
lab1: ALIGN 3
            ;lab1 is also aligned

ASCII

Syntax:

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

Description:

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

Examples:

HELLO:  ASCII "Hello world"
        ;Is the same as  DB "Hello world"

ASCIZ , DB

ASCIZ

Syntax:

[label:] ASCIZ string [, string]...

Description:

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

Examples:

HELLO:  ASCIZ "Hello world"
        ;Is the same as  DB "Hello world",0

ASCII , DB

BIT

Syntax:

name BIT expr

Description:

The BIT directive assigns a BIT address to a symbol name. The expression must evaluate into a number or BIT address and must not contain forward references. The symbol will be of type BIT.

Examples:

     RSEG A_SECT        ;relocatable bit
                        ;addressable data section
CTRL: DS  1

TST  BIT  CTRL.0        ;bit in relocatable byte
TST2 BIT  64H           ;absolute bit

BITADDR

Syntax:

name BITADDR expr

Description:

The BITADDR directive assigns a DATA BITADDRESSABLE address to a symbol name. The expression must evaluate into a number or DATA BITADDRESSABLE address and must not contain forward references. The symbol will be of type DATA BITADDRESSABLE.

Examples:

     RSEG BSPACE

ROOM: DS 4               ;reserve 4 bytes of
                         ;DATA BITADDRESSABLE
MORE_X BITADDR ROOM+2    ;define MORE_X to be 2
                         ;bytes after ROOM

BSEG

Syntax:

[name] BSEG [AT abs_expr] [NOCLEAR | CLEAR | INIT]

Description:

Switch to the absolute BIT section. The following statements will be assembled in the absolute mode within the BIT address space. The specified section remains in effect until another section directive is encountered. When no starting address and no attributes are specified, the assembler continues the last absolute BIT section. The first absolute BIT section starts at BIT address zero, that is 20H.0.

You can specify an optional name for the section.

Examples:

     section1 BSEG AT 73H          ;absolute bit section
     section2 BSEG AT 2EH.3        ;same as above

The paragraph 3.3 Sections in Chapter 3 Assembly Language.

CALLS

Syntax:

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

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

Stack information is also specified. After the callee name, for the stack a usage count can be specified.. The value specified (nr) is the stack usage (in bytes for the XA) at the time of the call including the 'RET' address of the current function.

This information is used by the linker to compute the used stack within the application. The information is found in the generated linker map file (-M option) within the call graph.

When callee is an empty name, this means we define the stack usage of the function itself.

Examples:

DA@nfunc SEGMENT DATA OVERLAY
DA@main SEGMENT DATA OVERLAY

CALLS 'main', 'nfunc', 5

The paragraph Relocatable Section Names in the chapter Assembly Language and the paragraph Linker Output in the chapter Linker.

CODE

Syntax:

name CODE expr

Description:

The CODE directive assigns a CODE address to a symbol name. The expression must evaluate into a number or CODE address and must not contain forward references. The symbol will be of type CODE.

Examples:

RESTART CODE 00H

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

CSEG

Syntax:

[name] CSEG [AT abs_expr] [NOCLEAR | CLEAR | INIT | ROMDATA]

Description:

Switch to the absolute CODE section. The following statements will be assembled in the absolute mode within the CODE address space. The specified section remains in effect until another section directive is encountered. When no starting address and no attributes are specified, the assembler continues the last absolute CODE section. The first absolute CODE section starts at address zero. When the assembler starts up, an implicit CSEG AT 0 is performed.

You can specify an optional name for the section.

Examples:

     section1 CSEG AT 00H          ;first absolute code
                          ;section

The paragraph 3.3 Sections in Chapter 3 Assembly Language.

DATA

Syntax:

name DATA expr

Description:

The DATA directive assigns a DATA address to a symbol name. The expression must evaluate into a number or DATA address and must not contain forward references. The symbol will be of type DATA.

Examples:

TSTART DATA 60H          ;define TSTART to be at
                         ;location 60H
TEND   DATA 6DH          ;define TEND to be at
                         ;location 6DH

DB

Syntax:

[label:] DB arg [,arg]...

Description:

The DB directive initializes memory with byte or bit values for each arg argument. This directive is allowed in a CODE or HCODE section or a data section with the INIT attribute. arg can be a numeric constant, a single or multiple character string constant, a symbol, or an expression. The DB directive can have one or more arguments separated by commas. Multiple arguments are stored in successive address locations. If multiple arguments are present, one or more of them can be null (two adjacent commas), in which case the corresponding address location will be filled with zeros. An error will occur if the evaluated argument value is too large to represent in a single byte.

In bit sections (BIT) the expression is evaluated as a boolean value. So, only expressions evaluating to 0 set the bit to zero (false). All other values set the bit to one (true).

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

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

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

Example: 'R' = 52H

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

Example:

Examples:

                              ;in a code section
HELLO: DB  'Hello World'      ;11 bytes in CODE
                              ;memory
NODD:  DB  1,3,5,7,9          ;initialize 5 bytes

CHARS: DB  'A','B','C','D'    ;generate four
                              ;characters
               ;in a bit section
FLAG: DB  0    ;set to 0
USED: DB  4    ;set to 1
OVERFLOW: DB   (NODD-HELLO)>10

DD , DS , DW

DBIT

Syntax:

[label:] DBIT abs_expr

Description:

The DBIT directive allocates space in bit units. It can be used only in a BIT type section. The expression must be a positive absolute expression without forward references. When a DBIT directive is encountered, the location counter of the current section is incremented by the number of bits specified with the expression.

Examples:

NBITS: DBIT 6     ; allocate 6 bits

DBSEG

Syntax:

[name] DBSEG [AT abs_expr] [NOCLEAR | CLEAR | INIT]

Description:

Switch to the absolute DATA BITADDRESSABLE section. The following statements will be assembled in the absolute mode within the DATA BITADDRESSABLE address space. The specified section remains in effect until another section directive is encountered. When no starting address and no attributes are specified, the assembler continues the last absolute DATA BITADDRESSABLE section. The first absolute DATA BITADDRESSABLE section starts at address 20H.

You can specify an optional name for the section.

Examples:

DAT_BSEG SEGMENT BITADDR        ;relocatable data
                                ;bitaddressable section
     section1 DBSEG   AT 08H    ;absolute  data
                                ;bitaddressable section

The paragraph 3.3 Sections in Chapter 3 Assembly Language.

DD

Syntax:

[label:] DD arg[,arg]...

Description:

The DD directive allocates and initializes a double-word of memory (32-bit) for each arg argument. This directive is only allowed in a CODE or HCODE section or a data section with the INIT attribute. arg can be a numeric constant, a single or double character string constant, a symbol, or an expression. The DCL directive can have one or more arguments separated by commas. Multiple arguments are stored in successive address locations. If multiple arguments are present, one or more of them can be null (two adjacent commas), in which case the corresponding address location will be filled with zeros. An error will occur if the evaluated argument value is too large to represent in a single double-word.

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

For each expression, the 32-bit value is stored with the low-order word first in the lowest address, followed by the high-order word.

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

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

Example: 'R' = 52H

2. Multiple character strings consisting of more than two characters are not allowed. Two-character strings are stored as if the ASCII value of the first character is the high byte value of the high word. The second character is used as the low byte. If three or four characters are present the third character is the high byte value of the low word and the fourth byte the low byte of the low word. If only one or two characters are present the rest of the words is filled with zeros.

Example:

Examples:

is equal to

DB , DS , DW

DEFINE

Syntax:

DEFINE symbol string

Description:

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

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

A label is not allowed with this directive.

Examples:

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

     DEFINE ARRAYSIZ '10 * SAMPLSIZ'

then the source line below:

     DS              ARRAYSIZ

would be transformed by the assembler to the following:

     DS              10 * SAMPLSIZ

UNDEF

DS

Syntax:

[label:] DS abs_expr

Description:

The DS directive allocates space in byte units. It can be used in any section except a BIT type section. This directive causes the run-time location counter to be advanced by the value of the absolute integer expression in the operand field. The block of memory reserved is not initialized to any value. The expression must be an integer greater than zero and cannot contain any forward references to address labels (labels that have not yet been defined).

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

Examples:

DS 3+2     ;allocate 5 bytes

DB , DD , DW

DSEG

Syntax:

[name] DSEG [AT abs_expr] [NOCLEAR | CLEAR | INIT]

Description:

Switch to the absolute DATA section. The following statements will be assembled in the absolute mode within the DATA address space. The specified section remains in effect until another section directive is encountered. When no starting address and no attributes are specified, the assembler continues the last absolute DATA section. The first absolute DATA section starts at address zero.

You can specify an optional name for the section.

Examples:

section1 DSEG    ;switch to an absolute DATA section

The paragraph 3.3 Sections in Chapter 3 Assembly Language.

DUP

Syntax:

[label:] DUP expression
.
.
ENDM

Description:

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

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

Examples:

The sequence of source input statements,

     COUNT SET  3
           DUP  COUNT          ; ASR BY COUNT
           ASR  R0
           ENDM

would generate the following in the source listing:

     COUNT SET  3
           DUP  COUNT          ; ASR BY COUNT
           ASR  R0
           ENDM

     ;     ASR  R0
     ;     ASR  R0
     ;     ASR  R0

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 runtime location counter at the start of the DUPA directive processing.

Examples:

If the input source file contained the following statements,

     DUPA VALUE,12,32,34
     DB   VALUE
     ENDM

then the assembler source listing would show

     DUPA VALUE,12,32,34
     DB   VALUE
     ENDM

     ;    DB  12
     ;    DB  32
     ;    DB  34

DUP , DUPC , DUPF , ENDM , MACRO

DUPC

Syntax:

[label:] DUPC dummy,string
.
.
ENDM

Description:

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

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

Examples:

If the input source file contained the following statements,

     DUPC VALUE,'123'
     DB   VALUE
     ENDM

then the assembler source listing would show

     DUPC VALUE,'123'
     DB   VALUE
     ENDM

     ;    DB  1
     ;    DB  2
     ;    DB  3

DUP , DUPA , DUPF , ENDM , MACRO

DUPF

Syntax:

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

Description:

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

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

Examples:

If the input source file contained the following statements,

     DUPF NUM,0,3
     MOV  R0,NUM
     ENDM

then the assembler source listing would show

     DUPF NUM,0,3
     MOV  R0,NUM
     ENDM

     ;    MOV  R0,0
     ;    MOV  R0,1
     ;    MOV  R0,2
     ;    MOV  R0,3

DUP , DUPA , DUPC , ENDM , MACRO

DW

Syntax:

[label:] DW arg[,arg]...

Description:

The DW directive initializes memory with word values for each arg argument.. This directive is only allowed in a CODE or HCODE section or a data section with the INIT attribute. arg can be a numeric constant, a single or double character string constant, a symbol, or an expression. The DW directive can have one or more arguments separated by commas. Multiple arguments are stored in successive address locations. If multiple arguments are present, one or more of them can be null (two adjacent commas), in which case the corresponding address location will be filled with zeros. An error will occur if the evaluated argument value is too large to represent in a single word.

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

Note that word values are stored in memory with the lower 8 bits on the lowest address.

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

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

Example: 'R' = 52H

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

Example:

Examples:

WRDS:   DW  34,'OK'        ;initialize 2 words in memory
TABLE:  DW 14,1635,2662H,'AB'

is equal to

TABLE:  DB 14,0,1635%256,6,62H,26H,'B','A'

DB , DD , DS

EDATA

Syntax:

name EDATA expr

Description:

The EDATA directive assigns an EDATA address to a symbol name. The expression must evaluate into a number or EDATA address and must not contain forward references. The symbol will be of type EDATA.

Examples:

TSTART EDATA 60H         ;define TSTART to be at
                         ;location 60H
TEND   EDATA 6DH         ;define TEND to be at
                         ;location 6DH

END

Syntax:

END

Description:

This should be the last statement of the assembly source. Text following the END directive is skipped and a warning message is generated if there is any. When the END is missing a warning is generated also. Empty lines, comment lines or lines consisting of tabs and spaces only, may follow the END directive. No warning message is generated in this case.

A label is not allowed with this directive.

Examples:

      DSEG
AVAR: DW  2


      CSEG
      .
      .

      END          ; End of assembler source

This line is ignored by asxa.

ENDIF

Syntax:

ENDIF

Description:

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

A label is not allowed with this directive.

Examples:

IF DEB
;Report building of the debug version
MSG 'Debug Version'
ENDIF 

IF

ENDM

Syntax:

ENDM

Description:

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

A label is not allowed with this directive.

Examples:

SWAP_MEM MACRO REG1,REG2     ;swap memory contents
     MOV R\REG1,R\REG2
     ENDM

DUP , DUPA , DUPC , MACRO

EQU

Syntax:

name EQU expression

Description:

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

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

An EQU symbol can be made public.

Examples:

COUNT EQU 0FFH     ;COUNT is the same as 0FFH

SET

ERROR

Syntax:

ERROR

Description:

The ERROR directive is generated by the C compiler indicating an error. The assembler stops when it encounters this directive.

ESEG

Syntax:

[name] ESEG [AT abs_expr] [NOCLEAR]

Description:

Switch to the absolute EDATA section. The following statements will be assembled in the absolute mode within the EDATA address space. The specified section remains in effect until another section directive is encountered. When no starting address and no attributes are specified, the assembler continues the last absolute EDATA section. The first absolute EDATA section starts at address zero.

You can specify an optional name for the section.

Examples:

section1 ESEG AT 100H      ; start EDATA section at
                           ; address 100H

The paragraph 3.3 Sections in Chapter 3 Assembly Language.

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
     MSG 'Macro parameter value out of range'
     EXITM ;Exit macro
     ENDIF
     .
     .
     .
     ENDM

DUP , DUPA , DUPC , MACRO

EXTRN

Syntax:

EXTRN type(sym[,sym]...) [,type(sym[, sym]...)]...

Description:

With the EXTRN directive it is possible to declare symbols that are defined PUBLIC in other modules. The section type of the symbols is specified with type, which must be one of the section types or NUMBER. The section type NUMBER does not correspond to a specific memory space, but indicates a typeless number.

Examples:

EXTRN  CODE (asym,get_info), DATA(count)
EXTRN  BIT(mybit,abit), NUMBER(tnum)
EXTRN  BITADDR(bitbyte)

PUBLIC

FAIL

Syntax:

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

Description:

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

A label is not allowed with this directive.

Examples:

FAIL 'Parameter out of range'

MSG , WARN

HCODE

Syntax:

name HCODE expr

Description:

The HCODE directive assigns a HCODE address to a symbol name. The expression must evaluate into a HCODE address and must not contain forward references. The symbol will be of type HCODE.

Examples:

RESTART HCODE 00H

HCSEG

Syntax:

[name] HCSEG [AT abs_expr] [NOCLEAR | CLEAR | INIT]

Description:

Switch to the absolute HCODE section. The following statements will be assembled in the absolute mode within the HCODE address space. The specified section remains in effect until another section directive is encountered. When no starting address and no attributes are specified, the assembler continues the last absolute HCODE section. The first absolute HCODE section starts at address zero.

You can specify an optional name for the section.

Examples:

section1 HCSEG AT 00H     ;first absolute hcode
                          ;section

The paragraph 3.3 Sections in Chapter 3 Assembly Language.

HDATA

Syntax:

name HDATA expr

Description:

The HDATA directive assigns a HDATA address to a symbol name. The expression must evaluate into a HDATA address and must not contain forward references. The symbol will be of type HDATA.

Examples:

TSTART HDATA 60H     ;define TSTART to be at
                     ;location 60H
TEND HDATA 6DH       ;define TEND to be at
                     ;location 6DH

HSEG

Syntax:

[name] HSEG [AT abs_expr] [NOCLEAR | CLEAR | INIT | ROMDATA]

Description:

Switch to the absolute HDATA section. The following statements will be assembled in the absolute mode within the HDATA address space. The specified section remains in effect until another section directive is encountered. When no starting address and no attributes are specified, the assembler continues the last absolute HDATA section. The first absolute HDATA section starts at address zero.

You can specify an optional name for the section.

Examples:

HDAT_SECT SEGMENT HDATA     ;reloc. hdata section
     section1 HSEG AT 70H   ;abs.  hdata section

The paragraph 3.3 Sections in Chapter 3 Assembly Language.

IDATA

Syntax:

name IDATA expr

Description:

The IDATA directive assigns an IDATA address to a symbol name. The expression must evaluate into a number or IDATA address and must not contain forward references. The symbol will be of type IDATA.

Examples:

TSTART IDATA 60H         ;define TSTART to be at
                         ;location 60H
TEND   IDATA 6DH         ;define TEND to be at
                         ;location 6DH

IF

Syntax:

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

Description:

Conditional Assembly Directive. Part of a program that is to be conditionally assembled must be bounded by an IF-ENDIF directive pair. If the optional ELSE 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 This means no forward references are allowed. Using labels in expression is allowed (e.g. _label2 - _label1) as long as the range is known in pass one. This means no generic branches can be used in that range since branch optimization is performed after pass one. To prevent any jump or branch optimization, use the -OJ option or the $OPTIMIZE control.

IF directives can be nested to any level. The ELSE directive will always refer to the nearest previous IF directive as will the ENDIF directive.

A label is not allowed with this directive.

Examples:

IF  XVAL<0
MSG 'Please select larger value for XVAL'
ENDIF

ENDIF

INCLUDE

Syntax:

INCLUDE string | <string>

Description:

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

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

A label is not allowed with this directive.

Examples:

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

ISEG

Syntax:

[name] ISEG [AT abs_expr] [NOCLEAR | CLEAR | INIT]

Description:

Switch to the absolute IDATA section. The following statements will be assembled in the absolute mode within the IDATA address space. The specified section remains in effect until another section directive is encountered. When no starting address and no attributes are specified, the assembler continues the last absolute IDATA section. The first absolute IDATA section starts at address zero.

You can specify an optional name for the section.

Examples:

     section1 ISEG AT 80H    ;start IDATA section at 
                             ;address 80H

The paragraph 3.3 Sections in Chapter 3 Assembly Language.

LOCAL

Syntax:

LOCAL symbol[,symbol]...

Description:

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

A label is not allowed with this directive.

Examples:

LOCAL LOOPA     ;LOOPA local to this module

PUBLIC

MACRO

Syntax:

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

Description:

Macro Definition. The dummy argument list has the form:

[dumarg[,dumarg]...]

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

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

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

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

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

Examples:

SWAP_MEM MACRO REG1,REG2     ;swap memory contents
     MOV R\REG1,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, can be specified optionally to describe the nature of the message.

A label is not allowed with this directive.

Examples:

MSG 'Generating tables'

FAIL , WARN

NAME

Syntax:

NAME module_name

Description:

The NAME directive is used to identify the current program module. If this directive is not present, the module name is taken from the input source file name.

Examples:

name my_prog ; module-name is my_prog

ORG

Syntax:

ORG expr

Description:

The ORG directive is used to alter the assembler's location counter of the current section to set a new program origin for statements following the directive. If the current section is absolute, the value will be an absolute address in the current section; if it is relocatable, the value is an offset from the base address of the instance of the section in the current module. The expression must not contain any forward references.

Examples:

ORG  ($ + 1000)     ; the current location counter
                    ; is incremented by 1000
ORG  60             ; set location counter to 60

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

PUBLIC

Syntax:

PUBLIC name [, name ]...

Description:

The PUBLIC directive allows symbols to be known outside the currently assembled module. Each symbol name can be declared public only once in a module. Any symbol declared PUBLIC must have been defined somewhere else in the program. This symbol must not be defined with the SET directive nor can it be equal to a register name. Symbols that are defined "public" are accessible from other modules using the EXTRN directive.

Examples:

public pub_symb  ;pub_symb is known outside module

EXTRN , LOCAL

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, 8, 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 suffix for base 10 numbers is the 'D' character. Note that if a constant is 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: DB 10     ; Evaluates to hex A
        RADIX 2
_RAD2:  DB 10     ; Evaluates to hex 2
        RADIX 16D
_RAD16: DB 10     ; Evaluates to hex 10
        RADIX 3   ; Bad radix expression

RSEG

Syntax:

RSEG section_name

Description:

Switch to (activate) a relocatable section previously defined by a SEGMENT directive. The following statements will be assembled in the relocatable section section_name, using the location counter of the named section. The specified section remains in effect until another section directive is encountered. The location counter of the relocatable section is initially set to zero.

Examples:

CD_SECT  SEGMENT CODE         ;relocatable code
                              ;section
     .
     .

         RSEG CD_SEG          ;select relocatable
                              ;code section

SEGMENT

Syntax:

name SEGMENT type [attr]...

Description:

The SEGMENT directive allows you to declare a relocatable section, assign a set of section attributes, and initialize the location counter to zero.

This directive is called 'SEGMENT' instead of 'SECTION' for compatibility reasons.

The section memory type specifies the address space where the section will reside. The optional section attributes define the properties of the section.

Examples:

DATSECT  SEGMENT  DATA          ;relocatable data
                                ;section

ROMS1 SEGMENT CODE ROMDATA      ;relocatable code
                                ;section with
                                ;attribute romdata

The paragraph Sections.

SET

Syntax:

name SET expression

Description:

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

SET symbols cannot be made public.

Examples:

COUNT  SET 0     ; Initialize COUNT

EQU

SYMB

Syntax:

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

Description:

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

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

UNDEF

Syntax:

UNDEF symbol

Description:

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

A label is not allowed with this directive.

Examples:

UNDEF DEBUG      ;Undefines the DEBUG substitution
                 ;string

DEFINE

USING

Syntax:

USING expression

Description:

This directive is ignored. It is only available for compatibily with the TASKING asm51 assembler.

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

XDATA

Syntax:

name XDATA expr

Description:

The XDATA directive assigns an XDATA address to a symbol name. The expression must evaluate into a number or XDATA address and must not contain forward references. The symbol will be of type XDATA.

Examples:

        RSEG    XSPACE

ROOM:   DS     4          ;reserve 4 bytes of XDATA
MORE_X  XDATA  ROOM+2     ;define MORE_X to be 2
                          ;bytes after ROOM

XSEG

Syntax:

[name] XSEG [AT abs_expr] [NOCLEAR | CLEAR | INIT]

Description:

Switch to the absolute XDATA section. The following statements will be assembled in the absolute mode within the XDATA address space. The specified section remains in effect until another section directive is encountered. When no starting address and no attributes are specified, the assembler continues the last absolute XDATA section. The first absolute XDATA section starts at address zero.

You can specify an optional name for the section.

Examples:

XDAT_SECT  SEGMENT  XDATA          ;reloc. xdata section
     section1 XSEG  AT 70H         ;abs.  xdata section

The paragraph 3.3 Sections in Chapter 3 Assembly Language.

XSHORT

Syntax:

name XSHORT expr

Description:

The XSHORT directive assigns an XDATA SHORT address to a symbol name. The expression must evaluate into a number or XDATA SHORT address and must not contain forward references. The symbol will be of type XDATA SHORT.

Examples:

        RSEG    XSPACE

ROOM:   DS     4          ;reserve 4 bytes of
                          ;XDATA SHORT
MORE_X  XSHORT ROOM+2     ;define MORE_X to be 2
                          ;bytes after ROOM

XSSEG

Syntax:

[name] XSSEG [AT abs_expr] [NOCLEAR | CLEAR | INIT]

Description:

Switch to the absolute XDATA SHORT section. The following statements will be assembled in the absolute mode within the XDATA SHORT address space. The specified section remains in effect until another section directive is encountered. When no starting address and no attributes are specified, the assembler continues the last absolute XDATA SHORT section. The first absolute XDATA SHORT section starts at address zero.

You can specify an optional name for the section.

Examples:

XDAT_SSECT SEGMENT  XSHORT         ;reloc. xdata short
                                   ;section
     section1 XSSEG  AT 70H        ;abs.  xdata short
                                   ;section

The paragraph 3.3 Sections in Chapter 3 Assembly Language.


Copyright © 2000 TASKING, Inc.