# CD32 Native-Akiko — PBX Cache Performance Build (2026-05-10)

Performance-focused update to the CD32 native-Akiko fork. Rewrites the
PBX prefetch cache to handle multi-region access patterns and adds OS
page-cache pre-warming, dramatically reducing cold-boot load times for
games that interleave reads from multiple LBA regions.

**Inherits everything from `CD32-native-mvp`** (Cannon Fodder boot,
Akiko bridge, NVRAM saves, etc.) — see that release's README for the
CD32 ROM concat procedure and SD-layout prerequisites. This release
only changes `MiSTer` (the ARM userspace binary); `Minimig.rbf` is
identical to the prior release.

## What changed

### 1. Multi-window LRU PBX prefetch cache (`akiko_cd32.cpp`)

The previous cache used a single 128-sector window aligned to a
128-LBA boundary. Games that interleave reads from 3+ regions thrashed
it: every access evicted the prior region's window. Rewritten as
**4 windows × 128 sectors with LRU eviction**.

- 4 windows is the sweet spot — 8 was tested and slightly regressed
  Microcosm/CF (more thinly-distributed evictions). Streamers like
  Litil Divil have working sets >8 regions and don't benefit further.
- ~1.18 MiB BSS (host has 1 GB DDR3 — negligible).
- Per-window LRU tick; uint32 wraparound (~5 months of continuous play)
  is benign.
- Disc-swap invalidation preserved (cross-core corruption guard).

### 2. CHD page-cache pre-warm via `posix_fadvise(WILLNEED)`

When a CHD is mounted, the bridge now hints the kernel to start async
readahead of the entire file. The kernel pulls the CHD pages from USB
into RAM in the background while the CD32 BIOS does its boot dance.
By the time the bridge cache misses, the file is already in RAM —
USB read latency drops from ~30 MB/s to RAM speed.

Before this, the only way to get a fast load was to boot a game,
reset the core, and let the page cache stay warm for the second boot.
Now the first boot is fast.

## Measured improvements (cold cache, 4 windows + fadvise)

| Game | Hit ratio | Throughput | Note |
|---|---|---|---|
| **Sim City** | **99.9%** (was 39%) | **244 sec/s** (was 30) | 8.1× speedup, 3-region thrash eliminated |
| **Microcosm** | **98.8%** | **370 sec/s** | Heavy streamer; >2× native CD32 rate (300 sec/s) |
| Cannon Fodder | 97.8% | 177 sec/s | Sequential reader, no regression |
| Litil Divil | 95% | 27 sec/s | Working set >8 regions; game pacing dominates load time |

## Files

| File | Path on MiSTer | Purpose |
|---|---|---|
| `MiSTer` | `/media/fat/MiSTer` | Patched ARM userspace (multi-window cache + fadvise) |
| `Minimig.rbf` | `/media/fat/_Test/Minimig.rbf` | Minimig-AGA core (identical to CD32-native-mvp) |
| `*-CD32MVP.cfg` | `/media/fat/config/` | Per-game launch configs |
| `*-CD32MVP.mgl` | `/media/fat/_Computer/` | Per-game MGL launchers |

Bundled launcher set (16): Cannon Fodder, Sim City, Microcosm,
Liberation: Captive 2, Litil Divil, Beneath a Steel Sky, Chuck Rock 1,
Chuck Rock 2, Fire & Ice, Banshee, Fields of Glory, Defender of the
Crown, Deep Core, Alien Breed SE, Beavers, plus the CD32 No-CD test
launcher.

## CHD layout assumed

CFGs in this bundle point at the AmigaVision CD32 pack layout:
`/media/usb0/Games/AmigaCD32/<title>.chd` (most titles) or
`/media/usb0/Games/AmigaCD32/Not working on MiSTer yet/<title>.chd`
(Cannon Fodder, Chuck Rock 1, Chuck Rock 2, Fire & Ice, Simon).

Kickstart: `../usb0/Games/Amiga/roms/Caldor/cd32_swapped.rom` (390 KB,
byte-swapped CD32 Kickstart 3.1) — same as CD32-native-mvp.

## Diagnostic tooling (in `tools/`)

- `test_pbx_cache_perf.py <setname> --wait 60` — quick per-game probe;
  prints hit ratio, throughput, per-window refill histogram.
- `test_cold_cache_perf.py <setname> --wait 90` — drops kernel page
  cache before each run, gives apples-to-apples cold-boot numbers.
- `akiko_stall_report.py` — older, deeper sec_req-gap analysis.

## Known not-yet-fixed items

- **Litil Divil** stays slow (27 sec/s) — heavy FMV streamer with
  a working set larger than the cache. Improvement would need a
  larger prefetch batch (read 256-512 sectors per miss) or
  ahead-of-game-of-cache prefetcher. Out of scope for this release.
- **CFG path layout** — older CFGs from before the 2026-05-08
  AmigaVision deploy may point at `../usb0/Games/Amiga/CHD/...`.
  This bundle's CFGs are all updated to AmigaVision paths.
- **FastRAM default = 0x83** — historically inauthentic (real CD32
  had no fast RAM); some games stall with 0 fast that are likely
  fixable bridge bugs. Tracked for next release.
