# 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

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

## GETIN example

```asm
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.