C64_SKILLS/.ai/skills/c64-memory-map/SKILL.md

Skill: C64 Memory Map and Address Discipline

Use this skill when

The task involves memory addresses, PEEK, POKE, page zero, screen/color memory, ROM/RAM/I/O banking, vectors, or safe placement of machine-language code.

Core concepts

• The 6510 can address 64K: $0000-$FFFF / 0-65535.
• Most two-byte addresses are stored little-endian: low byte first, high byte second.
• Page zero $0000-$00FF is fast and heavily used by BASIC/KERNAL.
• Page one $0100-$01FF is the processor stack.
• Screen RAM normally starts at $0400 / 1024.
• Color RAM normally starts at $D800 / 55296; only the low nybble is meaningful.
• I/O registers normally occupy $D000-$DFFF; character ROM or RAM can be banked into the same range.
• BASIC ROM is normally at $A000-$BFFF; KERNAL ROM at $E000-$FFFF.
• RAM exists under ROM/I/O areas, but using it requires banking and interrupt care.

Key addresses

Decimal	Hex	Meaning
0	$0000	6510 data-direction register
1	$0001	6510 processor port; controls ROM/I/O banking and cassette lines
43-44	$002B-$002C	Start of BASIC program text pointer
45-46	$002D-$002E	End of BASIC program text pointer
55-56	$0037-$0038	Top of BASIC memory pointer
198	$00C6	Keyboard buffer length
631-640	$0277-$0280	Keyboard buffer
646	$0286	Current text color
780-783	$030C-$030F	SYS register save/pass area: A, X, Y, status
788-789	$0314-$0315	IRQ vector
790-791	$0316-$0317	BRK vector
792-793	$0318-$0319	NMI vector
1024-2023	$0400-$07E7	Default 40x25 screen RAM
2040-2047	$07F8-$07FF	Default sprite pointers
49152	$C000	Common safe ML area if protected from BASIC use
53248	$D000	VIC-II register base
54272	$D400	SID register base
55296	$D800	Color RAM base
56320	$DC00	CIA #1 base
56576	$DD00	CIA #2 base

Safe machine-language placement

Common choices:

• $C000 / 49152: often used for ML routines because BASIC normally has about 38911 bytes free and does not use this area directly.
• Above a lowered BASIC top: set top-of-memory pointer and issue NEW before loading BASIC program.
• In a cartridge/ROM area only when explicitly building cartridge code.
• Avoid $033C-$03FB unless you know which cassette buffer or workspace is being used.

Banking rules

The 6510 processor port $0001 controls what the CPU sees in ROM/I/O ranges. Use cautious read-modify-write:

lda $01
pha
; change bits only as needed
; ... do banked access quickly ...
pla
sta $01

When banking out I/O or banking in character ROM, interrupts that use I/O can fail. Disable IRQ briefly with SEI, restore $01, then CLI.

BASIC bit manipulation patterns

Set a bit:

POKE A,PEEK(A) OR MASK

Clear a bit:

POKE A,PEEK(A) AND (255-MASK)

Toggle a bit:

POKE A,PEEK(A) XOR MASK

Agent checklist

Before suggesting memory writes:

1. Identify whether the address is RAM, ROM, I/O, color RAM, vector, or register.
2. State decimal and hex.
3. Warn about global side effects.
4. Preserve existing bits unless replacing the whole register is intentional.
5. Explain how to restore the original value.