Directives

INCLUDE
END
ALERT & ERROR
PROC
DATA
BLOCK
EQU
ASSIGN & SET
ASK
ORG
ALIGN
SECTION
RES, DS & RMB
IF, ELSE & ENDIF
MACRO, EXTIM & ENDM
ALIAS


INCLUDE

Syntax: include "file name" [; comments]

The include directive instructs Crossbow to read in and assemble the text from another source file, allowing very large programs to be split into smaller, more easily maintained modules. Combined with conditional assembly, include statements allow a family of similar products to share a common set of core source files while supporting specific hardware and software features.

Included files start immediately after the end of line containing the include statement, and assembly of the initial file resumes either at the physical end of the included file or on encountering an end statement in the included source. Included files may nest so that one include file may include another, which may in turn include another and so on, with a maximum of sixty-four levels.

The include directive requires a file name specifier in the operand field, which must be enclosed in double-quotes, must be less than sixty-four characters long, and must conform to Macintosh file naming conventions. Use two consecutive double-quotes to incorporate the double-quote character in a file name.

The assembler looks for the include file in the folder which contained the principle source file used to start the assembly. To force Crossbow to search in a different folder, use full Macintosh path names with colons delimiting the search path hierarchy. For example, an include name specified as "hd:monitor:test.asm" tells Crossbow to search on volume "hd", in the folder "test" for the document named "test.asm".

Errors encountered in an include file cause Crossbow to open a window for the offending file, positioning the insertion point at the cause of the problem. Crossbow will complain if no more windows are available (maximum of 16), telling you that an error occurred in the include file, but not showing exactly where. To locate the error, close one or more open windows and retry the assembly.

Proper Usage:

        include "Equates.Asm"           ; comments allowed
        INCLUDE "Inits.Asm"             ; case insensitive
        include "hd: Test:Monitor.Asm" ; full pathname
        include "Functions.Asm" ; leading space instead of tab ok
        include "I/O Lib.Asm"           ; input output functions
        if ASSEMBLER | DISASSEMBLER | TRACEPROG
        include "opcodes.asm"           ; conditional inclusion
        endif


Improper Usage:

        include "Equates.Asm"           ; can't begin in column 1
        INCLUDE Inits.Asm               ; missing quotes
        start:  include "Functions.Asm" ; must not have label


The include directive may neither be used inside, nor redefined by a macro definition. Include may not be prefaced with a label. Includes are limited to 64 include files, 64 nesting levels, and 64 characters in file names, including the full path.


END

Syntax: [label] end expr [; comments]

The end directive instructs the assembler to stop reading the current source file at the end of this line. If the current file is not the last or only source file, assembly resumes on the next line of the file which included this file. End statements may include an optional expression in the arguments field specifying the starting address of the assembled program. The start address will be placed in the output object file if the file format selected for this assembly supports starting address information.

theEnd: end     Monitor
        Here we've seen an end statement,
                so we can do anything we want!
                it won't be included in the source code!
 
        X     X  BBBBB    OOOO
         X   X   B    B  O    O
          X X    B    B  O    O
           X     BBBBB   O    O
          X X    B    B  O    O
         X   X   B    B  O    O
        X     X  BBBBB    OOOO

Crossbow ignores absolutely everything following the carriage return at the end of the line containing the end directive. This then becomes the only entirely safe place to store multi-line sections of arbitrary text without the possible side effects of assembler misinterpretation (blocks inside false conditionals are still examined by the assembler while looking for else and endif!).


ALERT & ERROR

Syntax: [label] alert "message" [; comments]
[label] error "message" [; comments]

The alert and error directives instruct Crossbow to get the programmer's attention by sounding a beep and displaying an alert box with a user specified message. In the case of the alert directive, assembly continues when the programmer acknowledges the alert by hitting the return key or clicking the mouse button. In the case of the error directive, Crossbow opens a window for the file requesting the error, positions the insertion point at the error message, then waits for the programmer's acknowledge.

lastLoc equ     $               ; know last memory used
;
  if lastLoc - startLoc > 8192
        alert   "This will need two EPROMs!"
  endif

When the example above is run with a source program that generates more code that will fit into a 2764 EPROM (assuming that the source program starts with a label called "startLoc"), the assembler displays the specified message as shown.


PROC

Syntax: [label] proc "proctype" [; comments]

Crossbow uses the quoted string following the proc directive to perform a case-insensitive substring search in the same string table used to create the processor pop-up menu.

    1                   ;======================
    2                   ;	Proc Test.Asm
    3                   ;======================
    4                   	proc	"1802"
    5 0000   C4         	nop
    6                   	proc	"6301"
    7 0001   01         	nop
    8                   	proc	"6502"
    9 0002   EA         	nop
   10                   	proc	"6805"
   11 0003   9D         	nop
   12                   	proc	"8085"
   13 0004   00         	nop



DATA DB, FCB, DW, FDB, & FCC

Syntax: [label] data[.sz] expr | "string" [,expr | "string"]
[label] db expr | "string" [,expr | "string"]
[label] fcb expr | "string" [,expr | "string"]
[label] dw expr | "string" [,expr | "string"]
[label] fdb expr | "string" [,expr | "string"]
[label] fcc <delim> "string" <delim>

The various data declaration directives instruct the assembler to generate initialized data from expressions and strings. The size of the data generated for each expression is determined either explicitly with "dot-size" suffixing as in the data directive, or implicitly by the directive name. Expression values are truncated to fit into objects of the specified size.

The data directive and the "dot-size" suffixes shown in the table below conform to the guidelines of the IEEE-694 standard for microprocessor assembly language. The fcb (Form Constant Byte), fdb (Form Double Byte), and fcc (Form Constant Characters) are provided as a convenience to programmers more comfortable with Motorola pseudo-ops, while the db (Define Byte), and dw (Define Word) are available for programmers preferring Intel mnemonics.

       Size Specifiers
        .b .B   Byte
        .s .S   Short (2 Bytes)
        .w .W   Word (2 Bytes)
        .l .L   Long (4 Bytes)
        .q .Q   Quad (8 Bytes)


With the exception of the fcc directive, all of the data directives accept any combination of strings and expressions. Strings used with these directives must be enclosed inside double quotes. Use two consecutive double quotes to generate one double quote character in the output data.

The fcc directive generates data from string expressions bracketed by the first character encountered in the operand field. Use two consecutive occurrences of the delimiting character to generate one instance of the character in the output data.

_data:  data    "sample string"
        data    "several", "different", "strings"
        data    "several", 0, "terminated", 0, "strings", 0
        data    "sample string with quote ("") character"
        data    "string with byte expression", 10
;
        data    0,1,2,3 ; yields: 00 01 02 03
        data.b  0,1,2,3 ; yields: 00 01 02 03
        data.w  0,1,2,3 ; yields: 00 00 00 01 00 02 00 03
        data.l  0,1     ; yields: 00 00 00 00 00 00 00 01
        data.q  0       ; yields: 00 00 00 00 00 00 00 00
;
_db:    db      "string with ending bit 7 hig", 'h' + h'80
_fcb:   fcb     "string with embedded quote ("")"
        db      'ab'    ; should just be h'61
        fcb     ''''    ; the single-quote character
;
_dw:    dw      0,1,2,3 ; yields: 00 00 00 01 00 02 00 03
        dw      'ab'    ; should        be h'6162
_fdb:   fdb     '''''' ; two single-quote characters
;
_fcc:   fcc     :string with colon (::) terminators:
        fcc     ~string with tilde (~~) terminators~
        fcc     /string with tilde (//) terminators/


The maximum number of bytes generated from a single data statement can not exceed 255.


BLOCK

Syntax: [label] block[.sz] length,value [; comments]

The block directive initializes a block of memory with a specified value. Block without a size specifier defaults to byte, and accepts size specifiers for byte (.b), word (.w or .s), long (.l) and quad (.q). The size of the block (length * size) must be less than 32767.

    1                   ;======================
    2                   ;       Block Test.Asm  
    3                   ;======================
    4 0000   2A2A2A2A2A         block   16,'*'
    5 0010   5555555555         block   32,h'55
    6 0030   00AA00AA00         block.w 32,h'aa
    7 0070   000000BB00         block.l 32,h'bb
    8 00F0   0000000000         block.q 32,h'cc
    9 01F0   FFFFFFFFFF         block   2048,h'ff
   10      = 09F0       next    equ     $



EQU

Syntax: label equ expr [; comments]

The equ directive permanently assigns a numeric value to a symbol which may be used anywhere a constant is expected. Both the label and operand fields are required.

        FALSE   equ     0
        TRUE    equ     ~FALSE
        DEBUG   equ     FALSE
        DEL     equ     H'7F    ; ASCII delete
        SOH     equ     H'01
        EOT     equ     H'04
        ACK     equ     H'06
        NAK     equ     H'15
        CAN     equ     H'18
        CON     equ     H'11
        NUL     equ     H'00    ; NUL is used as string terminator
        BS      equ     H'08    ; backspace
        CR      equ     H'0D    ; carriage return
        LF      equ     H'0A    ; line feed
        TAB     equ     H'09    ; horizontal tab
        SP      equ     H'20    ; 'space' character
        COMMA   equ     H'2C
        ; offsets into register storage - 9 bytes per area
        RSAVSIZ equ     7       ; amt of mem to save complete state
        CCR     equ     0       ; Condition Code offset
        AREG    equ     1       ; A register offset
        BREG    equ     2       ; B register offset
        XREG    equ     3       ; X register offset
        STKP    equ     5       ; Stack Pointer offset


Values used in the assignment expression must not contain any forward references. Crossbow does not adapt equ to perform text substitution on arguments which do not evaluate to a number.


ASSIGN & SET

Syntax: label assign expr [; comments]
label set expr [; comments]

The assign and set directives assign a value to a symbol which may later be redefined. Both the label and operand fields are required.

        temp    assign  1               ; simple assignment
        temp    assign  temp + 1        ; should be 2
        temp    assign  temp * 2        ; should be 4
         if temp <> 4
                alert "assign: defective directive"
         endif


Values used in the assignment expression must not contain any forward references. Assign is the recommended IEEE mnemonic and set is the equivalent Intel variation.


ASK

Syntax: [label] ask "question" [; comments]

The ask directive displays a Macintosh dialog box with a user specified prompt string and a text box for entering a numerical reply. Clicking "OK" assigns the value in the reply box to the label on the line with the ask directive.

        ;========================================
        ;       Ask Test.Asm
        ;========================================
        sernum  ask     "Serial Number ?"
        model   ask     "Model ? (2,3,4)"
                if      (model < 2) | (model > 4)
                error   "Model must be (2,3,4)"
                endif


ORG

Syntax: [label] org expr [; comments]

The org directive sets the location counter to the value specified by the expression in the operand field. Values used in the org directive's expression field must not contain any forward references.

        _org:   org     h'100
                data    "string at hex 100"
        ;
                org     h'100 + h'600
                data "string at hex 700"
        ;
                org 'ab'
                data "string at hex 6162"


ALIGN

Syntax: [label] align expr [; comments]

The align directive forces the location counter to align to a boundary that is an even multiple of the value specified by the expression in the operand field. Values in the align directive's expression field must not contain any forward references.

        _align: align   2       ; align on word boundary
                data    "word"
        ;
                align   4       ; align on long boundary
                data    "long"
        ;
                align   16      ; align on paragraph boundary
                data    "para"
        ;
                align   256     ; align on page boundary
                data    "page"
        ;
                align   32768   ; align on enormous boundary
                data    "huge"
        ;
                align   1       ; back to byte boundary
                data    "byte"
        ;
                align   37      ; align to silly boundary
                data    "silly" data "silly"


SECTION

Syntax: label section expr [; comments]
section name [; comments]

The section directive provides an efficient mechanism for conveniently partitioning the various memory resources used in a real program. Even simple programs usually have an area in EPROM for the program code and fixed data and an area in RAM for variables. More complex programs may have several code sections for overlays and bank switches, and several variable areas (page zero RAM for frequently referenced variables, and general purpose variable areas).

The section directive eliminates the requirement that all code and data declarations pertaining to a particular area must be in the same contiguous section of source code. Using section, the required areas are defined once early in the program and the assembler takes care of providing the proper location counter for a specific section request.

The first form of the section directive associates a section of code or data starting at the location specified by the expression in the operand field with a name specified by the label. This first form is just a definition; the location specified by the expression will not take effect until the section directive is invoked using the second form.

The second form of the section directive sets the location counter to the current value of the named section. Before switching sections, the assembler saves the address of the current location counter for a future section invocation of the previously used section. Values used in the section expression must not contain any forward references. Section invocations may not be prefaced with a label.

        _section:
        ;;;; DEFINE SECTIONS
        pg0     section 0
        code    section h'1000
        data    section h'8000
        ;;;; USE SECTIONS
 
                section pg0
                data    "page zero stuff"
        ;
                section data
                data    "some stuff in data section"
        ;
                section code
                nop
                nop
        ;
                section data
                data    "more data section stuff"
                section code
                nop
        lastop: nop
                section pg0


RES, DS, & RMB

Syntax: [label] res expr [; comments]
[label] ds expr [; comments]
[label] rmb expr [; comments]

The res, ds, and rmb directives define a block of uninitialized data equal in length to the value of the expression in the operand field multiplied by the optional size specifier . Blocks declared using the reserve directives affect only the location counter and do not generate any output data in the object file. Values used in reserve statements must not contain any forward references.

	org	h'8000		; nice spot for checking
;
_res:	res	h'100		; should be 8000 - 80FF
;
	res.b	h'100		; should be 8100 - 81FF
;
	res.s	h'100		; should be 8200 - 83FF
;
	res.w	h'100		; should be 8400 - 85FF
;
	res.l	h'100		; should be 8600 - 89FF
;
	res.q	h'100		; should be 8A00 - 91FF


IF, ELSE, & ENDIF

Syntax: [label] if expr [; comments]
else [; comments]
endif [; comments]

The conditional assembly directives allow blocks of source code to be excluded from assembly based on the value of an expression. Text between false conditional blocks must still be valid assembly code to enable the assembler to locate the else and endif directives.

        FALSE   EQU     0
        TRUE    EQU     ~ FALSE
        ;
          if    TRUE
                data    "true"  ; should assemble this
          else
                data    "false" ; but NOT this
          endif
        ;
          if    FALSE
                data    "false" ; should NOT assemble this
          else
                data    "true"  ; but should assemble this
          endif


Values used in the if expression must not contain any forward references. The else and endif directives may not be prefaced with labels. Crossbow does not support multiple exclusive else clauses (no if, else, else). If blocks may nest up to twenty-five levels deep.


MACRO, EXITM, & ENDM

Syntax: mcrnm macro [; comments]
[label] <mcrnm> [<][parm][,parm][>] [; comments]
exitm [; comments]
endm [; comments]

Crossbow's macro capabilities allow you to replace frequently used instruction sequences with a single keyword. Define macros by starting the line with the macro name in the label field, followed by the keyword macro and any optional comments prefaced with a semi-colon. Create the macro template by inserting the assembly statements which describe the operation of the macro, and finish the definition with the endm directive.

Parameters passed during macro invocation are declared in the macro template using a dollar sign ($) followed by a digit from one to nine. The parameter list in a macro invocation is declared in the operand field of the invocation as a comma delimited list of parameters. To allow multiple parameters to pass as a single parameter, enclose them in angle brackets.

In the macro expansion, the first parameter in the parameter list will replace the "$1" dummy parameter, the second will replace "$2" and so on up to "$9" To provide local labels during multiple macro expansions, the "$0" character string is replaced with an incrementing four digit string which may concatenate with a partial label to form a new unique label.

Macro definitions may reference other macros which may in turn reference other macros up to twenty five levels deep, although the body of a macro definition may not contain another macro definition. 

        ;;;; DEFINE PRINT MACRO
        print   macro
                jsr _print
                data $1,0
                endm
        ;;;; TRY THE PRINT MACRO
        cr      equ     h'0d
        lf      equ     h'0a
                print   "macro test"
                print   <cr,lf,"more test",cr,lf>
        ;;;; PRINT SUBROUTINE USED BY MACRO
        ;;;; prints zero terminated string on top of stack
        outc    equ     $       ; so we don't generate error
        print:  pulx            ; get string address
        _pr1:   ldaa    0,x     ; get first character
                inx             ; ready next char
                tsta            ; hit terminator ???
                beq     _prx    ; yes, exit
                jsr     outc    ; display char
                bra     _pr1    ; and loop
        ;
        _prx:   pshx            ; set up return address
                rts             ; and return


The include directive may not be used inside a macro definition. Exitm and endm may not be prefaced with labels. Macros may not be used to redefine mnemonic and directive keywords. Crossbow is limited to 200 macro definitions and 25 levels of nested macros.


ALIAS

Syntax: newop alias oldop [; comments]

The alias directive allows you to invoke any instruction mnemonic or directive using a different name. Alias helps Crossbow to work with source files created by other assemblers using non-standard instructions and pseudo-ops.

    1                   ;======================
    2                   ;       Alias Test.Asm  
    3                   ;======================
    4                           proc    "68HC11"
    5                   plugh   alias   wai
    6                   xyzzy   alias   ldaa
    7 0000   3E                 plugh
    8 0001   8601               xyzzy   #1
    9                   nop     alias   mul
   10                   mul     alias   nop
   11 0003   3D                 mul
   12 0004   01                 nop
   13 0005   3D                 .nop
   14 0006   01                 .mul
 

Previous               Contents