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