< [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) >