1Debugging 2========= 3 4Debugging utilities in gallium. 5 6Debug Variables 7^^^^^^^^^^^^^^^ 8 9All drivers respond to a set of common debug environment variables, as well as 10some driver-specific variables. Set them as normal environment variables for 11the platform or operating system you are running. For example, for Linux this 12can be done by typing "export var=value" into a console and then running the 13program from that console. 14 15Common 16"""""" 17 18.. envvar:: GALLIUM_PRINT_OPTIONS <bool> (false) 19 20This option controls if the debug variables should be printed to stderr. This 21is probably the most useful variable, since it allows you to find which 22variables a driver uses. 23 24.. envvar:: GALLIUM_RBUG <bool> (false) 25 26Controls if the :ref:`rbug` should be used. 27 28.. envvar:: GALLIUM_TRACE <string> ("") 29 30If set, this variable will cause the :ref:`trace` output to be written to the 31specified file. Paths may be relative or absolute; relative paths are relative 32to the working directory. For example, setting it to "trace.xml" will cause 33the trace to be written to a file of the same name in the working directory. 34 35.. envvar:: GALLIUM_TRACE_TC <bool> (false) 36 37If enabled while :ref:`trace` is active, this variable specifies that the threaded context 38should be traced for drivers which implement it. By default, the driver thread is traced, 39which will include any reordering of the command stream from threaded context. 40 41.. envvar:: GALLIUM_TRACE_TRIGGER <string> ("") 42 43If set while :ref:`trace` is active, this variable specifies a filename to monitor. 44Once the file exists (e.g., from the user running 'touch /path/to/file'), a single 45frame will be recorded into the trace output. 46Paths may be relative or absolute; relative paths are relative to the working directory. 47 48.. envvar:: GALLIUM_DUMP_CPU <bool> (false) 49 50Dump information about the current CPU that the driver is running on. 51 52.. envvar:: TGSI_PRINT_SANITY <bool> (false) 53 54Gallium has a built-in shader sanity checker. This option controls whether 55the shader sanity checker prints its warnings and errors to stderr. 56 57.. envvar:: DRAW_USE_LLVM <bool> (false) 58 59Whether the :ref:`Draw` module will attempt to use LLVM for vertex and geometry shaders. 60 61 62GL State tracker-specific 63""""""""""""""""""""""""" 64 65.. envvar:: ST_DEBUG <flags> (0x0) 66 67Debug :ref:`flags` for the GL state tracker. 68 69 70Driver-specific 71""""""""""""""" 72 73.. envvar:: I915_DEBUG <flags> (0x0) 74 75Debug :ref:`flags` for the i915 driver. 76 77.. envvar:: I915_NO_HW <bool> (false) 78 79Stop the i915 driver from submitting commands to the hardware. 80 81.. envvar:: I915_DUMP_CMD <bool> (false) 82 83Dump all commands going to the hardware. 84 85.. envvar:: LP_DEBUG <flags> (0x0) 86 87Debug :ref:`flags` for the llvmpipe driver. 88 89.. envvar:: LP_NUM_THREADS <int> (number of CPUs) 90 91Number of threads that the llvmpipe driver should use. 92 93.. envvar:: FD_MESA_DEBUG <flags> (0x0) 94 95Debug :ref:`flags` for the freedreno driver. 96 97 98.. _flags: 99 100Flags 101""""" 102 103The variables of type "flags" all take a string with comma-separated flags to 104enable different debugging for different parts of the drivers or state 105tracker. If set to "help", the driver will print a list of flags which the 106variable accepts. Order does not matter. 107 108 109.. _rbug: 110 111Remote Debugger 112^^^^^^^^^^^^^^^ 113 114The remote debugger, commonly known as rbug, allows for runtime inspections of 115:ref:`Context`, :ref:`Screen`, :ref:`Resource` and :ref:`Shader` objects; and 116pausing and stepping of :ref:`Draw` calls. Is used with rbug-gui which is 117hosted outside of the main mesa repository. rbug is can be used over a network 118connection, so the debugger does not need to be on the same machine. 119