From d4397c00485d8edb35d519e7036405527bb3e746 Mon Sep 17 00:00:00 2001 From: Erik Faye-Lund Date: Tue, 1 Jun 2021 11:30:08 +0200 Subject: [PATCH] docs: use envvar role for envvars Reviewed-by: Chia-I Wu Part-of: --- docs/envvars.rst | 214 ++++++++++++++++++++++++----------------------- 1 file changed, 108 insertions(+), 106 deletions(-) diff --git a/docs/envvars.rst b/docs/envvars.rst index 46595e78006..20e090e7f9c 100644 --- a/docs/envvars.rst +++ b/docs/envvars.rst @@ -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 ` -``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 ` -``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 ` -``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 ` 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 " 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 `` 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``