Intrepid/prometeu-runtime
Intrepid/prometeu-runtime
3
0
Fork 0
Code Pull Requests Activity
prometeu-runtime/docs/specs/runtime/10-debug-inspection-and-profiling.md

7.5 KiB
Raw Blame History

Debug, Inspection, and Profiling

Domain: machine diagnostics Function: normative

Didactic companion: ../learn/mental-model-observability-and-debugging.md

1 Scope

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:

  • runtime-visible execution control used by host tooling;
  • bounded operational telemetry;
  • profiling;
  • event and fault visibility;
  • certification input data;
  • host-side debug overlay (HUD) isolation.

2 Execution Modes

PROMETEU operates in three main modes:

2.1 Normal Mode

  • continuous execution
  • no detailed inspection
  • focus on game and experience

2.2 Debug Mode

  • controlled execution
  • host-mediated access to internal state
  • pauses and stepping

2.3 Certification Mode

  • deterministic execution
  • collected metrics
  • host-generated report output

No mode alters the logical result of the program.

3 Execution Control

3.1 Pause and Resume

The system can be paused at safepoints:

  • frame start
  • before UPDATE
  • after DRAW
  • before SYNC

During pause:

  • state is frozen
  • buffers are not swapped
  • logical time does not advance

3.2 Step-by-Step

PROMETEU allows host tooling to step execution at different levels:

  • by frame
  • by function
  • by VM instruction

When the host activates instruction-level inspection, it may observe:

  • Program Counter (PC)
  • current instruction
  • operand stack
  • call stack

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

Host tooling may inspect:

  • Operand Stack
  • Call Stack

For each frame:

  • content
  • depth
  • growth and cleanup

4.2 Heap

The host may inspect heap state in real time:

  • total size
  • current usage
  • peak usage
  • live objects

The programmer can observe:

  • allocation patterns
  • fragmentation
  • GC pressure

4.3 Global Space

Host-owned inspection may observe global variables, including:

  • current values
  • references
  • initialization

5 Graphics Inspection Boundary

Host tooling may inspect the graphics system:

  • front buffer
  • back buffer
  • palette state
  • active sprites

The host may:

  • freeze the image
  • observe buffers separately
  • identify excessive redraw

6 Time Profiling (Cycles)

6.1 Per-Frame Measurement

For each frame, PROMETEU records:

  • total cycles used
  • cycles per subsystem
  • execution peaks

Conceptual example:

Frame 18231:
Total:9,842/10,000cycles
UPDATE:4,210
DRAW:3,180
AUDIO:920
SYSTEM:612

6.2 Per-Function Profiling

Host tooling may associate cycles with:

  • functions
  • methods
  • logical blocks

6.3 Per-Instruction Profiling

At the lowest level, host tooling can display:

  • executed instructions
  • individual cost
  • frequency

7 Memory Profiling

PROMETEU records:

  • average heap usage
  • heap peak
  • allocations per frame
  • GC frequency

Example:

Heap:
Avg:24KB
Peak:34KB❌
Limit:32KB

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 host-owned certification is:

  • bank_type
  • used_slots
  • total_slots

For the current runtime banks, the canonical bank names are:

  • GLYPH
  • SOUNDS

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

The platform supports host-owned breakpoints in:

  • specific frames
  • functions
  • VM instructions

Breakpoints:

  • pause execution
  • preserve state
  • do not change behavior

8.2 Watchpoints

Host tooling may monitor watchpoints over:

  • variables
  • heap addresses
  • specific values

Execution can pause when:

  • a value changes
  • a limit is exceeded

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:

  • max_glyph_slots_used
  • max_sound_slots_used

Bank certification MUST NOT depend on max_gfx_bytes or max_audio_bytes.

Host tooling may observe:

  • event queue
  • active timers
  • published system faults

Each event has:

  • origin
  • frame
  • cost
  • consequence

11 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. 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.

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.
  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.

12 Integration with CAP and Certification

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.