Debugging

Debugging utilities in gallium.

Debug Variables

All drivers respond to a set of common debug environment variables, as well as some driver-specific variables. Set them as normal environment variables for the platform or operating system you are running. For example, for Linux this can be done by typing “export var=value” into a console and then running the program from that console.

Common

GALLIUM_PRINT_OPTIONS Type: bool, Default: false

This option controls if the debug variables should be printed to stderr. This is probably the most useful variable, since it allows you to find which variables a driver uses.

GALLIUM_RBUG Type: bool, Default: false

Controls if the Remote Debugger should be used.

GALLIUM_TRACE Type: string, Default: ""

If set, this variable will cause the Trace output to be written to the specified file. Paths may be relative or absolute; relative paths are relative to the working directory. For example, setting it to “trace.xml” will cause the trace to be written to a file of the same name in the working directory.

GALLIUM_TRACE_TC Type: bool, Default: false

If enabled while Trace is active, this variable specifies that the threaded context should be traced for drivers which implement it. By default, the driver thread is traced, which will include any reordering of the command stream from threaded context.

GALLIUM_TRACE_TRIGGER Type: string, Default: ""

If set while Trace is active, this variable specifies a filename to monitor. Once the file exists (e.g., from the user running ‘touch /path/to/file’), a single frame will be recorded into the trace output. Paths may be relative or absolute; relative paths are relative to the working directory.

GALLIUM_DUMP_CPU Type: bool, Default: false

Dump information about the current CPU that the driver is running on.

TGSI_PRINT_SANITY Type: bool, Default: false

Gallium has a built-in shader sanity checker. This option controls whether the shader sanity checker prints its warnings and errors to stderr.

DRAW_USE_LLVM Type: bool, Default: false

Whether the Draw module will attempt to use LLVM for vertex and geometry shaders.

GL State tracker-specific

ST_DEBUG Type: flags, Default: 0x0

Debug Flags for the GL state tracker.

Driver-specific

I915_DEBUG Type: flags, Default: 0x0

Debug Flags for the i915 driver.

I915_NO_HW Type: bool, Default: false

Stop the i915 driver from submitting commands to the hardware.

I915_DUMP_CMD Type: bool, Default: false

Dump all commands going to the hardware.

LP_DEBUG Type: flags, Default: 0x0

Debug Flags for the llvmpipe driver.

LP_NUM_THREADS Type: int, Default: number of CPUs

Number of threads that the llvmpipe driver should use.

FD_MESA_DEBUG Type: flags, Default: 0x0

Debug Flags for the freedreno driver.

Flags

The variables of type “flags” all take a string with comma-separated flags to enable different debugging for different parts of the drivers or state tracker. If set to “help”, the driver will print a list of flags which the variable accepts. Order does not matter.

Remote Debugger

The remote debugger, commonly known as rbug, allows for runtime inspections of Context, Screen, Resources and derived objects and Shader objects; and pausing and stepping of Draw calls. Is used with rbug-gui which is hosted outside of the main mesa repository. rbug is can be used over a network connection, so the debugger does not need to be on the same machine.