[PERF] Host Debug Overlay Isolation
This commit is contained in:
+39
@@ -0,0 +1,39 @@
|
||||
---
|
||||
id: LSN-0027
|
||||
ticket: perf-host-debug-overlay-isolation
|
||||
title: Host Debug Overlay Isolation
|
||||
created: 2026-04-10
|
||||
tags: [performance, host, gfx, telemetry]
|
||||
---
|
||||
|
||||
# Host Debug Overlay Isolation
|
||||
|
||||
The PROMETEU debug overlay (HUD) was decoupled from the emulated machine pipeline and moved to the Host layer to ensure measurement purity and architectural separation.
|
||||
|
||||
## The Original Problem
|
||||
|
||||
The debug overlay used to be rendered by injecting pixels directly into the emulated GFX pipeline during the logical frame execution. This caused several issues:
|
||||
- **Performance Distortion:** Cycle measurements for certification included the overhead of formatting technical strings and performing extra draw calls.
|
||||
- **Leaky Abstraction:** The emulated machine became aware of Host-only inspection needs.
|
||||
- **GFX Coupling:** The HUD was "burned" into the emulated framebuffer, making it impossible to capture raw game frames without the overlay while technical debugging was active.
|
||||
|
||||
## The Solution: Host-Side Rendering with Atomic Telemetry
|
||||
|
||||
The implemented solution follows a strictly non-intrusive approach:
|
||||
|
||||
1. **Atomic Telemetry (Push-based):** A new `AtomicTelemetry` structure was added to the HAL. It uses `AtomicU64`, `AtomicU32`, and `AtomicUsize` to track metrics (Cycles, Memory, Logs) in real-time.
|
||||
2. **Runtime Decoupling:** The `VirtualMachineRuntime` updates these atomic counters during its `tick` loop only if `inspection_active` is enabled. It does not perform any rendering or string formatting.
|
||||
3. **Host-Side HUD:** The `HostRunner` (in `prometeu-host-desktop-winit`) now takes a `snapshot()` of the atomic telemetry and renders the HUD as a native layer after the emulated machine has finished its work for the tick.
|
||||
|
||||
## Impact and Benefits
|
||||
|
||||
- **Zero Machine Overhead:** Rendering the HUD consumes Host CPU/GPU cycles but does not affect the emulated machine's cycle counter or logical behavior.
|
||||
- **Fidelity:** The emulated framebuffer remains pure, containing only game pixels.
|
||||
- **Responsive Telemetry:** By using atomics, the Host can read the most recent metrics at any time without waiting for frame boundaries or acquiring heavy read-locks on the runtime state.
|
||||
- **Platform Agnosticism:** Non-desktop hosts (which do not need the overlay) do not pay any implementation cost or performance penalty for the HUD's existence.
|
||||
|
||||
## Lessons Learned
|
||||
|
||||
- **Decouple Data from View:** Even for internal debugging tools, keeping the data collection (Runtime) separate from the visualization (Host) is crucial for accurate profiling.
|
||||
- **Atomic Snapshots are Sufficient:** For high-frequency HUD updates, eventual consistency via relaxed atomic loads is more than enough and significantly more performant than synchronizing via Mutexes or logical frame boundaries.
|
||||
- **Late Composition:** Composition of technical layers should always happen at the latest possible stage of the display pipeline to avoid polluting the core simulation state.
|
||||
+23
@@ -0,0 +1,23 @@
|
||||
# LSN-0028: Converging to a Single Atomic Telemetry Source
|
||||
|
||||
## Context
|
||||
Initial implementation of the Host Debug Overlay (DEC-0007) maintained legacy fields (`telemetry_current`, `telemetry_last`) alongside the new `AtomicTelemetry` for safety and backward compatibility. This resulted in redundant code and synchronization complexity in the core VM loop.
|
||||
|
||||
## Problem
|
||||
Maintaining two sources of truth for telemetry (frame-based and atomic-based) is a form of technical debt. It requires updating both systems, increases memory footprint in the `VirtualMachineRuntime`, and creates ambiguity about which data is more "accurate" or "current."
|
||||
|
||||
## Lesson
|
||||
1. **Atomics are sufficient:** A well-designed atomic structure with a `snapshot()` method can fulfill all needs, from real-time high-frequency inspection to deterministic frame-end certification.
|
||||
2. **Push-based over Pull-based:** By having the VM "push" updates to atomic counters, the Host can consume them at its own pace without ever locking the execution thread.
|
||||
3. **Purity through snapshots:** For processes that require a stable view of a frame (like Certification), capturing an atomic snapshot at the exact logical end of the frame is as precise as maintaining a separate buffered structure.
|
||||
|
||||
## Impact
|
||||
- **Simpler Code:** Removal of legacy fields reduced the complexity of `tick.rs` and `lifecycle.rs`.
|
||||
- **Better Performance:** Avoids redundant data copies and struct initializations per frame.
|
||||
- **Architectural Clarity:** All diagnostic tools (HUD, Debugger, CLI, Certifier) now converge on the same data source.
|
||||
|
||||
## References
|
||||
- DSC-0023 ([PERF] Full Migration to Atomic Telemetry)
|
||||
- DEC-0008 (Full Migration Decision)
|
||||
- PLN-0007 (Migration Plan)
|
||||
- DEC-0007 (Overlay Isolation)
|
||||
Reference in New Issue
Block a user