TeensyROM IO Handler Checklist

Adding an IO Handler to TeensyROM's MinimalBoot

A new piece of hardware (cartridge, freezer, peripheral) plugs into MinimalBoot as an stcIOHandlers struct of function pointers. Most of the work is mechanical wiring across a few files that must stay in sync; the rest is a handful of hardware-emulation conventions that are easy to get subtly wrong because the compiler won't catch them.

1. Write the handler file

Create Source/Teensy/MinimalBoot/Common/IO_Handlers/IOH_<Name>.c. Use an existing handler of the same cartridge class as your template rather than starting from a blank page — IOH_RetroReplay.c and IOH_SuperSnapshotV5.c are the reference implementations for freezer-style carts with a control register and a physical freeze button.

Shape:

void InitHndlr_<Name>();
void IO1Hndlr_<Name>(uint8_t Address, bool R_Wn);
// ...other handler prototypes you need

stcIOHandlers IOHndlr_<Name> =
{
  "<Name>",              // Name of handler, IOHNameLength max
  &InitHndlr_<Name>,     // Called once at handler startup
  &IO1Hndlr_<Name>,      // IO1 R/W handler
  &IO2Hndlr_<Name>,      // IO2 R/W handler
  NULL,                  // ROML Read handler (leave NULL if unused)
  NULL,                  // ROMH Read handler (leave NULL if unused)
  NULL,                  // Polled in main routine (leave NULL if unused)
  &CycleHndlr_<Name>,    // called at the end of EVERY c64 cycle (leave NULL if unused)
};

Any slot you don't need stays NULL — don't stub out empty functions for them.

2. Register it in three places, same relative order

There are explicit "Synch order/qty" comments in the code warning that these must match — add your handler in the same position (relative to neighboring handlers) in all three:

• Source/Teensy/MinimalBoot/Common/Menu_Regs.h — add IOH_<Name> to the enumIOHandlers enum.
• Source/Teensy/MinimalBoot/Common/IOHandlers.h — add both the #include "IO_Handlers/IOH_<Name>.c" line and the &IOHndlr_<Name> entry in the IOHandler[] array, at the same position as the enum.
• Source/Teensy/MinimalBoot/Common/DriveDirLoad.h — if it's a CRT-detectable cartridge type, add a (uint16_t)Cart_<Name>, IOH_<Name>, row to HWID_IOH_Assoc[] (the Cart_<Name> constant is usually already #defined nearby from CRT-format docs).

Include-order matters if your handler references another handler's global (see the reused-global pattern below) — your #include must come after the file that declares that global, since these are all textually included into one translation unit.

If the cartridge needs boot/CRT-type detection help (e.g. distinguishing which freezer cart produced a given CRT file), that logic lives in Source/Teensy/FileParsers.ino's SetTypeFromCRT(), typically behind the same feature-flag #ifdef as the handler registration.

3. Watch for these two things (found integrating Final Cartridge III)

Reused globals must be reset in your Init, not just passed as a parameter

To save RAM, a handler may alias an existing global from another handler that's never active at the same time, e.g. #define FC3_ControlReg RR_StatusReg, with a comment explaining the reuse. This is a legitimate, established pattern — but MinimalBoot's dispatcher (Source/Teensy/IOHandlers.ino and Source/Teensy/MinimalBoot/Min_DriveDirLoad.ino) only calls the new handler's InitHndlr() when switching handlers. It never clears shared globals in between, so whatever the previous handler left in that memory is still there when yours starts.

If your init logic does something like ProcessControlReg(0); // HW power-on reset and that function reads the persisted alias for anything (a status/hidden bit, a mode flag), passing 0 as a function parameter doesn't touch the alias itself — you must explicitly assign it too (FC3_ControlReg = 0;) before or as part of that call. Otherwise the first thing your handler does on load is act on stale garbage from whatever ran before it. Trace every read of a reused global back to where it's written, and make sure your Init path covers all of them, not just the ones a fresh parameter conveniently overwrites.