Skip to content

Latest commit

 

History

History
47 lines (34 loc) · 4.47 KB

Overview.md

File metadata and controls

47 lines (34 loc) · 4.47 KB

TeensyROM Architecture Overview

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.

Repo layout

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.

The two toolchains, and how they connect

TeensyROM is built in two independent passes that feed into each other in one direction only:

  1. C64 side builds first. 6502 assembly sources under Source/C64/*/source/ are cross-assembled (ACME, or KickAssembler for TRCustomBasicCommands) into raw binaries, then converted by tools/build-c64.mjs (npm run build:c64) into C headers (static const unsigned char ..._prg[]) written into Source/Teensy/TRMenuFiles/ROMs/.
  2. 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.

Doc set

  • 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
  • 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_Timing branch (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 /DMA assert/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 how DMAByte() uses them

Back to main ReadMe