[PERF] Host Debug Overlay Isolation
This commit is contained in:
@@ -238,6 +238,10 @@ The visual Debug Overlay (HUD) for technical inspection is not part of the emula
|
||||
### 10.1 Responsibilities
|
||||
|
||||
1. **Runtime:** Only exposes telemetry data via the machine diagnostics surface. It does not perform HUD rendering or string formatting.
|
||||
2. **Emulated graphics contract:** Machine graphics primitives such as `fill_rect` and `draw_text` remain valid parts of the emulated graphics/syscall contract. They are not host overlay APIs.
|
||||
3. **Host overlay module:** The Desktop Host owns a dedicated overlay module that performs host-side text, panel, and simple bar composition.
|
||||
4. **Composition boundary:** The overlay is composed on the Host presentation surface after the emulated frame is ready. Overlay pixels must not be written back into the emulated framebuffer.
|
||||
5. **Host control:** Overlay visibility and presentation policy remain under Host control.
|
||||
2. **Host (Desktop):** Responsible for collecting telemetry from the runtime and rendering the HUD as a native, transparent layer.
|
||||
|
||||
### 10.2 Principles
|
||||
@@ -253,6 +257,7 @@ To ensure zero-impact synchronization between the VM and the Host Debug Overlay,
|
||||
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.
|
||||
4. **Frame-Closed Log Metric:** `logs_count` in the snapshot represents the number of logs emitted in the last completed logical frame, not a transient in-flight counter.
|
||||
|
||||
## 11 Integration with CAP and Certification
|
||||
|
||||
|
||||
@@ -125,6 +125,7 @@ The platform layer:
|
||||
- only displays the framebuffer
|
||||
- does not reinterpret graphics commands
|
||||
- **may overlay technical HUDs without modifying the logical framebuffer**
|
||||
- may transport the logical framebuffer into a host presentation surface where a host-only overlay layer is composed
|
||||
|
||||
## 9 Debug and Inspection Isolation
|
||||
|
||||
@@ -133,6 +134,7 @@ To preserve portability and certification purity, technical inspection tools (li
|
||||
- **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.
|
||||
- **Contract Boundary:** Emulated graphics primitives such as `fill_rect` and `draw_text` remain part of the machine contract, but Host overlays must not depend on them.
|
||||
|
||||
### 9.1 Atomic Telemetry Interface
|
||||
|
||||
|
||||
Reference in New Issue
Block a user