maux
Star on GitHub Buy me a coffee

A ProDOS 8 program, built on maux

Watch / lssys

maux builds an ordinary ProDOS 8 system program and then gets out of its way. nas assembles it, ld links it at $2000, ls -l says SYS, and make test hands the whole machine over: ProDOS 8 loads the program, the program lists the directory it is sitting in and waits for a key, and QUIT brings back the shell that was waiting all along.

What it types

Everything it types, in order. A line starting with $ is a command at the shell, RET included; keys lines are single keystrokes to a program (RET, ESC and the control keys are named).

$ cd /tmp
$ mkdir lssys; cd lssys
$ cp /usr/src/examples/LSSYS/* .
$ ls
$ cat Makefile
$ make
$ ls -l LS.SYSTEM
$ echo $?
$ sort GOT
$ cat WANT

Between steps it presses ^L to clear the screen.

What the captions say

  1. A ProDOS 8 program, written and built on maux.
  2. The Makefile is the test harness.
  3. `test` builds it, runs it under ProDOS, then compares.
  4. nas assembles, ld links a SYS file at $2000.
  5. SYS. ProDOS 8 loads it flat at $2000 and jumps there.
  6. Now maux gets out of the way.
  7. GOT is what ProDOS wrote. WANT is what maux's ls says.

The program knows nothing of maux

LS.SYSTEM calls the ProDOS MLI at $BF00 and the monitor ROM's COUT, and nothing else. It finds its own prefix, opens the directory like a file, reads it a block at a time, and walks the entries: the high nibble of an entry's first byte is its storage type and the low nibble its name length. That is the ProDOS 8 of 1983, not a maux API, so the same file runs on a stock ProDOS 2.4 disk with no maux on it anywhere — which is how it is also tested.

It writes the names it found to a file called GOT, in maux's own text convention: high bit set, each line ended by $8D. So maux's tools read what ProDOS wrote with no conversion step in between. GOT is created only after the directory has been read, so it never lists itself.

One screen, two owners

Watch the picture change shape when the farewell prints. maux runs the console at 80 columns; bye puts the machine back the way a ProDOS program expects to find it — text mode, page 1, no 80STORE, 40 columns, and the display handed back to the motherboard — because a program written in 1983 is entitled to assume all of that. The 40-column screen in the middle of this film is not a rendering choice. It is the machine the tenant actually gets.

That is also why this is the one film here with a single display. Every other demo is filmed twice, on the IIe's own 80 columns and on a Videx UltraTerm. During the handover the card is not the selected display at all, so a card film would freeze on the farewell for the whole of the interesting part.

The Makefile is the test

The lesson's test rule is four lines: delete GOT, run mkwant (which is just ls | tr a-z A-Z > WANT, maux's own listing), bye LS.SYSTEM, and run check, which sorts both files and cmps them. Two programs that share no code, on two operating systems, list the same directory and are made to agree about it. The exit status of make is the verdict.

The gate that proves it

This film is made by site/demos/lssys.py. Run as assertions, the same file is make check-demo-lssys, and it runs with the rest of the tests. It requires that the copied directory holds the lesson's own files, in the order ls prints them; that the Makefile on screen is the lesson's, line for line, tabs included; that make prints the nas command, nas's report and the ld command, in that order, and nothing else; that ls -l calls the result SYS; that the names ProDOS printed appear on the 40-column page while the tenant owns the machine; that the rows of make test come back in order, ending in sh check, with an exit status of 0; that GOT and WANT each hold exactly the expected names; and that the host, reading the disk the machine wrote, finds GOT to be maux text — every byte with its high bit set, every line ended by $8D.

Lesson L7 under Learn walks through the same program with the source and the ProDOS directory format explained a line at a time, and links back to this film.

Transcript

The screen at every checkpoint the test checks, as the recorder saved it:

== mkdir prints nothing (t=9.8 s)
$ cd /tmp
$ mkdir lssys; cd lssys
$

== cp prints nothing (t=17.6 s)
$ cd /tmp
$ mkdir lssys; cd lssys
$ cp /usr/src/examples/LSSYS/* .
$

== ls (t=19.1 s)
$ cd /tmp
$ mkdir lssys; cd lssys
$ cp /usr/src/examples/LSSYS/* .
$ ls
check     ls.s      Makefile  mkwant
$

== the copy holds the lesson files: check ls.s Makefile mkwant (t=19.1 s)
$ cd /tmp
$ mkdir lssys; cd lssys
$ cp /usr/src/examples/LSSYS/* .
$ ls
check     ls.s      Makefile  mkwant
$

== the Makefile is the lesson's (TAB = 8 columns) (t=25.5 s)
$ cat 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
$

== make runs nas then ld (t=43.9 s)
$ make
nas -o ls.o ls.s
nas: 423 bytes -> ls.o
ld -t FF -a 2000 -o LS.SYSTEM ls.o
$

== make echoes the nas line, nas reports, then the ld line (t=43.9 s)
$ 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 (t=46.9 s)
$ 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
$

== ls -l says SYS: ProDOS 8 will boot it ('SYS       1b -                LS.SYSTEM') (t=46.9 s)
$ 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 (tenant window) (t=64.3 s)
CHECK
LS.S
MAKEFILE
MKWANT
LS.O
LS.SYSTEM
WANT

== ProDOS listed the directory: CHECK LS.O LS.S LS.SYSTEM MAKEFILE MKWANT WANT (t=73.7 s)
$ make test
rm -f GOT
sh mkwant
bye LS.SYSTEM
Leaving maux for ProDOS...
Welcome back.
sh check
$

== make test: out to ProDOS and back (t=74.0 s)
$ make test
rm -f GOT
sh mkwant
bye LS.SYSTEM
Leaving maux for ProDOS...
Welcome back.
sh check
$

== make test succeeded (t=75.6 s)
$ make test
rm -f GOT
sh mkwant
bye LS.SYSTEM
Leaving maux for ProDOS...
Welcome back.
sh check
$ echo $?
0
$

== GOT holds exactly the names (t=82.6 s)
$ sort GOT
CHECK
LS.O
LS.S
LS.SYSTEM
MAKEFILE
MKWANT
WANT
$

== WANT holds exactly the same names (t=84.7 s)
$ sort GOT
CHECK
LS.O
LS.S
LS.SYSTEM
MAKEFILE
MKWANT
WANT
$ cat WANT
CHECK
LS.O
LS.S
LS.SYSTEM
MAKEFILE
MKWANT
WANT
$

== on the disk, GOT is maux text (high bit, $8D lines) and holds the 7 names (t=84.7 s)
$ sort GOT
CHECK
LS.O
LS.S
LS.SYSTEM
MAKEFILE
MKWANT
WANT
$ cat WANT
CHECK
LS.O
LS.S
LS.SYSTEM
MAKEFILE
MKWANT
WANT
$