OpenHarmony/third_party_mesa3d
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: use envvar role for envvars

Browse Source 
Reviewed-by: Chia-I Wu <olvaffe@gmail.com>
Part-of: <https://gitlab.freedesktop.org/mesa/mesa/-/merge_requests/11106>
This commit is contained in:
Erik Faye-Lund
2021-06-01 11:30:08 +02:00
committed by Marge Bot
parent 7268a429ce
commit d4397c0048
1 changed files with 108 additions and 106 deletions
Download Patch File Download Diff File Expand all files Collapse all files

214
docs/envvars.rst
View File

@@ -8,49 +8,49 @@ but they can sometimes be useful for debugging end-user issues.
LibGL environment variables
---------------------------
``LIBGL_DEBUG``
:envvar:`LIBGL_DEBUG`
If defined debug information will be printed to stderr. If set to
``verbose`` additional information will be printed.
``LIBGL_DRIVERS_PATH``
:envvar:`LIBGL_DRIVERS_PATH`
colon-separated list of paths to search for DRI drivers
``LIBGL_ALWAYS_INDIRECT``
:envvar:`LIBGL_ALWAYS_INDIRECT`
if set to ``true``, forces an indirect rendering context/connection.
``LIBGL_ALWAYS_SOFTWARE``
:envvar:`LIBGL_ALWAYS_SOFTWARE`
if set to ``true``, always use software rendering
``LIBGL_NO_DRAWARRAYS``
:envvar:`LIBGL_NO_DRAWARRAYS`
if set to ``true``, do not use DrawArrays GLX protocol (for
debugging)
``LIBGL_SHOW_FPS``
:envvar:`LIBGL_SHOW_FPS`
print framerate to stdout based on the number of ``glXSwapBuffers``
calls per second.
``LIBGL_DRI2_DISABLE``
:envvar:`LIBGL_DRI2_DISABLE`
disable DRI2 if set to ``true``.
``LIBGL_DRI3_DISABLE``
:envvar:`LIBGL_DRI3_DISABLE`
disable DRI3 if set to ``true``.
Core Mesa environment variables
-------------------------------
``MESA_NO_ASM``
:envvar:`MESA_NO_ASM`
if set, disables all assembly language optimizations
``MESA_NO_MMX``
:envvar:`MESA_NO_MMX`
if set, disables Intel MMX optimizations
``MESA_NO_3DNOW``
:envvar:`MESA_NO_3DNOW`
if set, disables AMD 3DNow! optimizations
``MESA_NO_SSE``
:envvar:`MESA_NO_SSE`
if set, disables Intel SSE optimizations
``MESA_NO_ERROR``
:envvar:`MESA_NO_ERROR`
if set to 1, error checking is disabled as per ``KHR_no_error``. This
will result in undefined behavior for invalid use of the API, but
can reduce CPU use for apps that are known to be error free.
``MESA_DEBUG``
:envvar:`MESA_DEBUG`
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,
will be printed to stderr. For release builds, ``MESA_DEBUG``
defaults to off (no debug output). ``MESA_DEBUG`` accepts the
will be printed to stderr. For release builds, :envvar:`MESA_DEBUG`
defaults to off (no debug output). :envvar:`MESA_DEBUG` accepts the
following comma-separated list of named flags, which adds extra
behavior to just set ``MESA_DEBUG=1``:
behavior to just set :envvar:`MESA_DEBUG` to ``1``:
``silent``
turn off debug messages. Only useful for debug builds.
@@ -65,21 +65,21 @@ Core Mesa environment variables
print error and performance messages to stderr (or
``MESA_LOG_FILE``).
``MESA_LOG_FILE``
:envvar:`MESA_LOG_FILE`
specifies a file name for logging all errors, warnings, etc., rather
than stderr
``MESA_TEX_PROG``
:envvar:`MESA_TEX_PROG`
if set, implement conventional texture environment modes with fragment
programs (intended for developers only)
``MESA_TNL_PROG``
:envvar:`MESA_TNL_PROG`
if set, implement conventional vertex transformation operations with
vertex programs (intended for developers only). Setting this variable
automatically sets the ``MESA_TEX_PROG`` variable as well.
``MESA_EXTENSION_OVERRIDE``
automatically sets the :envvar:`MESA_TEX_PROG` variable as well.
:envvar:`MESA_EXTENSION_OVERRIDE`
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.
``MESA_EXTENSION_MAX_YEAR``
:envvar:`MESA_EXTENSION_MAX_YEAR`
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
@@ -87,7 +87,7 @@ Core Mesa environment variables
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.
``MESA_GL_VERSION_OVERRIDE``
:envvar:`MESA_GL_VERSION_OVERRIDE`
changes the value returned by ``glGetString(GL_VERSION)`` and
possibly the GL API type.
@@ -127,7 +127,7 @@ Core Mesa environment variables
- Mesa may not really implement all the features of the given
version. (for developers only)
``MESA_GLES_VERSION_OVERRIDE``
:envvar:`MESA_GLES_VERSION_OVERRIDE`
changes the value returned by ``glGetString(GL_VERSION)`` for OpenGL
ES.
@@ -136,17 +136,17 @@ Core Mesa environment variables
- Mesa may not really implement all the features of the given
version. (for developers only)
``MESA_GLSL_VERSION_OVERRIDE``
:envvar:`MESA_GLSL_VERSION_OVERRIDE`
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)
``MESA_GLSL_CACHE_DISABLE``
:envvar:`MESA_GLSL_CACHE_DISABLE`
if set to ``true``, disables the GLSL shader cache. If set to
``false``, enables the GLSL shader cache when it is disabled by
default.
``MESA_GLSL_CACHE_MAX_SIZE``
:envvar:`MESA_GLSL_CACHE_MAX_SIZE`
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
@@ -160,22 +160,22 @@ Core Mesa environment variables
you may end up with a 1GB cache for x86_64 and another 1GB cache for
i386.
``MESA_GLSL_CACHE_DIR``
:envvar:`MESA_GLSL_CACHE_DIR`
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.
``MESA_GLSL``
:envvar:`MESA_GLSL`
:ref:`shading language compiler options <envvars>`
``MESA_NO_MINMAX_CACHE``
:envvar:`MESA_NO_MINMAX_CACHE`
when set, the minmax index cache is globally disabled.
``MESA_SHADER_CAPTURE_PATH``
:envvar:`MESA_SHADER_CAPTURE_PATH`
see :ref:`Capturing Shaders <capture>`
``MESA_SHADER_DUMP_PATH`` and ``MESA_SHADER_READ_PATH``
:envvar:`MESA_SHADER_DUMP_PATH` and :envvar:`MESA_SHADER_READ_PATH`
see :ref:`Experimenting with Shader
Replacements <replacement>`
``MESA_VK_VERSION_OVERRIDE``
:envvar:`MESA_VK_VERSION_OVERRIDE`
changes the Vulkan physical device version as returned in
``VkPhysicalDeviceProperties::apiVersion``.
@@ -184,7 +184,7 @@ Core Mesa environment variables
instance version as advertised by ``vkEnumerateInstanceVersion``
- This can be very useful for debugging but some features may not be
implemented correctly. (For developers only)
``MESA_LOADER_DRIVER_OVERRIDE``
:envvar:`MESA_LOADER_DRIVER_OVERRIDE`
chooses a different driver binary such as ``etnaviv`` or ``zink``.
NIR passes environment variables
@@ -194,13 +194,13 @@ The following are only applicable for drivers that uses NIR, as they
modify the behavior for the common ``NIR_PASS`` and ``NIR_PASS_V`` macros,
that wrap calls to NIR lowering/optimizations.
``NIR_PRINT``
:envvar:`NIR_PRINT`
If defined, the resulting NIR shader will be printed out at each
successful NIR lowering/optimization call.
``NIR_TEST_CLONE``
:envvar:`NIR_TEST_CLONE`
If defined, cloning a NIR shader would be tested at each successful
NIR lowering/optimization call.
``NIR_TEST_SERIALIZE``
:envvar:`NIR_TEST_SERIALIZE`
If defined, serialize and deserialize a NIR shader would be tested at
each successful NIR lowering/optimization call.
@@ -210,31 +210,31 @@ Mesa Xlib driver environment variables
The following are only applicable to the Mesa Xlib software driver. See
the :doc:`Xlib software driver page <xlibdriver>` for details.
``MESA_RGB_VISUAL``
:envvar:`MESA_RGB_VISUAL`
specifies the X visual and depth for RGB mode
``MESA_BACK_BUFFER``
:envvar:`MESA_BACK_BUFFER`
specifies how to implement the back color buffer, either ``pixmap``
or ``ximage``
``MESA_GAMMA``
:envvar:`MESA_GAMMA`
gamma correction coefficients for red, green, blue channels
``MESA_XSYNC``
:envvar:`MESA_XSYNC`
enable synchronous X behavior (for debugging only)
``MESA_GLX_FORCE_CI``
:envvar:`MESA_GLX_FORCE_CI`
if set, force GLX to treat 8 BPP visuals as CI visuals
``MESA_GLX_FORCE_ALPHA``
:envvar:`MESA_GLX_FORCE_ALPHA`
if set, forces RGB windows to have an alpha channel.
``MESA_GLX_DEPTH_BITS``
:envvar:`MESA_GLX_DEPTH_BITS`
specifies default number of bits for depth buffer.
``MESA_GLX_ALPHA_BITS``
:envvar:`MESA_GLX_ALPHA_BITS`
specifies default number of bits for alpha channel.
i945/i965 driver environment variables (non-Gallium)
----------------------------------------------------
``INTEL_NO_HW``
:envvar:`INTEL_NO_HW`
if set to 1, prevents batches from being submitted to the hardware.
This is useful for debugging hangs, etc.
``INTEL_DEBUG``
:envvar:`INTEL_DEBUG`
a comma-separated list of named flags, which do various things:
``ann``
@@ -330,26 +330,26 @@ i945/i965 driver environment variables (non-Gallium)
``vs``
dump shader assembly for vertex shaders
``INTEL_SCALAR_VS`` (or ``TCS``, ``TES``, ``GS``)
:envvar:`INTEL_SCALAR_VS` (or ``TCS``, ``TES``, ``GS``)
force scalar/vec4 mode for a shader stage (Gen8-9 only)
``INTEL_PRECISE_TRIG``
:envvar:`INTEL_PRECISE_TRIG`
if set to 1, true or yes, then the driver prefers accuracy over
performance in trig functions.
``INTEL_SHADER_ASM_READ_PATH``
:envvar:`INTEL_SHADER_ASM_READ_PATH`
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
corresponding ``INTEL_DEBUG`` flag (e.g. ``vs`` for vertex shader).
corresponding :envvar:`INTEL_DEBUG` flag (e.g. ``vs`` for vertex shader).
A binary could be generated from a dumped assembly by ``i965_asm``.
For ``INTEL_SHADER_ASM_READ_PATH`` to work it is necessary to enable
dumping of corresponding shader stages via ``INTEL_DEBUG``.
It is advised to use ``nocompact`` flag of ``INTEL_DEBUG`` when
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
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.
``INTEL_BLACKHOLE_DEFAULT``
:envvar:`INTEL_BLACKHOLE_DEFAULT`
if set to 1, true or yes, then the OpenGL implementation will
default ``GL_BLACKHOLE_RENDER_INTEL`` to true, thus disabling any
rendering.
@@ -358,7 +358,7 @@ i945/i965 driver environment variables (non-Gallium)
Radeon driver environment variables (radeon, r200, and r300g)
-------------------------------------------------------------
``RADEON_NO_TCL``
:envvar:`RADEON_NO_TCL`
if set, disable hardware-accelerated Transform/Clip/Lighting.
EGL environment variables
@@ -370,53 +370,53 @@ Mesa EGL supports different sets of environment variables. See the
Gallium environment variables
-----------------------------
``GALLIUM_HUD``
:envvar:`GALLIUM_HUD`
draws various information on the screen, like framerate, CPU load,
driver statistics, performance counters, etc. Set
``GALLIUM_HUD=help`` and run e.g. ``glxgears`` for more info.
``GALLIUM_HUD_PERIOD``
:envvar:`GALLIUM_HUD` to ``help`` and run e.g. ``glxgears`` for more info.
:envvar:`GALLIUM_HUD_PERIOD`
sets the HUD update rate in seconds (float). Use zero to update every
frame. The default period is 1/2 second.
``GALLIUM_HUD_VISIBLE``
:envvar:`GALLIUM_HUD_VISIBLE`
control default visibility, defaults to true.
``GALLIUM_HUD_TOGGLE_SIGNAL``
:envvar:`GALLIUM_HUD_TOGGLE_SIGNAL`
toggle visibility via user specified signal. Especially useful to
toggle HUD at specific points of application and disable for
unencumbered viewing the rest of the time. For example, set
``GALLIUM_HUD_VISIBLE`` to ``false`` and
``GALLIUM_HUD_TOGGLE_SIGNAL`` to ``10`` (``SIGUSR1``). Use
:envvar:`GALLIUM_HUD_VISIBLE` to ``false`` and
:envvar:`GALLIUM_HUD_TOGGLE_SIGNAL` to ``10`` (``SIGUSR1``). Use
``kill -10 <pid>`` to toggle the HUD as desired.
``GALLIUM_HUD_SCALE``
:envvar:`GALLIUM_HUD_SCALE`
Scale HUD by an integer factor, for high DPI displays. Default is 1.
``GALLIUM_HUD_DUMP_DIR``
:envvar:`GALLIUM_HUD_DUMP_DIR`
specifies a directory for writing the displayed HUD values into
files.
``GALLIUM_DRIVER``
useful in combination with ``LIBGL_ALWAYS_SOFTWARE=true`` for
:envvar:`GALLIUM_DRIVER`
useful in combination with :envvar:`LIBGL_ALWAYS_SOFTWARE`=`true` for
choosing one of the software renderers ``softpipe``, ``llvmpipe`` or
``swr``.
``GALLIUM_LOG_FILE``
:envvar:`GALLIUM_LOG_FILE`
specifies a file for logging all errors, warnings, etc. rather than
stderr.
``GALLIUM_PIPE_SEARCH_DIR``
:envvar:`GALLIUM_PIPE_SEARCH_DIR`
specifies an alternate search directory for pipe-loader which overrides
the compile-time path based on the install location.
``GALLIUM_PRINT_OPTIONS``
:envvar:`GALLIUM_PRINT_OPTIONS`
if non-zero, print all the Gallium environment variables which are
used, and their current values.
``GALLIUM_DUMP_CPU``
:envvar:`GALLIUM_DUMP_CPU`
if non-zero, print information about the CPU on start-up
``TGSI_PRINT_SANITY``
:envvar:`TGSI_PRINT_SANITY`
if set, do extra sanity checking on TGSI shaders and print any errors
to stderr.
``DRAW_FSE``
:envvar:`DRAW_FSE`
???
``DRAW_NO_FSE``
:envvar:`DRAW_NO_FSE`
???
``DRAW_USE_LLVM``
:envvar:`DRAW_USE_LLVM`
if set to zero, the draw module will not use LLVM to execute shaders,
vertex fetch, etc.
``ST_DEBUG``
:envvar:`ST_DEBUG`
controls debug output from the Mesa/Gallium state tracker. Setting to
``tgsi``, for example, will print all the TGSI shaders. See
:file:`src/mesa/state_tracker/st_debug.c` for other options.
@@ -424,15 +424,15 @@ Gallium environment variables
Clover environment variables
----------------------------
``CLOVER_EXTRA_BUILD_OPTIONS``
:envvar:`CLOVER_EXTRA_BUILD_OPTIONS`
allows specifying additional compiler and linker options. Specified
options are appended after the options set by the OpenCL program in
``clBuildProgram``.
``CLOVER_EXTRA_COMPILE_OPTIONS``
:envvar:`CLOVER_EXTRA_COMPILE_OPTIONS`
allows specifying additional compiler options. Specified options are
appended after the options set by the OpenCL program in
``clCompileProgram``.
``CLOVER_EXTRA_LINK_OPTIONS``
:envvar:`CLOVER_EXTRA_LINK_OPTIONS`
allows specifying additional linker options. Specified options are
appended after the options set by the OpenCL program in
``clLinkProgram``.
@@ -440,7 +440,7 @@ Clover environment variables
Softpipe driver environment variables
-------------------------------------
``SOFTPIPE_DEBUG``
:envvar:`SOFTPIPE_DEBUG`
a comma-separated list of named flags, which do various things:
``vs``
@@ -463,15 +463,15 @@ Softpipe driver environment variables
LLVMpipe driver environment variables
-------------------------------------
``LP_NO_RAST``
:envvar:`LP_NO_RAST`
if set LLVMpipe will no-op rasterization
``LP_DEBUG``
:envvar:`LP_DEBUG`
a comma-separated list of debug options is accepted. See the source
code for details.
``LP_PERF``
:envvar:`LP_PERF`
a comma-separated list of options to selectively no-op various parts
of the driver. See the source code for details.
``LP_NUM_THREADS``
:envvar:`LP_NUM_THREADS`
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.
@@ -479,17 +479,17 @@ LLVMpipe driver environment variables
VMware SVGA driver environment variables
----------------------------------------
``SVGA_FORCE_SWTNL``
:envvar`SVGA_FORCE_SWTNL`
force use of software vertex transformation
``SVGA_NO_SWTNL``
:envvar`SVGA_NO_SWTNL`
don't allow software vertex transformation fallbacks (will often
result in incorrect rendering).
``SVGA_DEBUG``
:envvar`SVGA_DEBUG`
for dumping shaders, constant buffers, etc. See the code for details.
``SVGA_EXTRA_LOGGING``
:envvar`SVGA_EXTRA_LOGGING`
if set, enables extra logging to the ``vmware.log`` file, such as the
OpenGL program's name and command line arguments.
``SVGA_NO_LOGGING``
:envvar`SVGA_NO_LOGGING`
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.
@@ -499,7 +499,7 @@ See the driver code for other, lesser-used variables.
WGL environment variables
-------------------------
``WGL_SWAP_INTERVAL``
:envvar:`WGL_SWAP_INTERVAL`
to set a swap interval, equivalent to calling
``wglSwapIntervalEXT()`` in an application. If this environment
variable is set, application calls to ``wglSwapIntervalEXT()`` will
@@ -508,13 +508,13 @@ WGL environment variables
VA-API environment variables
----------------------------
``VAAPI_MPEG4_ENABLED``
:envvar:`VAAPI_MPEG4_ENABLED`
enable MPEG4 for VA-API, disabled by default.
VC4 driver environment variables
--------------------------------
``VC4_DEBUG``
:envvar:`VC4_DEBUG`
a comma-separated list of named flags, which do various things:
``cl``
@@ -543,7 +543,7 @@ VC4 driver environment variables
RADV driver environment variables
---------------------------------
``RADV_DEBUG``
:envvar:`RADV_DEBUG`
a comma-separated list of named flags, which do various things:
``llvm``
@@ -596,7 +596,8 @@ RADV driver environment variables
``notccompatcmask``
disable TC-compat CMASK for MSAA surfaces
``noumr``
disable UMR dumps during GPU hang detection (only with RADV_DEBUG=hang)
disable UMR dumps during GPU hang detection (only with
:envvar:`RADV_DEBUG`=``hang``)
``novrsflatshading``
disable VRS for flat shading (only on GFX10.3+)
``preoptir``
@@ -616,15 +617,15 @@ RADV driver environment variables
``zerovram``
initialize all memory allocated in VRAM as zero
``RADV_FORCE_FAMILY``
:envvar:`RADV_FORCE_FAMILY`
create a null device to compile shaders without a AMD GPU (e.g. vega10)
``RADV_FORCE_VRS``
:envvar:`RADV_FORCE_VRS`
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.
``RADV_PERFTEST``
:envvar:`RADV_PERFTEST`
a comma-separated list of named flags, which do various things:
``bolist``
@@ -644,9 +645,10 @@ RADV driver environment variables
``sam``
enable optimizations to move more driver internal objects to VRAM.
``RADV_TEX_ANISO``
:envvar`RADV_TEX_ANISO`
force anisotropy filter (up to 16)
``ACO_DEBUG``
:envvar:`ACO_DEBUG`
a comma-separated list of named flags, which do various things:
``validateir``
@@ -672,7 +674,7 @@ RADV driver environment variables
radeonsi driver environment variables
-------------------------------------
``AMD_DEBUG``
:envvar:`AMD_DEBUG`
a comma-separated list of named flags, which do various things:
``nodcc``
@@ -775,7 +777,7 @@ radeonsi driver environment variables
r600 driver environment variables
---------------------------------
``R600_DEBUG``
:envvar:`R600_DEBUG`
a comma-separated list of named flags, which do various things:
``nocpdma``
@@ -865,15 +867,15 @@ r600 driver environment variables
``unsafemath``
Enable unsafe math shader optimizations
``R600_DEBUG_COMPUTE``
:envvar:`R600_DEBUG_COMPUTE`
if set to ``true``, various compute-related debug information will
be printed to stderr. Defaults to ``false``.
``R600_DUMP_SHADERS``
:envvar:`R600_DUMP_SHADERS`
if set to ``true``, NIR shaders will be printed to stderr. Defaults
to ``false``.
``R600_HYPERZ``
:envvar:`R600_HYPERZ`
If set to ``false``, disables HyperZ optimizations. Defaults to ``true``.
``R600_NIR_DEBUG``
:envvar:`R600_NIR_DEBUG`
a comma-separated list of named flags, which do various things:
``instr``