Commodore64 Vice Debugging

C64 Debugging with VICE's Binary Monitor

Drives a real VICE emulator over TCP so a C64 program can be built, run, breakpointed, inspected and patched without a human touching the emulator.

   source (.bas / .c / .s)
        │  build  (petcat | bc64 | cl65 | ca65+ld65)
        ▼
     foo.prg  +  foo.lbl (symbols)  +  foo.map
        │  autostart
        ▼
┌──────────────────────┐   TCP 6502 (binary monitor)   ┌──────────────┐
│   VICE  (x64sc)      │◄─────────────────────────────►│ vice_debug.py│
│   emulated C64       │  checkpoints, regs, memory    │  (this PC)   │
└──────────────────────┘                               └──────────────┘

Scope: the C64 program is what gets debugged. This skill does not talk to Meatloaf firmware or any ESP32 — VICE has no bridge to a real IEC device. For that loop use the commodore64-debugging skill.

Read this first — three verified behaviours that will waste hours

All three were established empirically against VICE 3.10 on Windows. They are not in the protocol documentation.

1. Never disconnect while the emulator is halted

If a monitor client disconnects while the machine is stopped at a checkpoint, VICE tears down its monitor listener permanently. The emulator keeps running and its window stays responsive, but nothing can ever connect again — port 6502 refuses connections until VICE is restarted.

Consequence: one CLI process per command does not work once a breakpoint fires. Everything that must observe a halted machine has to happen on a single connection. That is exactly what batch is for:

# WRONG - the process after `wait` disconnects while halted, killing the monitor
python vice_debug.py brk _bump
python vice_debug.py wait
python vice_debug.py regs          # -> connection refused, VICE now unreachable

# RIGHT - one connection for the whole stop/inspect/resume sequence
python vice_debug.py batch "brk _bump" "autostart foo.prg" wait regs "mem _counter -n 1"

ViceSession.close() always resumes before closing, and main() closes the shared session in a finally, so the CLI cannot trip this on its own. Custom code using ViceMonitor directly must resume by hand.

2. Keyboard feed is only delivered after the client disconnects

keyboard_feed (0x72) queues text that VICE holds for as long as any binary monitor client is connected. Polling the screen for 20 s while connected shows nothing; the text appears the instant the connection drops.

type handles this for you — it feeds, drops the connection, waits, and reconnects to show the screen. Know about it anyway, because it explains the classic symptom: a typed command appearing to run one invocation late, or seemingly duplicating itself.

Prefer autostart over typing RUN wherever possible — autostart works normally while connected.

3. Register IDs are assigned by the emulator, never hardcoded

registers get returns (id, value) pairs with no names. The IDs differ per emulator and per VICE build. On this x64sc 3.10: A=0, X=1, Y=2, PC=3, SP=4, FL=5, plus LIN=53, CYC=54, 00=55, 01=56. Always resolve them through registers available (0x83) first — vice_monitor.py does this and caches it, so you work with {"PC": 2112, "A": 1, ...}.

Quick start

cd .claude/skills/commodore64-vice-debugging/scripts

python vice_debug.py config                 # what got discovered
python vice_debug.py launch                 # start VICE with -binarymonitor
python vice_debug.py cycle ../../../my.bas  # build, run, show the screen
python vice_debug.py kill                   # clean shutdown

config resolves every tool without hardcoding paths and reports what it found. Run it before anything else when something behaves oddly:

{
  "machine": "c64",
  "emulator": "C:\\vice\\bin\\x64sc.EXE",
  "petcat": "C:\\vice\\bin\\petcat.EXE",
  "c1541": "C:\\vice\\bin\\c1541.EXE",
  "cl65": "C:\\Users\\you\\Tools\\cc65\\bin\\cl65.EXE",
  "bc64": null,
  "basic_compiler": "petcat",
  "monitor_host": "127.0.0.1",
  "monitor_port": 6502,
  "monitor_reachable": true
}

Skill components

commodore64-vice-debugging/
├── SKILL.md                        ← this file: workflow + reference
├── scripts/
│   ├── vice_monitor.py             ← binary monitor protocol client (standalone)
│   ├── vice_toolchain.py           ← tool discovery, building, label parsing
│   └── vice_debug.py               ← CLI + ViceSession automation
├── reference/
│   └── binary_monitor_protocol.md  ← full opcode / packet reference
└── evals/evals.json

vice_monitor.py has no dependencies beyond the standard library and imports nothing else from the skill — import it directly to drive VICE from your own Python.

Building

build dispatches on extension and always emits a .prg.

python vice_debug.py build game.c                # -> game.prg, game.lbl, game.map
python vice_debug.py build game.c --release      # -Oirs instead of -g
python vice_debug.py build main.s -o main.prg

Assembly needs the asm linker config. A standalone .s has none of the C runtime's segments, so the default c64.cfg fails to link with Error: Start address of memory area 'BSS' is not constant. The builder adds -C <machine>-asm.cfg -u __LOADADDR__ automatically, and steps aside if you pass your own -C. A minimal source that links with it:

        .segment "EXEHDR"           ; BASIC stub so RUN works
        .word   nextline
        .word   10
        .byte   $9e, "2061", $00    ; SYS 2061 -> $080D
nextline:
        .word   0

        .segment "CODE"
        .export start
start:  lda #$06
        sta $d020
        jmp start

Name your outputs distinctly. build foo.bas and build foo.c both default to foo.prg. Building one after the other leaves a .prg from one language beside a .lbl from the other, and every breakpoint silently targets addresses that are not in the running program. Use -o.

Disk images

python vice_debug.py d64 loader.s game.c -o disk.d64 --name mygame

Needed when the program loads further files at runtime or you want true drive emulation — autostarting a bare .prg gives it no disk to read from.

Deploying

load strips the 2-byte little-endian load-address header and writes the body to that address. For a program at $0801 it also fixes the BASIC pointers at $2D/$2F/$31 to just past the program end — without that, RUN sees a zero-length program. It is skipped automatically for anything not loading at $0801, since C and assembly programs use that zero page for their own globals. Override with --basic / --no-basic.

python vice_debug.py autostart game.prg --wait 4     # run and show the screen
python vice_debug.py load game.prg                   # resident, not running
python vice_debug.py load game.bas --run --wait 4    # build, inject, RUN

Breakpoints, watchpoints and symbols

VICE calls them all checkpoints; the operation bits decide the kind: exec (0x04) is a breakpoint, load (0x01) and store (0x02) are watchpoints.

python vice_debug.py labels game.lbl        # load symbols (persists between calls)

python vice_debug.py brk _main              # break on execute (default)
python vice_debug.py brk '$d020' --store    # break when anything writes the border
python vice_debug.py brk _buf _bufend --load --trace   # log reads of a range, don't stop
python vice_debug.py brk _bump --temp       # delete after the first hit
python vice_debug.py brks                   # list
python vice_debug.py delbrk --all

Addresses accept $c000, 0xc000, bare hex c000, decimal #49152, or any symbol from the loaded label file. cc65 prefixes C symbols with _, and the resolver tries that prefix for you, so brk main finds _main.

--cond attaches a VICE monitor condition expression:

python vice_debug.py brk _bump --cond "A == 3"

Verified: A == 99 never fires, A == 1 fires with A=1 at the stop.

Quoting on Windows: PowerShell mangles nested quotes when passing them to a native executable, so --cond "A == 3" inside a quoted batch argument arrives split into pieces. Use a batch file, where each line is parsed by the skill and nothing else touches it:

python vice_debug.py batch -f session.txt

# session.txt — blank lines and # comments are skipped
labels game.lbl
delbrk --all
brk _bump --exec --cond "A == 1"
autostart game.prg
wait --timeout 20
regs
mem _counter -n 1

Inspecting

python vice_debug.py regs                       # decoded, with symbol for PC
python vice_debug.py regs --set A=7 X=1
python vice_debug.py mem _counter -n 16         # hex dump
python vice_debug.py mem '$0400' -n 1000 --ascii
python vice_debug.py mem '$c000' -n 256 --raw > dump.bin
python vice_debug.py poke _counter 04
python vice_debug.py poke '$d020' --text HELLO
python vice_debug.py screen

Memory reads default to side-effects OFF. Reading an I/O register such as $D019 with side effects clears latched bits and changes what the running program sees — a debugger that alters the bug is worthless. Pass --side-effects only when you specifically want that.

Screen reading

screen resolves where screen RAM actually is rather than assuming $0400: the VIC bank comes from $DD00 bits 0-1 (inverted) and the matrix offset from $D018 bits 4-7. Programs that relocate the screen — common in C and assembly — are read correctly.

It also picks the character set from $D018 bit 1, so uppercase/graphics mode and mixed-case mode both decode properly. Reverse-video codes are folded onto their normal characters so a reverse-printed line still reads as text.

+----------------------------------------+
|hello from cc65                         |
|counter=5                               |