C64-dev/reference/vice-usage.md

VICE 3.10 Usage Reference

Supplemental emulator reference distilled from C:\Program Files\GTK3VICE-3.10-win64\doc\vice.txt

This file is a practical subset of the VICE 3.10 manual for AI agents working on Commodore 64 software in this repository.

---

Preferred C64 Executable

• x64sc — accurate C64 emulator with cycle-based and pixel-accurate VIC-II emulation

Other useful VICE tools installed alongside it:

• c1541.exe — disk image tool
• petcat.exe — BASIC text/token conversion
• cartconv.exe — cartridge conversion
• vsid.exe — SID playback

---

Autostart

Equivalent manual-documented forms:

x64sc mydisk.d64
x64sc -autostart myprog.prg
x64sc -autostart "demo.d64:loader"

Useful switches:

Option	Purpose
-autostart-warp	Enable warp mode during autostart
-autostart-handle-tde	Temporarily manage True Drive Emulation for autostart
-basicload	Use BASIC-start load behavior when autostarting from disk
+basicload	Use ,1 absolute load behavior when autostarting from disk
-autostartprgdiskimage <name>	Choose the disk image used when autostarting a PRG via disk-copy mode

Notes:

• For raw .prg/P00 files, VICE restores autostart-related settings after load
• If a program must reach the host filesystem, enable virtual device traps

---

Debug Launch Options

Option	Meaning
-nativemonitor	Run the monitor in the spawning terminal
-keepmonopen	Keep the monitor open after continuing execution
-refreshonbreak	Refresh display when entering monitor and after monitor commands
-monlog	Log monitor output to a file
-monlogname <name>	Choose the monitor log filename
-remotemonitor	Enable the text remote monitor server
-remotemonitoraddress ip4://127.0.0.1:6510	Bind address for the text monitor server
-binarymonitor	Enable the binary monitor protocol server
-binarymonitoraddress ip4://127.0.0.1:6502	Bind address for the binary monitor server

Recommended debug launch for this repo:

"C:\Program Files\GTK3VICE-3.10-win64\bin\x64sc.exe" -autostart c64os.prg -autostart-warp -nativemonitor -keepmonopen -refreshonbreak

---

High-Value Debug Commands

Command	Use
r / registers	Show or edit registers
x / exit	Resume execution
q / quit	Quit VICE
step [count]	Step into
next [count]	Step over
return	Run until next RTS or RTI
until <address>	Run until a target address
bt / backtrace	Show JSR call chain
goto <address>	Set PC
m <range>	Dump memory
i <range>	View memory as PETSCII
d <range>	Disassemble
io [address]	Show I/O register state
break exec $addr	Execution breakpoint
watch store $addr	Write watchpoint
trace exec $a $b	Non-stopping trace
bank	Show/select banks
device c: / 8:	Switch computer or drive memory space
sidefx off	Avoid side-effect-causing reads while inspecting memory
keybuf "text\x0d"	Inject keyboard input
playback "file"	Execute a monitor script file
record "file"	Record a debug session as commands

Examples:

break exec $0810
watch store $0001
d $0810 $0840
m $0000 $0002
bt
return
playback "examples/vice-monitor-c64os.txt"

Conditional checkpoints support register expressions, raster line RL, and cycle CY.

Useful conditional examples from the manual style:

break exec $0810 if A == $00
break load 0 $ffff if @cpu:(pc - $1) == $37

Checkpoint management:

command 2 "m $0000 $0002"
ignore 2 1
disable 1
enable 1
delete 1

Debugging-specific watch targets:

• $0001 for memory banking writes
• $0314-$0315 for IRQ vector changes
• $0318-$0319 for NMI vector changes
• $0400-$07E7 for screen RAM writes
• $D800-$DBE7 for color RAM writes

---

Practical Debug Workflow

1. Launch with -nativemonitor -keepmonopen -refreshonbreak
2. Enter sidefx off
3. Break at entry with break exec $0810
4. Disassemble nearby code with d
5. Inspect registers with r
6. Use step to go into a routine, next to stay out of KERNAL internals, and return to escape a routine quickly
7. Add watchpoints once the suspicious state is known
8. Use bt if execution reached an unexpected location
9. Save a snapshot only for short-lived debugging checkpoints

---

Snapshots

VICE snapshots:

• save complete emulator state
• can include drive state
• restore memory configuration on load

Important manual warning:

• snapshots are convenient for debugging, but should not be treated as stable long-term storage across VICE versions

---

Repo-Focused Launch Examples

Build and run the current program:

build.bat
"C:\Program Files\GTK3VICE-3.10-win64\bin\x64sc.exe" -autostart c64os.prg -autostart-warp

Open with terminal monitor ready for debugging:

"C:\Program Files\GTK3VICE-3.10-win64\bin\x64sc.exe" -autostart c64os.prg -autostart-warp -nativemonitor -keepmonopen -refreshonbreak

Open with monitor logging enabled:

"C:\Program Files\GTK3VICE-3.10-win64\bin\x64sc.exe" -autostart c64os.prg -autostart-warp -nativemonitor -keepmonopen -refreshonbreak -monlog -monlogname vice-monitor.log