Don't worry. The new version of as11n is completely backwards compatible with the previous version. If you don't wish to use the new features, read no further. The improved version will work just like the old one.

However, the new features are meant to be useful and "to make your life easier" (by avoiding cutting and pasting). Read on if you are interested.

Glad you asked. Up until now, when you wanted to re-use subroutines from previous labs, you had to cut and paste the source code from one file to another. You also had to be very careful that you copied auxiliary details (such as EQU or FCB statements that the subroutine(s) needed. You also had to ensure that you had not done too much cutting and pasting; otherwise, you would get Symbol Redefined error messages. Finally, if you discovered a bug in a subroutine and fixed it, the improved subroutine would not magically become the one used in all previous code where you had pasted in the buggy version.

The extra features in as11n address of these problems.

Sure. Suppose that in Lab 2 you had to write a program that displayed "Hello world!\n" on the terminal (i.e. the workstation window where you invoke vt6811 lab2.s19.)

You might write a program like:

        org $6000
        ldx #hello
        jsr putstr
        swi

hello   fcc 'Hello World!'
        fcb NEWLINE, 0
        
NEWLINE equ 10
putchar equ  $E3E1 

putstr: 
        ldaa 0,x
        beq pstG_done
        jsr putchar
        inx
        bra putstr
pstG_done:
        rts

Simple. Assuming you wish to use the putstr subroutine in other projects, put it in a library. Call the library something like mylib.asm and put all the instructions and directives pertaining to it in that file. Thus, the file mylib.asm could be:

NEWLINE equ 10
putchar equ  $E3E1 

putstr: 
        ldaa 0,x
        beq pstG_done
        jsr putchar
        inx
        bra putstr
pstG_done:
        rts

You can now write your original program as follows:

        org $6000
        ldx #hello
        jsr putstr
        swi

hello   fcc 'Hello World!'
        fcb NEWLINE, 0

#include "mylib.asm"

And, of course, you can put #include "mylib.asm" into any other programs you write. If you later discover a bug in one of the subroutines in mylib.asm, fix it in the library source code and re-assemble any source code that included the library; everything will be brought up-to-date (no need to cut and paste the corrected version...)

It can be that simple. The most important rule to remember is that the library source code file(s) (such as mylib.asm in the previous example) must not not contain any ORG directives.

Alas, there can be problems, especially if you have more than one library. The problems arise because of:

1. Symbolic constants (usually defined with EQU statements) are used by more than one main program or library.
2. Global variables (eg. regions of memory set aside with directives like RMB 5 that are meant to be readable and writable from anywhere within the program)

If you need the same symbolic constants in more than one library wrote the EQU statements into both libraries, an assembler error ("redefinition error") would occur if both libraries were included in one program. To avoid this problem, isolate the EQU statements into a separate file and protect against multiple inclusions with the commonly-used pattern:

#ifndef FOO
#define FOO
....;put the real stuff here
#endif

For example, I use a file called PinkBook.h that defines commonly used constants that are derived from the 6811 reference manual. The file looks like:

#ifndef PINK_BOOK_H
#define PINK_BOOK_H

REG_BAS          equ $1000             ;Standard base address for I/O regs.

TMSK2            equ $24               ;TMSK2 register number
TMSK2_OFF        equ TMSK2             ;TMSK2 register offset
TMSK2_ABS        equ REG_BAS+TMSK2_OFF ;TMSK2 absolute address
;....etc....

#endif

There is no problem if the global variable is read-only. Simply define it in one (but only one) of the libraries that use it.

Things can get trickier, however, with global variables that can be modified (i.e. that must be placed in RAM.) Ideally, all the code in a library .asm should be ROMable. If you wish to maintain this ideal, the statements that set aside RAM (such as RMB directives should not be placed in the .asm file, but in the .h file and this file should be included in the part of the your main program that is designed for RAM (i.e. with an appropriate ORG directive.

Fortunately, you do not have to do this in the course.

Note first that you can use angle braces to include a file instead of quotations. In this case, you include files written by someone else for the system. Currently, there are three such files: stdlib.asm>, PinkBook.h and buffalo.h.

You can copy the following test program from ~courses/ele538/labs/examples/testStdlib.asm:

	org $6000
        ldx #myMenu
        ldaa #MENU_N_CHOICES
        jsr doMenu
	ldx #yourChoice
	jsr putstr
	adda #'0
	jsr putchar
	ldx #ycEnd
	jsr putstr
        swi

MENU_N_CHOICES equ 2
myMenu  fcc "    Choose one of the following     "
        fcb NEWLINE
        fcc "  1: Test foo"
        fcb NEWLINE
        fcc "  2: Test bar"     
        fcb NEWLINE
        fcb 0

yourChoice     fcc "You chose menu item "
	       fcb 0
ycEnd	       fcc "."
	       fcb NEWLINE
	       fcb 0
		
#include 

Assemble it with: as11n testStdlib.asm. You can look at what the program looks like after the library has been included in the file testStdlib.asmCPP and, of course, you can load it into the 6811 and try it out. If you look at the library, you may well discover several subroutines that you might want to use.