Unified PPU & APU Graphics-Backend Micro-Codes

1. Proposal and goals

Introduce a single, generic micro-code compilation model with three execution targets: CPU, GPU Graphics, and GPU Compute. The emulated machine's hardware rules stay in .phlegm definitions; generic native primitives and graphics drivers provide efficient execution.

This document authorizes no source edits by itself. It defines a plan to review before implementation, with incremental, testable deliveries rather than a single all-at-once rewrite.

2. Starting baseline and non-negotiable invariants

The intended starting point is PHLEGM v9 r13 (SNES Mode 7 compile fix), subject to checking whether a newer successful revision exists at implementation time. The proposed first implementation milestone is v9 r14; later revision labels must follow actual completed milestones, not speculative work.

• Micro-code compilation boundary: compile active machine-specific programs on machine load and when a session restore requires it; do not compile them during developer builds, bootstrap, or distribution packaging.
• No persistent compiled machine state: invalidate machine-specific compiled programs when changing machines or restoring sessions. Backend shader objects may be cached within the current active machine lifetime only.
• Native genericity: keep SNES/PET/NES behavior in definitions rather than adding machine-name conditionals to microcode.lib, compute.lib, or gfx_*.lib.
• CPU fallback: no machine, video mode, or audio device may require a GPU compute shader.
• Platform contract: maintain Windows 32/64 OpenGL/D3D11 and Linux x86/x86_64 OpenGL/Vulkan target support.
• Packaging contract: preserve existing bootstrap/compiler UI behavior and FreeBASIC toolchain. Do not ship Python scripts or dependencies. Use canonical forward slashes in definition paths.
• Hardware/legal contract: do not bundle proprietary SNES firmware; preserve machine-declared external firmware sourcing.

3. Unified execution pipeline

The dispatcher selects an implementation based on the primitive, capability, accuracy contract, and measured performance. A graphics backend is a route to GPU computation; sound is not passed through image presentation.

4. Library and component responsibilities

The proposed compute.lib is a new optional abstraction, not an existing confirmed module. Before edits, inspect the actual r13 library interfaces and reuse existing host/graphics integration where practical. Keep aa.lib's associative-array/FBVM responsibilities unchanged.

5. Definition schema and generic primitive contracts

Extend the definitions with typed micro-code operations and explicit execution constraints. Each operation must describe its inputs/outputs, integer width or sample format, state dependencies, memory effects, precision/rounding, and allowed execution targets.

Illustrative IR intent (not valid .phlegm syntax):
PROGRAM SNES_PPU_MODE7
  INPUT: raster_register_snapshot, vram_snapshot, cgram_snapshot
  OPS:   AFFINE_2D, COORD_WRAP, TILE_FETCH,
         TEXEL_FETCH, PALETTE_LOOKUP, RASTER_OUTPUT
  MATH:  deterministic fixed-point
  TARGET: CPU_REQUIRED, GPU_GRAPHICS_OPTIONAL
  SYNC:  raster-state-boundary
END

PROGRAM SNES_DSP_SELECTED_KERNEL
  INPUT: dsp_register_snapshot, voice_state, sample_clock
  OPS:   AUDIO_SAMPLE_INTERPOLATE, AUDIO_VOICE_MIX
  TARGET: CPU_REQUIRED, GPU_COMPUTE_OPTIONAL
  SYNC:  ordered-sample-block
END

6. PPU graphics micro-codes & SNES Mode 7

Keep SNES-PPU as one support chip. Its mode selection, register latches, scroll/center coordinates, tilemap/palette rules, pixel priority, and special effects remain in definitions compiled into generic raster operations.

Rendering pipeline

1. Schedule emulated PPU register, VRAM, CGRAM and OAM writes at the correct emulated time.
2. Snapshot or segment state at scanline/pixel boundaries where hardware changes affect pixels.
3. Compile Mode 7 affine/tile fetch into generic primitives, using SNES-accurate fixed-point and overflow behavior.
4. Execute CPU reference rasterization first; build a GPU Graphics translation after pixel-level tests pass.
5. Integrate color math, sprites, priority, windows and HDMA-dependent raster effects incrementally.
6. Present the validated framebuffer; report rendering backend and checksums for comparison.

Mode 7 operations are highly parallelizable per pixel, but mid-frame register writes and HDMA mean a single immutable frame-wide uniform state may be insufficient. Raster state and read-after-write visibility must be modeled explicitly.

7. APU micro-codes & optional GPU Compute

Keep the S-SMP/SPC700 instruction engine, IPL handshake, APU port communication, timers and CPU↔APU synchronization on the timing-controlled CPU micro-code path. The S-DSP produces roughly 32 kHz audio and is the candidate for selected general-purpose GPU compute workloads.

Small SNES workloads can be slower on a GPU because dispatch, state transfer, synchronization and readback cost more than the work saved. GPU compute is therefore optional and disabled by default until a tested kernel is both accurate and faster under realistic load.

8. Target platform and graphics backend matrix

Availability is a runtime device capability, not a promise made by the build name. Preserve other existing native backend behavior; do not expand the required target list to Windows/Vulkan or native Linux/D3D11 without a separate scope decision.

9. Runtime compilation, caching and cleanup

1. Machine load: resolve chipset/support-chip paths and validate active graphics/DSP definitions.
2. Compile generic IR: produce typed programs, explicit state descriptors, hazard metadata and deterministic CPU executor plans.
3. Probe backend: query graphics and compute capabilities, supported integer types, buffer limits and synchronization features.
4. Prepare optional GPU executors: translate eligible IR to backend shader code and compile pipelines once per active definition state—not per frame/sample.
5. Run: schedule PPU operations by raster state and DSP operations by emulated sample time, dispatching only proved-safe GPU work.
6. Session restore / machine change: discard old compiled machine-specific IR, shader bindings and buffers as needed; reconstruct from the active definitions.
7. Backend loss / unsupported feature: switch to CPU at a safe state boundary, keeping emulated time and state coherent.

Any runtime shader cache is session-local to the active machine/definitions; compiled machine micro-codes must not persist across machine loads or restores. Hashes may be logged for reproducibility without persisting compiled machine programs.

10. Timing, state ordering and determinism

Use an integer-exact CPU executor as the parity oracle. GPU code is acceptable only if it meets the chosen strict pixel/sample equivalence target and doesn't alter emulated register behavior. Performance cannot supersede fidelity.

11. Sequential implementation revisions

Each revision is a meaningful delivered milestone with its own new Developer Distribution, Bootstrap Archive, regression notes and logs. Upload completed revision artifacts to the ChatGPT Library without replacing prior revisions. Labels beyond r14 are provisional; assign the next number when a milestone is actually produced.

12. Test and acceptance matrix

For a failed game, capture two or more time-separated core dumps plus the console log and CPU/PPU/APU traces. Distinguish a rendering omission, forced blank, and CPU/APU polling stall; all three can produce a black picture for different reasons.

13. Instrumentation and performance evidence

Benchmark after correctness checks, always against the same machine state and host conditions. Record both emulated fidelity and host-side cost.

Report median and worst-case execution cost, frame pacing, A/V latency and power/CPU/GPU utilization where measured. Do not assume GPU acceleration wins just because a shader compiles; the S-DSP may be faster on a modern host CPU.

14. Risks, non-goals and rollback

• Incomplete hardware models: GPU acceleration doesn't supply missing HDMA, color math, S-SMP IPL, S-DSP or register timing behavior.
• Precision differences: shader floating point, signed shifts, overflow and rounding can differ from SNES hardware; specify integer semantics and parity tests.
• Synchronization hazards: CPU writes might race GPU reads; DSP echo introduces history dependencies; use explicit barriers and narrow offload.
• Performance inversions: tiny compute kernels may lose to dispatch overhead; always measure complete processing cost including transfers.
• Feature fragmentation: 32-bit hosts and older devices may lack compute or appropriate shader features; an equivalent CPU path is mandatory.
• Migration risk: maintain a selectable CPU reference path, preferably as the initial default, throughout implementation.

15. Pre-implementation review checklist

1. Confirm r13 is the intended base and inspect the current microcode.lib, PPU/DSP code, build scripts, graphics APIs, and actual definition grammars.
2. Approve the generic IR operation list and define fixed-point/integer semantics, state hazards and explicit target capabilities.
3. Define which existing SNES PPU behavior will first be expressed as data-driven programs, rather than blindly rewriting all graphics code.
4. Choose one constrained, benchmarkable DSP primitive for optional GPU Compute, while keeping S-SMP/ports on the CPU path.
5. Specify CPU-vs-GPU parity test vectors and the performance measurement procedure.
6. Implement the first small revision, preserve bootstrap/compiler equivalence, compile targets actually available, and publish test evidence.
7. Create and link a new sequential revision archive, upload it to Library, then proceed only after reviewing failures and known limitations.

Related documents: PHLEGM-Graphics-Backend-Micro-Codes.html and PHLEGM-APU-GPU-Compute-Micro-Codes.html. This document stands on its own; neither file is required for viewing.