dcovington
/
C64-dev
1
0
Fork 0
Código Issues 0 Pull requests 0 Versões 0 Wiki Atividade
Você não pode selecionar mais de 25 tópicos Os tópicos devem começar com uma letra ou um número, podem incluir traços ('-') e podem ter até 35 caracteres.
3 Commits
1 Branch
254KB
Branch: main
Branches Tags
${ item.name }
Criar branch ${ searchTerm }
de main
${ noResults }
C64-dev/AGENTS.md

12KB
Original Link permanente Anotar Histórico

AGENTS.md — Commodore 64 Developer Knowledge Base

Assembled by a collective of 150 expert Commodore 64 developers. This file is the primary reference for AI agents assisting with Commodore 64 application development. Core C64 platform knowledge is sourced from canonical reference books (see Sources below). Supplemental modern emulator workflow guidance is included for VICE 3.10 from C:\Program Files\GTK3VICE-3.10-win64\doc\vice.txt.

How to Use This Knowledge Base

This repository contains structured skills and reference material for developing software on the Commodore 64. Each subdirectory under skills/ is a self-contained topic skill. When answering a C64 development question, consult the most relevant skill first, then cross-reference the reference/ files.

Skill Index

Directory Topic When to Use
skills/6510-assembly/ 6510 CPU, opcodes, addressing modes, registers Writing or debugging assembly/ML programs
skills/memory-map/ Complete C64 memory layout, zero page, banking Memory management, PEEK/POKE, ML placement
skills/graphics-vic2/ VIC-II chip, sprites, character modes, color All graphics programming
skills/sound-sid/ SID 6581, ADSR, waveforms, filters Music and sound effects
skills/disk-io-1541/ 1541 DOS, file types, direct access Disk operations, file I/O
skills/kernal-routines/ OS jump table, screen/serial/tape I/O Using built-in OS calls from ML
skills/basic-programming/ BASIC 2.0 interpreter, extending BASIC, tokens BASIC programs, BASIC extensions
skills/interrupts/ IRQ, NMI, CIA timers, raster interrupts Interrupt-driven code, timing
skills/compiler-design/ Compiler & assembler construction for C64/128 Writing compilers, assemblers, parsers
skills/vice-emulator/ VICE emulator, autostart, monitor, snapshots, automation Running, testing, and debugging C64 software in VICE

Reference Files

File Contents
reference/memory-map-complete.md All C64 memory locations with descriptions
reference/6510-opcodes.md Full 6510 opcode table
reference/kernal-jumplist.md All Kernal jump table addresses and parameters
reference/vic-registers.md VIC-II chip register map
reference/sid-registers.md SID chip register map
reference/cia-registers.md CIA 6526 register map
reference/disk-dos-commands.md 1541 DOS command reference
reference/vice-usage.md VICE 3.10 emulator, monitor, autostart, and automation reference

Example Programs

File Description
examples/hello-world.asm Minimal 6510 assembly hello world
examples/sprite-demo.bas BASIC sprite programming demo
examples/sound-demo.bas SID chip sound demo in BASIC
examples/disk-access.bas Sequential and relative file access
examples/irq-handler.asm Custom IRQ handler skeleton
examples/kernal-io.asm Using Kernal routines for I/O
examples/vice-autostart-c64os.bat Launch c64os.prg directly in x64sc
examples/vice-monitor-c64os.txt VICE monitor playback script for debugging c64os.prg
examples/vice-debug-c64os.bat Launch c64os.prg with VICE native monitor and debug-friendly options
examples/vice-monitor-c64os-debug.txt Repeatable VICE debugging session with breakpoints, watchpoints, and keyboard injection

System Overview

The Commodore 64 (1982) features:

  • CPU: MOS 6510 (6502-compatible, 1 MHz NTSC / ~0.985 MHz PAL)
  • RAM: 64KB (not all simultaneously accessible)
  • ROM: 20KB total — 8KB BASIC ($A000–$BFFF), 8KB Kernal ($E000–$FFFF), 4KB Character ROM ($D000 when banked in)
  • Graphics: VIC-II (MOS 6567 NTSC / 6569 PAL) at $D000–$D3FF
  • Sound: SID MOS 6581 at $D400–$D7FF
  • I/O: Two CIA 6526 chips at $DC00–$DCFF (CIA #1) and $DD00–$DDFF (CIA #2)
  • Screen: 40×25 text, 320×200 bitmap, 160×200 multicolor
  • Colors: 16 colors
  • Sprites: 8 hardware sprites (24×21 pixels each)

Memory Architecture Quick Reference

$0000–$00FF  Zero Page      — CPU registers, BASIC/Kernal variables (fast access)
$0100–$01FF  Stack          — 6510 hardware stack
$0200–$03FF  Pages 2–3      — OS/BASIC working storage, vectors
$0400–$07FF  Screen RAM     — Default video matrix (40×25 = 1000 bytes)
$0800–$9FFF  BASIC RAM      — BASIC program area (default: $0801–$9FFF)
$A000–$BFFF  BASIC ROM      — Microsoft BASIC 2.0 (or RAM when banked out)
$C000–$CFFF  Free RAM       — ML programs, data (4KB always RAM)
$D000–$D3FF  VIC-II         — Graphics chip registers (I/O mode)
$D400–$D7FF  SID            — Sound chip registers (I/O mode)
$D800–$DBFF  Color RAM      — Screen color data (nybble wide, 1000 bytes)
$DC00–$DCFF  CIA #1         — Keyboard, joystick, IRQ timer
$DD00–$DDFF  CIA #2         — Serial bus, NMI timer, VIC-II bank select
$E000–$FFFF  Kernal ROM     — Operating system (or RAM when banked out)

Memory bank control — Location $0001 (6510 I/O port):

Bits 2-0:  000 = RAM everywhere
           101 = BASIC+Kernal ROM, I/O (default)
           110 = Kernal ROM + I/O, BASIC=RAM
           111 = All ROM + I/O (normal)

Critical Zero-Page Locations

Address Dec Name Description
$0000 0 R6510 6510 I/O direction register
$0001 1 M6510 6510 I/O port (memory bank/tape)
$0002 2 — Unused (free for user)
$0003-$0004 3-4 ADRAY1 Float→fixed vector
$0005-$0006 5-6 ADRAY2 Fixed→float vector
$0007 7 CHARAC Search character
$0014-$0015 20-21 — Integer value
$002B-$002C 43-44 TXTTAB Start of BASIC program
$002D-$002E 45-46 VARTAB Start of variable area
$0030-$0031 48-49 FRETOP Top of string storage
$0037-$0038 55-56 MEMSIZ Pointer to end of BASIC RAM
$0039-$003A 57-58 CURLIN Current BASIC line number
$003E-$003F 62-63 OLDLIN Previous BASIC line number
$0052-$0053 82-83 OLDTXT Previous BASIC text pointer
$007A-$007B 122-123 FNPNT Floating point accumulator
$00AC-$00AD 172-173 STRNG1 Start of string 1
$00C1 193 SAL Save start address (low)
$00C2 194 SAH Save start address (high)
$00AE-$00AF 174-175 FRESPC String utility pointer
$00FB-$00FE 251-254 — Free zero-page (user)

Kernal Jump Table Quick Reference

All Kernal routines are called via JSR to their jump table address ($FFxx). The jump table is always available regardless of ROM banking mode.

Address Name Function
$FF81 CINT Initialize screen editor
$FF84 IOINIT Initialize I/O devices
$FF87 RAMTAS Test/initialize RAM
$FF8A RESTOR Restore default I/O vectors
$FF8D VECTOR Read/set RAM vectors
$FF90 SETMSG Control OS messages
$FF93 SECOND Send secondary address after LISTEN
$FF96 TKSA Send secondary address after TALK
$FF99 MEMTOP Read/set top of memory
$FF9C MEMBOT Read/set bottom of memory
$FF9F SCNKEY Scan keyboard
$FFA2 SETTMO Set serial bus timeout
$FFA5 ACPTR Input byte from serial bus
$FFA8 CIOUT Output byte to serial bus
$FFAB UNTLK Send UNTALK to serial bus
$FFAE UNLSN Send UNLISTEN to serial bus
$FFB1 LISTEN Command device to LISTEN
$FFB4 TALK Command device to TALK
$FFB7 READST Read I/O status word
$FFBA SETLFS Set logical/device/command
$FFBD SETNAM Set filename
$FFC0 OPEN Open logical file
$FFC3 CLOSE Close logical file
$FFC6 CHKIN Open channel for input
$FFC9 CHKOUT Open channel for output
$FFCC CLRCH Close input/output channels
$FFCF BASIN Input character from channel
$FFD2 BSOUT Output character to channel
$FFD5 LOAD Load from device
$FFD8 SAVE Save to device
$FFDB SETTIM Set real-time clock
$FFDE RDTIM Read real-time clock
$FFE1 STOP Test STOP key
$FFE4 GETIN Get character from queue
$FFE7 CLALL Close all files
$FFEA UDTIM Increment real-time clock
$FFED SCREEN Return screen dimensions
$FFF0 PLOT Read/set cursor position
$FFF3 IOBASE Return base address of I/O

Source Books

This knowledge base was compiled from these canonical references:

  1. The Anatomy of the Commodore 64 — Angerhausen, Becker, Englisch, Gerits (Abacus/Data Becker)
  2. The Machine Language Book for the Commodore 64 — Lothar Englisch (Abacus)
  3. The Advanced Machine Language Book for the Commodore 64 — (Abacus)
  4. COMPUTE!‘s Mapping the Commodore 64 — Sheldon Leemon (COMPUTE! Publications)
  5. COMPUTE!‘s VIC-20 and Commodore 64 Tool Kit: BASIC — Dan Heeb (COMPUTE!)
  6. COMPUTE!‘s VIC-20 and Commodore 64 Tool Kit: Kernal — (COMPUTE!)
  7. The Anatomy of the 1541 Disk Drive (Revised Edition) — (Abacus)
  8. The Complete Commodore 64 ROM Disassembly — P.G. & K.B. (Melbourne House)
  9. Compiler Design and Implementation (64 and 128) — (Abacus)
  10. COMPUTE!‘s SpeedScript — (COMPUTE!) — word processor source & techniques
  11. Invaluable Utilities for the Commodore 64 — (various)

Supplemental Emulator Source

  1. VICE 3.10 Manual — C:\Program Files\GTK3VICE-3.10-win64\doc\vice.txt
  • Use for emulator operation, autostart behavior, monitor commands, snapshots, and automation interfaces

Agent Workflow

When an AI agent receives a C64 development question:

  1. Identify the domain using the Skill Index table above
  2. Load the relevant SKILL.md from the appropriate skills/ subdirectory
  3. Cross-reference reference/ files for specific register values, addresses, or opcodes
  4. Check examples/ for working code patterns
  5. If the task involves running or debugging software in an emulator, load skills/vice-emulator/SKILL.md and reference/vice-usage.md
  6. Apply the 150-expert consensus: prefer documented Kernal routines over custom implementations; use zero-page for speed; always consider memory banking when accessing $D000–$DFFF

VICE Debug Workflow

When debugging a C64 program in VICE, agents should prefer this flow:

  1. Launch x64sc rather than the older x64
  2. Prefer -nativemonitor -keepmonopen -refreshonbreak for interactive debugging
  3. Start the monitor session with sidefx off
  4. Break at the machine-code entry point or suspicious routine
  5. Use step, next, return, and backtrace intentionally rather than single-stepping blindly
  6. Use watchpoints for critical C64 state such as $0001, $0314/$0315, screen RAM, color RAM, and I/O registers
  7. Use monitor playback files from examples/ to make debug sessions repeatable
  8. Use snapshots for short-lived checkpoints only, not archival state

For this repository specifically:

  • examples/vice-debug-c64os.bat launches c64os.prg with monitor-friendly options
  • examples/vice-monitor-c64os-debug.txt sets up a practical debug session for startup, banking, and command input

Common Development Patterns

Running ML from BASIC

10 FOR I=49152 TO 49162 : READ D : POKE I,D : NEXT
20 SYS 49152
30 DATA 169,0,141,32,208,169,15,141,33,208,96

Protecting ML from BASIC

POKE 56,192 : CLR  ' Sets BASIC top to $C000 (49152)

Reading the Kernal status after I/O

JSR $FFB7  ; READST — status in Accumulator
BNE error  ; any non-zero means error

Setting up a custom IRQ

SEI                 ; disable interrupts
LDA #<my_irq       ; low byte of handler
STA $0314
LDA #>my_irq       ; high byte
STA $0315
CLI                 ; enable interrupts

Powered by TurnKey Linux.