• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
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_EXTENSION_OVERRIDE`
72   can be used to enable/disable extensions. A value such as
73   ``GL_EXT_foo -GL_EXT_bar`` will enable the ``GL_EXT_foo`` extension
74   and disable the ``GL_EXT_bar`` extension. Note that this will override
75   extensions override configured using driconf.
76:envvar:`MESA_EXTENSION_MAX_YEAR`
77   The ``GL_EXTENSIONS`` string returned by Mesa is sorted by extension
78   year. If this variable is set to year X, only extensions defined on
79   or before year X will be reported. This is to work-around a bug in
80   some games where the extension string is copied into a fixed-size
81   buffer without truncating. If the extension string is too long, the
82   buffer overrun can cause the game to crash. This is a work-around for
83   that.
84:envvar:`MESA_GL_VERSION_OVERRIDE`
85   changes the value returned by ``glGetString(GL_VERSION)`` and
86   possibly the GL API type.
87
88   -  The format should be ``MAJOR.MINOR[FC|COMPAT]``
89   -  ``FC`` is an optional suffix that indicates a forward compatible
90      context. This is only valid for versions >= 3.0.
91   -  ``COMPAT`` is an optional suffix that indicates a compatibility
92      context or ``GL_ARB_compatibility`` support. This is only valid
93      for versions >= 3.1.
94   -  GL versions <= 3.0 are set to a compatibility (non-Core) profile
95   -  GL versions = 3.1, depending on the driver, it may or may not have
96      the ``ARB_compatibility`` extension enabled.
97   -  GL versions >= 3.2 are set to a Core profile
98   -  Examples:
99
100      ``2.1``
101         select a compatibility (non-Core) profile with GL version 2.1.
102      ``3.0``
103         select a compatibility (non-Core) profile with GL version 3.0.
104      ``3.0FC``
105         select a Core+Forward Compatible profile with GL version 3.0.
106      ``3.1``
107         select GL version 3.1 with ``GL_ARB_compatibility`` enabled per
108         the driver default.
109      ``3.1FC``
110         select GL version 3.1 with forward compatibility and
111         ``GL_ARB_compatibility`` disabled.
112      ``3.1COMPAT``
113         select GL version 3.1 with ``GL_ARB_compatibility`` enabled.
114      ``X.Y``
115         override GL version to X.Y without changing the profile.
116      ``X.YFC``
117         select a Core+Forward Compatible profile with GL version X.Y.
118      ``X.YCOMPAT``
119         select a Compatibility profile with GL version X.Y.
120
121   -  Mesa may not really implement all the features of the given
122      version. (for developers only)
123
124:envvar:`MESA_GLES_VERSION_OVERRIDE`
125   changes the value returned by ``glGetString(GL_VERSION)`` for OpenGL
126   ES.
127
128   -  The format should be ``MAJOR.MINOR``
129   -  Examples: ``2.0``, ``3.0``, ``3.1``
130   -  Mesa may not really implement all the features of the given
131      version. (for developers only)
132
133:envvar:`MESA_GLSL_VERSION_OVERRIDE`
134   changes the value returned by
135   ``glGetString(GL_SHADING_LANGUAGE_VERSION)``. Valid values are
136   integers, such as ``130``. Mesa will not really implement all the
137   features of the given language version if it's higher than what's
138   normally reported. (for developers only)
139:envvar:`MESA_SHADER_CACHE_DISABLE`
140   if set to ``true``, disables the on-disk shader cache. If set to
141   ``false``, enables the on-disk shader cache when it is disabled by
142   default.
143:envvar:`MESA_SHADER_CACHE_MAX_SIZE`
144   if set, determines the maximum size of the on-disk cache of compiled
145   shader programs. Should be set to a number optionally followed by
146   ``K``, ``M``, or ``G`` to specify a size in kilobytes, megabytes, or
147   gigabytes. By default, gigabytes will be assumed. And if unset, a
148   maximum size of 1GB will be used.
149
150   .. note::
151
152      A separate cache might be created for each architecture that Mesa is
153      installed for on your system. For example under the default settings
154      you may end up with a 1GB cache for x86_64 and another 1GB cache for
155      i386.
156
157:envvar:`MESA_SHADER_CACHE_DIR`
158   if set, determines the directory to be used for the on-disk cache of
159   compiled shader programs. If this variable is not set, then the cache
160   will be stored in ``$XDG_CACHE_HOME/mesa_shader_cache`` (if that
161   variable is set), or else within ``.cache/mesa_shader_cache`` within
162   the user's home directory.
163:envvar:`MESA_GLSL`
164   :ref:`shading language compiler options <envvars>`
165:envvar:`MESA_NO_MINMAX_CACHE`
166   when set, the minmax index cache is globally disabled.
167:envvar:`MESA_SHADER_CAPTURE_PATH`
168   see :ref:`Capturing Shaders <capture>`
169:envvar:`MESA_SHADER_DUMP_PATH` and :envvar:`MESA_SHADER_READ_PATH`
170   see :ref:`Experimenting with Shader
171   Replacements <replacement>`
172:envvar:`MESA_VK_VERSION_OVERRIDE`
173   changes the Vulkan physical device version as returned in
174   ``VkPhysicalDeviceProperties::apiVersion``.
175
176   -  The format should be ``MAJOR.MINOR[.PATCH]``
177   -  This will not let you force a version higher than the driver's
178      instance version as advertised by ``vkEnumerateInstanceVersion``
179   -  This can be very useful for debugging but some features may not be
180      implemented correctly. (For developers only)
181:envvar:`MESA_VK_WSI_PRESENT_MODE`
182   overrides the WSI present mode clients specify in
183   ``VkSwapchainCreateInfoKHR::presentMode``. Values can be ``fifo``,
184   ``relaxed``, ``mailbox`` or ``immediate``.
185:envvar:`MESA_VK_ABORT_ON_DEVICE_LOSS`
186   causes the Vulkan driver to call abort() immediately after detecting a
187   lost device.  This is extremely useful when testing as it prevents the
188   test suite from continuing on with a lost device.
189:envvar:`MESA_VK_ENABLE_SUBMIT_THREAD`
190   for Vulkan drivers which support real timeline semaphores, this forces
191   them to use a submit thread from the beginning, regardless of whether or
192   not they ever see a wait-before-signal condition.
193:envvar:`MESA_LOADER_DRIVER_OVERRIDE`
194   chooses a different driver binary such as ``etnaviv`` or ``zink``.
195
196NIR passes environment variables
197--------------------------------
198
199The following are only applicable for drivers that uses NIR, as they
200modify the behavior for the common ``NIR_PASS`` and ``NIR_PASS_V`` macros,
201that wrap calls to NIR lowering/optimizations.
202
203:envvar:`NIR_DEBUG`
204   a comma-separated list of debug options to apply to NIR
205   shaders. Use `NIR_DEBUG=help` to print a list of available options.
206:envvar:`NIR_SKIP`
207   a comma-separated list of optimization/lowering passes to skip.
208
209Mesa Xlib driver environment variables
210--------------------------------------
211
212The following are only applicable to the Mesa Xlib software driver. See
213the :doc:`Xlib software driver page <xlibdriver>` for details.
214
215:envvar:`MESA_RGB_VISUAL`
216   specifies the X visual and depth for RGB mode
217:envvar:`MESA_BACK_BUFFER`
218   specifies how to implement the back color buffer, either ``pixmap``
219   or ``ximage``
220:envvar:`MESA_XSYNC`
221   enable synchronous X behavior (for debugging only)
222:envvar:`MESA_GLX_FORCE_ALPHA`
223   if set, forces RGB windows to have an alpha channel.
224:envvar:`MESA_GLX_DEPTH_BITS`
225   specifies default number of bits for depth buffer.
226:envvar:`MESA_GLX_ALPHA_BITS`
227   specifies default number of bits for alpha channel.
228
229Mesa WGL driver environment variables
230-------------------------------------
231
232The following are only applicable to the Mesa WGL driver, which is in use
233on Windows.
234
235:envvar:`WGL_FORCE_MSAA`
236   if set to a positive value, specifies the number of MSAA samples to
237   force when choosing the display configuration.
238:envvar:`WGL_DISABLE_ERROR_DIALOGS`
239   if set to 1, true or yes, disables Win32 error dialogs. Useful for
240   automated test-runs.
241
242Intel driver environment variables
243----------------------------------------------------
244
245:envvar:`INTEL_BLACKHOLE_DEFAULT`
246   if set to 1, true or yes, then the OpenGL implementation will
247   default ``GL_BLACKHOLE_RENDER_INTEL`` to true, thus disabling any
248   rendering.
249:envvar:`INTEL_COMPUTE_CLASS`
250   If set to 1, true or yes, then I915_ENGINE_CLASS_COMPUTE will be
251   supported. For OpenGL, iris will attempt to use a compute engine
252   for compute dispatches if one is detected. For Vulkan, anvil will
253   advertise support for a compute queue if a compute engine is
254   detected.
255:envvar:`INTEL_DEBUG`
256   a comma-separated list of named flags, which do various things:
257
258   ``ann``
259      annotate IR in assembly dumps
260   ``bat``
261      emit batch information
262   ``blit``
263      emit messages about blit operations
264   ``blorp``
265      emit messages about the blorp operations (blits & clears)
266   ``buf``
267      emit messages about buffer objects
268   ``bt``
269      emit messages binding tables
270   ``clip``
271      emit messages about the clip unit (for old gens, includes the CLIP
272      program)
273   ``color``
274      use color in output
275   ``cs``
276      dump shader assembly for compute shaders
277   ``do32``
278      generate compute shader SIMD32 programs even if workgroup size
279      doesn't exceed the SIMD16 limit
280   ``fall``
281      emit messages about performance issues (same as ``perf``)
282   ``fs``
283      dump shader assembly for fragment shaders
284   ``gs``
285      dump shader assembly for geometry shaders
286   ``hex``
287      print instruction hex dump with the disassembly
288   ``l3``
289      emit messages about the new L3 state during transitions
290   ``mesh``
291      dump shader assembly for mesh shaders
292   ``no8``
293      don't generate SIMD8 fragment shader
294   ``no16``
295      suppress generation of 16-wide fragment shaders. useful for
296      debugging broken shaders
297   ``no32``
298      suppress generation of 32-wide fragment shaders. useful for
299      debugging broken shaders
300   ``no-oaconfig``
301      disable HW performance metric configuration, and anything
302      related to i915-perf (useful when running on simulation)
303   ``nocompact``
304      disable instruction compaction
305   ``nodualobj``
306      suppress generation of dual-object geometry shader code
307   ``nofc``
308      disable fast clears
309   ``noccs``
310      disable lossless color compression
311   ``optimizer``
312      dump shader assembly to files at each optimization pass and
313      iteration that make progress
314   ``pc``
315      emit messages about PIPE_CONTROL instruction usage
316   ``perf``
317      emit messages about performance issues
318   ``perfmon``
319      emit messages about ``AMD_performance_monitor``
320   ``reemit``
321      mark all state dirty on each draw call
322   ``rt``
323      dump shader assembly for ray tracing shaders
324   ``sf``
325      emit messages about the strips & fans unit (for old gens, includes
326      the SF program)
327   ``soft64``
328      enable implementation of software 64bit floating point support
329   ``spill_fs``
330      force spilling of all registers in the scalar backend (useful to
331      debug spilling code)
332   ``spill_vec4``
333      force spilling of all registers in the vec4 backend (useful to
334      debug spilling code)
335   ``stall``
336      inserts a stall on the GPU after each draw/dispatch command to
337      wait for it to finish before starting any new work.
338   ``submit``
339      emit batchbuffer usage statistics
340   ``sync``
341      after sending each batch, wait on the CPU for that batch to
342      finish rendering
343   ``task``
344      dump shader assembly for task shaders
345   ``tcs``
346      dump shader assembly for tessellation control shaders
347   ``tcs8``
348      force usage of 8-patches tessellation control shaders (only
349      for gfx 9-11)
350   ``tes``
351      dump shader assembly for tessellation evaluation shaders
352   ``tex``
353      emit messages about textures.
354   ``urb``
355      emit messages about URB setup
356   ``vs``
357      dump shader assembly for vertex shaders
358   ``wm``
359      dump shader assembly for fragment shaders (same as ``fs``)
360
361:envvar:`INTEL_MEASURE`
362   Collects GPU timestamps over common intervals, and generates a CSV report
363   to show how long rendering took.  The overhead of collection is limited to
364   the flushing that is required at the interval boundaries for accurate
365   timestamps. By default, timing data is sent to ``stderr``.  To direct output
366   to a file:
367
368   ``INTEL_MEASURE=file=/tmp/measure.csv {workload}``
369
370   To begin capturing timestamps at a particular frame:
371
372   ``INTEL_MEASURE=file=/tmp/measure.csv,start=15 {workload}``
373
374   To capture only 23 frames:
375
376   ``INTEL_MEASURE=count=23 {workload}``
377
378   To capture frames 15-37, stopping before frame 38:
379
380   ``INTEL_MEASURE=start=15,count=23 {workload}``
381
382   Designate an asynchronous control file with:
383
384   ``INTEL_MEASURE=control=path/to/control.fifo {workload}``
385
386   As the workload runs, enable capture for 5 frames with:
387
388   ``$ echo 5 > path/to/control.fifo``
389
390   Enable unbounded capture:
391
392   ``$ echo -1 > path/to/control.fifo``
393
394   and disable with:
395
396   ``$ echo 0 > path/to/control.fifo``
397
398   Select the boundaries of each snapshot with:
399
400   ``INTEL_MEASURE=draw``
401      Collects timings for every render (DEFAULT)
402
403   ``INTEL_MEASURE=rt``
404      Collects timings when the render target changes
405
406   ``INTEL_MEASURE=batch``
407      Collects timings when batches are submitted
408
409   ``INTEL_MEASURE=frame``
410      Collects timings at frame boundaries
411
412   With ``INTEL_MEASURE=interval=5``, the duration of 5 events will be
413   combined into a single record in the output.  When possible, a single
414   start and end event will be submitted to the GPU to minimize
415   stalling.  Combined events will not span batches, except in
416   the case of ``INTEL_MEASURE=frame``.
417:envvar:`INTEL_NO_HW`
418   if set to 1, true or yes, prevents batches from being submitted to the
419   hardware. This is useful for debugging hangs, etc.
420:envvar:`INTEL_PRECISE_TRIG`
421   if set to 1, true or yes, then the driver prefers accuracy over
422   performance in trig functions.
423:envvar:`INTEL_SHADER_ASM_READ_PATH`
424   if set, determines the directory to be used for overriding shader
425   assembly. The binaries with custom assembly should be placed in
426   this folder and have a name formatted as ``sha1_of_assembly.bin``.
427   The sha1 of a shader assembly is printed when assembly is dumped via
428   corresponding :envvar:`INTEL_DEBUG` flag (e.g. ``vs`` for vertex shader).
429   A binary could be generated from a dumped assembly by ``i965_asm``.
430   For :envvar:`INTEL_SHADER_ASM_READ_PATH` to work it is necessary to enable
431   dumping of corresponding shader stages via :envvar:`INTEL_DEBUG`.
432   It is advised to use ``nocompact`` flag of :envvar:`INTEL_DEBUG` when
433   dumping and overriding shader assemblies.
434   The success of assembly override would be signified by "Successfully
435   overrode shader with sha1 <sha1>" in stderr replacing the original
436   assembly.
437
438
439DRI environment variables
440-------------------------
441
442:envvar:`DRI_NO_MSAA`
443   disable MSAA for GLX/EGL MSAA visuals
444
445
446Vulkan mesa device select layer environment variables
447-----------------------------------------------------
448
449:envvar:`MESA_VK_DEVICE_SELECT`
450   when set to "list" prints the list of devices.
451   when set to "vid:did" number from pci device. That pci device is
452   selected as default. The default device is returned as the first
453   device in vkEnumeratePhysicalDevices api.
454:envvar:`MESA_VK_DEVICE_SELECT_FORCE_DEFAULT_DEVICE`
455   when set to 1, the device identified as default will be the only
456   one returned in vkEnumeratePhysicalDevices api.
457
458
459EGL environment variables
460-------------------------
461
462Mesa EGL supports different sets of environment variables. See the
463:doc:`Mesa EGL <egl>` page for the details.
464
465Gallium environment variables
466-----------------------------
467
468:envvar:`GALLIUM_HUD`
469   draws various information on the screen, like framerate, CPU load,
470   driver statistics, performance counters, etc. Set
471   :envvar:`GALLIUM_HUD` to ``help`` and run e.g. ``glxgears`` for more info.
472:envvar:`GALLIUM_HUD_PERIOD`
473   sets the HUD update rate in seconds (float). Use zero to update every
474   frame. The default period is 1/2 second.
475:envvar:`GALLIUM_HUD_VISIBLE`
476   control default visibility, defaults to true.
477:envvar:`GALLIUM_HUD_TOGGLE_SIGNAL`
478   toggle visibility via user specified signal. Especially useful to
479   toggle HUD at specific points of application and disable for
480   unencumbered viewing the rest of the time. For example, set
481   :envvar:`GALLIUM_HUD_VISIBLE` to ``false`` and
482   :envvar:`GALLIUM_HUD_TOGGLE_SIGNAL` to ``10`` (``SIGUSR1``). Use
483   ``kill -10 <pid>`` to toggle the HUD as desired.
484:envvar:`GALLIUM_HUD_SCALE`
485   Scale HUD by an integer factor, for high DPI displays. Default is 1.
486:envvar:`GALLIUM_HUD_DUMP_DIR`
487   specifies a directory for writing the displayed HUD values into
488   files.
489:envvar:`GALLIUM_DRIVER`
490   useful in combination with :envvar:`LIBGL_ALWAYS_SOFTWARE`=`true` for
491   choosing one of the software renderers ``softpipe`` or ``llvmpipe``.
492:envvar:`GALLIUM_LOG_FILE`
493   specifies a file for logging all errors, warnings, etc. rather than
494   stderr.
495:envvar:`GALLIUM_PIPE_SEARCH_DIR`
496   specifies an alternate search directory for pipe-loader which overrides
497   the compile-time path based on the install location.
498:envvar:`GALLIUM_PRINT_OPTIONS`
499   if non-zero, print all the Gallium environment variables which are
500   used, and their current values.
501:envvar:`GALLIUM_DUMP_CPU`
502   if non-zero, print information about the CPU on start-up
503:envvar:`TGSI_PRINT_SANITY`
504   if set, do extra sanity checking on TGSI shaders and print any errors
505   to stderr.
506:envvar:`DRAW_FSE`
507   Enable fetch-shade-emit middle-end even though its not correct (e.g.
508   for softpipe)
509:envvar:`DRAW_NO_FSE`
510   Disable fetch-shade-emit middle-end even when it is correct
511:envvar:`DRAW_USE_LLVM`
512   if set to zero, the draw module will not use LLVM to execute shaders,
513   vertex fetch, etc.
514:envvar:`ST_DEBUG`
515   controls debug output from the Mesa/Gallium state tracker. Setting to
516   ``tgsi``, for example, will print all the TGSI shaders. See
517   :file:`src/mesa/state_tracker/st_debug.c` for other options.
518
519Clover environment variables
520----------------------------
521
522:envvar:`CLOVER_EXTRA_BUILD_OPTIONS`
523   allows specifying additional compiler and linker options. Specified
524   options are appended after the options set by the OpenCL program in
525   ``clBuildProgram``.
526:envvar:`CLOVER_EXTRA_COMPILE_OPTIONS`
527   allows specifying additional compiler options. Specified options are
528   appended after the options set by the OpenCL program in
529   ``clCompileProgram``.
530:envvar:`CLOVER_EXTRA_LINK_OPTIONS`
531   allows specifying additional linker options. Specified options are
532   appended after the options set by the OpenCL program in
533   ``clLinkProgram``.
534
535
536Nine frontend environment variables
537-----------------------------------
538
539:envvar:`D3D_ALWAYS_SOFTWARE`
540   an integer, which forces Nine to use the CPU instead of GPU acceleration.
541
542:envvar:`NINE_DEBUG`
543   a comma-separated list of named flags that do debugging things.
544   Use `NINE_DEBUG=help` to print a list of available options.
545
546:envvar:`NINE_FF_DUMP`
547   a boolean, which dumps shaders generated by a fixed function (FF).
548
549:envvar:`NINE_SHADER`
550   a comma-separated list of named flags, which do alternate shader handling.
551   Use `NINE_SHADER=help` to print a list of available options.
552
553:envvar:`NINE_QUIRKS`
554   a comma-separated list of named flags that do various things.
555   Use `NINE_DEBUG=help` to print a list of available options.
556
557Softpipe driver environment variables
558-------------------------------------
559
560:envvar:`SOFTPIPE_DEBUG`
561   a comma-separated list of named flags, which do various things:
562
563   ``vs``
564      Dump vertex shader assembly to stderr
565   ``fs``
566      Dump fragment shader assembly to stderr
567   ``gs``
568      Dump geometry shader assembly to stderr
569   ``cs``
570      Dump compute shader assembly to stderr
571   ``no_rast``
572      rasterization is disabled. For profiling purposes.
573   ``use_llvm``
574      the softpipe driver will try to use LLVM JIT for vertex
575      shading processing.
576   ``use_tgsi``
577      if set, the softpipe driver will ask to directly consume TGSI, instead
578      of NIR.
579
580LLVMpipe driver environment variables
581-------------------------------------
582
583:envvar:`LP_NO_RAST`
584   if set LLVMpipe will no-op rasterization
585:envvar:`LP_DEBUG`
586   a comma-separated list of debug options is accepted. See the source
587   code for details.
588:envvar:`LP_PERF`
589   a comma-separated list of options to selectively no-op various parts
590   of the driver. See the source code for details.
591:envvar:`LP_NUM_THREADS`
592   an integer indicating how many threads to use for rendering. Zero
593   turns off threading completely. The default value is the number of
594   CPU cores present.
595
596VMware SVGA driver environment variables
597----------------------------------------
598
599:envvar:`SVGA_FORCE_SWTNL`
600   force use of software vertex transformation
601:envvar:`SVGA_NO_SWTNL`
602   don't allow software vertex transformation fallbacks (will often
603   result in incorrect rendering).
604:envvar:`SVGA_DEBUG`
605   for dumping shaders, constant buffers, etc. See the code for details.
606:envvar:`SVGA_EXTRA_LOGGING`
607   if set, enables extra logging to the ``vmware.log`` file, such as the
608   OpenGL program's name and command line arguments.
609:envvar:`SVGA_NO_LOGGING`
610   if set, disables logging to the ``vmware.log`` file. This is useful
611   when using Valgrind because it otherwise crashes when initializing
612   the host log feature.
613
614See the driver code for other, lesser-used variables.
615
616WGL environment variables
617-------------------------
618
619:envvar:`WGL_SWAP_INTERVAL`
620   to set a swap interval, equivalent to calling
621   ``wglSwapIntervalEXT()`` in an application. If this environment
622   variable is set, application calls to ``wglSwapIntervalEXT()`` will
623   have no effect.
624
625VA-API environment variables
626----------------------------
627
628:envvar:`VAAPI_MPEG4_ENABLED`
629   enable MPEG4 for VA-API, disabled by default.
630
631VC4 driver environment variables
632--------------------------------
633
634:envvar:`VC4_DEBUG`
635   a comma-separated list of named flags, which do various things. Use
636   `VC4_DEBUG=help` to print a list of available options.
637
638
639V3D/V3DV driver environment variables
640-------------------------------------
641
642:envvar:`V3D_DEBUG`
643    a comma-separated list of debug options. Use `V3D_DEBUG=help` to
644    print a list of available options.
645
646
647.. _radv env-vars:
648
649RADV driver environment variables
650---------------------------------
651
652:envvar:`RADV_DEBUG`
653   a comma-separated list of named flags, which do various things:
654
655   ``llvm``
656      enable LLVM compiler backend
657   ``allbos``
658      force all allocated buffers to be referenced in submissions
659   ``checkir``
660      validate the LLVM IR before LLVM compiles the shader
661   ``epilogs``
662      dump fragment shader epilogs
663   ``forcecompress``
664      Enables DCC,FMASK,CMASK,HTILE in situations where the driver supports it
665      but normally does not deem it beneficial.
666   ``hang``
667      enable GPU hangs detection and dump a report to
668      $HOME/radv_dumps_<pid>_<time> if a GPU hang is detected
669   ``img``
670      Print image info
671   ``info``
672      show GPU-related information
673   ``invariantgeom``
674      Mark geometry-affecting outputs as invariant. This works around a common
675      class of application bugs appearing as flickering.
676   ``metashaders``
677      dump internal meta shaders
678   ``noatocdithering``
679      disable dithering for alpha to coverage
680   ``nobinning``
681      disable primitive binning
682   ``nocache``
683      disable shaders cache
684   ``nocompute``
685      disable compute queue
686   ``nodcc``
687      disable Delta Color Compression (DCC) on images
688   ``nodisplaydcc``
689      disable Delta Color Compression (DCC) on displayable images
690   ``nodynamicbounds``
691      do not check OOB access for dynamic descriptors
692   ``nofastclears``
693      disable fast color/depthstencil clears
694   ``nohiz``
695      disable HIZ for depthstencil images
696   ``noibs``
697      disable directly recording command buffers in GPU-visible memory
698   ``nomemorycache``
699      disable memory shaders cache
700   ``nongg``
701      disable NGG for GFX10 and GFX10.3
702   ``nonggc``
703      disable NGG culling on GPUs where it's enabled by default (GFX10.3+ only).
704   ``nooutoforder``
705      disable out-of-order rasterization
706   ``notccompatcmask``
707      disable TC-compat CMASK for MSAA surfaces
708   ``noumr``
709      disable UMR dumps during GPU hang detection (only with
710      :envvar:`RADV_DEBUG`=``hang``)
711   ``novrsflatshading``
712      disable VRS for flat shading (only on GFX10.3+)
713   ``preoptir``
714      dump LLVM IR before any optimizations
715   ``prologs``
716      dump vertex shader prologs
717   ``shaders``
718      dump shaders
719   ``shaderstats``
720      dump shader statistics
721   ``spirv``
722      dump SPIR-V
723   ``splitfma``
724      split application-provided fused multiply-add in geometry stages
725   ``startup``
726      display info at startup
727   ``syncshaders``
728      synchronize shaders after all draws/dispatches
729   ``vmfaults``
730      check for VM memory faults via dmesg
731   ``zerovram``
732      initialize all memory allocated in VRAM as zero
733
734:envvar:`RADV_FORCE_FAMILY`
735   create a null device to compile shaders without a AMD GPU (e.g. VEGA10)
736
737:envvar:`RADV_FORCE_VRS`
738   allow to force per-pipeline vertex VRS rates on GFX10.3+. This is only
739   forced for pipelines that don't explicitely use VRS or flat shading.
740   The supported values are 2x2, 1x2, 2x1 and 1x1. Only for testing purposes.
741
742:envvar:`RADV_FORCE_VRS_CONFIG_FILE`
743   similar to `RADV_FORCE_VRS` but allow to configure from a file. If present,
744   this supersedes `RADV_FORCE_VRS`.
745
746:envvar:`RADV_PERFTEST`
747   a comma-separated list of named flags, which do various things:
748
749   ``bolist``
750      enable the global BO list
751   ``cswave32``
752      enable wave32 for compute shaders (GFX10+)
753   ``dccmsaa``
754      enable DCC for MSAA images
755   ``emulate_rt``
756      forces ray-tracing to be emulated in software on GFX10_3+ and enables
757      rt extensions with older hardware.
758   ``gewave32``
759      enable wave32 for vertex/tess/geometry shaders (GFX10+)
760   ``localbos``
761      enable local BOs
762   ``nosam``
763      disable optimizations that get enabled when all VRAM is CPU visible.
764   ``nv_ms``
765      enable unofficial experimental support for NV_mesh_shader.
766   ``pswave32``
767      enable wave32 for pixel shaders (GFX10+)
768   ``nggc``
769      enable NGG culling on GPUs where it's not enabled by default (GFX10.1 only).
770   ``rt``
771      enable rt pipelines whose implementation is still experimental.
772   ``sam``
773      enable optimizations to move more driver internal objects to VRAM.
774   ``rtwave64``
775      enable wave64 for ray tracing shaders (GFX10+)
776
777:envvar:`RADV_TEX_ANISO`
778   force anisotropy filter (up to 16)
779
780:envvar:`RADV_THREAD_TRACE`
781   enable frame based SQTT/RGP captures (eg. `export RADV_THREAD_TRACE=100`
782   will capture the frame #100)
783
784:envvar:`RADV_THREAD_TRACE_BUFFER_SIZE`
785   set the SQTT/RGP buffer size in bytes (default value is 32MiB, the buffer is
786   automatically resized if too small)
787
788:envvar:`RADV_THREAD_TRACE_CACHE_COUNTERS`
789   enable/disable SQTT/RGP cache counters on GFX10+ (disabled by default)
790
791:envvar:`RADV_THREAD_TRACE_INSTRUCTION_TIMING`
792   enable/disable SQTT/RGP instruction timing (enabled by default)
793
794:envvar:`RADV_THREAD_TRACE_TRIGGER`
795   enable trigger file based SQTT/RGP captures (eg.
796   `export RADV_THREAD_TRACE_TRIGGER=/tmp/radv_sqtt_trigger` and then
797   `touch /tmp/radv_sqtt_trigger` to capture a frame)
798
799:envvar:`ACO_DEBUG`
800   a comma-separated list of named flags, which do various things:
801
802   ``validateir``
803      validate the ACO IR at various points of compilation (enabled by
804      default for debug/debugoptimized builds)
805   ``validatera``
806      validate register assignment of ACO IR and catches many RA bugs
807   ``perfwarn``
808      abort on some suboptimal code generation
809   ``force-waitcnt``
810      force emitting waitcnt states if there is something to wait for
811   ``novn``
812      disable value numbering
813   ``noopt``
814      disable various optimizations
815   ``noscheduling``
816      disable instructions scheduling
817   ``perfinfo``
818      print information used to calculate some pipeline statistics
819   ``liveinfo``
820      print liveness and register demand information before scheduling
821
822radeonsi driver environment variables
823-------------------------------------
824
825:envvar:`radeonsi_no_infinite_interp`
826   Kill PS with infinite interp coeff (might fix hangs)
827
828:envvar:`radeonsi_clamp_div_by_zero`
829   Clamp div by zero (x / 0 becomes FLT_MAX instead of NaN) (might fix rendering corruptions)
830
831:envvar:`radeonsi_zerovram`
832   Clear all allocated memory to 0 before usage (might fix rendering corruptions)
833
834:envvar:`AMD_DEBUG`
835   a comma-separated list of named flags, which do various things:
836
837   ``nodcc``
838      Disable DCC.
839   ``nodccclear``
840      Disable DCC fast clear
841   ``nodisplaydcc``
842      disable Delta Color Compression (DCC) on displayable images
843   ``nodccmsaa``
844      Disable DCC for MSAA
845   ``nodpbb``
846      Disable DPBB.
847   ``nodfsm``
848      Disable DFSM.
849   ``notiling``
850      Disable tiling
851   ``nofmask``
852      Disable MSAA compression
853   ``nohyperz``
854      Disable Hyper-Z
855   ``no2d``
856      Disable 2D tiling
857   ``info``
858      Print driver information
859   ``tex``
860      Print texture info
861   ``compute``
862      Print compute info
863   ``vm``
864      Print virtual addresses when creating resources
865   ``vs``
866      Print vertex shaders
867   ``ps``
868      Print pixel shaders
869   ``gs``
870      Print geometry shaders
871   ``tcs``
872      Print tessellation control shaders
873   ``tes``
874      Print tessellation evaluation shaders
875   ``cs``
876      Print compute shaders
877   ``noir``
878      Don't print the LLVM IR
879   ``nonir``
880      Don't print NIR when printing shaders
881   ``noasm``
882      Don't print disassembled shaders
883   ``preoptir``
884      Print the LLVM IR before initial optimizations
885   ``w32ge``
886      Use Wave32 for vertex, tessellation, and geometry shaders.
887   ``w32ps``
888      Use Wave32 for pixel shaders.
889   ``w32cs``
890      Use Wave32 for computes shaders.
891   ``w64ge``
892      Use Wave64 for vertex, tessellation, and geometry shaders.
893   ``w64ps``
894      Use Wave64 for pixel shaders.
895   ``w64cs``
896      Use Wave64 for computes shaders.
897   ``checkir``
898      Enable additional sanity checks on shader IR
899   ``mono``
900      Use old-style monolithic shaders compiled on demand
901   ``nooptvariant``
902      Disable compiling optimized shader variants.
903   ``nowc``
904      Disable GTT write combining
905   ``check_vm``
906      Check VM faults and dump debug info.
907   ``reserve_vmid``
908      Force VMID reservation per context.
909   ``nogfx``
910      Disable graphics. Only multimedia compute paths can be used.
911   ``nongg``
912      Disable NGG and use the legacy pipeline.
913   ``nggc``
914      Always use NGG culling even when it can hurt.
915   ``nonggc``
916      Disable NGG culling.
917   ``switch_on_eop``
918      Program WD/IA to switch on end-of-packet.
919   ``nooutoforder``
920      Disable out-of-order rasterization
921   ``dpbb``
922      Enable DPBB.
923   ``dfsm``
924      Enable DFSM.
925
926r600 driver environment variables
927---------------------------------
928
929:envvar:`R600_DEBUG`
930   a comma-separated list of named flags, which do various things:
931
932   ``nocpdma``
933      Disable CP DMA
934   ``nosb``
935      Disable sb backend for graphics shaders
936   ``sbcl``
937      Enable sb backend for compute shaders
938   ``sbdry``
939      Don't use optimized bytecode (just print the dumps)
940   ``sbstat``
941      Print optimization statistics for shaders
942   ``sbdump``
943      Print IR dumps after some optimization passes
944   ``sbnofallback``
945      Abort on errors instead of fallback
946   ``sbdisasm``
947      Use sb disassembler for shader dumps
948   ``sbsafemath``
949      Disable unsafe math optimizations
950   ``nirsb``
951      Enable NIR with SB optimizer
952   ``tex``
953      Print texture info
954   ``nir``
955      Enable experimental NIR shaders
956   ``compute``
957      Print compute info
958   ``vm``
959      Print virtual addresses when creating resources
960   ``info``
961      Print driver information
962   ``fs``
963      Print fetch shaders
964   ``vs``
965      Print vertex shaders
966   ``gs``
967      Print geometry shaders
968   ``ps``
969      Print pixel shaders
970   ``cs``
971      Print compute shaders
972   ``tcs``
973      Print tessellation control shaders
974   ``tes``
975      Print tessellation evaluation shaders
976   ``noir``
977      Don't print the LLVM IR
978   ``notgsi``
979      Don't print the TGSI
980   ``noasm``
981      Don't print disassembled shaders
982   ``preoptir``
983      Print the LLVM IR before initial optimizations
984   ``checkir``
985      Enable additional sanity checks on shader IR
986   ``nooptvariant``
987      Disable compiling optimized shader variants.
988   ``testdma``
989      Invoke SDMA tests and exit.
990   ``testvmfaultcp``
991      Invoke a CP VM fault test and exit.
992   ``testvmfaultsdma``
993      Invoke a SDMA VM fault test and exit.
994   ``testvmfaultshader``
995      Invoke a shader VM fault test and exit.
996   ``nodma``
997      Disable asynchronous DMA
998   ``nohyperz``
999      Disable Hyper-Z
1000   ``noinvalrange``
1001      Disable handling of INVALIDATE_RANGE map flags
1002   ``no2d``
1003      Disable 2D tiling
1004   ``notiling``
1005      Disable tiling
1006   ``switch_on_eop``
1007      Program WD/IA to switch on end-of-packet.
1008   ``forcedma``
1009      Use asynchronous DMA for all operations when possible.
1010   ``precompile``
1011      Compile one shader variant at shader creation.
1012   ``nowc``
1013      Disable GTT write combining
1014   ``check_vm``
1015      Check VM faults and dump debug info.
1016   ``unsafemath``
1017      Enable unsafe math shader optimizations
1018
1019:envvar:`R600_DEBUG_COMPUTE`
1020   if set to ``true``, various compute-related debug information will
1021   be printed to stderr. Defaults to ``false``.
1022:envvar:`R600_DUMP_SHADERS`
1023   if set to ``true``, NIR shaders will be printed to stderr. Defaults
1024   to ``false``.
1025:envvar:`R600_HYPERZ`
1026   If set to ``false``, disables HyperZ optimizations. Defaults to ``true``.
1027:envvar:`R600_NIR_DEBUG`
1028   a comma-separated list of named flags, which do various things:
1029
1030   ``instr``
1031      Log all consumed nir instructions
1032   ``ir``
1033      Log created R600 IR
1034   ``cc``
1035      Log R600 IR to assembly code creation
1036   ``noerr``
1037      Don't log shader conversion errors
1038   ``si``
1039      Log shader info (non-zero values)
1040   ``reg``
1041      Log register allocation and lookup
1042   ``io``
1043      Log shader in and output
1044   ``ass``
1045      Log IR to assembly conversion
1046   ``flow``
1047      Log control flow instructions
1048   ``merge``
1049      Log register merge operations
1050   ``nomerge``
1051      Skip register merge step
1052   ``tex``
1053      Log texture ops
1054   ``trans``
1055      Log generic translation messages
1056
1057r300 driver environment variables
1058---------------------------------
1059
1060:envvar:`RADEON_DEBUG`
1061   a comma-separated list of named flags, which do various things:
1062
1063   ``info``
1064      Print hardware info (printed by default on debug builds
1065   ``fp``
1066      Log fragment program compilation
1067   ``vp``
1068      Log vertex program compilation
1069   ``draw``
1070      Log draw calls
1071   ``swtcl``
1072      Log SWTCL-specific info
1073   ``rsblock``
1074      Log rasterizer registers
1075   ``psc``
1076      Log vertex stream registers
1077   ``tex``
1078      Log basic info about textures
1079   ``texalloc``
1080      Log texture mipmap tree info
1081   ``rs``
1082      Log rasterizer
1083   ``fb``
1084      Log framebuffer
1085   ``cbzb``
1086      Log fast color clear info
1087   ``hyperz``
1088      Log HyperZ info
1089   ``scissor``
1090      Log scissor info
1091   ``msaa``
1092      Log MSAA resources
1093   ``anisohq``
1094      Use high quality anisotropic filtering
1095   ``notiling``
1096      Disable tiling
1097   ``noimmd``
1098      Disable immediate mode
1099   ``noopt``
1100      Disable shader optimizations
1101   ``nocbzb``
1102      Disable fast color clear
1103   ``nozmask``
1104      Disable zbuffer compression
1105   ``nohiz``
1106      Disable hierarchical zbuffer
1107   ``nocmask``
1108      Disable AA compression and fast AA clear
1109   ``use_tgsi``
1110      Request TGSI shaders from the state tracker
1111   ``notcl``
1112      Disable hardware accelerated Transform/Clip/Lighting
1113
1114Other Gallium drivers have their own environment variables. These may
1115change frequently so the source code should be consulted for details.
1116