KERNAL I/O Routines

JSR $FFD2 prints a character. It did so on the original Commodore PET, on the VIC-20, the Commodore 64, the Plus/4 and the C128, because Commodore made a promise about that address and kept it. The top page of each machine’s ROM holds a table of jump instructions, one for each operating-system service, and while the code behind them moved from machine to machine and from one ROM revision to the next, the table stayed where it was. Commodore called the whole arrangement the KERNAL.

The Commodore 64 Programmer’s Reference Guide sets out the reasoning. The KERNAL is “the operating system of the Commodore 64 computer” and, more precisely, “a standardized JUMP TABLE to the input, output, and memory management routines in the operating system”. The routines themselves “may change as the system is upgraded. But the KERNAL jump table will always be changed to match.” A program that calls the table rather than the code behind it keeps working “if the KERNAL or BASIC is changed”, and is easier “to translate … from one Commodore computer to another”.

The spelling is Commodore’s own. Jim Butterfield, writing in 1984, said its origin “seems to be lost in legend”: “it was originally an acronym, standing for something like ‘Keyboard Entry Read, Network and Link’”. He kept “Commodore’s word” rather than correct it to “kernel”.

Fast facts

• Where: 39 entry points, three bytes apart, from $FF81 to $FFF3. The guide places the table “on the last page of memory, in read-only memory”.
• What each entry is: a JMP instruction. Twenty-nine jump straight into ROM. Ten jump indirectly through addresses held in RAM at $031A–$032D, and LOAD and SAVE take their own RAM detours through $0330 and $0332.
• How to call one: put the arguments in the registers, JSR to the table entry, and check the carry flag on return. A routine that fails sets carry and leaves an error number in the accumulator.
• Devices: 0 keyboard, 1 Datassette, 2 RS-232, 3 screen, 4 printer, 8 disk drive. Device numbers run from 0 to 31, and “device numbers 4 or greater automatically refer to devices on the serial bus”.
• Who else uses it: BASIC. Its OPEN, LOAD, SAVE, PRINT and GET go through the same table, so a program calling the KERNAL is using the same services BASIC does.

The common entry points

The names are the ones the Programmer’s Reference Guide uses.

Opening a channel

Most KERNAL I/O follows the same pattern as BASIC’s OPEN: name the file with SETNAM, give it a number, a device and a secondary address with SETLFS, call OPEN, then point input or output at it with CHKIN or CHKOUT. From then on CHRIN and CHROUT read and write that file instead of the keyboard and screen, until CLRCHN puts them back.

This program does the machine-code equivalent of OPEN 15,8,15:INPUT#15,... and prints the disk drive’s status message. It is written for the ACME assembler and starts at $C000 (49152), a block BASIC leaves alone; run it with SYS 49152.

SETLFS = $ffba
SETNAM = $ffbd
OPEN   = $ffc0
CLOSE  = $ffc3
CHKIN  = $ffc6
CLRCHN = $ffcc
CHRIN  = $ffcf
CHROUT = $ffd2
READST = $ffb7

        * = $c000

        lda #0          ; no file name
        jsr SETNAM
        lda #15         ; logical file 15
        ldx #8          ; device 8, the first disk drive
        ldy #15         ; secondary address 15: the command channel
        jsr SETLFS
        jsr OPEN
        bcs done        ; carry set: error number in A
        ldx #15
        jsr CHKIN       ; take input from file 15
        bcs done
loop    jsr CHRIN       ; one byte from the drive
        jsr CHROUT      ; output is still the screen
        jsr READST
        beq loop        ; stop at end of file or on an error
done    jsr CLRCHN      ; keyboard and screen again
        lda #15
        jmp CLOSE       ; close file 15 and return

On a C64 with a 1541 that has just been switched on, it prints 73,CBM DOS V2.6 1541,00,00, the drive’s power-on message. READST returns a non-zero status once the drive has sent the last byte of the message, which ends the loop. The program assumes a drive is connected: with nothing on the serial bus, CHKIN sends the command to talk and then waits indefinitely for a reply.

The vectors in RAM

Ten of the table’s jumps are indirect: JMP ($0326) rather than JMP $F1CA. At power-on the KERNAL fills the vectors at $031A–$032D with the addresses of its own routines, and RESTOR puts them back. Because they are in RAM, a program can point any of them somewhere else, and every caller, BASIC included, follows.

Sheldon Leemon’s Mapping the Commodore 64 gives the purpose: “By changing the vectors to these routines, it is possible to support new I/O devices, such as an IEEE disk drive used through an adapter.” It also gives the warning. Some of these routines run under interrupts, so “it is dangerous to change these vectors without first turning off all interrupts”; the KERNAL’s VECTOR routine swaps the whole block at once.

The LOAD vector is the one that mattered most in practice. A disk fastloader cartridge points $0330 at its own code, so an ordinary LOAD"NAME",8 runs the cartridge’s faster routine without the program or the user doing anything different. Changing $0328 changes what counts as the RUN/STOP key, which is how a program disables it.

Devices and the user port

Device 2, RS-232, is not a chip. The KERNAL does the serial conversion itself: its RS-232 “byte and bit level handlers run under the control of the 6526 CIA #2 device timers and interrupts”, and the signals come out on the user port, which is wired to that CIA, at 0 to 5 volt TTL levels rather than true RS-232 voltages. Opening an RS-232 channel also takes 512 bytes from the top of BASIC memory for its two buffers, and the guide warns that if the space is not free, “the end of your program will be destroyed”.

The screen (3) and keyboard (0) are devices like any other, so a program that writes through CHROUT can send the same output to a printer or a disk file by opening a different device and calling CHKOUT. BASIC’s CMD command does exactly this.

One table, several machines

The table is older than the C64. Even the original PET’s ROM has fifteen jumps at $FFC0–$FFEA, the block where the C64 keeps OPEN, CHKIN, CHROUT, GETIN and their neighbours, and later PET ROMs add more entries below it. The VIC-20’s table begins at $FF8A, without the three initialisation entries. The Plus/4 and C16 have all 39 at the C64’s addresses, and the C128 keeps them and adds nineteen more below $FF81. Butterfield could tell readers of his 1984 book that the routines “are always at the same addresses, and perform in about the same way regardless of which Commodore machine is used: PET, CBM, Commodore 64, PLUS/4, or VIC-20.”

The C64 added one routine to help: SCREEN, which returns the screen size so that a program can work out which machine it is on. The guide says it was “implemented on the Commodore 64 to help upward compatibility of your programs”.

See also

• Commodore BASIC V2
• Disk Fastloaders
• How a Cassette Becomes a Game
• CIA
• 6510
• Commodore 64