1Environment Variables
2=====================
3
4Normally, no environment variables need to be set. Most of the
5environment variables used by Mesa/Gallium are for debugging purposes,
6but they can sometimes be useful for debugging end-user issues.
7
8LibGL environment variables
9---------------------------
10
11:envvar:`LIBGL_DEBUG`
12   If defined debug information will be printed to stderr. If set to
13   ``verbose`` additional information will be printed.
14:envvar:`LIBGL_DRIVERS_PATH`
15   colon-separated list of paths to search for DRI drivers
16:envvar:`LIBGL_ALWAYS_INDIRECT`
17   if set to ``true``, forces an indirect rendering context/connection.
18:envvar:`LIBGL_ALWAYS_SOFTWARE`
19   if set to ``true``, always use software rendering
20:envvar:`LIBGL_NO_DRAWARRAYS`
21   if set to ``true``, do not use DrawArrays GLX protocol (for
22   debugging)
23:envvar:`LIBGL_SHOW_FPS`
24   print framerate to stdout based on the number of ``glXSwapBuffers``
25   calls per second.
26:envvar:`LIBGL_DRI2_DISABLE`
27   disable DRI2 if set to ``true``.
28:envvar:`LIBGL_DRI3_DISABLE`
29   disable DRI3 if set to ``true``.
30
31Core Mesa environment variables
32-------------------------------
33
34:envvar:`MESA_NO_ASM`
35   if set, disables all assembly language optimizations
36:envvar:`MESA_NO_MMX`
37   if set, disables Intel MMX optimizations
38:envvar:`MESA_NO_3DNOW`
39   if set, disables AMD 3DNow! optimizations
40:envvar:`MESA_NO_SSE`
41   if set, disables Intel SSE optimizations
42:envvar:`MESA_NO_ERROR`
43   if set to 1, error checking is disabled as per ``KHR_no_error``. This
44   will result in undefined behavior for invalid use of the API, but
45   can reduce CPU use for apps that are known to be error free.
46:envvar:`MESA_DEBUG`
47   if set, error messages are printed to stderr. For example, if the
48   application generates a ``GL_INVALID_ENUM`` error, a corresponding
49   error message indicating where the error occurred, and possibly why,
50   will be printed to stderr. For release builds, :envvar:`MESA_DEBUG`
51   defaults to off (no debug output). :envvar:`MESA_DEBUG` accepts the
52   following comma-separated list of named flags, which adds extra
53   behavior to just set :envvar:`MESA_DEBUG` to ``1``:
54
55   ``silent``
56      turn off debug messages. Only useful for debug builds.
57   ``flush``
58      flush after each drawing command
59   ``incomplete_tex``
60      extra debug messages when a texture is incomplete
61   ``incomplete_fbo``
62      extra debug messages when a FBO is incomplete
63   ``context``
64      create a debug context (see ``GLX_CONTEXT_DEBUG_BIT_ARB``) and
65      print error and performance messages to stderr (or
66      ``MESA_LOG_FILE``).
67
68:envvar:`MESA_LOG_FILE`
69   specifies a file name for logging all errors, warnings, etc., rather
70   than stderr
71:envvar:`MESA_TEX_PROG`
72   if set, implement conventional texture environment modes with fragment
73   programs (intended for developers only)
74:envvar:`MESA_TNL_PROG`
75   if set, implement conventional vertex transformation operations with
76   vertex programs (intended for developers only). Setting this variable
77   automatically sets the :envvar:`MESA_TEX_PROG` variable as well.
78:envvar:`MESA_EXTENSION_OVERRIDE`
79   can be used to enable/disable extensions. A value such as
80   ``GL_EXT_foo -GL_EXT_bar`` will enable the ``GL_EXT_foo`` extension
81   and disable the ``GL_EXT_bar`` extension.
82:envvar:`MESA_EXTENSION_MAX_YEAR`
83   The ``GL_EXTENSIONS`` string returned by Mesa is sorted by extension
84   year. If this variable is set to year X, only extensions defined on
85   or before year X will be reported. This is to work-around a bug in
86   some games where the extension string is copied into a fixed-size
87   buffer without truncating. If the extension string is too long, the
88   buffer overrun can cause the game to crash. This is a work-around for
89   that.
90:envvar:`MESA_GL_VERSION_OVERRIDE`
91   changes the value returned by ``glGetString(GL_VERSION)`` and
92   possibly the GL API type.
93
94   -  The format should be ``MAJOR.MINOR[FC|COMPAT]``
95   -  ``FC`` is an optional suffix that indicates a forward compatible
96      context. This is only valid for versions >= 3.0.
97   -  ``COMPAT`` is an optional suffix that indicates a compatibility
98      context or ``GL_ARB_compatibility`` support. This is only valid
99      for versions >= 3.1.
100   -  GL versions <= 3.0 are set to a compatibility (non-Core) profile
101   -  GL versions = 3.1, depending on the driver, it may or may not have
102      the ``ARB_compatibility`` extension enabled.
103   -  GL versions >= 3.2 are set to a Core profile
104   -  Examples:
105
106      ``2.1``
107         select a compatibility (non-Core) profile with GL version 2.1.
108      ``3.0``
109         select a compatibility (non-Core) profile with GL version 3.0.
110      ``3.0FC``
111         select a Core+Forward Compatible profile with GL version 3.0.
112      ``3.1``
113         select GL version 3.1 with ``GL_ARB_compatibility`` enabled per
114         the driver default.
115      ``3.1FC``
116         select GL version 3.1 with forward compatibility and
117         ``GL_ARB_compatibility`` disabled.
118      ``3.1COMPAT``
119         select GL version 3.1 with ``GL_ARB_compatibility`` enabled.
120      ``X.Y``
121         override GL version to X.Y without changing the profile.
122      ``X.YFC``
123         select a Core+Forward Compatible profile with GL version X.Y.
124      ``X.YCOMPAT``
125         select a Compatibility profile with GL version X.Y.
126
127   -  Mesa may not really implement all the features of the given
128      version. (for developers only)
129
130:envvar:`MESA_GLES_VERSION_OVERRIDE`
131   changes the value returned by ``glGetString(GL_VERSION)`` for OpenGL
132   ES.
133
134   -  The format should be ``MAJOR.MINOR``
135   -  Examples: ``2.0``, ``3.0``, ``3.1``
136   -  Mesa may not really implement all the features of the given
137      version. (for developers only)
138
139:envvar:`MESA_GLSL_VERSION_OVERRIDE`
140   changes the value returned by
141   ``glGetString(GL_SHADING_LANGUAGE_VERSION)``. Valid values are
142   integers, such as ``130``. Mesa will not really implement all the
143   features of the given language version if it's higher than what's
144   normally reported. (for developers only)
145:envvar:`MESA_GLSL_CACHE_DISABLE`
146   if set to ``true``, disables the GLSL shader cache. If set to
147   ``false``, enables the GLSL shader cache when it is disabled by
148   default.
149:envvar:`MESA_GLSL_CACHE_MAX_SIZE`
150   if set, determines the maximum size of the on-disk cache of compiled
151   GLSL programs. Should be set to a number optionally followed by
152   ``K``, ``M``, or ``G`` to specify a size in kilobytes, megabytes, or
153   gigabytes. By default, gigabytes will be assumed. And if unset, a
154   maximum size of 1GB will be used.
155
156   .. note::
157
158      A separate cache might be created for each architecture that Mesa is
159      installed for on your system. For example under the default settings
160      you may end up with a 1GB cache for x86_64 and another 1GB cache for
161      i386.
162
163:envvar:`MESA_GLSL_CACHE_DIR`
164   if set, determines the directory to be used for the on-disk cache of
165   compiled GLSL programs. If this variable is not set, then the cache
166   will be stored in ``$XDG_CACHE_HOME/mesa_shader_cache`` (if that
167   variable is set), or else within ``.cache/mesa_shader_cache`` within
168   the user's home directory.
169:envvar:`MESA_GLSL`
170   :ref:`shading language compiler options <envvars>`
171:envvar:`MESA_NO_MINMAX_CACHE`
172   when set, the minmax index cache is globally disabled.
173:envvar:`MESA_SHADER_CAPTURE_PATH`
174   see :ref:`Capturing Shaders <capture>`
175:envvar:`MESA_SHADER_DUMP_PATH` and :envvar:`MESA_SHADER_READ_PATH`
176   see :ref:`Experimenting with Shader
177   Replacements <replacement>`
178:envvar:`MESA_VK_VERSION_OVERRIDE`
179   changes the Vulkan physical device version as returned in
180   ``VkPhysicalDeviceProperties::apiVersion``.
181
182   -  The format should be ``MAJOR.MINOR[.PATCH]``
183   -  This will not let you force a version higher than the driver's
184      instance version as advertised by ``vkEnumerateInstanceVersion``
185   -  This can be very useful for debugging but some features may not be
186      implemented correctly. (For developers only)
187:envvar:`MESA_VK_WSI_PRESENT_MODE`
188   overrides the WSI present mode clients specify in
189   ``VkSwapchainCreateInfoKHR::presentMode``. Values can be ``fifo``,
190   ``relaxed``, ``mailbox`` or ``immediate``.
191:envvar:`MESA_LOADER_DRIVER_OVERRIDE`
192   chooses a different driver binary such as ``etnaviv`` or ``zink``.
193
194NIR passes environment variables
195--------------------------------
196
197The following are only applicable for drivers that uses NIR, as they
198modify the behavior for the common ``NIR_PASS`` and ``NIR_PASS_V`` macros,
199that wrap calls to NIR lowering/optimizations.
200
201:envvar:`NIR_PRINT`
202   If defined, the resulting NIR shader will be printed out at each
203   successful NIR lowering/optimization call.
204:envvar:`NIR_TEST_CLONE`
205   If defined, cloning a NIR shader would be tested at each successful
206   NIR lowering/optimization call.
207:envvar:`NIR_TEST_SERIALIZE`
208   If defined, serialize and deserialize a NIR shader would be tested at
209   each successful NIR lowering/optimization call.
210
211Mesa Xlib driver environment variables
212--------------------------------------
213
214The following are only applicable to the Mesa Xlib software driver. See
215the :doc:`Xlib software driver page <xlibdriver>` for details.
216
217:envvar:`MESA_RGB_VISUAL`
218   specifies the X visual and depth for RGB mode
219:envvar:`MESA_BACK_BUFFER`
220   specifies how to implement the back color buffer, either ``pixmap``
221   or ``ximage``
222:envvar:`MESA_GAMMA`
223   gamma correction coefficients for red, green, blue channels
224:envvar:`MESA_XSYNC`
225   enable synchronous X behavior (for debugging only)
226:envvar:`MESA_GLX_FORCE_CI`
227   if set, force GLX to treat 8 BPP visuals as CI visuals
228:envvar:`MESA_GLX_FORCE_ALPHA`
229   if set, forces RGB windows to have an alpha channel.
230:envvar:`MESA_GLX_DEPTH_BITS`
231   specifies default number of bits for depth buffer.
232:envvar:`MESA_GLX_ALPHA_BITS`
233   specifies default number of bits for alpha channel.
234
235Intel driver environment variables
236----------------------------------------------------
237
238:envvar:`INTEL_BLACKHOLE_DEFAULT`
239   if set to 1, true or yes, then the OpenGL implementation will
240   default ``GL_BLACKHOLE_RENDER_INTEL`` to true, thus disabling any
241   rendering.
242:envvar:`INTEL_DEBUG`
243   a comma-separated list of named flags, which do various things:
244
245   ``ann``
246      annotate IR in assembly dumps
247   ``aub``
248      dump batches into an AUB trace for use with simulation tools
249   ``bat``
250      emit batch information
251   ``blit``
252      emit messages about blit operations
253   ``blorp``
254      emit messages about the blorp operations (blits & clears)
255   ``buf``
256      emit messages about buffer objects
257   ``clip``
258      emit messages about the clip unit (for old gens, includes the CLIP
259      program)
260   ``color``
261      use color in output
262   ``cs``
263      dump shader assembly for compute shaders
264   ``do32``
265      generate compute shader SIMD32 programs even if workgroup size
266      doesn't exceed the SIMD16 limit
267   ``dri``
268      emit messages about the DRI interface
269   ``fbo``
270      emit messages about framebuffers
271   ``fs``
272      dump shader assembly for fragment shaders
273   ``gs``
274      dump shader assembly for geometry shaders
275   ``hex``
276      print instruction hex dump with the disassembly
277   ``l3``
278      emit messages about the new L3 state during transitions
279   ``miptree``
280      emit messages about miptrees
281   ``no8``
282      don't generate SIMD8 fragment shader
283   ``no16``
284      suppress generation of 16-wide fragment shaders. useful for
285      debugging broken shaders
286   ``nocompact``
287      disable instruction compaction
288   ``nodualobj``
289      suppress generation of dual-object geometry shader code
290   ``nofc``
291      disable fast clears
292   ``norbc``
293      disable single sampled render buffer compression
294   ``optimizer``
295      dump shader assembly to files at each optimization pass and
296      iteration that make progress
297   ``perf``
298      emit messages about performance issues
299   ``perfmon``
300      emit messages about ``AMD_performance_monitor``
301   ``pix``
302      emit messages about pixel operations
303   ``prim``
304      emit messages about drawing primitives
305   ``reemit``
306      mark all state dirty on each draw call
307   ``sf``
308      emit messages about the strips & fans unit (for old gens, includes
309      the SF program)
310   ``shader_time``
311      record how much GPU time is spent in each shader
312   ``spill_fs``
313      force spilling of all registers in the scalar backend (useful to
314      debug spilling code)
315   ``spill_vec4``
316      force spilling of all registers in the vec4 backend (useful to
317      debug spilling code)
318   ``state``
319      emit messages about state flag tracking
320   ``submit``
321      emit batchbuffer usage statistics
322   ``sync``
323      after sending each batch, emit a message and wait for that batch
324      to finish rendering
325   ``tcs``
326      dump shader assembly for tessellation control shaders
327   ``tes``
328      dump shader assembly for tessellation evaluation shaders
329   ``tex``
330      emit messages about textures.
331   ``urb``
332      emit messages about URB setup
333   ``vert``
334      emit messages about vertex assembly
335   ``vs``
336      dump shader assembly for vertex shaders
337
338:envvar:`INTEL_MEASURE`
339   Collects GPU timestamps over common intervals, and generates a CSV report
340   to show how long rendering took.  The overhead of collection is limited to
341   the flushing that is required at the interval boundaries for accurate
342   timestamps. By default, timing data is sent to ``stderr``.  To direct output
343   to a file:
344
345   ``INTEL_MEASURE=file=/tmp/measure.csv {workload}``
346
347   To begin capturing timestamps at a particular frame:
348
349   ``INTEL_MEASURE=file=/tmp/measure.csv,start=15 {workload}``
350
351   To capture only 23 frames:
352
353   ``INTEL_MEASURE=count=23 {workload}``
354
355   To capture frames 15-37, stopping before frame 38:
356
357   ``INTEL_MEASURE=start=15,count=23 {workload}``
358
359   Designate an asynchronous control file with:
360
361   ``INTEL_MEASURE=control=path/to/control.fifo {workload}``
362
363   As the workload runs, enable capture for 5 frames with:
364
365   ``$ echo 5 > path/to/control.fifo``
366
367   Enable unbounded capture:
368
369   ``$ echo -1 > path/to/control.fifo``
370
371   and disable with:
372
373   ``$ echo 0 > path/to/control.fifo``
374
375   Select the boundaries of each snapshot with:
376
377   ``INTEL_MEASURE=draw``
378      Collects timings for every render (DEFAULT)
379
380   ``INTEL_MEASURE=rt``
381      Collects timings when the render target changes
382
383   ``INTEL_MEASURE=batch``
384      Collects timings when batches are submitted
385
386   ``INTEL_MEASURE=frame``
387      Collects timings at frame boundaries
388
389   With ``INTEL_MEASURE=interval=5``, the duration of 5 events will be
390   combined into a single record in the output.  When possible, a single
391   start and end event will be submitted to the GPU to minimize
392   stalling.  Combined events will not span batches, except in
393   the case of ``INTEL_MEASURE=frame``.
394:envvar:`INTEL_NO_HW`
395   if set to 1, true or yes, prevents batches from being submitted to the
396   hardware. This is useful for debugging hangs, etc.
397:envvar:`INTEL_PRECISE_TRIG`
398   if set to 1, true or yes, then the driver prefers accuracy over
399   performance in trig functions.
400:envvar:`INTEL_SHADER_ASM_READ_PATH`
401   if set, determines the directory to be used for overriding shader
402   assembly. The binaries with custom assembly should be placed in
403   this folder and have a name formatted as ``sha1_of_assembly.bin``.
404   The sha1 of a shader assembly is printed when assembly is dumped via
405   corresponding :envvar:`INTEL_DEBUG` flag (e.g. ``vs`` for vertex shader).
406   A binary could be generated from a dumped assembly by ``i965_asm``.
407   For :envvar:`INTEL_SHADER_ASM_READ_PATH` to work it is necessary to enable
408   dumping of corresponding shader stages via :envvar:`INTEL_DEBUG`.
409   It is advised to use ``nocompact`` flag of :envvar:`INTEL_DEBUG` when
410   dumping and overriding shader assemblies.
411   The success of assembly override would be signified by "Successfully
412   overrode shader with sha1 <sha1>" in stderr replacing the original
413   assembly.
414
415
416Radeon driver environment variables (radeon, r200, and r300g)
417-------------------------------------------------------------
418
419:envvar:`RADEON_NO_TCL`
420   if set, disable hardware-accelerated Transform/Clip/Lighting.
421
422DRI environment variables
423-------------------------
424
425:envvar:`DRI_NO_MSAA`
426   disable MSAA for GLX/EGL MSAA visuals
427
428
429EGL environment variables
430-------------------------
431
432Mesa EGL supports different sets of environment variables. See the
433:doc:`Mesa EGL <egl>` page for the details.
434
435Gallium environment variables
436-----------------------------
437
438:envvar:`GALLIUM_HUD`
439   draws various information on the screen, like framerate, CPU load,
440   driver statistics, performance counters, etc. Set
441   :envvar:`GALLIUM_HUD` to ``help`` and run e.g. ``glxgears`` for more info.
442:envvar:`GALLIUM_HUD_PERIOD`
443   sets the HUD update rate in seconds (float). Use zero to update every
444   frame. The default period is 1/2 second.
445:envvar:`GALLIUM_HUD_VISIBLE`
446   control default visibility, defaults to true.
447:envvar:`GALLIUM_HUD_TOGGLE_SIGNAL`
448   toggle visibility via user specified signal. Especially useful to
449   toggle HUD at specific points of application and disable for
450   unencumbered viewing the rest of the time. For example, set
451   :envvar:`GALLIUM_HUD_VISIBLE` to ``false`` and
452   :envvar:`GALLIUM_HUD_TOGGLE_SIGNAL` to ``10`` (``SIGUSR1``). Use
453   ``kill -10 <pid>`` to toggle the HUD as desired.
454:envvar:`GALLIUM_HUD_SCALE`
455   Scale HUD by an integer factor, for high DPI displays. Default is 1.
456:envvar:`GALLIUM_HUD_DUMP_DIR`
457   specifies a directory for writing the displayed HUD values into
458   files.
459:envvar:`GALLIUM_DRIVER`
460   useful in combination with :envvar:`LIBGL_ALWAYS_SOFTWARE`=`true` for
461   choosing one of the software renderers ``softpipe``, ``llvmpipe`` or
462   ``swr``.
463:envvar:`GALLIUM_LOG_FILE`
464   specifies a file for logging all errors, warnings, etc. rather than
465   stderr.
466:envvar:`GALLIUM_PIPE_SEARCH_DIR`
467   specifies an alternate search directory for pipe-loader which overrides
468   the compile-time path based on the install location.
469:envvar:`GALLIUM_PRINT_OPTIONS`
470   if non-zero, print all the Gallium environment variables which are
471   used, and their current values.
472:envvar:`GALLIUM_DUMP_CPU`
473   if non-zero, print information about the CPU on start-up
474:envvar:`TGSI_PRINT_SANITY`
475   if set, do extra sanity checking on TGSI shaders and print any errors
476   to stderr.
477:envvar:`DRAW_FSE`
478   Enable fetch-shade-emit middle-end even though its not correct (e.g.
479   for softpipe)
480:envvar:`DRAW_NO_FSE`
481   Disable fetch-shade-emit middle-end even when it is correct
482:envvar:`DRAW_USE_LLVM`
483   if set to zero, the draw module will not use LLVM to execute shaders,
484   vertex fetch, etc.
485:envvar:`ST_DEBUG`
486   controls debug output from the Mesa/Gallium state tracker. Setting to
487   ``tgsi``, for example, will print all the TGSI shaders. See
488   :file:`src/mesa/state_tracker/st_debug.c` for other options.
489
490Clover environment variables
491----------------------------
492
493:envvar:`CLOVER_EXTRA_BUILD_OPTIONS`
494   allows specifying additional compiler and linker options. Specified
495   options are appended after the options set by the OpenCL program in
496   ``clBuildProgram``.
497:envvar:`CLOVER_EXTRA_COMPILE_OPTIONS`
498   allows specifying additional compiler options. Specified options are
499   appended after the options set by the OpenCL program in
500   ``clCompileProgram``.
501:envvar:`CLOVER_EXTRA_LINK_OPTIONS`
502   allows specifying additional linker options. Specified options are
503   appended after the options set by the OpenCL program in
504   ``clLinkProgram``.
505
506Softpipe driver environment variables
507-------------------------------------
508
509:envvar:`SOFTPIPE_DEBUG`
510   a comma-separated list of named flags, which do various things:
511
512   ``vs``
513      Dump vertex shader assembly to stderr
514   ``fs``
515      Dump fragment shader assembly to stderr
516   ``gs``
517      Dump geometry shader assembly to stderr
518   ``cs``
519      Dump compute shader assembly to stderr
520   ``no_rast``
521      rasterization is disabled. For profiling purposes.
522   ``use_llvm``
523      the softpipe driver will try to use LLVM JIT for vertex
524      shading processing.
525   ``use_tgsi``
526      if set, the softpipe driver will ask to directly consume TGSI, instead
527      of NIR.
528
529LLVMpipe driver environment variables
530-------------------------------------
531
532:envvar:`LP_NO_RAST`
533   if set LLVMpipe will no-op rasterization
534:envvar:`LP_DEBUG`
535   a comma-separated list of debug options is accepted. See the source
536   code for details.
537:envvar:`LP_PERF`
538   a comma-separated list of options to selectively no-op various parts
539   of the driver. See the source code for details.
540:envvar:`LP_NUM_THREADS`
541   an integer indicating how many threads to use for rendering. Zero
542   turns off threading completely. The default value is the number of
543   CPU cores present.
544
545VMware SVGA driver environment variables
546----------------------------------------
547
548:envvar`SVGA_FORCE_SWTNL`
549   force use of software vertex transformation
550:envvar`SVGA_NO_SWTNL`
551   don't allow software vertex transformation fallbacks (will often
552   result in incorrect rendering).
553:envvar`SVGA_DEBUG`
554   for dumping shaders, constant buffers, etc. See the code for details.
555:envvar`SVGA_EXTRA_LOGGING`
556   if set, enables extra logging to the ``vmware.log`` file, such as the
557   OpenGL program's name and command line arguments.
558:envvar`SVGA_NO_LOGGING`
559   if set, disables logging to the ``vmware.log`` file. This is useful
560   when using Valgrind because it otherwise crashes when initializing
561   the host log feature.
562
563See the driver code for other, lesser-used variables.
564
565WGL environment variables
566-------------------------
567
568:envvar:`WGL_SWAP_INTERVAL`
569   to set a swap interval, equivalent to calling
570   ``wglSwapIntervalEXT()`` in an application. If this environment
571   variable is set, application calls to ``wglSwapIntervalEXT()`` will
572   have no effect.
573
574VA-API environment variables
575----------------------------
576
577:envvar:`VAAPI_MPEG4_ENABLED`
578   enable MPEG4 for VA-API, disabled by default.
579
580VC4 driver environment variables
581--------------------------------
582
583:envvar:`VC4_DEBUG`
584   a comma-separated list of named flags, which do various things:
585
586   ``cl``
587      dump command list during creation
588   ``qpu``
589      dump generated QPU instructions
590   ``qir``
591      dump QPU IR during program compile
592   ``nir``
593      dump NIR during program compile
594   ``tgsi``
595      dump TGSI during program compile
596   ``shaderdb``
597      dump program compile information for shader-db analysis
598   ``perf``
599      print during performance-related events
600   ``norast``
601      skip actual hardware execution of commands
602   ``always_flush``
603      flush after each draw call
604   ``always_sync``
605      wait for finish after each flush
606   ``dump``
607      write a GPU command stream trace file (VC4 simulator only)
608
609RADV driver environment variables
610---------------------------------
611
612:envvar:`RADV_DEBUG`
613   a comma-separated list of named flags, which do various things:
614
615   ``llvm``
616      enable LLVM compiler backend
617   ``allbos``
618      force all allocated buffers to be referenced in submissions
619   ``checkir``
620      validate the LLVM IR before LLVM compiles the shader
621   ``forcecompress``
622      Enables DCC,FMASK,CMASK,HTILE in situations where the driver supports it
623      but normally does not deem it beneficial.
624   ``hang``
625      enable GPU hangs detection and dump a report to
626      $HOME/radv_dumps_<pid>_<time> if a GPU hang is detected
627   ``img``
628      Print image info
629   ``info``
630      show GPU-related information
631   ``invariantgeom``
632      Mark geometry-affecting outputs as invariant. This works around a common
633      class of application bugs appearing as flickering.
634   ``metashaders``
635      dump internal meta shaders
636   ``noatocdithering``
637      disable dithering for alpha to coverage
638   ``nobinning``
639      disable primitive binning
640   ``nocache``
641      disable shaders cache
642   ``nocompute``
643      disable compute queue
644   ``nodcc``
645      disable Delta Color Compression (DCC) on images
646   ``nodisplaydcc``
647      disable Delta Color Compression (DCC) on displayable images
648   ``nodynamicbounds``
649      do not check OOB access for dynamic descriptors
650   ``nofastclears``
651      disable fast color/depthstencil clears
652   ``nohiz``
653      disable HIZ for depthstencil images
654   ``noibs``
655      disable directly recording command buffers in GPU-visible memory
656   ``nomemorycache``
657      disable memory shaders cache
658   ``nongg``
659      disable NGG for GFX10+
660   ``nonggc``
661      disable NGG culling on GPUs where it's enabled by default (GFX10.3+ only).
662   ``nooutoforder``
663      disable out-of-order rasterization
664   ``notccompatcmask``
665      disable TC-compat CMASK for MSAA surfaces
666   ``noumr``
667      disable UMR dumps during GPU hang detection (only with
668      :envvar:`RADV_DEBUG`=``hang``)
669   ``novrsflatshading``
670      disable VRS for flat shading (only on GFX10.3+)
671   ``preoptir``
672      dump LLVM IR before any optimizations
673   ``prologs``
674      dump vertex shader prologs
675   ``shaders``
676      dump shaders
677   ``shaderstats``
678      dump shader statistics
679   ``spirv``
680      dump SPIR-V
681   ``startup``
682      display info at startup
683   ``syncshaders``
684      synchronize shaders after all draws/dispatches
685   ``vmfaults``
686      check for VM memory faults via dmesg
687   ``zerovram``
688      initialize all memory allocated in VRAM as zero
689
690:envvar:`RADV_FORCE_FAMILY`
691   create a null device to compile shaders without a AMD GPU (e.g. vega10)
692
693:envvar:`RADV_FORCE_VRS`
694   allow to force per-pipeline vertex VRS rates on GFX10.3+. This is only
695   forced for pipelines that don't explicitely use VRS or flat shading.
696   The supported values are 2x2, 1x2 and 2x1. Only for testing purposes.
697
698:envvar:`RADV_PERFTEST`
699   a comma-separated list of named flags, which do various things:
700
701   ``bolist``
702      enable the global BO list
703   ``cswave32``
704      enable wave32 for compute shaders (GFX10+)
705   ``dccmsaa``
706      enable DCC for MSAA images
707   ``force_emulate_rt``
708      forces ray-tracing to be emulated in software,
709      even if there is hardware support.
710   ``gewave32``
711      enable wave32 for vertex/tess/geometry shaders (GFX10+)
712   ``localbos``
713      enable local BOs
714   ``nosam``
715      disable optimizations that get enabled when all VRAM is CPU visible.
716   ``pswave32``
717      enable wave32 for pixel shaders (GFX10+)
718   ``nggc``
719      enable NGG culling on GPUs where it's not enabled by default (GFX10.1 only).
720   ``rt``
721      enable rt extensions whose implementation is still experimental.
722   ``sam``
723      enable optimizations to move more driver internal objects to VRAM.
724
725:envvar:`RADV_TEX_ANISO`
726   force anisotropy filter (up to 16)
727
728:envvar:`ACO_DEBUG`
729   a comma-separated list of named flags, which do various things:
730
731   ``validateir``
732      validate the ACO IR at various points of compilation (enabled by
733      default for debug/debugoptimized builds)
734   ``validatera``
735      validate register assignment of ACO IR and catches many RA bugs
736   ``perfwarn``
737      abort on some suboptimal code generation
738   ``force-waitcnt``
739      force emitting waitcnt states if there is something to wait for
740   ``novn``
741      disable value numbering
742   ``noopt``
743      disable various optimizations
744   ``noscheduling``
745      disable instructions scheduling
746   ``perfinfo``
747      print information used to calculate some pipeline statistics
748   ``liveinfo``
749      print liveness and register demand information before scheduling
750
751radeonsi driver environment variables
752-------------------------------------
753
754:envvar:`AMD_DEBUG`
755   a comma-separated list of named flags, which do various things:
756
757   ``nodcc``
758      Disable DCC.
759   ``nodccclear``
760      Disable DCC fast clear.
761   ``nodccmsaa``
762      Disable DCC for MSAA
763   ``nodpbb``
764      Disable DPBB.
765   ``nodfsm``
766      Disable DFSM.
767   ``notiling``
768      Disable tiling
769   ``nofmask``
770      Disable MSAA compression
771   ``nohyperz``
772      Disable Hyper-Z
773   ``no2d``
774      Disable 2D tiling
775   ``info``
776      Print driver information
777   ``tex``
778      Print texture info
779   ``compute``
780      Print compute info
781   ``vm``
782      Print virtual addresses when creating resources
783   ``vs``
784      Print vertex shaders
785   ``ps``
786      Print pixel shaders
787   ``gs``
788      Print geometry shaders
789   ``tcs``
790      Print tessellation control shaders
791   ``tes``
792      Print tessellation evaluation shaders
793   ``cs``
794      Print compute shaders
795   ``noir``
796      Don't print the LLVM IR
797   ``nonir``
798      Don't print NIR when printing shaders
799   ``noasm``
800      Don't print disassembled shaders
801   ``preoptir``
802      Print the LLVM IR before initial optimizations
803   ``gisel``
804      Enable LLVM global instruction selector.
805   ``w32ge``
806      Use Wave32 for vertex, tessellation, and geometry shaders.
807   ``w32ps``
808      Use Wave32 for pixel shaders.
809   ``w32cs``
810      Use Wave32 for computes shaders.
811   ``w64ge``
812      Use Wave64 for vertex, tessellation, and geometry shaders.
813   ``w64ps``
814      Use Wave64 for pixel shaders.
815   ``w64cs``
816      Use Wave64 for computes shaders.
817   ``checkir``
818      Enable additional sanity checks on shader IR
819   ``mono``
820      Use old-style monolithic shaders compiled on demand
821   ``nooptvariant``
822      Disable compiling optimized shader variants.
823   ``nowc``
824      Disable GTT write combining
825   ``check_vm``
826      Check VM faults and dump debug info.
827   ``reserve_vmid``
828      Force VMID reservation per context.
829   ``nogfx``
830      Disable graphics. Only multimedia compute paths can be used.
831   ``nongg``
832      Disable NGG and use the legacy pipeline.
833   ``nggc``
834      Always use NGG culling even when it can hurt.
835   ``nonggc``
836      Disable NGG culling.
837   ``switch_on_eop``
838      Program WD/IA to switch on end-of-packet.
839   ``nooutoforder``
840      Disable out-of-order rasterization
841   ``dpbb``
842      Enable DPBB.
843   ``dfsm``
844      Enable DFSM.
845
846r600 driver environment variables
847---------------------------------
848
849:envvar:`R600_DEBUG`
850   a comma-separated list of named flags, which do various things:
851
852   ``nocpdma``
853      Disable CP DMA
854   ``nosb``
855      Disable sb backend for graphics shaders
856   ``sbcl``
857      Enable sb backend for compute shaders
858   ``sbdry``
859      Don't use optimized bytecode (just print the dumps)
860   ``sbstat``
861      Print optimization statistics for shaders
862   ``sbdump``
863      Print IR dumps after some optimization passes
864   ``sbnofallback``
865      Abort on errors instead of fallback
866   ``sbdisasm``
867      Use sb disassembler for shader dumps
868   ``sbsafemath``
869      Disable unsafe math optimizations
870   ``nirsb``
871      Enable NIR with SB optimizer
872   ``tex``
873      Print texture info
874   ``nir``
875      Enable experimental NIR shaders
876   ``compute``
877      Print compute info
878   ``vm``
879      Print virtual addresses when creating resources
880   ``info``
881      Print driver information
882   ``fs``
883      Print fetch shaders
884   ``vs``
885      Print vertex shaders
886   ``gs``
887      Print geometry shaders
888   ``ps``
889      Print pixel shaders
890   ``cs``
891      Print compute shaders
892   ``tcs``
893      Print tessellation control shaders
894   ``tes``
895      Print tessellation evaluation shaders
896   ``noir``
897      Don't print the LLVM IR
898   ``notgsi``
899      Don't print the TGSI
900   ``noasm``
901      Don't print disassembled shaders
902   ``preoptir``
903      Print the LLVM IR before initial optimizations
904   ``checkir``
905      Enable additional sanity checks on shader IR
906   ``nooptvariant``
907      Disable compiling optimized shader variants.
908   ``testdma``
909      Invoke SDMA tests and exit.
910   ``testvmfaultcp``
911      Invoke a CP VM fault test and exit.
912   ``testvmfaultsdma``
913      Invoke a SDMA VM fault test and exit.
914   ``testvmfaultshader``
915      Invoke a shader VM fault test and exit.
916   ``nodma``
917      Disable asynchronous DMA
918   ``nohyperz``
919      Disable Hyper-Z
920   ``noinvalrange``
921      Disable handling of INVALIDATE_RANGE map flags
922   ``no2d``
923      Disable 2D tiling
924   ``notiling``
925      Disable tiling
926   ``switch_on_eop``
927      Program WD/IA to switch on end-of-packet.
928   ``forcedma``
929      Use asynchronous DMA for all operations when possible.
930   ``precompile``
931      Compile one shader variant at shader creation.
932   ``nowc``
933      Disable GTT write combining
934   ``check_vm``
935      Check VM faults and dump debug info.
936   ``unsafemath``
937      Enable unsafe math shader optimizations
938
939:envvar:`R600_DEBUG_COMPUTE`
940   if set to ``true``, various compute-related debug information will
941   be printed to stderr. Defaults to ``false``.
942:envvar:`R600_DUMP_SHADERS`
943   if set to ``true``, NIR shaders will be printed to stderr. Defaults
944   to ``false``.
945:envvar:`R600_HYPERZ`
946   If set to ``false``, disables HyperZ optimizations. Defaults to ``true``.
947:envvar:`R600_NIR_DEBUG`
948   a comma-separated list of named flags, which do various things:
949
950   ``instr``
951      Log all consumed nir instructions
952   ``ir``
953      Log created R600 IR
954   ``cc``
955      Log R600 IR to assembly code creation
956   ``noerr``
957      Don't log shader conversion errors
958   ``si``
959      Log shader info (non-zero values)
960   ``reg``
961      Log register allocation and lookup
962   ``io``
963      Log shader in and output
964   ``ass``
965      Log IR to assembly conversion
966   ``flow``
967      Log control flow instructions
968   ``merge``
969      Log register merge operations
970   ``nomerge``
971      Skip register merge step
972   ``tex``
973      Log texture ops
974   ``trans``
975      Log generic translation messages
976
977Other Gallium drivers have their own environment variables. These may
978change frequently so the source code should be consulted for details.
979