4.8 KiB
🛠️ Debug, Inspection, and Profiling
1. Overview
PROMETEU was designed to be observed.
Debug, inspection, and profiling are not optional external tools —
they are integral parts of the machine.
Nothing happens without leaving traces.
Nothing consumes resources without being measured.
Nothing fails without explanation.
PROMETEU does not hide state. PROMETEU exposes behavior.
2. Debug Philosophy in PROMETEU
PROMETEU follows three fundamental debug principles:
-
State before abstraction
The programmer sees the machine before seeing “features”.
-
Time as first class
Every action is analyzed in the context of the frame and cycles.
-
Observation does not alter execution
Debug never changes the behavior of the system.
3. Execution Modes
PROMETEU operates in three main modes:
3.1 Normal Mode
- continuous execution
- no detailed inspection
- focus on game and experience
3.2 Debug Mode
- controlled execution
- access to internal state
- pauses and stepping
This mode is used for:
- learning
- investigation
- error correction
3.3 Certification Mode
- deterministic execution
- collected metrics
- report generation
No mode alters the logical result of the program.
4. Execution Debug
4.1 Pause and Resume
The system can be paused at safe points:
- frame start
- before UPDATE
- after DRAW
- before SYNC
During pause:
- state is frozen
- buffers are not swapped
- logical time does not advance
4.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
5. State Inspection
5.1 Stacks
PROMETEU allows inspecting:
- Operand Stack
- Call Stack
For each frame:
- content
- depth
- growth and cleanup
Stack overflow and underflow are immediately visible.
5.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
5.3 Global Space
Global variables:
- current values
- references
- initialization
Globals are visible as static RAM.
6. 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
7. Time Profiling (Cycles)
7.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
7.2 Per-Function Profiling
PROMETEU can associate cycles with:
- functions
- methods
- logical blocks
This allows answering:
“where is the time being spent?”
7.3 Per-Instruction Profiling
At the lowest level, the system can display:
- executed instructions
- individual cost
- frequency
This level is especially useful for:
- VM teaching
- deep optimization
- bytecode analysis
8. 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.
9. Breakpoints and Watchpoints
9.1 Breakpoints
PROMETEU supports breakpoints in:
- specific frames
- functions
- VM instructions
Breakpoints:
- pause execution
- preserve state
- do not change behavior
9.2 Watchpoints
Watchpoints monitor:
- variables
- heap addresses
- specific values
Execution can pause when:
- a value changes
- a limit is exceeded
10. Event and Interrupt Debugging
PROMETEU allows observing:
- event queue
- active timers
- occurred interrupts
Each event has:
- origin
- frame
- cost
- consequence
Nothing happens “silently”.
11. Integration with CAP and Certification
All debug and profiling data:
- feed the certification report
- are collected deterministically
- do not depend on external tools
The final report is:
- reproducible
- auditable
- explainable
12. Pedagogical Use
This system allows teaching:
- how to debug real systems
- how to read metrics
- how to correlate time and memory
- how to justify technical decisions
The student learns:
debug is not trial and error, it is informed observation.
13. Summary
- debug is part of the system
- inspection is complete
- profiling is deterministic
- time and memory are visible
- certification is evidence-based