| name | c64-kernal |
| description | The Commodore 64 KERNAL ROM jump table and its user-callable routines: the fixed $FFxx entry points, each routine's purpose and register inputs/outputs, the carry-flag error convention and error codes, and the power-up sequence. Use this skill WHEN calling C64 OS routines from assembly: "print a character in 6510", "address of CHROUT/CHRIN/GETIN", "open a file with SETLFS and SETNAM", "the KERNAL I/O pattern", "what does set carry mean after a KERNAL call", "read the jiffy clock with RDTIM", "scan the STOP key". Pairs with c64-assembly, c64-memory-map, c64-io, c64-disk, and c64-tape. |
C64 KERNAL ROM Routines
The KERNAL is the C64 operating system. Its user-callable routines are reached
through a fixed jump table at the top of the KERNAL ROM ($FF81-$FFF5). Each
$FFxx address is a JMP to the real (version-specific) routine deeper in ROM.
Always call the $FFxx jump-table entry, never the actual ROM address. The
jump-table addresses are guaranteed stable across KERNAL revisions; the internal
routine addresses are not. This indirection is the whole point of the KERNAL.
JSR $FFD2 ; CHROUT — correct, version-proof
; JSR $E716 ; the real routine — DON'T; moves between ROM versions
Most-used routines
| Name | Addr | Purpose | Registers (in → out) |
|---|
| SETLFS | $FFBA | Set logical file #, device #, secondary addr | A=lfn, X=dev, Y=sec |
| SETNAM | $FFBD | Set filename | A=len, X/Y=name ptr (lo/hi) |
| OPEN | $FFC0 | Open a logical file | (after SETLFS+SETNAM); C/A=err |
| CLOSE | $FFC3 | Close a logical file | A=lfn |
| CHKIN | $FFC6 | Set an open file as input channel | X=lfn; C/A=err |
| CHKOUT | $FFC9 | Set an open file as output channel | X=lfn; C/A=err |
| CLRCHN | $FFCC | Restore default I/O channels | — |
| CHRIN | $FFCF | Input a char from current input channel | → A |
| CHROUT | $FFD2 | Output the char in A to current output channel | A=char |
| LOAD | $FFD5 | Load/verify RAM from device | A=0 load/1 verify, X/Y=addr; C/A=err |
| SAVE | $FFD8 | Save RAM to device | A=zp ptr to start, X/Y=end; C/A=err |
| GETIN | $FFE4 | Get a char from the keyboard queue (0 if none) | → A |
| CLALL | $FFE7 | Close all files & channels | — |
| CHKIN/CHKOUT/CLRCHN | (above) | channel management | |
| PLOT | $FFF0 | Read (C=1) / set (C=0) cursor X,Y | X=row, Y=col |
| SCNKEY | $FF9F | Scan the keyboard once | — |
| RDTIM | $FFDE | Read the jiffy clock (1/60 s) | → A/X/Y |
| SETTIM | $FFDB | Set the jiffy clock | A/X/Y |
| STOP | $FFE1 | Test the STOP key (Z=1 if pressed) | → Z, A |
| READST | $FFB7 | Read the I/O status word ST | → A |
| ACPTR | $FFA5 | Input a byte from the serial (IEC) bus | → A |
| CIOUT | $FFA8 | Output a byte to the serial bus | A=byte |
| TALK/LISTEN | $FFB4/$FFB1 | Command a serial device to talk/listen | A=dev |
| UNTLK/UNLSN | $FFAB/$FFAE | Untalk / unlisten the serial bus | — |
| SECOND/TKSA | $FF93/$FF96 | Send secondary address after LISTEN/TALK | A=sec |
| MEMTOP | $FF99 | Read (C=1) / set (C=0) top of memory | X/Y |
| MEMBOT | $FF9C | Read/set bottom of memory | X/Y |
| VECTOR | $FF8D | Read/set the RAM I/O vector table | C, X/Y=ptr |
| RESTOR | $FF8A | Restore default system & I/O vectors | — |
The full per-routine reference (purpose, communication registers, preparatory
routines, error returns, stack use, registers affected, description, example) is
in references/kernal-routines.md.
Worked I/O example: print a character
LDA #'H ; PETSCII code of the character
JSR $FFD2 ; CHROUT — to current output (default = screen)
The standard file-I/O pattern
To talk to a device (disk, printer, tape), the canonical sequence is:
SETNAM → SETLFS → OPEN → CHKIN/CHKOUT → CHRIN/CHROUT → CLRCHN → CLOSE.
; OPEN 1,8,2,"FILENAME" then write a byte, then close
LDA #fnamelen
LDX #<fname
LDY #>fname
JSR $FFBD ; SETNAM
LDA #1 ; logical file 1
LDX #8 ; device 8 (disk)
LDY #2 ; secondary address 2
JSR $FFBA ; SETLFS
JSR $FFC0 ; OPEN
LDX #1 ; logical file 1
JSR $FFC9 ; CHKOUT — make it the output channel
LDA #'X
JSR $FFD2 ; CHROUT — send a byte
JSR $FFCC ; CLRCHN — restore default channels
LDA #1
JSR $FFC3 ; CLOSE
RTS
Reading is symmetric: use CHKIN then CHRIN, checking READST ($FFB7) for
end-of-file/error after each byte. Device numbers: 0 keyboard, 1 tape, 2 RS-232,
3 screen, 4-7 printers/serial, 8+ disk drives. For the device-side usage of this
pattern see c64-io, c64-disk, c64-tape.
Error convention
After a KERNAL call, carry set (C=1) means error, and the accumulator holds
the error code:
| Code | Meaning |
|---|
| 0 | Routine terminated by the STOP key |
| 1 | Too many open files |
| 2 | File already open |
| 3 | File not open |
| 4 | File not found |
| 5 | Device not present |
| 6 | File is not an input file |
| 7 | File is not an output file |
| 8 | File name is missing |
| 9 | Illegal device number |
| 240 | Top-of-memory change (RS-232 buffer alloc/dealloc) |
JSR $FFC0 ; OPEN
BCS error ; carry set => A = error code above
Some I/O routines (CHRIN/CHROUT/serial) do not return these codes — instead
you must poll READST ($FFB7) for the ST status word (bit 6 = EOF, bit 7 =
device-not-present/timeout, etc.). See references/kernal-error-codes.md.
Power-up sequence (what runs at reset)
On reset the KERNAL: tests/sizes RAM and sets the tape buffer & screen via
RAMTAS; sets up the I/O devices and CIA timers via IOINIT; initializes the RAM
I/O vectors via RESTOR; sets the screen editor via CINT; then hands off (the
BASIC ROM cold-start). Full detail in references/kernal-routines.md
("KERNAL Power-Up Activities").
Calling KERNAL from BASIC
You can drive these from BASIC with SYS plus the register-pass locations:
POKE 780,A : POKE 781,X : POKE 782,Y : SYS addr. See c64-assembly for the
SYS/USR convention and the $030C-$030F register locations.
Gotchas
- Call the
$FFxx vector, not the internal ROM routine.
- The KERNAL ROM must be banked in (HIRAM=1 at
$0001) to reach $FFxx. If you
bank it out for RAM, you lose the jump table — see c64-memory-map.
- CHROUT to the serial bus sends to all open serial output channels; CLRCHN
or close the others first.
- Many routines need preparatory calls (OPEN needs SETLFS+SETNAM first); check
the "Preparatory routines" line in each entry.
- SAVE takes a zero-page pointer in A to the start address (not X/Y), with
X/Y holding the end address.
How to read the references
references/kernal-routines.md — the complete routine-by-routine
reference (PRG Ch5): "The KERNAL", the power-up activities, "How to Use the
KERNAL", and every User Callable routine with call address, communication
registers, preparatory routines, error returns, stack use, registers affected,
description, and an assembly example. Read for the exact contract of any
routine.references/kernal-error-codes.md — the carry-flag error convention and
the numbered error-code table. Read when interpreting a failed KERNAL call.
For the calling convention from BASIC/ML see c64-assembly; for where these
addresses sit and how to keep the KERNAL banked in see c64-memory-map; for
real file/device workflows see c64-io, c64-disk, c64-tape.
