How to debug SteamVR Drivers on Linux

steamvr_dev.md

SteamVR Driver Dev (Linux)

Installing your driver

To install your driver on Linux you have to drop it into $STEAM_HOME/steamapps/common/SteamVR/drivers where STEAM_HOME depends on your Steam settings and distro. Usually it is located at ~/.steam or ~/.local/share/Steam. However it can also be located on an external drive depending on where SteamVR is installed.

The in the drivers folder you have to drop a folder named after your module. This folder has to contain the following structure:

driver/
 ├─ example/
 │    ├─ bin /
 │    │   ├─ linux64/
 │    │   │   └─ driver_example.so
 │    │   ├─ win64/
 │    │   │   └─ driver_example.dll
 │    │   └─ ...
 │    ├─ resources/
 │    │   ├─ settings
 │    │   │   └─ default.vrsettings
 │    │   └─ ...
 │    └─ driver.vrdrivermanifest
 └─ ...

For information about the VR Driver Manifest look up the OpenVR documentation here: https://github.com/ValveSoftware/openvr/wiki/DriverManifest

Driver Disabled after Safe-Mode event

If your driver was responsible for a crash when starting SteamVR, SteamVR may disable it from loading.

To reenable your driver you have to remove the blocked_by_safe_mode entry in $STEAM_HOME/config/steamvr.vrsettings under the section named driver_<your driver>.

Running the debugger

In order to run the debgger (gdb) with SteamVR you have to use the following command:

$ LD_LIBRARY_PATH="$STEAMVR_HOME/bin/linux64" gdb --args $STEAMVR_HOME/bin/linux64/vrserver --keepalive

Where $STEAMVR_HOME is set to your SteamVR installation folder at $STEAM_HOME/steamapps/common/SteamVR (see "Installing your driver" for more info)

After running the vrserver you also have to start SteamVR using your Steam client, otherwise the modules won't load. You can skip starting SteamVR by adding the --earlyload argument however you may run into crashes with that one.

You may also have to continue execution a few times before the module loads since SteamVR may send a few SIGTRAP signals when loading the modules. This is an example of an SIGTRAP signal from SteamVR:

Fri Jul 1 2021 00:00:00.000000 - ASSERT: "DriverManager example load error 1" at /data/src/common/vrcommon/drivermanager.cpp:404.

Thread 8 "Connection - vr" received signal SIGTRAP, Trace/breakpoint trap.
0x00005555556a99d9 in CAssert::AssertMsgImpl(char const*, unsigned int, bool, unsigned int, ...) ()
(gdb) c

To continue execution just use the continue command or the abbreviated version c