350 lines
4.8 KiB
Markdown
350 lines
4.8 KiB
Markdown
< [Back](chapter-9.md) | [Summary](table-of-contents.md) | [Next](chapter-11.md) >
|
|
|
|
# 🛠️ **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:
|
|
|
|
1. **State before abstraction**
|
|
|
|
The programmer sees the machine before seeing “features”.
|
|
|
|
2. **Time as first class**
|
|
|
|
Every action is analyzed in the context of the frame and cycles.
|
|
|
|
3. **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
|
|
|
|
< [Back](chapter-9.md) | [Summary](table-of-contents.md) | [Next](chapter-11.md) > |