What are the key TU_DEBUG environment variables in Mesa Turnip and how do they affect performance?

TU_DEBUG is a comma-separated environment variable used by the Mesa Turnip Vulkan driver to toggle low-level hardware features, rendering modes, and debugging behavior on Qualcomm Adreno GPUs.

While primarily intended for Mesa driver developers and GPU hang analysis, several TU_DEBUG flags directly alter how Turnip handles tiling, memory compression, and culling—leading to significant performance differences.

Key TU_DEBUG Flags & Performance Impacts

1. Tiling & Binning Controls

Qualcomm Adreno GPUs rely on Tile-Based Deferred Rendering (TBDR), rendering frames in small "bins" inside fast on-chip SRAM (GMEM) before writing to system RAM.

• TU_DEBUG=sysmem

  • What it does: Forces the driver to bypass on-chip GMEM and render everything directly to system RAM (Direct System Memory mode).

  • Performance Impact: Usually negative (10% to 40%+ drop). Bypassing GMEM forces heavy memory bandwidth consumption over system RAM. However, in rare scenarios with extremely light fill-rate demands or games with hundreds of small render passes, it can eliminate tile-setup overhead and fix visual rendering artifacts.

• TU_DEBUG=gmem

  • What it does: Forces GMEM tiled rendering for all render passes.

  • Performance Impact: Generally positive for fill-rate heavy games. Keeps render targets on fast on-chip memory, saving memory bandwidth and reducing thermal throttling.

• TU_DEBUG=nobin

  • What it does: Disables hardware binning (Visibility Stream Compiler).

  • Performance Impact: Negative. Without hardware binning, the GPU processes geometry across tiles inefficiently, increasing vertex processing overhead in complex 3D scenes.

• TU_DEBUG=forcebin

  • What it does: Forces hardware binning on every pass.

  • Performance Impact: Variable. Can boost FPS in geometry-heavy games where Turnip’s heuristic might otherwise fall back to unbinned rendering.

2. Bandwidth & Early Culling Optimizations

• TU_DEBUG=noubwc

  • What it does: Disables Universal Bandwidth Compression (UBWC).

  • Performance Impact: Severe drop. UBWC compresses textures and framebuffer attachments in hardware. Disabling it dramatically spikes memory bus utilization, causing heavy frame drops on bandwidth-constrained mobile SoCs. Used almost exclusively to diagnose memory corruption artifacts.

• TU_DEBUG=nolrz

  • What it does: Disables the Low-Resolution Z-buffer (LRZ).

  • Performance Impact: Heavy drop in complex 3D games. LRZ is Adreno’s hardware early-Z culling mechanism. Disabling it forces the GPU to execute pixel shaders for hidden/occluded surfaces, causing massive overdraw penalties.

• TU_DEBUG=nolrzfc

  • What it does: Disables LRZ Fast-Clear optimizations.

  • Performance Impact: Minor drop. Adds slight depth-buffer clearing overhead between frames.

3. Execution & Pipeline Synchronization (Hang Debugging)

• TU_DEBUG=syncdraw

  • What it does: Forces the CPU and GPU to synchronize (wait for idle) after every single draw call.

  • Performance Impact: Catastrophic (Single-digit FPS). Completely destroys CPU/GPU pipelining. Strictly used to pinpoint exact draw calls that trigger GPU crashes or kernel devcoredumps.

• TU_DEBUG=flushall

  • What it does: Flushes GPU caches (CCU/UCHE) aggressively after operations.

  • Performance Impact: Severe stuttering. Kills cache hit rates and causes frequent pipeline stalls.

4. Profiling & Feature Exposures

• TU_DEBUG=perfc

  • What it does: Exposes the VK_KHR_performance_query extension.

  • Performance Impact: None when idle. Allows performance monitoring tools (such as MangoHud, RenderDoc, or ATrace) to capture hardware performance counters.

Summary Matrix

Flag
Typical Purpose
Performance Impact

sysmem
Bypass tiled SRAM / fix visual glitches
Lower FPS (increased RAM bandwidth)

gmem
Force on-chip SRAM tiled rendering
Higher FPS (in fill-rate heavy scenes)

nobin
Disable visibility binning
Lower FPS in geometry-heavy scenes

forcebin
Force visibility binning
Potential small gain in complex scenes

noubwc
Disable memory compression
Severe loss (bandwidth bottleneck)

nolrz
Disable hardware early-Z culling
Heavy loss in 3D games (overdraw)

syncdraw
Isolate crashing draw calls
Unplayable (Slideshow / CPU-bound lock)

Runtime Testing via TU_DEBUG_FILE

Instead of restarting games repeatedly to benchmark different flags, Mesa Turnip supports dynamic runtime toggling:

1. Export the control file path before launching the game:

   Bash

   export TU_DEBUG_FILE=/tmp/turnip_debug.txt
   

2. While the game is running, echo your desired runtime flags into that file:

   Bash

   echo "sysmem" > /tmp/turnip_debug.txt
   

3. Turnip instantly toggles the supported flags (such as sysmem, gmem, nobin, nolrz, perf) on the next frame submit, allowing real-time A/B performance profiling.