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.