Parallel Execution UI + Real Logs + Path/Profiling Summary

Summary

Running UI in parallel with multiple ROMs (Mario, Pokémon, Tetris, Zelda) to capture real render path logs, stage profiling and nonwhite metrics. Creation of automated scripts for parallel execution with timeout, extraction of log samples and freeze detection. Objective: obtain objective evidence of which path is used (cpp_rgb_view vs legacy), which stage consumes the most time, and where pixels are lost (nonwhite before/after blit). Results: all ROMs use correct path (cpp_rgb_view), Mario does NOT freeze but has massive pixel loss (11520→1), Pokémon has white framebuffer from core (not UI problem), profiling shows TOTAL ~420ms (possible crash in pygame.event.pump or sleep).

Hardware Concept

Parallel UI Execution: To save time in testing, multiple instances of the UI are run in parallel, each with a different ROM. Each instance has a timeout (15 seconds) to prevent it from hanging indefinitely. Logs are captured separately for each ROM, allowing independent analysis.

Log Analysis: Logs contain three types of critical information:

• [UI-PATH]: Indicates which render path is used (cpp_rgb_view vs legacy_fallback), framebuffer metrics (len, shape, nonwhite, hash), frame time and estimated FPS.
• [UI-PROFILING]: Measures time per presenter stage (frombuffer/reshape, blit_array, scale/blit, flip) and TOTAL time of the entire frame.
• [UI-DEBUG]: Check nonwhite before and after blit to detect pixel loss during presentation.

Freeze Detection: If a ROM freezes, the log will have very few lines (<50 líneas). Si una ROM funciona correctamente, generará miles o millones de líneas (dependiendo del timeout y FPS).

Profiling Analysis: TOTAL frame time should be ~16.67ms for 60 FPS. If TOTAL is much larger (e.g. 420ms), there is a block or wait somewhere (possibly pygame.event.pump(), sleep(), or synchronization with the core). The individual stages (frombuffer, blit_array, scale, flip) must be<5ms cada una en condiciones normales.

Implementation

Phase A: Parallel Execution Script

Archive: tools/run_ui_parallel_0447.sh

Functionality:

• Run multiple ROMs in parallel using&(background jobs)
• Each instance has a timeout of 15 seconds usingtimeout 15s
• Usestdbuf -oL -eLfor line-buffering (real-time capture)
• Logs are saved in/tmp/viboy_0447/{rom}.log
• Wait for all instances to finish withwait

#!/bin/bash
# Run UI in parallel with multiple ROMs to capture logs (Step 0447)

LOG_DIR="/tmp/viboy_0447"
mkdir -p "$LOG_DIR"

ROMS=(
    "mario.gbc" # Critical: before freeze + 0.1 FPS
    "pkmn.gb" # Critical: previous blank
    "tetris.gb" # Baseline DMG
    "tetris_dx.gbc" # Baseline GBC
    "zelda-dx.gbc" # Baseline GBC
)

run_ui() {
    local rom="$1"
    local out="$LOG_DIR/${rom}.log"
    timeout 15s stdbuf -oL -eL python3 main.py "roms/${rom}" 2>&1 | tee "$out" &
}

for rom in "${ROMS[@]}"; do
    if [ -f "roms/${rom}" ]; then
        run_ui "$rom"
        sleep 0.5
    fi
donated

wait

Phase B: Log Extraction Script

Archive: tools/extract_ui_logs_0447.sh

Functionality:

• Extract log samples per ROM (first 8 lines of each type)
• Seeks[UI-PATH], [UI-PROFILING], [UI-DEBUG]
• Count total lines to detect freezes
• Generate summary in/tmp/viboy_0447/summary.txt

Phase C: Freeze Detection Script and Summary Table

Archive: tools/detect_freezes_0447.sh

Functionality:

• Extract key metrics from each log (path, FPS, nonwhite, most expensive stage)
• Detects possible freezes (ROMs with<50 líneas)
• Generate summary table in markdown format

echo "ROM | Lines | Path | FPS | NonWhite (before/after) | Most expensive stage"
for f in "$LOG_DIR"/*.log; do
    # Extract metrics...
    # Detect freeze if line_count< 50
done

Affected Files

• tools/run_ui_parallel_0447.sh- Script to run UI in parallel with timeout
• tools/extract_ui_logs_0447.sh- Script to extract log samples from ROM
• tools/detect_freezes_0447.sh- Script to detect freezes and generate summary table

Note: No core code was modified. Only analysis scripts were created.

Tests and Verification

Execution: Scripts executed successfully. Captured logs for 5 ROMs.

Results by ROM:

Key Findings:

• Mario does NOT freeze: 6.5M log lines indicate that the UI is working, but there is massive pixel loss (11520→1). TOTAL profiling is ~420ms, suggesting blocking on pygame.event.pump() or sleep().
• Pokémon has white framebuffer from core: NonWhite=0 indicates that the problem is in the PPU/core, not the UI.
• All ROMs use correct path: cpp_rgb_view (not legacy_fallback).
• Pixel loss on GBC: Mario and Zelda lose almost all the pixels in the blit (11520→1 or 0), suggesting a problem in surface format or blit.

Example of Log [UI-PATH]:

[UI-PATH] Frame 4 | Path=cpp_rgb_view | Len=69120 | Shape=rgb_view | NonWhite=11520 | Hash=5d6c318f | Time=0.75ms | FPS=1327.7

Example of Log [UI-PROFILING]:

[UI-PROFILING] Frame 241 | frombuffer/reshape: 0.01ms | blit_array: 0.06ms | scale/blit: 0.01ms | flip: 5.80ms | TOTAL: 421.43ms

Log example [UI-DEBUG]:

[UI-DEBUG] Nonwhite before blit: 11520 (estimated)
[UI-DEBUG] Nonwhite after blit (sample): 1/3

Sources consulted

• Bash documentation:timeout, stdbuf, background jobs
• Pygame documentation: Profiling and rendering optimization

Educational Integrity

Next Steps

• [ ] Step 0448: Investigate why TOTAL is ~420ms (possible crash in pygame.event.pump() or sleep())
• [ ] Step 0448: Pixel loss fix in blit (Mario and Zelda lose 11520→1 or 0)
• [ ] Step 0448: Investigate why Pokémon has a white framebuffer from the core (PPU problem, not UI)
• [ ] Optimize profiling to also measure pygame.event.pump() and sleep()
• [ ] Check surface format and blit_array to avoid pixel loss