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_GALAHAD <bool> (false)
25
26Controls if the :ref:`galahad` sanity checker module should be used.
27
28.. envvar:: GALLIUM_RBUG <bool> (false)
29
30Controls if the :ref:`rbug` should be used.
31
32.. envvar:: GALLIUM_TRACE <string> ("")
33
34If set, this variable will cause the :ref:`Trace` output to be written to the
35specified file. Paths may be relative or absolute; relative paths are relative
36to the working directory.  For example, setting it to "trace.xml" will cause
37the trace to be written to a file of the same name in the working directory.
38
39.. envvar:: GALLIUM_DUMP_CPU <bool> (false)
40
41Dump information about the current CPU that the driver is running on.
42
43.. envvar:: TGSI_PRINT_SANITY <bool> (false)
44
45Gallium has a built-in shader sanity checker.  This option controls whether
46the shader sanity checker prints its warnings and errors to stderr.
47
48.. envvar:: DRAW_USE_LLVM <bool> (false)
49
50Whether the :ref:`Draw` module will attempt to use LLVM for vertex and geometry shaders.
51
52
53State tracker-specific
54""""""""""""""""""""""
55
56.. envvar:: ST_DEBUG <flags> (0x0)
57
58Debug :ref:`flags` for the GL state tracker.
59
60
61Driver-specific
62"""""""""""""""
63
64.. envvar:: I915_DEBUG <flags> (0x0)
65
66Debug :ref:`flags` for the i915 driver.
67
68.. envvar:: I915_NO_HW <bool> (false)
69
70Stop the i915 driver from submitting commands to the hardware.
71
72.. envvar:: I915_DUMP_CMD <bool> (false)
73
74Dump all commands going to the hardware.
75
76.. envvar:: LP_DEBUG <flags> (0x0)
77
78Debug :ref:`flags` for the llvmpipe driver.
79
80.. envvar:: LP_NUM_THREADS <int> (number of CPUs)
81
82Number of threads that the llvmpipe driver should use.
83
84
85.. _flags:
86
87Flags
88"""""
89
90The variables of type "flags" all take a string with comma-separated flags to
91enable different debugging for different parts of the drivers or state
92tracker. If set to "help", the driver will print a list of flags which the
93variable accepts. Order does not matter.
94
95
96.. _rbug:
97
98Remote Debugger
99^^^^^^^^^^^^^^^
100
101The remote debugger, commonly known as rbug, allows for runtime inspections of
102:ref:`Context`, :ref:`Screen`, :ref:`Resource` and :ref:`Shader` objects; and
103pausing and stepping of :ref:`Draw` calls. Is used with rbug-gui which is
104hosted outside of the main mesa repository. rbug is can be used over a network
105connection, so the debugger does not need to be on the same machine.
106