This is a cache of https://vccplus.brianholman.com/manuals/working-with-os9/assemble/. It is a snapshot of the page as it appeared on 2026-11-21T00:01:42.267+0000.
Assemble a program on the CoCo · Working with OS-9 — A Comprehensive Manual · VCC Plus
← Manual LibraryVCC Plus 3.7.1 · Reading on the web

Try the exercises in VCC Plus. Example links download files here; open them in the app to work beside the emulator.

The complete book · PDF editionBook 11: Working with OS-9 — A Comprehensive Manual

51 pages · VCC Plus 3.7.1 · Keep a copy to read or print.

Download PDF
Contents

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 guest assembler reports zero errors and zero warnings. IDENT shows the 56-byte beacon module, entry offset $0014 and good CRC $3D8059.

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.

Original VCC Plus manuals © 2026 Brian K. Holman. Third-party references retain their authors’ copyrights and licenses. Artwork notices. Edition 3.7.1; source and export identity. Printable edition: PDF source and export identity.

A closer look

Open original