... General Assembler Directives
An ASxxxx directive is placed in the operator field of the source line. Only one directive is allowed per source line. Each directive may have a blank operand field or one or more operands. Legal operands differ with each directive.
.module Directive
Format:
.module name
The .module directive causes the name to be included in the
assemblers output file as an identifier for this particular ob-
ject module. The name may be from 1 to 79 characters in length.
The name may not have any embedded white space (spaces or tabs).
Only one identifier is allowed per assembled module. The main
use of this directive is to allow the linker to report a
modules' use of undefined symbols. At link time all undefined
symbols are reported and the modules referencing them are
listed.
.title Directive
Format:
.title string
The .title directive provides a character string to be placed
on the second line of each page during listing. The string be-
gins with the first non white space character (after any space
or tab) and ends with the end of the line.
.sbttl Directive
Format:
.sbttl string
The .sbttl directive provides a character string to be placed
on the third line of each page during listing. The string be-
gins with the first non white space character (after any space
or tab) and ends with the end of the line.
.list and .nlist Directives
Format:
.list ;Basic .list
.list expr ;with expression
.list (arg1,arg2,...,argn) ;with sublist options
.nlist ;Basic .nlist
.nlist expr ;with expression
.nlist (arg1,arg2,...,argn) ;with sublist options
The .list and .nlist directives control the listing output to
the .lst file. The directives have the following sublist
options:
err - errors
loc - program location
bin - binary output
eqt - symbol or .if evaluation
cyc - opcode cycle count
lin - source line number
src - source line text
pag - pagination
lst - .list/.nlist line listing
md - macro definition listing
me - macro expansion listing
meb - macro expansion binary only listing
mel - macro expansion binary with source
! - sets the listing mode to
!(.list) or !(.nlist) before
applying the sublist options
The 'normal' listing mode .list is the combination of err, loc,
bin, eqt, cyc, lin, src, pag, lst, and md enabled with me, meb,
and mel disabled. The 'normal' listing mode .nlist has all sub-
list items disabled. When specifying sublist options the option
list must be enclosed within parenthesis and multiple options
separated by commas.
The NOT option, !, is used to set the listing mode to the op-
posite of the .list or .nlist directive before applying the sub-
list options. For example:
.nlist (!) is equivalent to .list and
.list (!) is equivalent to .nlist
any additional options will
be applied normally
Normal .list/.nlist processing is disabled within false con-
ditional blocks. However, the .list/.nlist with an expression
can override this behavior if the expression has a non zero
value.
Examples of listing options:
.list (me) ; listing options are enabled
; during macro processing
.list (meb) ; macro processing lists only
; generated binary and location
.list (mel) ; macro processing lists only
; source lines generating
; binary output
.nlist (src) ; .nlist src lines not listed
.nlist (!,lst) ; list all except .nlist
.nlist ; combination lists only
.list (src) ; the source line
.list (!,src) ; list only the source line
.list 1 ; enable listing even within
; a FALSE conditional block
.page Directive
Format:
.page
The .page directive causes a page ejection with a new heading
to be printed. The new page occurs after the next line of the
source program is processed, this allows an immediately follow-
ing .sbttl directive to appear on the new page. The .page
source line will not appear in the file listing. Paging may be
disabled by invoking the -p directive or by using the directive:
.nlist (pag)
If the .page directive is followed by a non zero constant or
an expression that evaluates to a non zero value then pagination
will be enabled within a false condition range to allow extended
textual information to be incorporated in the source program
with out the need to use the comment delimiter (;):
.if 0
.page 1 ;Enable pagination within 'if' block.
This text will be bypassed during assembly
but appear in the listing file.
.
.
.
.endif
.msg Directive
Format:
.msg /string/ or
.msg ^/string/
where: string represents a text string. The string is printed
to the console during the final assembly pass.
/ / represent the delimiting characters. These
delimiters may be any paired printing
characters, as long as the characters are not
contained within the string itself. If the
delimiting characters do not match, the .msg
directive will give the <q> error.
The .msg directive is useful to report assembly status or
other information during the assembly process.
.error Directive
Format:
.error exp
where: exp represents an absolute expression. If the
evaluation of the expression results in a non
zero value then an <e> error is reported and the
text line is listed in the generated error.
The .error directive is useful to report configuration or
value errors during the assembly process. (The .error directive
is identical in function to the .assume directive, just perhaps
more descriptive.)
.byte, .db, and .fcb Directives
Format:
.byte exp ;Stores the binary value
.db exp ;of the expression in the
.fcb exp ;next byte.
.byte exp1,exp2,expn ;Stores the binary values
.db exp1,exp2,expn ;of the list of expressions
.fcb exp1,exp2,expn ;in successive bytes.
where: exp, represent expressions that will be
exp1, truncated to 8-bits of data.
. Each expression will be calculated,
. the high-order byte will be truncated.
. Multiple expressions must be
expn separated by commas.
The .byte, .db, or .fcb directives are used to generate suc-
cessive bytes of binary data in the object module.
.word, .dw, and .fdb Directives
Format:
.word exp ;Stores the binary value
.dw exp ;of the expression in
.fdb exp ;the next word.
.word exp1,exp2,expn ;Stores the binary values
.dw exp1,exp2,expn ;of the list of expressions
.fdb exp1,exp2,expn ;in successive words.
where: exp, represent expressions that will occupy two
exp1, bytes of data. Each expression will be
. calculated as a 16-bit word expression.
. Multiple expressions must be
expn separated by commas.
The .word, .dw, or .fdb directives are used to generate suc-
cessive words of binary data in the object module.
.3byte and .triple Directive
Format:
.3byte exp ;Stores the binary value
.triple exp ;of the expression in
;the next triple (3 bytes).
.3byte exp1,exp2,expn ;Stores the binary values
.triple exp1,exp2,expn ;of the list of expressions
;in successive triples
;(3 bytes).
where: exp, represent expressions that will occupy three
exp1, bytes of data. Each expression will be
. calculated as a 24-bit word expression.
. Multiple expressions must be
expn separated by commas.
The .3byte or .triple directive is used to generate succes-
sive triples of binary data in the object module. (These direc-
tives are only available in assemblers supporting 24-bit
addressing.)
.dl, .long, .4byte, and .quad Directives
Format:
.dl exp ;Stores the binary value
.long exp ;of the expression in
.4byte exp ;the next quad (4 bytes).
.quad exp
.dl exp1,exp2,expn ;Stores the binary values
.long exp1,exp2,expn ;of the list of expressions
.4byte exp1,exp2,expn ;in successive quads
.quad exp1,exp2,expn ;(4 bytes).
where: exp, represent expressions that will occupy three
exp1, bytes of data. Each expression will be
. calculated as a 32-bit word expression.
. Multiple expressions must be
expn separated by commas.
The .dl, .long, .4byte or .quad directive is used to generate
successive quads of binary data in the object module. (These
directives are only available in assemblers supporting 32-bit
addressing.)
.blkb, .ds, .rmb, and .rs Directives
Format:
.blkb N ;reserve N bytes of space
.ds N ;reserve N bytes of space
.rmb N ;reserve N bytes of space
.rs N ;reserve N bytes of space
The .blkb, .ds, .rmb, and .rs directives reserve byte blocks
in the object module;
.blkw, .blkl, .blk3, and .blk4 Directives
Format:
.blkw N ;reserve N words of space
.blkl N ;reserve N quads of space
.blk3 N ;reserve N triples of space
.blk4 N ;reserve N quads of space
The .blkw directive reserves word blocks; the .blk3 reserves
3 byte blocks(available in assemblers supporting 24-bit
addressing); the .blkl and .blk4 reserves 4 byte blocks (avail-
able in assemblers supporting 32-bit addressing).
.ascii, .fcc and .str Directives
Format:
.ascii /string/ or
.ascii ^/string/
.fcc /string/ or
.fcc ^/string/
.str /string/ or
.str ^/string/
where: string is a string of printable ascii characters.
/ / represent the delimiting characters. These
delimiters may be any paired printing
characters, as long as the characters are not
contained within the string itself. If the
delimiting characters do not match, the .ascii
directive will give the <q> error.
The .ascii, .fcc, and .str directives place one binary byte of
data for each character in the string into the object module.
.ascis and .strs Directives
Format:
.ascis /string/ or
.ascis ^/string/
.strs /string/ or
.strs ^/string/
where: string is a string of printable ascii characters.
/ / represent the delimiting characters. These
delimiters may be any paired printing
characters, as long as the characters are not
contained within the string itself. If the
delimiting characters do not match, the .ascis
and .strs directives will give the <q> error.
The .ascis and .strs directives place one binary byte of data
for each character in the string into the object module. The
last character in the string will have the high order bit set.
.asciz and .strz Directives
Format:
.asciz /string/ or
.asciz ^/string/
.strz /string/ or
.strz ^/string/
where: string is a string of printable ascii characters.
/ / represent the delimiting characters. These
delimiters may be any paired printing
characters, as long as the characters are not
contained within the string itself. If the
delimiting characters do not match, the .asciz
and .strz directive will give the <q> error.
The .asciz and .strz directives place one binary byte of data
for each character in the string into the object module. Fol-
lowing all the character data a zero byte is inserted to ter-
minate the character string.
Non-Printing Characters In Strings Non-printing characters can be inserted into any string by enclosing the non-printing characters' value in parenthesis as shown in the following example. .asciz /Hello World!/(13)(10) A carriage return and line feed character have been appended to the string "Hello World!". The non-printing character values are always evaluated in the current radix (or in a temporary radix when specified.) The character values may be evaluated from any legal expression and are truncated to 8-bit values be- fore being inserted into the character string. It should be noted that multiple string segments and non-printing character segments can be included in a single string statemment: .asciz /I Said:/(13)(10)/Hello World!/(13)(10)
.assume Directive
Format:
.assume exp
where: exp represents an absolute expression. If the
evaluation of the expression results in a non
zero value then an <e> error is reported and the
text line is listed in the generated error.
The .assume directive is useful to check assumptions about
assembler values. (The .assume directive is identical in func-
tion to the .error directive, just perhaps more descriptive.)
.radix Directive
Format:
.radix character
where: character represents a single character specifying the
default radix to be used for succeeding numbers. The
character may be any one of the following:
B,b Binary
O,o Octal
Q,q
D,d Decimal
'blank'
H,h Hexidecimal
X,x
.even Directive
Format:
.even
The .even directive ensures that the current location counter
contains an even boundary value by adding 1 if the current loca-
tion is odd.
.odd Directive
Format:
.odd
The .odd directive ensures that the current location counter
contains an odd boundary value by adding one if the current lo-
cation is even.
.bndry Directive
Format:
.bndry n
If the current location is not an integer multiple of n then
the location counter is increased to the next integer multiple
of n.
As an example:
.bndry 4
changes the current location to be at a multiple of 4, a 4-byte
boundary.
The boundary specifications are propagated to the linker as a
boundary modulus, ie the smallest common boundary for all .odd,
.even, and .bndry directives contained within the area. A boun-
dary value of 1 is equivalent to .odd and a boundary value of 2
is equivalent to .even. Because areas are always assembled with
an initial address of 0, an even address, both .odd and .even
are modulus 2 boundaries.
As an example, suppose there are two sections: a CODE sec-
tion and a DATA section. The program code is written so that
the data associated with this section of the program code fol-
lows immediately.
.area CODE
; Subroutine 1 Code
; Uses data having a boundary of 6
.area DATA
; Subroutine 1 Data
.bndry 6
.word 1, 2, 3
...
.area CODE
; Subroutine 2 Code
; Uses data having a boundary of 8
.area DATA
; Subroutine 2 Data
.bndry 8
.word 1, 2, 3, 4,
Since the CODE and DATA sections are assembled during a sin-
gle assembly (also applies to include files) the the assembler
compiles all CODE segments as a single area segment. The assem-
bler also compiles all the DATA segments as a single area seg-
ment which has two .bndry directives and will have a boundary
modulus of 24. 24 is the smallest boundary divisible by 6 and 8
with no remainder. When the assembled file is linked the loca-
tion of the data in the DATA area will be offset to an address
which has a boundary modulus of 24.
When multiple files containing the same area names (projects
with multiple independently compiled files or library files) are
linked together each area segment will be offset to match the
segments boundary modulus.
Boundary specifications will also be preserved when an area
base address is specified with the -a linker option and/or the
area is placed within a bank.
.area Directive
Format:
.area name [(options)]
where: name represents the symbolic name of the program sec-
tion. This name may be the same as any
user-defined symbol or bank as the area names
are independent of all symbols, labels, and
banks.
options specify the type of program or data area:
ABS absolute (automatically invokes OVR)
REL relocatable
OVR overlay
CON concatenate
NOPAG non-paged area
PAG paged area
options specify a code or data segment:
CSEG Code segment
DSEG Data segment
option specifies the data area bank:
BANK Named collection of areas
The .area directive provides a means of defining and separat-
ing multiple programming and data sections. The name is the
area label used by the assembler and the linker to collect code
from various separately assembled modules into one section. The
name may be from 1 to 79 characters in length.
The options are specified within parenthesis and separated by
commas as shown in the following example:
.area TEST (REL,CON) ;This section is relocatable
;and concatenated with other
;sections of this program area.
.area DATA (REL,OVR) ;This section is relocatable
;and overlays other sections
;of this program area.
.area SYS (ABS,OVR) ;(CON not allowed with ABS)
;This section is defined as
;absolute. Absolute sections
;are always overlayed with
;other sections of this program
;area.
.area PAGE (PAG) ;This is a paged section. The
;section must be on a 256 byte
;boundary and its length is
;checked by the linker to be
;no larger than 256 bytes.
;This is useful for direct page
;areas.
The default area type is REL|CON; i.e. a relocatable sec-
tion which is concatenated with other sections of code with the
same area name. The ABS option indicates an absolute area. The
OVR and CON options indicate if program sections of the same
name will overlay each other (start at the same location) or be
concatenated with each other (appended to each other).
The area can be specified as either a code segment, CSEG, or
a data segment, DSEG. The CSEG and DSEG descriptors are useful
when the microprocessor code and data unit allocations are
unequal: e.g. the executable code uses an allocation of 2
bytes for each instruction and is addressed at an increment of 1
for every instruction, and the data uses an allocation of 1 byte
for each element and is addressed at an increment of 1 for each
data byte. The allocation units are defined by the architecture
of the particular microprocessor.
The .area directive also provides a means of specifying the
bank this area is associated with. All areas associated with a
particular bank are combined at link time into a block of
code/data.
The CSEG, DSEG, and BANK options are specified within the
parenthesis as shown in the following examples:
.area C_SEG (CSEG,BANK=C1)
;This is a code section
;and is included in bank C1
.area D_SEG (DSEG,BANK=D1)
;This is a data section
;and is included in bank D1.
Multiple invocations of the .area directive with the same
name must specify the same options or leave the options field
blank, this defaults to the previously specified options for
this program area.
The ASxxxx assemblers automatically provide two program
sections:
'_CODE' This is the default code/data area.
This program area is of type
(REL,CON,CSEG).
'_DATA' This is the default optional data area.
This program area is of type
(REL,CON,DSEG).
The .area names and options are never case sensitive.
.psharea and .poparea Directives
Format:
.psharea
.poparea
The .psharea directive pushes the current area context onto a
16 element stack. Attempting a .psharea operation with a full
stack results in a stack overflow error message.
The .poparea directive pops an area context from the 16 ele-
ment stack. Attemptimg a .poparea operation form an empty stack
results in a stack underflow error message.
These directives can be useful when calling macros which
place code and/or data into other areas. As an example this
macro saves the current area context, places descriptors into a
specific area, and then restores the area context.
.macro .descriptor name, device, block, flags
.psharea
.area Descriptors
name: .rad50 device
.word block
.word flags
.poparea
.endm
Code or data added to an area whose context is in the psh/pop
stack is not affected by the restoration of the area's context.
The code or data pointer is not part of the stacked area's con-
text.
.bank Directive
Format:
.bank name [(options)]
where: name represents the symbolic name of the bank sec-
tion. This name may be the same as any
user-defined symbol or area as the bank names
are independent of all symbols, labels, and
areas. The name may be from 1 to 79 characters
in length.
options specify the parameters of the bank:
BASE base address of bank
SIZE maximum size of bank
FSFX file suffix for this bank
MAP NOICE mapping
The .bank directive allows an arbitrary grouping of program
and/or data areas to be communicated to the linker. The bank
parameters are all optional and are described as follows:
1. BASE, the starting address of the bank (default is 0)
may be defined. This address can be overridden by us-
ing the linker -b option. The bank address is always
specified in 'byte' addressing. A first area which is
not 'byte' addressed (e.g. a processor addressed by a
'word' of 2 or more bytes) has the area address scaled
to begin at the 'byte' address.
2. SIZE, the maximum length of the bank specified in
bytes. The size is always specified in terms of bytes.
3. FSFX, the file suffix to be used by the linker for this
bank. The suffix may not contain embedded white space.
4. MAP, NOICE mapping parameter for this bank of
code/data.
The options are specified within parenthesis and separated by
commas as shown in the following example:
.BANK C1 (BASE=0x0100,SIZE=0x1000,FSFX=_C1)
;This bank starts at 0x0100,
;has a maximum size of 0x1000,
;and is to be placed into
;a file with a suffix of _C1
The parameters must be absolute (external symbols are not al-
lowed.)
.org Directive
Format:
.org exp
where: exp is an absolute expression that becomes the cur-
rent location counter.
The .org directive is valid only in an absolute program section
and will give a <q> error if used in a relocatable program area.
The .org directive specifies that the current location counter
is to become the specified absolute value.
.globl Directive
Format:
.globl sym1,sym2,...,symn
where: sym1, represent legal symbolic names. When
sym2,... When multiple symbols are specified,
symn they are separated by commas.
A .globl directive may also have a label field and/or a com-
ment field.
The .globl directive is provided to define (and thus provide
linkage to) symbols not otherwise defined as global symbols
within a module. In defining global symbols the directive
.globl J is similar to:
J == expression or J::
Because object modules are linked by global symbols, these
symbols are vital to a program. All internal symbols appearing
within a given program must be defined at the end of pass 1 or
they will be considered undefined. The assembly directive (-g)
can be be invoked to make all undefined symbols global at the
end of pass 1.
The .globl directive and == construct can be overridden by a
following .local directive.
NOTE
The ASxxxx assemblers use the last occurring symbol
specification in the source file(s) as the type shown
in the symbol table and output to the .rel file.
.local Directive
Format:
.local sym1,sym2,...,symn
where: sym1, represent legal symbolic names.
sym2,... When multiple symbols are specified,
symn they are separated by commas.
A .local directive may also have a label field and/or a com-
ment field.
The .local directive is provided to define symbols that are
local to the current assembly process. Local symbols are not
effected by the assembler option -a (make all symbols global).
In defining local symbols the directive .local J is similar to:
J =: expression
The .local directive and the =: construct are useful in de-
fining symbols and constants within a header or definition file
that contains many symbols specific to the current assembly pro-
cess that should not be exported into the .rel output file. A
typical usage is in the definition of SFRs (Special Function
Registers) for a microprocessor.
The .local directive and =: construct can be overridden by a
following .globl directive.
NOTE
The ASxxxx assemblers use the last occurring symbol
specification in the source file(s) as the type shown
in the symbol table and output to the .rel file.
.equ, .gblequ, and .lclequ Directives
Format:
sym1 .equ expr ; equivalent to sym1 = expr
sym2 .gblequ expr ; equivalent to sym2 == expr
sym3 .lclequ expr ; equivalent to sym3 =: expr
These alternate forms of equivalence are provided for user
convenience.
.if, .else, and .endif Directives
Format:
.if expr
. ;}
. ;} range of true condition
. ;}
.else
. ;}
. ;} range of false condition
. ;}
.endif
The conditional assembly directives allow you to include or
exclude blocks of source code during the assembly process, based
on the evaluation of the condition test.
The range of true condition will be processed if the expres-
sion 'expr' is not zero (i.e. true) and the range of false con-
dition will be processed if the expression 'expr' is zero (i.e
false). The range of true condition is optional as is the .else
directive and the range of false condition. The following are
all valid .if/.else/.endif constructions:
.if A-4 ;evaluate A-4
.byte 1,2 ;insert bytes if A-4 is
.endif ;not zero
.if K+3 ;evaluate K+3
.else
.byte 3,4 ;insert bytes if K+3
.endif ;is zero
.if J&3 ;evaluate J masked by 3
.byte 12 ;insert this byte if J&3
.else ;is not zero
.byte 13 ;insert this byte if J&3
.endif ;is zero
All .if/.else/.endif directives are limited to a maximum nesting
of 10 levels.
The use of a .else directive outside a .if/.endif block will
generate an <i> error. Assemblies having unequal .if and .endif
counts will cause an <i> error.
.iff, .ift, and .iftf Directives
Format:
.if expr ;'if' range Condition is
;TRUE when expr is not zero
.ift ;}
. ;} range of true condition ;}
.iff ;} if
. ;} range of false condition ;} block
.iftf ;}
. ;} unconditional range ;}
.else ;'else' range Condition is
;TRUE when expr is zero
.ift ;}
. ;} range of true condition ;}
.iff ;} else
. ;} range of false condition ;} block
.iftf ;}
. ;} unconditional range ;}
.endif
The subconditional assembly directives may be placed within
conditional assembly blocks to indicate:
1. The assembly of an alternate body of code when
the condition of the block tests false.
2. The assembly of non-contiguous body of code
within the conditional assembly block,
depending upon the result of the conditional
test in entering the block.
3. The unconditional assembly of a body of code
within a conditional assembly block.
The use of the .iff, .ift, and .iftf directives makes the use of
the .else directive redundant.
Note that the implementation of the .else directive causes
the .if tested condition to be complemented. The TRUE and FALSE
conditions are determined by the .if/.else conditional state.
All .if/.else/.endif directives are limited to a maximum
nesting of 10 levels.
The use of the .iff, .ift, or .iftf directives outside of a
conditional block results in a <i> error code.
The use of a .else directive outside a .if/.endif block will
generate an <i> error. Assemblies having unequal .if and .endif
counts will cause an <i> error.
.ifxx Directives
Additional conditional directives are available to test the
value of an evaluated expression:
.ifne expr ; true if expr != 0
.ifeq expr ; true if expr == 0
.ifgt expr ; true if expr > 0
.iflt expr ; true if expr < 0
.ifge expr ; true if expr >= 0
.ifle expr ; true if expr <= 0
Format:
.ifxx expr
. ;}
. ;} range of true condition
. ;}
.else
. ;}
. ;} range of false condition
. ;}
.endif
The conditional assembly directives allow you to include or
exclude blocks of source code during the assembly process, based
on the evaluation of the test condition.
The range of true condition will be processed if the expres-
sion 'expr' is not zero (i.e. true) and the range of false con-
dition will be processed if the expression 'expr' is zero (i.e
false). The range of true condition is optional as is the .else
directive and the range of false condition. The following are
all valid .if/.else/.endif constructions:
.ifne A-4 ;evaluate A-4
.byte 1,2 ;insert bytes if A-4 is
.endif ;not zero
.ifeq K+3 ;evaluate K+3
.byte 3,4 ;insert bytes if K+3
.endif ;is zero
.ifne J&3 ;evaluate J masked by 3
.byte 12 ;insert this byte if J&3
.else ;is not zero
.byte 13 ;insert this byte if J&3
.endif ;is zero
All .if/.else/.endif directives are limited to a maximum nesting
of 10 levels.
The use of a .else directive outside a .if/.endif block will
generate an <i> error. Assemblies having unequal .if and .endif
counts will cause an <i> error.
.ifdef Directive
Format:
.ifdef sym
. ;}
. ;} range of true condition
. ;}
.else
. ;}
. ;} range of false condition
. ;}
.endif
The conditional assembly directives allow you to include or
exclude blocks of source code during the assembly process, based
on the evaluation of the condition test.
The range of true condition will be processed if the symbol
'sym' has been defined with a .define directive or 'sym' is a
variable with an assigned value else the false range will be
processed. The range of true condition is optional as is the
.else directive and the range of false condition. The following
are all valid .ifdef/.else/.endif constructions:
.ifdef sym$1 ;lookup symbol sym$1
.byte 1,2 ;insert bytes if sym$1
.endif ;is defined or
;assigned a value
.ifdef sym$2 ;lookup symbol sym$2
.else
.byte 3,4 ;insert bytes if sym$1
.endif ;is not defined and
;not assigned a value
.ifdef sym$3 ;lookup symbol sym$3
.byte 12 ;insert this byte if sym$3
.else ;is defined/valued
.byte 13 ;insert this byte if sym$3
.endif ;is not defined/valued
Note that the default assembler configuration of case sensitive
means the testing for a defined symbol is also case sensitive.
All .if/.else/.endif directives are limited to a maximum
nesting of 10 levels.
The use of a .else directive outside a .if/.endif block will
generate an <i> error. Assemblies having unequal .if and .endif
counts will cause an <i> error.
.ifndef Directive
Format:
.ifndef sym
. ;}
. ;} range of true condition
. ;}
.else
. ;}
. ;} range of false condition
. ;}
.endif
The conditional assembly directives allow you to include or
exclude blocks of source code during the assembly process, based
on the evaluation of the condition test.
The range of true condition will be processed if the symbol
'sym' is not defined by a .define directive and a variable 'sym'
has not been assigned a value else the range of false condition
will be processed. The range of true condition is optional as
is the .else directive and the range of false condition. The
following are all valid .ifndef/.else/.endif constructions:
.ifndef sym$1 ;lookup symbol sym$1
.byte 1,2 ;insert bytes if sym$1 is
.endif ;not defined and
;not assigned a value
.ifndef sym$2 ;lookup symbol sym$2
.else
.byte 3,4 ;insert bytes if sym$1
.endif ;is defined or
;is assigned a value
.ifndef sym$3 ;lookup symbol sym$3
.byte 12 ;insert this byte if sym$3
.else ;is not defined/valued
.byte 13 ;insert this byte if sym$3
.endif ;is defined/valued
All .if/.else/.endif directives are limited to a maximum nesting
of 10 levels.
The use of a .else directive outside a .if/.endif block will
generate an <i> error. Assemblies having unequal .if and .endif
counts will cause an <i> error.
.ifb Directive
Format:
.ifb sym
. ;}
. ;} range of true condition
. ;}
.else
. ;}
. ;} range of false condition
. ;}
.endif
The conditional assembly directives allow you to include or
exclude blocks of source code during the assembly process, based
on the evaluation of the test condition.
The conditional .ifb is most useful when used in macro de-
finitions to determine if the argument is blank. The range of
true condition will be processed if the symbol 'sym' is blank.
The range of true condition is optional as is the .else direc-
tive and the range of false condition. The following are all
valid .ifb/.else/.endif constructions:
.ifb sym$1 ;argument is not blank
.byte 1,2 ;insert bytes if argument
.endif ;is blank
.ifb sym$2 ;argument is not blank
.else
.byte 3,4 ;insert bytes if argument
.endif ;is not blank
.ifb ;argument is blank
.byte 12 ;insert this byte if
.else ;argument is blank
.byte 13 ;insert this byte if
.endif ;argument not blank
All .if/.else/.endif directives are limited to a maximum nesting
of 10 levels.
The use of a .else directive outside a .if/.endif block will
generate an <i> error. Assemblies having unequal .if and .endif
counts will cause an <i> error.
.ifnb Directive
Format:
.ifnb sym
. ;}
. ;} range of true condition
. ;}
.else
. ;}
. ;} range of false condition
. ;}
.endif
The conditional assembly directives allow you to include or
exclude blocks of source code during the assembly process, based
on the evaluation of the test condition.
The conditional .ifnb is most useful when used in macro de-
finitions to determine if the argument is not blank. The range
of true condition will be processed if the symbol 'sym' is not
blank. The range of true condition is optional as is the .else
directive and the range of false condition. The following are
all valid .ifnb/.else/.endif constructions:
.ifnb sym$1 ;argument is not blank
.byte 1,2 ;insert bytes if argument
.endif ;is not blank
.ifnb sym$2 ;argument is not blank
.else
.byte 3,4 ;insert bytes if argument
.endif ;is blank
.ifnb ;argument is blank
.byte 12 ;insert this byte if
.else ;argument is not blank
.byte 13 ;insert this byte if
.endif ;argument is blank
All .if/.else/.endif directives are limited to a maximum nesting
of 10 levels.
The use of a .else directive outside a .if/.endif block will
generate an <i> error. Assemblies having unequal .if and .endif
counts will cause an <i> error.
.ifidn Directive
Format:
.ifidn sym$1,sym$2
. ;}
. ;} range of true condition
. ;}
.else
. ;}
. ;} range of false condition
. ;}
.endif
The conditional assembly directives allow you to include or
exclude blocks of source code during the assembly process, based
on the evaluation of the test condition.
The conditional .ifidn is most useful when used in macro de-
finitions to determine if the arguments are identical. The
range of true condition will be processed if the symbol 'sym$1'
is idendical to 'sym$2' (i.e. the character strings for sym$1
and sym$2 are the same consistent with the case sensitivity
flag). When this if statement occurs inside a macro where an
argument substitution may be blank then an argument should be
delimited with the form /symbol/ for each symbol. The range of
true condition is optional as is the .else directive and the
range of false condition. The following are all valid
.ifidn/.else/.endif constructions:
.ifidn sym$1,sym$1 ;arguments are the same
.byte 1,2 ;insert bytes if arguments
.endif ;are the sane
.ifidn sym$1,sym$2 ;arguments are not the same
.else
.byte 3,4 ;insert bytes if arguments
.endif ;are not the same
.ifidn sym$3,sym$3 ;arguments are the same
.byte 12 ;insert this byte if
.else ;arguments are the same
.byte 13 ;insert this byte if
.endif ;arguments are not the same
All .if/.else/.endif directives are limited to a maximum nesting
of 10 levels.
The use of a .else directive outside a .if/.endif block will
generate an <i> error. Assemblies having unequal .if and .endif
counts will cause an <i> error.
.ifdif Directive
Format:
.ifdif sym$1,sym$2
. ;}
. ;} range of true condition
. ;}
.else
. ;}
. ;} range of false condition
. ;}
.endif
The conditional assembly directives allow you to include or
exclude blocks of source code during the assembly process, based
on the evaluation of the test condition.
The conditional .ifdif is most useful when used in macro de-
finitions to determine if the arguments are different. The
range of true condition will be processed if the symbol 'sym$1'
is different from 'sym$2' (i.e. the character strings for sym$1
and sym$2 are the not the same consistent with the case sensi-
tivity flag). When this if statement occurs inside a macro
where an argument substitution may be blank then an argument
should be delimited with the form /symbol/ for each symbol. The
range of true condition is optional as is the .else directive
and the range of false condition. The following are all valid
.ifdif/.else/.endif constructions:
.ifdif sym$1,sym$2 ;arguments are different
.byte 1,2 ;insert bytes if arguments
.endif ;are different
.ifdif sym$1,sym$1 ;arguments are identical
.else
.byte 3,4 ;insert bytes if arguments
.endif ;are different
.ifdif sym$1,sym$3 ;arguments are different
.byte 12 ;insert this byte if
.else ;arguments are different
.byte 13 ;insert this byte if
.endif ;arguments are identical
All .if/.else/.endif directives are limited to a maximum nesting
of 10 levels.
The use of a .else directive outside a .if/.endif block will
generate an <i> error. Assemblies having unequal .if and .endif
counts will cause an <i> error.
Alternate .if Directive Forms
Format:
.if cnd(,) arg1(, arg2)
where the cnd (followed by an optional comma) may be any of
the following:
-------------------------------------------------------
condition Assemble
(complement) Args Block if:
-------------------------------------------------------
eq ( ne ) expr equal to zero
(not equal to zero)
gt ( le ) expr greater than zero
(less than or equal to zero)
lt ( ge ) expr less than zero
(greater than or equal to zero)
def ( ndef ) symbol .define'd or user set
(not .define'd or user set)
b ( nb ) macro argument present
symbol (argument not present)
idn ( dif ) macro arguments identical
symbol (arguments not identical)
f ( t ) ----- only within a .if/.else/.endif
conditional block
tf ----- only within a .if/.else/.endif
conditional block
All .if/.else/.endif directives are limited to a maximum nesting
of 10 levels.
The use of a .else directive outside a .if/.endif block will
generate an <i> error. Assemblies having unequal .if and .endif
counts will cause an <i> error.
Immediate Conditional Assembly Directives
The immediate conditional assembly directives allow a single
line of code to be assembled without using a .if/.else/.endif
construct. All of the previously described conditionals have
immediate equivalents.
Format:
.iif arg(,) line_to_assemble
.iifeq arg(,) line_to_assemble
.iifne arg(,) line_to_assemble
.iifgt arg(,) line_to_assemble
.iifle arg(,) line_to_assemble
.iifge arg(,) line_to_assemble
.iiflt arg(,) line_to_assemble
.iifdef arg(,) line_to_assemble
.iifndef arg(,) line_to_assemble
.iifb (,)arg(,) line_to_assemble
.iifnb (,)arg(,) line_to_assemble
.iifidn (,)arg1,arg2(,) line_to_assemble
.iifdif (,)arg1,arg2(,) line_to_assemble
Valid only within a conditional block.
.iiff line_to_assemble
.iift line_to_assemble
.iiftf line_to_assemble
Alternate Format:
.iif arg(,) line_to_assemble
.iif eq arg(,) line_to_assemble
.iif ne arg(,) line_to_assemble
.iif gt arg(,) line_to_assemble
.iif le arg(,) line_to_assemble
.iif ge arg(,) line_to_assemble
.iif lt arg(,) line_to_assemble
.iif def arg(,) line_to_assemble
.iif ndef arg(,) line_to_assemble
.iif b (,)arg(,) line_to_assemble
.iif nb (,)arg(,) line_to_assemble
.iif idn (,)arg1,arg2(,) line_to_assemble
.iif dif (,)arg1,arg2(,) line_to_assemble
Valid only within a conditional block.
.iif f line_to_assemble
.iif t line_to_assemble
.iif tf line_to_assemble
The (,) indicates an optional comma.
The .iif types b, n, idn, and dif require the commas if the
argument(s) may be blank. These commas may be removed if the
arguments are delimited with the form ^/symbol/ for each symbol.
The immediate conditional directives donot change the
.if/.else/.endif nesting level.
.incbin Directive
Format:
.incbin /string/ [,offset [,count]] or
.incbin ^/string/ [,offset [,count]]
where: string represents a string that is the file specifica-
tion of any file type.
/ / represent the delimiting characters. These
delimiters may be any paired printing
characters, as long as the characters are not
contained within the string itself. If the
delimiting characters do not match, the .incbin
directive will give the <q> error.
The .incbin directive is used to insert the contents of a
file verbatim into the assembler as a byte stream. This can be
handy (for example) when including some arbitrary data directly
into the executable output. However, it is recommended to use
this only for small pieces of data.
The .incbin can be invoked with one or two optional arguments
which specify the number of bytes to skip in the file and the
maximum number of bytes to insert into the output file.
.incbin "file.dat" ; include the whole file
.incbin "file.dat",1024 ; skip the first 1024 bytes
.incbin "file.dat",1024,512 ; skip first 1024, and
; include at most 512 bytes
The ',' delimiters can be any regular delimiter - space, tab, or
','. The offset and count arguments must be local, evaluate to
a constant, and may be 0. A blank offset is by default 0 and a
blank count is the remainder of the file.
An offset equal to or greater than the file length results in
an <i> error. A count that is larger than the remaining bytes
in a file does not result in an error.
.include Directive
Format:
.include /string/ or
.include ^/string/
where: string represents a string that is the file specifica-
tion of an ASxxxx source file.
/ / represent the delimiting characters. These
delimiters may be any paired printing
characters, as long as the characters are not
contained within the string itself. If the
delimiting characters do not match, the .include
directive will give the <q> error.
The .include directive is used to insert a source file within
the source file currently being assembled. When this directive
is encountered, an implicit .page directive is issued. When the
end of the specified source file is reached, an implicit .page
directive is issued and input continues from the previous source
file. The maximum nesting level of source files specified by a
.include directive is five.
The total number of separately specified .include files is
unlimited as each .include file is opened and then closed during
each pass made by the assembler.
The default directory path, if none is specified, for any
.include file is the directory path of the current file. For
example: if the current source file, D:\proj\file1.asm, in-
cludes a file specified as "include1" then the file
D:\proj\include1.asm is opened.
Including Files In Windows/DOS -
Graphical Illustration of Include File Locations
for the following command line entry:
__> bin\ascheck -l -o -s obj\prjct.rel src\prjct\prjct.asm
/-----------------------------------------------------------------------\
| (rooted) |
_____ | _____ |
| | | | | |
---| inc | <---/ ---| bin | |
| |_____| | |_____| |
| | | | |
| \___ inc4.asm | \___ ascheck.exe |
| | |
| | |
_____ | _____ _____ | _____ _____ |
| | | | | | | | | | | | (in prjct.asm directory) |
| C:\ |-----| ..\ |-----| __> |--+--| src |-----|prjct| <-------------------------------\ |
|_____| |_____| | |_____| | |_____| | |_____| | |
| | | | .include "inc1.asm" -/ |
| ^ | | \___ prjct.asm .include "C:\inc\inc4.asm" --/
| | | | \___ inc1.asm .include "..\inc\inc3.asm" -------\
Current | | | | _____ .include "src\inc\inc2.asm" -\ |
Working ------> | >---/ | | | | | |
Directory | | ---| inc | <---------------------------------------/ |
| | |_____| (relative to current working directory) |
| | | |
| | \___ inc2.asm |
| | _____ |
| | | | |
| ---| obj | |
| |_____| |
| | |
| \___ .REL, .SYM, .LST, .HLR |
| |
| _____ |
| | | (relative to current working directory) |
---| inc | <--------------------------------------------------------------------/
|_____|
|
\___ inc3.asm
Including Files In Linux -
Graphical Illustration of Include File Locations
for the following command line entry:
__$ bin/ascheck -l -o -s obj/prjct.rel src/prjct/prjct.asm
/-----------------------------------------------------------------------\
| (rooted) |
_____ | _____ |
| | | | | |
---| inc | <---/ ---| bin | |
| |_____| | |_____| |
| | | | |
| \___ inc4.asm | \___ ascheck |
| | |
| | |
_____ | _____ _____ | _____ _____ |
| | | | | | | | | | | | (in prjct.asm directory) |
| / |-----| ../ |-----| __$ |--+--| src |-----|prjct| <-------------------------------\ |
|_____| |_____| | |_____| | |_____| | |_____| | |
| | | | .include "inc1.asm" -/ |
| ^ | | \___ prjct.asm .include "/inc/inc4.asm" ----/
| | | | \___ inc1.asm .include "../inc/inc3.asm" -------\
Current | | | | _____ .include "src/inc/inc2.asm" -\ |
Working ------> | >---/ | | | | | |
Directory | | ---| inc | <---------------------------------------/ |
| | |_____| (relative to current working directory) |
| | | |
| | \___ inc2.asm |
| | _____ |
| | | | |
| ---| obj | |
| |_____| |
| | |
| \___ .REL, .SYM, .LST, .HLR |
| |
| _____ |
| | | (relative to current working directory) |
---| inc | <--------------------------------------------------------------------/
|_____|
|
\___ inc3.asm
.define and .undefine Directives
Format:
.define keyword /string/ or
.define keyword ^/string/
.undefine keyword
where: keyword is the substitutable string which must start
with a letter and may contain any combination of
digits and letters.
where: string represents a string that is substituted for the
keyword. The string may contain any sequence of
characters including white space.
/ / represent the delimiting characters. These
delimiters may be any paired printing
characters, as long as the characters are not
contained within the string itself. If the
delimiting characters do not match, the .define
directive will give the <q> error.
The .define directive specifies a user defined string which
is substituted for the keyword. The substitution string may it-
self contain other keywords that are substitutable. The assem-
bler resumes the parse of the line at the point the keyword was
found. Care must be excersized to avoid any circular references
within .define directives, otherwise the assembler may enter a
'recursion runaway' resulting in an <s> error.
The .undefine directive removes the keyword as a substitut-
able string. No error is returned if the keyword was not de-
fined.
When a .define directive specifies a keyword, with or without
a substitution string, the keyword is defined but is not a sym-
bol. Because the keyword is not a symbol the keyword becomes
undefined at the beginning of the next assembler pass.
The keyword substitution is never applied to these
directives: .define, .undefine, .ifdef .ifndef, iifdef,
iifndef, or any variation of def or ndef conditionals.
.enabl and .dsabl Directives
Format:
.enabl (optn1, optn2, ...) ;enable options
.dsabl (optn1, optn2, ...) ;disable options
The 'csn' option , C Style Numbers', is currently the only
option available to all ASxxxx assemblers. Enabling the 'csn'
option disables all the temporary radix options beginning with a
0 (zero) except the hex radix options 0x and 0X. All other
numbers beginning with 0 are evaluated as octal values and all
numbers beginning with digits 1-9 are evaluated as decimal
values.
Individual assemblers may have additional options specific to
that assembler and will be described in its documentation.
.setdp Directive
Format:
.setdp [base [,area]]
The set direct page directive has a common format in all the
AS68xx assemblers. The .setdp directive is used to inform the
assembler of the current direct page region and the offset ad-
dress within the selected area. The normal invocation methods
are:
.area DIRECT (PAG)
.setdp
or
.setdp 0,DIRECT
for all the 68xx microprocessors (the 6804 has only the paged
ram area). The commands specify that the direct page is in area
DIRECT and its offset address is 0 (the only valid value for all
but the 6809 microprocessor). Be sure to place the DIRECT area
at address 0 during linking. When the base address and area are
not specified, then zero and the current area are the defaults.
If a .setdp directive is not issued the assembler defaults the
direct page to the area "_CODE" at offset 0.
The assembler verifies that any local variable used in a
direct variable reference is located in this area. Local vari-
able and constant value direct access addresses are checked to
be within the address range from 0 to 255.
External direct references are assumed by the assembler to be
in the correct area and have valid offsets. The linker will
check all direct page relocations to verify that they are within
the correct area.
The 6809 microprocessor allows the selection of the direct
page to be on any 256 byte boundary by loading the appropriate
value into the dp register. Typically one would like to select
the page boundary at link time, one method follows:
.area DIRECT (PAG) ; define the direct page
.setdp
.
.
.
.area PROGRAM
.
ldd #DIRECT ; load the direct page register
tfr a,dp ; for access to the direct page
At link time specify the base and global equates to locate the
direct page:
-a DIRECT = 0x1000
-g DIRECT = 0x1000
Both the area address and offset value must be specified (area
and variable names are independent). The linker will verify
that the relocated direct page accesses are within the direct
page.
The preceding sequence could be repeated for multiple paged
areas, however an alternate method is to define a non-paged area
and use the .setdp directive to specify the offset value:
.area DIRECT ; define non-paged area
.
.
.
.area PROGRAM
.
.setdp 0,DIRECT ; direct page area
ldd #DIRECT ; load the direct page register
tfr a,dp ; for access to the direct page
.
.
.setdp 0x100,DIRECT ; direct page area
ldd #DIRECT+0x100 ; load the direct page register
tfr a,dp ; for access to the direct page
The linker will verify that subsequent direct page references
are in the specified area and offset address range. It is the
programmers responsibility to load the dp register with the cor-
rect page segment corresponding to the .setdp base address
specified.
For those cases where a single piece of code must access a
defined data structure within a direct page and there are many
pages, define a dummy direct page linked at address 0. This
dummy page is used only to define the variable labels. Then
load the dp register with the real base address but donot use a
.setdp directive. This method is equivalent to indexed
addressing, where the dp register is the index register and the
direct addressing is the offset.
.16bit, .24bit, and .32bit Directives
Format:
.16bit ;specify 16-bit addressing
.24bit ;specify 24-bit addressing
.32bit ;specify 32-bit addressing
The .16bit, .24bit, and .32bit directives are special direc-
tives for assembler configuration when default values are not
used.
.msb Directive
Format:
.msb n
The .msb directive is only available in selected assemblers
which support 24- or 32-bit addressing.
The assembler operator '>' selects the upper byte (MSB) when
included in an assembler instruction. The default assembler mode
is to select bits <15:8> as the MSB. The .msb directive allows
the programmer to specify a particular byte as the 'MSB' when
the address space is larger than 16-bits.
The assembler directive .msb n configures the assembler to
select a particular byte as MSB. Given a 32-bit address of MNmn
(M(3) is <31:24>, N(2) is <23:16>, m(1) is <15:8>, and n(0) is
<7:0>) the following examples show how to select a particular
address byte:
.msb 1 ;select byte 1 of address
;<M(3):N(2):m(1):n(0)>
LD A,>MNmn ;byte m <15:8> ==>> A
...
.msb 2 ;select byte 2 of address
;<M(3):N(2):m(1):n(0)>
LD A,>MNmn ;byte N <23:16> ==>> A
...
.msb 3 ;select byte 3 of address
;<M(3):N(2):m(1):n(0)>
LD A,>MNmn ;byte M <31:24> ==>> A
...
.lohi and .hilo Directives
Format:
.lohi ;specify LSB first output
.hilo ;specify MSB first output
The .lohi and .hilo directives are special directives for as-
sembler output configuration. These directives are currently
only enabled in assembler 'ascheck'.
An <m> error will be generated if the .lohi and .hilo direc-
tives are both used within the same assembly source file.
.trace and .ntrace Directives
Format:
.trace ;Basic .trace
.trace (arg1,arg2,...,argn) ;with trace options
.ntrace ;Basic .ntrace
.ntrace (arg1,arg2,...,argn) ;with trace options
The .trace and .ntrace directives are used to trace the process
of inserting assembler text lines, opening and closing of assem-
bler and include files, and the processing of macros. The
directives have the following tracing options:
ins - line insertion
asm - assembler files
inc - include files
mcr - macro invocation
rpt - macro repeat invocation
! - sets the tracing mode to
!(.trace) or !(.ntrace) before
applying the tracing options
The 'normal' tracing mode .trace is the combination of ins, asm,
inc, mcr and rpt enabled. The 'normal' non tracing mode .ntrace
has all tracing items disabled. When specifying tracing options
the option list must be enclosed within parenthesis and multiple
options separated by commas.
The NOT option, !, is used to set the tracing mode to the op-
posite of the .trace or .ntrace directive before applying the
tracing options.
For example:
.ntrace (!) is equivalent to .trace and
.trace (!) is equivalent to .ntrace
any additional options will
be applied normally
When tracing is invoked each trace option inserts a comment
line into the assembler listing denoting when a particular
traced action occurs. The inserted lines contain information
related to the type of traced action:
ins at insertion ;N>>
asm at entry ;A>> file.ext
at exit ;A<< file.ext
The name of the assembler file
inc at entry ;I>> (N) file.ext
at exit ;I<< (N) file.ext
The inclusion depth (N) and
the name of the include file
mcr at entry ;M>> (N) file.ext (L)
at exit ;M<< (N) file.ext (L)
The macro recursion level,
the name of the file defining the macro,
and the line number in file.ext
rpt at invocation ;R>> (N) file.ext (L)
The macro repeat count,
the name of the file defining the macro,
and the line number in file.ext
The initial invocation of a macro or any repeat macro will be
listed as ;M>> and subsequent repeats will be listed as ;R>>.
Thus the first ;R>> will be the second invocation of the repeat
macro.
Examples of tracing options:
.trace (mcr) ; macro processing lists
; the entry and exit from
; a non repeating macro.
.trace (rpt) ; macro processing lists
; the entry, exit, and
; repeat of a macro.
.end Directive
Format:
.end
.end exp
where: exp represents any expression, including constants,
symbols, or labels.
The .end directive is used to specify a code entry point to
be included in the linker output file. Review the I86 and S
record formats described in the linker section for details.
The .end directive without an expression is ignored.
... Exit the ASxxxx Documentation
... Home Page
Last Updated: September 2023