Docs / Specifications, source material and credits

Specifications, source material and credits#

The emulator follows publicly-available hardware references. VICE (x64sc) is also the runtime cross-check oracle — the diff workflow is documented in testing.html.

With gratitude to the VICE team. The following was important to the success of this project:

• VICE — the gold-standard C64 emulator, used as the runtime comparison oracle. https://vice-emu.sourceforge.io/
• VICE test progs — cycle-exact hardware test suite. https://github.com/libsidplayfp/VICE-testprogs

References by subsystem#

VIC-II video (6567/6569/8565)#

• Bauer, The MOS 6567/6569 video controller (VIC-II) and its application in the Commodore 64 — the primary reference. https://www.cebix.net/VIC-Article.txt
• VICE addendum — VIC-II Addendum: Key Technical Differences from Bauer's Article (Kahlin / Nuotio / Lankila / Matthies, rev 0.3, 20100729) — supplements Bauer where it was incomplete or wrong. https://sourceforge.net/p/vice-emu/code/HEAD/tree/techdocs/VICII/VIC-Addendum.txt
• "Nine" by Linus Åkesson (lft) — the author's explanation page is used directly as a spec for several VIC-II tricks. Thank you, Linus, for all your brilliant demos and inspiration. https://www.linusakesson.net/scene/nine/explanation.php
• Pepto / Colodore palettes — Philip "Pepto" Timmermann's measured PAL palette (2001) and his Colodore successor. Both ship as the emulator's selectable color palettes (PALETTES in src/vic2.js); Colodore is the default. https://www.pepto.de/projects/colorvic/ · https://www.colodore.com
• Bumbershoot Software — VIC-II/CPU interaction timing articles ("VIC-II interrupt timing"; VIC-before-CPU same-cycle ordering, BA lead time), corroborating Bauer §3.6.1/§3.8.1. https://bumbershootsoft.wordpress.com/2015/07/26/vic-ii-interrupt-timing-or-how-i-learned-to-stop-worrying-and-love-unstable-rasters/

6510 / 6502 CPU#

• MOS 6502 datasheet — cycle counts and microarchitecture (the MOS 6500-family MPU datasheet). https://6502.org/documents/datasheets/mos/mos_6500_mpu_preliminary_may_1976.pdf
• Klaus Dormann's 6502 functional test — exhaustive opcode/flag verification. https://github.com/Klaus2m5/6502_65C02_functional_tests
• groepaz — NMOS 6510 Unintended Opcodes — ground truth for the illegal opcodes: the SH* family's address-high instability and JAM/KIL behavior (as also presented in Michael Steil's c64ref). https://www.pagetable.com/c64ref/6502/
• 64doc — John West & Marko Mäkelä's cycle-by-cycle 65xx reference; cited for illegal-opcode semantics (ARR's decimal-mode interaction). https://www.atarihq.com/danb/files/64doc.txt
• Visual6502 — transistor-level 6502 simulation, cross-checked for the same illegal-opcode edge semantics. http://www.visual6502.org
• Bruce Clark — Decimal Mode — the definitive tutorial on 6502 BCD arithmetic; the ADC/SBC decimal-mode algorithm follows his analysis. http://www.6502.org/tutorials/decimal_mode.html

CIA / 6526#

• MOS 6526 (CIA) datasheet — timers, TOD, and serial-register behavior. https://6502.org/documents/datasheets/mos/mos_6526_cia_preliminary_nov_1981.pdf
• Wolfgang Lorenz — A Software Model of the CIA6526 — reverse-engineered cycle timing plus the CIA compatibility test suite this project validates against. https://ist.uwaterloo.ca/~schepers/MJK/cia6526.html

SID 6581 / 8580 audio#

• MOS Technology 6581 Sound Interface Device — original SID data sheet covering the register map, oscillator, envelope, filter, and external interface. https://6502.org/documents/datasheets/mos/mos_6581_sid.pdf
• Bob Yannes — the original SID designer's design rationale for the envelope model, its small ADSR-rate lookup table, and the 23-bit pseudo-random noise generator, from Andreas Varga's 1996 interview. The exact rate periods and noise-output taps used here come from reSID / resid-test. https://trondal.com/c64sid/yannes.html
• reSID by Dag Lem — canonical accuracy reference. Portions of our SID envelope, waveform/noise, and external-filter behavior are direct translations/reimplementations of reSID models; we do not redistribute its measured combined-waveform lookup tables (a synthetic generator is used instead). https://github.com/daglem/reSID
• reSIDfp / Antti Lankila — 6581 filter/distortion research and SID measurement lineage, especially waveform and TEST/noise behavior references preserved through reSID citations. The current 6581 cutoff table is calibrated against headless VICE reSID 6581 noise sweeps, not fitted directly from Lankila's old cutoff curve or ported from reSIDfp source. https://github.com/libsidplayfp/libsidplayfp
• jsSID by Hermit (Mihaly Horvath) — MIT-spirit synthetic combined-waveform generator (createCombinedWF). https://github.com/og2t/jsSID

Memory / PLA / banking#

• "The C64 PLA Dissected" by Thomas 'skoe' Giesel — 82S100 PLA behaviour; the ground truth for the banking / $01-port / Ultimax mapping logic in memory.js. Table A.11 also defines the VIC-II's Ultimax view used by vic2.js: cartridge ROMH at local $3000-$3FFF, with DRAM rather than character ROM in the remaining VIC windows. https://www.skoe.de/docs/c64-dissected/pla/c64_pla_dissected_a4ds.pdf

ROM images#

The C64 and 1541 ROMs aren't bundled (they're copyrighted) — you supply them once. The emulator was developed and tested against these specific CBM ROM revisions:

• KERNAL — kernal.901227-03.bin (8 KB)
• BASIC — basic.901226-01.bin (8 KB)
• CHARGEN — characters.901225-01.bin (4 KB)
• 1541 DOS — 1541-II.251968-03.bin (16 KB, optional — for True Drive Emulation)

Cartridges#

• CRT cartridge image format — from the CCS64 emulator (Per Håkan Sundell); the 64-byte header + CHIP packets that src/crt.js parses. https://ist.uwaterloo.ca/~schepers/formats/CRT.TXT
• Final Cartridge III hardware — ReplayResources register description plus Thomas Giesel's hardware-derived errata define the four 16 KB banks, permanent IO1/IO2 ROM mirror, $DFFF EXROM/GAME/NMI/hidden-register latch, and physical RESET/FREEZE behavior used by the type-3 mapper. https://rr.c64.org/wiki/Final_Cartridge https://rr.c64.org/wiki/Final_Cartridge_III_Internals_Errata.txt
• Action Replay v4.x/v5/v6 hardware — the MK5/6 schematic and hardware-derived AR6 PLA dump define its 32 KB ROM, 8 KB RAM, mirrored $DE00 latch, IO2 window, cartridge-kill and latched freezer behavior. In particular, the schematic's missing R/W qualification on IO1 is why a read clocks the current phi1 bus byte into the latch. https://rr.c64.org/wiki/File:Action_Replay_MK5_6.gif https://rr.c64.org/wiki/File:Ar6pla.rar
• EasyFlash hardware — Skoe's EasyFlash Programmer's Reference defines the bank/control registers, EXROM/GAME truth table, and IO2 RAM. https://skoe.de/easyflash/files/devdocs/EasyFlash-ProgRef.pdf
• Magic Desk-compatible hardware — the Universal Cartridge hardware description documents the $DE00 bank latch, 8 KB ROML mapping, and bit-7 cartridge disable used by this model. Its expanded hardware offers seven bank bits; the emulator implements a six-bit, 64-bank subset. https://github.com/msolajic/c64-uni-cart

1541 disk drive#

• D64 disk-image format — Peter Schepers, D64 (Electronic form of a physical 1541 disk). src/d64.js (valid image sizes, BAM layout, the 32-byte directory entries and file-type byte — including DEL/scratched entries, and the 35- vs 40-track / error-info variants) follows this reference. The write side — writeSector, and createBlankD64 (a fresh empty image: BAM at track 18/0 + empty directory at 18/1, 664 blocks free) — uses the same BAM/directory layout. https://ist.uwaterloo.ca/~schepers/formats/D64.TXT
• Inside Commodore DOS by Immers & Neufeld (Abacus) — background reference for CBM DOS internals and the disk format. (The byte-ready and PA-latch specifics are cited to Die Floppy and the schematics below.) https://archive.org/details/Inside_Commodore_Dos
• 1541 DOS ROM disassembly — Michael Steil's buildable, annotated source for the 251968-01/-02/-03 revisions; ground truth for the true-drive CPU timing. https://github.com/mist64/dos1541
• Sparkle — trackmo loader by Sparta / OMG; its source and Aloft's install stream informed validation of the drive's byte-ready/SO timing and IEC inter-block handshake. https://github.com/spartaomg/Sparkle
• Spindle — trackmo loader by lft / Linus Åkesson; a compatibility target whose command-stream cadence shaped the IEC idle-skip hysteresis. https://www.linusakesson.net/software/spindle/v2.php
• MOS 6522 (VIA) datasheet — timers, ports, and handshake lines; the drive's two VIA chips (src/6522.js) follow it. https://6502.org/documents/datasheets/mos/mos_6522_preliminary_nov_1977.pdf
• Die Floppy 1570/1571 — Karsten Schramm (Markt & Technik); the VIA2 CA2/SOE gating and byte-ready wiring details (§8.2).
• 1541 schematics / service manual — the SYNC 10-bit shift register, the byte-ready PA latch, the per-zone cycle counts, the read/write head select (VIA2 CB2), and the write-protect sense line (VIA2 PB4, active low: 0 = protected, 1 = write enabled). These govern the write path's mode select and write-protect polarity — the latter cross-checked against the real DOS ROM, which raises error 26 ("WRITE PROTECT ON") when PB4 reads low. https://www.zimmers.net/anonftp/pub/cbm/schematics/drives/new/1541/

Credits#

Thank you to every game and demo coder, and every SID composer, and to every graphic artist, cracker, swapper, and everyone else in the scene, who pushed the hardware further than anyone thought possible since 1982.

A special thanks goes to the following:

Demo groups and crackers#

Fairlight · Genesis Project · Oxyron · Crest · Razor 1911 · Booze Design · Censor Design · Triad · Performers · Reflex · Bonzai · Pretzel Logic · Elysium · Smash Designs

Game developers and publishers#

Sensible Software · System 3 · Beam Software · Raffaele Cecco · Sega · Capcom · ZeroPaige · Nostalgia · Hewson · Psygnosis · Ocean · Elite · Simon Pick · Amazing Products

SID musicians#

Rob Hubbard · Martin Galway · Jeroen Tel · Chris Hülsbeck · Ben Daglish

Collections and archives#

• CSDb — the C64 Scene Database. https://csdb.dk
• Assembly 64 — C64 demo / music / game archive. https://assembly64.hackerswithstyle.se/assembly/index.html
• OneLoad64 — one-file C64 games collection. https://oneload64.github.io/

AI collaborators#

• Claude Code (Anthropic) — primary implementation collaborator.
• Codex (OpenAI) — second opinion and advanced logic tasks.

Fonts#

• Inter by Rasmus Andersson — SIL OFL 1.1. https://rsms.me/inter/
• Share Tech Mono by Carrois Type Design — SIL OFL 1.1. https://fonts.google.com/specimen/Share+Tech+Mono
• PetMe64, Giana, and Berkelium (GEOS font) by Rebecca Bettencourt / Kreative Korporation — Kreative free-use license. https://www.kreativekorp.com/software/fonts/c64.shtml

3D model#

• Commodore 64 || Computer (Full Pack) by dark_igorek — CC BY 4.0, used for the Retro Vibes 3D viewer. https://skfb.ly/oUKFx