C64_SKILLS/.ai/skills/interrupts-reset/SKILL.md

Skill: Interrupts, Reset, IRQ, NMI, BRK, and Vectors

Use this skill when

The task involves IRQ/NMI handlers, raster interrupts, STOP+RESTORE, reset behavior, BRK, vector patching, or safe interrupt disabling.

Core concepts

• RESET loads the CPU program counter from vector $FFFC-$FFFD.
• IRQ/BRK loads from $FFFE-$FFFF after pushing PC/status to stack.
• NMI loads from $FFFA-$FFFB and cannot be masked by the I flag.
• C64 RAM vectors allow patching system behavior without changing ROM.

Important RAM vectors

Decimal	Hex	Meaning
788-789	$0314-$0315	IRQ vector
790-791	$0316-$0317	BRK vector
792-793	$0318-$0319	NMI vector
768-779	$0300-$030B	BASIC vectors: error, main loop, tokenize, list, execute, evaluate

Safe IRQ hook pattern

1. SEI.
2. Save old vector.
3. Store new low/high bytes to $0314/$0315.
4. CLI.
5. Handler saves registers.
6. Handler acknowledges its interrupt source.
7. Handler restores registers.
8. Handler jumps to old IRQ or normal KERNAL IRQ path.

Minimal handler skeleton

irq:    pha
        txa
        pha
        tya
        pha

        ; acknowledge source here, e.g. VIC raster IRQ:
        lda #$01
        sta $d019

        ; do short, deterministic work

        pla
        tay
        pla
        tax
        pla
        jmp $ea31      ; normal KERNAL IRQ continuation on C64

Warnings

• Do not leave IRQ disabled unless building a controlled loader/demo effect.
• NMI is used by RESTORE and CIA #2; avoid breaking STOP+RESTORE recovery unless intentional.
• Raster IRQ code must be short and cycle-aware.
• Always acknowledge the hardware source or the interrupt will immediately retrigger.

Agent checklist

1. State interrupt source: VIC-II, CIA #1, CIA #2, BRK, RESTORE/NMI.
2. Show vector write low byte then high byte while IRQ disabled.
3. Save/restore A, X, Y unless deliberately not needed.
4. Acknowledge interrupt flags.
5. Chain to old handler or document full replacement.