alien.png TASM Docs -- Assembler Directives


[Previous] [Main] [Next]


Most of the assembler directives have a format similar to the machine instruction format. However, instead of specifying operations for the processor to carry out, the directives cause the assembler to perform some function related to the assembly process. TASM has two types of assembler directives - those that mimic the 'C' preprocessor functions, and those that resemble the more traditional assembler directive functions. Each of these will be discussed.
The 'C' preprocessor style directives are invoked with a '#' as the first character of the line followed by the appropriate directive (just as in 'C'). Thus, these directives cannot have a label preceding them (on the same line). Note that in the examples directives are shown in upper case, however, either upper or lower case is acceptable.

ADDINSTR
The ADDINSTR directive can be used to define additional instructions for TASM to use in this assembly. The format is:

  [label] .ADDINSTR inst args opcode nbytes rule class shift binor

The fields are separated by white space just as they would appear in an instruction definition file. See the TASMTABS.TXT file on the TASM distribution disk for more detail.

AVSYM
See SYM/AVSYM.


BLOCK
The BLOCK directive causes the Instruction Pointer to advance the specified number of bytes without assigning values to the skipped over locations. The format is:
  [label] .BLOCK        expr

Some valid examples are:
    word1   .BLOCK     2
    byte1   .block     1
    buffer  .block     80


BSEG/CSEG/DSEG/NSEG/XSEG
These directives can be invoked to indicate the appropriate address space for symbols and labels defined in the subsequent code. The invocation of these directives in no way affects the code generated, only provides more information in the symbol table file if the AVSYM directive is employed. Segment control directives such as these are generally supported by assemblers that generate relocatable object code. TASM does not generate relocatable object code and does not support a link phase, so these directives have no direct effect on the resulting object code. The segments are defined as follows:

Directive
   Segment Description    
BSEG      Bit address    
CSEG      Code address    
DSEG      Data address (internal RAM)    
NSEG      Number or constant (EQU)    
XSEG      External data address (external RAM)    

BYTE
The BYTE directive allows a value assignment to the byte pointed to by the current Instruction Pointer. The format is:

    [label] .BYTE   expr [, expr ...]

Only the lower eight bits of expr are used. Multiple bytes may be assigned by separating them with commas or (for printable strings) enclosed in double quotes. Here are some examples:

    label1   .BYTE     10010110B
             .byte     'a'
             .byte     0
             .byte     100010110b,'a',0
             .byte     "Hello", 10, 13, "World"

CHK
The CHK directive causes a checksum to be computed and deposited at the current location. The starting point of the checksum calculation is indicated as an argument. Here is the format:

    [label]    .CHK    starting_addr

Here is an example:

    start: NOP
           LDA #1
           .CHK start

The checksum is calculated as the simple arithmetic sum of all bytes starting at the starting_addr up to but not including the address of the CHK directive. The least significant byte is all that is used.

CODES/NOCODES
The CODES/NOCODES directives can be used to alternately turn on or off the generation of formatted listing output with line numbers, opcodes, data, etc. With NOCODES in effect, the source lines are sent to the listing file untouched. This is useful around blocks of comments that need a full 80 columns of width for clarity.

DB
This is alternate form of the BYTE directive.

DW
This is alternate form of the WORD directive.

DEFINE
The DEFINE directive is one of the most powerful of the directives and allows string substitution with optional arguments (macros). The format is as follows:
    #DEFINE  macro_label[(arg_list)]  [macro_definition]

Where:
macro_label

character string to be expanded when found in the source file  

arg_list

optional argument list for variable substitution in macro expansion  

macro_def

string to replace the occurrences of macro_label in the source file.  

The simplest form of the DEFINE directive might look like this:
  #DEFINE MLABEL

Notice that no substitutionary string is specified. The purpose of a statement like this would typically be to define a label for the purpose of controlling some subsequent conditional assembly (IFDEF
or IFNDEF).

A more complicated example, performing simple substitution, might look like this:
  #DEFINE VAR1_LO(VAR1 & 255)

This statement would cause all occurrences of the string 'VAR1_LO
' in the source to be substituted with '(VAR1 & 255)'.
As a more complicated example, using the argument expansion capability, consider this:
  #DEFINE  ADD(xx,yy)    clc\ lda xx\ adc yy\ sta xx

If the source file then contained a line like this:
  ADD(VARX,VARY)

It would be expanded to:
  clc\ lda VARX\ adc VARY\ sta VARX

The above example shows the use of the backslash ('\') character as a multiple instruction statement delimiter. This approach allows the definition of fairly powerful, multiple statement macros. The example shown generates 6502 instructions to add one memory location to another.
Some rules associated with the argument list:
Use a maximum of 10 arguments.  
Each argument should be a maximum of 15 characters.  
Note that macros can be defined on the TASM command line, also, with the -d option flag.

DEFCONT
The DEFCONT directive can be used to add to the last macro started with a DEFINE directive. This provides a convenient way to define long macros without running off the edge of the page. The ADD macro shown above could be defined as follows:

  #DEFINE         ADD(xx,yy)     clc
  #DEFCONT                     \ lda xx
  #DEFCONT                     \ adc yy
  #DEFCONT                     \ sta xx

ECHO
The ECHO directive can be used to send output to the console (stderr). It can accept either a quoted text string (with the standard escape sequences allowed) or a valid expression. It can accept only one or the other, however. Multiple instances of the directive may be used to create output that contains both. Consider the following example:

  .ECHO "The size of the table is "
  .ECHO (table_end - table_start)
  .ECHO " bytes long.\n"

This would result in a single line of output something like this:
  The size of the table is 196 bytes long.

EJECT
The EJECT directive can be used to force a top-of-form and the generation of a page header on the list file. It has no effect if the paging mode is off (see PAGE/NOPAGE). The format is:
    [label]    .EJECT

ELSE
The ELSE directive can optionally be used with IFDEF, IFNDEF and IF to delineate an alternate block of code to be assembled if the block immediately following the IFDEF, IFNDEF or IF is not assembled.

Here are some examples of the use of IFDEF, IFNDEF, IF, ELSE, and ENDIF:

  #IFDEF   label1
      lda      byte1
      sta      byte2
  #ENDIF   

  #ifdef   label1
      lda      byte1
  #else    
      lda      byte2
  #endif   

  #ifndef  label1
      lda      byte2
  #else    
      lda      byte1
  #endif   

  #if ($ >= 1000h)
  ; generate an invalid statement to cause an error
  ;  when we go over the 4K boundary.
  !!! PROM bounds exceeded.
  #endif

END
The END directive should follow all code/data generating statements in the source file. It forces the last record to be written to the object file. The format is:
    [label]       .END [addr]

The optional addr will appear in the last object record (Motorola S9 record type) if the object format is Motorola hex. The addr field is ignored for all other object formats.

ENDIF
The ENDIF directive must always follow an IFDEF, IFNDEF, or IF directive and signifies the end of the conditional block.

EQU
The EQU directive can be used to assign values to labels. The labels can then be used in expressions in place of the literal constant. The format is:
    label   .EQU   expr

Here is an example:
    MASK   .EQU  0F0H
    ;
           lda   IN_BYTE
           and   MASK
           sta   OUT_BYTE

An alternate form of the EQU directive is '='. The previous example is equivalent to any of the following:
    MASK    =   0F0H
    MASK    =0F0H
    MASK    = $F0

White space must exist after the label, but none is required after the '='.

EXPORT
The EXPORT directive can be used to define labels (symbols) that are to be written to the export symbol file. The symbols are written as equates (using the .EQU directive) so that the resulting file can be included in a subsequent assembly. This feature can help overcome some of the deficiencies of TASM due to its lack of a relocating linker. The format is:
    [label]  .EXPORT      label [,label...]
The following example illustrates the use of the EXPORT directive and the format of the resulting export file:
Source file:
    EXPORT        read_byte
    EXPORT        write_byte, open_file
Resulting export file:
    read_byte      .EQU   $1243
    write_byte     .EQU   $12AF
    open_file      .EQU   $1301

FILL
The FILL directive can be used to fill a selected number of object bytes with a fixed value. Object memory is filled from the current program counter forward. The format is as follows:
    [label]  .FILL      number_of_bytes [,fill_value]
The number_of_bytes value can be provided as any valid expression. The optional fill_value can also be any valid expression. If fill_value is not provided, a default value of 255 ($FF) is used.

IFDEF
The IFDEF directive can be used to optionally assemble a block of code. It has the following form:
    #IFDEF  macro_label
When invoked, the list of macro labels (established via DEFINE directives) is searched. If the label is found, the following lines of code are assembled. If not found, the input file is skipped until an ENDIF or ELSE directive is found.
Lines that are skipped over still appear in the listing file, but a '~' will appear immediately after the current PC and no object code will be generated (this is applicable to IFDEF, IFNDEF, and IF).

IFNDEF
The IFNDEF directive is the opposite of the IFDEF directive. The block of code following is assembled only if the specified macro_label is undefined. It has the following form:
    #IFNDEF  macro_label
When invoked, the list of macro labels (established via DEFINE directives) is searched. If the label is not found, the following lines of code are assembled. If it is found, the input file is skipped until an ENDIF or ELSE directive is found.

IF
The IF directive can be used to optionally assemble a block of code dependent on the value of a given expression. The format is as follows:
    #IF     expr

If the expression expr evaluates to non-zero, the following block of code is assembled (until an ENDIF or ELSE is encountered).

INCLUDE
The INCLUDE directive reads in and assembles the indicated source file. INCLUDEs can be nested up to six levels. This allows a convenient means to keep common definitions, declarations, or subroutines in files to be included as needed. The format is as follows:

#INCLUDE        filename

The filename must be enclosed in double quotes. Here are some examples:

  #INCLUDE "macros.h"
  #include "equates"
  #include "subs.asm"

LIST/NOLIST
The LIST and NOLIST directives can be used to alternately turn the output to the list file on (LIST) or off (NOLIST). The formats are:

  .LIST
  .NOLIST

LOCALLABELCHAR
The LOCALLABELCHAR directive can be used to override the default "_" as the label prefix indicating a local label. For example, to change the prefix to "?" do this:
  [label]   .LOCALLABELCHAR "?"

Be careful to use only characters that are not operators for expression evaluation. To do so causes ambiguity for the expression evaluator. Some safe characters are "?", "{", and "}".

LSFIRST/MSFIRST
The LSFIRST and MSFIRST directives determine the byte order rule to be employed for the WORD directive. The default (whether correct or not) for all TASM versions is the least significant byte first (LSFIRST). The following illustrates its effect:

  0000  34 12    .word $1234
  0002           .msfirst
  0002  12 34    .word $1234
  0004           .lsfirst
  0004  34 12    .word $1234

MODULE
The MODULE directive defines the scope of local labels. The format is:
  [label]   .MODULE label

Here is an example:
       .MODULE module_x
       lda regx
       jne _skip
       dec
_skip  rts

       .MODULE module_y
       lda regy
       jne _skip
       dec
_skip  rts

In the above example, the local label _skip is reused without harm since the two usages are in separate modules. See also section LOCALLABELCHAR directive.

ORG
The ORG directive provides the means to set the Instruction Pointer (a.k.a. Program Counter) to the desired value. The format is:
  [label] .ORG    expr

The label is optional. The Instruction pointer is assigned the value of the expr. For example, to generate code starting at address 1000H, the following could be done:
  start   .ORG    1000H

The expression (expr) may contain references to the current Instruction Pointer, thus allowing various manipulations to be done. For example, to align the Instruction Pointer on the next 256 byte boundary, the following could be done:
  .ORG  (($ + 0FFH) & 0FF00H)

ORG can also be used to reserve space without assigning values:
  .ORG    $+8

An alternate form of ORG is '*=' or '$='. Thus the following two examples are exactly equivalent to the previous example:
  *=*+8
  $=$+8

PAGE/NOPAGE
The PAGE/NOPAGE directives can be used to alternately turn the paging mode on (PAGE) or off (NOPAGE). If paging is in effect, then every sixty lines of output will be followed by a Top of Form character and a two line header containing page number, filename, and the title. The format is:
    
    .PAGE
    .NOPAGE

The number of lines per page can be set with the '-p' command line option.

SET
The SET directive allows the value of an existing label to be changed. The format is:
    label   .SET    expr
The use of the SET directive should be avoided since changing the value of a label can sometimes cause phase errors between pass 1 and pass 2 of the assembly.

SYM/AVSYM
These directives can be used to cause a symbol table file to be generated. The format is:
  .SYM    ["symbol_filename"]
  .AVSYM  ["symbol_filename"]

For example:
  .SYM       "symbol.map"
  .SYM       
  .AVSYM     "prog.sym"
  .AVSYM

The two directives are similar, but result in a different format of the symbol table file. The format of the SYM file is one line per symbol, each symbol starts in the first column and is followed by white space and then four hexadecimal digits representing the value of the symbol. The following illustrates the format:

  label1         FFFE
  label2         FFFF
  label3         1000

The AVSYM directive is provided to generate symbol tables compatible with the Avocet 8051 simulator. The format is similar, but each line is prefixed by an 'AS' and each symbol value is prefixed by a segment indicator:

    AS     start          C:1000
    AS     read_byte      C:1245
    AS     write_byte     C:1280
    AS     low_nib_mask   N:000F
    AS     buffer         X:0080

The segment prefixes are determined by the most recent segment directive invoked (see BSEG/CSEG/DSEG/NSEG/XSEG directives).

TEXT
This directive allows an ASCII string to be used to assign values to a sequence of locations starting at the current Instruction Pointer. The format is:
  [label] .TEXT   "string"

The ASCII value of each character in string is taken and assigned to the next sequential location. Some escape sequences are supported as follows:

Escape Sequence   Description    
\n            Line Feed    
\r            Carriage return    
\b            Backspace    
\t            Tab    
\f            Formfeed    
\\            Backslash    
\"            Quote    
\000         Octal value of character    

Here are some examples:

    message1   .TEXT   "Disk I/O error"
    message2   .text   "Enter file name "
               .text   "abcdefg\n\r"
               .text   "I said \"NO\""

TITLE
The TITLE directive allows the user to define a title string that appears at the top of each page of the list file (assuming the PAGE mode is on). The format is:
    [label]    .TITLE  "string"

The string should not exceed 80 characters. Here are some examples:
    .TITLE  "Controller version 1.1"
    .title  "This is the title of the assembly"
    .title  ""

WORD
The WORD directive allows a value assignment to the next two bytes pointed to by the current Instruction Pointer. The format is:
  [label] .WORD expr [,expr...]

The least significant byte of expr is put at the current Instruction Pointer with the most significant byte at the next sequential location (unless the MSFIRST directive has been invoked). Here are some examples:

  data_table     .WORD   (data_table + 1)
                 .word   $1234
                 .Word   (('x' - 'a')  << 2)
                 .Word  12, 55, 32




TASM. Copyright (C) 1998 by Squak Valley Software.
All rights reserved.