discussion framework migration
This commit is contained in:
@@ -0,0 +1,239 @@
|
||||
# Debug, Inspection, and Profiling
|
||||
|
||||
Domain: machine diagnostics
|
||||
Function: normative
|
||||
|
||||
Didactic companion: [`../learn/mental-model-observability-and-debugging.md`](../runtime/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
|
||||
Reference in New Issue
Block a user