Feersum miSim DE 2.0 Manual

Chapter 4 - Assembler Continued

Assembler Commands

The assembler recognises the following commands:


Command Meaning
General Commands
ORG        Set program origin
INCLUDE / #INCLUDE Include source file
#DEFINE Define text substitution
LIST      Assembly & listing options
NOLIST  Disable listing
RADIX    Set default radix
PROCESSOR Set processor
END        End of assembly file
Label & Variable Definitions
EQU        Define constant label
SET        Define variable label
CONSTANT Create constant label(s)
VARIABLE Create variable label(s)
Data Definition
DW          Declare word data
DB          Declare byte data
DT          Declare table
DE          Declare EEPROM data
Conditional Assembly
IF          Begin conditional assembly block
ELSE      Begin Else-part of condition
ENDIF    End conditional assembly block
IFDEF    Conditional on label being defined
IFNDEF  Conditional on label not being defined
Macro Commands
MACRO    Start macro definition
ENDM      End macro definition
LOCAL    Declare local label
EXITM    Exit from macro
Message and Error reporting
MESSG    Generate a message during assembly
ERROR    Generate error report during assembly
Device Configuration
__CONFIG Set configuration bits
__MAXRAM Specify Maximum RAM address
__BADRAM Specify Bad RAM Address

Command	Meaning
General Commands
ORG	Set program origin
INCLUDE / #INCLUDE	Include source file
#DEFINE	Define text substitution
LIST	Assembly & listing options
NOLIST	Disable listing
RADIX	Set default radix
PROCESSOR	Set processor
END	End of assembly file
Label & Variable Definitions
EQU	Define constant label
SET	Define variable label
CONSTANT	Create constant label(s)
VARIABLE	Create variable label(s)
Data Definition
DW	Declare word data
DB	Declare byte data
DT	Declare table
DE	Declare EEPROM data
Conditional Assembly
IF	Begin conditional assembly block
ELSE	Begin Else-part of condition
ENDIF	End conditional assembly block
IFDEF	Conditional on label being defined
IFNDEF	Conditional on label not being defined
Macro Commands
MACRO	Start macro definition
ENDM	End macro definition
LOCAL	Declare local label
EXITM	Exit from macro
Message and Error reporting
MESSG	Generate a message during assembly
ERROR	Generate error report during assembly
Device Configuration
__CONFIG	Set configuration bits
__MAXRAM	Specify Maximum RAM address
__BADRAM	Specify Bad RAM Address

ORG - Set program origin

[<label>] ORG <address>

Set the program address for subsequent machine instructions. <address> can be any numeric expression within the address range of the device. The expression must have no forward references. If a label is specified, then it will be defined with the value of the address expression. If no origin is specified, machine instructions will start at address zero.

main ORG 100

#INCLUDE - Include source file

INCLUDE <include_file>

#INCLUDE <include_file>

The specified source file is read and the assembler treats it as though it were inserted into the current file at the line of the INCLUDE command. The include file can be specifed as a valid string, either enclosed in quotes (eg. INCLUDE "my_utils.asm") or angle brackets (eg. INCLUDE <my_utils.asm>). The assembler supports nested include files (one file including another and so on) up to a depth of 32 files. However, macro expansion uses the same source stack, so the functional depth may be less. For code legibility it is not recommended that more than two or three levels of include file are used.

INCLUDE <registers.h>

#DEFINE - Define text substitution

#DEFINE <name> [<text>]

Before subsequent lines of the assembly file are parsed, any occurance of <name> will be replaced with the text given in the definition. This can be used, for instance, to replace a commonly used expression with a simpler label. If no text is specified, the substitution will be defined (and can be tested with the IFDEF command), but occurances of <name> will be removed from the assembly file - i.e. replaced by an empty string.

Unlike MPASM, this implementation of #DEFINE does not support parameters
(for instance #DEFINE a_function(A,B,C) A-(b*C))).

#DEFINE clock_freq 12000000/4

LIST - Assembly & listing options

LIST [<list_option> [,<list_option>...]]

The list command by itself may be used to turn listing back on if it has been disabled using the NOLIST command.

Otherwise, a number of list options may be specified to control the assembly process and final listing format.

List Option	Meaning
`p=<processor>`	Assemble for the given processor type
`r=[oct\|dec\|hex]`	Set default radix (base) to octal, decimal or hex

LIST p=16F84,r=dec

NOLIST - Disable listing

NOLIST

Turn off file listing output in assembled file. This might be used to hide unwanted comments or assembler commands in the final listing.

NOLIST

RADIX - Set default radix

RADIX [oct|dec|hex]

Set the default radix (base) for numbers to octal, decimal or hexadecimal. If no radix is specified in an assembly file, numbers are assumed to be in hexadecimal.

RADIX dec

PROCESSOR - Set processor

PROCESSOR <processor>

Set the target processor to the given device. If the processor is defined in the assembly file, it must be done before any machine instructions. When assembling a file that defines a different processor to the device currently being emulated, miSim DE will automatically switch to the new device, and reparse the current file if necessary. A label of the form '__<processor>' will be defined and can be tested with the IFDEF command.

PROCESSOR 16F84

EQU - Define constant label

<label> EQU <expression>

The value of the expression is assigned to the label. The label is treated as a constant - it cannot be given another value. Constant labels may be referenced before they are defined in the assembly file.

porta EQU 05h

SET - Define variable label

label SET <expression>

The value of the expression is assigned to the label. The label is treated as a variable - it may be assigned another value later in the source file. Variable labels cannot be referenced before they are assigned. The equals ('=') operator may be used in place of the SET command.

counter SET counter+1

CONSTANT - Create constant label(s)

CONSTANT <label>=<expression> [,<label>=<expression>...]

One or more labels may be defined. Each label behaves exactly as it would if defined by the EQU command.

CONSTANT speed=23,maximum=speed+12

VARIABLE - Define variable label(s)

VARIABLE <label>[=<expression>] [,<label>[=<expression>]...]

One or more variable labels may be defined. Each label behaves exactly as it would if defined by the SET command or = operator. If no initial value is given for the label, it is reserved as a variable label (and may be tested with the IFDEF command) but has no value.

VARIABLE counter,limit=12

DW - Declare word data

DW <expression> [,<expression>... ]

Declare one or more words of data, which are stored at the current assembly address. Note that strings may be used as an argument to the DW command, each word will be initialised with the numeric values of two characters. If the string does not contain an even number of characters, the final word will contain 0 in it's least significant byte.

DW 0x123, 0x1FF, 0x012

DB - Declare byte data

DB <expression> [,<expression>... ]

Declare one or more bytes of data which will be stored at the current assembly address. Two bytes of data will be stored in each word. Note that strings may be used as an argument to the DB command, each byte will contain the value of the equivalent character in the string.

DB 2,3,4,5

DT - Declare table data

DT <expression> [,<expression>... ]

Define a table of values. A table is created as a sequence of RETLW instructions, each returning a byte value for the relevant expression. Each character in a string is returned in its own RETLW instruction.

DT "Hello"

DE - Declare EEPROM data

DE <expression> [,<expression>... ]

Store a sequence of 8-bit expressions as word data at the current assembly address. The upper bits of each word are set to zero.

DE "Hello"

IF - Begin conditional assembly block

IF <expression>

Test the given expression, and if it is logically true, assemble the following lines of code to the matching ELSE or ENDIF statement - otherwise skip those lines. An expression is considered logically false if it evaluates to zero, otherwise it is true. Relational expressions (eg. a >= b) will evaluate to the appropriate zero or non-zero values.

     IF label > 4
       label = 4
     ENDIF

ELSE - Begin Else-part of condition

ELSE

If the previous IF statement evaluated to true, stop assembling successive lines of code until a matching ENDIF statement is found. If it evaluated to false, assemble the following lines to the ENDIF statement.

     IF size < 20
       DW size
     ELSE
       DW 20
     ENDIF

ENDIF - End conditional assembly block

ENDIF

Conditional assembly returns to the state of the surrounding block. If there is no surrounding IF..ENDIF block, assembly continues as normal - otherwise, conditional assembly is decided by the surrounding IF statement.

     IF label == 12
       IF size < 20    ; Nested IF command
          DW size
       ELSE 
          DW 20
       ENDIF           ; End nested IF
     ELSE
       DW 0
     ENDIF             ; End surrounding IF

IFDEF - Conditional on label being defined

IFDEF <label>

Behaves exactly as the IF command - except that the following lines will be assembled if the given label has been defined - either with the #DEFINE, SET or EQU commands - or has been defined as an address label.

#DEFINE testing     ; Comment this out to stop test_routine being called
.
.
.
     IFDEF testing
       CALL test_routine
     ENDIF

IFNDEF - Conditional on label not being defined

IFNDEF <label>

As for the IFDEF command - but the following lines will be assembled if the given label has not been defined.

     IFNDEF file_included
       #INCLUDE "my_file.asm"
       #DEFINE file_included
     ENDIF

MACRO - Start Macro definition

<label> MACRO [<argument> [,<argument>...]]

Start the definition of a macro with the name <label>. A macro is a number of lines of assembly code which can be inserted into the source file simply by using the macro name. The Macro is expanded in place of the label, and will assemble as though those lines were inserted. Macros therefore do not save on program space (as a subroutine would), but save on typing, and can make a program more readable by replacing common sequences of instructions with a single label.

Macros can take optional arguments. Each of these is a label that can be referenced within the macro definition. When the Macro is called, the arguments must then be specified as a series of expressions, separated by commas. The text of each argument (not the value) is inserted in place of the argument name wherever it occurs in the expanded macro. This means that an expression is not evaluated until after it is substituted, and so care must be taken with operator precedence for complex expressions involving arguments.

Macros may reference other macros, or even themselves (recursion). Macros may be nested in this way up to 32 deep - however, the macro stack is shared by the INCLUDE function so in practice the available depth is lower. If a macro references itself (if it is recursive), the macro must use conditional assembly (IF,ELSE,ENDIF) to prevent infinite recursion. See the EXITM command for an example.

delay MACRO  time
      MOVLW  time
      MOVWF  counter         
loop  DECFSZ counter
      GOTO   loop
      ENDM

counter EQU   11
        .
        .
        .
        delay 4

ENDM - End macro definition

ENDM

This command marks the end of a macro definition.

two_cycle_delay  MACRO
                 GOTO $+1    ; Goto the next address - takes two cycles
                 ENDM

LOCAL - Declare local label

LOCAL <label>[=<expression>] [,<label>[=<expression>]...]

In the example above for the 'delay' Macro, the label 'loop' will be defined when the macro is referenced. However, if the macro is referenced a second time, the assembler will produce an error - that the label 'loop' has already been defined. To prevent this error, a macro can declare labels to be LOCAL. The label can then be declared and given a value within the macro that is not visible outside of the macro definition. The value of the local label is only available within the Macro, or within nested macros.

LOCAL loop, timer=32

EXITM - Exit from macro

EXITM

When an this command is encountered whilst expanding a Macro, the macro expansion will stop immediately. This allows macros to be terminated early or conditionally (using the IF, ELSE, ENDIF commands).

many_loops  MACRO  n, delay         ; Expands to create n delay loops
            LOCAL  loop             ; Local label loop

	    MOVLW  delay            ; Delay 
            MOVWF  counter
loop        DECFSZ counter
            GOTO   loop

            IF n <= 1               ; Test to see if we've done enough
              EXITM                 ; If we have Exit the Macro
            ENDIF                   ; Otherwise create another delay..
              many_loops n-1, delay ; ..by calling this macro recursively
            ENDM

MESSG - Generate a message during assembly

MESSG <string>

When this command is encountered, the given message is placed on a line of its own in the listing file.

     NOLIST
     MESSG "This program was last updated 10/5/2002"
     MESSG "Latest sorce is at: http://www.feertech.com"
     LIST

ERROR - Generate error report during assembly

ERROR <string>

When this command is encountered, the current line is marked with the error message, and assembly fails. This allows the source code to respond to situations where assembly should not complete.

     IFNDEF __16F84
       ERROR "This code will only work with the 16F84 processor!"
     ENDIF

__CONFIG - Set configuration bits

__CONFIG <expression>

The configuration word for this processor is set to the value of the given expression.

__CONFIG 0xFF34

__MAXRAM - Specify Maximum RAM address

__MAXRAM <expression>

This command is ignored by miSim but is included for compatibility with MPASM source files.

__MAXRAM 0x7F

__BADRAM - Specify Bad RAM Address

__BADRAM <expression> [-<expression>] [, <expression> [-<expression>]]

This command is ignored by miSim but is included for compatibility with MPASM source files.

__BADRAM 0x70, 0x30-0x3F