implements PLN-0084 remove host debug overlay

This commit is contained in:
2026-05-25 14:23:18 +01:00
parent 295666b310
commit d79c11faa8
7 changed files with 33 additions and 536 deletions
@@ -18,7 +18,7 @@ It covers:
- profiling;
- event and fault visibility;
- certification input data;
- host-side debug overlay (HUD) isolation.
- host-side debug UI isolation.
## 2 Execution Modes
@@ -131,15 +131,15 @@ The host may:
- observe buffers separately
- identify excessive redraw
Host-owned overlay or inspection surfaces MUST observe the last published logical frame rather than force continuous redraw to probe for changes.
Host-owned inspection surfaces MUST observe the last published logical frame rather than force continuous redraw to probe for changes.
When overlay, debugger, or other host-only diagnostics become visually stable:
When debugger or other host-only diagnostics become stable:
- the host MUST preserve the last valid visible image;
- the host MUST NOT keep recomposing the surface by continuous polling alone;
- additional redraw is only justified by a newly published logical frame or a host-owned invalidation event such as overlay toggle, resize, expose, or explicit debugger-visible state transition.
- additional redraw is only justified by a newly published logical frame or a host-owned invalidation event such as resize, expose, or explicit debugger-visible state transition.
Paused or breakpointed execution does not grant permission to swap logical machine buffers just to sustain a host-only HUD.
Paused or breakpointed execution does not grant permission to swap logical machine buffers just to sustain host-only diagnostics.
## 6 Time Profiling (Cycles)
@@ -285,28 +285,32 @@ Each event has:
- cost
- consequence
## 11 Host-Side Debug Overlay (HUD) Isolation
## 11 Host-Side Debug UI Isolation
The visual Debug Overlay (HUD) for technical inspection is not part of the emulated machine pipeline.
The desktop host MUST NOT inject a debug overlay into Game or Shell output. Any
future visual debug UI is a separate product/domain concern and requires its own
decision before it can become part of host presentation.
### 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.
6. **Host (Desktop):** Responsible for collecting telemetry from the runtime and rendering the HUD as a native, transparent layer.
3. **Host diagnostics:** The Desktop Host may consume telemetry for logs,
debugger streams, and non-render diagnostics, but it does not compose debug
pixels into the presentation surface.
4. **Composition boundary:** Published Game and Shell output must be presented
without host-owned debug overlay injection.
### 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.
- **Zero Pipeline Interference:** Host diagnostics must not inject pixels into
the emulated framebuffer or the host presentation surface.
- **Zero Cycle Impact:** Diagnostic processing must occur outside the emulated
machine cycles.
### 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**:
To ensure zero-impact synchronization between the VM and host diagnostics, 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.
@@ -320,4 +324,4 @@ All machine diagnostics and profiling data:
- feed the host-owned certification report;
- are collected deterministically;
- do not require a guest-visible debug ABI;
- are consistent regardless of whether the Host HUD is active or not.
- are consistent regardless of whether host diagnostics are active or not.
@@ -51,7 +51,8 @@ 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)**
- technical inspection and debugger integrations that do not modify presented
Game or Shell pixels
The host provides realization of machine surfaces. It does not redefine cartridge semantics.
@@ -123,8 +124,8 @@ The graphics system:
The platform layer:
- consumes closed render submissions through a render-surface implementation
- **may overlay technical HUDs without modifying the logical framebuffer**
- may transport published RGBA8888 output into a host presentation surface where a host-only overlay layer is composed
- transports published RGBA8888 output into a host presentation surface without
injecting host-owned debug overlay pixels
The host presentation layer MUST treat RGBA8888 as the canonical logical
framebuffer format. RGB565 conversion is not part of the normal host
@@ -136,17 +137,19 @@ host-owned invalidation, not by perpetual redraw polling.
In particular:
- a stable published submission MAY remain visible across multiple host wakeups without recomposition;
- a host MAY redraw the same logical frame again when its own surface is invalidated by resize, expose, or host-only overlay/debug changes;
- a host MAY redraw the same logical frame again when its own surface is invalidated by resize, expose, or debugger-visible host changes;
- a host MUST NOT invent intermediate logical frames or require continuous redraw merely to discover whether a new logical frame exists.
## 9 Debug and Inspection Isolation
To preserve portability and certification purity, technical inspection tools (like the Debug Overlay) are moved to the Host layer.
To preserve portability and certification purity, technical inspection tools are host-owned and must not inject pixels into Game or Shell output.
- **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.
- **Contract Boundary:** Emulated graphics primitives such as `fill_rect` and
`draw_text` remain part of the machine contract; host diagnostics must not
depend on them for visual injection.
### 9.1 Atomic Telemetry Interface