update documentation

2026-08-15 17:55:33 +02:00
parent 39a16e8650
commit 520ce45a50
5 changed files with 111 additions and 2 deletions
@@ -5,6 +5,111 @@

 Install the firmware `sof-firmware`

+### Random Freezes (SoundWire Kernel Panic)
+
+On kernel `7.1.x` the machine hard-hangs every day or two. The internal panel freezes on its last
+frame, the external DisplayPort monitors go black, the LED above the keyboard starts blinking, and
+nothing at all is written to the journal. Only a long press on the power button recovers it.
+
+The cause is a NULL pointer dereference in the Intel SoundWire interrupt handler.
+`sdw_intel_thread` walks the SoundWire link list and calls `sdw_cdns_irq(irq, link->cdns)` while the
+links are powered back up after a runtime suspend. One link is still listed with `cdns == NULL`, so
+the handler dereferences NULL. The kernel dies in interrupt context, which is why the journal stays
+empty — journald never gets a chance to flush.
+
+.collapse {Panic trace}
+	```txt
+	Oops: general protection fault, kernel NULL pointer dereference 0x3c0: 0000 [#1] SMP NOPTI
+	CPU: 3 UID: 0 PID: 807 Comm: irq/146-AudioDS
+	Hardware name: Dell Inc. XPS 13 9350/0MMW13, BIOS 1.22.0 06/01/2026
+	RIP: 0010:sdw_cdns_irq+0x9/0x290 [soundwire_cadence]
+	RSI: 0000000000000000
+	Call Trace:
+	 <TASK>
+	 sdw_intel_thread+0x3b/0x70          [soundwire_intel]
+	 hda_dsp_interrupt_thread+0x99/0x380 [snd_sof_intel_hda_generic]
+	 irq_thread_fn+0x25/0x60
+	 irq_thread+0x1cb/0x340
+	 kthread+0xe4/0x120
+	 ret_from_fork+0x2a7/0x330
+	 </TASK>
+
+	kernel tried to execute NX-protected page - exploit attempt? (uid: 0)
+	BUG: unable to handle page fault for address: ffff88f18fab5340
+	Oops: Oops: 0011 [#2] SMP NOPTI
+	```
+
+	The faulting instruction is `cmpb $0x0, 0x3c0(%rsi)` with `RSI = 0`. The second fault is what makes
+	the hang unrecoverable rather than just killing the interrupt thread.
+
+Anything that repeatedly wakes the audio controller makes this far more likely — a Spotify stream
+running in the background is enough. Before the workaround the controller spent roughly 89% of its
+uptime runtime-suspended, so the race window was being hit constantly.
+
+Pin the audio controller out of runtime power management so the SoundWire links stay powered and the
+window never opens.
+
+`/etc/udev/rules.d/99-sof-audio-no-runtime-pm.rules`:
+
+```txt
+ACTION=="add|bind", SUBSYSTEM=="pci", ATTR{vendor}=="0x8086", ATTR{device}=="0xa828", ATTR{power/control}="on"
+```
+
+Matching on the PCI ID `8086:a828` rather than the slot `0000:00:1f.3` keeps the rule valid if the
+device is ever renumbered. `add|bind` covers both device registration and driver bind.
+
+Apply it without rebooting:
+
+```sh
+sudo udevadm control --reload
+sudo udevadm trigger --action=add /sys/bus/pci/devices/0000:00:1f.3
+```
+
+Verify. `control` must read `on` and `runtime_status` must read `active`:
+
+```sh
+cat /sys/bus/pci/devices/0000:00:1f.3/power/{control,runtime_status}
+```
+
+From this point `runtime_suspended_time` must stop increasing, with all further time accruing to
+`runtime_active_time`. If it keeps climbing, the pin is not actually holding:
+
+```sh
+cat /sys/bus/pci/devices/0000:00:1f.3/power/runtime_suspended_time
+cat /sys/bus/pci/devices/0000:00:1f.3/power/runtime_active_time
+```
+
+Confirm the rule also applies on a fresh boot rather than only surviving the manual trigger:
+
+```sh
+udevadm test --action=add /sys/bus/pci/devices/0000:00:1f.3 2>&1 | grep power/control
+```
+
+.box {This is a mitigation, not a fix} type:{warning}
+	The driver defect is still present. The rule only stops it from being triggered.
+
+	If the freezes return, bypass SoundWire entirely by forcing the legacy HDA driver in
+	`/etc/modprobe.d/`:
+
+	```txt
+	options snd-intel-dspcfg dsp_driver=1
+	```
+
+	This costs the internal speakers and the internal microphone array, since both sit behind
+	SoundWire (`rt1318` amplifiers and an `rt715` microphone). USB and HDMI/DisplayPort audio keep
+	working.
+
+.box {Ruled out} type:{note}
+	`power-profiles-daemon` is not the cause, despite the timing looking suspicious — most of the
+	panics predate its installation. See [Power Profiles](003-power-profiles.qd).
+
+	The hardware is fine too: no machine check exceptions, no ECC or EDAC errors, and `fwupdmgr`
+	reports all firmware current.
+
+	Capturing a fresh trace would need `efi_pstore.pstore_disable=0` on the kernel command line,
+	which means creating `/etc/kernel/cmdline`, regenerating the unified kernel image and re-signing
+	it. `CONFIG_EFI_VARS_PSTORE_DEFAULT_DISABLE` is set, so panics are not persisted by default.
+
 ## Camera

 The camera, while available on free software and without drivers,