cybersorcerer/c64u/c64-knowledge

C64 Knowledge

Grounding for C64 programming and for driving real hardware through the c64u CLI.

How to use this skill

Read one reference file - the one that covers the register or subsystem at hand. Do not read them all; each is a standalone quickref.

references/opcodes.md is generated from the disassembler's own table in tools/c64u; regenerate it with make -C skills/c64-knowledge opcodes rather than editing it.

For driving real hardware with the c64u CLI, use the c64u-cli skill instead.

Working code

examples/ holds assembled-and-runnable Kick Assembler sources.

Do not read `examples/` to answer a question. The reference files carry the register tables and the rules; the examples exist to be built and run. Open one only when:

• the user asks for working code or a starting point,
• you need to modify or debug that specific program,
• a reference file explicitly points at it and the register table alone did not settle the question.

Preferring build then run over read keeps them out of context entirely.

Toolchain

Assemble with Kick Assembler (Java):

java -jar KickAss.jar program.asm -o program.prg

Run on the connected C64 Ultimate:

c64u runners run-prg-upload program.prg    # upload and start
c64u machine read-mem 0400 --length 16     # verify what the program changed
c64u machine reset                         # back to a clean BASIC

The c64u-cli skill covers the CLI itself - all commands, verified workflows, and the limits that catch people out.

Rules that prevent most C64 bugs

1. Check the video standard before any timing or pitch maths. $02A6 holds 1 for

PAL, 0 for NTSC. SID frequency values and raster line counts differ between them. See references/vic-ii.md and references/sid.md.

1. Screen RAM stores screen codes, not PETSCII. $FFD2 takes PETSCII; a direct

sta $0400 takes a screen code. They are different encodings. See references/petscii.md.

1. Banking out ROM means banking out the IRQ handler. Any write to $01 that removes

the KERNAL must be wrapped in sei / cli, with the hardware vector at $FFFE set up first. See references/memory-map.md.

1. Acknowledge VIC interrupts. A raster IRQ that does not clear $D019 fires forever.
2. Derive REU command bytes from the bit fields, not from copied constants. Published

listings disagree on the unused bits. See references/reu.md.

Sources

Written from the Commodore 64 Programmer's Reference Guide, Mapping the Commodore 64 (Sheldon Leemon), the Kick Assembler manual (Mads Nielsen), the REU article at retro-programming.de, and the Ultimate Documentation (Gideon Zweijtzer) for the Command Interface. No text was copied from those sources; register values and protocol behaviour were checked against real hardware where possible.