docs/envvars.rst

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