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 13 If defined debug information will be printed to stderr. If set to 14 ``verbose`` additional information will be printed. 15 16.. envvar:: LIBGL_DRIVERS_PATH 17 18 colon-separated list of paths to search for DRI drivers 19 20.. envvar:: LIBGL_ALWAYS_INDIRECT 21 22 if set to ``true``, forces an indirect rendering context/connection. 23 24.. envvar:: LIBGL_ALWAYS_SOFTWARE 25 26 if set to ``true``, always use software rendering 27 28.. envvar:: LIBGL_NO_DRAWARRAYS 29 30 if set to ``true``, do not use DrawArrays GLX protocol (for 31 debugging) 32 33.. envvar:: LIBGL_DRI2_DISABLE 34 35 disable DRI2 if set to ``true``. 36 37.. envvar:: LIBGL_DRI3_DISABLE 38 39 disable DRI3 if set to ``true``. 40 41Core Mesa environment variables 42------------------------------- 43 44.. envvar:: MESA_NO_ERROR 45 46 if set to 1, error checking is disabled as per :ext:`GL_KHR_no_error`. 47 This will result in undefined behavior for invalid use of the API, but 48 can reduce CPU use for apps that are known to be error free. 49 50.. envvar:: MESA_DEBUG 51 52 if set, error messages are printed to stderr. For example, if the 53 application generates a ``GL_INVALID_ENUM`` error, a corresponding 54 error message indicating where the error occurred, and possibly why, 55 will be printed to stderr. For release builds, :envvar:`MESA_DEBUG` 56 defaults to off (no debug output). :envvar:`MESA_DEBUG` accepts the 57 following comma-separated list of named flags, which adds extra 58 behavior to just set :envvar:`MESA_DEBUG` to ``1``: 59 60 ``silent`` 61 turn off debug messages. Only useful for debug builds. 62 ``flush`` 63 flush after each drawing command 64 ``incomplete_tex`` 65 extra debug messages when a texture is incomplete 66 ``incomplete_fbo`` 67 extra debug messages when a FBO is incomplete 68 ``context`` 69 create a debug context (see ``GLX_CONTEXT_DEBUG_BIT_ARB``) and 70 print error and performance messages to stderr (or 71 ``MESA_LOG_FILE``). 72 73.. envvar:: MESA_PROCESS_NAME 74 75 if set, overrides the process name string used internally for various 76 purposes (e.g. for driconf option matching, logging, artifact storage, 77 etc.). 78 79.. envvar:: MESA_LOG_FILE 80 81 specifies a file name for logging all errors, warnings, etc., rather 82 than stderr 83 84.. envvar:: MESA_EXTENSION_OVERRIDE 85 86 can be used to enable/disable extensions. A value such as 87 ``GL_EXT_foo -GL_EXT_bar`` will enable the ``GL_EXT_foo`` extension 88 and disable the ``GL_EXT_bar`` extension. Note that this will override 89 extensions override configured using driconf. 90 91.. envvar:: MESA_EXTENSION_MAX_YEAR 92 93 The ``GL_EXTENSIONS`` string returned by Mesa is sorted by extension 94 year. If this variable is set to year X, only extensions defined on 95 or before year X will be reported. This is to work-around a bug in 96 some games where the extension string is copied into a fixed-size 97 buffer without truncating. If the extension string is too long, the 98 buffer overrun can cause the game to crash. This is a work-around for 99 that. 100 101.. envvar:: MESA_GL_VERSION_OVERRIDE 102 103 changes the value returned by ``glGetString(GL_VERSION)`` and 104 possibly the GL API type. 105 106 - The format should be ``MAJOR.MINOR[FC|COMPAT]`` 107 - ``FC`` is an optional suffix that indicates a forward compatible 108 context. This is only valid for versions >= 3.0. 109 - ``COMPAT`` is an optional suffix that indicates a compatibility 110 context or :ext:`GL_ARB_compatibility` support. This is only valid 111 for versions >= 3.1. 112 - GL versions <= 3.0 are set to a compatibility (non-Core) profile 113 - GL versions = 3.1, depending on the driver, it may or may not have 114 the :ext:`GL_ARB_compatibility` extension enabled. 115 - GL versions >= 3.2 are set to a Core profile 116 - Examples: 117 118 ``2.1`` 119 select a compatibility (non-Core) profile with GL version 2.1. 120 ``3.0`` 121 select a compatibility (non-Core) profile with GL version 3.0. 122 ``3.0FC`` 123 select a Core+Forward Compatible profile with GL version 3.0. 124 ``3.1`` 125 select GL version 3.1 with :ext:`GL_ARB_compatibility` enabled 126 per the driver default. 127 ``3.1FC`` 128 select GL version 3.1 with forward compatibility and 129 :ext:`GL_ARB_compatibility` disabled. 130 ``3.1COMPAT`` 131 select GL version 3.1 with :ext:`GL_ARB_compatibility` enabled. 132 ``X.Y`` 133 override GL version to X.Y without changing the profile. 134 ``X.YFC`` 135 select a Core+Forward Compatible profile with GL version X.Y. 136 ``X.YCOMPAT`` 137 select a Compatibility profile with GL version X.Y. 138 139 - Mesa may not really implement all the features of the given 140 version. (for developers only) 141 142.. envvar:: MESA_GLES_VERSION_OVERRIDE 143 144 changes the value returned by ``glGetString(GL_VERSION)`` for OpenGL 145 ES. 146 147 - The format should be ``MAJOR.MINOR`` 148 - Examples: ``2.0``, ``3.0``, ``3.1`` 149 - Mesa may not really implement all the features of the given 150 version. (for developers only) 151 152.. envvar:: MESA_GLSL_VERSION_OVERRIDE 153 154 changes the value returned by 155 ``glGetString(GL_SHADING_LANGUAGE_VERSION)``. Valid values are 156 integers, such as ``130``. Mesa will not really implement all the 157 features of the given language version if it's higher than what's 158 normally reported. (for developers only) 159 160.. envvar:: MESA_DRICONF_EXECUTABLE_OVERRIDE 161 162 if set, overrides the "executable" string used specifically for driconf 163 option matching. This takes higher precedence over more general process 164 name override (e.g. MESA_PROCESS_NAME). 165 166.. envvar:: MESA_SHADER_CACHE_DISABLE 167 168 if set to ``true``, disables the on-disk shader cache. If set to 169 ``false``, enables the on-disk shader cache when it is disabled by 170 default. Note that EGL_ANDROID_blob_cache is still enabled even 171 if on-disk shader cache is disabled. 172 173.. envvar:: MESA_SHADER_CACHE_MAX_SIZE 174 175 if set, determines the maximum size of the on-disk cache of compiled 176 shader programs. Should be set to a number optionally followed by 177 ``K``, ``M``, or ``G`` to specify a size in kilobytes, megabytes, or 178 gigabytes. By default, gigabytes will be assumed. And if unset, a 179 maximum size of 1GB will be used. 180 181 .. note:: 182 183 A separate cache might be created for each architecture that Mesa is 184 installed for on your system. For example under the default settings 185 you may end up with a 1GB cache for x86_64 and another 1GB cache for 186 i386. 187 188.. envvar:: MESA_SHADER_CACHE_DIR 189 190 if set, determines the directory to be used for the on-disk cache of 191 compiled shader programs. If this variable is not set, then the cache 192 will be stored in ``$XDG_CACHE_HOME/mesa_shader_cache`` (if that 193 variable is set), or else within ``.cache/mesa_shader_cache`` within 194 the user's home directory. 195 196.. envvar:: MESA_SHADER_CACHE_SHOW_STATS 197 198 if set to ``true``, keeps hit/miss statistics for the shader cache. 199 These statistics are printed when the app terminates. 200 201.. envvar:: MESA_DISK_CACHE_SINGLE_FILE 202 203 if set to 1, enables the single file Fossilize DB on-disk shader 204 cache implementation instead of the default multi-file cache 205 implementation. This implementation reduces the overall disk usage by 206 the shader cache and also allows for loading of precompiled cache 207 DBs via :envvar:`MESA_DISK_CACHE_READ_ONLY_FOZ_DBS` or 208 :envvar:`MESA_DISK_CACHE_READ_ONLY_FOZ_DBS_DYNAMIC_LIST`. This 209 implementation does not support cache size limits via 210 :envvar:`MESA_SHADER_CACHE_MAX_SIZE`. If 211 :envvar:`MESA_SHADER_CACHE_DIR` is not set, the cache will be stored 212 in ``$XDG_CACHE_HOME/mesa_shader_cache_sf`` (if that variable is set) 213 or else within ``.cache/mesa_shader_cache_sf`` within the user's home 214 directory. 215 216.. envvar:: MESA_DISK_CACHE_READ_ONLY_FOZ_DBS 217 218 if set with :envvar:`MESA_DISK_CACHE_SINGLE_FILE` enabled, references 219 a string of comma separated file paths to read only Fossilize DB 220 shader caches for loading at initialization. The file paths are 221 relative to the cache directory and do not include suffixes, 222 referencing both the cache DB and its index file. E.g. 223 ``MESA_DISK_CACHE_SINGLE_FILE=filename1`` refers to ``filename1.foz`` 224 and ``filename1_idx.foz``. A limit of 8 DBs can be loaded and this limit 225 is shared with :envvar:`MESA_DISK_CACHE_READ_ONLY_FOZ_DBS_DYNAMIC_LIST.` 226 227.. envvar:: MESA_DISK_CACHE_DATABASE 228 229 if set to 1, enables the Mesa-DB single file on-disk shader cache 230 implementation instead of the default multi-file cache implementation. 231 Like :envvar:`MESA_DISK_CACHE_SINGLE_FILE`, Mesa-DB reduces overall 232 disk usage but Mesa-DB supports cache size limits via 233 :envvar:`MESA_SHADER_CACHE_MAX_SIZE`. If 234 :envvar:`MESA_SHADER_CACHE_DIR` is not set, the cache will be stored 235 in ``$XDG_CACHE_HOME/mesa_shader_cache_db`` (if that variable is set) 236 or else within ``.cache/mesa_shader_cache_db`` within the user's home 237 directory. 238 239.. envvar:: MESA_DISK_CACHE_DATABASE_NUM_PARTS 240 241 specifies number of mesa-db cache parts, default is 50. 242 243.. envvar:: MESA_DISK_CACHE_DATABASE_EVICTION_SCORE_2X_PERIOD 244 245 Mesa-DB cache eviction algorithm calculates weighted score for the 246 cache items. The weight is doubled based on the last access time of 247 cache entry. By default period of weight doubling is set to one month. 248 Period value is given in seconds. 249 250.. envvar:: MESA_DISK_CACHE_READ_ONLY_FOZ_DBS_DYNAMIC_LIST 251 252 if set with :envvar:`MESA_DISK_CACHE_SINGLE_FILE` enabled, references 253 a text file that contains a new-line separated list of read only 254 Fossilize DB shader caches to load. The list file is modifiable at 255 runtime to allow for loading read only caches after initialization 256 unlike :envvar:`MESA_DISK_CACHE_READ_ONLY_FOZ_DBS`. This variable 257 takes an absolute path to the list file. The list file must exist at 258 initialization for updating to occur. Cache files in the list take 259 relative paths to the current cache directory like 260 :envvar:`MESA_DISK_CACHE_READ_ONLY_FOZ_DBS`. A limit of 8 DBs can be 261 loaded and this limit is shared with 262 :envvar:`MESA_DISK_CACHE_READ_ONLY_FOZ_DBS`. 263 264.. envvar:: MESA_DISK_CACHE_COMBINE_RW_WITH_RO_FOZ 265 266 if set to 1, enables simultaneous use of :abbr:`RW (read-write)` and 267 :abbr:`RW (read-write)` Fossilize DB caches. At first, data will be 268 retrieved from the RO Fossilize cache. If data isn't found in the RO 269 cache, then it will be retrieved from the RW cache. 270 271.. envvar:: MESA_GLSL 272 273 :ref:`shading language compiler options <envvars>` 274 275.. envvar:: MESA_NO_MINMAX_CACHE 276 277 when set, the minmax index cache is globally disabled. 278 279.. envvar:: MESA_SHADER_CAPTURE_PATH 280 281 see :ref:`Capturing Shaders <capture>` 282 283.. envvar:: MESA_SHADER_DUMP_PATH 284 285 see :ref:`Experimenting with Shader Replacements <replacement>` 286 287.. envvar:: MESA_SHADER_READ_PATH 288 289 see :ref:`Experimenting with Shader Replacements <replacement>` 290 291.. envvar:: MESA_VK_VERSION_OVERRIDE 292 293 changes the Vulkan physical device version as returned in 294 ``VkPhysicalDeviceProperties::apiVersion``. 295 296 - The format should be ``MAJOR.MINOR[.PATCH]`` 297 - This will not let you force a version higher than the driver's 298 instance version as advertised by ``vkEnumerateInstanceVersion`` 299 - This can be very useful for debugging but some features may not be 300 implemented correctly. (For developers only) 301 302.. envvar:: MESA_VK_WSI_PRESENT_MODE 303 304 overrides the WSI present mode clients specify in 305 ``VkSwapchainCreateInfoKHR::presentMode``. Values can be ``fifo``, 306 ``relaxed``, ``mailbox`` or ``immediate``. 307 308.. envvar:: MESA_VK_WSI_HEADLESS_SWAPCHAIN 309 310 Forces all swapchains to be headless (no rendering will be display 311 in the swapchain's window). 312 313.. envvar:: MESA_VK_ABORT_ON_DEVICE_LOSS 314 315 causes the Vulkan driver to call abort() immediately after detecting a 316 lost device. This is extremely useful when testing as it prevents the 317 test suite from continuing on with a lost device. 318 319.. envvar:: MESA_VK_ENABLE_SUBMIT_THREAD 320 321 for Vulkan drivers which support real timeline semaphores, this forces 322 them to use a submit thread from the beginning, regardless of whether or 323 not they ever see a wait-before-signal condition. 324 325.. envvar:: MESA_VK_DEVICE_SELECT_DEBUG 326 327 print debug info about device selection decision-making 328 329.. envvar:: MESA_VK_TRACE 330 331 A comma-separated list of trace types used for offline analysis. The 332 option names are equal to the file extension. Traces are dumped into ``/tmp``. 333 Captures can be triggered by pressing ``F1`` with the application window 334 focused (Currently X11 only) or via :envvar:`MESA_VK_TRACE_FRAME` and 335 :envvar:`MESA_VK_TRACE_TRIGGER`. 336 337 .. list-table:: 338 :header-rows: 1 339 340 * - File extension 341 - Offline analysis tool 342 - Supported drivers 343 * - ``rmv`` 344 - Radeon Memory Visualizer 345 - ``RADV`` 346 * - ``rgp`` 347 - Radeon GPU Profiler 348 - ``RADV`` 349 * - ``rra`` 350 - Radeon Raytracing Analyzer 351 - ``RADV`` 352 * - ``ctxroll`` 353 - Context rolls 354 - ``RADV`` 355 356 - Creating RMV captures requires the ``scripts/setup.sh`` script in the 357 Radeon Developer Tools folder to be run beforehand 358 359.. envvar:: MESA_VK_TRACE_FRAME 360 361 Specifies a frame index at which a trace capture is automatically triggered. 362 363.. envvar:: MESA_VK_TRACE_TRIGGER 364 365 Specifies a trigger file. Creating the file triggers the capture. (e.g. 366 ``export MESA_VK_TRACE_TRIGGER=/tmp/trigger`` and then ``touch /tmp/trigger``) 367 368.. envvar:: MESA_LOADER_DRIVER_OVERRIDE 369 370 chooses a different driver binary such as ``etnaviv`` or ``zink``. 371 372.. envvar:: DRI_PRIME_DEBUG 373 374 print debug info about device selection decision-making 375 376.. envvar:: DRI_PRIME 377 378 the default GPU is the one used by Wayland/Xorg or the one connected to a 379 display. This variable allows to select a different GPU. It applies to OpenGL 380 and Vulkan (in this case "select" means the GPU will be first in the reported 381 physical devices list). The supported syntaxes are: 382 383 - ``DRI_PRIME=N``: selects the Nth non-default GPU (N > 0). 384 - ``DRI_PRIME=pci-0000_02_00_0``: selects the GPU connected to this PCIe bus 385 - ``DRI_PRIME=vendor_id:device_id``: selects the first GPU matching these ids. 386 387 For Vulkan it's possible to append ``!``, in which case only the selected GPU 388 will be exposed to the application (eg: DRI_PRIME=1!). 389 390 .. note:: 391 392 ``lspci -nn | grep VGA`` can be used to know the PCIe bus or ids to use. 393 394.. envvar:: DRIRC_CONFIGDIR 395 396 If set, overrides the global search-directories used when searching for 397 drirc config files. The user-local one will still be used. Mostly useful for 398 internal debugging. 399 400NIR passes environment variables 401-------------------------------- 402 403The following are only applicable for drivers that uses NIR, as they 404modify the behavior for the common ``NIR_PASS`` and ``NIR_PASS_V`` macros, 405that wrap calls to NIR lowering/optimizations. 406 407.. envvar:: NIR_DEBUG 408 409 a comma-separated list of debug options to apply to NIR 410 shaders. Use ``NIR_DEBUG=help`` to print a list of available options. 411 412.. envvar:: NIR_SKIP 413 414 a comma-separated list of optimization/lowering passes to skip. 415 416Mesa Xlib driver environment variables 417-------------------------------------- 418 419The following are only applicable to the Mesa Xlib software driver. See 420the :doc:`Xlib software driver page <xlibdriver>` for details. 421 422.. envvar:: MESA_RGB_VISUAL 423 424 specifies the X visual and depth for RGB mode 425 426.. envvar:: MESA_BACK_BUFFER 427 428 specifies how to implement the back color buffer, either ``pixmap`` 429 or ``ximage`` 430 431.. envvar:: MESA_XSYNC 432 433 enable synchronous X behavior (for debugging only) 434 435.. envvar:: MESA_GLX_FORCE_ALPHA 436 437 if set, forces RGB windows to have an alpha channel. 438 439.. envvar:: MESA_GLX_DEPTH_BITS 440 441 specifies default number of bits for depth buffer. 442 443.. envvar:: MESA_GLX_ALPHA_BITS 444 445 specifies default number of bits for alpha channel. 446 447Mesa WGL driver environment variables 448------------------------------------- 449 450The following are only applicable to the Mesa WGL driver, which is in use 451on Windows. 452 453.. envvar:: WGL_FORCE_MSAA 454 455 if set to a positive value, specifies the number of MSAA samples to 456 force when choosing the display configuration. 457 458.. envvar:: WGL_DISABLE_ERROR_DIALOGS 459 460 if set to 1, true or yes, disables Win32 error dialogs. Useful for 461 automated test-runs. 462 463Intel driver environment variables 464---------------------------------------------------- 465 466.. envvar:: ANV_NO_GPL 467 468 If set to 1, true, or yes, then VK_EXT_graphics_pipeline_library 469 will be disabled. 470 471.. envvar:: INTEL_BLACKHOLE_DEFAULT 472 473 if set to 1, true or yes, then the OpenGL implementation will 474 default ``GL_BLACKHOLE_RENDER_INTEL`` to true, thus disabling any 475 rendering. 476 477.. envvar:: INTEL_COMPUTE_CLASS 478 479 If set to 1, true or yes, then I915_ENGINE_CLASS_COMPUTE will be 480 supported. For OpenGL, iris will attempt to use a compute engine 481 for compute dispatches if one is detected. For Vulkan, anvil will 482 advertise support for a compute queue if a compute engine is 483 detected. 484 485.. envvar:: INTEL_COPY_CLASS 486 487 If set to 1, true or yes, then I915_ENGINE_CLASS_COPY will be 488 supported. For Vulkan, anvil will advertise support for a transfer 489 queue if a copy engine is detected. 490 491.. envvar:: INTEL_DEBUG 492 493 a comma-separated list of named flags, which do various things: 494 495 ``ann`` 496 annotate IR in assembly dumps 497 ``bat`` 498 emit batch information. Can control in which frames batches 499 get dumped using ``INTEL_DEBUG_BATCH_FRAME_*``, where 500 ``INTEL_DEBUG_BATCH_FRAME_START`` <= frame < ``INTEL_DEBUG_BATCH_FRAME_STOP`` 501 ``blit`` 502 emit messages about blit operations 503 ``blorp`` 504 emit messages about the blorp operations (blits & clears) 505 ``buf`` 506 emit messages about buffer objects 507 ``bt`` 508 emit messages binding tables 509 ``capture-all`` 510 flag all buffers to be captured by the kernel driver when 511 generating an error stage after a GPU hang 512 ``clip`` 513 emit messages about the clip unit (for old gens, includes the CLIP 514 program) 515 ``color`` 516 use color in output 517 ``cs`` 518 dump shader assembly for compute shaders 519 ``do32`` 520 generate compute shader SIMD32 programs even if workgroup size 521 doesn't exceed the SIMD16 limit 522 ``draw_bkp`` 523 Add semaphore wait before/after draw call count. 524 ``INTEL_DEBUG_BKP_BEFORE_DRAW_COUNT`` or 525 ``INTEL_DEBUG_BKP_AFTER_DRAW_COUNT`` can control draw call number. 526 To make test wait forever, we need to set preempt_timeout_ms and 527 i915.enable_hangcheck to zero. 528 ``fall`` 529 emit messages about performance issues (same as ``perf``) 530 ``fs`` 531 dump shader assembly for fragment shaders 532 ``gs`` 533 dump shader assembly for geometry shaders 534 ``heaps`` 535 print information about the driver's heaps (Anv only) 536 ``hex`` 537 print instruction hex dump with the disassembly 538 ``l3`` 539 emit messages about the new L3 state during transitions 540 ``mesh`` 541 dump shader assembly for mesh shaders 542 ``no8`` 543 don't generate SIMD8 fragment shader 544 ``no16`` 545 suppress generation of 16-wide fragment shaders. useful for 546 debugging broken shaders 547 ``no32`` 548 suppress generation of 32-wide fragment shaders. useful for 549 debugging broken shaders 550 ``no-oaconfig`` 551 disable HW performance metric configuration, and anything 552 related to i915-perf (useful when running on simulation) 553 ``nocompact`` 554 disable instruction compaction 555 ``nodualobj`` 556 suppress generation of dual-object geometry shader code 557 ``nofc`` 558 disable fast clears 559 ``noccs`` 560 disable lossless color compression 561 ``optimizer`` 562 dump shader assembly to files at each optimization pass and 563 iteration that make progress 564 ``pc`` 565 emit messages about PIPE_CONTROL instruction usage 566 ``perf`` 567 emit messages about performance issues 568 ``perfmon`` 569 emit messages about :ext:`GL_AMD_performance_monitor` 570 ``perf-symbol-names`` 571 use performance counter symbols instead of the counter name 572 (counter symbols are like variable names, it's sometimes easier 573 to work with when you have lots of metrics to collect) 574 ``reemit`` 575 mark all state dirty on each draw call 576 ``rt`` 577 dump shader assembly for ray tracing shaders 578 ``sf`` 579 emit messages about the strips & fans unit (for old gens, includes 580 the SF program) 581 ``soft64`` 582 enable implementation of software 64bit floating point support 583 ``sparse`` 584 dump usage of sparse resources 585 ``spill_fs`` 586 force spilling of all registers in the scalar backend (useful to 587 debug spilling code) 588 ``spill_vec4`` 589 force spilling of all registers in the vec4 backend (useful to 590 debug spilling code) 591 ``stall`` 592 inserts a stall on the GPU after each draw/dispatch command to 593 wait for it to finish before starting any new work. 594 ``submit`` 595 emit batchbuffer usage statistics 596 ``sync`` 597 after sending each batch, wait on the CPU for that batch to 598 finish rendering 599 ``swsb-stall`` 600 Insert sync NOP after each instruction. This is only valid for Gfx12+. 601 ``task`` 602 dump shader assembly for task shaders 603 ``tcs`` 604 dump shader assembly for tessellation control shaders 605 ``tcs8`` 606 force usage of 8-patches tessellation control shaders (only 607 for gfx 9-11) 608 ``tes`` 609 dump shader assembly for tessellation evaluation shaders 610 ``tex`` 611 emit messages about textures. 612 ``urb`` 613 emit messages about URB setup 614 ``vs`` 615 dump shader assembly for vertex shaders 616 ``wm`` 617 dump shader assembly for fragment shaders (same as ``fs``) 618 619.. envvar:: INTEL_DECODE 620 621 a comma-separated list of enable/disable flags configuring the 622 output produced by ``INTEL_DEBUG=bat`` (use with 623 ``INTEL_DECODE=+color,-floats``) : 624 625 ``color`` 626 print colored output 627 628 ``floats`` 629 try to decode floating point data in buffers 630 631 ``full`` 632 print additional custom information for instructions (usually 633 pulling more information by inspecting memory) 634 635 ``offsets`` 636 print offsets of instructions 637 638.. envvar:: INTEL_EXTENDED_METRICS 639 640 By default, only a standard set of gpu metrics are advertised. This 641 reduces time to collect metrics and hides infrequently used metrics. 642 To enable all metrics, set value to 1. 643 644.. envvar:: INTEL_MEASURE 645 646 Collects GPU timestamps over common intervals, and generates a CSV report 647 to show how long rendering took. The overhead of collection is limited to 648 the flushing that is required at the interval boundaries for accurate 649 timestamps. By default, timing data is sent to ``stderr``. To direct output 650 to a file: 651 652 ``INTEL_MEASURE=file=/tmp/measure.csv {workload}`` 653 654 To begin capturing timestamps at a particular frame: 655 656 ``INTEL_MEASURE=file=/tmp/measure.csv,start=15 {workload}`` 657 658 To capture only 23 frames: 659 660 ``INTEL_MEASURE=count=23 {workload}`` 661 662 To capture frames 15-37, stopping before frame 38: 663 664 ``INTEL_MEASURE=start=15,count=23 {workload}`` 665 666 Designate an asynchronous control file with: 667 668 ``INTEL_MEASURE=control=path/to/control.fifo {workload}`` 669 670 As the workload runs, enable capture for 5 frames with: 671 672 ``$ echo 5 > path/to/control.fifo`` 673 674 Enable unbounded capture: 675 676 ``$ echo -1 > path/to/control.fifo`` 677 678 and disable with: 679 680 ``$ echo 0 > path/to/control.fifo`` 681 682 Select the boundaries of each snapshot with: 683 684 ``INTEL_MEASURE=draw`` 685 Collects timings for every render (DEFAULT) 686 687 ``INTEL_MEASURE=rt`` 688 Collects timings when the render target changes 689 690 ``INTEL_MEASURE=batch`` 691 Collects timings when batches are submitted 692 693 ``INTEL_MEASURE=frame`` 694 Collects timings at frame boundaries 695 696 With ``INTEL_MEASURE=interval=5``, the duration of 5 events will be 697 combined into a single record in the output. When possible, a single 698 start and end event will be submitted to the GPU to minimize 699 stalling. Combined events will not span batches, except in 700 the case of ``INTEL_MEASURE=frame``. 701 702 Collect CPU timestamps instead of GPU timestamps. Prints results 703 immediately instead of waiting for GPU execution. Useful when used 704 with interactive debug to know which frame, or where in frame, you 705 are currently in. 706 707 ``INTEL_MEASURE=cpu {workload}`` 708 709.. envvar:: INTEL_MODIFIER_OVERRIDE 710 711 if set, determines the single DRM modifier reported back to (Vulkan) 712 applications, in order to make selecting modifier deterministic 713 between Vulkan driver and applications. The value can be one of the 714 supported modifiers on a platform, but other values are also acceptable 715 for debug purposes. 716 717.. envvar:: INTEL_NO_HW 718 719 if set to 1, true or yes, prevents batches from being submitted to the 720 hardware. This is useful for debugging hangs, etc. 721 722.. envvar:: INTEL_PRECISE_TRIG 723 724 if set to 1, true or yes, then the driver prefers accuracy over 725 performance in trig functions. 726 727.. envvar:: INTEL_SHADER_OPTIMIZER_PATH 728 729 if set, determines the directory to be used for overriding shader 730 assembly. The binaries with custom assembly should be placed in 731 this folder and have a name formatted as ``sha1_of_assembly.bin``. 732 The SHA-1 of a shader assembly is printed when assembly is dumped via 733 corresponding :envvar:`INTEL_DEBUG` flag (e.g. ``vs`` for vertex shader). 734 A binary could be generated from a dumped assembly by ``i965_asm``. 735 For :envvar:`INTEL_SHADER_ASM_READ_PATH` to work it is necessary to enable 736 dumping of corresponding shader stages via :envvar:`INTEL_DEBUG`. 737 It is advised to use ``nocompact`` flag of :envvar:`INTEL_DEBUG` when 738 dumping and overriding shader assemblies. 739 The success of assembly override would be signified by "Successfully 740 overrode shader with sha1 <SHA-1>" in stderr replacing the original 741 assembly. 742 743.. envvar:: INTEL_SHADER_ASM_READ_PATH 744 745 if set, determines the directory to be used for overriding shader 746 assembly. The binaries with custom assembly should be placed in 747 this folder and have a name formatted as ``sha1_of_assembly.bin``. 748 The SHA-1 of a shader assembly is printed when assembly is dumped via 749 corresponding :envvar:`INTEL_DEBUG` flag (e.g. ``vs`` for vertex shader). 750 A binary could be generated from a dumped assembly by ``i965_asm``. 751 For :envvar:`INTEL_SHADER_ASM_READ_PATH` to work it is necessary to enable 752 dumping of corresponding shader stages via :envvar:`INTEL_DEBUG`. 753 It is advised to use ``nocompact`` flag of :envvar:`INTEL_DEBUG` when 754 dumping and overriding shader assemblies. 755 The success of assembly override would be signified by "Successfully 756 overrode shader with sha1 <SHA-1>" in stderr replacing the original 757 assembly. 758 759.. envvar:: INTEL_SHADER_BIN_DUMP_PATH 760 761 if set, determines the directory to which the compiled shaders will be 762 dumped. They will be dumped as ``sha1_of_assembly.bin``, where the sha1 763 values will be the same as can be found in the :envvar:`INTEL_DEBUG` 764 output, and can be used for :envvar:`INTEL_SHADER_ASM_READ_PATH` input. 765 766 .. note:: 767 Unlike the text form of shader dumping, :envvar:`INTEL_DEBUG` 768 does not affect on the list of shaders to dump. All generated shaders 769 are always dumped if :envvar:`INTEL_SHADER_BIN_DUMP_PATH` variable is 770 set. 771 772.. envvar:: INTEL_SIMD_DEBUG 773 774 a comma-separated list of named flags, which control simd dispatch widths: 775 776 ``fs8`` 777 allow generation of SIMD8 fragment shader 778 ``fs16`` 779 allow generation of SIMD16 fragment shader 780 ``fs32`` 781 allow generation of SIMD32 fragment shader 782 ``cs8`` 783 allow generation of SIMD8 compute shader 784 ``cs16`` 785 allow generation of SIMD16 compute shader 786 ``cs32`` 787 allow generation of SIMD32 compute shader 788 ``ts8`` 789 allow generation of SIMD8 task shader 790 ``ts16`` 791 allow generation of SIMD16 task shader 792 ``ts32`` 793 allow generation of SIMD32 task shader 794 ``ms8`` 795 allow generation of SIMD8 mesh shader 796 ``ms16`` 797 allow generation of SIMD16 mesh shader 798 ``ms32`` 799 allow generation of SIMD32 mesh shader 800 ``rt8`` 801 allow generation of SIMD8 ray-tracing shader 802 ``rt16`` 803 allow generation of SIMD16 ray-tracing shader 804 ``rt32`` 805 allow generation of SIMD32 ray-tracing shader 806 807 If none of widths for particular shader stage was specified, then all 808 widths are allowed. 809 810DRI environment variables 811------------------------- 812 813.. envvar:: DRI_NO_MSAA 814 815 disable MSAA for GLX/EGL MSAA visuals 816 817 818Vulkan mesa device select layer environment variables 819----------------------------------------------------- 820 821.. envvar:: MESA_VK_DEVICE_SELECT 822 823 when set to "list" prints the list of devices. 824 when set to "vid:did" number from PCI device. That PCI device is 825 selected as default. The default device is returned as the first 826 device in vkEnumeratePhysicalDevices API. 827 Using "vid:did!" will have the same effect as using the 828 ``MESA_VK_DEVICE_SELECT_FORCE_DEFAULT_DEVICE`` variable. 829 830.. envvar:: MESA_VK_DEVICE_SELECT_FORCE_DEFAULT_DEVICE 831 832 when set to 1, the device identified as default will be the only 833 one returned in vkEnumeratePhysicalDevices API. 834 835 836EGL environment variables 837------------------------- 838 839Mesa EGL supports different sets of environment variables. See the 840:doc:`Mesa EGL <egl>` page for the details. 841 842Gallium environment variables 843----------------------------- 844 845.. envvar:: GALLIUM_HUD 846 847 draws various information on the screen, like framerate, CPU load, 848 driver statistics, performance counters, etc. Set 849 :envvar:`GALLIUM_HUD` to ``help`` and run e.g. ``glxgears`` for more info. 850 851.. envvar:: GALLIUM_HUD_PERIOD 852 853 sets the HUD update rate in seconds (float). Use zero to update every 854 frame. The default period is 1/2 second. 855 856.. envvar:: GALLIUM_HUD_VISIBLE 857 858 control default visibility, defaults to true. 859 860.. envvar:: GALLIUM_HUD_OPACITY 861 862 control background opacity as an integer percentage (1-100), defaults to 66%. 863 864.. envvar:: GALLIUM_HUD_TOGGLE_SIGNAL 865 866 toggle visibility via user specified signal. Especially useful to 867 toggle HUD at specific points of application and disable for 868 unencumbered viewing the rest of the time. For example, set 869 :envvar:`GALLIUM_HUD_VISIBLE` to ``false`` and 870 :envvar:`GALLIUM_HUD_TOGGLE_SIGNAL` to ``10`` (``SIGUSR1``). Use 871 ``kill -10 <pid>`` to toggle the HUD as desired. 872 873.. envvar:: GALLIUM_HUD_SCALE 874 875 Scale HUD by an integer factor, for high DPI displays. Default is 1. 876 877.. envvar:: GALLIUM_HUD_ROTATION 878 879 Rotate the HUD by an integer number of degrees, the specified value must be 880 a multiple of 90. Default is 0. 881 882.. envvar:: GALLIUM_HUD_DUMP_DIR 883 884 specifies a directory for writing the displayed HUD values into 885 files. 886 887.. envvar:: GALLIUM_DRIVER 888 889 useful in combination with :envvar:`LIBGL_ALWAYS_SOFTWARE` = ``true`` for 890 choosing one of the software renderers ``softpipe`` or ``llvmpipe``. 891 892.. envvar:: GALLIUM_LOG_FILE 893 894 specifies a file for logging all errors, warnings, etc. rather than 895 stderr. 896 897.. envvar:: GALLIUM_PIPE_SEARCH_DIR 898 899 specifies an alternate search directory for pipe-loader which overrides 900 the compile-time path based on the install location. 901 902.. envvar:: GALLIUM_PRINT_OPTIONS 903 904 if non-zero, print all the Gallium environment variables which are 905 used, and their current values. 906 907.. envvar:: GALLIUM_TRACE 908 909 If set, this variable will cause the :ref:`trace` output to be written to the 910 specified file. Paths may be relative or absolute; relative paths are relative 911 to the working directory. For example, setting it to "trace.xml" will cause 912 the trace to be written to a file of the same name in the working directory. 913 914.. envvar:: GALLIUM_TRACE_TC 915 916 If enabled while :ref:`trace` is active, this variable specifies that the threaded context 917 should be traced for drivers which implement it. By default, the driver thread is traced, 918 which will include any reordering of the command stream from threaded context. 919 920.. envvar:: GALLIUM_TRACE_TRIGGER 921 922 If set while :ref:`trace` is active, this variable specifies a filename to monitor. 923 Once the file exists (e.g., from the user running 'touch /path/to/file'), a single 924 frame will be recorded into the trace output. 925 Paths may be relative or absolute; relative paths are relative to the working directory. 926 927.. envvar:: GALLIUM_DUMP_CPU 928 929 if non-zero, print information about the CPU on start-up 930 931.. envvar:: TGSI_PRINT_SANITY 932 933 if set, do extra sanity checking on TGSI shaders and print any errors 934 to stderr. 935 936.. envvar:: DRAW_FSE 937 938 Enable fetch-shade-emit middle-end even though its not correct (e.g. 939 for Softpipe) 940 941.. envvar:: DRAW_NO_FSE 942 943 Disable fetch-shade-emit middle-end even when it is correct 944 945.. envvar:: DRAW_USE_LLVM 946 947 if set to zero, the draw module will not use LLVM to execute shaders, 948 vertex fetch, etc. 949 950.. envvar:: ST_DEBUG 951 952 controls debug output from the Mesa/Gallium state tracker. Setting to 953 ``tgsi``, for example, will print all the TGSI shaders. See 954 :file:`src/mesa/state_tracker/st_debug.c` for other options. 955 956.. envvar:: GALLIUM_OVERRIDE_CPU_CAPS 957 958 Override CPU capabilities for LLVMpipe and Softpipe, possible values for x86: 959 ``nosse`` 960 ``sse`` 961 ``sse2`` 962 ``sse3`` 963 ``ssse3`` 964 ``sse4.1`` 965 ``avx`` 966 967Clover environment variables 968---------------------------- 969 970.. envvar:: CLOVER_DEVICE_TYPE 971 972 allows to overwrite the device type of devices. Possible values are 973 ``accelerator``, ``cpu``, ``custom`` and ``gpu`` 974 975.. envvar:: CLOVER_DEVICE_VERSION_OVERRIDE 976 977 overwrites the auto detected OpenCL version of a device. Possible values: 978 ``1.0`` 979 ``1.1`` 980 ``1.2`` 981 ``2.0`` 982 ``2.1`` 983 ``2.2`` 984 ``3.0`` 985 986.. envvar:: CLOVER_DEVICE_CLC_VERSION_OVERRIDE 987 988 overwrites the auto detected CLC version. Possible values: 989 ``1.0`` 990 ``1.1`` 991 ``1.2`` 992 ``2.0`` 993 ``2.1`` 994 ``2.2`` 995 ``3.0`` 996 997.. envvar:: CLOVER_EXTRA_BUILD_OPTIONS 998 999 allows specifying additional compiler and linker options. Specified 1000 options are appended after the options set by the OpenCL program in 1001 ``clBuildProgram``. 1002 1003.. envvar:: CLOVER_EXTRA_COMPILE_OPTIONS 1004 1005 allows specifying additional compiler options. Specified options are 1006 appended after the options set by the OpenCL program in 1007 ``clCompileProgram``. 1008 1009.. envvar:: CLOVER_EXTRA_LINK_OPTIONS 1010 1011 allows specifying additional linker options. Specified options are 1012 appended after the options set by the OpenCL program in 1013 ``clLinkProgram``. 1014 1015.. _rusticl-env-var: 1016 1017.. envvar:: IRIS_ENABLE_CLOVER 1018 1019 allows to enable experimental Clover NIR support with the iris driver if 1020 set to 1 or true. 1021 1022Rusticl environment variables 1023----------------------------- 1024 1025.. envvar:: RUSTICL_DEVICE_TYPE 1026 1027 allows to overwrite the device type of devices. Possible values are 1028 ``accelerator``, ``cpu``, ``custom`` and ``gpu`` 1029 1030.. envvar:: RUSTICL_CL_VERSION 1031 1032 overwrites the auto detected OpenCL version of all devices. Specified as 1033 ``major.minor``. 1034 1035.. envvar:: RUSTICL_ENABLE 1036 1037 a comma-separated list of drivers to enable CL on. An optional list of 1038 comma-separated integers can be passed per driver to specify which devices 1039 to enable. Examples: 1040 1041 - ``RUSTICL_ENABLE=iris`` (enables all iris devices) 1042 - ``RUSTICL_ENABLE=iris:1,radeonsi:0,2`` (enables second iris and first 1043 and third radeonsi device) 1044 1045 Supported drivers (decent support with maybe a few conformance issues or bugs): 1046 ``iris``, 1047 ``llvmpipe``, 1048 ``nouveau``, 1049 ``panfrost``, 1050 ``radeonsi``, 1051 Experimental drivers (unknown level of support, expect conformance issues or major bugs): 1052 ``r600`` 1053 1054.. envvar:: RUSTICL_FEATURES 1055 1056 a comma-separated list of features to enable. Those are disabled by default 1057 as they might not be stable enough or break OpenCL conformance. 1058 1059 - ``fp16`` enables OpenCL half support 1060 - ``fp64`` enables OpenCL double support 1061 1062.. envvar:: RUSTICL_DEBUG 1063 1064 a comma-separated list of debug channels to enable. 1065 1066 - ``allow_invalid_spirv`` disables validation of any input SPIR-V 1067 - ``clc`` dumps all OpenCL C source being compiled 1068 - ``program`` dumps compilation logs to stderr 1069 - ``sync`` waits on the GPU to complete after every event 1070 - ``validate`` validates any internally generated SPIR-Vs, e.g. through compiling OpenCL C code 1071 1072.. _clc-env-var: 1073 1074clc environment variables 1075----------------------------- 1076 1077.. envvar:: CLC_DEBUG 1078 1079 a comma-separated list of debug channels to enable. 1080 1081 - ``dump_llvm`` Dumps all generated LLVM IRs 1082 - ``dump_spirv`` Dumps all compiled, linked and specialized SPIR-Vs 1083 - ``verbose`` Enable debug logging of clc code 1084 1085Nine frontend environment variables 1086----------------------------------- 1087 1088.. envvar:: D3D_ALWAYS_SOFTWARE 1089 1090 an integer, which forces Nine to use the CPU instead of GPU acceleration. 1091 1092.. envvar:: NINE_DEBUG 1093 1094 a comma-separated list of named flags that do debugging things. 1095 Use ``NINE_DEBUG=help`` to print a list of available options. 1096 1097.. envvar:: NINE_FF_DUMP 1098 1099 a boolean, which dumps shaders generated by a fixed function (FF). 1100 1101.. envvar:: NINE_SHADER 1102 1103 a comma-separated list of named flags, which do alternate shader handling. 1104 Use ``NINE_SHADER=help`` to print a list of available options. 1105 1106.. envvar:: NINE_QUIRKS 1107 1108 a comma-separated list of named flags that do various things. 1109 Use ``NINE_DEBUG=help`` to print a list of available options. 1110 1111Softpipe driver environment variables 1112------------------------------------- 1113 1114.. envvar:: SOFTPIPE_DEBUG 1115 1116 a comma-separated list of named flags, which do various things: 1117 1118 ``vs`` 1119 Dump vertex shader assembly to stderr 1120 ``fs`` 1121 Dump fragment shader assembly to stderr 1122 ``gs`` 1123 Dump geometry shader assembly to stderr 1124 ``cs`` 1125 Dump compute shader assembly to stderr 1126 ``no_rast`` 1127 rasterization is disabled. For profiling purposes. 1128 ``use_llvm`` 1129 the Softpipe driver will try to use LLVM JIT for vertex 1130 shading processing. 1131 1132LLVMpipe driver environment variables 1133------------------------------------- 1134 1135.. envvar:: LP_NO_RAST 1136 1137 if set LLVMpipe will no-op rasterization 1138 1139.. envvar:: LP_DEBUG 1140 1141 a comma-separated list of debug options is accepted. See the source 1142 code for details. 1143 1144.. envvar:: LP_PERF 1145 1146 a comma-separated list of options to selectively no-op various parts 1147 of the driver. See the source code for details. 1148 1149.. envvar:: LP_NUM_THREADS 1150 1151 an integer indicating how many threads to use for rendering. Zero 1152 turns off threading completely. The default value is the number of 1153 CPU cores present. 1154 1155VMware SVGA driver environment variables 1156---------------------------------------- 1157 1158.. envvar:: SVGA_FORCE_SWTNL 1159 1160 force use of software vertex transformation 1161 1162.. envvar:: SVGA_NO_SWTNL 1163 1164 don't allow software vertex transformation fallbacks (will often 1165 result in incorrect rendering). 1166 1167.. envvar:: SVGA_DEBUG 1168 1169 for dumping shaders, constant buffers, etc. See the code for details. 1170 1171.. envvar:: SVGA_EXTRA_LOGGING 1172 1173 if set, enables extra logging to the ``vmware.log`` file, such as the 1174 OpenGL program's name and command line arguments. 1175 1176.. envvar:: SVGA_NO_LOGGING 1177 1178 if set, disables logging to the ``vmware.log`` file. This is useful 1179 when using Valgrind because it otherwise crashes when initializing 1180 the host log feature. 1181 1182See the driver code for other, lesser-used variables. 1183 1184WGL environment variables 1185------------------------- 1186 1187.. envvar:: WGL_SWAP_INTERVAL 1188 1189 to set a swap interval, equivalent to calling 1190 ``wglSwapIntervalEXT()`` in an application. If this environment 1191 variable is set, application calls to ``wglSwapIntervalEXT()`` will 1192 have no effect. 1193 1194VA-API environment variables 1195---------------------------- 1196 1197.. envvar:: VAAPI_MPEG4_ENABLED 1198 1199 enable MPEG4 for VA-API, disabled by default. 1200 1201VC4 driver environment variables 1202-------------------------------- 1203 1204.. envvar:: VC4_DEBUG 1205 1206 a comma-separated list of named flags, which do various things. Use 1207 ``VC4_DEBUG=help`` to print a list of available options. 1208 1209V3D/V3DV driver environment variables 1210------------------------------------- 1211 1212.. envvar:: V3D_DEBUG 1213 1214 a comma-separated list of debug options. Use ``V3D_DEBUG=help`` to 1215 print a list of available options. 1216 1217 1218.. _radv env-vars: 1219 1220RADV driver environment variables 1221--------------------------------- 1222 1223.. envvar:: RADV_DEBUG 1224 1225 a comma-separated list of named flags, which do various things: 1226 1227 ``llvm`` 1228 enable LLVM compiler backend 1229 ``allbos`` 1230 force all allocated buffers to be referenced in submissions 1231 ``checkir`` 1232 validate the LLVM IR before LLVM compiles the shader 1233 ``epilogs`` 1234 dump fragment shader epilogs 1235 ``extra_md`` 1236 add extra information in bo metadatas to help tools (umr) 1237 ``forcecompress`` 1238 Enables DCC,FMASK,CMASK,HTILE in situations where the driver supports it 1239 but normally does not deem it beneficial. 1240 ``hang`` 1241 enable GPU hangs detection and dump a report to 1242 $HOME/radv_dumps_<pid>_<time> if a GPU hang is detected 1243 ``img`` 1244 Print image info 1245 ``info`` 1246 show GPU-related information 1247 ``invariantgeom`` 1248 Mark geometry-affecting outputs as invariant. This works around a common 1249 class of application bugs appearing as flickering. 1250 ``metashaders`` 1251 dump internal meta shaders 1252 ``noatocdithering`` 1253 disable dithering for alpha to coverage 1254 ``nobinning`` 1255 disable primitive binning 1256 ``nocache`` 1257 disable shaders cache 1258 ``nocompute`` 1259 disable compute queue 1260 ``nodcc`` 1261 disable Delta Color Compression (DCC) on images 1262 ``nodisplaydcc`` 1263 disable Delta Color Compression (DCC) on displayable images 1264 ``nodynamicbounds`` 1265 do not check OOB access for dynamic descriptors 1266 ``nofastclears`` 1267 disable fast color/depthstencil clears 1268 ``nofmask`` 1269 disable FMASK compression on MSAA images (GFX6-GFX10.3) 1270 ``nogpl`` 1271 disable VK_EXT_graphics_pipeline_library 1272 ``nogsfastlaunch2`` 1273 disable GS_FAST_LAUNCH=2 for Mesh shaders (GFX11 only) 1274 ``nohiz`` 1275 disable HIZ for depthstencil images 1276 ``noibs`` 1277 disable directly recording command buffers in GPU-visible memory 1278 ``nomemorycache`` 1279 disable memory shaders cache 1280 ``nomeshshader`` 1281 disable mesh shader support on GFX10.3+ 1282 ``nongg`` 1283 disable NGG for GFX10 and GFX10.3 1284 ``nonggc`` 1285 disable NGG culling on GPUs where it's enabled by default (GFX10.3 only). 1286 ``nongg_gs`` 1287 disable NGG GS for GFX10 and GFX10.3 1288 ``nort`` 1289 skip executing vkCmdTraceRays and ray queries (RT extensions will still be 1290 advertised) 1291 ``notccompatcmask`` 1292 disable TC-compat CMASK for MSAA surfaces 1293 ``noumr`` 1294 disable UMR dumps during GPU hang detection (only with 1295 :envvar:`RADV_DEBUG` = ``hang``) 1296 ``novrsflatshading`` 1297 disable VRS for flat shading (only on GFX10.3+) 1298 ``preoptir`` 1299 dump LLVM IR before any optimizations 1300 ``prologs`` 1301 dump vertex shader prologs 1302 ``shaders`` 1303 dump shaders 1304 ``shaderstats`` 1305 dump shader statistics 1306 ``shadowregs`` 1307 enable register shadowing 1308 ``spirv`` 1309 dump SPIR-V 1310 ``splitfma`` 1311 split application-provided fused multiply-add in geometry stages 1312 ``startup`` 1313 display info at startup 1314 ``syncshaders`` 1315 synchronize shaders after all draws/dispatches 1316 ``zerovram`` 1317 initialize all memory allocated in VRAM as zero 1318 1319.. envvar:: RADV_FORCE_FAMILY 1320 1321 create a null device to compile shaders without a AMD GPU (e.g. VEGA10) 1322 1323.. envvar:: RADV_FORCE_VRS 1324 1325 allow to force per-pipeline vertex VRS rates on GFX10.3+. This is only 1326 forced for pipelines that don't explicitly use VRS or flat shading. 1327 The supported values are 2x2, 1x2, 2x1 and 1x1. Only for testing purposes. 1328 1329.. envvar:: RADV_FORCE_VRS_CONFIG_FILE 1330 1331 similar to ``RADV_FORCE_VRS`` but allow to configure from a file. If present, 1332 this supersedes ``RADV_FORCE_VRS``. 1333 1334.. envvar:: RADV_PERFTEST 1335 1336 a comma-separated list of named flags, which do various things: 1337 1338 ``bolist`` 1339 enable the global BO list 1340 ``cswave32`` 1341 enable wave32 for compute shaders (GFX10+) 1342 ``dccmsaa`` 1343 enable DCC for MSAA images 1344 ``dmashaders`` 1345 upload shaders to invisible VRAM (might be useful for non-resizable BAR systems) 1346 ``emulate_rt`` 1347 forces ray-tracing to be emulated in software on GFX10_3+ and enables 1348 rt extensions with older hardware. 1349 ``gewave32`` 1350 enable wave32 for vertex/tess/geometry shaders (GFX10+) 1351 ``localbos`` 1352 enable local BOs 1353 ``nggc`` 1354 enable NGG culling on GPUs where it's not enabled by default (GFX10.1 only). 1355 ``nircache`` 1356 cache per-stage NIR for graphics pipelines 1357 ``nosam`` 1358 disable optimizations that get enabled when all VRAM is CPU visible. 1359 ``pswave32`` 1360 enable wave32 for pixel shaders (GFX10+) 1361 ``rtwave32`` 1362 enable wave32 for ray tracing shaders (GFX11+) 1363 ``rtwave64`` 1364 enable wave64 for ray tracing shaders (GFX10-10.3) 1365 ``sam`` 1366 enable optimizations to move more driver internal objects to VRAM. 1367 ``shader_object`` 1368 enable experimental implementation of VK_EXT_shader_object (GFX6-8 and 1369 VEGA10) 1370 ``transfer_queue`` 1371 enable experimental transfer queue support (GFX9+, not yet spec compliant) 1372 ``video_decode`` 1373 enable experimental video decoding support 1374 1375.. envvar:: RADV_TEX_ANISO 1376 1377 force anisotropy filter (up to 16) 1378 1379.. envvar:: RADV_THREAD_TRACE_BUFFER_SIZE 1380 1381 set the SQTT/RGP buffer size in bytes (default value is 32MiB, the buffer is 1382 automatically resized if too small) 1383 1384.. envvar:: RADV_THREAD_TRACE_CACHE_COUNTERS 1385 1386 enable/disable SQTT/RGP cache counters on GFX10+ (enabled by default) 1387 1388.. envvar:: RADV_THREAD_TRACE_INSTRUCTION_TIMING 1389 1390 enable/disable SQTT/RGP instruction timing (enabled by default) 1391 1392.. envvar:: RADV_THREAD_TRACE_QUEUE_EVENTS 1393 1394 enable/disable SQTT/RGP queue events (enabled by default) 1395 1396.. envvar:: RADV_RRA_TRACE_VALIDATE 1397 1398 enable validation of captured acceleration structures. Can be 1399 useful if RRA crashes upon opening a trace. 1400 1401.. envvar:: RADV_RRA_TRACE_HISTORY_SIZE 1402 1403 set the ray history buffer size when capturing RRA traces (default value is 100MiB, 1404 small buffers may result in incomplete traces) 1405 1406.. envvar:: RADV_RRA_TRACE_RESOLUTION_SCALE 1407 1408 decrease the resolution used for dumping the ray history resolution when capturing 1409 RRA traces. This allows for dumping every Nth invocation along each dispatch dimension. 1410 1411.. envvar:: ACO_DEBUG 1412 1413 a comma-separated list of named flags, which do various things: 1414 1415 ``validateir`` 1416 validate the ACO IR at various points of compilation (enabled by 1417 default for debug/debugoptimized builds) 1418 ``novalidateir`` 1419 disable ACO IR validation in debug/debugoptimized builds 1420 ``validatera`` 1421 validate register assignment of ACO IR and catches many RA bugs 1422 ``perfwarn`` 1423 abort on some suboptimal code generation 1424 ``force-waitcnt`` 1425 force emitting waitcnt states if there is something to wait for 1426 ``force-waitdeps`` 1427 force emitting waitcnt dependencies for debugging hazards on GFX10+ 1428 ``novn`` 1429 disable value numbering 1430 ``noopt`` 1431 disable various optimizations 1432 ``nosched`` 1433 disable instructions scheduling 1434 ``perfinfo`` 1435 print information used to calculate some pipeline statistics 1436 ``liveinfo`` 1437 print liveness and register demand information before scheduling 1438 1439RadeonSI driver environment variables 1440------------------------------------- 1441 1442.. envvar:: radeonsi_no_infinite_interp 1443 1444 Kill PS with infinite interp coeff (might fix hangs) 1445 1446.. envvar:: radeonsi_clamp_div_by_zero 1447 1448 Clamp div by zero (x / 0 becomes FLT_MAX instead of NaN) (might fix rendering corruptions) 1449 1450.. envvar:: radeonsi_zerovram 1451 1452 Clear all allocated memory to 0 before usage (might fix rendering corruptions) 1453 1454.. envvar:: AMD_DEBUG 1455 1456 a comma-separated list of named flags, which do various things: 1457 1458 ``nodcc`` 1459 Disable DCC. 1460 ``nodccclear`` 1461 Disable DCC fast clear 1462 ``nodisplaydcc`` 1463 disable Delta Color Compression (DCC) on displayable images 1464 ``nodccmsaa`` 1465 Disable DCC for MSAA 1466 ``nodpbb`` 1467 Disable DPBB. Overrules the dpbb enable option. 1468 ``noefc`` 1469 Disable hardware based encoder colour format conversion 1470 ``notiling`` 1471 Disable tiling 1472 ``nofmask`` 1473 Disable MSAA compression 1474 ``nohyperz`` 1475 Disable Hyper-Z 1476 ``no2d`` 1477 Disable 2D tiling 1478 ``info`` 1479 Print driver information 1480 ``tex`` 1481 Print texture info 1482 ``compute`` 1483 Print compute info 1484 ``vm`` 1485 Print virtual addresses when creating resources 1486 ``vs`` 1487 Print vertex shaders 1488 ``ps`` 1489 Print pixel shaders 1490 ``gs`` 1491 Print geometry shaders 1492 ``tcs`` 1493 Print tessellation control shaders 1494 ``tes`` 1495 Print tessellation evaluation shaders 1496 ``cs`` 1497 Print compute shaders 1498 ``noir`` 1499 Don't print the LLVM IR 1500 ``nonir`` 1501 Don't print NIR when printing shaders 1502 ``noasm`` 1503 Don't print disassembled shaders 1504 ``preoptir`` 1505 Print the LLVM IR before initial optimizations 1506 ``w32ge`` 1507 Use Wave32 for vertex, tessellation, and geometry shaders. 1508 ``w32ps`` 1509 Use Wave32 for pixel shaders. 1510 ``w32cs`` 1511 Use Wave32 for computes shaders. 1512 ``w64ge`` 1513 Use Wave64 for vertex, tessellation, and geometry shaders. 1514 ``w64ps`` 1515 Use Wave64 for pixel shaders. 1516 ``w64cs`` 1517 Use Wave64 for computes shaders. 1518 ``checkir`` 1519 Enable additional sanity checks on shader IR 1520 ``mono`` 1521 Use old-style monolithic shaders compiled on demand 1522 ``nooptvariant`` 1523 Disable compiling optimized shader variants. 1524 ``useaco`` 1525 Use ACO as shader compiler when possible 1526 ``nowc`` 1527 Disable GTT write combining 1528 ``check_vm`` 1529 Check VM faults and dump debug info. 1530 ``reserve_vmid`` 1531 Force VMID reservation per context. 1532 ``nongg`` 1533 Disable NGG and use the legacy pipeline. 1534 ``nggc`` 1535 Always use NGG culling even when it can hurt. 1536 ``nonggc`` 1537 Disable NGG culling. 1538 ``switch_on_eop`` 1539 Program WD/IA to switch on end-of-packet. 1540 ``nooutoforder`` 1541 Disable out-of-order rasterization 1542 ``dpbb`` 1543 Enable DPBB. Enable DPBB for gfx9 dGPU. Default enabled for gfx9 APU and >= gfx10. 1544 ``extra_md`` 1545 add extra information in bo metadatas to help tools (umr) 1546 1547r600 driver environment variables 1548--------------------------------- 1549 1550.. envvar:: R600_DEBUG 1551 1552 a comma-separated list of named flags, which do various things: 1553 1554 ``nocpdma`` 1555 Disable CP DMA 1556 ``nosb`` 1557 Disable sb backend for graphics shaders 1558 ``sbcl`` 1559 Enable sb backend for compute shaders 1560 ``sbdry`` 1561 Don't use optimized bytecode (just print the dumps) 1562 ``sbstat`` 1563 Print optimization statistics for shaders 1564 ``sbdump`` 1565 Print IR dumps after some optimization passes 1566 ``sbnofallback`` 1567 Abort on errors instead of fallback 1568 ``sbdisasm`` 1569 Use sb disassembler for shader dumps 1570 ``sbsafemath`` 1571 Disable unsafe math optimizations 1572 ``nirsb`` 1573 Enable NIR with SB optimizer 1574 ``tex`` 1575 Print texture info 1576 ``nir`` 1577 Enable experimental NIR shaders 1578 ``compute`` 1579 Print compute info 1580 ``vm`` 1581 Print virtual addresses when creating resources 1582 ``info`` 1583 Print driver information 1584 ``fs`` 1585 Print fetch shaders 1586 ``vs`` 1587 Print vertex shaders 1588 ``gs`` 1589 Print geometry shaders 1590 ``ps`` 1591 Print pixel shaders 1592 ``cs`` 1593 Print compute shaders 1594 ``tcs`` 1595 Print tessellation control shaders 1596 ``tes`` 1597 Print tessellation evaluation shaders 1598 ``noir`` 1599 Don't print the LLVM IR 1600 ``notgsi`` 1601 Don't print the TGSI 1602 ``noasm`` 1603 Don't print disassembled shaders 1604 ``preoptir`` 1605 Print the LLVM IR before initial optimizations 1606 ``checkir`` 1607 Enable additional sanity checks on shader IR 1608 ``nooptvariant`` 1609 Disable compiling optimized shader variants. 1610 ``testdma`` 1611 Invoke SDMA tests and exit. 1612 ``testvmfaultcp`` 1613 Invoke a CP VM fault test and exit. 1614 ``testvmfaultsdma`` 1615 Invoke a SDMA VM fault test and exit. 1616 ``testvmfaultshader`` 1617 Invoke a shader VM fault test and exit. 1618 ``nodma`` 1619 Disable asynchronous DMA 1620 ``nohyperz`` 1621 Disable Hyper-Z 1622 ``noinvalrange`` 1623 Disable handling of INVALIDATE_RANGE map flags 1624 ``no2d`` 1625 Disable 2D tiling 1626 ``notiling`` 1627 Disable tiling 1628 ``switch_on_eop`` 1629 Program WD/IA to switch on end-of-packet. 1630 ``forcedma`` 1631 Use asynchronous DMA for all operations when possible. 1632 ``precompile`` 1633 Compile one shader variant at shader creation. 1634 ``nowc`` 1635 Disable GTT write combining 1636 ``check_vm`` 1637 Check VM faults and dump debug info. 1638 ``unsafemath`` 1639 Enable unsafe math shader optimizations 1640 1641.. envvar:: R600_DEBUG_COMPUTE 1642 1643 if set to ``true``, various compute-related debug information will 1644 be printed to stderr. Defaults to ``false``. 1645 1646.. envvar:: R600_DUMP_SHADERS 1647 1648 if set to ``true``, NIR shaders will be printed to stderr. Defaults 1649 to ``false``. 1650 1651.. envvar:: R600_HYPERZ 1652 1653 If set to ``false``, disables HyperZ optimizations. Defaults to ``true``. 1654 1655.. envvar:: R600_NIR_DEBUG 1656 1657 a comma-separated list of named flags, which do various things: 1658 1659 ``instr`` 1660 Log all consumed nir instructions 1661 ``ir`` 1662 Log created R600 IR 1663 ``cc`` 1664 Log R600 IR to assembly code creation 1665 ``noerr`` 1666 Don't log shader conversion errors 1667 ``si`` 1668 Log shader info (non-zero values) 1669 ``reg`` 1670 Log register allocation and lookup 1671 ``io`` 1672 Log shader in and output 1673 ``ass`` 1674 Log IR to assembly conversion 1675 ``flow`` 1676 Log control flow instructions 1677 ``merge`` 1678 Log register merge operations 1679 ``nomerge`` 1680 Skip register merge step 1681 ``tex`` 1682 Log texture ops 1683 ``trans`` 1684 Log generic translation messages 1685 1686r300 driver environment variables 1687--------------------------------- 1688 1689.. envvar:: RADEON_DEBUG 1690 1691 a comma-separated list of named flags, which do various things: 1692 1693 ``info`` 1694 Print hardware info (printed by default on debug builds 1695 ``fp`` 1696 Log fragment program compilation 1697 ``vp`` 1698 Log vertex program compilation 1699 ``draw`` 1700 Log draw calls 1701 ``swtcl`` 1702 Log SWTCL-specific info 1703 ``rsblock`` 1704 Log rasterizer registers 1705 ``psc`` 1706 Log vertex stream registers 1707 ``tex`` 1708 Log basic info about textures 1709 ``texalloc`` 1710 Log texture mipmap tree info 1711 ``rs`` 1712 Log rasterizer 1713 ``fb`` 1714 Log framebuffer 1715 ``cbzb`` 1716 Log fast color clear info 1717 ``hyperz`` 1718 Log HyperZ info 1719 ``scissor`` 1720 Log scissor info 1721 ``msaa`` 1722 Log MSAA resources 1723 ``anisohq`` 1724 Use high quality anisotropic filtering 1725 ``notiling`` 1726 Disable tiling 1727 ``noimmd`` 1728 Disable immediate mode 1729 ``noopt`` 1730 Disable shader optimizations 1731 ``nocbzb`` 1732 Disable fast color clear 1733 ``nozmask`` 1734 Disable zbuffer compression 1735 ``nohiz`` 1736 Disable hierarchical zbuffer 1737 ``nocmask`` 1738 Disable AA compression and fast AA clear 1739 ``notcl`` 1740 Disable hardware accelerated Transform/Clip/Lighting 1741 1742Asahi driver environment variables 1743---------------------------------- 1744 1745.. envvar:: ASAHI_MESA_DEBUG 1746 1747 a comma-separated list of named flags, which do various things: 1748 1749 ``trace`` 1750 Trace work submitted to the GPU to files, using the agxdecode 1751 infrastructure. This produces a large volume of data, so should be used 1752 with caution. The traces are written to ``agxdecode.dump``, 1753 but this can be overridden using ``AGXDECODE_DUMP_FILE``. 1754 ``no16`` 1755 Disable 16-bit floating point support. This may workaround application 1756 bugs in certain OpenGL ES applications originally written for desktops. If 1757 such applications are found in the wild, they should be fixed upstream (if 1758 possible) or added in the Mesa-wide driconf (if closed source). 1759 ``dirty`` 1760 In debug builds only: disable dirty tracking optimizations. 1761 ``nowc`` 1762 Disable write-combining (force all allocations to be write-through). This 1763 may be useful for diagnosing certain performance issues. Note imported 1764 buffers may still be write-combined. 1765 1766.. envvar:: AGX_MESA_DEBUG 1767 1768 a comma-separated list of named flags, which do various things: 1769 1770 ``shaders`` 1771 Print shaders being compiled at various stages in the pipeline. 1772 ``shaderdb`` 1773 Print statistics about compiled shaders. 1774 ``verbose`` 1775 Disassemble in verbose mode, including additional information that may be 1776 useful for debugging. 1777 ``internal`` 1778 Include even internal shaders (as produced for clears, blits, and such) 1779 when printing shaders. Without this flag, internal shaders are ignored by 1780 the shaders and shaderdb flags. 1781 ``novalidate`` 1782 In debug builds only: skip internal intermediate representation validation. 1783 ``noopt`` 1784 Disable various backend optimizations. 1785 1786.. _imagination env-vars: 1787 1788PowerVR driver environment variables 1789------------------------------------------------ 1790 1791.. envvar:: PVR_DEBUG 1792 1793 A comma-separated list of debug options. Use `PVR_DEBUG=help` to 1794 print a list of available options. 1795 1796.. envvar:: ROGUE_DEBUG 1797 1798 a comma-separated list of named flags for the Rogue compiler, 1799 which do various things: 1800 1801 ``nir`` 1802 Print the input NIR to stdout. 1803 ``nir_passes`` 1804 Print the output of each NIR pass to stdout. 1805 ``ir`` 1806 Print the input Rogue IR to stdout. 1807 ``ir_passes`` 1808 Print the output of each Rogue IR pass to stdout. 1809 ``ir_details`` 1810 Includes additional details when printing Rogue IR. 1811 ``vld_skip`` 1812 Skips the compiler validation step. 1813 ``vld_nonfatal`` 1814 Prints all the validation errors instead of stopping after the first. 1815 1816.. envvar:: ROGUE_COLOR 1817 1818 if set to ``auto`` Rogue IR will be colorized if stdout is not a pipe. 1819 Color is forced off if set to ``off``/``0`` or on if set to ``on``/``1``. 1820 Defaults to ``auto``. 1821 1822i915 driver environment variables 1823--------------------------------- 1824 1825.. envvar:: I915_DEBUG 1826 1827 Debug flags for the i915 driver. 1828 1829.. envvar:: I915_NO_HW 1830 1831 Stop the i915 driver from submitting commands to the hardware. 1832 1833.. envvar:: I915_DUMP_CMD 1834 1835 Dump all commands going to the hardware. 1836 1837Freedreno driver environment variables 1838-------------------------------------- 1839 1840.. envvar:: FD_MESA_DEBUG 1841 1842 Debug flags for the Freedreno driver. 1843 1844---- 1845 1846Other Gallium drivers have their own environment variables. These may 1847change frequently so the source code should be consulted for details. 1848