[PERF] Runtime Introspection Syscalls

This commit is contained in:
2026-04-19 08:37:21 +01:00
parent e895b01b8f
commit aaf4dff69d
11 changed files with 361 additions and 71 deletions
@@ -7,19 +7,18 @@ Didactic companion: [`../learn/mental-model-observability-and-debugging.md`](../
## 1 Scope
This chapter defines the machine-visible debugging, inspection, and profiling surface of PROMETEU.
This chapter defines the machine-visible diagnostics and profiling surface of PROMETEU after `DEC-0009`.
`DEC-0009` locks debug tooling and certification output as host-owned concerns. The runtime machine contract therefore exposes only bounded operational diagnostics and deterministic telemetry production, not a general-purpose guest-visible debug surface.
It covers:
- execution modes;
- pause and stepping;
- state inspection;
- graphics inspection;
- runtime-visible execution control used by host tooling;
- bounded operational telemetry;
- profiling;
- breakpoints and watchpoints;
- event and fault visibility;
- certification-facing diagnostics;
- Host-side debug overlay (HUD) isolation.
- certification input data;
- host-side debug overlay (HUD) isolation.
## 2 Execution Modes
@@ -34,18 +33,18 @@ PROMETEU operates in three main modes:
### 2.2 Debug Mode
- controlled execution
- access to internal state
- host-mediated access to internal state
- pauses and stepping
### 2.3 Certification Mode
- deterministic execution
- collected metrics
- report generation
- host-generated report output
No mode alters the logical result of the program.
## 3 Execution Debug
## 3 Execution Control
### 3.1 Pause and Resume
@@ -64,24 +63,26 @@ During pause:
### 3.2 Step-by-Step
PROMETEU allows stepping at different levels:
PROMETEU allows host tooling to step execution at different levels:
- **by frame**
- **by function**
- **by VM instruction**
Stepping by instruction reveals:
When the host activates instruction-level inspection, it may observe:
- Program Counter (PC)
- current instruction
- operand stack
- call stack
## 4 State Inspection
## 4 State Inspection Boundary
Detailed state inspection is a host-owned concern. The runtime may expose deterministic machine state to host tooling, but this chapter does not define a general guest ABI for introspection convenience.
### 4.1 Stacks
PROMETEU allows inspecting:
Host tooling may inspect:
- **Operand Stack**
- **Call Stack**
@@ -94,7 +95,7 @@ For each frame:
### 4.2 Heap
The heap can be inspected in real time:
The host may inspect heap state in real time:
- total size
- current usage
@@ -109,22 +110,22 @@ The programmer can observe:
### 4.3 Global Space
Global variables:
Host-owned inspection may observe global variables, including:
- current values
- references
- initialization
## 5 Graphics Debug
## 5 Graphics Inspection Boundary
PROMETEU allows inspecting the graphics system:
Host tooling may inspect the graphics system:
- front buffer
- back buffer
- palette state
- active sprites
It is possible to:
The host may:
- freeze the image
- observe buffers separately
@@ -153,7 +154,7 @@ SYSTEM:612
### 6.2 Per-Function Profiling
PROMETEU can associate cycles with:
Host tooling may associate cycles with:
- functions
- methods
@@ -161,7 +162,7 @@ PROMETEU can associate cycles with:
### 6.3 Per-Instruction Profiling
At the lowest level, the system can display:
At the lowest level, host tooling can display:
- executed instructions
- individual cost
@@ -185,13 +186,13 @@ Peak:34KB❌
Limit:32KB
```
These data directly feed the certification.
These data feed host-owned certification.
### 7.1 Bank Occupancy Profiling
Bank occupancy diagnostics are slot-first.
The visible per-bank telemetry used by host inspection surfaces and certification is:
The visible per-bank telemetry used by host inspection surfaces and host-owned certification is:
- `bank_type`
- `used_slots`
@@ -206,9 +207,11 @@ Byte-oriented bank occupancy is not the canonical visible profiling contract.
## 8 Breakpoints and Watchpoints
Breakpoints and watchpoints are host-mediated tooling controls. They are not part of the gameplay-facing cartridge contract.
### 8.1 Breakpoints
PROMETEU supports breakpoints in:
The platform supports host-owned breakpoints in:
- specific frames
- functions
@@ -222,7 +225,7 @@ Breakpoints:
### 8.2 Watchpoints
Watchpoints monitor:
Host tooling may monitor watchpoints over:
- variables
- heap addresses
@@ -233,10 +236,14 @@ Execution can pause when:
- a value changes
- a limit is exceeded
## 9 Event and Fault Debugging
## 9 Event and Fault Diagnostics
## 10 Certification Diagnostics
Certification diagnostics are produced by the host from deterministic runtime telemetry.
The runtime does not generate the final certification artifact. It only maintains the machine-facing counters and summaries required for host-owned certification.
Certification diagnostics may enforce bank occupancy ceilings.
For bank residency, certification uses slot-based limits, such as:
@@ -246,7 +253,7 @@ For bank residency, certification uses slot-based limits, such as:
Bank certification MUST NOT depend on `max_gfx_bytes` or `max_audio_bytes`.
PROMETEU allows observing:
Host tooling may observe:
- event queue
- active timers
@@ -259,7 +266,7 @@ Each event has:
- cost
- consequence
## 10 Host-Side Debug Overlay (HUD) Isolation
## 11 Host-Side Debug Overlay (HUD) Isolation
The visual Debug Overlay (HUD) for technical inspection is not part of the emulated machine pipeline.
@@ -270,7 +277,7 @@ The visual Debug Overlay (HUD) for technical inspection is not part of the emula
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.
6. **Host (Desktop):** Responsible for collecting telemetry from the runtime and rendering the HUD as a native, transparent layer.
### 10.2 Principles
@@ -287,11 +294,11 @@ To ensure zero-impact synchronization between the VM and the Host Debug Overlay,
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
## 12 Integration with CAP and Certification
All debug and profiling data:
All machine diagnostics and profiling data:
- feed the certification report
- are collected deterministically
- do not depend on external tools
- 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.