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.

Share on Google Plus

About Giampaolo Rossi.

Fond of computer and video games. Stay informed of the latest news on games for Linux and Android. The future of gaming is in Linux. All you need to know about How to play Windows games on Linux.