7 ASSEMBLER DIRECTIVES

This chapter contains the following sections:

Introduction
Directives Overview
Debugging
Location Counter
Use of the Location Counter ($)
Directives
?FILE Directive
?LINE Directive
?SYMB Directive
BSEG Directive
CODE Directive
CSEG Directive
DATA Directive
DB Directive
DBIT Directive
DS Directive
DSEG Directive
DW Directive
END Directive
EQU Directive
EXTRN Directive
IDATA Directive
ISEG Directive
NAME Directive
ORG Directive
PUBLIC Directive
RSEG Directive
SEGMENT Directive
SET Directive
USING Directive
XDATA Directive
XSEG Directive

7.1 Introduction

Assembler directives, or pseudo instructions, are used to control the assembly process. Rather than being translated into a 8051 machine instruction, assembler directives are interpreted by the assembler. Only the DB and DW directives actually cause code to be generated. The other directives perform actions like defining or switching segments, defining symbols or changing the location counter.

7.2 Directives Overview

Directive Description
DEBUGGING
?FILE "filename" Generate filename symbol record.
?LINE [abs_expr] Generate line number symbol record.
?SYMB string, expr [,abs_expr] [,abs_expr] Generate hll symbol info record.
SYMBOL DEFINITION
name SEGMENT type [attr] [OVERLAY( b [,b ]... )] Declare relocatable segment.
equ-name EQU expression Assign expression to name.
set-name SET expression Define symbol for expression.
bit-name BIT bit-address Assign bit address to name.
name DATA expression Assign DATA address to name.
name IDATA expression Assign IDATA address to name.
name XDATA expression Assign XDATA address to name.
name CODE expression Assign CODE address to name.
STORAGE INITIALIZATION AND RESERVATION
[label:] DS abs_expr Reserve bytes
[label:] DBIT abs_expr Reserve bits
[label:] DB item [,...] 1-byte  initialization
[label:] DW init [,...] 2-byte  initialization
PROGRAM LINKAGE
PUBLIC name [,...] Define symbols to be public
EXTRN type (sym[,sym]...) [,type (sym[,sym]...)]... Set symbols to be defined extern.
NAME module-name Define module name

ASSEMBLER STATE
END End assembly.
ORG expression Modify location counter.
SEGMENT SELECTION
RSEG segment_name Select relocatable segment.
CSEG [AT address] Select absolute CODE segment.
DSEG [AT address] Select absolute DATA segment.
ISEG [AT address] Select absolute IDATA segment.
BSEG [AT address] Select absolute BIT segment.
XSEG [SHORT] [AT address] Select absolute XDATA segment.
REGISTER BANK
USING expression Use register bank number.

Table 7-1: asm51 directives

7.3 Debugging

The assembler asm51 supports the following debugging directives: ?FILE, ?LINE and ?SYMB. These directives will not be used by an assembler programmer. They are used by a high level language code generator to pass high level language symbol information to a debugger.

7.4 Location Counter

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

7.5 Directives

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

?FILE

Synopsis:

?FILE "filename"

Description:

This directive is intended mainly for use by a high level language code generator. It generates a symbol record containing the high level source filename, which is written to the object file. Also, the current high level line number is reset to zero. The filename can be used by a high level language debugger.

?LINE

Synopsis:

?LINE [abs_expr]

Description:

This directive is intended mainly for use by a high level language code generator. It generates a symbol record containing the high level source file line number, which is written to the object file. The line number can be used by a high level language debugger. abs_expr is any absolute expression. If abs_expr is omitted, the line number defined by the previous ?LINE or ?FILE is incremented and used.

?SYMB

Synopsis:

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

Description:

The ?SYMB directive is used for passing high-level language symbol information to the assembler. This information can be used by a high level language debugger.

BIT

Synopsis:

name BIT expr

Description:

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

Examples:

      RSEG  A_SEG        ;relocatable bit
                         ;addressable segment
CTRL: DS    1

TST   BIT   CTRL.0       ;bit in relocatable byte
OK    BIT   TST+1        ;next bit
TST2  BIT   64H          ;absolute bit

BSEG

Synopsis:

BSEG [AT abs_expr]

Description:

Switch to the absolute BIT segment. The following statements will be assembled in the absolute mode within the BIT address space. The specified segment remains in effect until another segment directive is encountered. Unless a starting address is specified with abs_expr, the assembler continues the last absolute BIT segment. The first absolute BIT segment starts at address zero.

Examples:

BSEG AT 70H     ;absolute bit segment

CODE

Synopsis:

name CODE expr

Description:

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

Examples:

RESTART     CODE     00H

CSEG

Synopsis:

CSEG [AT abs_expr]

Description:

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

Examples:

CSEG AT 00H     ;first absolute code segment

DATA

Synopsis:

name DATA expr

Description:

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

Examples:

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

DB

Synopsis:

[label:] DB item [,item]...

Description:

The DB directive initializes memory with byte values. This directive is only allowed in a CODE segment. An item can be either a string, or an expression. For strings, each character in the string is placed in one byte of memory.

With this directive, strings longer that 2 characters and empty strings are acceptable. For every expression in the item list, the least significant byte is placed in memory.

Examples:

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

DBIT

Synopsis:

[label:] DBIT abs_expr

Description:

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

Examples:

NBITS:  DBIT  6  ; reserve 6 bits

DS

Synopsis:

[label:] DS abs_expr

Description:

The DS directive reserves space in byte units. It can be used in any segment except a BIT type segment. The expression must be an absolute expression without forward references. When a DS directive is encountered, the location counter of the current segment is incremented by the value of the expression.

Examples:

DS 3+2  ;reserve 5 bytes

DSEG

Synopsis:

DSEG [AT abs_expr]

Description:

Switch to the absolute DATA segment. The following statements will be assembled in the absolute mode within the DATA address space. The specified segment remains in effect until another segment directive is encountered. Unless a starting address is specified with abs_expr, the assembler continues the last absolute DATA segment. The first absolute DATA segment starts at address zero.

Examples:

DSEG    ;switch to DATA segment

DW

Synopsis:

[label:] DW expr [,expr]...

Description:

The DW directive initializes memory with word values. This directive is only allowed in a CODE segment. For every expression in the item list, the word value represented by the expression is placed in memory with the high byte first. Unlike the DB directive, no more than two characters are permitted in a character string, and the null string evaluates to 0000h.

Examples:

WRDS:  DW  34,'OK'  ;initialize 2 words in memory

END

Synopsis:

END

Description:

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

Examples:

  DSEG
AVAR  DW  2


  CSEG
  .
  .

  END    ; End of assembler source

This line is ignored by asm51.

EQU

Synopsis:

name EQU expr
name EQU register

Description:

The EQU directive assigns a numeric value or register name to a symbol name. The expression may not contain forward references or externals. The symbol gets the same type as expr and can be used in any context where expr is allowed.

In the second form, name is declared to be equivalent to a register name; the identifier name can be used in any context where register is allowed. Valid register names are: A, AB, C, DPTR, PC and R0-R7.

Examples:

COUNT  EQU  0FFH  ;COUNT is the same as 0FFH
ACCU  EQU  A  ;define ACCU to stand for A

EXTRN

Synopsis:

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

Description:

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

Examples:

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

IDATA

Synopsis:

name IDATA expr

Description:

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

Examples:

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

ISEG

Synopsis:

ISEG [AT abs_expr]

Description:

Switch to the absolute IDATA segment. The following statements will be assembled in the absolute mode within the IDATA address space. The specified segment remains in effect until another segment directive is encountered. Unless a starting address is specified with abs_expr, the assembler continues the last absolute IDATA segment. The first absolute IDATA segment starts at address zero.

Examples:

ISEG AT 80H  ;start IDATA segment at address 80H

NAME

Synopsis:

NAME module_name

Description:

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

Examples:

name my_prog ; module-name is my_prog

ORG

Synopsis:

ORG expr

Description:

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

Examples:

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

PUBLIC

Synopsis:

PUBLIC name [, name ]...

Description:

The PUBLIC directive allows symbols to be known outside the currently assembled module. Each symbol name may be declared public only once in a module. Any symbol declared PUBLIC must have been defined somewhere else in the program.

Examples:

public pub_symb  ;pub_symb is known outside module

RSEG

Synopsis:

RSEG segment_name

Description:

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

Examples:

CD_SEG SEGMENT  CODE    ;relocatable
          ;code segment
  .
  .

       RSEG  CD_SEG  ;select relocatable
          ;code segment

SEGMENT

Synopsis:

name SEGMENT type [attr] [OVERLAY(b[,b]... )]

Description:

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

The segment type specifies the address space where the segment will reside. Allowable segment types are:

Type Description
BIT bit address space (on-chip)
CODE code address space
DATA direct addressable data (on-chip)
IDATA indirect addressable space (on-chip)
XDATA external address space

Table 7-2: Segment memory types

The optional segment attribute defines the relocation type for this segment. Possible relocation types are:

- BITADDRESSABLE
Specifies a segment to be relocated within the bit space on a byte boundary. Allowed only for DATA segments and the segment size is limited to 16 bytes.

- COMMON
Specifies a segment to be located in the common area. Allowed only for CODE segments. This is only useful when code bank switching is used.

- PAGE
Specifies a segment whose start address must be on a 256-byte page boundary. Allowed only for CODE and XDATA segments.

- INPAGE
Specifies a segment which must be contained in a 256-byte page. Allowed only with CODE and XDATA segments.

- INBLOCK
Specifies a segment which must be contained in a 2048-byte page. Allowed only for CODE segments.

- UNIT
The default relocation attribute: the segment will not be aligned.

- ROMDATA
Specifies that the segment contains initialized data. This attribute is allowed for CODE segments only. This information is meaningful for debugging purposes. A segment that has been declared with the ROMDATA attribute cannot be disassembled by a debugger.

- SHORT
XDATA segments can be declared with the SHORT attribute. The linker allocates the segment in a page of auxiliary memory.

With the optional OVERLAY attribute, it is possible to specify the register banks (b) used in the segment. This information will be used by the linker to overlay segments using the same register banks. No overlaying will be done when the OVERLAY attribute is omitted. The OVERLAY attribute is not allowed for CODE segments.

Examples:

DATSEG  SEGMENT  DATA  ;relocatable data segment

SET

Synopsis:

name SET expr
name SET register

Description:

The SET directive assigns a numeric value or register name to a symbol name. The expression may not contain forward references. The symbol gets the same type as expr and can be used in any context where expr is allowed.

In the second form, name is declared to be equivalent to a register name; the identifier name can be used in any context where register is allowed. Valid register names are: A, AB, C, DPTR, PC and R0-R7.

Unlike the EQU directive, multiple SET directives for the same symbol may be present in one source file. The most recent SET directive determines the value of the symbol.

Examples:

CNT  SET  0  ;set counter to 0
CNT  SET  CNT+1  ;increment counter

USING

Synopsis:

USING expression

Description:

This directive notifies the assembler of the register bank that is used by the subsequent code. The expression is the number (between 0 and 3 inclusive) which refers to one of four register banks.

The USING directive allows you to use the predefined symbolic register addresses (AR0 through AR7) instead of their absolute addresses. In addition, the directive causes the assembler to reserve a space for the specified register bank.

Examples:

USING     3
PUSH      AR2  ;Push register 2 of bank 3
USING     1
PUSH      AR2  ;Push register 2 of bank 1

If you equate a symbol (e.g. using EQU directive) to an ARi symbol, the user-defined symbol will not change its value as a result of the subsequent USING directive.

XDATA

Synopsis:

name XDATA expr

Description:

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

Examples:

        RSEG    XSPACE

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

XSEG

Synopsis:

XSEG [SHORT] [AT abs_expr]

Description:

Switch to the absolute XDATA segment. The following statements will be assembled in the absolute mode within the XDATA address space. The specified segment remains in effect until another segment directive is encountered.

With the SHORT attribute the linker allocates the segment in a page of auxiliary memory (PDATA).

Unless a starting address is specified with abs_expr, the assembler continues the last absolute XDATA segment. The first absolute XDATA segment starts at address zero.

Examples:

XDAT_SEG  SEGMENT  XDATA      ;reloc. data segment

    XSEG SHORT AT 10H   ;abs.  pdata segment
    DS 1

    XSEG       AT 70H   ;abs.  xdata segment
    DS 1

Copyright © 2002 Altium BV