| Jakob Bornecrantz | d62b29f | 2010-08-15 00:59:57 +0100 | [diff] [blame] | 1 | Debugging |
| 2 | ========= |
| 3 | |
| 4 | Debugging utilities in gallium. |
| 5 | |
| 6 | Debug Variables |
| 7 | ^^^^^^^^^^^^^^^ |
| 8 | |
| 9 | All drivers respond to a couple of debug enviromental variables. Below is |
| 10 | a collection of them. Set them as you would any normal enviromental variable |
| 11 | for the platform/operating system you are running. For linux this can be |
| 12 | done by typing "export var=value" into a console and then running the |
| 13 | program from that console. |
| 14 | |
| 15 | Common |
| 16 | """""" |
| 17 | |
| Corbin Simpson | bf357ae | 2010-08-15 03:05:18 -0700 | [diff] [blame^] | 18 | .. envvar:: GALLIUM_PRINT_OPTIONS <bool> (false) |
| Jakob Bornecrantz | d62b29f | 2010-08-15 00:59:57 +0100 | [diff] [blame] | 19 | |
| 20 | This options controls if the debug variables should be printed to stderr. |
| 21 | This is probably the most usefull variable since it allows you to find |
| 22 | which variables a driver responds to. |
| 23 | |
| Corbin Simpson | bf357ae | 2010-08-15 03:05:18 -0700 | [diff] [blame^] | 24 | .. envvar:: GALLIUM_RBUG <bool> (false) |
| Jakob Bornecrantz | d62b29f | 2010-08-15 00:59:57 +0100 | [diff] [blame] | 25 | |
| 26 | Controls if the :ref:`rbug` should be used. |
| 27 | |
| Corbin Simpson | bf357ae | 2010-08-15 03:05:18 -0700 | [diff] [blame^] | 28 | .. envvar:: GALLIUM_TRACE <string> ("") |
| Jakob Bornecrantz | d62b29f | 2010-08-15 00:59:57 +0100 | [diff] [blame] | 29 | |
| 30 | If not set tracing is not used, if set it will write the output to the file |
| 31 | specifed by the variable. So setting it to "trace.xml" will write the output |
| 32 | to the file "trace.xml". |
| 33 | |
| Corbin Simpson | bf357ae | 2010-08-15 03:05:18 -0700 | [diff] [blame^] | 34 | .. envvar:: GALLIUM_DUMP_CPU <bool> (false) |
| Jakob Bornecrantz | d62b29f | 2010-08-15 00:59:57 +0100 | [diff] [blame] | 35 | |
| 36 | Dump information about the current cpu that the driver is running on. |
| 37 | |
| Corbin Simpson | bf357ae | 2010-08-15 03:05:18 -0700 | [diff] [blame^] | 38 | .. envvar:: TGSI_PRINT_SANITY <bool> (false) |
| Jakob Bornecrantz | d62b29f | 2010-08-15 00:59:57 +0100 | [diff] [blame] | 39 | |
| 40 | Gallium has a inbuilt shader sanity checker, this option controls if results |
| 41 | from it should be printed. This include warnings such as unused variables. |
| 42 | |
| Corbin Simpson | bf357ae | 2010-08-15 03:05:18 -0700 | [diff] [blame^] | 43 | .. envvar:: DRAW_USE_LLVM <bool> (false) |
| Jakob Bornecrantz | d62b29f | 2010-08-15 00:59:57 +0100 | [diff] [blame] | 44 | |
| 45 | Should the :ref:`draw` module use llvm for vertex and geometry shaders. |
| 46 | |
| Corbin Simpson | bf357ae | 2010-08-15 03:05:18 -0700 | [diff] [blame^] | 47 | .. envvar:: ST_DEBUG <flags> (0x0) |
| Jakob Bornecrantz | d62b29f | 2010-08-15 00:59:57 +0100 | [diff] [blame] | 48 | |
| 49 | Debug :ref:`flags` for the GL state tracker. |
| 50 | |
| 51 | |
| 52 | Driver specific |
| 53 | """"""""""""""" |
| 54 | |
| Corbin Simpson | bf357ae | 2010-08-15 03:05:18 -0700 | [diff] [blame^] | 55 | .. envvar:: I915_DEBUG <flags> (0x0) |
| Jakob Bornecrantz | d62b29f | 2010-08-15 00:59:57 +0100 | [diff] [blame] | 56 | |
| 57 | Debug :ref:`flags` for the i915 driver. |
| 58 | |
| Corbin Simpson | bf357ae | 2010-08-15 03:05:18 -0700 | [diff] [blame^] | 59 | .. envvar:: I915_NO_HW <bool> (false) |
| Jakob Bornecrantz | d62b29f | 2010-08-15 00:59:57 +0100 | [diff] [blame] | 60 | |
| 61 | Stop the i915 driver from submitting commands to the hardware. |
| 62 | |
| Corbin Simpson | bf357ae | 2010-08-15 03:05:18 -0700 | [diff] [blame^] | 63 | .. envvar:: I915_DUMP_CMD <bool> (false) |
| Jakob Bornecrantz | d62b29f | 2010-08-15 00:59:57 +0100 | [diff] [blame] | 64 | |
| 65 | Dump all commands going to the hardware. |
| 66 | |
| Corbin Simpson | bf357ae | 2010-08-15 03:05:18 -0700 | [diff] [blame^] | 67 | .. envvar:: LP_DEBUG <flags> (0x0) |
| Jakob Bornecrantz | d62b29f | 2010-08-15 00:59:57 +0100 | [diff] [blame] | 68 | |
| 69 | Debug :ref:`flags` for the llvmpipe driver. |
| 70 | |
| Corbin Simpson | bf357ae | 2010-08-15 03:05:18 -0700 | [diff] [blame^] | 71 | .. envvar:: LP_NUM_THREADS <int> (num cpus) |
| Jakob Bornecrantz | d62b29f | 2010-08-15 00:59:57 +0100 | [diff] [blame] | 72 | |
| 73 | Number of threads that the llvmpipe driver should use. |
| 74 | |
| 75 | |
| 76 | .. _flags: |
| 77 | |
| 78 | Flags |
| 79 | """"" |
| 80 | |
| 81 | The variables of type <flags> all take a string with comma seperated |
| 82 | flags to enable different debugging for different parts of the drivers |
| 83 | or state tracker. If set to "help" the driver will print a list of flags |
| 84 | to which the variable can be set to. Order does not matter. |
| 85 | |
| 86 | |
| 87 | .. _rbug: |
| 88 | |
| 89 | Remote Debugger |
| 90 | ^^^^^^^^^^^^^^^ |
| 91 | |
| 92 | Or rbug for short allows for runtime inspections of :ref:`Context`, |
| 93 | :ref:`Screen`, Resources and Shaders; pauseing and stepping of draw calls; |
| 94 | and runtime disable and replacement of shaders. Is used with rbug-gui which |
| 95 | is hosted outside of the main mesa repositor. Rbug is can be used over a |
| 96 | network connection so the debbuger does not need to be on the same machine. |