C64 KERNAL ROM: Making Sense

The KERNAL is the heart of the Commodore 8-Bit computer family. Although each machine's KERNAL is slightly different, there is also substantial overlap in code and design.

The C64's KERNAL provides a standard jump table with 39 routines from $FF81 and $FFF3. The order of the entries in the jump table is stable, but not particularly logically organized. Most websites and books, including the C64 Programmers Reference Guide, list the routines in alphabetical order, or in the order in which they appear in the jump table. This makes it easy to find the details of any routine, if you already know which routine you want to use, but it can often lead to confusion trying to understand the relationship between the routines. Especially because many of them have similar sounding names, and in some cases similar functionality.

To improve clarity, and facilitate understanding of how the KERNAL should be used, I have grouped the routines into 7 conceptual KERNAL modules, shown in the table below.

C64 OS provides includable assembly headers which define labels for the KERNAL routines in each module. C64 OS itself is an extension of the KERNAL, and relies on the KERNAL for many tasks. For example, C64 OS's File module adds a thin abstraction layer over the KERNAL's file table and logical file numbering system. A C64 OS application that makes use of C64 OS File References can extract the logical file number from the file and use it to make manual KERNAL calls. The relationship of the KERNAL ROM to C64 OS, including a compatibility table, is discussed at the end of this post.

KERNAL Modules

I have never seen the routines grouped as these 7 modules before, but to me, they most logically and thematically fall into these groupings, which helps to understand how to use them.

File (6 Routines)

Among other things, the KERNAL recognizes 6 device types. Two of those device types, the Keyboard and Screen, it implements directly. And it provides implementations of the communications protocols with the other devices which may or may not be connected to the computer.

Each device is referenced by a unique device number, from 0 to 30. Device types are recognized by their fixed address or the address range they fall within. Some devices also support a secondary address, which is used to send it low-level commands.

The KERNAL provides a thin abstraction layer to reference devices, and in some cases subdivisions of a device. The abstract entity is called a logical file. Commodore may have been influenced by Unix, which treats everything—including devices—as files. On some devices, such as a Datasette or Disk Drive, logical files can also be associated with actual files, which are named collections of data stored on physical media.

The 4 main File routines allow you to open and close logical files by associating them with an underlying physical device, and optionally with a secondary address on that device. Each logical file is assigned a unique file number from 1 to 127. The KERNAL supports opening up to 10 logical files simultaneously.

There are 2 additional File routines that allow you to load and save data to and from Datasette or Disk Drive, to and from memory. Attempting to load or save to or from any other device type results in an Illegal Device Number error.

File Routines

I/O (8 Routines)

The KERNAL operates on a general design principle; data is streamed from the system's input channel to the output channel. Opened logical files (see File Module) are assigned to the input and output channels. Attempting to assign an input-only device to the output channel or vice versa results in an error. (See Devices Table)

The default configuration assigns the keyboard as the input device and the screen as the output device. This is why, when a C64 is turned on, typing on the keyboard results in characters appearing on the screen.

The 8 routines in the I/O KERNAL module assign logical files to channels, read and write bytes to and from the channels, check for channel status messages and restore default channel assignments.

Status Values

I/O Routines

IEC (9 Routines)

A major part of the KERNAL is dedicated to IEC serial bus communications. The IEC bus is a variant of IEEE-488, used by Commodore, which you can read about here. The bus allows multiple devices to be chained together to one C64, in a master/slave arrangement. The C64 is the master, which tells individual slave devices when to talk and when to listen.

All device numbers from 4 to 30 are assigned to the IEC serial bus, although this can be overridden by use of the vectors specified for routines in the File and I/O KERNAL modules.

Each device must have its unique device number manually configured. In addition to the device number, the IEC protocol can send a secondary address and command string, the meaning and use of which are device specific. The 9 IEC KERNAL routines implement this protocol by timed manipulation of CIA 2. It is rarely necessary to use any of these calls directly, as they are abstracted and called automatically by higher-level routines in the File and I/O KERNAL modules.

For maximum device compatibility, direct use of these routines should be avoided, unless the device type is detected and determined to actually reside on the physical IEC bus.

IEC Routines

MEMORY (6 Routines)

The memory map differs between the various Commodore 8-Bit computers. They have different amounts of ram and their I/O chips reside at different places. Additionally, BASIC is by default configured to use as much free memory as is available.

These 6 Memory routines allow you to reliably locate where the I/O chips are mapped, test and determine the quantity of RAM available, configure how much and in what range of that RAM BASIC should use. It also helps you to configure the KERNAL's ram vectors, by backing them up, replacing them with a custom table, and restoring them to defaults.

Memory Routines

KEYBOARD (3 Routines)

A C64 has a built-in keyboard, however it is just a matrix of switches connected to Ports A and B of CIA 1. (See How the C64 Keyboard Works.) The KERNAL implements all of the software routines necessary to make the keyboard a device. The matrix scanning routine is part of the KERNAL's IRQ interrupt service routine, which converts key presses into PETSCII characters and stores them in the 10-byte keyboard buffer ($0277–$0280).

RS-232 shares some properties in common with the keyboard. Namely, there is no custom RS-232 hardware, there is only CIA 2 which is connected to the user port. All RS-232 behavior is implemented by software routines provided by the KERNAL and the NMI interrupt service routine. Similarly to the keyboard buffer, the KERNAL puts incoming RS-232 bytes into a buffer in memory. The location of the RS-232 buffer, though, can be configured.

There are two routines for reading a byte from the input channel, GETIN and CHRIN. These routines have different behavior and different error conditions depending on the input device. GETIN has unique behavior only for the keyboard (Device 0) and RS-232 (Device 2). For all other devices, GETIN is merely an alias to CHRIN. Therefore, I have chosen to categorize GETIN in the keyboard KERNAL module, even though it can also be used with RS-232, or even with the other devices.

When GETIN is used with the keyboard as the input device, it returns the next character waiting in the keyboard buffer. If the buffer is empty, it returns 0 (ASCII NULL). It works the same way for RS-232, returning the next byte in the RS-232 buffer, or 0 if the buffer is empty. Using CHRIN with the keyboard enters a special routine that is used primarily by BASIC for getting data for INPUT statements. When BASIC calls CHRIN to input from the keyboard, the keyboard buffer is continuously output to the screen until return is pressed. This allows the user to populate an entire line buffer (80 characters) before the data is processed.

Keyboard Routines

SCREEN (4 Routines)

Just as the keyboard is transformed into a device by routines in the KERNAL, so is the screen. The VIC-II chip, when in character mode, merely renders whatever screencodes are in the 1000 bytes of screen memory, with the 1000 bytes of color data in color memory.

A non-trivial amount of code in the KERNAL is devoted to implementing the screen editor. The screen editor consists of a table of 80-column logical lines which are drawn and moved through screen memory. Positioning of the cursor, inserting new characters in a line, manipulating color memory, PETSCII control codes, and insertion, quotation and reverse modes, are all part of the screen editor.

The screen editor maintains a positional cursor, which allows the screen to be abstracted into a generic I/O device. Reading a byte from the screen finds the screencode at the position of the cursor, and converts and returns its PETSCII equivalent, then advances the cursor. Writing to the screen as a device works similarly. Writing a PETSCII character converts the character to a screencode, and will reverse it if reverse mode is on, and then outputs the character to screen memory at the position of the cursor, then advances the cursor.

The 4 SCREEN routines are used to initialize the screen, reads its dimensions (which vary depending on the Commodore 8-Bit computer), read and move the cursor, and enable or disable the messages (two different types) that the KERNAL prints to the screen as user feedback.

Screen Routines

TIME (3 Routines)

The KERNAL keeps track of time using a 3-byte Jiffy Clock. A Jiffy is a short unit of time, in computing normally the length of time between two ticks of the system timer interrupt, or in electronics the cycle period of the AC mains. On an NTSC C64 (not sure about PAL), CIA 1 is configured to produce an interrupt every 1/60th of a second, which corresponds closely with the screen refresh rate and the cycle period of North American AC power. On every interrupt, the Jiffy Clock is ticked up. When it reaches the equivalent of 24 hours worth of jiffies, it is reset to zero.

There is a bug in the timer which, even if left to run under perfect conditions, would lose one Jiffy (1/60th of a second) per 24 hour period. In practice, this is completely irrelevant because the Jiffy Clock stops ticking entirely any time the IRQ is temporarily masked. Despite this general unreliability as a realtime clock, the Jiffy Clock is useful in a variety of small ways.

The 3 TIME routines allow you to read and set the Jiffy Clock. And, if you reimplement the IRQ interrupt service routine, calling UDTIM in your ISR will tick the Jiffy Clock. The STOP routine, in the Keyboard KERNAL module, does not scan the keyboard. It checks a stop key flag. This flag is set by the UDTIM routine. If UDTIM is not being regularly called, therefore, STOP will not work as expected.

Time Routines

The KERNAL and C64 OS

The C64's KERNAL ROM is used by C64 OS. The default state expects the KERNAL to be patched in. However you are free to patch it out at any time, and are not required mask IRQs when you do so. In fact, it would detrimental to mask IRQs unless you absolutely have to. C64 OS will automatically patch the KERNAL back in during the IRQ service routine, and restore its state upon returning to your code. However, if you patch the KERNAL out, you are required to patch it back in before returning to or calling system code, as the rest of the system expects it to be patched in.

Despite using the KERNAL, parts of it are irrelevant under C64 OS, and parts of it have been superseded by newer implementations in the C64 OS KERNAL.

FILE

The FILE module is used pretty much as normal. The C64 OS File module provides a thin wrapper around most of these calls. When using LOAD, you have to be careful that the data loaded in will not overwrite memory that is already allocated. If you do use LOAD carefully, you must also use the C64 OS Memory routine PGMARK to mark as allocated the pages of memory that were loaded into.

I/O

The I/O module is used almost the same in C64 OS. It is unsafe to use CLALL, however, as you cannot be sure that a Utility, or the System itself, does not have a file open. If you call CLALL, all files will be closed but their corresponding C64 OS file references will be left marked as open, with invalid Logical File Numbers assigned to them.

You should also never call IOINIT, as this would change the configuration of the CIA and IRQ handler and likely crash the system. C64 OS provides a clean way to quit back to BASIC.

IEC

The IEC routines interact explicitly with the IEC bus. For maximum compatibility with other drive types, these routines should be avoided. For example, the IDE64 programming documentation states that you must not use any of these routines. For C64 OS, I would follow that practice. C64 OS routines never call these routines, prefering to call FILE and I/O routines instead.

There is, however, a way to use these routines safely. C64 OS maintains a detected drives table, containing device numbers corresponding with detected physical drive types (1541, 1571, 1581, CMD HD, CMD RamLink, CMD FD, IDE64, SD2IEC, etc.) If you consult that table, and determine that the drive is on the IEC bus, it's reasonably safe and compatible to use these IEC specific routines.

MEMORY

This part of the KERNAL is more or less irrelevant. MEMTOP and MEMBOT are specifically for configuring what BASIC can use. RAMTAS is called as part of starting up and resetting a C64. IOBASE only made sense for maintaining BASIC program compatibility between different Commodore 8-Bit computers. IOBASE on a C64 hasn't changed in 35 years, and isn't going to change any time soon. RESTOR should not be used, as C64 OS overrides some of the KERNAL's vectors. Restoring these to their defaults will cause problems. If you are careful and know what you're doing, you can use VECTOR, although it is recommended to use VECTOR to backup the current VECTOR table first, before using it to replace them with your own.

The KERNAL ROM's memory module is mostly irrelevant, not because memory management has become less important, but because C64 OS provides a Memory module that is significantly more sophisticated, which entirely supersedes these KERNAL routines.

KEYBOARD

The KERNAL ROM has only very basic support for input devices. It does not provide input drivers for anything on the two built-in controller ports. It does not provide input for joysticks or mice, and its keyboard input system is limited only to populating the keyboard buffer with PETSCII values. If two keyboard combinations resolve to the same PETSCII value (Control M and RETURN both resolve to $0D), there is no way to distinguish the two.

C64 OS completely replaces SCNKEY with a new keyboard matrix scanner, and divides the results into two types of events: Key Commands, and Printable Key Events. Printable Key Events are buffered in the same 10-key keyboard buffer used by the KERNAL, and can be retrieved with GETIN. However, this call removes the character from the buffer. C64 OS provides routines to allow you to read the current event in the buffer, without removing it. This is used to allow the event to propagate through different levels of the OS, before being removed at the end of the current iteration of the main event loop. C64 OS also provides mouse input, and will likely provide joystick input drivers as well.

STOP can be used as normal. If it interrupts one of C64 OS's FREAD or FWRITE routines, a C64 OS exception will be thrown.

SCREEN

The KERNAL's screen editor is not used by C64 OS. If the Screen device is set as the current input or output device, it will be used as a pipe to read or write data from or to a Toolkit widget that is in keyboard focus. Selecting the Screen as the output device, while a Toolkit text area is in focus, and then repeatedly calling CHROUT will insert characters into the text area.

CINT should never be used. SCREEN can be used, although it is not terribly useful. C64 OS provides SCREEN_COLS and SCREEN_ROWS constants. PLOT should never be used, as it manipulates screen editor variables in workspace memory that are used for other purposes by C64 OS. SETMSG is used by the C64 OS Booter to disable KERNAL messages, and it should not be used to turn messages back on.

TIME

C64 OS uses the same Jiffy Clock as the KERNAL ROM. Therefore, it is safe to call RDTIM and SETTIM. However, C64 OS calls UDTIM inside a larger context, which includes updating other variables. You should avoid calling UDTIM manually.

C64 OS also provides a Timers module. You can read more here about how timers work in C64 OS. The Timers module mostly obviates the need to manually use the Jiffy Clock for common timer functions.

KERNAL Compatibility in C64 OS

Do you like what you see?

You've just read one of my high-quality, long-form, weblog posts, for free! First, thank you for your interest, it makes producing this content feel worthwhile. I love to hear your input and feedback in the forums below. And I do my best to answer every question.

I'm creating C64 OS and documenting my progress along the way, to give something to you and contribute to the Commodore community. Please consider purchasing one of the items I am currently offering or making a small donation, to help me continue to bring you updates, in-depth technical discussions and programming reference. Your generous support is greatly appreciated.

Greg Naçu — C64OS.com

Want to support my work?

C64 OS version 1.04 is now available

The best way to help C64OS.com grow and continue is to purchase a commercial copy of C64 OS version 1.04.

Join the growing C64 OS user community. Take advantage of the powerful and useful features available now, and get access to run new and future software made for C64 OS.

Learn More Order Now

C64OS.com is hosted on a Digital Ocean droplet.

Digital Ocean is a cloud hosting platform, built for developers. They make it simple to get started. They have intuitive administrative tools and reasonable prices. And they can scale as your needs grow.

If you sign up with this referral link, you'll get a $100 credit, and after you've spent $25, I'll get $25. If you are looking for a cloud platform to host your website or web app, this is win-win.

Sign up for Digital Ocean with this refereral link.
Save money and help C64OS.com at the same time.

No, thank you.

Want to support my hard work? Here's how!