mirror of
https://github.com/WiVRn/WiVRn.git
synced 2026-11-20 09:01:39 -08:00
476 lines
13 KiB
Markdown
476 lines
13 KiB
Markdown
# Debugging WiVRn
|
|
|
|
This guide covers debugging techniques for WiVRn, including log collection, crash analysis, performance profiling, and common troubleshooting scenarios.
|
|
|
|
## Table of Contents
|
|
|
|
- [Prerequisites](#prerequisites)
|
|
- [Collecting Logs](#collecting-logs)
|
|
- [HMD Client Logs](#hmd-client-logs)
|
|
- [Server Logs](#server-logs)
|
|
- [Starting Components for Debugging](#starting-components-for-debugging)
|
|
- [HMD Client](#hmd-client)
|
|
- [Server](#server)
|
|
- [XR Applications](#xr-applications)
|
|
- [Crash Debugging](#crash-debugging)
|
|
- [Server Crashes](#server-crashes)
|
|
- [HMD Client Crashes](#hmd-client-crashes)
|
|
- [Performance Profiling](#performance-profiling)
|
|
- [USB Tunneling](#usb-tunneling)
|
|
- [Game Debugging](#game-debugging)
|
|
- [Environment Variables Reference](#environment-variables-reference)
|
|
- [Configuration Files](#configuration-files)
|
|
- [External Resources](#external-resources)
|
|
- [Remote Native Debugging (Advanced)](#remote-native-debugging-advanced)
|
|
|
|
---
|
|
|
|
## Prerequisites
|
|
|
|
### ADB Setup
|
|
|
|
The Android Debug Bridge ([ADB](https://developer.android.com/tools/adb)) is required for debugging the HMD client. Connect your headset to your PC via a USB data cable and authorize the connection when prompted in the HMD.
|
|
|
|
### Clean Installation
|
|
|
|
When debugging, ensure the HMD client matches the server version. Perform a clean reinstall:
|
|
|
|
```bash
|
|
# Find and uninstall existing installation
|
|
WIVRN_PKG=$(adb shell pm list packages | grep wivrn | cut -d: -f2)
|
|
adb uninstall ${WIVRN_PKG}
|
|
|
|
# Install the debug APK
|
|
adb install /path/to/wivrn-standard-debug.apk
|
|
```
|
|
|
|
---
|
|
|
|
## Collecting Logs
|
|
|
|
### HMD Client Logs
|
|
|
|
The primary method to collect logs from the HMD is through [ADB logcat](https://developer.android.com/tools/logcat).
|
|
|
|
Watch for crashes (FATAL priority):
|
|
|
|
```bash
|
|
adb logcat '*:F'
|
|
```
|
|
|
|
Record ERROR and above:
|
|
|
|
```bash
|
|
adb logcat '*:E' | tee -a errors-$(date "+%Y-%m-%d-%H").log
|
|
```
|
|
|
|
WiVRn-only logs (verbose):
|
|
|
|
```bash
|
|
adb logcat '*:S' WiVRn:V
|
|
```
|
|
|
|
Watch WiVRn client logs:
|
|
|
|
```bash
|
|
adb logcat | grep WiVRn
|
|
```
|
|
|
|
Watch Android system logs related to WiVRn:
|
|
|
|
```bash
|
|
adb logcat | grep wivrn
|
|
```
|
|
|
|
### Server Logs
|
|
|
|
Start the server with debug logging enabled:
|
|
|
|
```bash
|
|
XRT_LOG=debug XRT_COMPOSITOR_LOG=debug wivrn-server
|
|
```
|
|
|
|
To also dump video frames for analysis:
|
|
|
|
```bash
|
|
XRT_LOG=debug XRT_COMPOSITOR_LOG=debug WIVRN_DUMP_VIDEO=/tmp/video-dump wivrn-server
|
|
```
|
|
|
|
The video dump can be played back with `mpv` or other media players to verify what video was being sent to the HMD.
|
|
|
|
There will be multiple files in the directory, one for each video stream per codec. For example, `/tmp/video-dump-0.h264`.
|
|
|
|
---
|
|
|
|
## Starting Components for Debugging
|
|
|
|
### HMD Client
|
|
|
|
The package name varies by build variant:
|
|
- `org.meumeu.wivrn` - for app store builds
|
|
- `org.meumeu.wivrn.github` - for GitHub release builds
|
|
- `org.meumeu.wivrn.local` - for locally built APK
|
|
- `org.meumeu.wivrn.github.testing` - for CI runs
|
|
- `org.meumeu.wivrn.github.nightly` - for APK repo
|
|
|
|
Find your installed package with:
|
|
|
|
```bash
|
|
adb shell pm list packages | grep wivrn
|
|
```
|
|
|
|
Start via ADB:
|
|
|
|
```bash
|
|
WIVRN_PKG=$(adb shell pm list packages | grep wivrn | cut -d: -f2)
|
|
adb shell am start ${WIVRN_PKG}/org.meumeu.wivrn.MainActivity
|
|
```
|
|
|
|
Connect to a specific server:
|
|
|
|
Replace `ADDRESS=localhost` with the address of the server you want to connect to.
|
|
|
|
```bash
|
|
WIVRN_PKG=$(adb shell pm list packages | grep wivrn | cut -d: -f2)
|
|
ADDRESS=localhost
|
|
adb shell am start -a android.intent.action.VIEW -d "wivrn://${ADDRESS}" ${WIVRN_PKG}
|
|
```
|
|
|
|
Stop the client:
|
|
|
|
```bash
|
|
WIVRN_PKG=$(adb shell pm list packages | grep wivrn | cut -d: -f2)
|
|
adb shell am force-stop ${WIVRN_PKG}
|
|
```
|
|
|
|
### Server
|
|
|
|
Start the server with debug logging:
|
|
|
|
```bash
|
|
XRT_LOG=debug XRT_COMPOSITOR_LOG=debug wivrn-server
|
|
```
|
|
|
|
The server will publish itself on the network via mDNS/Zeroconf for discovery by the HMD client.
|
|
|
|
### XR Applications
|
|
|
|
Basic OpenXR application:
|
|
|
|
```bash
|
|
xrgears
|
|
```
|
|
|
|
To run Steam games via OpenVR, make sure to add the Steam launch options presented by the server output or in the dashboard. This is required to configure the OpenVR runtime correctly.
|
|
|
|
Some games have options to control window behavior. Try adding `-windowed` or `-window -w 1280 -h 1024` to the game launch options to allow moving/resizing the local render window. Each game may have different options, check the game's documentation.
|
|
|
|
> Note: Games linked to OpenVR require [OpenComposite](https://gitlab.com/znixian/OpenOVR) or [xrizer](https://github.com/Supreeeme/xrizer) to translate calls to OpenXR.
|
|
|
|
---
|
|
|
|
## Crash Debugging
|
|
|
|
### Server Crashes
|
|
|
|
#### Systemd
|
|
|
|
Core dumps are managed by [systemd-coredump](https://www.freedesktop.org/software/systemd/man/latest/coredumpctl.html).
|
|
|
|
View the most recent crash:
|
|
|
|
```bash
|
|
coredumpctl info
|
|
```
|
|
|
|
Start a debugger on the most recent crash:
|
|
|
|
```bash
|
|
coredumpctl -1 debug
|
|
```
|
|
|
|
Inside GDB/LLDB:
|
|
|
|
```
|
|
# Select frame 2
|
|
f 2
|
|
|
|
# View local variables
|
|
info locals
|
|
|
|
# Print backtrace
|
|
bt
|
|
```
|
|
|
|
#### Non-Systemd Systems
|
|
|
|
On systems without systemd-coredump, core dumps are handled by the kernel directly.
|
|
|
|
Check where core dumps are written:
|
|
|
|
```bash
|
|
cat /proc/sys/kernel/core_pattern
|
|
```
|
|
|
|
To set a simple core pattern:
|
|
|
|
```bash
|
|
sudo sysctl -w kernel.core_pattern=/tmp/core.%e.%p.%t
|
|
```
|
|
|
|
This writes cores to `/tmp/` with the format `core.<executable>.<pid>.<timestamp>`.
|
|
|
|
Analyze a core dump with GDB:
|
|
|
|
```bash
|
|
gdb /usr/bin/wivrn-server /tmp/core.wivrn-server.12345.1706234567
|
|
```
|
|
|
|
Inside GDB:
|
|
|
|
```
|
|
# Print backtrace
|
|
bt
|
|
|
|
# View all threads
|
|
info threads
|
|
|
|
# Switch to thread 2
|
|
thread 2
|
|
|
|
# Print backtrace for all threads
|
|
thread apply all bt
|
|
```
|
|
|
|
### HMD Client Crashes
|
|
|
|
Copy the traceback from the HMD logs using logcat:
|
|
|
|
```bash
|
|
adb logcat '*:F' | grep -A 50 wivrn
|
|
```
|
|
|
|
---
|
|
|
|
## Performance Profiling
|
|
|
|
WiVRn supports timing analysis and detailed system-wide profiling with Perfetto.
|
|
See [docs/profiling.md](profiling.md) for capturing
|
|
timing data, profiling the HMD client and server, and comparing the Vulkan,
|
|
NVENC, and VAAPI encoder paths.
|
|
|
|
---
|
|
|
|
## USB Tunneling
|
|
|
|
For debugging network issues or testing with a wired connection, you can tunnel WiVRn over USB.
|
|
|
|
Set up the tunnel and connect:
|
|
|
|
```bash
|
|
WIVRN_PKG=$(adb shell pm list packages | grep wivrn | cut -d: -f2)
|
|
adb reverse tcp:9757 tcp:9757
|
|
adb shell am start -a android.intent.action.VIEW -d "wivrn+tcp://localhost:9757" ${WIVRN_PKG}
|
|
```
|
|
|
|
You are also able to make this connection through the dashboard.
|
|
|
|
---
|
|
|
|
## Game Debugging
|
|
|
|
### Proton/Wine Games
|
|
|
|
Enable additional logging for Windows compatibility layers:
|
|
|
|
```
|
|
PROTON_LOG=1 WINEDEBUG=vrclient,openxr,steam %command%
|
|
```
|
|
|
|
### OpenComposite
|
|
|
|
For games using OpenVR, and you are using [OpenComposite](https://gitlab.com/znixian/OpenOVR) to translate calls to OpenXR.
|
|
|
|
The OpenComposite log can be found at `$HOME/.local/state/OpenComposite/logs/opencomposite.log`.
|
|
|
|
### XRizer
|
|
|
|
To debug [xrizer](https://github.com/Supreeeme/xrizer), you can set the `RUST_LOG` environment variable to control the log level.
|
|
|
|
| Variable | Description | Default |
|
|
|------------|-----------------------------------------------------------------------------|---------|
|
|
| `RUST_LOG` | Configures the logging level for Rust applications. Accepts a comma-separated list of directives in the format `module::path=level`, where `level` can be `error`, `warn`, `info`, `debug`, or `trace`. For example, `RUST_LOG=info,my_crate=debug` sets the global level to `info` and the `my_crate` module to `debug`. | `warn` |
|
|
|
|
In xrizer, `RUST_LOG` follows the standard [`env_logger` semantics](https://docs.rs/env_logger/latest/env_logger/#enabling-logging) described above. In addition, xrizer defines the following useful nonstandard logging targets:
|
|
|
|
| Logging Target | Description |
|
|
|-----------------|-------------|
|
|
| `openvr_calls` | Logs the name of each OpenVR function as they are called |
|
|
| `tracked_property` | Logs the name and device index of each requested tracked device property |
|
|
|
|
The log is located at `$XDG_STATE_HOME/xrizer/xrizer.txt`, or `$HOME/.local/state/xrizer/xrizer.txt` if `$XDG_STATE_HOME` is not set.
|
|
|
|
---
|
|
|
|
## Environment Variables Reference
|
|
|
|
### Compositor Settings
|
|
|
|
| Variable | Description | Default |
|
|
|----------|-------------|---------|
|
|
| `XRT_LOG` | Log level (`trace`, `debug`, `info`, `warn`, `error`) | `warn` |
|
|
| `XRT_COMPOSITOR_LOG` | Compositor log level (`trace`, `debug`, `info`, `warn`, `error`) | `info` |
|
|
| `OXR_VIEWPORT_SCALE_PERCENTAGE` | Per-application viewport scale (set on application, not server) | `100` |
|
|
|
|
### Debugging
|
|
|
|
| Variable | Description |
|
|
|----------|-------------|
|
|
| `WIVRN_DUMP_VIDEO` | Path to dump video frames (e.g., `/tmp/video-dump`) |
|
|
| `WIVRN_LOGLEVEL` | Log level for the native client |
|
|
| `WIVRN_AUTOCONNECT` | Auto-connect to the first discovered server |
|
|
| `WIVRN_TRACING` | Enable WiVRn Perfetto tracing: `system` / `inprocess`. Requires `WIVRN_USE_PERFETTO=ON` at build time. See [docs/profiling.md](profiling.md). |
|
|
|
|
### Vulkan
|
|
|
|
| Variable | Description |
|
|
|----------|-------------|
|
|
| `VK_INSTANCE_LAYERS` | Vulkan validation layers (e.g., `VK_LAYER_KHRONOS_validation`) |
|
|
|
|
### OpenXR
|
|
|
|
| Variable | Description |
|
|
|----------|-------------|
|
|
| `XR_RUNTIME_JSON` | Path to OpenXR runtime configuration |
|
|
|
|
See also the [Monado compositor documentation](https://monado.freedesktop.org/getting-started.html#compositor) for additional options.
|
|
|
|
---
|
|
|
|
## Configuration Files
|
|
|
|
### OpenXR Runtime Configuration
|
|
|
|
Active runtime symlink:
|
|
|
|
```bash
|
|
ls -la $HOME/.config/openxr/1/active_runtime.json
|
|
```
|
|
|
|
Should point to `/usr/share/openxr/1/openxr_wivrn.json` or similar.
|
|
|
|
Check runtime configuration:
|
|
|
|
```bash
|
|
cat /usr/share/openxr/1/openxr_wivrn.json
|
|
```
|
|
|
|
Example output:
|
|
|
|
```json
|
|
{
|
|
"file_format_version": "1.0.0",
|
|
"runtime": {
|
|
"name": "Monado",
|
|
"library_path": "../../../lib64/wivrn/libopenxr_wivrn.so",
|
|
"MND_libmonado_path": "../../../lib64/wivrn/libmonado_wivrn.so"
|
|
}
|
|
}
|
|
```
|
|
|
|
Verify library dependencies:
|
|
|
|
```bash
|
|
pushd /usr/share/openxr/1/
|
|
ldd ../../../lib64/wivrn/libopenxr_wivrn.so
|
|
popd
|
|
```
|
|
|
|
### WiVRn Server Configuration
|
|
|
|
See [docs/configuration.md](configuration.md).
|
|
|
|
---
|
|
|
|
## External Resources
|
|
|
|
### Tools and Documentation
|
|
|
|
- [ADB Documentation](https://developer.android.com/tools/adb) - Android Debug Bridge
|
|
- [ADB Logcat](https://developer.android.com/tools/logcat) - Log filtering and analysis
|
|
- [coredumpctl](https://www.freedesktop.org/software/systemd/man/latest/coredumpctl.html) - Core dump management
|
|
- [Perfetto](https://perfetto.dev/docs/) - System profiling and tracing
|
|
- [Perfetto UI](https://ui.perfetto.dev/) - Web-based trace viewer
|
|
|
|
### Monado/OpenXR
|
|
|
|
- [Monado Getting Started](https://monado.freedesktop.org/getting-started.html) - Compositor configuration
|
|
- [Monado Tracing with Perfetto](https://monado.pages.freedesktop.org/monado/tracing-perfetto.html) - Server-side tracing
|
|
- [OpenXR](https://www.khronos.org/openxr/) - Khronos OpenXR standard
|
|
- [xrgears](https://github.com/ila-embsys/monado_demo_xrgears) - OpenXR test application
|
|
|
|
### Gaming
|
|
|
|
- [OpenComposite](https://gitlab.com/znixian/OpenOVR) - OpenVR to OpenXR translation
|
|
- [xrizer](https://github.com/Supreeeme/xrizer) - OpenVR to OpenXR translation layer (Rust)
|
|
|
|
### Rust
|
|
|
|
- [env_logger](https://docs.rs/env_logger/latest/env_logger/#enabling-logging) - Rust logging configuration via RUST_LOG
|
|
|
|
### Android Debugging
|
|
|
|
- [Android NDK Debugging](https://developer.android.com/ndk/guides/ndk-gdb) - Native debugging with ndk-gdb
|
|
- [Android Tracing Quickstart](https://perfetto.dev/docs/quickstart/android-tracing) - Perfetto on Android
|
|
|
|
---
|
|
|
|
## Remote Native Debugging (Advanced)
|
|
|
|
This section covers attaching a native debugger to the HMD client remotely. This requires the Android NDK and familiarity with LLDB/GDB.
|
|
|
|
Start the client with debugging enabled:
|
|
|
|
```bash
|
|
WIVRN_PKG=$(adb shell pm list packages | grep wivrn | cut -d: -f2)
|
|
adb shell am start -D ${WIVRN_PKG}/org.meumeu.wivrn.MainActivity
|
|
```
|
|
|
|
Set up LLDB debugging:
|
|
|
|
1. Push the LLDB server to the device:
|
|
|
|
```bash
|
|
adb shell "mkdir -p /data/local/tmp/tools"
|
|
adb push "$ANDROID_NDK/toolchains/llvm/prebuilt/linux-x86_64/lib64/clang/*/lib/linux/aarch64/lldb-server" /data/local/tmp/tools/
|
|
```
|
|
|
|
2. Start the LLDB server on the device:
|
|
|
|
```bash
|
|
adb shell /data/local/tmp/tools/lldb-server platform --server --listen '*:5039'
|
|
```
|
|
|
|
3. Forward the port:
|
|
|
|
```bash
|
|
adb forward tcp:5039 tcp:5039
|
|
```
|
|
|
|
4. Connect from your host:
|
|
|
|
```bash
|
|
lldb
|
|
(lldb) platform select remote-android
|
|
(lldb) platform connect connect://localhost:5039
|
|
```
|
|
|
|
Resume the app (required for `-D` flag):
|
|
|
|
```bash
|
|
adb forward tcp:12345 jdwp:$(adb shell pidof ${WIVRN_PKG})
|
|
jdb -attach localhost:12345
|
|
```
|
|
|
|
See the [Android NDK debugging guide](https://developer.android.com/ndk/guides/ndk-gdb) for more details.
|