> ## Documentation Index
> Fetch the complete documentation index at: https://dragonwingdocs.qualcomm.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Common kernel failures

Targeted diagnosis steps and fixes for the most common
failures encountered when working with the Qualcomm<sup>®</sup> Linux kernel.

## Boot failures

### Kernel does not boot with a black screen or no serial output

**Check first:**

1. Confirm the serial console is configured (`console=ttyMSM0,115200n8` in the
   kernel command line).
2. Verify `efi.bin` was flashed successfully by re-running `fastboot flash efi efi.bin`
   and check for `OKAY` responses.
3. Erase RPMB area in case its persistent state carrying EFI variables is corrupted or misaligned:

```text theme={null}
fastboot oem rpmb_erase
```

4. Add `earlycon` to the kernel command line to get output before the UART
   driver initialises.

```text theme={null}
# Minimum working kernel command line for serial output
console=ttyMSM0,115200n8 earlycon
```

See [Kernel logging](./kernel-logging) for serial console setup.

### Kernel panic at boot

A kernel panic during boot produces a call stack on the serial console. Capture
it and identify the faulting function:

```bash theme={null}
# After collecting the panic log
dmesg | grep -A 30 "Kernel panic"
```

Common causes on Qualcomm Linux:

| **Panic message**                                          | **Likely cause**                                                                                                                   |
| :--------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------- |
| `Unable to handle kernel NULL pointer dereference`         | Driver accesses a resource before it is initialised (probe order issue)                                                            |
| `SError Interrupt on CPU`                                  | To debug unclocked or protected register access, enable MMIO traces (see [Kernel probes and tracing](./kernel-probes-and-tracing)) |
| `Kernel panic - not syncing: VFS: Unable to mount root fs` | Root partition label mismatch or missing file system driver                                                                        |
| `KASAN: use-after-free`                                    | To check memory safety bug, enable `CONFIG_KASAN=y` in a debug build to get more detail                                            |

## Device tree issues

### DTB authentication failure

UEFI firmware authenticates the DTB before passing it to the kernel. An
authentication failure prevents the kernel from receiving any device tree.

Log signature:

```text theme={null}
Platform Subtype : 0
DtPlatformLoadDtb qcs6490-rb3gen2.dtb is loaded
Platform Subtype : -2090817768
DtPlatformLoadSign qcs6490-rb3gen2.sgn is loaded
failed to authenticate image !
```

**Fix:** Flash the correctly signed `dtb.bin` that matches the current signing
key provisioned on the device. Ensure `efi.bin` and `dtb.bin` are from the same
build.

### DTB not found

```text theme={null}
DtPlatformLoadDtb qcs6490-rb3gen2.dtb is loading failed with Status = E
DtPlatformDxeEntryPoint: no DTB blob could be loaded, defaulting to ACPI
```

**Fix:**

1. Verify the DTB is included in the packaged `dtb.bin`:

   if using legacy concatenated dtb packaging:

   ```bash theme={null}
   # On the host
   mount -o loop -t vfat dtb.bin /mnt/
   fdtdump /mnt/combined-dtb.bin | grep -i model
   ```

   if using FIT-based packaging:

   ```bash theme={null}
   # On the host
   mount -o loop -t vfat dtb.bin /mnt/
   fdtdump /mnt/qclinux_fit.img | grep -i compatible
   ```

2. Check that the board DTS file is listed in `KERNEL_DEVICETREE` in the Yocto
   machine configuration.

3. Reflash `dtb.bin`:

   ```bash theme={null}
   fastboot flash dtb_a dtb.bin
   ```

### Verify which DTB was loaded at runtime

After a successful boot, confirm the correct device tree was loaded:

```bash theme={null}
dmesg | grep -i "machine model\|compatible\|of_flat_dt"
# or
cat /proc/device-tree/model
```

### DTB identification during boot

Refer [common dtb issues](./common-dt-issues) for more information on device tree identification.

## Module load failures

### `Invalid module format` showing vermagic mismatch

```text theme={null}
insmod: ERROR: could not insert module my_driver.ko: Invalid module format
```

**Cause:** The module was built against a different kernel version, configuration,
or compiler than the running kernel. The `vermagic` string embedded in the `.ko`
file does not match.

**Diagnose:**

```bash theme={null}
# Check the module's vermagic
modinfo my_driver.ko | grep vermagic

# Check the running kernel's vermagic
modinfo /lib/modules/$(uname -r)/kernel/drivers/net/dummy.ko | grep vermagic
# or
uname -r
```

**Fix:** Rebuild the module against the exact kernel source tree (same `KERNEL_SRC`,
same `defconfig` and fragments) that produced the running kernel image. If using
Yocto, rebuild with `bitbake qcom-multimedia-image` to keep the module and
kernel in sync.

### missing `.ko` file

```text theme={null}
insmod: ERROR: could not insert module my_driver.ko: No such file or directory
```

**Diagnose:**

```bash theme={null}
find /lib/modules/$(uname -r) -name "my_driver.ko"
```

**Fix:** Ensure the module is built (`obj-m += my_driver.o` in the Makefile)
and installed (`make modules_install` or via Yocto `module` class).

### Module not found and missing from modules.dep

```text theme={null}
modprobe: FATAL: Module my_driver not found in directory /lib/modules/<version>
```

**Fix:** Run `depmod` to rebuild the module dependency map after installing new
modules:

```bash theme={null}
depmod -a
modprobe my_driver
```

### Module loads but does not work

Check `dmesg` immediately after `insmod` for probe errors:

```bash theme={null}
dmesg | tail -30
```

Common patterns:

| **Log pattern**                      | **Cause**                                                               |
| :----------------------------------- | :---------------------------------------------------------------------- |
| `probe of ... failed with error -19` | `-ENODEV`, hardware not present or DT node has `status = "disabled"`    |
| `probe of ... failed with error -22` | `-EINVAL`, missing or malformed device tree property                    |
| `probe of ... deferred`              | `-EPROBE_DEFER`, a dependency (clock, regulator, GPIO) is not yet ready |

For deferred probe, check which devices are still pending:

```bash theme={null}
cat /sys/kernel/debug/devices_deferred
```

## Serial console not working

If there is no output on the serial console after flashing a new kernel:

1. **Verify Kconfig:**

   ```bash theme={null}
   zcat /proc/config.gz | grep QCOM_GENI
   # Required: CONFIG_SERIAL_QCOM_GENI=y, CONFIG_SERIAL_QCOM_GENI_CONSOLE=y
   ```

2. **Verify kernel command line:**

   ```bash theme={null}
   cat /proc/cmdline
   # Must contain: console=ttyMSM0,115200n8
   ```

3. **Get early boot messages:** Add `earlycon` to the kernel command line. This
   enables output before the UART driver is fully initialised.

4. **Check the cable and baud rate:** Confirm 115200 baud, 8N1, no hardware
   flow control on both the device and the host terminal.

## Remoteproc failures

### Firmware load failure

```text theme={null}
remoteproc remoteproc0: Direct firmware load for qcom/qcs6490/adsp.mdt failed with error -2
```

**Fix:** Ensure all required firmware files are present in `/lib/firmware/qcom/<SoC>/`:

```bash theme={null}
ls /lib/firmware/qcom/qcs6490/
# Required: adsp.mdt, adsp.b00, adsp.b01, ..., cdsp.mdt, wpss.mdt
```

### Capture logs on subsystem crash

To prevent the remoteproc driver from automatically recovering a crashed
subsystem (which clears the crash logs), disable recovery before reproducing
the crash:

```bash theme={null}
echo disabled > /sys/kernel/debug/remoteproc/remoteprocN/recovery
```

Sample crash log:

```text theme={null}
qcom_q6v5_pas 3000000.remoteproc: fatal error received
remoteproc remoteproc2: crash detected in 3000000.remoteproc: type fatal error
remoteproc remoteproc2: handling crash #1 in 3000000.remoteproc
```

Enable coredump to capture a memory snapshot for offline analysis:

```bash theme={null}
echo enabled > /sys/kernel/debug/remoteproc/remoteprocN/coredump
# After the crash:
cp /sys/class/devcoredump/devcdN/data /var/spool/crash/dump_file.elf
```

Transfer the `.elf` file to a host and analyse with the Qualcomm Crash Analysis
Portal (QCAP). For more detail see
[Configure the remoteprocessor subsystems](./configure-the-remoteprocessor-remoteproc-subsystems).