envvars.rst 30.8 KB
Newer Older
1
2
3
4
5
6
7
8
9
10
Environment Variables
=====================

Normally, no environment variables need to be set. Most of the
environment variables used by Mesa/Gallium are for debugging purposes,
but they can sometimes be useful for debugging end-user issues.

LibGL environment variables
---------------------------

11
:envvar:`LIBGL_DEBUG`
12
13
   If defined debug information will be printed to stderr. If set to
   ``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
22
   if set to ``true``, do not use DrawArrays GLX protocol (for
   debugging)
23
:envvar:`LIBGL_SHOW_FPS`
24
25
   print framerate to stdout based on the number of ``glXSwapBuffers``
   calls per second.
26
:envvar:`LIBGL_DRI2_DISABLE`
27
   disable DRI2 if set to ``true``.
28
:envvar:`LIBGL_DRI3_DISABLE`
29
30
31
32
33
   disable DRI3 if set to ``true``.

Core Mesa environment variables
-------------------------------

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
Erik Faye-Lund 's avatar
Erik Faye-Lund committed
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
48
49
   if set, error messages are printed to stderr. For example, if the
   application generates a ``GL_INVALID_ENUM`` error, a corresponding
   error message indicating where the error occurred, and possibly why,
50
51
   will be printed to stderr. For release builds, :envvar:`MESA_DEBUG`
   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
56
57
58
59
60
61

   ``silent``
      turn off debug messages. Only useful for debug builds.
   ``flush``
      flush after each drawing command
   ``incomplete_tex``
      extra debug messages when a texture is incomplete
   ``incomplete_fbo``
Erik Faye-Lund 's avatar
Erik Faye-Lund committed
62
      extra debug messages when a FBO is incomplete
63
64
65
66
67
   ``context``
      create a debug context (see ``GLX_CONTEXT_DEBUG_BIT_ARB``) and
      print error and performance messages to stderr (or
      ``MESA_LOG_FILE``).

68
:envvar:`MESA_LOG_FILE`
69
70
   specifies a file name for logging all errors, warnings, etc., rather
   than stderr
71
:envvar:`MESA_TEX_PROG`
72
   if set, implement conventional texture environment modes with fragment
73
   programs (intended for developers only)
74
:envvar:`MESA_TNL_PROG`
75
76
   if set, implement conventional vertex transformation operations with
   vertex programs (intended for developers only). Setting this variable
77
78
   automatically sets the :envvar:`MESA_TEX_PROG` variable as well.
:envvar:`MESA_EXTENSION_OVERRIDE`
79
80
81
   can be used to enable/disable extensions. A value such as
   ``GL_EXT_foo -GL_EXT_bar`` will enable the ``GL_EXT_foo`` extension
   and disable the ``GL_EXT_bar`` extension.
82
:envvar:`MESA_EXTENSION_MAX_YEAR`
83
84
85
86
87
88
89
   The ``GL_EXTENSIONS`` string returned by Mesa is sorted by extension
   year. If this variable is set to year X, only extensions defined on
   or before year X will be reported. This is to work-around a bug in
   some games where the extension string is copied into a fixed-size
   buffer without truncating. If the extension string is too long, the
   buffer overrun can cause the game to crash. This is a work-around for
   that.
90
:envvar:`MESA_GL_VERSION_OVERRIDE`
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
   changes the value returned by ``glGetString(GL_VERSION)`` and
   possibly the GL API type.

   -  The format should be ``MAJOR.MINOR[FC|COMPAT]``
   -  ``FC`` is an optional suffix that indicates a forward compatible
      context. This is only valid for versions >= 3.0.
   -  ``COMPAT`` is an optional suffix that indicates a compatibility
      context or ``GL_ARB_compatibility`` support. This is only valid
      for versions >= 3.1.
   -  GL versions <= 3.0 are set to a compatibility (non-Core) profile
   -  GL versions = 3.1, depending on the driver, it may or may not have
      the ``ARB_compatibility`` extension enabled.
   -  GL versions >= 3.2 are set to a Core profile
   -  Examples:

      ``2.1``
         select a compatibility (non-Core) profile with GL version 2.1.
      ``3.0``
         select a compatibility (non-Core) profile with GL version 3.0.
      ``3.0FC``
         select a Core+Forward Compatible profile with GL version 3.0.
      ``3.1``
         select GL version 3.1 with ``GL_ARB_compatibility`` enabled per
         the driver default.
      ``3.1FC``
         select GL version 3.1 with forward compatibility and
         ``GL_ARB_compatibility`` disabled.
      ``3.1COMPAT``
         select GL version 3.1 with ``GL_ARB_compatibility`` enabled.
      ``X.Y``
         override GL version to X.Y without changing the profile.
      ``X.YFC``
         select a Core+Forward Compatible profile with GL version X.Y.
      ``X.YCOMPAT``
         select a Compatibility profile with GL version X.Y.

   -  Mesa may not really implement all the features of the given
      version. (for developers only)

130
:envvar:`MESA_GLES_VERSION_OVERRIDE`
131
132
133
134
135
136
137
138
   changes the value returned by ``glGetString(GL_VERSION)`` for OpenGL
   ES.

   -  The format should be ``MAJOR.MINOR``
   -  Examples: ``2.0``, ``3.0``, ``3.1``
   -  Mesa may not really implement all the features of the given
      version. (for developers only)

139
:envvar:`MESA_GLSL_VERSION_OVERRIDE`
140
141
142
143
144
   changes the value returned by
   ``glGetString(GL_SHADING_LANGUAGE_VERSION)``. Valid values are
   integers, such as ``130``. Mesa will not really implement all the
   features of the given language version if it's higher than what's
   normally reported. (for developers only)
145
:envvar:`MESA_GLSL_CACHE_DISABLE`
146
147
148
   if set to ``true``, disables the GLSL shader cache. If set to
   ``false``, enables the GLSL shader cache when it is disabled by
   default.
149
:envvar:`MESA_GLSL_CACHE_MAX_SIZE`
150
151
152
153
   if set, determines the maximum size of the on-disk cache of compiled
   GLSL programs. Should be set to a number optionally followed by
   ``K``, ``M``, or ``G`` to specify a size in kilobytes, megabytes, or
   gigabytes. By default, gigabytes will be assumed. And if unset, a
154
155
156
157
158
159
160
161
162
   maximum size of 1GB will be used.

   .. note::

      A separate cache might be created for each architecture that Mesa is
      installed for on your system. For example under the default settings
      you may end up with a 1GB cache for x86_64 and another 1GB cache for
      i386.

163
:envvar:`MESA_GLSL_CACHE_DIR`
164
165
166
167
168
   if set, determines the directory to be used for the on-disk cache of
   compiled GLSL programs. If this variable is not set, then the cache
   will be stored in ``$XDG_CACHE_HOME/mesa_shader_cache`` (if that
   variable is set), or else within ``.cache/mesa_shader_cache`` within
   the user's home directory.
169
:envvar:`MESA_GLSL`
170
   :ref:`shading language compiler options <envvars>`
171
:envvar:`MESA_NO_MINMAX_CACHE`
172
   when set, the minmax index cache is globally disabled.
173
:envvar:`MESA_SHADER_CAPTURE_PATH`
174
   see :ref:`Capturing Shaders <capture>`
175
:envvar:`MESA_SHADER_DUMP_PATH` and :envvar:`MESA_SHADER_READ_PATH`
176
177
   see :ref:`Experimenting with Shader
   Replacements <replacement>`
178
:envvar:`MESA_VK_VERSION_OVERRIDE`
179
180
181
182
183
184
185
186
   changes the Vulkan physical device version as returned in
   ``VkPhysicalDeviceProperties::apiVersion``.

   -  The format should be ``MAJOR.MINOR[.PATCH]``
   -  This will not let you force a version higher than the driver's
      instance version as advertised by ``vkEnumerateInstanceVersion``
   -  This can be very useful for debugging but some features may not be
      implemented correctly. (For developers only)
187
:envvar:`MESA_LOADER_DRIVER_OVERRIDE`
Jan Ziak's avatar
Jan Ziak committed
188
   chooses a different driver binary such as ``etnaviv`` or ``zink``.
189

Eric Engestrom's avatar
Eric Engestrom committed
190
191
NIR passes environment variables
--------------------------------
192
193

The following are only applicable for drivers that uses NIR, as they
Erik Faye-Lund 's avatar
Erik Faye-Lund committed
194
195
modify the behavior for the common ``NIR_PASS`` and ``NIR_PASS_V`` macros,
that wrap calls to NIR lowering/optimizations.
196

197
:envvar:`NIR_PRINT`
198
   If defined, the resulting NIR shader will be printed out at each
Eric Engestrom's avatar
Eric Engestrom committed
199
   successful NIR lowering/optimization call.
200
:envvar:`NIR_TEST_CLONE`
Eric Engestrom's avatar
Eric Engestrom committed
201
   If defined, cloning a NIR shader would be tested at each successful
202
   NIR lowering/optimization call.
203
:envvar:`NIR_TEST_SERIALIZE`
204
   If defined, serialize and deserialize a NIR shader would be tested at
Eric Engestrom's avatar
Eric Engestrom committed
205
   each successful NIR lowering/optimization call.
206
207
208
209
210

Mesa Xlib driver environment variables
--------------------------------------

The following are only applicable to the Mesa Xlib software driver. See
211
the :doc:`Xlib software driver page <xlibdriver>` for details.
212

213
:envvar:`MESA_RGB_VISUAL`
214
   specifies the X visual and depth for RGB mode
215
:envvar:`MESA_BACK_BUFFER`
216
217
   specifies how to implement the back color buffer, either ``pixmap``
   or ``ximage``
218
:envvar:`MESA_GAMMA`
219
   gamma correction coefficients for red, green, blue channels
220
:envvar:`MESA_XSYNC`
221
   enable synchronous X behavior (for debugging only)
222
:envvar:`MESA_GLX_FORCE_CI`
Erik Faye-Lund 's avatar
Erik Faye-Lund committed
223
   if set, force GLX to treat 8 BPP visuals as CI visuals
224
:envvar:`MESA_GLX_FORCE_ALPHA`
225
   if set, forces RGB windows to have an alpha channel.
226
:envvar:`MESA_GLX_DEPTH_BITS`
227
   specifies default number of bits for depth buffer.
228
:envvar:`MESA_GLX_ALPHA_BITS`
229
230
231
232
233
   specifies default number of bits for alpha channel.

i945/i965 driver environment variables (non-Gallium)
----------------------------------------------------

234
:envvar:`INTEL_NO_HW`
235
236
   if set to 1, prevents batches from being submitted to the hardware.
   This is useful for debugging hangs, etc.
237
:envvar:`INTEL_DEBUG`
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
   a comma-separated list of named flags, which do various things:

   ``ann``
      annotate IR in assembly dumps
   ``aub``
      dump batches into an AUB trace for use with simulation tools
   ``bat``
      emit batch information
   ``blit``
      emit messages about blit operations
   ``blorp``
      emit messages about the blorp operations (blits & clears)
   ``buf``
      emit messages about buffer objects
   ``clip``
      emit messages about the clip unit (for old gens, includes the CLIP
      program)
   ``color``
      use color in output
   ``cs``
      dump shader assembly for compute shaders
   ``do32``
      generate compute shader SIMD32 programs even if workgroup size
      doesn't exceed the SIMD16 limit
   ``dri``
      emit messages about the DRI interface
   ``fbo``
      emit messages about framebuffers
   ``fs``
      dump shader assembly for fragment shaders
   ``gs``
      dump shader assembly for geometry shaders
   ``hex``
      print instruction hex dump with the disassembly
   ``l3``
      emit messages about the new L3 state during transitions
   ``miptree``
      emit messages about miptrees
   ``no8``
      don't generate SIMD8 fragment shader
   ``no16``
      suppress generation of 16-wide fragment shaders. useful for
      debugging broken shaders
   ``nocompact``
      disable instruction compaction
   ``nodualobj``
      suppress generation of dual-object geometry shader code
   ``nofc``
      disable fast clears
   ``norbc``
      disable single sampled render buffer compression
   ``optimizer``
      dump shader assembly to files at each optimization pass and
      iteration that make progress
   ``perf``
      emit messages about performance issues
   ``perfmon``
      emit messages about ``AMD_performance_monitor``
   ``pix``
      emit messages about pixel operations
   ``prim``
      emit messages about drawing primitives
   ``reemit``
      mark all state dirty on each draw call
   ``sf``
      emit messages about the strips & fans unit (for old gens, includes
      the SF program)
   ``shader_time``
      record how much GPU time is spent in each shader
   ``spill_fs``
      force spilling of all registers in the scalar backend (useful to
      debug spilling code)
   ``spill_vec4``
      force spilling of all registers in the vec4 backend (useful to
      debug spilling code)
   ``state``
      emit messages about state flag tracking
   ``submit``
      emit batchbuffer usage statistics
   ``sync``
      after sending each batch, emit a message and wait for that batch
      to finish rendering
   ``tcs``
      dump shader assembly for tessellation control shaders
   ``tes``
      dump shader assembly for tessellation evaluation shaders
   ``tex``
      emit messages about textures.
   ``urb``
      emit messages about URB setup
   ``vert``
      emit messages about vertex assembly
   ``vs``
      dump shader assembly for vertex shaders

333
:envvar:`INTEL_SCALAR_VS` (or ``TCS``, ``TES``, ``GS``)
334
   force scalar/vec4 mode for a shader stage (Gen8-9 only)
335
:envvar:`INTEL_PRECISE_TRIG`
336
337
   if set to 1, true or yes, then the driver prefers accuracy over
   performance in trig functions.
338
:envvar:`INTEL_SHADER_ASM_READ_PATH`
339
340
341
342
   if set, determines the directory to be used for overriding shader
   assembly. The binaries with custom assembly should be placed in
   this folder and have a name formatted as ``sha1_of_assembly.bin``.
   The sha1 of a shader assembly is printed when assembly is dumped via
343
   corresponding :envvar:`INTEL_DEBUG` flag (e.g. ``vs`` for vertex shader).
344
   A binary could be generated from a dumped assembly by ``i965_asm``.
345
346
347
   For :envvar:`INTEL_SHADER_ASM_READ_PATH` to work it is necessary to enable
   dumping of corresponding shader stages via :envvar:`INTEL_DEBUG`.
   It is advised to use ``nocompact`` flag of :envvar:`INTEL_DEBUG` when
348
349
350
351
   dumping and overriding shader assemblies.
   The success of assembly override would be signified by "Successfully
   overrode shader with sha1 <sha1>" in stderr replacing the original
   assembly.
352
:envvar:`INTEL_BLACKHOLE_DEFAULT`
353
354
355
356
   if set to 1, true or yes, then the OpenGL implementation will
   default ``GL_BLACKHOLE_RENDER_INTEL`` to true, thus disabling any
   rendering.

357
358
359
360

Radeon driver environment variables (radeon, r200, and r300g)
-------------------------------------------------------------

361
:envvar:`RADEON_NO_TCL`
362
363
364
365
366
   if set, disable hardware-accelerated Transform/Clip/Lighting.

EGL environment variables
-------------------------

367
368
Mesa EGL supports different sets of environment variables. See the
:doc:`Mesa EGL <egl>` page for the details.
369
370
371
372

Gallium environment variables
-----------------------------

373
:envvar:`GALLIUM_HUD`
Erik Faye-Lund 's avatar
Erik Faye-Lund committed
374
   draws various information on the screen, like framerate, CPU load,
375
   driver statistics, performance counters, etc. Set
376
377
   :envvar:`GALLIUM_HUD` to ``help`` and run e.g. ``glxgears`` for more info.
:envvar:`GALLIUM_HUD_PERIOD`
Erik Faye-Lund 's avatar
Erik Faye-Lund committed
378
   sets the HUD update rate in seconds (float). Use zero to update every
379
   frame. The default period is 1/2 second.
380
:envvar:`GALLIUM_HUD_VISIBLE`
381
   control default visibility, defaults to true.
382
:envvar:`GALLIUM_HUD_TOGGLE_SIGNAL`
383
   toggle visibility via user specified signal. Especially useful to
Erik Faye-Lund 's avatar
Erik Faye-Lund committed
384
   toggle HUD at specific points of application and disable for
385
   unencumbered viewing the rest of the time. For example, set
386
387
   :envvar:`GALLIUM_HUD_VISIBLE` to ``false`` and
   :envvar:`GALLIUM_HUD_TOGGLE_SIGNAL` to ``10`` (``SIGUSR1``). Use
Erik Faye-Lund 's avatar
Erik Faye-Lund committed
388
   ``kill -10 <pid>`` to toggle the HUD as desired.
389
:envvar:`GALLIUM_HUD_SCALE`
Erik Faye-Lund 's avatar
Erik Faye-Lund committed
390
   Scale HUD by an integer factor, for high DPI displays. Default is 1.
391
:envvar:`GALLIUM_HUD_DUMP_DIR`
Erik Faye-Lund 's avatar
Erik Faye-Lund committed
392
   specifies a directory for writing the displayed HUD values into
393
   files.
394
395
:envvar:`GALLIUM_DRIVER`
   useful in combination with :envvar:`LIBGL_ALWAYS_SOFTWARE`=`true` for
396
397
   choosing one of the software renderers ``softpipe``, ``llvmpipe`` or
   ``swr``.
398
:envvar:`GALLIUM_LOG_FILE`
399
400
   specifies a file for logging all errors, warnings, etc. rather than
   stderr.
401
:envvar:`GALLIUM_PIPE_SEARCH_DIR`
402
403
   specifies an alternate search directory for pipe-loader which overrides
   the compile-time path based on the install location.
404
:envvar:`GALLIUM_PRINT_OPTIONS`
405
406
   if non-zero, print all the Gallium environment variables which are
   used, and their current values.
407
:envvar:`GALLIUM_DUMP_CPU`
408
   if non-zero, print information about the CPU on start-up
409
:envvar:`TGSI_PRINT_SANITY`
410
411
   if set, do extra sanity checking on TGSI shaders and print any errors
   to stderr.
412
:envvar:`DRAW_FSE`
413
414
   Enable fetch-shade-emit middle-end even though its not correct (e.g.
   for softpipe)
415
:envvar:`DRAW_NO_FSE`
416
   Disable fetch-shade-emit middle-end even when it is correct
417
:envvar:`DRAW_USE_LLVM`
418
419
   if set to zero, the draw module will not use LLVM to execute shaders,
   vertex fetch, etc.
420
:envvar:`ST_DEBUG`
421
422
   controls debug output from the Mesa/Gallium state tracker. Setting to
   ``tgsi``, for example, will print all the TGSI shaders. See
423
   :file:`src/mesa/state_tracker/st_debug.c` for other options.
424
425

Clover environment variables
426
----------------------------
427

428
:envvar:`CLOVER_EXTRA_BUILD_OPTIONS`
429
430
431
   allows specifying additional compiler and linker options. Specified
   options are appended after the options set by the OpenCL program in
   ``clBuildProgram``.
432
:envvar:`CLOVER_EXTRA_COMPILE_OPTIONS`
433
434
435
   allows specifying additional compiler options. Specified options are
   appended after the options set by the OpenCL program in
   ``clCompileProgram``.
436
:envvar:`CLOVER_EXTRA_LINK_OPTIONS`
437
438
439
440
441
   allows specifying additional linker options. Specified options are
   appended after the options set by the OpenCL program in
   ``clLinkProgram``.

Softpipe driver environment variables
442
-------------------------------------
443

444
:envvar:`SOFTPIPE_DEBUG`
445
446
447
448
449
450
451
452
453
454
455
   a comma-separated list of named flags, which do various things:

   ``vs``
      Dump vertex shader assembly to stderr
   ``fs``
      Dump fragment shader assembly to stderr
   ``gs``
      Dump geometry shader assembly to stderr
   ``cs``
      Dump compute shader assembly to stderr
   ``no_rast``
Erik Faye-Lund 's avatar
Erik Faye-Lund committed
456
      rasterization is disabled. For profiling purposes.
457
458
459
   ``use_llvm``
      the softpipe driver will try to use LLVM JIT for vertex
      shading processing.
460
461
462
   ``use_tgsi``
      if set, the softpipe driver will ask to directly consume TGSI, instead
      of NIR.
463
464

LLVMpipe driver environment variables
465
-------------------------------------
466

467
:envvar:`LP_NO_RAST`
468
   if set LLVMpipe will no-op rasterization
469
:envvar:`LP_DEBUG`
470
471
   a comma-separated list of debug options is accepted. See the source
   code for details.
472
:envvar:`LP_PERF`
473
474
   a comma-separated list of options to selectively no-op various parts
   of the driver. See the source code for details.
475
:envvar:`LP_NUM_THREADS`
476
477
478
479
480
   an integer indicating how many threads to use for rendering. Zero
   turns off threading completely. The default value is the number of
   CPU cores present.

VMware SVGA driver environment variables
481
----------------------------------------
482

483
:envvar`SVGA_FORCE_SWTNL`
484
   force use of software vertex transformation
485
:envvar`SVGA_NO_SWTNL`
486
487
   don't allow software vertex transformation fallbacks (will often
   result in incorrect rendering).
488
:envvar`SVGA_DEBUG`
489
   for dumping shaders, constant buffers, etc. See the code for details.
490
:envvar`SVGA_EXTRA_LOGGING`
491
492
   if set, enables extra logging to the ``vmware.log`` file, such as the
   OpenGL program's name and command line arguments.
493
:envvar`SVGA_NO_LOGGING`
494
495
496
497
498
499
500
   if set, disables logging to the ``vmware.log`` file. This is useful
   when using Valgrind because it otherwise crashes when initializing
   the host log feature.

See the driver code for other, lesser-used variables.

WGL environment variables
501
-------------------------
502

503
:envvar:`WGL_SWAP_INTERVAL`
504
505
506
507
508
509
   to set a swap interval, equivalent to calling
   ``wglSwapIntervalEXT()`` in an application. If this environment
   variable is set, application calls to ``wglSwapIntervalEXT()`` will
   have no effect.

VA-API environment variables
510
----------------------------
511

512
:envvar:`VAAPI_MPEG4_ENABLED`
513
514
515
   enable MPEG4 for VA-API, disabled by default.

VC4 driver environment variables
516
--------------------------------
517

518
:envvar:`VC4_DEBUG`
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
   a comma-separated list of named flags, which do various things:

   ``cl``
      dump command list during creation
   ``qpu``
      dump generated QPU instructions
   ``qir``
      dump QPU IR during program compile
   ``nir``
      dump NIR during program compile
   ``tgsi``
      dump TGSI during program compile
   ``shaderdb``
      dump program compile information for shader-db analysis
   ``perf``
      print during performance-related events
   ``norast``
      skip actual hardware execution of commands
   ``always_flush``
      flush after each draw call
   ``always_sync``
      wait for finish after each flush
   ``dump``
      write a GPU command stream trace file (VC4 simulator only)

RADV driver environment variables
545
---------------------------------
546

547
:envvar:`RADV_DEBUG`
548
549
   a comma-separated list of named flags, which do various things:

550
551
   ``llvm``
      enable LLVM compiler backend
552
553
554
555
556
557
   ``allbos``
      force all allocated buffers to be referenced in submissions
   ``checkir``
      validate the LLVM IR before LLVM compiles the shader
   ``errors``
      display more info about errors
558
559
560
   ``forcecompress``
      Enables DCC,FMASK,CMASK,HTILE in situations where the driver supports it
      but normally does not deem it beneficial.
561
   ``hang``
562
563
      enable GPU hangs detection and dump a report to
      $HOME/radv_dumps_<pid>_<time> if a GPU hang is detected
Simon Ser's avatar
Simon Ser committed
564
565
   ``img``
      Print image info
566
567
   ``info``
      show GPU-related information
568
569
570
   ``invariantgeom``
      Mark geometry-affecting outputs as invariant. This works around a common
      class of application bugs appearing as flickering.
571
572
573
574
575
576
577
578
579
580
   ``metashaders``
      dump internal meta shaders
   ``nobinning``
      disable primitive binning
   ``nocache``
      disable shaders cache
   ``nocompute``
      disable compute queue
   ``nodcc``
      disable Delta Color Compression (DCC) on images
581
582
   ``nodisplaydcc``
      disable Delta Color Compression (DCC) on displayable images
583
584
585
586
587
588
589
590
591
592
593
594
   ``nodynamicbounds``
      do not check OOB access for dynamic descriptors
   ``nofastclears``
      disable fast color/depthstencil clears
   ``nohiz``
      disable HIZ for depthstencil images
   ``noibs``
      disable directly recording command buffers in GPU-visible memory
   ``nomemorycache``
      disable memory shaders cache
   ``nongg``
      disable NGG for GFX10+
595
596
   ``nonggc``
      disable NGG culling for GFX10+
597
598
   ``nooutoforder``
      disable out-of-order rasterization
599
600
   ``notccompatcmask``
      disable TC-compat CMASK for MSAA surfaces
601
   ``noumr``
602
603
      disable UMR dumps during GPU hang detection (only with
      :envvar:`RADV_DEBUG`=``hang``)
604
605
   ``novrsflatshading``
      disable VRS for flat shading (only on GFX10.3+)
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
   ``preoptir``
      dump LLVM IR before any optimizations
   ``shaders``
      dump shaders
   ``shaderstats``
      dump shader statistics
   ``spirv``
      dump SPIR-V
   ``startup``
      display info at startup
   ``syncshaders``
      synchronize shaders after all draws/dispatches
   ``vmfaults``
      check for VM memory faults via dmesg
   ``zerovram``
      initialize all memory allocated in VRAM as zero

623
:envvar:`RADV_FORCE_FAMILY`
624
   create a null device to compile shaders without a AMD GPU (e.g. vega10)
625

626
:envvar:`RADV_FORCE_VRS`
627
628
629
630
   allow to force per-pipeline vertex VRS rates on GFX10.3+. This is only
   forced for pipelines that don't explicitely use VRS or flat shading.
   The supported values are 2x2, 1x2 and 2x1. Only for testing purposes.

631
:envvar:`RADV_PERFTEST`
632
633
634
635
636
637
638
639
640
641
642
643
   a comma-separated list of named flags, which do various things:

   ``bolist``
      enable the global BO list
   ``cswave32``
      enable wave32 for compute shaders (GFX10+)
   ``dccmsaa``
      enable DCC for MSAA images
   ``gewave32``
      enable wave32 for vertex/tess/geometry shaders (GFX10+)
   ``localbos``
      enable local BOs
644
645
   ``nosam``
      disable optimizations that get enabled when all VRAM is CPU visible.
646
647
   ``pswave32``
      enable wave32 for pixel shaders (GFX10+)
Bas Nieuwenhuizen's avatar
Bas Nieuwenhuizen committed
648
649
   ``sam``
      enable optimizations to move more driver internal objects to VRAM.
650

651
:envvar`RADV_TEX_ANISO`
652
   force anisotropy filter (up to 16)
653
654

:envvar:`ACO_DEBUG`
655
656
657
658
659
660
661
662
663
   a comma-separated list of named flags, which do various things:

   ``validateir``
      validate the ACO IR at various points of compilation (enabled by
      default for debug/debugoptimized builds)
   ``validatera``
      validate register assignment of ACO IR and catches many RA bugs
   ``perfwarn``
      abort on some suboptimal code generation
664
665
   ``force-waitcnt``
      force emitting waitcnt states if there is something to wait for
666
667
668
669
670
671
   ``novn``
      disable value numbering
   ``noopt``
      disable various optimizations
   ``noscheduling``
      disable instructions scheduling
Rhys Perry's avatar
Rhys Perry committed
672
673
   ``perfinfo``
      print information used to calculate some pipeline statistics
Rhys Perry's avatar
Rhys Perry committed
674
675
   ``liveinfo``
      print liveness and register demand information before scheduling
676
677

radeonsi driver environment variables
678
-------------------------------------
679

680
:envvar:`AMD_DEBUG`
681
   a comma-separated list of named flags, which do various things:
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778

   ``nodcc``
      Disable DCC.
   ``nodccclear``
      Disable DCC fast clear.
   ``nodccfb``
      Disable separate DCC on the main framebuffer
   ``nodccmsaa``
      Disable DCC for MSAA
   ``nodpbb``
      Disable DPBB.
   ``nodfsm``
      Disable DFSM.
   ``notiling``
      Disable tiling
   ``nofmask``
      Disable MSAA compression
   ``nohyperz``
      Disable Hyper-Z
   ``no2d``
      Disable 2D tiling
   ``info``
      Print driver information
   ``tex``
      Print texture info
   ``compute``
      Print compute info
   ``vm``
      Print virtual addresses when creating resources
   ``vs``
      Print vertex shaders
   ``ps``
      Print pixel shaders
   ``gs``
      Print geometry shaders
   ``tcs``
      Print tessellation control shaders
   ``tes``
      Print tessellation evaluation shaders
   ``cs``
      Print compute shaders
   ``noir``
      Don't print the LLVM IR
   ``nonir``
      Don't print NIR when printing shaders
   ``noasm``
      Don't print disassembled shaders
   ``preoptir``
      Print the LLVM IR before initial optimizations
   ``gisel``
      Enable LLVM global instruction selector.
   ``w32ge``
      Use Wave32 for vertex, tessellation, and geometry shaders.
   ``w32ps``
      Use Wave32 for pixel shaders.
   ``w32cs``
      Use Wave32 for computes shaders.
   ``w64ge``
      Use Wave64 for vertex, tessellation, and geometry shaders.
   ``w64ps``
      Use Wave64 for pixel shaders.
   ``w64cs``
      Use Wave64 for computes shaders.
   ``checkir``
      Enable additional sanity checks on shader IR
   ``mono``
      Use old-style monolithic shaders compiled on demand
   ``nooptvariant``
      Disable compiling optimized shader variants.
   ``nowc``
      Disable GTT write combining
   ``check_vm``
      Check VM faults and dump debug info.
   ``reserve_vmid``
      Force VMID reservation per context.
   ``nogfx``
      Disable graphics. Only multimedia compute paths can be used.
   ``nongg``
      Disable NGG and use the legacy pipeline.
   ``nggc``
      Always use NGG culling even when it can hurt.
   ``nonggc``
      Disable NGG culling.
   ``alwayspd``
      Always enable the primitive discard compute shader.
   ``pd``
      Enable the primitive discard compute shader for large draw calls.
   ``nopd``
      Disable the primitive discard compute shader.
   ``switch_on_eop``
      Program WD/IA to switch on end-of-packet.
   ``nooutoforder``
      Disable out-of-order rasterization
   ``dpbb``
      Enable DPBB.
   ``dfsm``
      Enable DFSM.
779

780
r600 driver environment variables
781
---------------------------------
782

783
:envvar:`R600_DEBUG`
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
   a comma-separated list of named flags, which do various things:

   ``nocpdma``
      Disable CP DMA
   ``nosb``
      Disable sb backend for graphics shaders
   ``sbcl``
      Enable sb backend for compute shaders
   ``sbdry``
      Don't use optimized bytecode (just print the dumps)
   ``sbstat``
      Print optimization statistics for shaders
   ``sbdump``
      Print IR dumps after some optimization passes
   ``sbnofallback``
      Abort on errors instead of fallback
   ``sbdisasm``
      Use sb disassembler for shader dumps
   ``sbsafemath``
      Disable unsafe math optimizations
   ``nirsb``
      Enable NIR with SB optimizer
   ``tex``
      Print texture info
   ``nir``
      Enable experimental NIR shaders
   ``compute``
      Print compute info
   ``vm``
      Print virtual addresses when creating resources
   ``info``
      Print driver information
   ``fs``
      Print fetch shaders
   ``vs``
      Print vertex shaders
   ``gs``
      Print geometry shaders
   ``ps``
      Print pixel shaders
   ``cs``
      Print compute shaders
   ``tcs``
      Print tessellation control shaders
   ``tes``
      Print tessellation evaluation shaders
   ``noir``
      Don't print the LLVM IR
   ``notgsi``
      Don't print the TGSI
   ``noasm``
      Don't print disassembled shaders
   ``preoptir``
      Print the LLVM IR before initial optimizations
   ``checkir``
      Enable additional sanity checks on shader IR
   ``nooptvariant``
      Disable compiling optimized shader variants.
   ``testdma``
      Invoke SDMA tests and exit.
   ``testvmfaultcp``
      Invoke a CP VM fault test and exit.
   ``testvmfaultsdma``
      Invoke a SDMA VM fault test and exit.
   ``testvmfaultshader``
      Invoke a shader VM fault test and exit.
   ``nodma``
      Disable asynchronous DMA
   ``nohyperz``
      Disable Hyper-Z
   ``noinvalrange``
      Disable handling of INVALIDATE_RANGE map flags
   ``no2d``
      Disable 2D tiling
   ``notiling``
      Disable tiling
   ``switch_on_eop``
      Program WD/IA to switch on end-of-packet.
   ``forcedma``
      Use asynchronous DMA for all operations when possible.
   ``precompile``
      Compile one shader variant at shader creation.
   ``nowc``
      Disable GTT write combining
   ``check_vm``
      Check VM faults and dump debug info.
   ``unsafemath``
      Enable unsafe math shader optimizations

873
:envvar:`R600_DEBUG_COMPUTE`
874
875
   if set to ``true``, various compute-related debug information will
   be printed to stderr. Defaults to ``false``.
876
:envvar:`R600_DUMP_SHADERS`
877
878
   if set to ``true``, NIR shaders will be printed to stderr. Defaults
   to ``false``.
879
:envvar:`R600_HYPERZ`
880
   If set to ``false``, disables HyperZ optimizations. Defaults to ``true``.
881
:envvar:`R600_NIR_DEBUG`
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
   a comma-separated list of named flags, which do various things:

   ``instr``
      Log all consumed nir instructions
   ``ir``
      Log created R600 IR
   ``cc``
      Log R600 IR to assembly code creation
   ``noerr``
      Don't log shader conversion errors
   ``si``
      Log shader info (non-zero values)
   ``reg``
      Log register allocation and lookup
   ``io``
      Log shader in and output
   ``ass``
      Log IR to assembly conversion
   ``flow``
      Log control flow instructions
   ``merge``
      Log register merge operations
   ``nomerge``
      Skip register merge step
   ``tex``
      Log texture ops
   ``trans``
      Log generic translation messages

911
912
Other Gallium drivers have their own environment variables. These may
change frequently so the source code should be consulted for details.