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 string The .module directive causes the string to be included in the assemblers output file as an identifier for this particular ob- ject module. The string may be from 1 to 79 characters in length. 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.
.sbttl Directive Format: .sbttl string The .sbttl directive provides a character string to be placed on the third line of each page during listing.
.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.
.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.)
.4byte and .quad Directives Format: .4byte exp ;Stores the binary value .quad exp ;of the expression in ;the next quad (4 bytes). .4byte exp1,exp2,expn ;Stores the binary values .quad exp1,exp2,expn ;of the list of expressions ;in successive quads ;(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 .4byte or .quad directive is used to generate successive quads of binary data in the object module. (This directive is 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, .blk3, and .blk4 Directives Format: .blkw N ;reserve N words 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 .blk4 reserves 4 byte blocks (available in as- semblers supporting 32-bit addressing).
.ascii, .fcc and .str Directives Format: .ascii /string/ .fcc /string/ .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/ .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.
.asciz and .strz Directives Format: .asciz /string/ .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.
.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.
.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 ASxxxx assemblers also automatically generate two symbols for each program area: 's_' This is the starting address of the pro- gram area. 'l_' This is the length of the program area. The .area names and options are never case sensitive.
.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 for the first area within the bank. 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.
.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 process 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 the .globl directive.
.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 The .if/.else/.endif directives may be nested upto 10 levels. The .page directive is processed 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 This text will be bypassed during assembly but appear in the listing file. . . . .endif
.ifdef, .else, and .endif Directives 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' is defined (i.e. true) and the range of false condition will be processed if the symbol 'sym' is not defined (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 .ifdef/.else/.endif constructions: .ifdef sym$1 ;lookup symbol sym$1 .byte 1,2 ;insert bytes if sym$1 is .endif ;defined .ifdef sym$2 ;lookup symbol sym$2 .else .byte 3,4 ;insert bytes if sym$1 .endif ;is not defined .ifdef sym$3 ;lookup symbol sym$3 .byte 12 ;insert this byte if sym$3 .else ;is defined .byte 13 ;insert this byte if sym$3 .endif ;is not defined The .ifdef/.else/.endif directives may be nested upto 10 levels.
.ifndef, .else, and .endif Directives 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 (i.e. true) and the range of false condi- tion will be processed if the symbol 'sym' is defined (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 .ifndef/.else/.endif constructions: .ifndef sym$1 ;lookup symbol sym$1 .byte 1,2 ;insert bytes if sym$1 is .endif ;not defined .ifndef sym$2 ;lookup symbol sym$2 .else .byte 3,4 ;insert bytes if sym$1 .endif ;is defined .ifndef sym$3 ;lookup symbol sym$3 .byte 12 ;insert this byte if sym$3 .else ;is not defined .byte 13 ;insert this byte if sym$3 .endif ;is defined The .ifndef/.else/.endif directives may be nested upto 10 lev- els.
.include Directive Format: .include string where: string represents a delimited string that is the file specification of an ASxxxx source file. 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.
.define and .undefine Directives Format: .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 delimited string that is substi- tuted for the keyword. The string may contain any sequence of characters including white space. 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.
.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: -b 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 preceeding 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 dumby direct page linked at address 0. This dumby 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. (Currently only the as8xCxxx and aspic assemblers can use the .16bit, .24bit, and .32bit directives in special mode.)
.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.