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
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.
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
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.
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.
The rest of this chapter contains an alphabetical list of the assembler directives.
ALIGN expression
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).
ALIGN 2 ;align at 4 bytes lab1: ALIGN 3 ;lab1 is also aligned
[label:] ASCII string [, string]...
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.
HELLO: ASCII "Hello world" ;Is the same as DB "Hello world"
[label:] ASCIZ string [, string]...
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.
HELLO: ASCIZ "Hello world" ;Is the same as DB "Hello world",0
name BIT expr
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.
RSEG A_SECT ;relocatable bit ;addressable data section CTRL: DS 1 TST BIT CTRL.0 ;bit in relocatable byte TST2 BIT 64H ;absolute bit
name BITADDR expr
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.
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
[name] BSEG [AT abs_expr] [NOCLEAR | CLEAR | INIT]
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.
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 'caller', 'callee'[, nr ]... [, 'callee'[, nr ]... ]...
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.
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.
name CODE expr
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.
RESTART CODE 00H
COMMENT delimiter
.
.
delimiter
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.
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. *
[name] CSEG [AT abs_expr] [NOCLEAR | CLEAR | INIT | ROMDATA]
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.
section1 CSEG AT 00H ;first absolute code ;section
The paragraph 3.3
Sections in Chapter 3 Assembly Language.
name DATA expr
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.
TSTART DATA 60H ;define TSTART to be at ;location 60H TEND DATA 6DH ;define TEND to be at ;location 6DH
[label:] DB arg [,arg]...
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:
'ABCD' = 41H, 42H, 43H, 44H
;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
[label:] DBIT abs_expr
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.
NBITS: DBIT 6 ; allocate 6 bits
[name] DBSEG [AT abs_expr] [NOCLEAR | CLEAR | INIT]
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.
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.
[label:] DD arg[,arg]...
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:
'ABC' = 41424300H
TABLE: DD 14,1635,62267345H,'AB'
is equal to
TABLE: DW 14,0,1635,0,7345H,6226H,0,'AB'
DEFINE symbol string
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.
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
[label:] DS abs_expr
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.
DS 3+2 ;allocate 5 bytes
[name] DSEG [AT abs_expr] [NOCLEAR | CLEAR | INIT]
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.
section1 DSEG ;switch to an absolute DATA section
The paragraph 3.3
Sections in Chapter 3 Assembly Language.
[label:] DUP expression
.
.
ENDM
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.
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
[label:] DUPA dummy,arg[,arg]...
.
.
ENDM
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.
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
[label:] DUPC dummy,string
.
.
ENDM
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.
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
[label:] DUPF dummy,[start],end[,increment]
.
.
ENDM
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.
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
[label:] DW arg[,arg]...
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:
'AB' = 4142H
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'
name EDATA expr
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.
TSTART EDATA 60H ;define TSTART to be at ;location 60H TEND EDATA 6DH ;define TEND to be at ;location 6DH
END
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.
DSEG AVAR: DW 2 CSEG . . END ; End of assembler source This line is ignored by asxa.
ENDIF
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.
IF DEB ;Report building of the debug version MSG 'Debug Version' ENDIF
ENDM
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.
SWAP_MEM MACRO REG1,REG2 ;swap memory contents MOV R\REG1,R\REG2 ENDM
name EQU expression
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.
COUNT EQU 0FFH ;COUNT is the same as 0FFH
ERROR
The ERROR directive is generated by the C compiler indicating an error. The assembler stops when it encounters this directive.
[name] ESEG [AT abs_expr] [NOCLEAR]
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.
section1 ESEG AT 100H ; start EDATA section at ; address 100H
The paragraph 3.3
Sections in Chapter 3 Assembly Language.
EXITM
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.
CALC MACRO XVAL,YVAL IF XVAL<0 MSG 'Macro parameter value out of range' EXITM ;Exit macro ENDIF . . . ENDM
EXTRN type(sym[,sym]...) [,type(sym[, sym]...)]...
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.
EXTRN CODE (asym,get_info), DATA(count) EXTRN BIT(mybit,abit), NUMBER(tnum) EXTRN BITADDR(bitbyte)
FAIL [{str | exp}[,{str | exp}]...]
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.
FAIL 'Parameter out of range'
name HCODE expr
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.
RESTART HCODE 00H
[name] HCSEG [AT abs_expr] [NOCLEAR | CLEAR | INIT]
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.
section1 HCSEG AT 00H ;first absolute hcode ;section
The paragraph 3.3
Sections in Chapter 3 Assembly Language.
name HDATA expr
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.
TSTART HDATA 60H ;define TSTART to be at ;location 60H TEND HDATA 6DH ;define TEND to be at ;location 6DH
[name] HSEG [AT abs_expr] [NOCLEAR | CLEAR | INIT | ROMDATA]
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.
HDAT_SECT SEGMENT HDATA ;reloc. hdata section section1 HSEG AT 70H ;abs. hdata section
The paragraph 3.3
Sections in Chapter 3 Assembly Language.
name IDATA expr
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.
TSTART IDATA 60H ;define TSTART to be at ;location 60H TEND IDATA 6DH ;define TEND to be at ;location 6DH
IF expression
...
[ELSE] (the ELSE directive
is optional)
...
ENDIF
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.
IF XVAL<0 MSG 'Please select larger value for XVAL' ENDIF
INCLUDE string | <string>
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.
INCLUDE 'headers/io.asm' ; Unix example INCLUDE <data.asm> ; Do not look in ; current directory
[name] ISEG [AT abs_expr] [NOCLEAR | CLEAR | INIT]
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.
section1 ISEG AT 80H ;start IDATA section at ;address 80H
The paragraph 3.3
Sections in Chapter 3 Assembly Language.
LOCAL symbol[,symbol]...
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.
LOCAL LOOPA ;LOOPA local to this module
name MACRO [dummy argument
list]
.
macro definition statements
.
.
ENDM
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.
SWAP_MEM MACRO REG1,REG2 ;swap memory contents MOV R\REG1,R\REG2 ENDM
DUP
, DUPA
, DUPC
, DUPF
, ENDM
MSG [{str | exp}[ ,{str | exp}]...]
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.
MSG 'Generating tables'
NAME module_name
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.
name my_prog ; module-name is my_prog
ORG expr
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.
ORG ($ + 1000) ; the current location counter ; is incremented by 1000 ORG 60 ; set location counter to 60
PMACRO symbol[,symbol]...
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.
PMACRO MAC1,MAC2
This statement would cause the macros named MAC1 and MAC2 to be purged.
PUBLIC name [, name ]...
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.
public pub_symb ;pub_symb is known outside module
RADIX expression
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.
_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 section_name
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.
CD_SECT SEGMENT CODE ;relocatable code ;section . . RSEG CD_SEG ;select relocatable ;code section
name SEGMENT type [attr]...
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.
DATSECT SEGMENT DATA ;relocatable data ;section ROMS1 SEGMENT CODE ROMDATA ;relocatable code ;section with ;attribute romdata
The paragraph Sections.
name SET expression
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.
COUNT SET 0 ; Initialize COUNT
SYMB string, expression [, abs_expr] [, abs_expr]
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 symbol
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.
UNDEF DEBUG ;Undefines the DEBUG substitution ;string
USING expression
This directive is ignored. It is only available for compatibily with the TASKING asm51 assembler.
WARN [{str | exp}[,{str | exp}]...]
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.
WARN 'parameter too large'
name XDATA expr
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.
RSEG XSPACE ROOM: DS 4 ;reserve 4 bytes of XDATA MORE_X XDATA ROOM+2 ;define MORE_X to be 2 ;bytes after ROOM
[name] XSEG [AT abs_expr] [NOCLEAR | CLEAR | INIT]
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.
XDAT_SECT SEGMENT XDATA ;reloc. xdata section section1 XSEG AT 70H ;abs. xdata section
The paragraph 3.3
Sections in Chapter 3 Assembly Language.
name XSHORT expr
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.
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
[name] XSSEG [AT abs_expr] [NOCLEAR | CLEAR | INIT]
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.
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.