# 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_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.