diff --git a/docs/drivers/llvmpipe.rst b/docs/drivers/llvmpipe.rst index 1c8fb6ce903..9884b1889d8 100644 --- a/docs/drivers/llvmpipe.rst +++ b/docs/drivers/llvmpipe.rst @@ -90,11 +90,14 @@ Using Environment variables ~~~~~~~~~~~~~~~~~~~~~ -``LP_NATIVE_VECTOR_WIDTH`` +.. envvar:: LP_NATIVE_VECTOR_WIDTH + We can use it to override vector bits. Because sometimes it turns out LLVMpipe can be fastest by using 128 bit vectors, yet use AVX instructions. -``GALLIUM_OVERRIDE_CPU_CAPS`` + +.. envvar:: GALLIUM_OVERRIDE_CPU_CAPS + Override CPU capabilities for LLVMpipe and Softpipe, possible values for x86: ``nosse`` ``sse`` @@ -103,10 +106,14 @@ Environment variables ``ssse3`` ``sse4.1`` ``avx`` -``GALLIUM_NOSSE`` + +.. envvar:: GALLIUM_NOSSE + Deprecated in favor of ``GALLIUM_OVERRIDE_CPU_CAPS``, use ``GALLIUM_OVERRIDE_CPU_CAPS=nosse`` instead. -``LP_FORCE_SSE2`` + +.. envvar:: LP_FORCE_SSE2 + Deprecated in favor of ``GALLIUM_OVERRIDE_CPU_CAPS`` use ``GALLIUM_OVERRIDE_CPU_CAPS=sse2`` instead. diff --git a/docs/envvars.rst b/docs/envvars.rst index db47503cff2..6dafec7771c 100644 --- a/docs/envvars.rst +++ b/docs/envvars.rst @@ -8,42 +8,68 @@ but they can sometimes be useful for debugging end-user issues. LibGL environment variables --------------------------- -:envvar:`LIBGL_DEBUG` +.. envvar:: LIBGL_DEBUG + If defined debug information will be printed to stderr. If set to ``verbose`` additional information will be printed. -:envvar:`LIBGL_DRIVERS_PATH` + +.. envvar:: LIBGL_DRIVERS_PATH + colon-separated list of paths to search for DRI drivers -:envvar:`LIBGL_ALWAYS_INDIRECT` + +.. envvar:: LIBGL_ALWAYS_INDIRECT + if set to ``true``, forces an indirect rendering context/connection. -:envvar:`LIBGL_ALWAYS_SOFTWARE` + +.. envvar:: LIBGL_ALWAYS_SOFTWARE + if set to ``true``, always use software rendering -:envvar:`LIBGL_NO_DRAWARRAYS` + +.. envvar:: LIBGL_NO_DRAWARRAYS + if set to ``true``, do not use DrawArrays GLX protocol (for debugging) -:envvar:`LIBGL_SHOW_FPS` + +.. envvar:: LIBGL_SHOW_FPS + print framerate to stdout based on the number of ``glXSwapBuffers`` calls per second. -:envvar:`LIBGL_DRI2_DISABLE` + +.. envvar:: LIBGL_DRI2_DISABLE + disable DRI2 if set to ``true``. -:envvar:`LIBGL_DRI3_DISABLE` + +.. envvar:: LIBGL_DRI3_DISABLE + disable DRI3 if set to ``true``. Core Mesa environment variables ------------------------------- -:envvar:`MESA_NO_ASM` +.. envvar:: MESA_NO_ASM + if set, disables all assembly language optimizations -:envvar:`MESA_NO_MMX` + +.. envvar:: MESA_NO_MMX + if set, disables Intel MMX optimizations -:envvar:`MESA_NO_3DNOW` + +.. envvar:: MESA_NO_3DNOW + if set, disables AMD 3DNow! optimizations -:envvar:`MESA_NO_SSE` + +.. envvar:: MESA_NO_SSE + if set, disables Intel SSE optimizations -:envvar:`MESA_NO_ERROR` + +.. envvar:: MESA_NO_ERROR + if set to 1, error checking is disabled as per :ext:`GL_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. -:envvar:`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, @@ -65,15 +91,20 @@ Core Mesa environment variables print error and performance messages to stderr (or ``MESA_LOG_FILE``). -:envvar:`MESA_LOG_FILE` +.. envvar:: MESA_LOG_FILE + specifies a file name for logging all errors, warnings, etc., rather than stderr -:envvar:`MESA_EXTENSION_OVERRIDE` + +.. 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. Note that this will override extensions override configured using driconf. -:envvar:`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 @@ -81,7 +112,9 @@ 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. -:envvar:`MESA_GL_VERSION_OVERRIDE` + +.. envvar:: MESA_GL_VERSION_OVERRIDE + changes the value returned by ``glGetString(GL_VERSION)`` and possibly the GL API type. @@ -121,7 +154,8 @@ Core Mesa environment variables - Mesa may not really implement all the features of the given version. (for developers only) -:envvar:`MESA_GLES_VERSION_OVERRIDE` +.. envvar:: MESA_GLES_VERSION_OVERRIDE + changes the value returned by ``glGetString(GL_VERSION)`` for OpenGL ES. @@ -130,17 +164,22 @@ Core Mesa environment variables - Mesa may not really implement all the features of the given version. (for developers only) -:envvar:`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) -:envvar:`MESA_SHADER_CACHE_DISABLE` + +.. envvar:: MESA_SHADER_CACHE_DISABLE + if set to ``true``, disables the on-disk shader cache. If set to ``false``, enables the on-disk shader cache when it is disabled by default. -:envvar:`MESA_SHADER_CACHE_MAX_SIZE` + +.. envvar:: MESA_SHADER_CACHE_MAX_SIZE + if set, determines the maximum size of the on-disk cache of compiled shader programs. Should be set to a number optionally followed by ``K``, ``M``, or ``G`` to specify a size in kilobytes, megabytes, or @@ -154,25 +193,41 @@ Core Mesa environment variables you may end up with a 1GB cache for x86_64 and another 1GB cache for i386. -:envvar:`MESA_SHADER_CACHE_DIR` +.. envvar:: MESA_SHADER_CACHE_DIR + if set, determines the directory to be used for the on-disk cache of compiled shader 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. -:envvar:`MESA_SHADER_CACHE_SHOW_STATS` + +.. envvar:: MESA_SHADER_CACHE_SHOW_STATS + if set to ``true``, keeps hit/miss statistics for the shader cache. These statistics are printed when the app terminates. -:envvar:`MESA_GLSL` + +.. envvar:: MESA_GLSL + :ref:`shading language compiler options ` -:envvar:`MESA_NO_MINMAX_CACHE` + +.. envvar:: MESA_NO_MINMAX_CACHE + when set, the minmax index cache is globally disabled. -:envvar:`MESA_SHADER_CAPTURE_PATH` + +.. envvar:: MESA_SHADER_CAPTURE_PATH + see :ref:`Capturing Shaders ` -:envvar:`MESA_SHADER_DUMP_PATH` and :envvar:`MESA_SHADER_READ_PATH` - see :ref:`Experimenting with Shader - Replacements ` -:envvar:`MESA_VK_VERSION_OVERRIDE` + +.. envvar:: MESA_SHADER_DUMP_PATH + + see :ref:`Experimenting with Shader Replacements ` + +.. envvar:: MESA_SHADER_READ_PATH + + see :ref:`Experimenting with Shader Replacements ` + +.. envvar:: MESA_VK_VERSION_OVERRIDE + changes the Vulkan physical device version as returned in ``VkPhysicalDeviceProperties::apiVersion``. @@ -181,21 +236,31 @@ 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) -:envvar:`MESA_VK_WSI_PRESENT_MODE` + +.. envvar:: MESA_VK_WSI_PRESENT_MODE + overrides the WSI present mode clients specify in ``VkSwapchainCreateInfoKHR::presentMode``. Values can be ``fifo``, ``relaxed``, ``mailbox`` or ``immediate``. -:envvar:`MESA_VK_ABORT_ON_DEVICE_LOSS` + +.. envvar:: MESA_VK_ABORT_ON_DEVICE_LOSS + causes the Vulkan driver to call abort() immediately after detecting a lost device. This is extremely useful when testing as it prevents the test suite from continuing on with a lost device. -:envvar:`MESA_VK_ENABLE_SUBMIT_THREAD` + +.. envvar:: MESA_VK_ENABLE_SUBMIT_THREAD + for Vulkan drivers which support real timeline semaphores, this forces them to use a submit thread from the beginning, regardless of whether or not they ever see a wait-before-signal condition. -:envvar:`MESA_LOADER_DRIVER_OVERRIDE` + +.. envvar:: MESA_LOADER_DRIVER_OVERRIDE + chooses a different driver binary such as ``etnaviv`` or ``zink``. -:envvar:`DRI_PRIME` + +.. envvar:: DRI_PRIME + the default GPU is the one used by Wayland/Xorg or the one connected to a display. This variable allows to select a different GPU. It applies to OpenGL and Vulkan (in this case "select" means the GPU will be first in the reported @@ -216,10 +281,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. -:envvar:`NIR_DEBUG` +.. envvar:: NIR_DEBUG + a comma-separated list of debug options to apply to NIR shaders. Use ``NIR_DEBUG=help`` to print a list of available options. -:envvar:`NIR_SKIP` + +.. envvar:: NIR_SKIP + a comma-separated list of optimization/lowering passes to skip. Mesa Xlib driver environment variables @@ -228,18 +296,29 @@ 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. -:envvar:`MESA_RGB_VISUAL` +.. envvar:: MESA_RGB_VISUAL + specifies the X visual and depth for RGB mode -:envvar:`MESA_BACK_BUFFER` + +.. envvar:: MESA_BACK_BUFFER + specifies how to implement the back color buffer, either ``pixmap`` or ``ximage`` -:envvar:`MESA_XSYNC` + +.. envvar:: MESA_XSYNC + enable synchronous X behavior (for debugging only) -:envvar:`MESA_GLX_FORCE_ALPHA` + +.. envvar:: MESA_GLX_FORCE_ALPHA + if set, forces RGB windows to have an alpha channel. -:envvar:`MESA_GLX_DEPTH_BITS` + +.. envvar:: MESA_GLX_DEPTH_BITS + specifies default number of bits for depth buffer. -:envvar:`MESA_GLX_ALPHA_BITS` + +.. envvar:: MESA_GLX_ALPHA_BITS + specifies default number of bits for alpha channel. Mesa WGL driver environment variables @@ -248,27 +327,35 @@ Mesa WGL driver environment variables The following are only applicable to the Mesa WGL driver, which is in use on Windows. -:envvar:`WGL_FORCE_MSAA` +.. envvar:: WGL_FORCE_MSAA + if set to a positive value, specifies the number of MSAA samples to force when choosing the display configuration. -:envvar:`WGL_DISABLE_ERROR_DIALOGS` + +.. envvar:: WGL_DISABLE_ERROR_DIALOGS + if set to 1, true or yes, disables Win32 error dialogs. Useful for automated test-runs. Intel driver environment variables ---------------------------------------------------- -:envvar:`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. -:envvar:`INTEL_COMPUTE_CLASS` + +.. envvar:: INTEL_COMPUTE_CLASS + If set to 1, true or yes, then I915_ENGINE_CLASS_COMPUTE will be supported. For OpenGL, iris will attempt to use a compute engine for compute dispatches if one is detected. For Vulkan, anvil will advertise support for a compute queue if a compute engine is detected. -:envvar:`INTEL_DEBUG` + +.. envvar:: INTEL_DEBUG + a comma-separated list of named flags, which do various things: ``ann`` @@ -377,7 +464,8 @@ Intel driver environment variables ``wm`` dump shader assembly for fragment shaders (same as ``fs``) -:envvar:`INTEL_MEASURE` +.. envvar:: INTEL_MEASURE + Collects GPU timestamps over common intervals, and generates a CSV report to show how long rendering took. The overhead of collection is limited to the flushing that is required at the interval boundaries for accurate @@ -433,13 +521,19 @@ Intel driver environment variables start and end event will be submitted to the GPU to minimize stalling. Combined events will not span batches, except in the case of ``INTEL_MEASURE=frame``. -:envvar:`INTEL_NO_HW` + +.. envvar:: INTEL_NO_HW + if set to 1, true or yes, prevents batches from being submitted to the hardware. This is useful for debugging hangs, etc. -:envvar:`INTEL_PRECISE_TRIG` + +.. envvar:: INTEL_PRECISE_TRIG + if set to 1, true or yes, then the driver prefers accuracy over performance in trig functions. -:envvar:`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``. @@ -458,19 +552,23 @@ Intel driver environment variables DRI environment variables ------------------------- -:envvar:`DRI_NO_MSAA` +.. envvar:: DRI_NO_MSAA + disable MSAA for GLX/EGL MSAA visuals Vulkan mesa device select layer environment variables ----------------------------------------------------- -:envvar:`MESA_VK_DEVICE_SELECT` +.. envvar:: MESA_VK_DEVICE_SELECT + when set to "list" prints the list of devices. when set to "vid:did" number from PCI device. That PCI device is selected as default. The default device is returned as the first device in vkEnumeratePhysicalDevices API. -:envvar:`MESA_VK_DEVICE_SELECT_FORCE_DEFAULT_DEVICE` + +.. envvar:: MESA_VK_DEVICE_SELECT_FORCE_DEFAULT_DEVICE + when set to 1, the device identified as default will be the only one returned in vkEnumeratePhysicalDevices API. @@ -484,53 +582,84 @@ Mesa EGL supports different sets of environment variables. See the Gallium environment variables ----------------------------- -:envvar:`GALLIUM_HUD` +.. envvar:: GALLIUM_HUD + draws various information on the screen, like framerate, CPU load, driver statistics, performance counters, etc. Set :envvar:`GALLIUM_HUD` to ``help`` and run e.g. ``glxgears`` for more info. -:envvar:`GALLIUM_HUD_PERIOD` + +.. 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. -:envvar:`GALLIUM_HUD_VISIBLE` + +.. envvar:: GALLIUM_HUD_VISIBLE + control default visibility, defaults to true. -:envvar:`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 :envvar:`GALLIUM_HUD_VISIBLE` to ``false`` and :envvar:`GALLIUM_HUD_TOGGLE_SIGNAL` to ``10`` (``SIGUSR1``). Use ``kill -10 `` to toggle the HUD as desired. -:envvar:`GALLIUM_HUD_SCALE` + +.. envvar:: GALLIUM_HUD_SCALE + Scale HUD by an integer factor, for high DPI displays. Default is 1. -:envvar:`GALLIUM_HUD_DUMP_DIR` + +.. envvar:: GALLIUM_HUD_DUMP_DIR + specifies a directory for writing the displayed HUD values into files. -:envvar:`GALLIUM_DRIVER` + +.. envvar:: GALLIUM_DRIVER + useful in combination with :envvar:`LIBGL_ALWAYS_SOFTWARE`=`true` for choosing one of the software renderers ``softpipe`` or ``llvmpipe``. -:envvar:`GALLIUM_LOG_FILE` + +.. envvar:: GALLIUM_LOG_FILE + specifies a file for logging all errors, warnings, etc. rather than stderr. -:envvar:`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. -:envvar:`GALLIUM_PRINT_OPTIONS` + +.. envvar:: GALLIUM_PRINT_OPTIONS + if non-zero, print all the Gallium environment variables which are used, and their current values. -:envvar:`GALLIUM_DUMP_CPU` + +.. envvar:: GALLIUM_DUMP_CPU + if non-zero, print information about the CPU on start-up -:envvar:`TGSI_PRINT_SANITY` + +.. envvar:: TGSI_PRINT_SANITY + if set, do extra sanity checking on TGSI shaders and print any errors to stderr. -:envvar:`DRAW_FSE` + +.. envvar:: DRAW_FSE + Enable fetch-shade-emit middle-end even though its not correct (e.g. for Softpipe) -:envvar:`DRAW_NO_FSE` + +.. envvar:: DRAW_NO_FSE + Disable fetch-shade-emit middle-end even when it is correct -:envvar:`DRAW_USE_LLVM` + +.. envvar:: DRAW_USE_LLVM + if set to zero, the draw module will not use LLVM to execute shaders, vertex fetch, etc. -:envvar:`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. @@ -538,15 +667,20 @@ Gallium environment variables Clover environment variables ---------------------------- -:envvar:`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``. -:envvar:`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``. -:envvar:`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``. @@ -554,13 +688,18 @@ Clover environment variables Rusticl environment variables ----------------------------- -:envvar:`RUSTICL_DEVICE_TYPE` +.. envvar:: RUSTICL_DEVICE_TYPE + allows to overwrite the device type of devices. Possible values are ``accelerator``, ``cpu``, ``custom`` and ``gpu`` -:envvar:`RUSTICL_CL_VERSION` + +.. envvar:: RUSTICL_CL_VERSION + overwrites the auto detected OpenCL version of all devices. Specified as ``major.minor``. -:envvar:`RUSTICL_ENABLE` + +.. envvar:: RUSTICL_ENABLE + a comma-separated list of drivers to enable CL on. An optional list of comma-separated integers can be passed per driver to specify which devices to enable. Examples: @@ -572,28 +711,34 @@ Rusticl environment variables Nine frontend environment variables ----------------------------------- -:envvar:`D3D_ALWAYS_SOFTWARE` +.. envvar:: D3D_ALWAYS_SOFTWARE + an integer, which forces Nine to use the CPU instead of GPU acceleration. -:envvar:`NINE_DEBUG` +.. envvar:: NINE_DEBUG + a comma-separated list of named flags that do debugging things. Use ``NINE_DEBUG=help`` to print a list of available options. -:envvar:`NINE_FF_DUMP` +.. envvar:: NINE_FF_DUMP + a boolean, which dumps shaders generated by a fixed function (FF). -:envvar:`NINE_SHADER` +.. envvar:: NINE_SHADER + a comma-separated list of named flags, which do alternate shader handling. Use ``NINE_SHADER=help`` to print a list of available options. -:envvar:`NINE_QUIRKS` +.. envvar:: NINE_QUIRKS + a comma-separated list of named flags that do various things. Use ``NINE_DEBUG=help`` to print a list of available options. Softpipe driver environment variables ------------------------------------- -:envvar:`SOFTPIPE_DEBUG` +.. envvar:: SOFTPIPE_DEBUG + a comma-separated list of named flags, which do various things: ``vs`` @@ -616,15 +761,22 @@ Softpipe driver environment variables LLVMpipe driver environment variables ------------------------------------- -:envvar:`LP_NO_RAST` +.. envvar:: LP_NO_RAST + if set LLVMpipe will no-op rasterization -:envvar:`LP_DEBUG` + +.. envvar:: LP_DEBUG + a comma-separated list of debug options is accepted. See the source code for details. -:envvar:`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. -:envvar:`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. @@ -632,17 +784,26 @@ LLVMpipe driver environment variables VMware SVGA driver environment variables ---------------------------------------- -:envvar:`SVGA_FORCE_SWTNL` +.. envvar:: SVGA_FORCE_SWTNL + force use of software vertex transformation -:envvar:`SVGA_NO_SWTNL` + +.. envvar:: SVGA_NO_SWTNL + don't allow software vertex transformation fallbacks (will often result in incorrect rendering). -:envvar:`SVGA_DEBUG` + +.. envvar:: SVGA_DEBUG + for dumping shaders, constant buffers, etc. See the code for details. -:envvar:`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. -:envvar:`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. @@ -652,7 +813,8 @@ See the driver code for other, lesser-used variables. WGL environment variables ------------------------- -:envvar:`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 @@ -661,13 +823,15 @@ WGL environment variables VA-API environment variables ---------------------------- -:envvar:`VAAPI_MPEG4_ENABLED` +.. envvar:: VAAPI_MPEG4_ENABLED + enable MPEG4 for VA-API, disabled by default. VC4 driver environment variables -------------------------------- -:envvar:`VC4_DEBUG` +.. envvar:: VC4_DEBUG + a comma-separated list of named flags, which do various things. Use ``VC4_DEBUG=help`` to print a list of available options. @@ -675,9 +839,10 @@ VC4 driver environment variables V3D/V3DV driver environment variables ------------------------------------- -:envvar:`V3D_DEBUG` - a comma-separated list of debug options. Use ``V3D_DEBUG=help`` to - print a list of available options. +.. envvar:: V3D_DEBUG + + a comma-separated list of debug options. Use ``V3D_DEBUG=help`` to + print a list of available options. .. _radv env-vars: @@ -685,7 +850,8 @@ V3D/V3DV driver environment variables RADV driver environment variables --------------------------------- -:envvar:`RADV_DEBUG` +.. envvar:: RADV_DEBUG + a comma-separated list of named flags, which do various things: ``llvm`` @@ -767,19 +933,23 @@ RADV driver environment variables ``zerovram`` initialize all memory allocated in VRAM as zero -:envvar:`RADV_FORCE_FAMILY` +.. envvar:: RADV_FORCE_FAMILY + create a null device to compile shaders without a AMD GPU (e.g. VEGA10) -:envvar:`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 explicitly use VRS or flat shading. The supported values are 2x2, 1x2, 2x1 and 1x1. Only for testing purposes. -:envvar:`RADV_FORCE_VRS_CONFIG_FILE` +.. envvar:: RADV_FORCE_VRS_CONFIG_FILE + similar to ``RADV_FORCE_VRS`` but allow to configure from a file. If present, this supersedes ``RADV_FORCE_VRS``. -:envvar:`RADV_PERFTEST` +.. envvar:: RADV_PERFTEST + a comma-separated list of named flags, which do various things: ``bolist`` @@ -815,42 +985,52 @@ RADV driver environment variables ``rtwave64`` enable wave64 for ray tracing shaders (GFX10+) -:envvar:`RADV_TEX_ANISO` +.. envvar:: RADV_TEX_ANISO + force anisotropy filter (up to 16) -:envvar:`RADV_THREAD_TRACE` +.. envvar:: RADV_THREAD_TRACE + enable frame based SQTT/RGP captures (e.g. ``export RADV_THREAD_TRACE=100`` will capture the frame #100) -:envvar:`RADV_THREAD_TRACE_BUFFER_SIZE` +.. envvar:: RADV_THREAD_TRACE_BUFFER_SIZE + set the SQTT/RGP buffer size in bytes (default value is 32MiB, the buffer is automatically resized if too small) -:envvar:`RADV_THREAD_TRACE_CACHE_COUNTERS` +.. envvar:: RADV_THREAD_TRACE_CACHE_COUNTERS + enable/disable SQTT/RGP cache counters on GFX10+ (disabled by default) -:envvar:`RADV_THREAD_TRACE_INSTRUCTION_TIMING` +.. envvar:: RADV_THREAD_TRACE_INSTRUCTION_TIMING + enable/disable SQTT/RGP instruction timing (enabled by default) -:envvar:`RADV_THREAD_TRACE_TRIGGER` +.. envvar:: RADV_THREAD_TRACE_TRIGGER + enable trigger file based SQTT/RGP captures (e.g. ``export RADV_THREAD_TRACE_TRIGGER=/tmp/radv_sqtt_trigger`` and then ``touch /tmp/radv_sqtt_trigger`` to capture a frame) -:envvar:`RADV_RRA_TRACE` +.. envvar:: RADV_RRA_TRACE + enable frame based Radeon Raytracing Analyzer captures (e.g. ``export RADV_RRA_TRACE=100`` will capture the frame #100) -:envvar:`RADV_RRA_TRACE_TRIGGER` +.. envvar:: RADV_RRA_TRACE_TRIGGER + enable trigger file based RRA captures (e.g. ``export RADV_RRA_TRACE_TRIGGER=/tmp/radv_rra_trigger`` and then ``touch /tmp/radv_rra_trigger`` to capture a frame) -:envvar:`RADV_RRA_TRACE_VALIDATE` +.. envvar:: RADV_RRA_TRACE_VALIDATE + enable validation of captured acceleration structures. Can be useful if RRA crashes upon opening a trace. -:envvar:`ACO_DEBUG` +.. envvar:: ACO_DEBUG + a comma-separated list of named flags, which do various things: ``validateir`` @@ -878,16 +1058,20 @@ RADV driver environment variables RadeonSI driver environment variables ------------------------------------- -:envvar:`radeonsi_no_infinite_interp` +.. envvar:: radeonsi_no_infinite_interp + Kill PS with infinite interp coeff (might fix hangs) -:envvar:`radeonsi_clamp_div_by_zero` +.. envvar:: radeonsi_clamp_div_by_zero + Clamp div by zero (x / 0 becomes FLT_MAX instead of NaN) (might fix rendering corruptions) -:envvar:`radeonsi_zerovram` +.. envvar:: radeonsi_zerovram + Clear all allocated memory to 0 before usage (might fix rendering corruptions) -:envvar:`AMD_DEBUG` +.. envvar:: AMD_DEBUG + a comma-separated list of named flags, which do various things: ``nodcc`` @@ -982,7 +1166,8 @@ RadeonSI driver environment variables r600 driver environment variables --------------------------------- -:envvar:`R600_DEBUG` +.. envvar:: R600_DEBUG + a comma-separated list of named flags, which do various things: ``nocpdma`` @@ -1072,15 +1257,22 @@ r600 driver environment variables ``unsafemath`` Enable unsafe math shader optimizations -:envvar:`R600_DEBUG_COMPUTE` +.. envvar:: R600_DEBUG_COMPUTE + if set to ``true``, various compute-related debug information will be printed to stderr. Defaults to ``false``. -:envvar:`R600_DUMP_SHADERS` + +.. envvar:: R600_DUMP_SHADERS + if set to ``true``, NIR shaders will be printed to stderr. Defaults to ``false``. -:envvar:`R600_HYPERZ` + +.. envvar:: R600_HYPERZ + If set to ``false``, disables HyperZ optimizations. Defaults to ``true``. -:envvar:`R600_NIR_DEBUG` + +.. envvar:: R600_NIR_DEBUG + a comma-separated list of named flags, which do various things: ``instr`` @@ -1113,7 +1305,8 @@ r600 driver environment variables r300 driver environment variables --------------------------------- -:envvar:`RADEON_DEBUG` +.. envvar:: RADEON_DEBUG + a comma-separated list of named flags, which do various things: ``info`` @@ -1170,7 +1363,8 @@ r300 driver environment variables Asahi driver environment variables ---------------------------------- -:envvar:`ASAHI_MESA_DEBUG` +.. envvar:: ASAHI_MESA_DEBUG + a comma-separated list of named flags, which do various things: ``trace`` @@ -1186,7 +1380,8 @@ Asahi driver environment variables ``dirty`` In debug builds only: disable dirty tracking optimizations. -:envvar:`AGX_MESA_DEBUG` +.. envvar:: AGX_MESA_DEBUG + a comma-separated list of named flags, which do various things: ``shaders`` diff --git a/docs/u_trace.rst b/docs/u_trace.rst index 9e8acdfc131..9bbeb153cdc 100644 --- a/docs/u_trace.rst +++ b/docs/u_trace.rst @@ -21,7 +21,8 @@ Usage u_trace is controlled by environment variables: -:envvar:`MESA_GPU_TRACES` +.. envvar:: MESA_GPU_TRACES + controls whether u_trace is enabled and trace output ``print`` @@ -44,10 +45,12 @@ u_trace is controlled by environment variables: - For Turnip, ``cffdump`` can be used to view the markers in the trace. -:envvar:`MESA_GPU_TRACEFILE` +.. envvar:: MESA_GPU_TRACEFILE + specifies a file where to write the output instead of ``stdout`` -:envvar:`*_GPU_TRACEPOINT` +.. envvar:: *_GPU_TRACEPOINT + tracepoints can be enabled or disabled using driver specific environment variable. Most tracepoints are enabled by default. For instance ``TU_GPU_TRACEPOINT=-blit,+render_pass`` will disable the @@ -60,8 +63,8 @@ u_trace is controlled by environment variables: - Environment Variable - Tracepoint Definitions * - Freedreno - - :envvar:`FD_GPU_TRACEPOINT` + - .. envvar:: FD_GPU_TRACEPOINT - ``src/gallium/drivers/freedreno/freedreno_tracepoints.py`` * - Turnip - - :envvar:`TU_GPU_TRACEPOINT` + - .. envvar:: TU_GPU_TRACEPOINT - ``src/freedreno/vulkan/tu_tracepoints.py``