Reference documentation for AI assistants and contributors ramping up on this codebase. Dense and structural by design — see linked docs for user-facing feature explanations, and Constraints.md for hard rules not to violate.
TeensyROM is a Teensy 4.1-based multi-function cartridge for the Commodore 64/128: ROM (CRT) emulator, instant PRG loader, MIDI/SID interface, Ethernet/BBS bridge, NFC launcher, and remote-control target. Two hardware variants share one firmware codebase: TR (original, PCB v0.3, DMA-line-assert only) and TR+ (PCB v0.4, adds true bus-mastering DMA enabling Kernal Replacement, a real 512KB REU, freezer cartridge emulation, and remote DMA memory access). TR+ is gated in firmware by Fab04_Features in Source/Teensy/MinimalBoot/Common/Fab04FeatureCtl.h.
| Path | Contents |
|---|---|
Source/Teensy/ |
Teensy microcontroller firmware — C/C++, Arduino/Teensyduino build. See Teensy-Firmware.md. |
Source/C64/ |
Programs that run ON the C64 (menu, settings, utilities) — 6502 assembly. See C64-Software.md. |
Source/BuildInfo.md |
Canonical build instructions/tool versions for both sides. |
PCB/ |
Eagle PCB (.sch/.brd) schematic/PCB source, per hardware version (v0.3 public/self-buildable under v0.3/EaglePCB/, v0.4/TR+ not yet public). |
docs/ |
User-facing feature docs (usage guides, protocol reference) — flat, no subfolders except this one. |
docs/Architecture/ |
This doc set — structural/AI-reference material, not user-facing. |
bin/TeensyROM/ |
Released firmware binaries + FW_Release_History.md. |
3D_Print_Case/, media/ |
Enclosure files and images, not code. |
TeensyROM is built in two independent passes that feed into each other in one direction only:
- C64 side builds first. 6502 assembly sources under
Source/C64/*/source/are cross-assembled (ACME, or KickAssembler forTRCustomBasicCommands) into raw binaries, then converted bytools/build-c64.mjs(npm run build:c64) into C headers (static const unsigned char ..._prg[]) written intoSource/Teensy/TRMenuFiles/ROMs/. - Teensy firmware builds second, embedding those generated headers directly as byte arrays — the on-screen menu, settings pages, and bundled utility programs are compiled-in C64 machine code, not generated at runtime.
This means a change to any C64-side .asm requires rebuilding that sub-project (npm run build:c64 -- --project <name>, or all of them with npm run build:c64) before rebuilding the Teensy firmware, or the change won't be picked up. Full details: Build-System.md.
C64 code and Teensy firmware also talk to each other at runtime two different ways — a low-level memory-mapped cartridge register protocol, and (separately) an external host-facing USB/Ethernet protocol. See Comms-Protocol.md.
- Teensy-Firmware.md — module map, entry point, IO_Handlers pattern, MinimalBoot
- C64-Software.md — MainMenuCRT, SettingsMenu, sub-programs, build pipeline
- Comms-Protocol.md — cartridge register protocol + link to external host protocol
- Build-System.md — toolchains, versions, dual-boot linking, known gotchas
- How to build and flash, step by step: the build skill, .claude/skills/teensyrom-build/SKILL.md
- Constraints.md — hard rules: ISR hot path, memory budgets, startup hooks, toolchain pins
- Known-Issues.md — scoped, deferred findings from architecture walkthroughs, with designed (not yet implemented) fixes
- DMA-Timing-Known-Issues.md — itemized tracking for the
DMA_Timingbranch (TR+'s true bus-mastering DMA, not the CRT bank-swap pause mechanism) - Reboot-Display-Blanking.md — why
RebootTR()exists, the large-CRT reboot glitch fix, and what was tried and didn't help - C64-C128-DMA-Port-Reference.md — what Commodore's own manuals/schematics say about C64 vs C128
/DMAassert/de-assert timing (background reference, not a bug list) - DMA-Phi2-Timing.md — where each
nS_DMA*offset lands in one Phi2 cycle (PAL / NTSC / NTSC C128), and howDMAByte()uses them