[PERF] Host Debug Overlay Isolation

This commit is contained in:
2026-04-10 10:55:15 +01:00
parent f5580ae0ce
commit 47ab664280
21 changed files with 526 additions and 154 deletions
@@ -18,7 +18,8 @@ It covers:
- profiling;
- breakpoints and watchpoints;
- event and fault visibility;
- certification-facing diagnostics.
- certification-facing diagnostics;
- Host-side debug overlay (HUD) isolation.
## 2 Execution Modes
@@ -230,10 +231,34 @@ Each event has:
- cost
- consequence
## 10 Integration with CAP and Certification
## 10 Host-Side Debug Overlay (HUD) Isolation
The visual Debug Overlay (HUD) for technical inspection is not part of the emulated machine pipeline.
### 10.1 Responsibilities
1. **Runtime:** Only exposes telemetry data via the machine diagnostics surface. It does not perform HUD rendering or string formatting.
2. **Host (Desktop):** Responsible for collecting telemetry from the runtime and rendering the HUD as a native, transparent layer.
### 10.2 Principles
- **Zero Pipeline Interference:** HUD rendering must not inject pixels into the emulated framebuffer. It is applied after upscaling or as a separate display surface.
- **Zero Cycle Impact:** HUD-related processing (like formatting technical text) must occur outside the emulated machine cycles.
- **Toggle Control:** The activation of the overlay (typically via **F1**) is managed by the Host layer.
### 10.3 Atomic Telemetry Model
To ensure zero-impact synchronization between the VM and the Host Debug Overlay, PROMETEU uses a **push-based atomic model**:
1. **Atomic Storage:** Metrics such as cycles, syscalls, and memory usage are stored in a dedicated `AtomicTelemetry` structure using thread-safe atomic types (`AtomicU64`, `AtomicU32`, etc.).
2. **Lockless Access:** The Host (Desktop) reads these metrics asynchronously and without locks by taking a `snapshot()` of the atomic state.
3. **Single Source of Truth:** This model is the exclusive source of truth for both real-time inspection and frame-end certification, replacing legacy per-frame buffered fields.
## 11 Integration with CAP and Certification
All debug and profiling data:
- feed the certification report
- are collected deterministically
- do not depend on external tools
- are consistent regardless of whether the Host HUD is active or not.
@@ -51,6 +51,7 @@ The contract is about logical behavior, not identical physical latency or throug
- audio output
- physical input collection
- access to the sandbox file system
- **technical inspection surfaces (Debug Overlay/HUD)**
The host provides realization of machine surfaces. It does not redefine cartridge semantics.
@@ -123,8 +124,25 @@ The platform layer:
- only displays the framebuffer
- does not reinterpret graphics commands
- **may overlay technical HUDs without modifying the logical framebuffer**
## 9 File System and Persistence
## 9 Debug and Inspection Isolation
To preserve portability and certification purity, technical inspection tools (like the Debug Overlay) are moved to the Host layer.
- **Host-exclusive:** These tools are only implemented where they are relevant (e.g., Desktop) and do not exist in the logical machine.
- **Non-intrusive:** They must not consume machine cycles or alter memory state.
- **Consistent Results:** A cartridge will produce the same logical results and certification metrics regardless of the Host's inspection capabilities.
### 9.1 Atomic Telemetry Interface
Inspection is facilitated by a lockless, push-based atomic interface:
1. **Host-Independent:** The VM updates atomic counters in every frame.
2. **Asynchronous Observation:** The Host layer reads snapshots of these counters at its own display frequency.
3. **Loop Purity:** This ensures that the VM execution loop remains deterministic and free from synchronization overhead (locks) that could vary across host architectures.
## 10 File System and Persistence
PROMETEU defines a **sandbox logical filesystem**:
@@ -140,7 +158,7 @@ The platform maps this filesystem to:
Without changing semantics.
## 10 Certification and Portability
## 11 Certification and Portability
The **PROMETEU Certification** is valid for all platforms.
@@ -154,7 +172,7 @@ It:
- will pass on all
- will produce the same reports
## 11 What PROMETEU Does Not Guarantee
## 12 What PROMETEU Does Not Guarantee
PROMETEU **does not promise**: