240 lines
3.5 KiB
Markdown
240 lines
3.5 KiB
Markdown
# Debug, Inspection, and Profiling
|
|
|
|
Domain: machine diagnostics
|
|
Function: normative
|
|
|
|
Didactic companion: [`../learn/mental-model-observability-and-debugging.md`](../learn/mental-model-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
|