Repository navigation
Wii U Homebrew Notes
Michele Primavera edited this page Nov 18, 2026
·
1 revision
Things about the Wii U's hardware, Cafe OS, wut and Aroma that Maelle ran into, most of them found the hard way. They're written for anyone making Wii U homebrew, emulators especially. Tested on a retail console under Aroma, with wut 1.9.x and devkitPPC.
Tested with a small test app before any JIT work:
-
OSGetCodegenVirtAddrRangegives 32 MB at 0x01800000.OSGetCodegenCore()is 1, andOSGetCodegenMode()is 0x80000000. -
OSCodegenCopyfails in this mode. Don't use it. -
What works:
OSSwitchSecCodeGenMode(CODEGEN_RW_), write the instructions directly,DCFlushRange,OSSwitchSecCodeGenMode(CODEGEN_R_X),ICInvalidateRange, then call. Rewriting the same address and calling it again works too. - Each mode switch costs about 1 µs, so batch compiles. The switch returns nonzero garbage rather than 1, so treat any nonzero value as success.
-
Only core 1 can run code from that area. Threads can't change cores once they're running, so the JIT's thread has to
be created on core 1 (
7d503bb). -
32 MB is close enough for relative branches to reach anywhere in the area, so generated code can call shared
routines with
b/bl.
-
lwarx/stwcx.need a cache workaround that Cafe OS's own atomics have andstd::atomic's read-modify-write operations don't (described by fail0verflow in 2013). Values shared between cores with exchange or compare-and-swap need an atomic built on Cafe OS's (0d12a01). -
Build with
-fno-allow-store-data-races.-Ofastturns on-fallow-store-data-races, which lets GCC add stores the source doesn't make. On a multi-core console these lose other threads' updates and caused rare permanent freezes. Every build variant needs the flag, andmakedoesn't notice when only flags change, so clean after changing them. -
There's no
fsqrt(Espresso is a Broadway descendant), and 64-bit multiplies take several instructions. The FPU is fine, but adoublesquare root is a software routine. -
GCC doesn't merge byte loads into one big-endian load the way it does on little-endian hosts. Emulators reading
little-endian guest memory should use
lwbrx/lhbrx/stwbrx/sthbrxexplicitly (8f32105). -
longis 32 bits. Files past 2 GB needfseeko/ftellowith 64-bit offsets (9b6c90a). -
Memory latency dominates. Copying a 1 KB line took about 7 µs from write-allocate misses, and copying a 786 KB frame
took 1.7 ms. Claiming cache blocks with
dcbzbefore overwriting them helps a lot: writing GPU vertices went from 3.3 to 1.3 ms a frame (4e1d73b). -
dcbtprefetching made things slower in every place tried. - Code size costs more than calls. The L1 instruction cache is 32 KB. Inlining memory accesses into generated code cut calls but grew the code and lost speed. Shrinking generated code was the strongest speedup found.
-
divwuis cheap compared to the alternatives. A multiply-and-correct replacement for a division was slower. - Instruction counts don't predict time for code that moves data. A sound mixer rework running 29% fewer instructions saved about nothing on its own. Measure on the console.
-
Reading memory the GPU wrote is slow. It has to be dropped from the CPU's cache first, and every read then
misses. Reading a 512x384 frame back took about 8 ms (
0a4dbc9). - Work on one core can slow the others through shared memory traffic. Moving a frame conversion off core 2 made the 2D threads on cores 0 and 2 finish sooner.
- Threads can't change cores while running. Create them with their affinity set.
-
Don't free a thread's stack right after joining it. The thread can still be exiting on its stack. Allocate the stack
and the
OSThreadtogether, and free them from a deallocator (OSSetThreadDeallocator) once the thread has fully exited (97dedf5). -
OSYieldThreadonly gives way to threads of equal or higher priority. A spinning thread starves anything lower on its core. A worker below priority 16 on core 2 never ran while other threads spun there. Lowering a worker's priority below a spinning thread hung the app. -
std::mutexis recursive in wut, since it's built onOSMutex. -
OSThread::coreTimeConsumedNsgives meaningless values (for example 159% of one core). -
wut 1.9.2 changed thread entry points to take a
void*instead of aconst char**. Cast your entry function forOSCreateThreadto build with both (a5e03c0). -
A thread exiting can hang behind a spinning thread on its core, and freeing memory from an alarm callback isn't safe
with the heap's lock. A profiler that samples another core should keep one thread there for good
(
a6df9d0). -
abort()freezes the console with a striped screen and no message. Route failed assertions toOSFatalinstead. -
Apps load at the link address + 0x0A000000. An ELF linked at 0x02000000 runs at 0x0C000000, so subtract
0x0A000000 from a crash or hang address before
addr2line. Addresses at 0x0103xxxx are system libraries.
-
Never do file I/O from core 0. When a thread on core 0 makes a file call (through
__wut_fsa_*), Aroma's ContentRedirection plugin's "IO Thread 0" can spin at top priority while the call waits, starving everything else on core 0 for good. The FTP plugin makes it worse by also spinning on core 2. Run file-using threads on core 2 and keep file calls from overlapping (66f7f3b). -
Every SD card read costs about 4-5 ms of fixed latency, even for 16 KB. Unbuffered stdio only cut it from 5.5 to
4.3 ms, so the cost is in the file system, not newlib. Read big chunks (1 MB reads loaded a 256 MB ROM in 13 s where
small ones took 28 s), cache, and write back in chunks
(
cf42a2d,58179a0). - Writes cost milliseconds each too. 900 sector writes in one frame stopped the app for many seconds.
- The Wii U's file system stops at 4 GB per file.
-
A mutex isn't fair. A loader that takes the lock back right after each block starves everything else waiting for it,
so count waiters and step aside (
9340bfb).
-
Handle system messages while the app runs, not only at exit, or the HOME button does nothing
(
ca9be97). -
Stop writing files once the system asks for the foreground. A logger that kept writing to the SD card while the
system took the foreground away hung the exit (
d1920ba). - Closing from the HOME menu suspends threads on cores 0 and 1, so anything that waits on them can't be torn down then.
-
Shut down what you started when exiting from your own menu: close sockets, end your threads, close audio, shut
down the controllers, and then graphics and the SD mount on the UI's core after the system has taken the
foreground. Otherwise the Wii U Menu can stop loading, or powering off can hang later
(
926a657,d373cf2).
-
Never draw 0 vertices.
GX2DrawExwith a count of 0 (including a zero-count indexed line draw) hangs the GPU until the system resets it about 1.16 s later. After that reset, exiting to the Wii U Menu hangs. If you see a fixed 1.1-1.2 s stall with ordinary content, it's a GPU hang and reset, not slow work (c3a3800). -
GX2DrawDonenever returns after a GPU hang. To find the draw that hangs, poll timestamps instead (3e68792). -
Copying or resolving surfaces changes GPU state your context keeps. After a surface copy, set your state again, as
you would after resolving a multisampled buffer. Leaving it caused random GPU hangs within minutes
(
1ad38a9). -
GX2Invalidatewith GPU modes writes GPU commands. If two threads use GX2, it must happen under the same lock as everything else, or the GPU hangs after a while. -
Don't wait for the GPU while holding a lock the other GX2 user needs. Flush, release the lock, then wait for your
timestamp (
71eec22).
-
FLOAT_D24_S8can't resolve tiny depths like 1/W ≈ 1e-5, which gave straight bands of polygons drawn behind others.FLOAT_X8_X24(32-bit float depth) fixed precision, but its stencil misbehaved. A 24-bit fixed-point depth buffer (UNORM_R24_X8) with values scaled to the frame's range worked (2a16dea). -
The GPU writes
FLOAT_R32render targets little-endian. The CPU has to byte-swap them. RGBA8 reads fine as 0xRRGGBBAA. -
GX2SetDepthStencilControl's stencil operations are ordered (pass, depth-fail, fail). It's easy to copy a call and mark on depth fail by mistake. -
Locking and unlocking a GX2R buffer invalidates the whole buffer. With three vertex buffers, each textured quad
flushed about 160 KB. Flush only the range you wrote (
568cdcf). - Flushing many vertices costs time on the CPU. About 800 KB a frame was most of the cost of sending draws.
-
Tiled render targets draw faster than linear ones, about 0.9 ms a frame in a heavy scene. Keep linear only what the
CPU reads (
922c4a8). -
GX2_PRIMITIVE_MODE_QUADSexists and takes 4 vertices a quad instead of 6 (d603504). -
The TV's and GamePad's scan buffers keep their pixels between frames. Only redraw what changed
(
ed047eb). - The UI loop is held at the display's rate by GX2's swap, so time saved shows up as waiting inside the swap, not as a faster loop.
-
A group can't read the same channel of different GPRs in one cycle (bank conflicts). latte-assembler doesn't check
this, and the bad code stalled the GPU about 0.7 s every frame (
f9bb07a). The packing rules are insrc/ui/console/shaders/README.md, after Mesa'sr600_asm.c: vector slot = destination channel, one GPR per channel per read cycle, at most 2 constant-file reservations, transcendental-slot ops andKILLalone. -
Pack ALU instructions into VLIW groups. One instruction per group runs up to 5 times slower. Packed, full-screen
passes became texture-fetch bound (
3c94aff). -
Literal words are stored per literal operand at the channel it names, not deduplicated. The GPU reads words up to
the highest channel used, so give every literal operand its own channel (at most 4 a group) or the clause falls out
of step. 0.0, 0.5 and 1.0 become inline constants. ALU
CNTcounts literal slots. -
latte-assembler sets
CB_SHADER_MASKto 0xF. For 2 render targets, patch it to 0xFF. - latte-assembler hangs on non-numeric ADDR/CNT placeholders instead of erroring. It does check numeric clause ADDR and CNT values and tells you the expected ones. TEX ADDR = 32 + CNT, rounded up to a multiple of 8.
- Program words are little-endian in GFD block type 7.
-
Sample with only the coordinates you mean. Once a texture coordinate attribute carried extra values in .zw,
SAMPLE R0, R0hung the GPU.R0.xy00works. - Running latte-assembler on a Mac:
docker run --rm --platform linux/amd64 -v $PWD:/s -w /s devkitpro/devkitppc ./latte-assembler compile X.gsh --vsh X.vsh --psh X.psh
-
If the GamePad is off when the app starts, WHB gives it no display buffer, and it stays black after it's turned on.
Set one up whenever the GamePad's display mode differs from the one the current buffer is for, and again after getting
the foreground back, since WHB sets up its own then (
a464d0e). -
With the TV set to 4:3 at 480i/480p,
WHBGfxInitgives the TV a 640x480 buffer. A layout worked out for 854x480 is squeezed to three quarters of its width (11a16d5). - A connected GamePad costs about 0.2-0.35 ms of CPU a frame for the system's streaming, in any screen arrangement.
-
Sample order is easy to swap on big-endian. If you pack stereo as
(right << 16) | leftin a 32-bit word and hand it to SDL as 16-bit pairs, right comes first in memory on the Wii U and plays on the left (1e11cb9). -
Output buffers of 512 samples let an emulator fall further behind before running dry than 1024 do
(
eea6f2f). -
AXRegisterDeviceFinalMixCallbacklets you capture what the mixer actually plays. Its struct, from decaf:int32_t **data; uint16_t channels, samples, devices, channelsOut, withdata[device * channels + channel]. The mixer runs in 3 ms frames at 48 kHz (454b271). - SDL 2.32.10's Wii U backend uses two 512-sample buffers and one AX voice per channel, moving loop offsets from a 3 ms frame callback.
Found while porting libslirp (44664d9). Each looked fine on a
desktop:
-
poll()returns -1 withEINVALstraight away for an empty fd array, and when any fd is above 31. A poll loop then spins. Poll sockets one at a time instead. -
fcntl()only supportsF_GETFLandF_SETFL. There's no close-on-exec (F_GETFD). -
UDP
recvfrom()fails withEMSGSIZE(122) unless the buffer is large, whatever the datagram's size. 8192 bytes works and 1512 doesn't. -
TCP_NODELAYgivesENOPROTOOPT(harmless).connect()returningEINPROGRESSis normal.
-
Pro and Classic Controllers come through KPAD, with Pro Controller support enabled
(
531cd62). -
VPADInitis deprecated and does nothing on current firmware (2d38b57). -
The GamePad camera opens with
CAMInitat 15 fps and gives NV12 frames (9746603). -
Headphones in the GamePad's jack show in
VPADStatus.usingHeadphones(a4b729d). -
The GamePad's IR port only speaks IrDA with its own framing (0xA5 header, session ID, CRC8, handshake; see wut's
libirc). A real DS searching for a partner in Pokémon Black/White, held at the GamePad for about 80 s at 115200 baud in both ANY and WAIT modes, gave no data. ANY mode reports "connected" at once with no partner. Polls with no data return 0 but leave the buffer unwritten. Other bit rates weren't tried, and the receiver wasn't checked against a known sender, so this doesn't rule IR out completely. It does mean the GamePad can't simply stand in for a DS's IR.