Dev
For a programmer who already knows 6502 assembly. There is no C compiler, so the library is the thing you program against: liba, whose routines are named and shaped after the libc functions they stand in for. Learn the handful below and most of a Unix program writes itself.
liba
liba is a directory of REL modules at /usr/lib/LIBA that
ld -l a searches. A program names what it wants with
ext and the linker pulls in the modules that define those names;
the equates it includes live in /usr/inc. liba is built by
nas, and a gate checks that a fresh build reproduces the tracked
objects byte for byte (check-liba-pins).
ext PUTS,EXIT
lda #<msg
ldx #>msg
sta PTR0
stx PTR0+1
ldx #1 ;stdout
jsr PUTS
The file is the inclusion boundary, so a program pays for every routine in a
module it touches, whether it calls it or not. make report-liba
prints that bill per program and names the routines nobody reached.
The libc names it answers to
Same job, same name where the name survives six characters of Merlin label. Arguments arrive in registers and zero-page pointers rather than on a C stack, and each routine's own header comment is the contract.
| liba | libc | What differs |
|---|---|---|
STRLEN | strlen | 16-bit, so a string over 255 bytes measures correctly |
STRCMP | strcmp | byte for byte, 16-bit |
STRCMPI | strcasecmp | folds a-z only; digits and punctuation untouched |
STRCPY | strcpy | terminator included |
PUTS | write | takes an fd, not a stream; the NUL is not written |
PUTC | fputc | buffered per fd, line or full (SIOM_LINE, SIOM_FULL) |
GETC | getc | one raw byte; flushes every stream first |
SIO_FLUSH | fflush | one fd; SIO_FLUSHALL for all of them |
FCLOSE | fclose | flushes, then closes |
EXIT | exit | flushes every stream; SC_EXIT is _exit |
LSEEK | lseek | the offset is 3 bytes, so a file reaches 16 MB |
SC_PIPE | pipe | writes the two fds into your buffer |
SC_DUP2 | dup2 | as in V6 |
SC_FDSTAT | isatty | answers what kind of object an fd holds |
SC_BRK, SC_SBRK | brk, sbrk | page-granular; see below |
GETENV | getenv | ENVNTH walks it the way environ does |
OPTINIT, GETOPT | getopt | OPTINIT takes the permitted letters first; OPTIND as usual |
OPENDIR, RD_ADVANCE, CLOSEDIR | opendir, readdir, closedir | also serves the synthetic directories |
RE_MATCH | regexec | basic expressions only, no ERE; no separate compile step |
HASMETA, GFOLD | fnmatch | the shell's globbing primitives |
PRNUM, PRHEX8, PRHEX16 | printf | no format strings and no varargs: one routine per conversion |
Where it is not libc
- Strings carry the high bit. A liba string is NUL-terminated like C's, but its characters have bit 7 set, which is what the screen and ProDOS want.
MAKEHIandSTRIPHIconvert a byte at the boundary; nothing converts silently. - There is no
malloc. A program sets its break withSC_BRKand grows it withSC_SBRK, both rounded up to a page. Above that you manage your own storage. - Eight open files per process, which is ProDOS's limit, not a choice.
- No varargs.
printfcannot exist without a C stack to walk, so formatting is one call per conversion and the caller does the joining. - Return values are registers and carry. A result comes back in A, or in A and X for sixteen bits, with carry set on failure. Each header says what it clobbers and what it preserves, and those promises are relied on.
The nas dialect
nas is the native assembler. It accepts the Merlin-derived dialect
this repository checks, and nothing is promised beyond that: it is not a claim to
accept every Merlin macro or historical option. The limits below are house
limits, inherited from Merlin-8 and held by the check-modules and
check-dialect gates over every source in the tree. They are not errors that
nas itself raises:
- 64-character lines. Real Merlin-8 rejects a longer line, and the gate refuses one in the tree.
nasdoes not enforce it. - 13-character labels, 12 for a
:locallabel (the colon counts), the length at which Merlin-8 assembles and one more does not.naskeeps 13 significant characters of a name and does not reject a longer one. - No macros. The tree has none, by ruling; you write the lines out.
- Expressions: write them so that precedence cannot matter. Merlin-8 evaluates strictly left to right and rejects parentheses; merlin32 evaluates inline operands the same way but gives an
equright-hand side C-style precedence. The dialect gate flags the shapes where the two disagree (scripts/check_dialect.py, hazard 1), so keep expressions to one operator kind, or split them over severalequlines. - Undefined symbols are refused.
nasreportsunknown labeland exits 1; it no longer assembles one as zero.
Usage: nas -o OUTPUT INPUT.S. The -o comes first;
without it the output name is A.OUT. Success returns 0, a reported
failure 1.
REL and ld
Objects are Merlin REL files, ProDOS file type $F8. An object is
its code, then 4-byte fixup records, then a symbol list; the file's ProDOS
aux type is its code length, so a REL moved without its metadata links to
nothing. ld links modules and library directories (not archives; there is no
ar), origin $0800 by default:
nas -o hello.o hello.s ld -o hello hello.o -L /usr/lib -l a
PLASMA and the plasma cutter
maux runs David Schmenk's PLASMA: a word-oriented language compiled to
bytecode for a small virtual machine. plasm is his compiler, running on
the machine; plasma hello.mod runs a module it wrote. The
L6 lesson on the Learn page compiles his own
hello.pla that way. A PLASMA program has to be linked at launch:
plasma reads the runtime, reads the module, relocates it and binds each
name it imports, every time.
The plasma cutter, scripts/plascut.py, does that
work once, on the host, and writes the result as a single flat BIN file
that the kernel spawns like ls: the runtime and every module already
relocated and bound, with a small table that puts the program's data back to its
pristine state on a warm respawn. A cut program is the same module as the loaded one
with its loading done in advance, not a different language or compiler.
nas and plasm are shipped this way, and so is the
HELLO of the L6 lesson, which is why make can start them
once per file without paying for the link each time.
Measured on the emulator by the gate that checks the cutter, at revision
485672f5: one warm nas run over a small fixture (it assembles
to 34 bytes, so this is the cost of loading, not of
assembling) takes 1.65 million cycles cut against
5.95 million loaded through plasma NAS:
4.30 million cycles, 72 percent,
saved on every launch. The cutting itself happens on the host, not on the machine.
make
make is a POSIX subset with no shell between it and the commands:
macros ($(NAME), ${NAME}, $@ $< $* $?),
double-suffix inference rules, .SUFFIXES, .SILENT,
.IGNORE, .PRECIOUS, .DEFAULT, .POSIX, the
@ - + recipe prefixes, and -e -i -k -n -p -q -r -S -s -t.
It has no built-in rules, no single-suffix rules, no include, no
:: rules, no parallelism. It reads either text convention.
Text
maux writes high-bit-set 7-bit ASCII ending in $8D and types
such files $04. That is a maux ruling, not a property of the
machine: standard ProDOS text is low ASCII ending in $0D, with the
same type byte. The line-oriented tools read either convention, and a filter emits
the convention its input arrived in, so running one over a file from
a2til, tip or a NuFX archive does not leave a mixed file.
nas and make read either too.
Underneath: calling the kernel
liba's SC_ routines are thin wrappers over this, and you rarely
need it directly. The native door is JSR $FF00: the call number in Y,
a pointer to the parameter block in A (low) and X (high), the result in A with
carry set on failure. A call that takes no parameters, such as fork,
ignores the pointer.
lda #<parms
ldx #>parms
ldy #SYS_FORK
jsr $FF00
The kernel is entered by that call or by an interrupt; both build the same
six-byte frame on the process's own stack. A BRK in a user process is
a SIGTRAP: the process is killed and the machine goes on. A BRK in
the kernel halts it. The full contract is docs/SYSCALL.md.
42 calls are defined in the inc/sc.*.equ files,
which the build reads. The low numbers are the kernel's process, descriptor, signal and terminal
calls. The file calls start at $C0 and each is named for the ProDOS
MLI call it carries. The comments in each file describe the call.