prometeu-runtime/docs/runtime/specs/10-debug-inspection-and-profiling.md

Debug, Inspection, and Profiling

Domain: machine diagnostics Function: normative

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

1 Scope

This chapter defines the machine-visible debugging, inspection, and profiling surface of PROMETEU.

It covers:

• execution modes;
• pause and stepping;
• state inspection;
• graphics inspection;
• profiling;
• breakpoints and watchpoints;
• event and fault visibility;
• certification-facing diagnostics.

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
• access to internal state
• pauses and stepping

2.3 Certification Mode

• deterministic execution
• collected metrics
• report generation

No mode alters the logical result of the program.

3 Execution Debug

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 stepping at different levels:

• by frame
• by function
• by VM instruction

Stepping by instruction reveals:

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

4 State Inspection

4.1 Stacks

PROMETEU allows inspecting:

• Operand Stack
• Call Stack

For each frame:

• content
• depth
• growth and cleanup

4.2 Heap

The heap can be inspected in real time:

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

The programmer can observe:

• allocation patterns
• fragmentation
• GC pressure

4.3 Global Space

Global variables:

• current values
• references
• initialization

5 Graphics Debug

PROMETEU allows inspecting the graphics system:

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

It is possible to:

• 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

PROMETEU can associate cycles with:

• functions
• methods
• logical blocks

6.3 Per-Instruction Profiling

At the lowest level, the system 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 directly feed the certification.

8 Breakpoints and Watchpoints

8.1 Breakpoints

PROMETEU supports breakpoints in:

• specific frames
• functions
• VM instructions

Breakpoints:

• pause execution
• preserve state
• do not change behavior

8.2 Watchpoints

Watchpoints monitor:

• variables
• heap addresses
• specific values

Execution can pause when:

• a value changes
• a limit is exceeded

9 Event and Fault Debugging

PROMETEU allows observing:

• event queue
• active timers
• published system faults

Each event has:

• origin
• frame
• cost
• consequence

10 Integration with CAP and Certification

All debug and profiling data:

• feed the certification report
• are collected deterministically
• do not depend on external tools