I am writing this so one of the 6809 experts who reads this can chime in and tell me a better way…

Often I post things so they can get in the search engines in case anyone else looks for that topic later. This is one of those.

Using DEF USR is a great way to put up to ten “easy to execute” routines in an assembly language program. Each of those routines can also do different things based on the numeric (or string) parameter passed in to the USR() call.

If you aren’t trying to be that fancy, but do want multiple functions for whatever reason, what methods are there? Please leave a comment with the best ways to call multiple functions using EXEC from Color BASIC.

Dispatch table

One method that comes to mind is using a dispatch table at the start of the machine language program. If the code is built to compile at &H3F00, then doing an EXEC &H3F00 will run that program. If there are more functions, you have to figure out where they are located and provide those address to the user. This is fine, until you make a change to the code and then those locations shift.

Instead, the start of the program could begin with a series of “branch always” instructions. For example:

            org     $7f00

start1      bra     install
start2      bra     uninstall

The branch always instruction is one byte, and it is followed by a second byte which is how many bytes away the function is. This makes each entry take two bytes. Thus, install is at &H7F00 and uninstall is at &H7F02. A whole series of functions could be done this way, and the user just has to remember which is which — &H7F00, &H7F02, &H7F04, etc. Having every two bytes be an entry makes it easy to remember.

; lwasm dispatch.asm -fbasic -odispatch.bas --map
; a09 -fbasic -odispatch.bas dispatch.asm

ORGADDR     equ     $3f00       ; Where program loads in memory

            org     ORGADDR

;------------------------------------------------------------------------------
; Absolute addresses of ROM calls
;------------------------------------------------------------------------------
CHROUT      equ	    $A002

;------------------------------------------------------------------------------
; This code can be called by EXEC/EXEC xxxx.
;------------------------------------------------------------------------------
; Dispatch table at the start of the program.
start1      bra     install
start2      bra     uninstall

install     leax    <msginst,pcr    ; X points to message
            bra     print           ; print will do the RTS
            ;rts

uninstall   leax    <msguninst,pcr  ; X points to message
            ;bra     print          ; print will do the RTS
            ;rts

;------------------------------------------------------------------------------
; PRINT subroutine. Prints the 0-terminated string pointed to by X plus CR
;------------------------------------------------------------------------------
print       lda     ,x+
            beq     printdone
            jsr     [CHROUT]
            bra     print
printdone   lda     #13
            jmp     [CHROUT]        ; JMP CHROUT will do an rts.
            ;rts

;------------------------------------------------------------------------------
; Data storage for the string messages
;------------------------------------------------------------------------------
msginst     fcc     "INSTALLED"
            fcb     0

msguninst   fcc     "UNINSTALLED"
            fcb     0

            end

One potential issue is that branch can only jump so far. If large functions are being called, you might find they cannot be reached from this dispatch table. One option would be to switch to “long branch”, but then you add more bytes and your dispatch table might be every three bytes – &H7F00, &H7F03, &H7F06, &H7F09, &H7F0C, etc.

That is a fine solution though every 2 may “look” nicer than every 3.

As a workaround, the dispatch table could remain short branches, but they go to a longer one just below it:

            org     $7f00

start1      bra     install
start2      bra     uninstall

; If a short branch cannot reach, it can call a second long branch:
uninstall   lbra    realuninstall

Above, perhaps “install” is within reach of the “bra”, but “uninstall” is too far away. Simply make the “bra uninstall” branch to a spot with a long branch. A few more bytes, a few more clock cycles, but now the dispatch table can remain “every 2 bytes”.

But there has to be a better way…

Leave your suggestions in the comments.

Until next time…

Bonus

Here is a BASIC loader for that example. RUN it, then EXEC &H7F00 or &H7F02 and be amazed. (Loader generated using Sean Conner’s a09 assembler.)

10 DATA32,2,32,5,48,140,21,32,3,48,140,26,166,128,39,6,173,159,160,2,32,246,134,13,110,159,160,2,73,78,83,84,65,76,76,69,68,0,85,78,73,78,83,84,65,76,76,69,68,0
20 CLEAR200,16127:FORA=16128TO16177:READB:POKEA,B:NEXT: