# HDGL Commodore 64 — complete package

A real, functioning Commodore 64 as a face of the substrate: a real 6502 core
executes the real KERNAL/BASIC ROMs, boots to a live BASIC prompt, and the
substrate observes its screen and projects it as the face — running through the
universal translator interface (`face_realize` / `face_tick` / `face_key`), one
operator for any translated OS. Boots on real hardware (fixed for high PCIe
framebuffer addresses).

## Boot it (Windows / Rufus)

1. Rufus → SELECT `iso/hdgl-c64.iso` → **DD Image mode** → START (erases the USB).
2. Boot the PC from USB (boot menu → the **non-UEFI / Legacy** USB entry).
   If USB doesn't appear: BIOS → enable **CSM / Legacy**, disable **Secure Boot**.
3. GRUB menu → pick an entry. After the blue screen, wait a few seconds:
   - **interactive** → `READY.`; type `PRINT 3+4` ⏎ → `7`
   - **self-test** → auto-types `PRINT 3+4` → `7` (no typing needed)

Under QEMU: `qemu-system-i386 -cdrom iso/hdgl-c64.iso -boot d -m 256`

## The two metal fixes (found by reading the code, not guessing)

1. **GDT segment limit 64MB → 4GB** (`OS64-master/src/gdt.cpp`). Real GPUs (e.g.
   Quadro NVS 295) expose the framebuffer at a high physical address (~`$F9000000`).
   The old 64MB segment limit made any write there a General Protection fault →
   triple fault → **reboot**. The 4GB flat segment makes high-address writes legal.
   This was THE "flash then reboot on metal" bug; invisible in QEMU because its
   framebuffer sits at a low address inside the old 64MB window.
2. **Prefer GRUB's real framebuffer** (`OS64-master/src/kernel.cpp`) instead of a
   hardcoded QEMU address, plus `set gfxpayload` in the ISO's grub.cfg so GRUB
   establishes a real linear framebuffer and hands it to the kernel.

Plus a speed fix: the 6502 step batch was raised 2000 → 200000 per screen
refresh, so BASIC boots in ~3-4s instead of ~16s.

## What's in here

```
iso/hdgl-c64.iso              bootable image for Rufus (GDT-fixed, fast boot)
kernels/                      the multiboot kernels
  os64_c64_interactive.bin      boots to READY.; type to use BASIC
  os64_c64_selftest.bin         auto-runs PRINT 3+4 = 7
  os64kernel.flat               raw binary (substrate blind-load)
glyph/                        the HDGL architecture as glyphs
  hdgl_universal_face.hdgl      universal translator: hardware-as-face ↔ OS-as-face
  hdgl_c64_node.hdgl            the C64 as an Omega-graph node
  hdgl_console.hdgl             console-out / PETSCII / seed glyphs
analogcontainer1/             the container primitive the face-node maps onto
  vector_container.h            VectorContext: a mathematical boundary (no escape)
roms/                         the real C64 ROMs (already baked into the kernel)
screenshots/                  proof: BASIC computing 3+4 = 7
OS64-master/                  the COMPLETE source tree (rebuilds clean)
```

## The architecture (universal translator)

The substrate does not re-implement any OS's hardware — it **translates** the
small, documented set of hardware-contract vectors an OS already uses (console
out, keyboard, IRQ) into substrate operations. One translator per OS dialect;
one operator drives them all. The C64 proves it: we translate CHROUT
(`$FFD2 → JMP($0326)`) and the keyboard buffer (`$0277`/`$C6`), not the silicon.

Key files:
- `OS64-master/include/c64/face_node.h` — the universal translator interface
- `OS64-master/src/c64/face_node.cpp` — the OS-agnostic operator + C64 translation table
- `OS64-master/src/c64/f6502/` — the real 6502 core (fake6502) + C64 memory bridge
- `OS64-master/src/c64/c64.cpp` — the C64 running through the translator
- `OS64-master/src/gdt.cpp` — the 4GB-segment metal fix
- `OS64-master/src/kernel.cpp` — framebuffer selection (GRUB-provided, metal-safe)

## Rebuild (Linux + gcc-multilib)

```sh
cd OS64-master
make os64kernel.bin
objcopy -O binary os64kernel.bin os64kernel.flat
# rebuild the ISO:
mkdir -p iso/boot/grub
cp os64kernel.bin iso/boot/os64_c64.bin
printf 'set timeout=5\ninsmod all_video\nset gfxpayload=800x600x16,auto\nmenuentry "HDGL C64" { multiboot /boot/os64_c64.bin; boot }\n' > iso/boot/grub/grub.cfg
grub-mkrescue -o hdgl-c64.iso iso
```

## Honest status

- **Verified in emulation:** boots through GRUB to the real BASIC banner and
  `READY.`; real BASIC computes `PRINT 3+4` → `7`.
- **Metal reboot fixed:** your boot log (`VGA Memory @ $F9000000`, blue stays, no
  reboot) confirmed the GDT fix landed. The remaining "blue but no text yet" was
  boot slowness, now fixed (~3-4s to BASIC).
- **`.hdgl` is not canonical yet** — the glyph files express the architecture,
  not a fixed grammar.
- Interactive typing works; timing is not cycle-exact (fine for BASIC/editor,
  not for tight raster demos).
