← Back to branch summary

~ubuntu-branches/ubuntu/precise/mesa/precise-updates

« back to all changes in this revision

Viewing changes to src/gallium/docs/source/debugging.rst

  • Committer: Package Import Robot
  • Author(s): Robert Hooker
  • Date: 2012-02-02 12:05:48 UTC
  • mfrom: (1.7.1) (3.3.27 sid)
  • Revision ID: package-import@ubuntu.com-20120202120548-nvkma85jq0h4coix
Tags: 8.0~rc2-0ubuntu4
Drop drisearchdir handling, it is no longer needed with multiarch
and dri-alternates being removed.

Show diffs side-by-side

added added

removed removed

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