games/nyuller
4
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit: C64 project skeleton with oscar64 submodule

Browse Source
This commit is contained in:
ballz
2026-07-17 00:36:14 +02:00
commit cbe5cf6a47
31 changed files with 29332 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
PROG_C64.md
+645
View File
@@ -0,0 +1,645 @@
# Programming the Commodore 64 — A Low-Level Overview
Notes from studying the downloaded C64 reference docs in `./docs/c64/`
(C64-Wiki, Christian Bauer's VIC-II article, the Commodore 64 Programmer's
Reference Guide, and the Oscar64 runtime headers). This is the practical
"how do I actually program the thing" companion to `OSCAR64.md`.
## 0. The mental model in one paragraph
The C64 is a 6510 (6502 plus an 8-bit I/O port) running at ~1 MHz, sharing
the bus with a 6567/6569 VIC-II graphics chip and a 6581 SID sound chip.
The VIC and CPU alternate bus cycles automatically; the VIC can "stun" the
CPU when it needs extra cycles. Two 6526 CIAs handle I/O and timers. The
whole 64 KB address space is overlaid with RAM, ROM, I/O, and Color RAM in
a swizzled fashion controlled by the 6510's $01 port plus the PLA. The
KERNAL ROM at $E000-$FFFF is always present at reset and provides 39
service routines via a jump table at $FF81-$FFF3. There is no memory
protection. To make the chip set do interesting things, you write to its
registers — for the VIC that's $D000-$D3FF, for the SID $D400-$D7FF, for
the CIAs $DC00-$DCFF and $DD00-$DDFF. Everything visible on screen is
driven by writes to these registers plus writes to the 1 KB of "screen
memory" at $0400-$07FF and the 1/2 KB of "color RAM" at $D800-$DBFF.
## 1. The hardware
```
+-------+ +-------+ +-------+ +--------+
| BASIC | |KERNAL | | CHAR | | 8x8K |
| ROM | | ROM | | ROM | | RAM |
+--++---+ +--++---+ +--++---+ +--++---+
|| || || ||
+------+||+++++++++||+++++++++||++++++++++++||+++++
| PLA |+>------------>------------>----------- --->| (chip selects)
+--+---+ |
| |
+------+------+ +-----+----+
| 6510 | | VIC-II |
| CPU |<--data/addr----+--------------+ 6569 |
+-----+------+ | | +-----+----+
| | | |
| | | +--------+ |
| | +--+ 6581 | |
| | | | SID | |
| | | +--------+ |
| | | |
+-----+-----+ +-----+--+----+ +-----+-----+
| 6526 CIA1| | 6526 CIA2 | | 4-bit |
| (IRQ) | | (NMI) | | Color RAM|
+-----+-----+ +-----+-------+ +-----------+
| |
+----------+----------+ |
| keyboard, joystick | +-----+----+
| paddles, datasette | | IEC bus |
+---------------------+ | RS-232 |
| userport|
+----------+
```
The 6510's port at `$01` plus the PLA determine which of BASIC, KERNAL, CHAR
ROM, and I/O is visible at $A000-$BFFF, $E000-$FFFF, and $D000-$DFFF
respectively. CIA 2 port A bits 0-1 pick one of four 16 KB "VIC banks" by
extending the VIC's 14-bit address bus to a full 16 bits.
## 2. The bus and the "stun" mechanism
This is the bit that explains every weird timing thing on the C64.
The system clock is one period of ϕ2 (phi2). PAL: ~985 kHz, NTSC: ~1.023 MHz.
The VIC generates the pixel clock (8 pixels per ϕ2 cycle) and divides by 8
to make ϕ0, which the 6510 delays by ~30-40 ns to make ϕ2. Within each ϕ2
cycle, the first half (ϕ2 low) is the VIC's turn and the second half (ϕ2
high) is the CPU's turn. So they normally share the bus cleanly with no
contention.
The VIC needs extra cycles for two things:
1. **C-accesses** — 40 character-pointer reads at the start of each text
row. These happen on "badlines" (every 8th raster line when the display
is enabled and `(RASTER & 7) == YSCROLL` for raster in the range $30-$F7).
2. **S-accesses** — 2 sprite data reads per sprite per scanline, when the
sprite's Y position matches the current raster line.
For these, the VIC pulls BA (Bus Available) low 3 cycles early. BA is wired
to the 6510's RDY line. The 6510 can only be paused on a *read* (writes
can't be paused — that's why the VIC waits up to 3 cycles: 3 is the
maximum run of consecutive writes the 6510 can do). When AEC is then held
low for the second half of a cycle too, the VIC owns the bus exclusively.
The 6510's actual data/address timing from the datasheet, relative to ϕ2:
- Address valid: 100-300 ns after falling edge of ϕ2.
- Write data valid: 150-200 ns after rising edge of ϕ2.
- Read data latched on falling edge of ϕ0.
In practice the C64 is a bit slower than this because the VIC holds AEC
late, so address is valid about 60-75 ns after ϕ2 rising edge and data
another ~120 ns later.
**Why this matters:** any code that depends on cycle-accurate timing
(raster IRQ tricks, floppy timing, raster bars) has to count cycles
*including* badline stalls. The "raster stable" raster line (line 311 on
PAL) is the line right after vertical blank where no badline penalties
have happened recently, so cycle counts on that line are exact.
The VIC also performs 5 DRAM refresh accesses per raster line — that
means you don't have to refresh the 64 KB of main RAM yourself; the VIC
does it. (Pretty unusual for a graphics chip.)
## 3. The 6510
- 6502 plus a 6-/8-bit on-chip I/O port.
- 16-bit address bus, 8-bit data bus.
- Two external interrupts: **IRQ** (maskable via the I flag in P; SEI/CLI)
and **NMI** (non-maskable; fires on RESTORE key or CIA 2 /FLAG).
- Three vectors in the top six bytes of the address space (KERNAL ROM
always present at reset):
- `$FFFA-$FFFB` NMI → `$FE43`
- `$FFFC-$FFFD` RESET → `$FCE2`
- `$FFFE-$FFFF` IRQ / BRK → `$FF48`
The 6510 is *object-code-compatible* with the 6502. Same instruction set,
same addressing modes, same cycle counts. The only thing the 6510 adds is
the port.
The port lives at `$00` (data direction, 1=output) and `$01` (data). `$01`
is also the CPU's bank-switch latch. The bit meanings:
| Bit | Name | Effect |
|-----|------|--------|
| 0 | LORAM | 0=RAM at $A000-$BFFF, 1=BASIC ROM |
| 1 | HIRAM | 0=RAM at $E000-$FFFF, 1=KERNAL ROM |
| 2 | CHAREN | 0=CHAR ROM at $D000-$DFFF, 1=I/O (default) |
| 3 | Cassette Data Out |
| 4 | Cassette Switch Sense |
| 5 | Cassette Motor (0=on) |
| 6-7 | Unused |
Default after reset is `$37` (%00110111) — everything visible, cassette
motor off.
To run with no ROMs (for a self-contained .prg that owns all memory), set
`$01` to `$34` (or thereabouts depending on whether you need CHAR ROM).
The Oscar64 runtime does exactly this kind of bank switching in its crt.c
when `-rt=` is given, and the oscar64 `mmap_set` API exposes it.
There is no "address 0/1 in RAM". The 6510 port occupies those two
addresses. To read the underlying RAM, you have to use a VIC trick
(corrupting the datassette buffer at $02 and using the VIC's read
prefetch), but you almost never need to.
## 4. The memory map (after reset, no cartridge)
| Address | Contents |
|---------|----------|
| $0000-$00FF | Zeropage (see §5) |
| $0100-$01FF | Hardware stack (and a few KERNAL scratch bytes at the bottom) |
| $0200-$02FF | BASIC / KERNAL pointers |
| $0300-$03FF | More KERNAL/BASIC pointers; **$0314-$0315 = IRQ vector, $0316-$0317 = BRK vector, $0318-$0319 = NMI vector** |
| $0400-$07FF | Screen RAM (1000 bytes for the 40×25 text screen) |
| $0800-$9FFF | Free BASIC program storage (38911 bytes) |
| $A000-$BFFF | BASIC ROM (8 KB, visible iff LORAM=1) |
| $C000-$CFFF | Free for ML programs |
| $D000-$D3FF | VIC-II registers (47 of them, mirrored every 64 bytes) |
| $D400-$D7FF | SID registers (mirrored every 32 bytes; not on C128) |
| $D800-$DBFF | Color RAM (1000 nibbles, 4-bit wide) |
| $DC00-$DCFF | CIA 1 |
| $DD00-$DDFF | CIA 2 |
| $DE00-$DFFF | I/O expansion / open bus |
| $E000-$FFFF | KERNAL ROM (8 KB, visible iff HIRAM=1) |
Two important properties:
- **Write-through to RAM under ROM.** If a write targets an address where
ROM is currently visible, the read still goes to the ROM but the data
is written to the underlying RAM. This is how a .prg loaded at $0801
can be "installed" — the kernal loads it at the standard BASIC start
address $0801, writes a 0 to $01 to hide ROMs, then JMPs to the entry
point. The RAM at $A000-$BFFF and $E000-$FFFF is still 8 KB of usable
space once you bank it in. (But you have to write a custom ISR vector
because the KERNAL ISR is in $EA31, which is in KERNAL ROM.)
- **Color RAM upper nibble is open bus.** Color RAM is a 4-bit-wide
2114 SRAM, so reads of $D800-$DBFF return the low nibble as a valid
color, but the high nibble is "random" (often it reflects the last
byte the VIC read, due to bus capacitance).
For full detail see `docs/c64/memory/memory_map.md`.
## 5. Zero page
Every 6502 has 256 bytes of "page 0" with a special addressing mode that
is 1 byte shorter and 1 cycle faster than the equivalent absolute mode.
The C64 puts the 6510 port at $00/$01, the floating-point accumulators at
$61-$6E, the BASIC interpreter state at $2B-$8F, the keyboard buffer
state at $C5-$D7, and a ton of other shared state through the rest of the
page. The hardware stack (which the 6502 grows downward) lives in
$0100-$01FF, so $013F-$01FF is the actual usable stack.
For ML work the "free" scratch locations are very few. A common pattern:
a few variables at $FB-$FE (which the KERNAL doesn't touch except for
$FF in the float-to-ASCII routine), and the area $C0-$C4 is free when
no cassette or serial I/O is in progress.
For the full table of every zero-page address, see
`docs/c64/memory/zeropage.md`.
The Oscar64 runtime uses its own scheme (it dedicates a zero-page window
to its software stack, e.g. $F7-$FF on a C64, and shifts it around for
other targets — see `Compiler.cpp` lines 57-105 for the ZP register
allocation logic).
## 6. The VIC-II: how the screen actually gets drawn
The VIC has:
- A 14-bit address bus (16 KB of address space). The high 2 bits come
from CIA 2 port A, picking one of 4 banks.
- A 12-bit data bus (8 normal + 4 directly to color RAM).
- A 320×200 pixel display generated 8 pixels at a time (1 character cell).
- 16 colors, fixed palette (see below).
- 8 sprites (MOBs), 24×21 each (12×21 in multicolor).
- 5 DRAM refresh accesses per line.
- A raster counter you can read at $D012 (low 8 bits; the 9th bit is
bit 7 of $D011).
### 6.1 The display window and border
The VIC paints within a fixed "display window" surrounded by a border in
the color stored in $D020. The window dimensions are selected by
RSEL (bit 3 of $D011) and CSEL (bit 3 of $D016):
| RSEL | Window height | First line | Last line |
|------|---------------|------------|-----------|
| 0 | 24 rows (192 px) | 55 ($37) | 246 ($F6) |
| 1 | 25 rows (200 px) | 51 ($33) | 250 ($FA) |
| CSEL | Window width | First X | Last X |
|------|--------------|---------|--------|
| 0 | 38 cols (304 px) | 31 ($1F) | 334 ($14E) |
| 1 | 40 cols (320 px) | 24 ($18) | 343 ($157) |
The YSCROLL (bits 0-2 of $D011) and XSCROLL (bits 0-2 of $D016) shift the
*content* of the window in 1-pixel increments, which is how smooth
scrolling works. (Set RSEL=1, CSEL=1, and XSCROLL=YSCROLL=0 to get the
canonical 40×25 layout, or XSCROLL=YSCROLL=7 for 38×24, etc.)
DEN (bit 4 of $D011) is the "display enable" master switch. If DEN=0 the
VIC still runs but doesn't actually display anything.
### 6.2 Badlines and bus stalls
A "badline" is any line on which the VIC has to do the 40-character
pointer read. By default that happens on the first raster line of each
text row, i.e. every 8th line. The exact definition (from Christian
Bauer's article):
> A Bad Line Condition is given at any arbitrary clock cycle if, at the
> negative edge of ϕ0 at the beginning of the cycle, RASTER >= $30 and
> RASTER <= $f7 and the lower three bits of RASTER are equal to YSCROLL,
> and if the DEN bit was set during an arbitrary cycle of raster line $30.
That means you can trigger a badline manually by changing YSCROLL mid-line
— this is the basis of FLI/AFLI/NUFLI, the demo scene hacks that get
more colors per cell.
When a badline fires, the VIC "stuns" the CPU for 40 cycles (plus the
3-cycle setup), then does 40 c-accesses to read the video matrix. That's
the 40-cycle-per-text-row overhead that the CPU pays for graphics.
### 6.3 The 16 colors
The 16-color palette is hard-wired in the VIC (the VIC generates color
from the phase and amplitude of a signal derived from a 14.3/17.7 MHz
color clock):
| Code | Color | Code | Color |
|------|----------|------|-------------|
| 0 | Black | 8 | Orange |
| 1 | White | 9 | Brown |
| 2 | Red | 10 | Light red |
| 3 | Cyan | 11 | Dark gray |
| 4 | Pink | 12 | Medium gray |
| 5 | Green | 13 | Light green |
| 6 | Blue | 14 | Light blue |
| 7 | Yellow | 15 | Light gray |
### 6.4 The 5 legal graphics modes
The VIC is set into one of 5 legal "modes" by three bits:
- **ECM** (Extended Color Mode) — bit 6 of $D011
- **BMM** (Bitmap Mode) — bit 5 of $D011
- **MCM** (Multicolor Mode) — bit 4 of $D016
| Mode | ECM BMM MCM | Result |
|------|-------------|--------|
| 0 | 0 0 0 | Standard Character Mode (40×25 text) |
| 1 | 0 0 1 | Multicolor Character Mode |
| 2 | 0 1 0 | Standard Bitmap Mode (hires, 320×200) |
| 3 | 0 1 1 | Multicolor Bitmap Mode (160×200) |
| 4 | 1 0 0 | Extended Background Color Mode |
Modes 5-7 are technically possible but produce no visible output.
In Standard Character Mode:
- Screen memory at $0400-$07FF (40×25 = 1000 bytes) holds character codes
(PETSCII values 0-255, but the character generator only has 256 chars so
effectively 0-255).
- Color RAM at $D800-$DBE7 (1000 nibbles, low 4 bits) holds the color of
each character cell, drawn from the 16-color palette.
- One global background color in $D021.
- Character patterns in the char generator (default 4 KB at $D000-$DFFF
in banks 0/2; can be relocated by changing $D018 to point to RAM at
$1000-aligned addresses).
In Bitmap Mode:
- 8000 bytes of bitmap at the address pointed to by bits VM13-VM10 of
$D018 (in 8 KB steps). Each bit is one pixel.
- 1000 bytes of "screen memory" at the address pointed to by bits VM13-VM10
in 1 KB steps. The screen memory holds color information: the low 4
bits are the cell's foreground color, the high 4 bits are the cell's
background color *index* (0-3, picking one of $D021-$D024). When MCM=1,
the 2 bits per pixel pick from $D021/$D022/$D023/color RAM.
### 6.5 Sprites
8 sprites (MOBs), each:
- 24×21 pixels (12×21 in multicolor).
- Data: 63 bytes + 1 unused pad = 64 bytes, must be 64-byte aligned in the
current VIC bank.
- Position: X (9 bits — low 8 in $D000/$D002/.../$D00E, bit 8 in $D010
one bit per sprite) and Y (8 bits in $D001/$D003/.../$D00F).
- Color: $D027-$D02E (one per sprite); shared multicolor colors at
$D025 (MC0), $D026 (MC1).
- Pointer: at $07F8-$07FF (one byte per sprite; contains the pattern
address divided by 64).
- Enabled: $D015 (one bit per sprite).
- Mode (hires or multicolor): $D01C (one bit per sprite).
- X/Y expansion: $D01D (X) and $D017 (Y), one bit per sprite.
- Priority vs background: $D01B (one bit per sprite, 1 = behind
background).
- Sprite-sprite priority is hardwired: lower-numbered sprite is in front.
- Collision detection: $D01E (sprite-sprite, read clears) and $D01F
(sprite-data, read clears). Bits 1 and 2 of $D019 / $D01A are the
collision IRQ flag and enable.
The "trick" of showing more than 8 sprites is to use raster IRQs to
re-load the sprite pointers and Y positions mid-frame, presenting a
different set of up to 8 sprites on each part of the screen. With careful
timing you can show 24+ sprites on a single line.
### 6.6 Raster interrupt
The raster IRQ is the heart of all the C64 graphics tricks. The hardware
fires IRQ whenever the 9-bit raster counter (RASTER in $D012 plus bit 7
of $D011) equals the 9-bit value last written to those same bits.
The standard setup is:
```asm
Init SEI
LDA #%01111111
STA $DC0D ; mask CIA 1 IRQs
AND $D011 ; clear bit 7 of $D011 (RST8)
STA $D011
STA $DC0D ; ack CIA 1
STA $DD0D ; ack CIA 2
LDA #<raster_line ; raster line low
STA $D012
LDA #<Irq
STA $0314 ; IRQ vector
LDA #>Irq
STA $0315
LDA #%00000001
STA $D01A ; enable raster IRQ in VIC
CLI
RTS
Irq ; do stuff
ASL $D019 ; ack: clear bit 0 of $D019
JMP $EA31 ; chain into KERNAL ISR (or $EA81 to skip)
```
The 8-bit "raster line 311" trick (writing a specific YSCROLL value
during certain ranges of the raster counter to force extra badlines) is
the basis of FLI/AFLI/NUFLI.
Stable raster: raster line 311 on PAL is the one that gives the cleanest,
most predictable cycle counts because no recent badline penalty is in
effect. Writing to $D012 on this line will trigger the IRQ exactly
63 cycles later.
For the rest of the line the timing is stable too; Christian Bauer's
article has the full per-cycle timing table.
## 7. The SID
The 6581 (early C64s) or 8580 (C64C) is a 3-voice analog synthesizer
chip designed by Bob Yannes. The 8580 is "cleaner" but lacks the bugs
of the 6581 that people used for tricks like 4-bit sample playback.
Each voice has:
- 16-bit frequency ($D400/$D401, $D407/$D408, $D40E/$D410).
- 12-bit pulse width ($D402/$D403, $D409/$D40A, $D410/$D411).
- Control register $D404 / $D40B / $D412: gate, sync, ring mod, test,
triangle, saw, pulse, noise.
- ADSR envelope in $D405/$D406 etc. (4-bit attack, 4-bit decay, 4-bit
sustain, 4-bit release).
Shared:
- Filter cutoff at $D415/$D416 (low 3 bits + 8 bits).
- Filter routing/resonance at $D417 (high 4 bits = resonance, low 4 bits
= enable ext/v3/v2/v1).
- Filter mode and master volume at $D418 (bit 6 = mute V3, bit 5 = HP,
bit 4 = BP, bit 3 = LP, bits 0-3 = volume 0-15).
- Read-only: $D419 paddle X, $D41A paddle Y, $D41B oscillator V3, $D41C
envelope V3.
Classic 4-bit sample playback on the 6581: rapidly write the high nibble
of $D418 to output 4-bit sample values. The 8580 fixed this "feature" so
samples are very quiet; restoring it requires a 470kΩ-1MΩ resistor on
EXT IN to GND.
## 8. The CIAs
Two 6526 CIAs. CIA 1 drives the keyboard, joysticks, paddles, and
datasette. CIA 2 drives the serial (IEC) bus, RS-232, the userport, and
provides the VIC bank bits (lower 2 of port A).
Each CIA has:
- Two 16-bit timers (A and B). Timer A is normally used by the KERNAL
IRQ for the jiffy clock.
- 24-hour TOD clock with alarm (B.C.D format).
- 8-bit serial shift register.
- 16 GPIO lines (PA0-PA7, PB0-PB7), with separate DDR.
- Interrupt control register (ICR) with sources from timers, TOD, serial,
FLAG pin.
The CIA is at $DC00 (CIA 1) and $DD00 (CIA 2); each is 16 bytes, mirrored
every 16 bytes in its 256-byte page.
### 8.1 Joystick reading
The joystick switches are wired in parallel with the keyboard matrix.
Reading $DC00 (PRA, port 2 / left) and $DC01 (PRB, port 1 / right) gives
a byte where the low 5 bits are active-low direction + fire. The
high 3 bits are keyboard column bits. Rest position, no buttons, is $7F
(127) on port 2 and $FF (255) on port 1.
Important: in the C64, the CIA 1 IRQ line is the IRQ for the *whole CPU*.
If you don't want CIA 1 timer A to fire IRQ (which is the default and
triggers the jiffy-clock-and-keyboard-scan KERNAL handler), mask it via
`$DC0D` (the ICR) at the start of your raster-IRQ setup.
## 9. The KERNAL
39 service routines, jump table at $FF81-$FFF3. The most useful ones for
low-level work:
| Use | Call |
|-----|------|
| Print a character | `JSR $FFD2` (CHROUT, A = char) |
| Read a character | `JSR $FFCF` (CHRIN) — A = char on return |
| Test for STOP key | `JSR $FFE1` (STOP) — carry set if STOP pressed |
| Open a file | `JSR $FFC0` (OPEN) — A=LA, X=FA, Y=SA |
| Close a file | `JSR $FFC3` (CLOSE) — A=LA |
| Set filename | `JSR $FFBD` (SETNAM) — A=length, X/Y=ptr |
| Set logical file | `JSR $FFBA` (SETLFS) — A=LA, X=FA, Y=SA |
| Load | `JSR $FFD5` (LOAD) — .A=0 load, .A=1 verify |
| Save | `JSR $FFD8` (SAVE) — A=zpage pointer, X/Y=end ptr |
| Read clock | `JSR $FFDE` (RDTIM) — A/X/Y = jiffy/seconds/min |
| Set clock | `JSR $FFDB` (SETTIM) — A/X/Y = same |
| Plot (get/set cursor) | `JSR $FFF0` (PLOT) — carry=set, X=row, Y=col |
Oscar64 wraps these in its runtime. `printf("hello")` ultimately calls
CHROUT in a loop; `getch()` calls CHRIN; `oscar_kernalio.h` provides the
serial-bus file routines.
## 10. The interrupt model
### 10.1 Hardware vectors
In the top 6 bytes of KERNAL ROM (always mapped at reset, in the top of
the 64 KB address space):
- `$FFFA-$FFFB` NMI
- `$FFFC-$FFFD` RESET
- `$FFFE-$FFFF` IRQ / BRK
The KERNAL entry points then read indirect RAM vectors:
- `$0314-$0315` IRQ (default → $EA31, the KERNAL standard IRQ)
- `$0316-$0317` BRK (used for the BASIC `BRK` instruction in monitor-style use)
- `$0318-$0319` NMI (default → $FE47)
### 10.2 The KERNAL IRQ handler
When an IRQ fires, the 6510 hardware pushes P and PC and jumps via
($FFFE) to $FF48. $FF48 pushes A, X, Y onto the stack and then indirect-
jumps via $0314 (for IRQ) or $0316 (for BRK). The default $0314 → $EA31
runs the standard KERNAL ISR which:
1. Reads CIA 1 ICR to find the source.
2. If timer A: increments the jiffy clock at $A0-$A2.
3. Scans the keyboard.
4. Handles the cursor blink.
5. Checks for RUN/STOP.
6. Exits via $EA81 which pulls A/X/Y and `RTI`.
The stack at the start of a user IRQ handler is (top to bottom):
PC_hi, PC_lo, P, A, X, Y.
The fastest way to do an IRQ that does work but still gets the KERNAL
service: end with `JMP $EA31`. The fastest way to do an IRQ that needs
no KERNAL service at all (e.g. a music player): end with `JMP $EA81`.
### 10.3 NMI
NMI is wired to CIA 2's FLAG pin, which is the RESTORE key. The KERNAL's
NMI handler at $FE47 is also the "soft reset" entry: if RUN/STOP is held
when RESTORE is pressed, the system returns to BASIC without losing the
program in memory. To disable the soft-reset, mask CIA 2 interrupts
($DD0D).
## 11. The character set and PETSCII
PETSCII is the C64's character encoding — not ASCII. Printable range is
$20-$7E and $A0-$FE (with some overlap differences). CR ($0D) is the
line terminator, not LF. There's an upper/lowercase font switch:
$00-$1F are graphics characters in uppercase mode; $00-$1F are
uppercase letters in lowercase mode (the "shifted" font).
The two font variants:
- "Uppercase" / graphics mode: PETSCII $00-$1F → graphics chars
- "Lowercase" mode: PETSCII $00-$1F → uppercase letters
Switch with `iocharmap(IOCHM_PETSCII_2)` in Oscar64. In assembly: KERNAL
call `CHROUT` with $0E to set uppercase+graphics, $8E for lowercase.
In Oscar64 you can mark string literals with `p""` for PETSCII or `s""`
for screen code (the byte values used directly in screen memory, which
are the same as the character set ROM offsets).
## 12. Putting it all together: a tiny "hires clear" example
In C, with Oscar64:
```c
#include <c64/memmap.h>
#include <c64/vic.h>
#include <gfx/bitmap.h>
char Color[1000];
char Hires[8000];
Bitmap Screen;
int main(void) {
mmap_trampoline();
mmap_set(MMAP_RAM); // bank out BASIC+KERNAL
memset(Color, 0x01, 1000); // white-on-black
memset(Hires, 0x00, 8000); // clear bitmap
mmap_set(MMAP_NO_ROM); // also bank out the I/O CHAR ROM
// (so hires memory is visible)
vic_setmode(VICM_HIRES, Color, Hires);
vic.color_border = VCOL_WHITE;
bm_init(&Screen, Hires, 40, 25);
getch();
mmap_set(MMAP_ROM); // put ROMs back
vic_setmode(VICM_TEXT, (char*)0x0400, (char*)0x1000);
return 0;
}
```
What this exercises:
- Bank switching: `mmap_set` writes to $01 (and triggers the trampoline
for IRQs).
- Absolute addressing: `char *Hires = (char*)0xe000` is the
straightforward way to reach video memory, made possible by
`mmap_set(MMAP_RAM)` which gives us $E000-$FFFF as 8 KB of RAM (with
the CHAR ROM not at $D000 anymore, because CHAREN=0 maps CHAR ROM
there).
- VIC control: `vic_setmode` writes ECM/BMM/MCM, $D018 (video matrix
and bitmap pointers), $D016 (CSEL=1, XSCROLL=0), and the screen
memory pointer (set via CIA 2 PRA low 2 bits, plus $DD00 writes).
## 13. Things to remember
- The VIC and CPU share the bus. Badlines cost 40 cycles every 8 lines
in text mode. Cycle-counting code on other lines gives you one cycle
per line, but the badline penalty can blow your timing.
- Writes to ROM addresses go to underlying RAM. This is how .prg files
install themselves and how you can put code at $A000 without banking
out BASIC (just write to the right places, but BASIC will still run if
you don't bank it out).
- The 6510 I/O port at $00/$01 is the master bank switch. Three bits
(LORAM, HIRAM, CHAREN) plus the PLA. The Oscar64 `mmap_set` API
exposes this as `MMAP_NO_BASIC`, `MMAP_RAM`, `MMAP_NO_ROM`, etc.
- The VIC raster counter is 9 bits. Always write to $D011 bit 7 (RST8)
and $D012 together to set the IRQ trigger line. Reading them also
gives you 9 bits of current raster.
- The KERNAL ISR at $EA31 does useful work (jiffy clock, keyboard scan,
cursor blink) but you can call $EA81 to skip it. For a music player
running in IRQ, the trick is to keep $EA31 alive by patching $0314 to
your routine, ending with `JMP $EA31`.
- PETSCII != ASCII. Use `p""` or `s""` prefixes in Oscar64, or `-psci`
on the command line. Use the KERNAL `CHROUT` ($FFD2) and `CHRIN` ($FFCF)
for character I/O so the translation happens.
- The Color RAM upper nibble is meaningless. Only the low 4 bits are
connected.
- Sprites need to be 64-byte aligned in the current VIC bank. The
pointers at $07F8-$07FF are byte values, pattern address / 64.
- The SID's 6581 has bugs that the 8580 doesn't. If you want 4-bit
sample playback, you need a 6581 (or simulate the bug).
- The CIAs' FLAG pins are NMI/IRQ sources. The RESTORE key triggers an
NMI through CIA 2. If you want RUN/STOP+RESTORE to be a no-op, mask
CIA 2 NMI in $DD0D.
## 14. Where to look for more
- `docs/c64/memory/memory_map.md` — every address
- `docs/c64/memory/zeropage.md` — every zero-page address
- `docs/c64/memory/hardware_internals.md` — block diagram and bus
- `docs/c64/vic/vic_registers.md` — every VIC register
- `docs/c64/vic/graphics_modes.md` — the 5 official modes
- `docs/c64/vic/cebix-vic-article.txt` — Christian Bauer's VIC paper
(the canonical timing reference, 80 pages, dense)
- `docs/c64/sprites/sprites_overview.md` — sprite programming
- `docs/c64/interrupts/raster_interrupt.md` — how to set up a raster IRQ
- `docs/c64/interrupts/interrupts_overview.md` — IRQ/NMI/BRK flow
- `docs/c64/cia/cia_overview.md` — CIA 1 + CIA 2 register maps
- `docs/c64/sid/sid_overview.md` — SID register map, ADSR, filter
- `docs/c64/kernal/kernal_jumptable.md` — every KERNAL entry point
- `docs/c64/kernal/c64_programmers_reference_guide.txt` — the full
500-page official Commodore 64 Programmer's Reference Guide (1982)
The PRG is dense and a bit old-fashioned (it's 1982) but it's the
definitive reference and includes the full instruction set with cycle
counts. Christian Bauer's VIC article is the modern, exhaustive
treatment of the VIC-II — section 3.14 ("Effects and applications") is
where the FLI/AFLI/NUFLI/etc. tricks are explained.