From 1c873bfcf521eb89476b1042150decd1485d34a8 Mon Sep 17 00:00:00 2001 From: Ian Douglas Scott Date: Thu, 25 Jul 2024 19:04:41 -0700 Subject: [PATCH] Add a `DEBUGGING.md` file with some information useful for debugging I have included information about various things I've used for debugging COSMIC. More could definitely be added. It seems good to have some central resource for this. Though not everything listed here is very straightforward to use. --- docs/DEBUGGING.md | 41 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 41 insertions(+) create mode 100644 docs/DEBUGGING.md diff --git a/docs/DEBUGGING.md b/docs/DEBUGGING.md new file mode 100644 index 00000000..9b12cc5c --- /dev/null +++ b/docs/DEBUGGING.md @@ -0,0 +1,41 @@ +Debugging COSMIC +================ + +An assortment of useful tools and settings for debugging COSMIC. + +## Logs +Cosmic-comp, cosmic-panel, and other components log to `stderr`, as well as journald (if present). + +## Wayland and X11 Protocols + +Run clients with `WAYLAND_DEBUG=1` to see what wayland calls are made. `xtrace -n ` can be used to see what X calls an X11 client is making. + +## XWayland + +A tool like `xprop` can be used to determine if an application is running in XWayland. If `xprop` is unable to select a window, it is a native Wayland window. + +## Performance + +`sudo perf top` can be used to see what functions, across all processes, are using the most CPU time. The `-p` argument can be used to restrict this to a single process. The output is more useful for executables with debug symbols. + +`cosmic-comp` integrates Tracy for profiling. It can be built with `cargo build --features profile-with-tracy --profile fastdebug`, then the Tracy client can connect from the same system or a different one + +## Graphics drivers +`eglinfo` and `vulkaninfo` indicate what graphics cards and drivers are in use for hardware-accelerated rendering. + +On systems with NVIDIA graphics, `nvidia-smi` has information about the GPU and driver. + +## DRM +The Linux DRM subsystem handles graphics cards and display controllers. + +`drm_info` prints information about the outputs, planes, etc. associated with each GPU and their properties. The output of this command can be useful for understanding display related issues. + +https://gitlab.freedesktop.org/wlroots/wlroots/-/wikis/DRM-Debugging documents how to configure DRM to enable additional logging, which can be useful for understanding some DRM driver issues. + +## Frozen desktop + +If the desktop is frozen and `ctrl+alt+f*` don't work to change to a TTY, [the magic SysRq key](https://www.kernel.org/doc/html/latest/admin-guide/sysrq.html) with `r` can be used to swich input in raw mode, so the kernel will handle the tty switch key binding. /etc/sysctl.conf` or `/etc/sysctl.d` may need to be edited first to set `kernel.sysrq=1` or another value that allows this command. + +It is also possible to connect over `ssh` from another computer. + +Then `pidof cosmic-comp` can be used to get the PID of the compositor. Then it is possible to investigate further with tools like `gdb`, using `sudo gdb` then `attach `.