Programming the MEGA65 — Chapter 11: MEGA65 ROM Guide

Oct 4, 2026 · Updated Oct 11, 2026 · @Craig Taylor

Introduction

The MEGA65's ROM holds the KERNAL, the screen editor, BASIC 65, the DOS, the monitor, the character sets, and a complete set of C64 ROMs for C64 mode, in a 128KB image. Unlike the C64's, it is still changing: new releases appear regularly, fixing bugs and adding features.

That makes the question "which parts can I call?" more important than it was on the C64. On a C64, programmers called almost any ROM routine they found, because the ROM never changed. On the MEGA65, a routine that is not part of an official interface may move in the next release. The MEGA65 team treats the KERNAL jump table as officially supported, along with certain documented facts about the memory layout such as $2001 being the start of BASIC (Dan Sanderson, MEGA65 Digest). Almost everything else is internal.

This chapter therefore concentrates on the stable interfaces:

• How the ROM is organised and how to tell which version is installed
• The KERNAL jump table, including the C65 additions
• The RAM vectors for interrupts and I/O
• The Hypervisor's DOS functions
• Practices for writing code that survives ROM updates

There is no complete map of BASIC 65's internal routines here, of the kind West gave for the C64's BASIC. Such a map would be out of date within months, and code built on it would break with it. Where earlier chapters needed BASIC internals, such as the USR function's conversion routines, the safest course is to check the documentation for the ROM version in use.

ROM Layout and Versions

The ROM is a single 128KB image, loaded from the SD card into chip RAM at $20000-$3FFFF and write-protected, as Chapter 5 described. Because it is an ordinary file, the installed version is simply whichever image the SD card holds, and different machines may run different versions.

Where things are

The ROM is a 128KB image that the MEGA65 holds at $20000-$3FFFF, in banks 2 and 3. Its arrangement comes from the C65's. The C65 brings its system ROM into the CPU's window using both banking mechanisms: $D030 for some regions, and MAP for the rest (MEGA65 ROM issue #62). ROM 920422 is laid out as follows, according to the ROM's build files:

Treat this table as orientation only. The ROM's internal arrangement is not an interface, MEGA65 releases have reorganised it, and code should reach the ROM only through the jump table and vectors described in the following sections.

Identifying the version

MEGA65 ROM versions are six-digit numbers such as 920422, shown in the start-up banner. Release and beta ROMs are numbered 92xxxx and are meant to stay compatible with existing software. Development ROMs, numbered 99xxxx, are built separately and may include experimental features that break existing software. The two series run side by side; most owners should run a 92xxxx ROM (MEGA65 ROM source, README; owners can request access through the MEGA65 ROM issue repository).

The ROM version matters most to programs that depend on behaviour added in a particular release, such as the BASIC 65 features dated in Chapter 6. Such programs should say which version they need. Programs that keep to the interfaces in this chapter rarely need to check at all.

As on every Commodore machine since the C64, the byte at $FF80 is set aside for a KERNAL version number (pagetable.com). On the MEGA65 it is always $FF, the C65's "not released" value, so it says nothing about the ROM version (MEGA65 ROM source, jump table).

From ROM 920417, the KERNAL's VERSIONQ routine at $FF2F returns the six-digit ROM version shown in the banner (see Extended entries). It loads the version into Q, the 32-bit register made up of A, X, Y and Z, as a little-endian binary integer: 920422 is $000E0B66. A single STQ stores it in four bytes:

        jsr $ff2f       ; VERSIONQ
        stq version     ; four bytes, low byte first

On a ROM older than 920417, $FF2F is not VERSIONQ, and calling it is likely to crash the program. At the time of writing, 920417 and later are beta releases; the latest stable ROM is 920413 (MEGA65 ROM change log).

The version is also stored as text. The ROM image, which the MEGA65 holds at $20000, has the letter V followed by the six ASCII digits at $20016-$2001C, for example V920422. Reading this string is discouraged: its address is not part of the ROM's supported interface, and it may not work with future ROM versions. A program that must also run on ROMs older than 920417 can fall back on it, accepting that risk.

The KERNAL Jump Table

The jump table is a list of JMP instructions at the top of the KERNAL, each at a fixed address. Programs call the fixed address, and the JMP there leads to wherever the routine currently lives. When a new ROM moves a routine, only the JMP changes.

The MEGA65-mode KERNAL derives from the C65's, which in turn derives from the C128's. Its table has two parts: the standard entries shared with the C64, and an extended block below them inherited from the C128 by way of the C65, to which the MEGA65 has added entries of its own.

Standard entries

These 39 entries occupy the same addresses as on the C64, and most do the same jobs (pagetable.com). Four addresses hold different routines on the MEGA65: KEY, MONEXIT, ScanStopKey and SCRORG take the places of the C64's SCNKEY, SETTMO, UDTIM and SCREEN. MEMTOP, MEMBOT and IOBASE are reserved. Some routines that keep their C64 names take different arguments: the clock routines work in BCD hours, minutes, seconds and tenths. PLOT keeps the C64's registers, with the line in X and the column in Y, but measures them from the top-left corner of the current window rather than of the screen. The inputs and outputs in the table come from the MEGA65 Book's KERNAL Jump Table appendix, checked against the ROM source. Where they disagree, as for PLOT, the table follows the ROM.

X/Y means a 16-bit value with the low byte in X and the high byte in Y. C is the carry flag: routines that can fail return with C=1 and an error code in A. A dash means the routine takes no input or returns no result. Unless the table says otherwise, assume a KERNAL routine changes every register and flag. All of them expect the KERNAL's normal memory map, with the base page register B set to $00.

SCRORG is worth using on the MEGA65, where the text screen may be 40 or 80 columns wide and 25 or 50 rows high, and the WINDOW command can shrink the area the editor uses. A program that asks SCRORG for the window's size and position works in every mode.

Extended entries

The C65 kept most of the C128's additions, dropped three that made sense only on a C128 (DMA_CALL, DLCHR and GETCFG), and added MONITOR_CALL. The removals moved many entries to new addresses, so they do not match the C128 (pagetable.com). The MEGA65 has extended the table downwards: the entries from $FF2F to $FF4A are its own additions and are not on the C65. They arrived between ROM 920398 and 920417, as the table notes, so a program that uses one should check the ROM version first; KEYLOCKS was renamed SYSFLAGS in ROM 920418 (MEGA65 ROM change log).

The last six are not among the entries the C65 moved, so they keep their C128 addresses. PRIMM at $FF7D is confirmed on the MEGA65 (MEGA65 Digest). The far-memory calls do not take the same arguments as on the C128: LDA_FAR, STA_FAR and CMP_FAR take the bank in the Z register, and JSRFAR and JMPFAR take their target and register values from base page locations $02-$09. The inputs and outputs come from the MEGA65 Book's KERNAL Jump Table appendix.

Where the far calls run

The far-call routines don't run from ROM. They exist to change the memory map, and code running in the KERNAL at $E000-$FFFF could map itself out halfway through. So the KERNAL's start-up routine copies them into bank 0 RAM from $0380, below $2000, where they stay visible whatever the mapping, and the jump-table entries at $FF6E (JSRFAR) and $FF71 (JMPFAR) simply jump to those copies. Disassembling $FF6E therefore shows a JMP into page 3 (MEGA65 ROM source, install and the RAM-copied far-call block).

Always call them through the jump table, never at their RAM addresses. The jump-table addresses are the ROM's promise; where the copies land is an internal detail, decided by the size of the code ahead of them, and it changes when that code changes. It has already happened between two released ROMs. For SYS TO, ROM 920414 added a MAP-offset version of JSRFAR, which BASIC reaches through the reserved entry $FF38, and four bytes of code to support it. On the stable ROM 920413, JMPFAR's copy starts at $03BB; on 920414 and later it starts at $03BF, and the MAP-offset entry at $0397 does not exist at all (MEGA65 ROM change log; MEGA65 ROM source). A program that called $03BB directly would work on the stable ROM and jump into the middle of an instruction on every beta since, and the reverse holds for a program built against a beta. Calling $FF71 works on both. As with every jump-table call, the KERNAL ROM must be mapped at $E000-$FFFF to reach the entry.

Example: printing with PRIMM

PRIMM reads the bytes after the JSR as a string, prints them, and returns to the instruction after the terminating zero:

        jsr $ff7d       ; PRIMM
        .text "HELLO, MEGA65", 13, 0
        rts             ; execution continues here

It is the shortest way to print a fixed message from machine language, and it needs no pointer setup.

RAM Vectors

The jump table lets programs call the KERNAL. The RAM vectors let programs change what the KERNAL does. Each is a two-byte address in RAM that the KERNAL jumps through at a key moment, such as handling an interrupt or outputting a character. Pointing a vector at your own routine inserts that routine into the KERNAL's work.

The standard vector table

The C65's vector table at $0314-$0333 follows the C64 and C128 layout, with the vector the C64 left unused now serving the monitor (pagetable.com). The MEGA65 KERNAL inherits it from the C65.

The C65 followed this table with two more groups of two-byte vectors. From $0334 to $0343 are the low-level serial bus routines, in the order TALK, LISTEN, TKSA, SECOND, ACPTR, CIOUT, UNTLK and UNLSN. From $0344 to $034B are four screen editor vectors: CTLVEC, SHFVEC and ESCVEC, through which the editor handles control, shifted and escape characters, and KEYSCAN, which is called after a key is read and before it is buffered.

The VECTOR call at $FF8D copies the vectors to or from memory, and RESTOR at $FF8A resets the KERNAL's own vectors to the defaults. From ROM 920400, VECTOR copies all three groups, a 56-byte table from $0314 to $034B; earlier ROMs copied only the first 32 bytes. Give VECTOR room for 56 bytes (MEGA65 ROM change log). Using VECTOR to save the table before changing it, and to put it back afterwards, is safer than editing individual entries.

Chaining into the IRQ

A cooperative program that wants code to run on every system interrupt, such as a background music player, points CINV at its own routine and ends that routine by jumping to the old handler, so that keyboard scanning and the clock keep working:

install sei
        lda $0314
        sta oldirq
        lda $0315
        sta oldirq+1
        lda #<myirq
        sta $0314
        lda #>myirq
        sta $0315
        cli
        rts

myirq   inc $d020       ; the routine's own work
        jmp (oldirq)    ; continue with the KERNAL handler

oldirq  .word 0

Before jumping through CINV, the KERNAL saves A, X, Y and Z and the base page register B, then sets B to $00. A handler that ends by jumping on to the KERNAL's handler, as above, can therefore use all of them freely: the KERNAL restores them before its RTI. Changing the vector inside SEI and CLI prevents an interrupt from arriving when only one byte has been written.

Hardware vectors

Separate from the RAM vectors are the CPU's own vectors at the top of the KERNAL ROM: NMI at $FFFA, RESET at $FFFC and IRQ/BRK at $FFFE. They point into the KERNAL; for NMI and IRQ, it then jumps through the RAM vectors. A takeover program that switches the KERNAL out replaces them with its own, as shown in Chapter 8.

BASIC vectors and USR

BASIC 65 has its own vectors, which belong to BASIC rather than the KERNAL. The one programs most often need is the USR vector, two bytes at $02F8, low byte first, read in the system bank: BANK 128 : WPOKE $02F8, $1800 points USR at a routine at $1800 (MEGA65 Book, p. B-285). Chapter 9 describes writing USR routines. Other BASIC vectors and work areas are internal and should not be assumed from the C64 or C128.

Hypervisor Services

The Hypervisor's services, documented by the MEGA65 Book for Hyppo version 1.2, are reached through trap registers at $D640-$D67F. The service number goes in A, other inputs in X, Y and Z, and the write is followed by CLV, because the CPU may or may not execute the byte after the trap when the service returns. On return, carry set means success; carry clear means failure, with an error code in A. Registers not used for results are preserved, and the trap registers exist only in the MEGA65 I/O personalities, the normal one and the Ethernet one (MEGA65 Book, pp. N-4, N-5; mega65-core, gs4510.vhdl).

Most services use $D640. A few use other trap registers: $D641 for ROM write-protection, $D642 for configuration and freeze-slot services, $D643 for serial monitor output, and $D67F for a program to freeze itself (MEGA65 Book, Appendix N).

Services at $D640

The table lists the services the Book documents. "Not in 1.2" marks services the Book defines but describes as not implemented in Hyppo 1.2; they return error $82 there.

The Input column lists the registers a service reads besides A, and anything that must be set up first. A page is the high byte of a page-aligned address between $0000 and $7E00. The Output column lists results besides the carry flag. "Not documented" means the Book gives no details for a service it does not implement.

Several services have extra requirements. setname needs the name to start on a page boundary between $0000 and $7E00, be shorter than 63 characters and end with a zero byte; it is ASCII, and Hyppo does not convert from PETSCII. Services that pass data use the transfer area, which setname also sets to the name's page. The file services work on the FAT32 file system of the SD cards, not on floppy disks or disk images (MEGA65 Book, pp. N-10, N-38).

Versions

Hyppo is updated with the MEGA65 core, independently of the ROM. In August 2026, for example, a pull request was opened against mega65-core to fill in getdisksize (the Book's getdrivesize), getcwd, mkdir, rmdir, seekfile and rename, finish fstat, and add long file name support to mkfile; it had not been merged at the time of writing (mega65-core PR #946). A program should therefore call getversion first and treat error $82, not implemented, as an expected result for newer services rather than as a failure of the program.

Error codes

The Book lists these error codes (MEGA65 Book, pp. N-7, N-8). Its table also has lower-numbered codes for partition, argument and read/write errors, such as $10 for an invalid address, which setname returns when Y is above $7E, and it notes that the list may not be exhaustive.

Writing ROM-Independent Code

A MEGA65 program may be run on a ROM newer, or older, than the one it was written on. The habits below keep it working across versions.

Zero page and system RAM

The C64's zero page was so well documented that programmers routinely borrowed its locations. On the MEGA65 that is risky. The MEGA65 team keeps what it calls a private API contract over the KERNAL's zero page, so its use can change (MEGA65 ROM issue #80). The same issue records a ROM release that began using a zero-page location in C64 mode that third-party software also used, breaking that software.

A routine that needs base page storage should therefore bring its own, by pointing B at a page it owns. A routine that must share zero page should restrict itself to locations the ROM documentation for its target version describes as free.

When a ROM routine is unavoidable

Sometimes a program genuinely needs an internal ROM routine, such as BASIC's floating-point conversion for USR. In that case:

1. Keep every such address in one place in the source, labelled with the ROM version it was taken from.
2. Have the program check the ROM version at start-up and refuse to run, with a clear message, on a version it was not tested with.
3. Note the dependency in the program's documentation, so users know to look for an update after upgrading their ROM.

This turns a silent crash after a ROM update into a clear message, which is the best that can be done for code outside the official interfaces.

Summary

• Stability. The KERNAL jump table is the officially supported ROM interface. BASIC 65 internals, ROM layout and KERNAL zero page are private and change between releases.
• Layout and versions. The 128KB ROM lives at $20000-$3FFFF. Versions are six-digit numbers: 92xxxx for release and beta ROMs, 99xxxx for development ROMs built alongside them. VERSIONQ returns the version from ROM 920417; $FF80 is always $FF.
• Jump table. The 39 entries at $FF81-$FFF3 sit at the C64's addresses, though a few hold different routines or take different arguments. The extended block runs from VERSIONQ at $FF2F to PRIMM at $FF7D: the MEGA65's own additions, then the C65-derived block from SPIN_SPOUT at $FF4D, with C128-style calls at C65 addresses.
• RAM vectors. CINV, CBINV and NMINV at $0314-$0319 and the I/O vectors up to $0333 follow the C64 layout; VECTOR and RESTOR manage them safely. The KERNAL saves A, X, Y, Z and B before jumping through CINV, so a routine that chains on to the old handler needn't preserve them.
• Hypervisor. Even-numbered functions in A, a write to $D640, CLV, and carry for success. Hyppo 1.2 leaves directory creation, renaming, seeking and the services for creating and switching tasks unimplemented; check the version before relying on newer services, and treat error $82 as "not available".
• Portability. Use interfaces, bring your own base page, and confine any unavoidable ROM dependency to one labelled place with a version check.

Chapter 12 turns to the VIC-IV and graphics.