maux
Star on GitHub Buy me a coffee

L2. hello, world, in assembly

Learn / L2

Goal: turn a 6502 source file into a program with nas and ld, run it, and then make one mistake and see how the assembler reports it.

What you need

L1 (you can edit a file with vi). The source is already on the disk, so this lesson copies it; retype it with vi if you want the practice.

The file

About twenty lines of code under a long comment. PUTS and EXIT belong to liba, maux's own small C-less library: ext says "defined somewhere else", and ld will find them.

examples/hello/hello.s — on the disk as /usr/src/examples/HELLO/hello.s
*---------------------------------------------------------------
* hello.s -- the first maux program, in 6502 assembly.
*
*   nas -o hello.o hello.s
*   ld -o hello hello.o -L /usr/lib -l a
*   ./hello
*
* PUTS and EXIT belong to liba, maux's C-less libc. `ext` names
* them, and `ld -l a` pulls the modules that define them out of
* the library directory /usr/lib/LIBA. Everything else here is
* this file: START is the first byte of the program, and ld puts
* the module you name first, at $0800.
*
* The string is plain 7-bit ASCII (single quotes) ending in CR
* ($0D) and then NUL: PUTS stops at the NUL. maux's console
* takes it in either polarity.
*
* 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
PUTS        ext
EXIT        ext
            put   /usr/inc/sc.fd.equ
            put   /usr/inc/zp.equ

START       lda   #<MSG
            sta   PTR0
            lda   #>MSG
            sta   PTR0+1
            ldx   #FD_STDOUT
            jsr   PUTS
            lda   #0
            jsr   EXIT

MSG         asc   'hello, world',0D,00

The session

The first half builds and runs the program. The second half, which is the film “a typo, caught”, breaks it twice.

$ mkdir /tmp/l2
$ cd /tmp/l2
$ cp /usr/src/examples/HELLO/hello.s hello.s
$ nas -o hello.o hello.s
nas: 32 bytes -> hello.o
$ ld -o hello hello.o -L /usr/lib -l a
$ ls -l
BIN     3070 -                hello
$F8       64 -                hello.o
TXT     1344 -                hello.s
$ ./hello
hello, world
$ vi hello.s
[ in vi: type :%s/jsr   PUTS/jsr   PUTZ/ and press RETURN, then :wq and RETURN ]
$ nas -o hello.o hello.s 2> ERRS
$ cat ERRS
nas: unknown label PUTZ (hello.s line 35)
nas: pass 2 failed
$ nas -o hello.o hello.s 2> /dev/null; echo $?
1
$ vi hello.s
[ in vi: put PUTS back, then change the first lda to ldq: :%s/jsr   PUTZ/jsr   PUTS/ and :%s/lda   #<MSG/ldq   #<MSG/, RETURN after each, then :wq ]
$ nas -o hello.o hello.s 2> ERRS
$ cat ERRS
nas: pass 1 failed
$ grep -n ldq hello.s
30:START       ldq   #<MSG
$ vi hello.s
[ in vi: change ldq back to lda, then :wq ]
$ nas -o hello.o hello.s
nas: 32 bytes -> hello.o
$ ld -o hello hello.o -L /usr/lib -l a
$ ./hello
hello, world

What just happened

nas assembled hello.s into hello.o, an object file of type $F8, the Merlin REL format. ld linked it into hello, a BIN file: the module you name goes first, at $0800, and -l a told it to pull from the library directory /usr/lib/LIBA the modules that define the names your program left open. That is why hello is much larger than the 32 bytes nas reported: the rest is liba.

A BIN file's auxiliary type is its load address, and $0800 is where every maux program starts. The shell loads hello there and runs it. The program builds its message in plain 7-bit ASCII (single quotes) ending in $0D and a zero; the console takes either polarity, and maux's own text, the kind vi writes, has the high bit set and ends lines with $8D.

A typo, caught

The first mistake changes jsr PUTS to jsr PUTZ with a vi command: :%s/jsr PUTS/jsr PUTZ/ replaces on every line. nas says:

nas: unknown label PUTZ (hello.s line 35)
nas: pass 2 failed

That is the whole format: the label, the file, the line. Both lines came out of 2> ERRS: in Unix the shell's 2> catches the error stream, and nas prints its diagnostics there, so the screen stayed quiet and the file holds the complaint. (Its success line, with the byte count, goes to the ordinary output.) Its exit status is 1 when it fails, which is what make will use in L5 to stop. Watch the whole repair, from the failed make to vi on the line.

The second mistake is a misspelt instruction, ldq for lda. This one is reported more tersely: nas: pass 1 failed and nothing else, no line number and no reason. It is the same message you get for an instruction nas does not know, for a 65C02 instruction in a file that never says xc (the directive that enables them), and for a source file that does not exist. When you see it, look at the lines you changed last; grep -n prints a matching line with its number, which is how the session finds the line.

Try next

Change the message, assemble, link and run it again. Then make it print the message twice. The call that prints is six lines long and you already have it.

← Hello, world in the shell | All lessons | Your own filter →