This is a cache of https://vccplus.brianholman.com/manuals/assembly-language-programming/contract/. It is a snapshot of the page as it appeared on 2026-11-21T00:00:49.025+0000.
Give a subroutine a contract · Assembly Language Programming for the VCC Plus CoCo 3 · 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 9: Assembly Language Programming for the VCC Plus CoCo 3

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

Download PDF
Contents

Chapter 3 of 8

Give a subroutine a contract

Imagine handing the receiver to someone who will call it from a second program. “Copies a message” leaves important questions open. Which register holds the length? Does it copy a zero? Who provides memory? Can the caller still find the next instruction after borrowing the stack?

Trace one trip around the loop

; Input: X source, Y destination, B positive byte count.
; Output: A = sum modulo 256. X and Y advance; B ends at zero.
receive     clra
next        adda    ,x          ; add this byte, leave X at it for the copy
            pshs    a           ; keep the running sum while moving the byte
            lda     ,x+
            sta     ,y+
            puls    a
            decb
            bne     next
            rts

On entry, X points at readable bytes, Y points at a separate writable destination, and B is a positive byte count. The caller owns both regions. It reserves one extra initialized zero for the later print routine. receive does its first copy before it tests B. Supplying zero here would make the first decrement wrap to $FF and the loop perform 256 transfers. That would run far past this destination. A general-purpose copy routine accepting an empty message would need an entry test. Keep the supplied three-byte count for this lab.

The first ADDA reads from X without moving X. PSHS saves the running sum because LDA needs to borrow A to carry a character. The plus in ,X+ takes the byte at the old address and then advances X by one. The store does the same for Y. PULS restores the saved sum. DECB sets the flag used by BNE. When the last iteration finishes, both pointers have advanced by the original count, B is zero, and A contains the checksum. CC has changed. Code that needs the original pointers or flags must save them or arrange to reconstruct them.

Find both kinds of saved byte

Start the portable receiver again with a stop on BSR receive. In the Inspector write down S. Follow the steps below in the assembly window; read memory through Mapped CPU. For a refresher, read the return address one byte at a time.

Stop before the instruction Where to look What was observed in Disk BASIC
BSR at $3F0A S $7F35
CLRA at the start of receive New S and the byte above it S=$7F33; 3F 0C is the address of inspect.
LDA ,X+ immediately after the first PSHS A Top three bytes starting at S S=$7F32; 4F 3F 0C. The one-byte sum sits below the two-byte return address.
DECB after PULS A S and A S=$7F33, A=$4F. The return address is again on top.
CMPA at inspect after the routine returns S and PC S=$7F35, PC=$3F0C. The caller can keep using its stack.

Use your own S if BASIC started with a different stack position. Set a second stop at inspect once you’ve followed the first pass; Continue lets the other passes finish. The saved sum and the saved PC use the same storage mechanism. The instruction that later consumes those bytes determines their meaning.

Choose how to address an operand

Form What the CPU uses Example to find
Immediate A value embedded in the instruction LDB #size puts 3 into B.
Direct An eight-bit operand supplies the low byte; DP supplies the high byte Inspect DP before using a direct-page location. A direct-page offset of $21 would name $0021 only when DP=$00.
Extended A full 16-bit logical address The pointer used for output is at $A002. This address names a ROM vector in this BASIC environment.
Indexed A register supplies a base; an offset or update changes how it is used ADDA ,X leaves X alone. LDA ,X+ advances X.
PC relative A signed displacement is added to the PC after the operand LEAX packet,PCR finds this program’s data even if code and data move together.
Indirect Memory holds the address to use next The brackets in JSR [CHROUT] tell the CPU to read the two-byte destination address through the vector.

Cross the ROM boundary

emit        pshs    x           ; caller still needs its position after ROM I/O
            jsr     [CHROUT]
            puls    x,pc

Look at mapped addresses $A002 and $A003. Our Disk BASIC machine contained A2 82, so this call entered $A282. The source names the vector rather than baking that observed destination into the program. This service expects a character code in A. The caller still needs X to walk the text after the service returns; emit saves X and restores it. PULS X,PC also consumes the return address placed by the caller’s BSR. A routine that branches into emit without that return address would give PULS the wrong stack layout.

ROM entry points are part of the environment. The supplied examples assume the indicated BASIC ROM is mapped and its services initialized. A program running in another OS needs its own service conventions. The linked receiver gives the copy routine a second caller without changing its contract.

Follow the same registers across an operating-system boundary in Beacon’s OS-9 call contract.

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