KWin/Debugging: Difference between revisions

From KDE Community Wiki
(11 intermediate revisions by 2 users not shown)
Line 1: Line 1:
{{Construction}}
= Getting diagnosis information for bug reports =
= Getting diagnosis information for bug reports =


Line 15: Line 13:
</nowiki>}}
</nowiki>}}


On occasion, <code>xwininfo</code> might be asked for by the developers if the issue concerns screens and windows, and <code>xprop</code> if the issue concerns window information. Both commands can be run standalone, but depending on the issue it might be useful to run them on specific windows.
On occasion, <code>xwininfo</code> might be asked for by the developers if the issue concerns screens and windows, and <code>xprop</code> if the issue concerns window information. After running either of those two commands, you'll need to click the window that's showing issues.
 


= Report issues via DrKonqi =
= Report issues via DrKonqi =
Line 21: Line 20:
Generally speaking, Plasmashell handles all widgets (including the menu), KWin handles windows and compositing (such as window decorations and desktop effects), and KGlobalAccel5 handles keyboard shortcuts.
Generally speaking, Plasmashell handles all widgets (including the menu), KWin handles windows and compositing (such as window decorations and desktop effects), and KGlobalAccel5 handles keyboard shortcuts.


In a situation where the Plasmashell and KGlobalAccel5 processes are still running but KWin has crashed, you will probably see a sad face in your notification tray, that's DrKonqi, the KDE Crash Handler, getting sad that you experienced a crash. Click its icon and you should be able to follow through with the crash reporting process in a straightforward manner.
In a situation where the Plasmashell and KGlobalAccel5 processes are still running but KWin (X11) has crashed, you will probably see a sad face in your notification tray, that's DrKonqi, the KDE Crash Handler, getting sad that you experienced a crash. Click its icon and you should be able to follow through with the crash reporting process in a straightforward manner.


In a situation where KGlobalAccel5 is still running but both Plasmashell and KWin are running, you can still invoke any keyboard shortcut to run a program that allows you to run a command, such as KRunner, Konsole or Yakuake. With that, you can restart the plasmashell process with:
In a situation where KGlobalAccel5 is still running but both Plasmashell and KWin have crashed, you can still invoke any keyboard shortcut to run a program that allows you to run a command, such as KRunner, Konsole or Yakuake. With that, you can restart the plasmashell process with:


{{Input|1=<nowiki>
{{Input|1=<nowiki>
Line 35: Line 34:
</nowiki>}}
</nowiki>}}


And you might get a DrKonqi icon on your panel mentioning the KWin crash.
And you'll get a DrKonqi icon on your panel mentioning the KWin crash.


In case you were unable to create a backtrace using the KDE Crash Handler, proceed to the section [[KWin/Debugging#Debug KWin with GDB]].
In case you were unable to create a backtrace using the KDE Crash Handler or you are using the Wayland session, proceed to the section [[KWin/Debugging#Debug KWin with GDB| Debug KWin with GDB]].


== Install debug symbols ==
== Install debug symbols ==


TODO
Depending on your distribution, you might need additional steps before you're able to install debug symbols, as detailed on the [[Guidelines_and_HOWTOs/Debugging/How_to_create_useful_crash_reports#Install_debugging_packages| instructions on how to install debugging packages]].


= Debug KWin with GDB =
= Debug KWin with GDB =
Line 49: Line 48:
For ease of reference, users wanting to report a KWin crash can just copy-paste the following two commands, wait for the crash to happen and ignore the rest of this page. You'll get a file named kwin.gdb in your home folder (or wherever folder you run this command).
For ease of reference, users wanting to report a KWin crash can just copy-paste the following two commands, wait for the crash to happen and ignore the rest of this page. You'll get a file named kwin.gdb in your home folder (or wherever folder you run this command).


For KWin on the X11 session:
{{Input|1=<nowiki>
echo 0 | sudo tee /proc/sys/kernel/yama/ptrace_scope
gdb -pid $(pidof kwin_x11) -batch -ex "set logging file kwin_x11.gdb" -ex "set logging on" -ex "continue" -ex "thread apply all backtrace" -ex "quit"
</nowiki>}}
For KWin on the Wayland session:
{{Input|1=<nowiki>
{{Input|1=<nowiki>
echo 0 | sudo tee /proc/sys/kernel/yama/ptrace_scope
echo 0 | sudo tee /proc/sys/kernel/yama/ptrace_scope
gdb -pid $(pidof kwin_x11) -batch -ex "set logging file kwin.gdb" -ex "set logging on" -ex "continue" -ex "thread apply all backtrace" -ex "quit"
sudo gdb -pid $(pidof kwin_wayland) -batch -ex "set logging file kwin_wayland.gdb" -ex "set logging on" -ex "continue" -ex "thread apply all backtrace" -ex "quit"
</nowiki>}}
</nowiki>}}
{{Note| If you get a message stating "tee: /proc/sys/kernel/yama/ptrace_scope: No such file or directory", that means your distribution kernel does not have yama enabled, that is, this security module won't hinder you from attaching GDB to KWin. You can safely ignore this error.}}


If you want to know what these commands do (recommended), keep reading.
If you want to know what these commands do (recommended), keep reading.
Line 58: Line 66:
== General information ==
== General information ==


While interacting with GDB, the debugged process is stopped - that's of course nasty if the debugged process is what paints what you see. Therefore it's inevitable to debug KWin from a side-channel, eg. '''another VT''' or '''via SSH''' - depending on what's available on your system.
While interacting with GDB, the debugged process is stopped - that's of course nasty if the debugged process is what paints what you see and handles your input.


'''NOTICE''' that debugging from an SSH login is generally preferable, since it doesn't impact the framebuffer/scanout buffer state.
KWin used to have issues with attaching GDB, but it is no longer the case on X11. Nevertheless, if you ever encounter issues doing this, you'll need to debug KWin from a side-channel, eg. '''another TTY''' or '''via SSH''' depending on what's available on your system. On Wayland, logging in via SSH is mandatory for interactive debugging because KWin is responsible for input handling and VT switching.
 
{{Note| Debugging from an SSH connection is generally preferable over a TTY, since it doesn't impact the framebuffer/scanout buffer state.}}


== GDB says "ptrace: Operation not permitted." ==
== GDB says "ptrace: Operation not permitted." ==


This is probably the first thing you'll need to circumvent. By default, you're not allowed to attach GDB to KWin.
This is probably the first thing you'll need to circumvent. By default, you're not allowed to attach GDB to KWin on a kernel which has the '''Yama''' security module enabled.


This is a security feature in "newer" Linux kernels, you'll need to explicitly allow GDB to attach to a non-inferior process:
'''Yama''' is a kernel security feature which might or might not be enabled depending on your distro. In case it is, you'll need to explicitly allow GDB to attach to a non-inferior process:


{{Input|1=<nowiki>
{{Input|1=<nowiki>
Line 147: Line 157:
gdb -pid $(pidof kwin_x11) -batch -ex "set logging file kwin.gdb" -ex "set logging on" -ex "continue" -ex "thread apply all backtrace" -ex "quit"
gdb -pid $(pidof kwin_x11) -batch -ex "set logging file kwin.gdb" -ex "set logging on" -ex "continue" -ex "thread apply all backtrace" -ex "quit"
</nowiki>}}
</nowiki>}}


= Debug KWin with Valgrind =
= Debug KWin with Valgrind =


TODO
[https://www.valgrind.org/docs/manual/faq.html#faq.attach| It is not possible to attach Valgrind to running processes for fetching backtraces], but it is possible for Valgrind to run a nested KWin Wayland session with an XWayland server running rootless:
 
{{Input|1=<nowiki>
valgrind --log-file=kwinxwayland.log dbus-run-session kwin_wayland --xwayland
</nowiki>}}
 
And a pure KWin Wayland session:
 
{{Input|1=<nowiki>
valgrind --log-file=kwinwayland.log dbus-run-session kwin_wayland
</nowiki>}}
 
KWin X11 is limited to using the currently running dbus session, and therefore it cannot produce nested sessions. The <tt>--replace</tt> flag is used for substituting your current <tt>kwin_x11</tt> process.
 
{{Input|1=<nowiki>
valgrind --log-file=kwinx11.log kwin_x11 --replace
</nowiki>}}
 
{{Note| It's not possible to run a KWin X11 session from a KWin Wayland session.}}
In addition to creating backtraces, Valgrind is also able to log memory leaks.
 
{{Input|1=<nowiki>
valgrind --leak-check=full --show-reachable=yes --track-origins=yes --trace-children=yes --log-file=kwinxwaylandmem.log dbus-run-session kwin_wayland --xwayland"
</nowiki>}}
 


= Automatically fetch core dumps with coredumpctl =
= Automatically fetch core dumps with coredumpctl =


TODO edit /etc/systemd/coredump.conf
After installing systemd-coredumpctl, you should now have a file located in /etc/systemd/coredump.conf that can be used to configure coredumpctl.
 
The <tt>Storage=</tt> setting defaults to external. This means that core dumps, in addition to being available through coredumpctl, are stored as physical files under /var/lib/systemd/coredump/. If you wish to be able to rotate core dumps together with the journal, you might want to set Storage=journal.
 
{{Warning| The kwin_wayland process is not dumpable, which means coredumpctl is unable to fetch a full backtrace, rendering only truncated core dumps. Those are still useful, but if possible, SSH into your session and attach GDB directly.}}
 
{{Note| Older versions of kwin_wayland used to throw the user back to the login screen if it it got killed (SIGKILL) or suffered a segmentation fault (SIGSEGV). As per <nowiki>https://invent.kde.org/plasma/kwin/-/merge_requests/483</nowiki>, SIGSEGV no longer causes this issue.}}
 
The main instructions on using coredumpctl to fetch are available on [[Guidelines_and_HOWTOs/Debugging/How_to_create_useful_crash_reports#Retrieving_a_backtrace_using_coredumpctl| the wiki page on crash reporting]]. Basically, it amounts to this:
 
<tt>coredumpctl</tt> &rarr; check the PID of the crashed process &rarr; coredumpctl dbg <KWin PID here> &rarr; bt &rarr; copy into a log file
 
Or, alternatively:
 
{{Input|1=<nowiki>
coredumpctl dump <KWin PID>
</nowiki>}}
 
It's possible to create a log file containing the backtrace by setting the --output flag to cat and redirecting it to a file:
 
{{Input|1=<nowiki>
coredumpctl dump <KWin PID> --output=cat > kwincrash.log
</nowiki>}}


However, kwin_wayland crashes might be a bit trickier to debug. Because KWin plays the traditional role of what is known as Display Server (in X11 lingo) in a Wayland session, whenever it crashes, you get thrown off to the login screen. Therefore, it's advisable to use a different TTY or SSH and attach GDB directly instead of using coredumpctl (as systemd-coredump might not be able to fetch the stacktrace and it might get truncated).


= Getting debug log output =
= Getting debug log output =
Line 165: Line 221:
</nowiki>}}
</nowiki>}}


The logs in X are at {{Input|1=<nowiki>~/.xsession-errors</nowiki>}}
You can append the environment variable to your ~/.bash_profile or to /etc/environment. If you are a bug tester, you might prefer to use /etc/environment since it's a common workflow to create new users for bug testing.
The logs in Wayland are in {{Input|1=<nowiki>~/.local/share/sddm/wayland-session.log</nowiki>}}


TODO KDE_DEBUG=1 to disable DrKonqi
The logs for X11 are located in: {{Input|1=<nowiki>~/.xsession-errors</nowiki>}}
The logs for Wayland are located in: {{Input|1=<nowiki>~/.local/share/sddm/wayland-session.log</nowiki>}}

Revision as of 17:32, 22 February 2021

Getting diagnosis information for bug reports

If you want to fetch relevant information to report a bug with KWin, the following command will provide a general list of data that should help the KWin developers diagnose your problem.

qdbus org.kde.KWin /KWin supportInformation

Depending on your distro (e.g. openSUSE), by default the command might be named a bit differently:

qdbus-qt5 org.kde.KWin /KWin supportInformation

On occasion, xwininfo might be asked for by the developers if the issue concerns screens and windows, and xprop if the issue concerns window information. After running either of those two commands, you'll need to click the window that's showing issues.


Report issues via DrKonqi

Generally speaking, Plasmashell handles all widgets (including the menu), KWin handles windows and compositing (such as window decorations and desktop effects), and KGlobalAccel5 handles keyboard shortcuts.

In a situation where the Plasmashell and KGlobalAccel5 processes are still running but KWin (X11) has crashed, you will probably see a sad face in your notification tray, that's DrKonqi, the KDE Crash Handler, getting sad that you experienced a crash. Click its icon and you should be able to follow through with the crash reporting process in a straightforward manner.

In a situation where KGlobalAccel5 is still running but both Plasmashell and KWin have crashed, you can still invoke any keyboard shortcut to run a program that allows you to run a command, such as KRunner, Konsole or Yakuake. With that, you can restart the plasmashell process with:

plasmashell --replace

Or if you have manually enabled the new systemd initialization:

systemctl --user restart plasma-plasmashell

And you'll get a DrKonqi icon on your panel mentioning the KWin crash.

In case you were unable to create a backtrace using the KDE Crash Handler or you are using the Wayland session, proceed to the section Debug KWin with GDB.

Install debug symbols

Depending on your distribution, you might need additional steps before you're able to install debug symbols, as detailed on the instructions on how to install debugging packages.

Debug KWin with GDB

TL;DR for bug reporters

For ease of reference, users wanting to report a KWin crash can just copy-paste the following two commands, wait for the crash to happen and ignore the rest of this page. You'll get a file named kwin.gdb in your home folder (or wherever folder you run this command).

For KWin on the X11 session:

echo 0 | sudo tee /proc/sys/kernel/yama/ptrace_scope
gdb -pid $(pidof kwin_x11) -batch -ex "set logging file kwin_x11.gdb" -ex "set logging on" -ex "continue" -ex "thread apply all backtrace" -ex "quit"

For KWin on the Wayland session:

echo 0 | sudo tee /proc/sys/kernel/yama/ptrace_scope
sudo gdb -pid $(pidof kwin_wayland) -batch -ex "set logging file kwin_wayland.gdb" -ex "set logging on" -ex "continue" -ex "thread apply all backtrace" -ex "quit"

Note

If you get a message stating "tee: /proc/sys/kernel/yama/ptrace_scope: No such file or directory", that means your distribution kernel does not have yama enabled, that is, this security module won't hinder you from attaching GDB to KWin. You can safely ignore this error.


If you want to know what these commands do (recommended), keep reading.

General information

While interacting with GDB, the debugged process is stopped - that's of course nasty if the debugged process is what paints what you see and handles your input.

KWin used to have issues with attaching GDB, but it is no longer the case on X11. Nevertheless, if you ever encounter issues doing this, you'll need to debug KWin from a side-channel, eg. another TTY or via SSH depending on what's available on your system. On Wayland, logging in via SSH is mandatory for interactive debugging because KWin is responsible for input handling and VT switching.

Note

Debugging from an SSH connection is generally preferable over a TTY, since it doesn't impact the framebuffer/scanout buffer state.


GDB says "ptrace: Operation not permitted."

This is probably the first thing you'll need to circumvent. By default, you're not allowed to attach GDB to KWin on a kernel which has the Yama security module enabled.

Yama is a kernel security feature which might or might not be enabled depending on your distro. In case it is, you'll need to explicitly allow GDB to attach to a non-inferior process:

echo 0 | sudo tee /proc/sys/kernel/yama/ptrace_scope

Do I have to write down the debug output by hand ????

No ;-)

You just copy the gdb output into a file.

gdb --pid `pidof kwin_x11` 2>&1 | tee kwin.gdb

Alternatively, you can use the lengthier method made available by GDB.

gdb --pid `pidof kwin_x11`
set logging file kwin.gdb
set logging on

I know nothing about GDB, how do I obtain a stacktrace?

A stacktrace (or backtrace) is a set of data containing information of the state the program was when it crashed. It is the primary means for the KWin developers to find out what happened on your machine.

Nowadays it's common for programs to take advantage of multiple threads to run more efficiently and make better use of the CPU cores available on your machine. Different threads might run different parts of a program, and each thread can render a different stacktrace.

So after attaching GDB to the application process, you'll see the GDB shell. It's where you'll run instructions so GDB can fetch the information you want.

Immediately after attaching GDB, it will stop the process, but you'll likely want to cause a certain condition (halt or crash) while KWin is running - in that case you first need to

continue

the process before it can be crashed.

If KWin does not crash, but you want to inspect the stack at some other time, you'll first need to interrupt the process by pressing

Ctrl+C

To dump a stacktrace, issue

bt

With this command you will get the stacktrace for the main thread where KWin crashed.

Then, hit the

Enter

key until you reach the end of the stack.

Sometimes, you may want to see what's in another thread

thread 2
bt
thread 3
bt

Alternatively, to dump a stacktrace the same way DrKonqi does (i.e. showing all available threads), use

thread apply all backtrace

This is probably the best method if you want to provide some awesome stacktraces for the KWin devs!

Finally, to leave GDB:

detach
quit

Automating the creation of backtraces

GDB provides an easy way to automate debugging: the -batch flag. After enabling it, you should be able to run commands sequentially with -ex or --eval-command. A more detailed explanation of the procedure can be seen in Plasma/Debugging.

gdb -pid $(pidof kwin_x11) -batch -ex "set logging file kwin.gdb" -ex "set logging on" -ex "continue" -ex "thread apply all backtrace" -ex "quit"


Debug KWin with Valgrind

It is not possible to attach Valgrind to running processes for fetching backtraces, but it is possible for Valgrind to run a nested KWin Wayland session with an XWayland server running rootless:

valgrind --log-file=kwinxwayland.log dbus-run-session kwin_wayland --xwayland

And a pure KWin Wayland session:

valgrind --log-file=kwinwayland.log dbus-run-session kwin_wayland

KWin X11 is limited to using the currently running dbus session, and therefore it cannot produce nested sessions. The --replace flag is used for substituting your current kwin_x11 process.

valgrind --log-file=kwinx11.log kwin_x11 --replace

Note

It's not possible to run a KWin X11 session from a KWin Wayland session.

In addition to creating backtraces, Valgrind is also able to log memory leaks.

valgrind --leak-check=full --show-reachable=yes --track-origins=yes --trace-children=yes --log-file=kwinxwaylandmem.log dbus-run-session kwin_wayland --xwayland"


Automatically fetch core dumps with coredumpctl

After installing systemd-coredumpctl, you should now have a file located in /etc/systemd/coredump.conf that can be used to configure coredumpctl.

The Storage= setting defaults to external. This means that core dumps, in addition to being available through coredumpctl, are stored as physical files under /var/lib/systemd/coredump/. If you wish to be able to rotate core dumps together with the journal, you might want to set Storage=journal.

Warning

The kwin_wayland process is not dumpable, which means coredumpctl is unable to fetch a full backtrace, rendering only truncated core dumps. Those are still useful, but if possible, SSH into your session and attach GDB directly.


Note

Older versions of kwin_wayland used to throw the user back to the login screen if it it got killed (SIGKILL) or suffered a segmentation fault (SIGSEGV). As per https://invent.kde.org/plasma/kwin/-/merge_requests/483, SIGSEGV no longer causes this issue.


The main instructions on using coredumpctl to fetch are available on the wiki page on crash reporting. Basically, it amounts to this:

coredumpctl → check the PID of the crashed process → coredumpctl dbg <KWin PID here> → bt → copy into a log file

Or, alternatively:

coredumpctl dump <KWin PID>

It's possible to create a log file containing the backtrace by setting the --output flag to cat and redirecting it to a file:

coredumpctl dump <KWin PID> --output=cat > kwincrash.log


Getting debug log output

The environment variable QT_LOGGING_RULES can be used to turn on full debug output from KWin:

export QT_LOGGING_RULES="kwin_*.debug=true"

You can append the environment variable to your ~/.bash_profile or to /etc/environment. If you are a bug tester, you might prefer to use /etc/environment since it's a common workflow to create new users for bug testing.

The logs for X11 are located in:

~/.xsession-errors

The logs for Wayland are located in:

~/.local/share/sddm/wayland-session.log