The SD-8516 instruction set is organized into four tiers. Numbering is canonical in decimal (as defined in arch.h and arch.ts); hex is given alongside for convenience.

• Tier 1 - Core behaves like a RISC instruction set: small, orthogonal, and complete on its own. Target this first. Everything above it can be synthesized from the core if you have to.
• Tier 2 - Extended are quality-of-life instructions for hand assemblers. ADD reg, imm is the canonical example: you do not need it (load the immediate and ADD), but it is provided for convenience. MUL is in the same spirit, since you can loop with ADD.
• Tier 3 - CISC are heavier, mostly VAX- and 680×0-flavored instructions: block memory, queue management, character scanning, jump tables. Each one folds a small loop into a single fetch-execute.
• Tier 4 - Acceleration are instructions added primarily to speed up a specific consumer: the LLVM backend (MOVSX/MOVZX, indexed addressing), the Forth system (LSTEP and friends), or the hardware (PPU/ASU). They exist to remove instructions from a hot path, not to add expressiveness.

A handful of opcodes carry aliases (e.g. JC/JAE, BC/BAE, CMPC/CMPC3); both names assemble to the same byte.

Deprecated since the previous revision: CASE3, CASEB, PAB, UAB, and conditional JMPR.

A small, sufficient core. If you only ever target these, you can write any program.

Although this is intended as a RISC core, there are some extras here, primarily LD-8bit hot path, which is done to speed up execution of 8 bit loads by about 30%. Additionally, INC, DEC and CALL/RET are semi-RISC because you can ADD reg, #1 or PUSH ptr0 and JMP (then POP IP to return). INT and RTI are suspect here, as well as CMP_IMM (you can just load into a register and use register compare). But these instructions are so common that it is difficult to justify not including them. The core set is intended to be minimalist, but not obtusely so.

POPF however, is a strong canidate for removal. It would really only be needed for a kind of protected mode, interrupt mode or kernal mode, and we dont use it currently.

Finally, it may be interesting to fuse CMP and JZ. Imagine, any CMP and conditional jump could be a CJMP. ex. CJZ A, B, address – if they're equal, then we jump. One instruction. We save a dispatch and a byte.

Consider:

• No CMP exists in isolation
• No JZ exists without responding to a change in the Z flag.
• CJZ A, A can test for zero after a load if we really need one.

Further investigate:

• Does the cost of flag calculation outweight dispatch for how often a CMP occurrs?

Conveniences for the hand assembler. None of these add capability the core lacks; they trade an opcode for fewer instructions in common patterns.

Heavier instructions that fold a loop into one fetch-execute. Mostly VAX- and 680×0-inspired; useful for the kernal and for hand-written string/queue code.

Instructions added to remove work from a specific hot path rather than to add expressiveness. Each one has a primary consumer noted below.

Canidates for inclusion: LEA, fused CMP-Bcc and CMP-Jcc, conditional move, LD_IDX16

Detailed notes per instruction. Linkable anchors are provided for cross-reference from the tables above.

#0 $00 LD_IMM
Load register with an immediate value. A = $5 (16/24/32-bit depending on register width).

#1 $01 LD_MEM
Load register from memory (absolute address). A = [$5].

#2 $02 LD_REG
Load register from memory (register-indirect pointer). A = [X].

#3 $03 LD_IMM8
Load byte register with an immediate value. AL = $5.

#4 $04 LD_MEM8
Load byte from memory (absolute). AL = [$5].

#5 $05 LD_REG8
Load byte from memory (register-indirect). AL = [X].

#6 $06 ST_MEM
Store register to memory (absolute). [$10] = A.

#7 $07 ST_REG
Store register to memory (register-indirect). [X] = A.

#9 $09 MOV dst, src
Register-to-register copy ex. Y = A. MOV requires source and destination of equal width; this is enforced at assemble time. A move that changes width is not a MOV – use MOVSX/MOVZX to widen. The assembler rejects a mismatched-width MOV rather than guessing which bytes you meant. Mismatched MOV is undefined at execution time.

#11 $0B PUSH
Push register onto stack. SP -= width; [SP] = A.

#12 $0C POP
Pop stack into register. Y = [SP]; SP += width.

#15 $0F PUSHF
Push flags register onto stack.

#16 $10 POPF
Pop stack into flags register. *

#23 $17 INC
Increment register by 1 (any width). X += 1. Sets Z/N flags.

#24 $18 DEC
Decrement register by 1 (any width). Y -= 1. Sets Z/N flags.

#25 ST_PD / #26 LD_FS / #27 ST_FS
Auto-stepping addressing. ST_PD pre-decrements the pointer then stores (STA [-, BLX]), giving a push-style write. LD_FS loads then advances the pointer (LDA [BLX, +]), and ST_FS stores then advances. These collapse the pointer bookkeeping of a copy loop into the access itself.

#28 $1C MOVSX dst, src / #29 $1D MOVZX dst, src
Move with sign-extend (MOVSX) or zero-extend (MOVZX). The source is read at its own width and written across the full destination, with the high bytes filled from the source's sign bit (MOVSX) or with zero (MOVZX). The destination must be strictly wider than the source; this is checked at assemble time. Both fully define the destination, so unlike a byte ALU op there is no partial-register hazard, and the in-place overlapping case (MOVSX A, AL) is well defined.

These exist to collapse the compiler's extend sequence: without a native sign-extend, widening a signed char to int took three ops (AND/XOR/SUB implementing the (x ^ 0x80) - 0x80 identity). MOVSX does it in one. Integer promotion makes signed widening pervasive in C, so this is a recurring code-size win. MOVZX similarly drops the masking immediate of an AND $FF style zero-extend.

#30 $1E ADD
Add registers. X = X + Y. Updates Z N C V.

#31 $1F SUB
Subtract registers. X = X - Y. Updates Z N C V.

#50 $32 AND
Bitwise AND. dst = dst & src. Updates Z N.

#51 $33 OR
Bitwise OR. dst = dst | src. Updates Z N.

#52 $34 XOR
Bitwise XOR. dst = dst ^ src. Updates Z N.

#53 $35 NOT
Bitwise NOT (invert all bits). reg = ~reg. Updates Z N.

#70 $46 SHL
Shift left. A «= count. Updates Z N C.

#71 $47 SHR
Shift right (logical). A »= count. Updates Z N C.

#80 SHL_X / #81 SHR_X
Shift by a variable count rather than by one. The exact operand form (count in a register vs. immediate) and whether the count is masked should be confirmed against the current emulator handler before relying on this entry.

#90 $64 CMP
Compare registers (subtract, discard result). tmp = A - B. Updates Z N C V.

#91 $5B CMP_IMM
Compare register against immediate. tmp = A - $1. Updates Z N C V.

#100 $64 JMP
Unconditional jump. IP = @label.

#101 $65 JZ
Jump if zero. if (Z) IP = @label.

#102 $66 JNZ
Jump if not zero. if (!Z) IP = @label.

#105 $69 JC
Jump if carry set (alias JAE for unsigned >=). if (C) IP = @label.

#106 $6A JNC
Jump if carry clear (alias JNAE for unsigned <). if (!C) IP = @label.

#130 $82 CALL addr / CALL reg / #131 $83 CALLR reg
CALL pushes the return address (the instruction after the call) and jumps to the target. CALLR takes a register operand and dispatches on its width: 16-bit and 8-bit registers combine with the current bank, 24-bit registers give a full address, and a 32-bit pair (e.g. AB) is narrowed to 24 bits by discarding the high byte. This makes 32-bit register pairs usable as function pointers.

#120-#129 Branches (BZ, BNZ, BC, BNC, BA, BNA, BG, BGE, BL, BLE)
Two-byte relative branches with a signed 8-bit displacement (range -128..+127 from the instruction). They mirror the absolute jumps but encode shorter and stay position-independent, so they are preferred for tight local loops. BC/BAE and BNC/BNAE are aliases. For targets outside +/-127, use the absolute jumps.

#140 $8C MEMCOPY src, dst, reg
Copy reg bytes from src to dst. Handles overlap. A fast MMU operation – where a string copy is otherwise a tight LDA/STA/JNZ loop, this is a single opcode when you know the length.

#141 $8D SCAN ELM, reg
Scan from ELM for the value in reg. An 8-bit register searches for a byte; a wider register searches for that many bytes. Useful for finding keyword candidates and for computing string length (scan for zero, subtract the start pointer).

#142 $8E CMPC ELM, FLD, C (alias CMPC3)
Non-zero byte compare, useful for strings. Compares up to C characters; C returns either the index of the first mismatch or the matched length. Sets ZERO on a full match; otherwise CARRY distinguishes the -1 / +1 ordering.

CMPC allows early termination when byte_a == 0 – the C-string “begins with” semantics. If both strings reach a terminator at the same position with all prior bytes equal, the loop exits matched (Z=1, C=1). Only byte_a is tested because by that point byte_a == byte_b is already proven, so byte_a == 0 implies byte_b == 0. This lets CMPC do double duty: fixed-length compare and null-terminated strcmp in one instruction.

#143 $8F SKPC ELM, reg / #144 $90 SKPC_IMM ELM, #imm
Anti-scan: advance while the needle is found, stopping at the first non-matching position. A word-or-wider needle steps by needle width. Most often used to skip spaces: SKPC ELM, $20 leaves ELM just past the last space.

#145 INSQUE / #146 INSQUE_PTR / #147 REMQUE
Doubly-linked queue primitives. INSQUE inserts an element (register or pointer form); REMQUE removes one.

REMQUE's Z-flag semantic differs from the VAX and is worth a kernal-side note. The VAX used V for “the queue was already empty” (an error condition). SD-8516 uses Z for “the queue is now empty after this removal” (a state condition):

• VAX: V=1 means “you tried to remove from an empty queue.”
• SD-8516: Z=1 means “you removed the last item; the queue is now empty.”

Both are useful, but they answer different questions.

#148 $94 SCANQUE H, N, O / #149 $95 SCANQUE_IMM H, N, #O
Three operands: head, needle, and offset. SCANQUE_IMM takes the offset as an immediate byte; SCANQUE takes it in a register (allowing offsets beyond +255).

SCANQUE combines queue traversal with a structured-field match in one fetch-execute cycle – the inner loop of every lookup in a hash chain, free list, or PCB table. The immediate form is what you use 99% of the time (the field offset is known when you write CRUD for a struct); the register form exists so generic kernel queue helpers can take “field offset” as a parameter.

#160 SEZ / #161 SEN / #162 SEC / #163 SEV
Set the zero, negative, carry, and overflow flags respectively. Useful when you are certain no intervening operation disturbs the flag – for example, carry survives POP and MOV, so it is a common error/clear channel out of a routine (JC @error).

#164 $A4 SEE
Set the Exception flag. Used by some interrupts and the system to signal an error, but free for your own use otherwise. Think of it as an “Extra” flag.

#165 $A5 SEF
Set the F (“free”) flag. Used for “first-statement” in BASIC; otherwise safe for machine-language use.

#166 $A6 SEB
Set the B (“bonus”) flag. Used for BREAK in BASIC; otherwise safe for machine-language use.

#167 $A7 SEU
Set the User flag. Not used by the system; reserved for the programmer.

#168 $A8 SED
Set Debug. Emits trace messages while on; slows the system considerably. Trace output may be compiled out in some builds.

#169 $A9 SEI
Enable/disable interrupts. With interrupts off, INT will not fire.

#170 $AA SSI
Set the Sound Interrupt flag. Managed by the KERNAL; semi-reserved and may be removed.

#200 $C8 CASE selector, #limit
Inline jump table. Indexes an address from the table that follows the instruction and CALLs it. limit (immediate, 0-255) is the table length. If selector > limit the instruction silently falls through without calling; if you need to detect that, have your handlers return a result code whose default means “no handler ran.” Table format: [addr][addr]….

CASE reads from the instruction stream as data – the inline table is structured bytes, not fetched-and-decoded instructions, the same idea as LD_IMM's operand pushed further. Two derived addresses do the bookkeeping:

• IP + 3 * sel: the table slot holding the target (read as a 24-bit address).
• IP + 3 * lim + 3: the first byte past the table (the return point, and the

IP destination on out-of-bounds).

Both are masked to 24 bits because IP arithmetic wraps in a 24-bit space.

Out-of-bounds sets V and ER and falls through rather than trapping (unlike VAX CASE, which raises an exception). The policy is “error recoverable”: software decides whether to handle it, e.g. a JV some_handler after the CASE. No other flags are touched, which is convenient if the selector came from an arithmetic op whose flags you still want.

A single-entry CASE acts as a CALLZ: call if the register is zero, otherwise not.

#202 $CA CASETAB base, selector, #limit
Jump table held at a base address rather than inline. Indexes an address from the table at base by selector, bounded by limit, and dispatches to it.

#203 $CB CVTAN reg8
Convert ASCII to number. Maps '0'-'Z' to 0-35. Sets Overflow if the character is not a decimal digit (0-9) and Carry if it is not a hex digit (0-15). Also a fast digit test: MOV reg8, AL then CVTAN reg8 lets you branch with JO/JNO (JV/JNV). Designed for zoned decimal, and works for zoned hex.

#204 $CC CVTNA reg8
Convert number to ASCII, the inverse of CVTAN. Maps 0-35 to '0'-'Z'. Sets Overflow if outside 0-9 and Carry if outside 0-15.

#210 LD_IDXI / #211 LD_IDXR / #212 ST_IDXI / #213 ST_IDXR
Indexed load/store: a 24-bit pointer register plus a displacement. The I forms take a signed byte immediate (-128..+127); the R forms take a register offset. These back the compiler's frame-slot and struct-field access ([ptr + disp]). The pointer base must be a 24-bit register; the effective address reads the base at its true width before applying the offset.

#220-#229 PPU accelerators
Delegate a drawing or timing primitive to the PPU: PPIXEL (pixel), PLINE (line), PRECT / PRECTF (rectangle, outline / filled), PCIRC / PCIRCF (circle, outline / filled), PCLEAR (clear screen), PBLIT (tile blit), and PTIMER / PNTIMER (timer functions). Example: PPIXEL X, Y, C draws a pixel at (X, Y) in color C.

#240 $F0 LSTEPM
In-memory loop step, a Forth accelerator. Increments the 4-byte loop counter at [FLX], compares it to the 4-byte limit at [FLX+4], and sets Z when they match. This enables a very tight count-from-X-to-Y loop at the cost of an 8-byte counter/limit in memory:

    LDFLX $F000       ; 8 byte loop data start
    LDA #1            ; start at 1
    STA [FLX]         ; write starting counter at first four bytes
    LDA #1000         ; go until 1000
    STA [FLX+4]       ; write finish (until) counter at second four bytes
loop:
    LSTEPM            ; INC N1, if N1==N2 set Z=1
    JNZ @loop

Unlike a DEC loop it counts upward and supports an arbitrary start. The generalized form of this is LSTEP which counts downwards instead.

Only used by Forth. It is recommended to use LSTEP instead; this instruction is a canidate for removal.

#241 $F1 TTOS
Test top of stack (Forth). CD = AB; AB = [ELY]; ELY += 4; Z = (CD == 0).

#242 $F2 LIT
Push literal (Forth). Pushes AB to the stack and loads the next 4 bytes of the instruction stream into AB. Encoding: [242, b0, b1, b2, b3].

#243 $F3 LSTEP reg, @addr
Loop step, the generalized Forth accelerator: a decrement-and-branch in one opcode, inspired by the VAX SOB (subtract one and branch) and the 68000 DBcc.

    LDC #1000       ; loop range
loop:
    LSTEP C, @loop