docs: record what firmware fixed, and what it turns out not to fix

The motd was the worst of it — it told anyone logging in that "WiFi and
Bluetooth work with the firmware Fedora ships", which is precisely backwards for
the onboard adapter, and pointed at a Windows partition this machine no longer
has.

What the blobs did fix, verified: the GPU initialises, ADSP/CDSP/SLPI all run,
sensors appear as IIO devices, venus registers /dev/video0-3.

What they did not, and why, so nobody repeats the search:

Onboard WiFi is loaded by the modem — wlan*mdsp* is the WLAN Modem DSP — so
ath10k_snoc binds and then waits silently on a QMI service that never arrives.
The modem boots and dies at "RF stuck in QLINK start state", the RF front-end,
which is board-specific wiring in a way the SoC-level blobs are not. These are
Qualcomm *reference* drivers; good enough for the GPU and DSPs, evidently not
for this machine's radio. Three plausible fixes that do not work are recorded
too: rmtfs (correct to enable, does not help), the _nm firmware variants
(rejected at PBL), and unplugging the USB dongle (different bus entirely — it
was never competing).

Audio gets further than expected. The codec answers over SLIMbus with its chip
id, so hardware and ADSP are fine; what fails is the codec's SoundWire block
declaring two data-in ports where the controller expects six. That is a kernel
mismatch and needs a kernel change.

Also record the mesa caveat properly: the GPU works, but freedreno's EGL path
segfaults gnome-shell into a login loop, and LIBGL_ALWAYS_SOFTWARE does nothing
because mutter uses EGL. MESA_LOADER_DRIVER_OVERRIDE=kms_swrast is what works.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XWRjNJMistCy6ngXH5aJLS

README.md

@@ -31,22 +31,31 @@ login. Root is locked.
 
 ## Hardware status
 
-| Works out of the box            | Needs firmware from Windows | Not supported |
+| Works | Works once you supply firmware | Does not work |
-|---------------------------------|-----------------------------|---------------|
+|---|---|---|
-| UFS storage, USB, keyboard, touchpad, touchscreen | Graphics (Adreno 630 zap shader) | LTE modem |
+| UFS storage, USB, keyboard, touchpad, touchscreen | Adreno 630 initialises — see mesa note below | Audio — kernel driver, not firmware |
-| WiFi + Bluetooth (ath10k WCN3990) | Audio | |
+| Display (unaccelerated), battery, charging | Sensor hub — accelerometer, auto-rotate | Onboard WiFi — needs modem firmware no public source provides |
-| Battery and charging            | Sensor hub — lid switch, accelerometer, auto-rotate | |
+| USB WiFi dongles, USB phone tethering | Hardware video decode (venus, `/dev/video0-3`) | LTE modem — same reason |
-| Display (unaccelerated)         | Hardware video decode (venus) | |
 
-Fedora ships everything Qualcomm permits to be redistributed, which covers
+Verified on hardware. `docs/firmware.md` has the evidence for each, including
-WiFi and Bluetooth outright. Graphics is the awkward case: the generic Adreno
+the things that look like they should help and do not.
-pieces (`a630_gmu.bin`, `a630_sqe.fw`) are packaged, but the C630's device tree
-asks for a **model-signed** zap shader, `qcdxkmsuc850.mbn`, which exists only in
-your machine's Windows partition — Fedora's generic `sdm845/a630_zap.mbn` is not
-what this device requests. Audio, sensors and video decode are the same story.
 
-Run `sudo c630-firmware` once after installing — see
+**Graphics comes with a caveat.** With `qcdxkmsuc850.mbn` in place the GPU
-[docs/firmware.md](docs/firmware.md) for the full list and a manual fallback.
+genuinely initialises — `gpu-initialized: 1`, revision 630, executing
+submissions. But mesa's freedreno EGL path then segfaults in
+`dri2_drm_swap_buffers`, taking gnome-shell down in a login loop. Until that is
+fixed upstream, the desktop needs software rendering:
+
+```sh
+echo 'MESA_LOADER_DRIVER_OVERRIDE=kms_swrast' | sudo tee /etc/environment
+```
+
+Note `LIBGL_ALWAYS_SOFTWARE=1` does *not* work here — mutter uses EGL, which
+ignores it.
+
+Getting the firmware: see
+[docs/firmware.md](docs/firmware.md). The cabinets from WOA-Project are the
+easiest route; `sudo c630-firmware` works if the Windows partition survives.
 
 ## Building
 
@@ -119,7 +128,7 @@ docs/                        Installation, firmware, runner setup
 ## Documentation
 
 - [docs/install.md](docs/install.md) — writing the image and booting the laptop
-- [docs/firmware.md](docs/firmware.md) — what needs extracting from Windows and why
+- [docs/firmware.md](docs/firmware.md) — the per-model blobs: what they enable, where to get them, and what they do not fix
 - [docs/runner-setup.md](docs/runner-setup.md) — one-time Gitea runner preparation
 
 ## Boot status
@@ -141,11 +150,11 @@ is installed and corrects the clock once the network is up. Until it does, rpm
 rejects package signatures dated after the (wrong) current time and reports
 installed packages as missing — see [docs/install.md](docs/install.md).
 
-Onboard WiFi does not appear at all, and audio, sensors, video decode and
+With the per-model firmware supplied, the GPU initialises, the ADSP, CDSP and
-accelerated graphics are all absent — every one of them waiting on the
+SLPI all run, sensors appear as IIO devices and venus registers `/dev/video0-3`.
-model-signed firmware described in [docs/firmware.md](docs/firmware.md). On
+Audio and onboard WiFi remain broken for reasons unrelated to firmware — see
-this machine Windows has been wiped, so those blobs are gone; the kernel names
+[docs/firmware.md](docs/firmware.md), which records both the evidence and the
-each missing file explicitly in `dmesg`.
+several plausible fixes that turn out not to work.
 
 The internal drive needs `build/install-to-disk.sh` rather than `dd`: its UFS
 uses 4096-byte logical sectors, which the 512-byte image geometry cannot be

docs/firmware.md

@@ -194,6 +194,76 @@ circulated before, and any 81JL's copy is as good as your own.
 Whichever route, drop the result into `firmware/local/` and rebuild — see
 [Baking firmware into the image](#baking-firmware-into-the-image).
 
+## What the firmware does not fix
+
+Installing all of it still leaves two things broken, both for reasons that are
+not about firmware. Recorded here so nobody repeats the search.
+
+### Onboard WiFi needs the modem, and the modem needs firmware nobody publishes
+
+The name gives it away: **wlan*mdsp*** is the WLAN *Modem* DSP. On SDM845 the
+WiFi firmware is loaded by the modem subsystem, so `ath10k_snoc` binds to
+`18800000.wifi` and then sits silent, waiting on a QMI service that only appears
+once the modem is up. It never logs an error, because from its point of view
+nothing has gone wrong yet.
+
+The modem itself boots and then dies:
+
+```
+qcom-q6v5-mss 4080000.remoteproc: MBA booted without debug policy, loading mpss
+qcom-q6v5-mss 4080000.remoteproc: fatal error received:
+    RFLM@rflm_qlnk.cpp:1087 [3,3] RF stuck in QLINK start state: 0x0 after maximum
+remoteproc remoteproc0: crash detected ... recovering
+```
+
+QLINK is the RF front-end interface, and RF front-end wiring is board-specific
+in a way the DSP and GPU images are not. The WOA-Project cabinets are Qualcomm
+*reference* drivers: good enough for the SoC-level blobs, evidently not for this
+machine's radio. It restarts about every 42 seconds until stopped.
+
+Things that sound like they should help and do not:
+
+- **`rmtfs`.** The modem stores its NV and calibration on the `modemst1`,
+  `modemst2`, `fsg` and `fsc` partitions and reaches them through the `rmtfs`
+  daemon. Fedora packages it, and it is disabled by default. Enabling it is
+  correct and worth doing — `sudo systemctl enable --now rmtfs` — but the QLINK
+  failure persists with it running. Its "failed to update start state" warnings
+  are its optional remoteproc-control helper and are harmless.
+- **The `_nm` firmware variants.** `qcdsp1v2850_nm.mbn` and `qcdsp2850_nm.mbn`
+  are the no-modem images, 5.7 MB against 60 MB, analogous to the `modem_nm.mbn`
+  Fedora ships for generic sdm845. They are rejected before they even run:
+  `PBL returned unexpected status`.
+- **Unplugging the USB WiFi dongle.** Different bus, different driver, no
+  interaction. `ath10k_snoc` is waiting on the modem, not competing for a radio.
+
+A USB dongle or USB tethering from a phone is the practical answer.
+
+### Audio is a kernel driver problem
+
+The ADSP runs, the audio services register, and the codec answers:
+
+```
+wcd934x-slim 217:250:1:0: WCD934x chip id major 0x108, minor 0x1
+```
+
+So SLIMbus, the ADSP and the hardware are all fine. What fails is one sub-device
+of the codec:
+
+```
+qcom-soundwire wcd934x-soundwire.12.auto: din-ports (2) mismatch with controller (6)
+platform sound: deferred probe pending: msm-snd-sdm845: SLIM Playback: codec dai not found
+```
+
+The codec's SoundWire block declares two data-in ports where the controller
+expects six, so it never probes, so the sound card has no codec DAI and never
+appears. That is a mismatch inside the kernel, and needs a kernel or
+device-tree change rather than any blob.
+
+One thing worth knowing if you go looking: `slim_qcom_ngd_ctrl` can probe before
+the ADSP is ready and log `QMI wait timeout`. Reloading the module afterwards
+gets the codec detected, which is how the chip ID above was obtained — but it
+does not get past the SoundWire mismatch.
+
 ## Extracting them
 
 The image ships Fedora's `qcom-firmware-extract`. Run it once:

overlay/etc/motd.d/c630.in

@@ -1,7 +1,11 @@
 
   Fedora @FEDORA_RELEASE@ for the @DEVICE_DESC@  (built @BUILD_DATE@ from @BUILD_REF@)
 
-  WiFi and Bluetooth work with the firmware Fedora ships. Accelerated
+  No per-model Qualcomm firmware ships in this image — it is not
-  graphics, audio, the sensor hub and video decode all need per-model blobs
+  redistributable. Supply it to get accelerated graphics, audio, the sensor
-  from the Windows partition — run `sudo c630-firmware` once to extract them.
+  hub and hardware video decode: see docs/firmware.md, or run
+  `sudo c630-firmware` if this machine still has its Windows partition.
+
+  Onboard WiFi additionally needs modem firmware that no public source
+  provides. Use a USB dongle or tether a phone over USB.