6502-sweet16

name

6502-sweet16

description

Reference for SWEET16, Steve Wozniak's 16-bit interpreted pseudo-processor built into the Apple II Integer BASIC ROM (entry $F689). SWEET16 is a tiny virtual machine with sixteen 16-bit registers (R0-R15) living in zero page, invoked by JSR SWEET16 followed by inline bytecode and terminated by RTN. Use this skill WHENEVER you see a JSR $F689 (or JSR SWEET16) followed by data bytes, encounter SWEET16 mnemonics (SET, LDD, STD, POP, STP, CPR, BNC, RTN, BS/RS), need to disassemble or trace SWEET16 bytecode, or are porting Apple II code that drops into SWEET16 for compact 16-bit pointer math and block moves. Trigger on "what is SWEET16", "$F689", inline bytecode after a JSR, or 16-bit register ops like "SET R1" / "LDD @R1". Pairs with the 6502-instruction-set, 6502-memory-map, and 6502-to-rust skills.

SWEET16 — Wozniak's 16-bit Pseudo-Processor

SWEET16 is a 512-byte interpreter in the Apple II Integer BASIC ROM that gives the 8-bit 6502 a compact 16-bit instruction set. Woz wrote it to shrink the 16-bit pointer arithmetic in Apple BASIC (incrementing pointers, comparing addresses, block moves) — operations that are verbose in native 6502. It trades speed (≈10× slower, it's interpreted) for code density. You will meet it in Integer BASIC-era Apple II code and in anything that calls $F689.

How it is invoked — the key idea

SWEET16 is entered with an ordinary JSR SWEET16 (JSR $F689 on the Apple II). The bytes immediately following the JSR are not 6502 code — they are SWEET16 bytecode, executed by the interpreter. A RTN opcode ($00) ends SWEET16 mode and returns to the 6502 instruction right after the bytecode.

        JSR  SWEET16     ; $F689 — switch into the VM
        ; ---- the following bytes are SWEET16 bytecode, NOT 6502 ----
        11 00 20         ; SET R1, $2000     (1n + 2 immediate bytes, low first)
        12 00 40         ; SET R2, $4000
        13 00 01         ; SET R3, $0100     (count)
LOOP    41               ; LD  @R1           (R0 = (R1), R1++)
        52               ; ST  @R2           ((R2) = R0, R2++)
        F3               ; DCR R3
        07 ??            ; BNZ LOOP
        00               ; RTN — back to 6502
        ; ---- 6502 resumes here ----

Disassembly trap: a 6502 disassembler will mis-decode the bytecode region as 6502 instructions. Whenever you see JSR $F689, switch to SWEET16 decoding until the $00 (RTN). This is the single most common mistake reading this code.

The 16 registers (in zero page $00-$1F)

Each register is a 16-bit little-endian pair. Four are special:

Register	ZP addr	Role
R0	$00-$01	accumulator (ACC) — implicit operand of ADD/SUB/LD/ST
R1-R11	$02-$17	general purpose
R12	$18-$19	subroutine return-stack pointer (used by BS/RS)
R13	$1A-$1B	holds the result of the last CPR (compare)
R14	$1C-$1D	status register (drives the branch tests)
R15	$1E-$1F	program counter (the SWEET16 PC)

Because the registers are just zero-page locations, 6502 code and SWEET16 code share them — you can set up a pointer in zero page before entry and it is the corresponding Rn.

Opcode set

Register operations — high nibble 1–F, low nibble = register n

Opcode	Mnemonic	Operation
1n	SET Rn	Rn ← next two bytes (low byte first)
2n	LD Rn	R0 ← Rn
3n	ST Rn	Rn ← R0
4n	LD @Rn	R0 ← byte at (Rn); then Rn ← Rn + 1 (high byte of R0 = 0)
5n	ST @Rn	byte at (Rn) ← low byte of R0; then Rn ← Rn + 1
6n	LDD @Rn	R0 ← word at (Rn); then Rn ← Rn + 2
7n	STD @Rn	word at (Rn) ← R0; then Rn ← Rn + 2
8n	POP @Rn	Rn ← Rn − 1; then R0 ← byte at (Rn) (high byte of R0 = 0)
9n	STP @Rn	Rn ← Rn − 1; then byte at (Rn) ← low byte of R0
An	ADD Rn	R0 ← R0 + Rn (carry → R14)
Bn	SUB Rn	R0 ← R0 − Rn (carry/borrow → R14)
Cn	POPD @Rn	Rn ← Rn − 2; then R0 ← word at (Rn)
Dn	CPR Rn	R13 ← R0 − Rn (compare; sets status, doesn't change R0)
En	INR Rn	Rn ← Rn + 1
Fn	DCR Rn	Rn ← Rn − 1

The @Rn modes auto-increment (LD/ST/LDD/STD) or pre-decrement (POP/STP/POPD) the pointer register — that is what makes SWEET16 so compact for walking buffers and implementing stacks. Byte loads zero-extend into R0's high byte.

Non-register operations — high nibble 0, low nibble selects

Opcode	Mnemonic	Operation
00	RTN	exit SWEET16, return to 6502 (restores 6502 registers)
01 dd	BR	branch always (signed 8-bit displacement dd)
02 dd	BNC	branch if no carry
03 dd	BC	branch if carry
04 dd	BP	branch if plus (R0/last result positive, bit 15 = 0)
05 dd	BM	branch if minus (bit 15 = 1)
06 dd	BZ	branch if zero
07 dd	BNZ	branch if nonzero
08 dd	BM1	branch if result = $FFFF (minus one)
09 dd	BNM1	branch if result ≠ $FFFF
0A	BK	execute a 6502 BRK
0B	RS	return from a SWEET16 subroutine (pops via R12)
0C dd	BS	call a SWEET16 subroutine (pushes via R12, then branches)
0D–0F	(unused)	not defined

Branch displacements are a signed byte relative to the address of the byte after the displacement (like 6502 relative branches).

Branch/status semantics

The branch conditions read the status register R14, which is updated by the last register operation that produced a result in R0 (LD, ADD, SUB, INR, DCR, LD/POP @Rn…) or by CPR (which puts its result in R13 and sets status from it):

• BZ / BNZ — zero / nonzero result.
• BP / BM — bit 15 of the result clear / set (treat as sign).
• BM1 / BNM1 — result is exactly $FFFF / not. Handy as a loop sentinel.
• BC / BNC — carry out of the last ADD/SUB (16-bit), i.e. unsigned overflow / borrow. After CPR, carry reflects an unsigned comparison of R0 vs Rn.

A typical compare-and-branch: CPR Rn (Dn) then BC/BNC/BZ to test the relationship between R0 and Rn.

Porting SWEET16 to Rust (see the 6502-to-rust skill)

SWEET16 is pleasant to port because it is already higher-level than 6502:

• Model the 16 registers as [u16; 16] (or named fields), with R0 the accumulator.
• @Rn loads/stores become indexed memory access with an explicit Rn += 1/2.
• ADD/SUB are u16 wrapping ops; capture the carry into a bool (the R14 status) so BC/BNC port correctly.
• BP/BM test (result & 0x8000) != 0; BM1/BNM1 test result == 0xFFFF.
• BS/RS are a call/return using R12 as a stack pointer into memory — port them as a recursion or an explicit stack, matching the original.

Decode the inline bytecode into a list of SWEET16 instructions first, then port that list — never try to port the raw bytes as if they were 6502.

Source / verification

Entry point $F689, register roles, and the full opcode map are per Wozniak's "SWEET16: The 6502 Dream Machine" (BYTE, Nov 1977) and the 6502.org SWEET16 listing. Reimplementations exist for other 6502 systems; the bytecode is platform-neutral, but the $F689 entry is Apple II Integer-BASIC-ROM specific — on other systems SWEET16 is linked in at a different address.