Skip to content

Select DSP-1 LLE or HLE at build time and preserve the reference contract - #150

Merged
mstan merged 3 commits into
mainfrom
codex/dsp1-build-selection
Oct 21, 2026
Merged

mstan merged 3 commits into
mainfrom
codex/dsp1-build-selection

Conversation

@mstan

@mstan mstan commented Oct 7, 2026 •

Copy link
Copy Markdown
Member

Select the existing DSP-1 LLE core or HLE command model when building, rather than changing implementations according to firmware availability at runtime. The engine defaults to LLE; HLE ignores firmware inputs and LLE fails its title preflight when required firmware is absent. DSP arithmetic and command timing are unchanged.

The companion Super Mario Kart PR explicitly keeps that title's existing firmware-free HLE default and preserves separately selectable LLE reference builds. Adopt it with this engine change to avoid introducing a new firmware requirement for the default SMK build. The companion also fixes the current-engine headless build by excluding desktop-only SDL diagnostic writers.

Disk and memory snapshots identify their DSP implementation and reject opposite-backend or old untagged DSP-1 states before live restoration. Non-DSP-1 snapshots and native game SRAM retain their existing format. No live switching or cross-backend snapshot conversion is provided.

Validation:

  • 6 LLE and 5 HLE contract tests passed, including the differential test with real DSP firmware, host protocol, missing/present firmware selection, and header identity.
  • Fresh paired SMK builds at framework 38dab07 completed the recorded 5,001-frame driving/pause/give-up route twice each, with zero audio underruns. Each backend's repeats have identical RAM, final video and complete WAV output.
  • Public disk/memory round trips and rejection of actual opposite-backend snapshots pass in both directions. HLE starts without firmware; LLE exits with its explicit missing-firmware diagnostic. The companion's default cache resolves to HLE without changing compiled objects.
  • Exact source, ROM/firmware and binary identities plus measured differences are recorded in docs/qualification/dsp1-smk-windows-20261021.json.

Qualification limits: this route does not complete a lap/race or exercise results/next-race progression. Listening qualification and clean-host representative performance remain unverified; another compiler job was active, so no new speedup is claimed. Native comparison differences are confined below row 111 at the four captured frames; do not treat that as full gameplay qualification or promote a shared-engine HLE default from it.

Tracked in beads-qhnd and beads-sity. No ROM, firmware or generated commercial-game source is included.

Merge scope: fixed build selection and snapshot identity for existing DSP implementations. No DSP algorithm/timing change or shared-engine HLE-default promotion. Full-race progression, listening and clean-host performance remain tracked follow-ups, not prerequisites for this wiring change. Owner policy explicitly permits breaking older save states; same-build correctness and native game saves remain required.

@mstan

mstan commented Oct 21, 2026

Copy link
Copy Markdown
Member Author

Reviewed 6372ca3 against current main. Keeping this PR draft in this merge sweep.

The build selection and snapshot identity design are reasonable. Fresh isolated Windows builds pass 5 LLE tests plus 5 HLE tests; the real-firmware differential test is explicitly skipped because this run supplied no firmware. The existing older real-firmware evidence remains separate.

There is a concrete default migration to resolve: the same no-firmware probe reports loaded=0 hle=1 on current main and loaded=0 hle=0 on this PR with default compiler settings. A firmware-free DSP-1 consumer that rebuilds without selecting HLE therefore loses its working backend. This is unrelated to the six released non-DSP-1 titles, but matters to Super Mario Kart. The consumer migration in mstan/SuperMarioKartRecompiled#1 is itself still a draft, with LLE as its default. Land a deliberate, validated consumer/default/missing-firmware disposition with this change.

The consumer qualification also explicitly leaves lower-map racer placements, later pixels and audio differences unqualified and does not complete a race. Tiny unnoticeable HLE differences are allowed; exact waveform or internal-state equality is not a requirement. What is missing is evidence that these observed differences stay within that tolerance through race completion/progression, plus an uncontaminated cost measurement for any performance/default promotion claim.

Tracking remains beads-qhnd and the SMK consumer qualification. These are specific remaining acceptance gaps, not failures of the focused unit tests. No runtime backend switch or cross-build snapshot conversion is requested.

@mstan

mstan commented Oct 21, 2026

Copy link
Copy Markdown
Member Author

Verification/fix update: real-firmware differential, protocol and selection tests now pass (6 LLE / 5 HLE). Fresh paired SMK builds complete the 5,001-frame driving/pause/give-up route twice each with identical per-backend repeat RAM/video/WAV hashes and zero underruns. Same-backend disk/memory restore and real opposite-backend rejection pass both ways.

The companion SMK PR now explicitly selects its existing firmware-free HLE default, fixing the default-build migration problem, and excludes desktop-only SDL diagnostic writers from the headless build. Both changes are pushed; precise hashes and capture metrics are in docs/qualification/dsp1-smk-windows-20261021.json. The combined local branch with #193 and newly merged #194-#197 passes 125 focused tests plus runtime dispatch.

Still draft: this input route does not complete a lap/race or verify results/next-race progression. Listening qualification and a clean-host performance comparison remain open; no new speedup or full-game qualification is claimed.

@mstan
mstan marked this pull request as ready for review October 21, 2026 21:34
@mstan
mstan merged commit 97fcafd into main Oct 21, 2026
8 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant