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
- The file must be type
SYS($FF) and no larger than 30,720 bytes. It is loaded at$2000and entered there.
- A SYSTEM file loads flat from
$2000, so its real size ceiling is the first thing it allocates above itself, not a number anyone chose. Put the MLI's 1 KB buffers at the bottom of free memory and every build is capped at that address.LS.SYSTEMputs them at$9800and its other buffers above them, so it may grow to 30,720 bytes, the limitbyeenforces anyway; a program is also free to put them higher still.
- The program must QUIT. One that never quits, or reboots the machine
to leave, ends the session: the saved banks survive a reset, but nothing yet
restores from them, so a program that never quits costs a reboot. Save in
vibefore you runmake test. This page describes that failure and does not stage it; the gate that produced the sessions below does not run a program that never quits.
- QUIT carries no exit status. A ProDOS program cannot say whether it worked, so it leaves the answer in a file, and maux checks the file with ordinary tools when it is back. That is the whole idea of the lesson.
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/mkwanttouch WANT
ls | tr a-z A-Z > WANT
examples/lssys/check — on the disk as /usr/src/examples/LSSYS/checksort 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.
- Names are upper case in ProDOS. The program lists what ProDOS
stores,
MAKEFILE;lsprints the case maux recorded,Makefile. Somkwantpipeslsthroughtr a-z A-Z. - The directory is in the order ProDOS keeps it and
lssorts. Sochecksorts both files before it compares them. The program has no need to sort. - The program writes maux's text encoding. maux writes high-bit
text ending each line with
$8D; a ProDOS program would normally write low ASCII and$0D. Tools such assorthand back the encoding they were given, so a low-ASCIIGOTwould still differ fromWANTafter sorting.LS.SYSTEMwrites the names with the high bit set and ends each with$8D, so the two files are the same bytes. Its screen output is the opposite case: the ROM'sCOUTwants the high bit set, and the program ORs it in.
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?