DEBUGGING.md
6918 bytes · Original / download
Debugging and profiling
Logs
VITA_LOG(...)(src/platform/vita/vita_platform.h) writes toux0:data/POKEVITA/debug.logthrough a 32 KB buffered stream. It compiles to nothing unless the build is configured with-DVITA_LOGGING=ON.- Do not log every frame: writes to the memory card can stall for hundreds of milliseconds.
printfis not used in production code.
UI stall log (ui_stall.c)
With a screen of the new UI open, ux0:data/POKEVITA/ui_stall.log gets a line (200 at most per
session) whenever Core 1 did not tick the UI for more than 100 ms, Core 0 did not render for more
than 100 ms, or Core 0 kept drawing the same list while Core 1 was publishing new ones. Each line
gives the screen and the ages of the other core, so it says which core held the frame.
It opens, writes and closes the file on the spot, from Core 0 when the render side logs: on a slow card that write can itself last hundreds of milliseconds and chain further stall lines. Read a run of consecutive Core 0 gaps with that in mind.
Per-frame telemetry (vita_perf.c/h)
Always compiled in. Timestamps cost ~40 ns (sceKernelGetProcessTimeWide); results are buffered
in RAM and written with 32 KB buffers.
| File | Content |
|---|---|
ux0:data/POKEVITA/perf_summary.txt |
Every 120 3D frames (or 5 s): render FPS against the real target, logic Hz, Core 0 / Core 1 load, frame-time p50/p95/p99 and frames over budget, HOLES, WORKER (chunks built on Core 2, dropped, frames that overlapped a job, Core 0 wait), PACING, events, average/min/max per stage, sub-timers, PER CHUNK and LIGHT PER CHUNK costs, atlas cost per upload, free memory, session totals. [MEMORY …] lines at boot and after each map warm-up |
ux0:data/POKEVITA/perf_frames.csv |
One row per Core 0 frame |
CSV columns:
| Group | Columns |
|---|---|
| Frame | frame, render3d, target_fps, frame_ms (wall time, start to after the swap), c0_active_ms (sum of the named stages), other_ms (frame_ms minus the named stages) |
| Atlas animation | atlas_ms, atlas_compose_ms, atlas_upload_ms, atlas_uploads |
| Chunks | cull_ms, build_ms (Core 0 builds only), build_ground_ms (ground, relief and their light rays; includes build_atlas_ext_ms), build_atlas_ext_ms, build_trees_ms, build_bldg_ms, build_upload_ms, light_rays, build_verts. The phase times and counts include the chunk committed from the worker that frame |
| Other stages | draw3d_ms, ui_scan_ms, ui_up_ms, swap_ms, entities_ms, digest_ms, shift_ms (all the map change work of the frame: HandleMapChange, chunk shift, building and lighting resets) |
| Core 1 | c1_logic_ms, c1_vblank_ms, c1_pacing_ms (time sleeping to hold 60 Hz; Core 1 never waits for Core 0) |
| Scene | chunks_vis, chunks_built, draw_calls, verts; holes: chunks in view left wrong this frame, without geometry (the background shows) or drawn with an atlas slot recomposed since their build |
| Lighting (chunk builds) | light_ray_ms (marching shadow rays), light_contact_ms (contact AO), light_steps (ray points), light_cells (cells classified: cache misses), light_blocks (block bounds worked out), light_api_ms (all time inside the lighting entry points, rays and AO included). The times are part of the build phases above |
| Pacing | logic_ticks: game frames since the previous Core 0 frame (1 per 3D frame at 60 FPS, 2 at 30; the summary's PACING line counts the others); world_ms: VoxelWorld_BuildInstances; atlas_slots_ms: the current map's atlas slot (compose, extend, activate) on map or tileset changes |
| Chunk worker | worker_built, worker_dropped (results dropped because the world changed), worker_compute_ms (the worker's time for the chunk committed this frame), worker_wait_ms (Core 0 blocked waiting for it, at the frame start or in mid-frame). build_ms and chunks_built count only the builds on Core 0 |
events |
Letters: M new map (chunk cache reset), X map crossing (chunks shifted), L live tile changed, S sun moved (visible chunks rebuild), W warm-up, F faded (synchronous builds), A atlas extended in a build, C an atlas slot recomposed for another tileset |
| New UI | ui2_render_ms (Core 0 Pass 7 draw and cell uploads), ui2_tick_ms (Core 1 Ui_Tick draw-list build), ui2_quads (quads in the list) |
| Marker | Where |
|---|---|
VitaPerf_BeginFrame / EndFrame |
sdl2.c presentation loop (EndFrame gets the target FPS) |
VitaPerf_MarkAtlasAnim*, MarkCull*, MarkBuild*, MarkDraw3D* |
VoxelRenderer_RenderFrame |
VitaPerf_SubBegin/SubEnd, AddCount, MarkEvent |
BuildChunk phases, atlas animation, map shift, entities, live digest, and New UI render/tick (VITA_PERF_T_UI2_RENDER, VITA_PERF_T_UI2_TICK) |
VitaPerf_MarkUiScanlines*, MarkUiUpload* |
Pass 6 (GBA overlay) |
VitaPerf_MarkSwap* |
around vglSwapBuffers |
VitaPerf_Core1* |
VBlankIntrWait (logic, VBlank and audio, pacing) |
Draw calls and vertices are counted by a glDrawArrays wrapper in voxel_renderer.c.
Reading it: the budget is 33.3 ms at 30 FPS and 16.7 ms at 60 FPS (target_fps). In 3D the
remaining spikes come from ui_scan_ms + ui_up_ms (a GBA window on screen), worker_wait_ms
(Core 0 waiting for a long chunk on Core 2), build_ms (a visible hole built on Core 0) and the
crossing frame (shift_ms, atlas_slots_ms, entities_ms); a large other_ms points at work
outside the named stages. Core 1 should show c1_logic_ms + c1_vblank_ms well under 16.7 ms;
if c1_pacing_ms drops to zero the game logic is the limit.
Copy the files to logs/<session>/ in the repository (git-ignored) to keep a history. Quick
aggregation by column name:
awk -F, 'NR==1 {for (i=1;i<=NF;i++) c[$i]=i; next}
$c["worker_built"]>0 {n++; w+=$c["worker_compute_ms"]}
$c["frame_ms"]>16.7 && $c["render3d"]==1 {slow++}
END {print "worker chunk:", w/n, "ms;", slow, "frames over 16.7 ms"}' logs/<session>/perf_frames.csv
Crash dumps
A crash leaves ux0:data/psp2core-*.psp2dmp (gzip'd ELF core). Decode it against the ELF of
the same build (build-vita/pokeemerald):
- With
vita-parse-core:vita-parse-core <dump> build-vita/pokeemerald. - By hand: take the crashed thread's PC/LR from
THREAD_REG_INFO, subtract the module base fromMODULE_INFO, thenarm-vita-eabi-addr2line -e build-vita/pokeemerald 0x81000000+offset.
Keep the ELF of every build you test on hardware; a dump from another build decodes to wrong lines.
Vita3K vs hardware
Vita3K runs the ARM code much faster than the console and hides GPU timing and texture races. Use it for boot, visuals and crashes; take performance numbers from the telemetry on a real Vita.
Checking the parallel renderer
Configure with -DVITA_DRAW_SELFCHECK=ON: every few frames the parallel renderer's output is
compared byte for byte with the sequential one.