implements PLN-0084 remove host debug overlay
This commit is contained in:
@@ -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
|
||||
|
||||
|
||||
Reference in New Issue
Block a user