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 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
  18 GALLIUM_PRINT_OPTIONS <bool> (false)
  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
  24 GALLIUM_RBUG <bool> (false)
  25
  26 Controls if the :ref:`rbug` should be used.
  27
  28 GALLIUM_TRACE <string> ("")
  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
  34 GALLIUM_DUMP_CPU <bool> (false)
  35
  36 Dump information about the current cpu that the driver is running on.
  37
  38 TGSI_PRINT_SANITY <bool> (false)
  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
  43 DRAW_USE_LLVM <bool> (false)
  44
  45 Should the :ref:`draw` module use llvm for vertex and geometry shaders.
  46
  47 ST_DEBUG <flags> (0x0)
  48
  49 Debug :ref:`flags` for the GL state tracker.
  50
  51
  52 Driver specific
  53 """""""""""""""
  54
  55 I915_DEBUG <flags> (0x0)
  56
  57 Debug :ref:`flags` for the i915 driver.
  58
  59 I915_NO_HW <bool> (false)
  60
  61 Stop the i915 driver from submitting commands to the hardware.
  62
  63 I915_DUMP_CMD <bool> (false)
  64
  65 Dump all commands going to the hardware.
  66
  67 LP_DEBUG <flags> (0x0)
  68
  69 Debug :ref:`flags` for the llvmpipe driver.
  70
  71 LP_NUM_THREADS <int> (num cpus)
  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.