Chapter 13 of 14
Assemble a program on the CoCo
Write a station report in 56 bytes. Most of those bytes will describe the program or hold its message. Only seven instructions are needed to deliver the line and return control to the shell.
Give OS-9 a module
Begin at Shell+ with /dd/cmds as the execution directory and a personal HD1. Keep any previous beacon.a or beacon by using a fresh practice image for a repeat. At the shell enter:
build /h1/beacon.a
Type the Beacon source one line at a time. Start each label, such as start or finish, in the first column. Keep a leading space on lines that start with an assembler directive or an instruction. Finish by pressing Return at the next empty BUILD prompt.
mod endmod,name,$11,$81,start,256
name fcs /beacon/
fcb 1
start lda #1
leax note,pcr
ldy #notesiz
os9 $8c
bcs finish
clrb
finish os9 $06
note fcc /beacon report/
fcb 13
notesiz equ *-note
emod
endmod equ *
end
mod starts a module. Its arguments supply the end of the module, the name, its type and language, its attributes and revision, the entry point, and a request for working storage. The assembler resolves the labels as offsets. fcs stores the module name with the high bit of its last character set. The byte immediately after the name gives edition 1. Those bytes belong to the name and header information. The first executable instruction begins at start.
The header declares a 6809 program module ($11), re-entrant with revision 1 ($81). OS-9 can share its program bytes among callers. Each process gets its own working storage and stack. Beacon requests 256 bytes and leaves its message inside the read-only module. fcb 13 adds the carriage return expected by the line-writing service. The assembler evaluates notesiz as 14, the length including that final byte.
Follow the two system calls
| At this line | What the register or flag means |
|---|---|
| lda #1 | A selects path 1, the process's standard output. The shell chose what is on the other end. |
| leax note,pcr | X becomes the address of the first message byte. The displacement is relative to the program counter, so the module can execute at different logical addresses. |
| ldy #notesiz | Y supplies the maximum number of bytes the write may consume. |
| os9 $8c | I$WritLn asks the operating system to write a line. The assembler emits a 6809 SWI2 instruction followed by the service number. |
| bcs finish | The service sets carry on failure and puts the error number in B. This branch preserves the number for the caller. |
| clrb | On the success path the exit status becomes zero. |
| os9 $06 | F$Exit ends the process and passes the status in B to its parent. |
The CPU never has to know an address for the screen. In the BASIC ROM example, a caller used a ROM vector to send a character. Here the OS-9 process selects a path and asks the kernel for a service. In the next exercise the shell will put a disk file on that very same path.
Let the guest assembler check your work
list /h1/beacon.a
asm /h1/beacon.a o=/h1/beacon
ident /h1/beacon
Use the listing to catch a missing label or misplaced space before assembling. In the asm command o= names the output file. The final emod in the source generates the closing CRC. Here are four checks on what came out:
| Field from IDENT | Expected value | How to read it |
|---|---|---|
| Header name and module size | beacon, $0038 | The whole module, including header and CRC, occupies 56 bytes. |
| Execution offset | $0014 | The first instruction is 20 bytes from the beginning of the module. |
| Data size | $0100 | The process requests 256 bytes for working storage including its stack. These bytes are allocated at execution. |
| Module CRC | $3D8059 (Good) | IDENT recomputed the CRC successfully. This particular value identifies the bytes produced by the printed listing. |
The assembler's line counting allocated data can read zero even though the header requests $0100 bytes at runtime. Compare what was written into the file with what a new process will need. Now take your completed module to the station console.
For the format and service conventions, see The NitrOS-9 Project, NitrOS-9 Technical Reference, revision 0.1 (2004), chapter 3, pp. 26–32, F$Exit, p. 99, and I$WritLn, p. 148.