GitHub Vita Lite - Wolff's Store
Code / README | Releases | Issues
WolffsRoom/pokeemerald-vita-3ds / docs

THREADS.md

7604 bytes · Original / download

Threads and shared data

The Vita gives an application three user cores (Cortex-A9). The port uses all three. Most regressions in this project have been races between Core 0 and Core 1, so read this before touching anything that crosses threads.

Threads

Thread Core Created in Work
MainThread 0 sdl2.c (main) Input, presentation (vitaGL, voxel renderer, 2D overlay, the new UI's draw list), vglSwapBuffers. The GXM display-queue driver thread also stays on Core 0: moving it caused a GPU crash
AgbMain 1 sdl2.c (main → DoMain) The original game loop, the m4a/CGB sound mixer, VBlank work, 60 Hz pacing
DrawWorker1, DrawWorker2 2 gba_fast_draw.c (StartWorkers) Draw even/odd scanlines of a GBA frame and convert them to RGB565 with NEON
VoxelIoWorker 2 voxel_renderer.c (VoxelRenderer_Init) Reads building texture pages from the VPK with its own buffered file handle
VoxelChunkWorker 2 (low priority) voxel_renderer.c (ChunkWorker_Start) Computes one chunk at a time (ComputeChunkJob), launched after each swap; see "The chunk worker" below

Pacing

Who owns what

Data Writer Reader Protection
Game state: gMain, tasks, gObjectEvents, gSprites, save blocks Core 1 Core 0 (renderer) Renderer reads entities only through the snapshot below. The new UI reads game state on Core 1 (Ui_Tick) and hands Core 0 only a draw list
Entity snapshot VoxelEntitySnapshot sSnapshots[2] (voxel_entities.c, include/platform/voxel_snapshot.h) Core 1, VoxelEntities_PublishSnapshot() in VBlank Core 0, VoxelEntities_GetVisibleSnapshot() Double buffer; index swap between release fences, acquire fence on read
Map layout during a map change Core 1 (CB2_LoadMap, DoMapLoadLoop, connection transitions) Core 0 (voxel_world.c) volatile uint32_t sMapMutationLock (overworld.c:102): set by the loader, cleared when the next snapshot is published. Core 0 keeps drawing the previous instances meanwhile
Emulated VRAM, OAM, palettes, registers Core 1 Draw workers (2D), Core 0 (overlay pass) 2D: Core 1 is blocked while the frame is captured line by line. Overlay pass: read only; layers it hides are masked in each line's captured copy (gFastDrawDispcntClear, gFastDrawBldcntClear), never in the live registers
2D overlay backdrop colour Core 0 Draw code gFastDrawBackdropOverride instead of PLTT[0], so Core 1 palette writes cannot leak into the chroma key
Audio queue Core 1 SDL audio thread SDL queue
Building pages VoxelIoWorker Core 0 sBuildingIoMutex, held only to swap requests, never across fread
New UI draw list UiDrawList (src/platform/ui/ui_draw.c) Core 1, Ui_Tick Core 0, Ui_Render Triple buffer, index exchanged with __atomic_exchange_n
New UI run-time sprites (ui_sprites.c): cell cache and staging ring Core 1 decodes into the ring (head) Core 0 writes the cells into the UI texture (tail) Single-producer / single-consumer ring with release / acquire counters; the head is published before the list that uses it. A cell is reused only after 16 ticks without being drawn
Voxel world state a chunk build reads or writes: map instances, lighting caches, building caches, mesh builder window, sScratch, sChunkStaging, atlas maps Core 0, and VoxelChunkWorker while a job runs Core 0, Core 1 (entity snapshot reads instances, relief, decks) A window, not a lock: see "The chunk worker"

Rules

  1. Core 0 never writes game state. Input reaches the game through the emulated key register.
  2. Anything the renderer needs from gObjectEvents / gSprites goes into the snapshot, computed on Core 1 (the player's world position is already there).
  3. Code that changes the map layout sets sMapMutationLock first.
  4. Don't pin or re-prioritise SDK threads (GXM, audio).
  5. A new worker thread gets its own file handles and buffers; no shared FILE *.
  6. New Core 0 code that touches the voxel world outside the safe points of VoxelRenderer_RenderFrame calls EnsureWorkerIdle() (or ChunkWorker_Join()) first.

The chunk worker

VoxelChunkWorker computes one chunk at a time (ComputeChunkJob); see VOXEL_ENGINE.md for the three build phases.

Known risks (to fix)