maux
Star on GitHub Buy me a coffee

L7. A ProDOS 8 program, built on maux, tested with bye

Learn / L7

Goal: edit in vi, assemble with nas, link with ld, drive it with make — all under maux — then run the result on a real ProDOS 8 and come back to the editor and the shell exactly where they were.

What you need

L2 (nas and ld) and L5 (a Makefile). You should also be comfortable with a hex number.

What bye does

bye suspends maux, gives the whole machine to a real ProDOS 8, and takes it back when the program that ran there quits. Main memory and the auxiliary bank are saved into RamWorks banks that ProDOS cannot see and restored afterwards; every other process stays in its own bank, untouched. The shell, the editor and everything else resume where they were.

The program you name is launched the way a program selector launches one. ProDOS's own QUIT call takes no pathname, so the selector's job, and bye's, is to store the system program's name at $280, close the open files, clear the bit map, protect the zero page, stack, text page and ProDOS global page, read the file into $2000 and jump to it. What your program finds is an ordinary freshly booted ProDOS 8: main memory, the language card and /RAM (present and empty) all its own, every open file closed, and the prefix set to the directory the file was launched from.

The limits, before you build anything

Step one: a program that says hello to ProDOS

The smallest tenant (the name for a program that runs under bye). It prints a line with the monitor ROM's character routine, writes a six-byte file named RESULT through the real MLI at $BF00, and QUITs. It is the shape of src/test/byetenant.s, which the gate for bye itself uses and whose header calls itself the worked example of what a tenant is owed.

examples/hellosys/hello.s — on the disk as /usr/src/examples/HELLOSYS/hello.s
*---------------------------------------------------------------
* hello.s -- HELLO.SYSTEM, a ProDOS 8 program built on maux.
*
*   nas -o hello.o hello.s
*   ld -t FF -a 2000 -o HELLO.SYSTEM hello.o
*   bye HELLO.SYSTEM
*
* This knows nothing of maux. It calls the real ProDOS MLI at
* $BF00 and the monitor ROM's COUT, and runs on any ProDOS 8
* machine; `bye` suspends maux, runs it on a freshly booted
* ProDOS, and brings maux back when it QUITs. It writes a file,
* RESULT, so you can check from maux that it really ran.
*
* A SYSTEM file loads flat at $2000, so everything the program
* allocates above itself is its size limit. The MLI's 1 KB
* io_buffer goes at $9000, high and out of the way.
*
* Pathnames in raw MLI calls are plain 7-bit ASCII (single
* quotes). COUT wants the high bit set, so the message is stored
* as plain ASCII and the loop ORs HIBIT in as it prints.
*
* This file is staged on the release disk as MAUX TEXT (high
* bit set, lines ended by $8D), exactly what `vi` writes. nas
* reads that or ProDOS-standard text (low ASCII, $0D) alike, so
* edit it with `vi` and run `nas` on it: nothing to convert.
*---------------------------------------------------------------
            rel
            lst   off
TMLI        equ   $BF00
COUT        equ   $FDED
IOBUF       equ   $9000
STACKTOP    equ   $FF
HIBIT       equ   $80

START       ldx   #STACKTOP
            txs
            cld
            ldy   #0
:say        lda   MSG,y
            beq   :said
            ora   #HIBIT
            jsr   COUT
            iny
            bne   :say
:said       jsr   TMLI
            dfb   $C0              ;CREATE (fails if it exists)
            da    CRPARM
            jsr   TMLI
            dfb   $C8              ;OPEN
            da    OPPARM
            lda   OPREF
            sta   WRREF
            sta   CLREF
            jsr   TMLI
            dfb   $CB              ;WRITE
            da    WRPARM
            jsr   TMLI
            dfb   $CC              ;CLOSE
            da    CLPARM
            jsr   TMLI
            dfb   $65              ;QUIT: maux comes back
            da    QUPARM

CRPARM      dfb   7
            da    PATH
            dfb   $C3
            dfb   $04
            da    0
            dfb   1
            da    0
            da    0
OPPARM      dfb   3
            da    PATH
            da    IOBUF
OPREF       dfb   0
WRPARM      dfb   4
WRREF       dfb   0
            da    DATA
            da    6
            da    0
CLPARM      dfb   1
CLREF       dfb   0
QUPARM      dfb   4
            dfb   0
            da    0
            dfb   0
            da    0

PATH        dfb   12
            asc   '/MAUX/RESULT'
DATA        asc   'HELLO',0D
MSG         asc   'HELLO FROM PRODOS',0D,00
examples/hellosys/Makefile — on the disk as /usr/src/examples/HELLOSYS/Makefile
# make finds nas, ld and rm on PATH, as `sh -c` would (they live in /bin).
HELLO.SYSTEM: hello.o
	ld -t FF -a 2000 -o HELLO.SYSTEM hello.o
hello.o: hello.s
	nas -o hello.o hello.s
clean:
	rm -f HELLO.SYSTEM hello.o /mnt/MAUX/RESULT

Step two: LS.SYSTEM

A real program: it lists the directory it was launched from, by opening the directory as a file and reading its blocks, writes the same names to a file GOT, shows them on the screen, waits for a key and QUITs.

examples/lssys/ls.s — on the disk as /usr/src/examples/LSSYS/ls.s
*---------------------------------------------------------------
* ls.s -- LS.SYSTEM, a ProDOS 8 program built on maux.
*
*   nas -o ls.o ls.s
*   ld -t FF -a 2000 -o LS.SYSTEM ls.o
*   bye LS.SYSTEM
*
* This knows nothing of maux. It calls the real ProDOS MLI at
* $BF00 and the monitor ROM's COUT, and runs on any ProDOS 8
* machine, with or without maux under it.
*
* It finds its prefix directory (GET_PREFIX), opens it like a
* file and READs it a block at a time. The first block's header
* says how long an entry is ($23) and how many fit in a block
* ($24); the entries follow a 4-byte block header. The high
* nibble of an entry's first byte is its storage type and the
* low nibble the name length; the name follows. Storage type 0
* is a deleted entry, $E and $F are directory headers, anything
* else is a file or a subdirectory.
*
* It collects the names, writes them to a file GOT, prints them
* on the screen (after clearing it with the monitor's HOME),
* waits for a key and QUITs, which brings maux back. Any MLI
* error prints a short message and QUITs: no reference number
* of 0 ever reaches READ or CLOSE (CLOSE 0 closes every file).
*
* GOT is written the way maux writes text (high bit set, each
* line ended by $8D), so maux's own tools compare it with no
* conversion. The names are the ones ProDOS stores: upper case.
* GOT is created only after the directory has been read, so it
* does not list itself.
*
* A SYSTEM file loads flat at $2000, so everything the program
* allocates above itself is its size limit. The MLI's two 1 KB
* io_buffers start at $9800 and the other buffers sit above
* them, below the ProDOS global page at $BF00, so the image may
* grow to 30,720 bytes, which is also the limit bye enforces.
*
* Pathnames in raw MLI calls are plain 7-bit ASCII (single
* quotes). COUT wants the high bit set, so the program ORs
* HIBIT in as it copies each name.
*
* This file is staged on the release disk as MAUX TEXT (high
* bit set, lines ended by $8D), exactly what `vi` writes. nas
* reads that or ProDOS-standard text (low ASCII, $0D) alike.
*---------------------------------------------------------------
            rel
            lst   off
            xc                     ;enable the 65C02 (bra)
TMLI        equ   $BF00
COUT        equ   $FDED
HOME        equ   $FC58
KBD         equ   $C000
KBDSTRB     equ   $C010
STACKTOP    equ   $FF
HIBIT       equ   $80
CR          equ   $8D
SLASH       equ   $2F
EOFERR      equ   $4C              ;end of data: not an error
DUPERR      equ   $47              ;CREATE of a name that exists
TYPEMASK    equ   $F0
LENMASK     equ   $0F
HDRTYPE     equ   $E0              ;$E0 and $F0 are headers
IOBUF1      equ   $9800            ;io_buffer, 1 KB, aligned
IOBUF2      equ   $9C00
DIRBUF      equ   $A000            ;one directory block
ENTRIES     equ   $A004            ;DIRBUF + 4
HDRLEN      equ   $A023            ;DIRBUF+$23 entry_length
HDRPER      equ   $A024            ;DIRBUF+$24 entries_per
NAMES       equ   $A200            ;collected names
LIMITHI     equ   $BA              ;stop collecting at $BA00
TMPNAME     equ   $BB00
PREFIX      equ   $BC00
ENT         equ   $06              ;zero page, free for programs
COUNT       equ   $08
NLEN        equ   $09
LEN2        equ   $0A
OUT         equ   $0B
ELEN        equ   $0D
PERBLK      equ   $0E

START       ldx   #STACKTOP
            txs
            cld
            jsr   HOME             ;clear the screen
            bit   KBDSTRB          ;drop any key already down
            lda   #<NAMES
            sta   OUT
            lda   #>NAMES
            sta   OUT+1
            jsr   TMLI
            dfb   $C7              ;GET_PREFIX
            da    GPPARM
            bcs   ERR
            ldx   PREFIX           ;length
            lda   PREFIX,x         ;last character
            cmp   #SLASH
            bne   :open
            dec   PREFIX           ;OPEN wants no trailing slash
:open       jsr   TMLI
            dfb   $C8              ;OPEN the prefix directory
            da    OPDPARM
            bcs   ERR
            lda   OPDREF
            sta   RDREF
            sta   CLDREF
            jsr   TMLI
            dfb   $CA              ;READ the first block
            da    RDPARM
            bcs   ERR
            lda   HDRLEN           ;sizes come from the header
            sta   ELEN
            lda   HDRPER
            sta   PERBLK
:walk       jsr   WALK
            jsr   TMLI
            dfb   $CA              ;READ the next block
            da    RDPARM
            bcc   :walk
            cmp   #EOFERR
            bne   ERR              ;a real error
            jsr   TMLI
            dfb   $CC              ;CLOSE the directory
            da    CLDPARM
            bcs   ERR
            bra   MAKEGOT

*---------------------------------------------------------------
* ERR -- an MLI call failed: say so, wait for a key, QUIT.
*---------------------------------------------------------------
ERR         ldx   #0
:say        lda   ERRTXT,x
            beq   :said
            phx
            jsr   COUT
            plx
            inx
            bra   :say
:said       jsr   KEY
QUIT        jsr   TMLI
            dfb   $65              ;QUIT: maux comes back
            da    QUPARM

KEY         lda   KBD              ;wait for a key
            bpl   KEY
            bit   KBDSTRB
            rts

MAKEGOT     jsr   TMLI
            dfb   $C0              ;CREATE GOT
            da    CRPARM
            bcc   :made
            cmp   #DUPERR          ;it may already be there
            bne   ERR
:made       jsr   TMLI
            dfb   $C8              ;OPEN GOT
            da    OPGPARM
            bcs   ERR
            lda   OPGREF
            sta   WRREF
            sta   EOFREF
            sta   CLGREF
            sec
            lda   OUT
            sbc   #<NAMES
            sta   WRREQ
            sta   EOFLO
            lda   OUT+1
            sbc   #>NAMES
            sta   WRREQ+1
            sta   EOFLO+1
            jsr   TMLI
            dfb   $CB              ;WRITE the names
            da    WRPARM
            bcs   ERR
            jsr   TMLI
            dfb   $D0              ;SET_EOF (old GOT)
            da    EOFPARM
            bcs   ERR
            jsr   TMLI
            dfb   $CC              ;CLOSE GOT
            da    CLGPARM
            bcs   ERR
            jsr   SHOW
            jsr   KEY
            bra   QUIT

*---------------------------------------------------------------
* WALK -- the entries of the block just read: append each live
* name, high bit set and CR-ended, at OUT.
*---------------------------------------------------------------
WALK        lda   #<ENTRIES
            sta   ENT
            lda   #>ENTRIES
            sta   ENT+1
            lda   PERBLK
            sta   COUNT
:entry      ldy   #0
            lda   (ENT),y
            and   #LENMASK
            sta   NLEN
            lda   (ENT),y
            and   #TYPEMASK
            beq   :next            ;storage type 0: deleted
            cmp   #HDRTYPE
            bcs   :next            ;a directory header
            lda   OUT+1
            cmp   #LIMITHI
            bcs   :next            ;buffer full: drop the name
            ldy   #0
:copy       iny
            lda   (ENT),y
            ora   #HIBIT
            sta   TMPNAME-1,y
            cpy   NLEN
            bne   :copy
            lda   #CR
            sta   TMPNAME,y
            iny
            sty   LEN2
            ldy   #0
:move       lda   TMPNAME,y
            sta   (OUT),y
            iny
            cpy   LEN2
            bne   :move
            tya
            clc
            adc   OUT
            sta   OUT
            bcc   :next
            inc   OUT+1
:next       clc
            lda   ENT
            adc   ELEN
            sta   ENT
            bcc   :more
            inc   ENT+1
:more       dec   COUNT
            bne   :entry
            rts

*---------------------------------------------------------------
* SHOW -- print the collected names through the monitor ROM.
*---------------------------------------------------------------
SHOW        lda   #<NAMES
            sta   ENT
            lda   #>NAMES
            sta   ENT+1
:again      lda   ENT
            cmp   OUT
            bne   :more
            lda   ENT+1
            cmp   OUT+1
            beq   :end
:more       ldy   #0
            lda   (ENT),y
            jsr   COUT
            inc   ENT
            bne   :again
            inc   ENT+1
            bra   :again
:end        rts

ERRTXT      asc   "MLI ERROR",8D,00
GPPARM      dfb   1
            da    PREFIX
OPDPARM     dfb   3
            da    PREFIX
            da    IOBUF1
OPDREF      dfb   0
RDPARM      dfb   4
RDREF       dfb   0
            da    DIRBUF
            da    512
            da    0
CLDPARM     dfb   1
CLDREF      dfb   0
CRPARM      dfb   7
            da    GOTNAME
            dfb   $C3
            dfb   $04
            da    0
            dfb   1
            da    0
            da    0
OPGPARM     dfb   3
            da    GOTNAME
            da    IOBUF2
OPGREF      dfb   0
WRPARM      dfb   4
WRREF       dfb   0
            da    NAMES
WRREQ       da    0
            da    0
EOFPARM     dfb   2
EOFREF      dfb   0
EOFLO       da    0
            dfb   0
CLGPARM     dfb   1
CLGREF      dfb   0
QUPARM      dfb   4
            dfb   0
            da    0
            dfb   0
            da    0

GOTNAME     dfb   3
            asc   'GOT'

The Makefile is the test harness

The test rule is the harness. A recipe has no shell, so the two steps that need a redirection or a pipe are scripts, run with sh.

examples/lssys/Makefile — on the disk as /usr/src/examples/LSSYS/Makefile
# make finds nas, ld and rm on PATH, as `sh -c` would (they live in /bin).
LS.SYSTEM: ls.o
	ld -t FF -a 2000 -o LS.SYSTEM ls.o
ls.o: ls.s
	nas -o ls.o ls.s
test: LS.SYSTEM
	rm -f GOT
	sh mkwant
	bye LS.SYSTEM
	sh check
clean:
	rm -f LS.SYSTEM ls.o GOT WANT
examples/lssys/mkwant — on the disk as /usr/src/examples/LSSYS/mkwant
touch WANT
ls | tr a-z A-Z > WANT
examples/lssys/check — on the disk as /usr/src/examples/LSSYS/check
sort GOT > GOT.S
sort WANT > WANT.S
cmp GOT.S WANT.S
st=$?
rm GOT.S WANT.S
exit $st

The session

The indented lines under ProDOS is running the program are the screen ProDOS drew, read by the gate while the program ran: once maux is back the console repaints and the program's screen is gone. The gate presses a key to let LS.SYSTEM quit, and then make goes on to the last recipe line, sh check, which prints nothing because cmp found no difference. Then the session breaks the test on purpose: one more line in mkwant makes WANT name a file ProDOS never listed, and make test must fail, with make: command failed and a non-zero status. A test that cannot fail is not a test; check ends with exit $st so that cmp's verdict is the script's, not rm's.

$ mkdir /tmp/l7a
$ cd /tmp/l7a
$ cp /usr/src/examples/HELLOSYS/* .
$ make
nas -o hello.o hello.s
nas: 131 bytes -> hello.o
ld -t FF -a 2000 -o HELLO.SYSTEM hello.o
$ rm -f /mnt/MAUX/RESULT
$ bye HELLO.SYSTEM
Leaving maux for ProDOS...
[ ProDOS is running the program. Its screen: ]
  HELLO FROM PRODOS
Welcome back.
$ cat /mnt/MAUX/RESULT
HELLO
$ mkdir /tmp/l7
$ cd /tmp/l7
$ cp /usr/src/examples/LSSYS/* .
$ ls
check     ls.s      Makefile  mkwant
$ make
nas -o ls.o ls.s
nas: 423 bytes -> ls.o
ld -t FF -a 2000 -o LS.SYSTEM ls.o
$ ls -l LS.SYSTEM
SYS       1b -                LS.SYSTEM
$ make test
rm -f GOT
sh mkwant
bye LS.SYSTEM
Leaving maux for ProDOS...
[ ProDOS is running the program. Its screen: ]
  CHECK
  LS.S
  MAKEFILE
  MKWANT
  LS.O
  LS.SYSTEM
  WANT
[ a key is pressed ]
Welcome back.
sh check
$ echo $?
0
$ cat GOT
CHECK
LS.S
MAKEFILE
MKWANT
LS.O
LS.SYSTEM
WANT
$ cat WANT
CHECK
LS.O
LS.S
LS.SYSTEM
MAKEFILE
MKWANT
WANT
$ echo 'echo ZZZ >> WANT' >> mkwant
$ make test
rm -f GOT
sh mkwant
bye LS.SYSTEM
Leaving maux for ProDOS...
[ ProDOS is running the program. Its screen: ]
  CHECK
  LS.S
  MAKEFILE
  MKWANT
  LS.O
  LS.SYSTEM
  WANT
[ a key is pressed ]
Welcome back.
sh check
cmp: EOF on GOT.S
make: command failed
$ echo $?
1
[ the same LS.SYSTEM, copied onto a stock ProDOS 2.4 disk with no maux, boots and shows: ]
  ALPHA
  BETA
  LS.SYSTEM
  PRODOS
  SUB
[ a key is pressed, it QUITs, and the GOT it wrote holds the same names ]

What just happened

Three things had to line up for cmp to say nothing, and each is a fact about the machine rather than about this program.

That is also why the pathname in a raw MLI call is plain 7-bit ASCII in single quotes: a byte with the high bit set is not a legal pathname character to ProDOS. maux's own file names, and the text it writes, have the bit set; the MLI wants it clear. A first-time reader meets this once and should expect it.

GOT is created after the directory has been read, so it does not list itself; WANT is created by touch before ls runs, so it is in both lists. Without those two details the files would differ by one name, and the harness would be red for a reason that has nothing to do with the program.

Shipping it

The finished LS.SYSTEM is an ordinary ProDOS file. It calls only the MLI and the monitor ROM, so it needs nothing from maux, and nulib2 -a can archive it for transfer to another machine. The gate checks that claim rather than asserting it: after the lesson it copies the LS.SYSTEM that was built on maux onto a stock ProDOS 2.4 disk, with no maux on it, boots that disk on the emulator, and requires the program to list the disk's files, write its GOT and QUIT. The last lines of the session above are that run.

Watch it

Watch the whole thing happen: the build, the farewell, the 40-column screen the tenant actually gets, and the shell coming back where it was left.

Try next

Make LS.SYSTEM list only the files whose names end in .S, and change mkwant to match. Which side of the test do you change first?

← Hello, world in PLASMA | All lessons