Gitiles
Code Review Sign In
gerrit-public.fairphone.software / platform / external / mesa3d / 2d53dc873ea1d9e0e3e4c1cf08a63621661e422f / . / src / gallium / docs / source / debugging.rst
blob: 42bda5aee93a1d1bf07bd40c2b993b39cc6f7db1 [file] [log] [blame]
Jakob Bornecrantzd62b29f2010-08-15 00:59:57 +0100[diff] [blame]1Debugging
2=========
3
4Debugging utilities in gallium.
5
6Debug Variables
7^^^^^^^^^^^^^^^
8
Corbin Simpson2d53dc82010-08-15 03:26:58 -0700[diff] [blame^]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
Jakob Bornecrantzd62b29f2010-08-15 00:59:57 +0100[diff] [blame]13program from that console.
14
15Common
16""""""
17
Corbin Simpsonbf357ae2010-08-15 03:05:18 -0700[diff] [blame]18.. envvar:: GALLIUM_PRINT_OPTIONS <bool> (false)
Jakob Bornecrantzd62b29f2010-08-15 00:59:57 +0100[diff] [blame]19
Corbin Simpson2d53dc82010-08-15 03:26:58 -0700[diff] [blame^]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.
Jakob Bornecrantzd62b29f2010-08-15 00:59:57 +0100[diff] [blame]23
Corbin Simpsonbf357ae2010-08-15 03:05:18 -0700[diff] [blame]24.. envvar:: GALLIUM_RBUG <bool> (false)
Jakob Bornecrantzd62b29f2010-08-15 00:59:57 +0100[diff] [blame]25
26Controls if the :ref:`rbug` should be used.
27
Corbin Simpsonbf357ae2010-08-15 03:05:18 -0700[diff] [blame]28.. envvar:: GALLIUM_TRACE <string> ("")
Jakob Bornecrantzd62b29f2010-08-15 00:59:57 +0100[diff] [blame]29
Corbin Simpson2d53dc82010-08-15 03:26:58 -0700[diff] [blame^]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.
Jakob Bornecrantzd62b29f2010-08-15 00:59:57 +0100[diff] [blame]34
Corbin Simpsonbf357ae2010-08-15 03:05:18 -0700[diff] [blame]35.. envvar:: GALLIUM_DUMP_CPU <bool> (false)
Jakob Bornecrantzd62b29f2010-08-15 00:59:57 +0100[diff] [blame]36
Corbin Simpson2d53dc82010-08-15 03:26:58 -0700[diff] [blame^]37Dump information about the current CPU that the driver is running on.
Jakob Bornecrantzd62b29f2010-08-15 00:59:57 +0100[diff] [blame]38
Corbin Simpsonbf357ae2010-08-15 03:05:18 -0700[diff] [blame]39.. envvar:: TGSI_PRINT_SANITY <bool> (false)
Jakob Bornecrantzd62b29f2010-08-15 00:59:57 +0100[diff] [blame]40
Corbin Simpson2d53dc82010-08-15 03:26:58 -0700[diff] [blame^]41Gallium has a built-in shader sanity checker. This option controls whether
42the shader sanity checker prints its warnings and errors to stderr.
Jakob Bornecrantzd62b29f2010-08-15 00:59:57 +0100[diff] [blame]43
Corbin Simpsonbf357ae2010-08-15 03:05:18 -0700[diff] [blame]44.. envvar:: DRAW_USE_LLVM <bool> (false)
Jakob Bornecrantzd62b29f2010-08-15 00:59:57 +0100[diff] [blame]45
Corbin Simpson2d53dc82010-08-15 03:26:58 -0700[diff] [blame^]46Whether the :ref:`Draw` module will attempt to use LLVM for vertex and geometry shaders.
47
48
49State tracker-specific
50""""""""""""""""""""""
Jakob Bornecrantzd62b29f2010-08-15 00:59:57 +0100[diff] [blame]51
Corbin Simpsonbf357ae2010-08-15 03:05:18 -0700[diff] [blame]52.. envvar:: ST_DEBUG <flags> (0x0)
Jakob Bornecrantzd62b29f2010-08-15 00:59:57 +0100[diff] [blame]53
54Debug :ref:`flags` for the GL state tracker.
55
56
Corbin Simpson2d53dc82010-08-15 03:26:58 -0700[diff] [blame^]57Driver-specific
Jakob Bornecrantzd62b29f2010-08-15 00:59:57 +0100[diff] [blame]58"""""""""""""""
59
Corbin Simpsonbf357ae2010-08-15 03:05:18 -0700[diff] [blame]60.. envvar:: I915_DEBUG <flags> (0x0)
Jakob Bornecrantzd62b29f2010-08-15 00:59:57 +0100[diff] [blame]61
62Debug :ref:`flags` for the i915 driver.
63
Corbin Simpsonbf357ae2010-08-15 03:05:18 -0700[diff] [blame]64.. envvar:: I915_NO_HW <bool> (false)
Jakob Bornecrantzd62b29f2010-08-15 00:59:57 +0100[diff] [blame]65
66Stop the i915 driver from submitting commands to the hardware.
67
Corbin Simpsonbf357ae2010-08-15 03:05:18 -0700[diff] [blame]68.. envvar:: I915_DUMP_CMD <bool> (false)
Jakob Bornecrantzd62b29f2010-08-15 00:59:57 +0100[diff] [blame]69
70Dump all commands going to the hardware.
71
Corbin Simpsonbf357ae2010-08-15 03:05:18 -0700[diff] [blame]72.. envvar:: LP_DEBUG <flags> (0x0)
Jakob Bornecrantzd62b29f2010-08-15 00:59:57 +0100[diff] [blame]73
74Debug :ref:`flags` for the llvmpipe driver.
75
Corbin Simpson2d53dc82010-08-15 03:26:58 -0700[diff] [blame^]76.. envvar:: LP_NUM_THREADS <int> (number of CPUs)
Jakob Bornecrantzd62b29f2010-08-15 00:59:57 +0100[diff] [blame]77
78Number of threads that the llvmpipe driver should use.
79
80
81.. _flags:
82
83Flags
84"""""
85
Corbin Simpson2d53dc82010-08-15 03:26:58 -0700[diff] [blame^]86The variables of type "flags" all take a string with comma-separated flags to
87enable different debugging for different parts of the drivers or state
88tracker. If set to "help", the driver will print a list of flags which the
89variable accepts. Order does not matter.
Jakob Bornecrantzd62b29f2010-08-15 00:59:57 +0100[diff] [blame]90
91
92.. _rbug:
93
94Remote Debugger
95^^^^^^^^^^^^^^^
96
Corbin Simpson2d53dc82010-08-15 03:26:58 -0700[diff] [blame^]97The remote debugger, commonly known as rbug, allows for runtime inspections of
98:ref:`Context`, :ref:`Screen`, :ref:`Resource` and :ref:`Shader` objects; and
99pausing and stepping of :ref:`Draw` calls. Is used with rbug-gui which is
100hosted outside of the main mesa repository. rbug is can be used over a network
101connection, so the debugger does not need to be on the same machine.