C64_SKILLS/.ai/skills/kernal-jump-table/SKILL.md

Skill: KERNAL Jump Table and C64 Device I/O

Use this skill when

The task involves screen/keyboard I/O, files, disk, printer, tape, RS-232, serial bus, LOAD, SAVE, OPEN, CLOSE, GETIN, CHROUT, or KERNAL calls from assembly.

Core principle

Prefer KERNAL jump-table calls at the top of memory. They are stable public entry points and safer than jumping into undocumented ROM internals.

Common KERNAL calls

Address	Name	Purpose
$FF81	CINT	Initialize screen editor
$FF84	IOINIT	Initialize I/O devices
$FF87	RAMTAS	Initialize RAM/test memory
$FF8A	RESTOR	Restore default vectors
$FF8D	VECTOR	Read/set RAM vectors
$FF90	SETMSG	Control system messages
$FF93	SECOND	Send secondary address after LISTEN
$FF96	TKSA	Send secondary address after TALK
$FF99	MEMTOP	Read/set top of memory
$FF9C	MEMBOT	Read/set bottom of memory
$FF9F	SCNKEY	Scan keyboard
$FFA2	SETTMO	Set serial timeout
$FFA5	ACPTR	Input byte from serial bus
$FFA8	CIOUT	Output byte to serial bus
$FFAB	UNTLK	Send UNTALK
$FFAE	UNLSN	Send UNLISTEN
$FFB1	LISTEN	Command device to listen
$FFB4	TALK	Command device to talk
$FFB7	READST	Read I/O status byte
$FFBA	SETLFS	Set logical file, device, secondary address
$FFBD	SETNAM	Set filename pointer and length
$FFC0	OPEN	Open logical file
$FFC3	CLOSE	Close logical file
$FFC6	CHKIN	Set input channel
$FFC9	CHKOUT	Set output channel
$FFCC	CLRCHN	Restore default I/O channels
$FFCF	CHRIN	Input character
$FFD2	CHROUT	Output character
$FFD5	LOAD	Load RAM from device
$FFD8	SAVE	Save RAM to device
$FFDB	SETTIM	Set system clock
$FFDE	RDTIM	Read system clock
$FFE1	STOP	Test STOP key
$FFE4	GETIN	Get character from keyboard/input buffer
$FFE7	CLALL	Close all channels/files
$FFEA	UDTIM	Update software clock
$FFED	SCREEN	Get screen size
$FFF0	PLOT	Read/set cursor position
$FFF3	IOBASE	Return I/O base address

CHROUT example

        lda #'A'       ; assembler may translate ASCII differently; PETSCII 65 works for A
        jsr $ffd2      ; CHROUT
        rts

GETIN example

wait:   jsr $ffe4      ; GETIN
        beq wait       ; zero means no key available
        jsr $ffd2      ; echo key
        rts

Opening a device from ML

Typical sequence:

1. SETLFS with logical file, device number, secondary address.
2. SETNAM with filename length and pointer.
3. OPEN.
4. CHKIN or CHKOUT.
5. Use CHRIN / CHROUT.
6. CLRCHN.
7. CLOSE.

Device numbers

Device	Meaning
0	Keyboard
1	Cassette
2	RS-232
3	Screen
4-5	Printers, usually serial bus
8-11	Disk drives, commonly 8 for first 1541

Agent checklist

When writing KERNAL-call assembly:

1. State required registers before call.
2. State affected registers/status after call if important.
3. Use jump table names in comments.
4. Restore channels with CLRCHN after redirected I/O.
5. Close files that were opened.