ASHC11 - 68HC11 Macro Assembler

ASHC11 is a DOS based macro assembler for the Motorola 68HC11 and similar processors. It has been used by the author to generate code for a number of vehicle applications, particularly for the GM C3, P4 and higher EC Us. ASHC11's Features include a very capable macro facility and additional (Intel style) mnemonics. The author's companion disassembler DHC11 creates output that can be used immediately by ASHC11. The author's binary conversion utility BINCVT may be used to convert S19 or Hex records to a binary image, and GMCKS to create GM checksums from binary images.

Get version 1.2 of ASHC11 here.

The assembler is described in enough detail here to enable anyone familiar with assembler concepts to begin using it immediately. It was designed to be largely compatible with existing HC11 assemblers and in particular the Motorola freeware assembler (available here as as11.exe). Note that ASHC11 is not a "relocating" assembler, and produces S19 or Hex output only.

As with a lot of free software, the documentation is never complete. We're sure you'll find enough information here to effectively use ASHC11 as long as you've used some kind of assembler before.

Features of the Macro Assembler.

Enhanced Expression Analysis - using simple left to right parsing with the addition of brackets allowing arbitrarily complex expressions to be created on a single assembly line. No complex hierarchy rules need be learnt. White space can be freely used to make expressions easier to analyse. Multiple formats are supported for different number base schemes (eg. 100B, or %100 are equivalent).

MACRO support has been added. Macros may have embedded definitions (ie. macros defined within another macro) and may call other macros (including themselves) from within the macro definition. LOCAL labels used to avoid symbol name clashes may be defined within macros. Compound arguments (ie. arguments containing embedded arguments) may be passed to macros. Early macro exit is possible with the EXITIF clause.

Repeat Blocks using REPT, IRPC and IRP can be declared. REPT blocks repeat a section of code a certain number of times. IRPC blocks repeat a block of code and iterate each pass with the next character from a supplied string. IRP is supplied with a list of arguments that are used successively for each iteration. LOCAL labels can also be used within repeat blocks.

Conditional Assembly is supported with the standard IF, ELSE, ENDIF construct. An ELSEIF clause allows more complex expressions to be expressed quite simply. An IFD and IFND adds a test for symbols being defined or not. Conditional expressions can be nested to many levels.

INCLUDE Files are supported to multiple levels with full listing support.

List Pseudo-ops and command line switches allow control over many variables including macro expansion listing, page length and width, title and subtitle, etc.

Alternative Opcodes have been defined such as EI for STI (or is that CLI? see what I mean?) and DI to enable and disable interrupts. All existing opcodes are supported but you can use more standard names like XOR, PUSH, POP, CALL, RET, JR, etc.

Compound Opcodes like PUSH D (PUSH A + PUSH B) and POP D (POP B + POP A) have been added. These enhancements have been made to allow easy migration from other processors, and are designed to allow programmers to focus on the programming task rather than on learning a new set of obscure and machine specific mnemonics.

ASHC11 Quick Start

 C:\> ASHC11 sourcefilelist [-switchlist]

 ASHC11 file.ext

 ASHC11  x  y  -intel -listing

Only an abbreviated form of each switch is required, eg, -l is enough to specify that a listing should be created. The minimum number of characters required for each switch is indicated by the upper case characters in the description below. Where a parameter is required the switch and the parameter should be separated with a colon (:), or an equals (=) sign. All switches must be separated with white space and the first switch is required to be proceeded by a hyphen. Subsequent switches may be optionally proceeded by a hyphen.

ASHC11 x -i l=list.lst

This command line assembles file X and produces a listing list.list and output file x.hex.

ASHC11 Switches

Expressions, Symbols & Data Types

Expressions

        left_expr operator right_expr      example:    3 + 7
        left_expr operator (right_expr)    example:  1 % (3 + 1)

   expr     ::=  term operator term    |         eg.  a + b
                 term operator expr    |         eg.  a + b / c
                 term operator (expr)  |         eg.  a + (b / c)
                 expr operator expr              eg. (a + d) / (b + c)


   operator ::=      -   |  minus operator
                     +   |  plus operator
                     *   |  multiply operator
                     /   |  divide operator (integer truncation)
                     %   |  modulus operator (integer remainder)
                     |   |  OR operator
                     &   |  AND operator
                     ^   |  XOR (exclusive OR)
                     <<  |  left shift
                     >>  |  right shift

   comparison ::=    <   |  less than
                     >   |  greater than
                     >=  |  equal or greater than
                     <=  |  equal or less than
                     =   |  equal
                     !=     not equal

    term ::=    -term    |  (unary minus)
                ~term    |  (unary NOT or one's complement, 0->1, and 1->0)
                *        |  (the current PC)
                symbol   |  see the symbols section and labels and equates
                constant    see next section

An expression list is simply a comma separated list of individual expressions, and is used for the definition of data storage. Macro parameter lists are also like expression lists. (all are described below).

        expresion_list ::= expression, expression_list

Constant Data Types

  constant         ::=  hex constant     |
                        binary constant  |
                        octal constant   |
                        decimal constant |
                        ascii constant

  hex constant     ::= ${hex digits} |
                       {hex digits}H |
                       {hex digits}h

  octal constant   ::= {octal digits}Q |
                       {octal digits}q |
                       {octal digits}O |
                       {octal digits}o

  binary constant  ::= %{binary digits} |
                       {binary digits}B |
                       {binary digits}b

  decimal constant ::= decimal digits

  ASCII            ::= any printing ASCII character

  ascii constant   ::= '{ASCII character}  |  '{ASCII character}'

  ascii string     ::=  "{ASCII characters}"

  binary digits    ::= 0 | 1

  octal digits     ::= 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7

  decimal digits   ::= 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9

  hex digits       ::= decimal digits  | A | B | C | D | E | F

Symbols

To distinguish symbols from the start of an expression or a constant, all symbols must begin with an upper or lower case alphabetic character, or one of the special characters, underscore (_), dot (.), question mark (?), or the "at" character (@). Numeric characters (ie. 0 through 9) and the dollar symbol ($) are allowed within the body of a symbol. Symbols may be up to at least 80 characters long (but symbol table space is finite) and all symbols are case sensitive (ie. symbol DELAY is NOT the same as Delay).

Note that some characters that are acceptable symbols for Motorola's freeware assembler are not valid for ASHC11. In particular, the dollar ($) symbol is NOT a valid starting character for a symbol, although it may be used within the symbol.

Pseudo-Ops

Pseudo-ops may be in upper or lower case and can begin in any column other than the first. They may have a "." (dot) in front of them (to remain compatible with some other assemblers) so that ".eject" is the same as "eject" or "EJECT" or even ".Eject". Additionally, if a "#" (hash, or pound symbol) is in column one, it may be immediately followed by a pseudo-op. So that "   include" is the same as "#include" (# is in the first column!).

For the purpose of describing them, pseudo-ops have been arbitrarily divided into the following alphabetically listed categories:

1. Conditional expressions that selective assembly blocks of code.
2. Data-ops that generate constant and variable data definitions.
3. Errors and Warnings are user definable messages that are flagged to the command line.
4. Include Files allow (nested) reusable source code.
5. Ignored pseudo-ops are recognised but not actioned and do NOT generate errors or warnings.
6. Labels and Equates allow fixed and variable references and definitions.
7. Listing control allows control over what's sent to the list file, and how it’s formatted.
8. Macros and Repeat blocks that are short definitions used to automatically generate code and data statements.
9. Segment control allows code and various data to be easily combined in the one source file.

Following is an alphabetical listing of all recognised and actioned pseudo-ops. More information on some is found in the section following this list.

Recognised Pseudo-Ops

conditional expressions

IF <expr>
...

ENDIF

    DEBUG equ 3
    IF DEBUG >= 2        ;Assemble if symbol DEBUG is >= to 2
        ldd     MSG      ;This will be assembled in this example
        call    MSGOUT
    ENDIF                ;This terminates the conditional section of code

    IFD <symbolname>
         ...            ;assembles if <symbolname> IS defined
    ENDIF

    IFND <symbolname>
         ...            ;assembles if <symbolname> is NOT defined
    ENDIF

    IFND   PRINTF               ;Tests if symbol PRINTF is defined
        INCLUDE "printf.inc"    ;it's not so include the definitions
    ENDIF

Here is an example where the ELSE statement's code will be assembled.

J = 5 IF J < 4 ;so this is NOT true DB $01 ;this is NOT assembled ELSE DB $02 ;this will be assembled ENDIF

Multiple conditions may be tested for using the ELSEIF conditional. The syntax for ELSEIF is

IFx <expr or symbol> ;IFx may be IF, IFD or IFND ... ELSEIF <expr> ... ELSEIF <expr> ;optional multiple ELSEIF clause ... ELSE ;optional ELSE clause ... ENDIF

ELSEIF may only appear after an IF and before an ELSE or ENDIF. Multiple "ELSEIF <expr>" statements may appear. Note that <expr> will not be evaluated if a previous IF (or ELSEIF) <expr> evaluates to TRUE. This means that none or exactly one section of code associated with an IF or ELSEIF expressions will be evaluated in any IF/ELSEIF/ELSE/ENDIF conditional block.

Here is an example where two ELSEIF code sections would evaluate true, but only the first will generate code.

K = 2 IF K > 2 ;NOT true ldaa #K ;NOT assembled ELSEIF K = 2 ;IS true ldaa VAR1 ;IS assembled ELSEIF K < 3 ;IS true but NOT assembled as we already matched TRUE ldaa VAR2 ;NOT assembled ELSE ;ignored as we already have a TRUE match ldaa #4 ;NOT assembled ENDIF ;completes this IF block

Nested IFx expressions are possible (refer to the Maximums sections for nesting limits) as the following example shows, but note that complex nested expressions may sometimes be used to obviate the need for nested IF expressions.

IF A = B IF C >= D dw C + D ELSE ;ELSE clause for "IF C >= D" dw D - C ENDIF ;terminates the "IF C >= D" expression ELSE ;ELSE clause for "IF A = B" dw $123 ENDIF ;terminates the "IF A = B" expression

Note also that as an IF expression must be terminated with an ENDIF clause, there is no confusion about what IF expression an ELSE refers to. Indenting can sometimes be used to improve the readability of nested IF expressions but remember the assembler ignores indenting and relies on you getting everything in the correct logical sequence.

data operations

Note that ALIGN <expr> advances the PC by PC % <expr> (ie. the remainder when the PC is divided by <expr>. Some assemblers call this directive EVEN.

ALIGNZ <expr> works like ALIGN but explicitly sets the skipped bytes to zero.

BSZ <expr>

        DB     $12              ;hex byte
        DB     %10001101        ;binary byte
        DB     'C'              ;character ('C) also works
        DB     "text"           ;double quoted text

        DB     10, $ff, %1011001, 'A', "string", 0   ;multiple format too...

errors and warnings

Include Files

Ignored Pseudo-ops

SPC, NAM, NAME & END

Labels & Equates

All lables must start in the first column (otherwise they will be interpreted as a pseudo-op) and may optionally be terminated with one or more colons (ie. :, or ::, etc.) the colon(s) are not considered part of the label.

Local labels begin with the at symbol (@) and are followed by one or more digits, and are used between normal (ie. non-local) labels when it's not convenient to define a unique identifier. Local labels are checked at assembly time to ensure they are not duplicated, and that their scope does not cross a "symbol boundary".

EQU, = =

symbolname   equ   expression
anothername  ==    another+expression

counter    set   25
counter    =     counter+1

listing control

Here's an example of a page from a list file showing the page's header block, and a number of selected lines of the source file (the ... indicates where lines have been removed):

ASHC11, 68HC11 Macro Assembler v1.2 (c) Copyright 2000 Tech Edge Pty. Ltd. page 2 - amxy.a - Fri 1 Sep 2000 10:58:09.45 Re-assembly of AMXY.BIN =005d 112 kProgramID == $5D ;$5D for AMXY 113 114 #include "macs.a" ... 250 KKPGMID ;($c008) Program ID c008 5d 251 db kProgramID ;$5d in AMXY ... d081 86 60 1522 ldaA #$60 ;Read AN6 d083 bd ec d8 1523 call ReadADC ;Read fuel pump voltage

EJECT

LIST & NOLIST

PAGE [<pagelength>] [, <pagewidth>]

The number of lines listed per page is controlled by the pagelength parameter, and the default is to have a single page (ie. no page breaks in the list file). A page length of zero (0) will restore the default of a single page. Alternatively, you can use the pagelength pseudo-op.

The number of character columns on each list page is controlled by the pagewidth parameter. A maximum of 255 columns will be listed in the output. All characters beyond pagewidth will simply be truncated. Note that you can specify the page width independently of the page length by using a null pagelength parameter and a comma (,) before the pagewidth parameter. Alternatively, you can use the pagewidth pseudo-op.

PAGELENGTH <pagelength>
PAGEWIDTH <pagewidth>

SUBTITLE <text>
TITLE <text>

Macros and Repeat Blocks

Here’s a simple parameterless macro definition defined with the MACRO keyword and terminated with the ENDM keyword.

setflag MACRO ;declare macro "setflag" ldab #1 ;set B register to 1 stab flag ;set the variable called flag ENDM

The macro is called "setflag" and is invoked by specifying its name in the opcode field, as follows.

setflag ;invoke macro example called "setflag"

It will produce the code defined in the macro definition’s body (ie. between the MACRO and ENDM pseudo-ops). Specifically the code:

ldab #1 stab flag

will be generated every time the macro "setflag" is used. Note that we could have begun the macro definition as follows (with the macro's name following the MACRO keyword):

MACRO setflag ;also declares macro "setflag"

If the macro is not declared with a label field then the field to the right of "MACRO" is the macro’s name.

Typically a macro will be used with parameters to vary how it is expanded. The macro’s parameters are declared to the right of the MACRO pseudo-op, and if there is more than one parameter then they must be comma separated. An example using two parameter fields, "here" and "value", follows.

setvar MACRO here, value ldab #value ;set B with immediate value "value" stab here ;store B into location "here" ENDM

Each occurrence of "here" and "value" in the macro’s definition will be replaced with the arguments supplied with the macro. This macro is invoked three times below, along with two arguments for each invocation:

setvar loc1, 1 ;set variable "loc1" to immediate value 1 setvar loc2, 2 ;set loc2 to 2 setvar $124, 'X' ;set $124 to ASCII 'X'

The first two invocation of setvar will produce the code:

ldab #1 ;'value' is substituted with parameter '1' stab loc1 ;'here'is substituted with the parameter 'loc1' ldab #2 ;'value' is substituted with parameter '2' stab loc2 ;'here'is substituted with the parameter 'loc2'

Repeat Blocks:
 REPT <count>
 ENDR

Repeat Blocks are used to define sections of code that are to be repeated and/or iterated a number of times. The REPT pseudo-op simply repeats a block of code a certain number of times. Here’s a REPT block that initialises a data area. Defining a REPT block is like defining a macro, but the REPT block is immediately actioned and is not saved for future use.

REPT 10 ;repeat the next code section 10 times db 'A' ;define a single byte 'A' ENDR ;end of REPT block

The above REPT block produces the equivalent of the following code (although the listing would show 10 individual db ‘A’ instructions).

db "AAAAAAAAAA"

Iterated Repeat Blocks:
 IRP <symbol>, <expr> [[, <expr>]..]
 IRPC <symbol>, <string>

    IRPC chr, "JKLMNOP"
        db     'chr'    ;chr will take on the values J, K, L, etc.
    ENDR

More complex code structures are possible by combining REPT or IRPx with one or more macros. Here’s an example that uses IRPC to set up a data area invocation (see example file "x4") First we define a macro, then a repeat block using that macro:

defchar MACRO chr Lchr db 'chr' ;define a label and a data byte ENDM IRPC _ch, <ABCD> defchar _ch ENDR

This IRPC will iterate four times for each character of the string "ABCD" and will generate the four lines:

defchar A defchar B defchar C defchar D

and the macro will be expanded to produce the following code defining four labels and four data bytes:

LA db 'A' ;Label LA for data byte "A" LB db 'B' ;etc.. LC db 'C' LD db 'D'

Macro Support:
 EXITIF <expr>
 LOCAL <name> [[,<name>] ..]

The local pseudo-op defines local lables that have a scope only within the current macro or repeat block.

segment control

Note that bss selects the same segment as data (some compilers use this name) and the auto segment is the fourth independent segment, and you can use this any way you like.

Disclaimer, Bugs, Limitations, Enhancements

Tech Edge does not warrant ASHC11 for any use what so ever. You use ASHC11 at your own risk.

Bugs

Limitations

  ASHC11  Mnemonics           Motorola's     Function Performed
  call                           JSR         Call
  callr                          BSR         Call Relative (short call)
  cmpD, cmpX cmpY                CP?         Compare (16 bit register)
  decX, decY, decS               DE?         Decrement (16 bit register)
  di                             SEI         Disable Interrupts
  ei                             CLI         Enable Interrupts
  incX, incY, incS               IN?         Increment (16 bit register)
  jr                             BRA         Jump Relative (short jump)
  push, pushB, pushX, pushY      PSH?        Push on to stack
  popA, popB, popX, popY         PUL?        Pop off stack
  ret                            RTS         Return (from subroutine)
  reti                           RTI         Return From Interrupt
  xorA, xorB                     EOR?        eXclusive Or