常见内核故障 - Qualcomm Dragonwing Documentation

针对使用 Qualcomm^® Linux 内核时最常见故障的定向诊断步骤和修复方法。

启动失败

内核无法启动，黑屏或无串口输出

首先检查：

确认已配置串口控制台（内核命令行中包含 console=ttyMSM0,115200n8）。
通过重新运行 fastboot flash efi efi.bin 验证 efi.bin 已成功烧写，并检查是否有 OKAY 响应。
如果携带 EFI 变量的 RPMB 持久状态已损坏或错位，请擦除 RPMB 区域：

fastboot oem rpmb_erase

在内核命令行中添加 earlycon，以便在 UART 驱动初始化之前获得输出。

# Minimum working kernel command line for serial output
console=ttyMSM0,115200n8 earlycon

有关串口控制台设置，请参阅内核日志。

启动时内核 panic

启动期间的内核 panic 会在串口控制台上产生调用栈。捕获它并找出出错的函数：

# After collecting the panic log
dmesg | grep -A 30 "Kernel panic"

Qualcomm Linux 上的常见原因：

Panic 消息	可能原因
`Unable to handle kernel NULL pointer dereference`	驱动程序在资源初始化之前访问该资源（probe 顺序问题）
`SError Interrupt on CPU`	要调试未开时钟或受保护的寄存器访问，请启用 MMIO 跟踪（参阅内核探针和跟踪）
`Kernel panic - not syncing: VFS: Unable to mount root fs`	根分区标签不匹配或缺少文件系统驱动程序
`KASAN: use-after-free`	要检查内存安全缺陷，请在调试构建中启用 `CONFIG_KASAN=y` 以获取更多详细信息

设备树问题

DTB 认证失败

UEFI 固件在将 DTB 传递给内核之前会对其进行认证。认证失败会导致内核无法接收任何设备树。日志特征：

Platform Subtype : 0
DtPlatformLoadDtb qcs6490-rb3gen2.dtb is loaded
Platform Subtype : -2090817768
DtPlatformLoadSign qcs6490-rb3gen2.sgn is loaded
failed to authenticate image !

**修复：**烧写与设备上当前预置的签名密钥相匹配的、正确签名的 dtb.bin。确保 efi.bin 和 dtb.bin 来自同一次构建。

未找到 DTB

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

修复：

验证 DTB 已包含在打包的 dtb.bin 中：如果使用传统的拼接式 dtb 打包：

# On the host
mount -o loop -t vfat dtb.bin /mnt/
fdtdump /mnt/combined-dtb.bin | grep -i model

如果使用基于 FIT 的打包：

# On the host
mount -o loop -t vfat dtb.bin /mnt/
fdtdump /mnt/qclinux_fit.img | grep -i compatible

检查开发板的 DTS 文件是否列在 Yocto machine 配置的 KERNEL_DEVICETREE 中。
重新烧写 dtb.bin：
fastboot flash dtb_a dtb.bin

验证运行时加载了哪个 DTB

成功启动后，确认加载了正确的设备树：

dmesg | grep -i "machine model\|compatible\|of_flat_dt"
# or
cat /proc/device-tree/model

启动期间的 DTB 识别

有关设备树识别的更多信息，请参阅常见 DTB 问题。

模块加载失败

`Invalid module format`，显示 vermagic 不匹配

insmod: ERROR: could not insert module my_driver.ko: Invalid module format

**原因：**该模块是针对与正在运行的内核不同的内核版本、配置或编译器构建的。 .ko 文件中嵌入的 vermagic 字符串不匹配。 诊断：

# 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

**修复：**针对生成正在运行的内核镜像的确切内核源码树（相同的 KERNEL_SRC、相同的 defconfig 和片段）重新构建模块。如果使用 Yocto，请使用 bitbake qcom-multimedia-image 重新构建，以保持模块与内核同步。

缺少 `.ko` 文件

insmod: ERROR: could not insert module my_driver.ko: No such file or directory

诊断：

find /lib/modules/$(uname -r) -name "my_driver.ko"

**修复：**确保模块已构建（Makefile 中包含 obj-m += my_driver.o）且已安装（通过 make modules_install 或 Yocto 的 module 类）。

模块未找到且未出现在 modules.dep 中

modprobe: FATAL: Module my_driver not found in directory /lib/modules/<version>

**修复：**安装新模块后，运行 depmod 以重建模块依赖映射：

depmod -a
modprobe my_driver

模块加载成功但不工作

在 insmod 之后立即检查 dmesg 中的探测错误：

dmesg | tail -30

常见模式：

日志模式	原因
`probe of ... failed with error -19`	`-ENODEV`，硬件不存在或 DT 节点为 `status = "disabled"`
`probe of ... failed with error -22`	`-EINVAL`，设备树属性缺失或格式错误
`probe of ... deferred`	`-EPROBE_DEFER`，某个依赖项（时钟、稳压器、GPIO）尚未就绪

对于延迟探测（deferred probe），检查哪些设备仍处于挂起状态：

cat /sys/kernel/debug/devices_deferred

串口控制台不工作

如果烧写新内核后串口控制台没有输出：

验证 Kconfig：

zcat /proc/config.gz | grep QCOM_GENI
# Required: CONFIG_SERIAL_QCOM_GENI=y, CONFIG_SERIAL_QCOM_GENI_CONSOLE=y

验证内核命令行：

cat /proc/cmdline
# Must contain: console=ttyMSM0,115200n8

**获取早期启动消息：**在内核命令行中添加 earlycon。这可以在 UART 驱动完全初始化之前启用输出。
**检查线缆和波特率：**确认设备和主机终端两侧均为 115200 波特、8N1、无硬件流控。

Remoteproc 故障

固件加载失败

remoteproc remoteproc0: Direct firmware load for qcom/qcs6490/adsp.mdt failed with error -2

**修复：**确保所有必需的固件文件都存在于 /lib/firmware/qcom/<SoC>/ 中：

ls /lib/firmware/qcom/qcs6490/
# Required: adsp.mdt, adsp.b00, adsp.b01, ..., cdsp.mdt, wpss.mdt

在子系统崩溃时捕获日志

为了防止 remoteproc 驱动自动恢复崩溃的子系统（这会清除崩溃日志），请在复现崩溃之前禁用恢复功能：

echo disabled > /sys/kernel/debug/remoteproc/remoteprocN/recovery

崩溃日志示例：

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

启用 coredump 以捕获内存快照供离线分析：

echo enabled > /sys/kernel/debug/remoteproc/remoteprocN/coredump
# After the crash:
cp /sys/class/devcoredump/devcdN/data /var/spool/crash/dump_file.elf

将 .elf 文件传输到主机，并使用 Qualcomm Crash Analysis Portal（QCAP）进行分析。有关更多详细信息，请参阅配置远程处理器子系统。

​启动失败

​内核无法启动，黑屏或无串口输出

​启动时内核 panic

​设备树问题

​DTB 认证失败

​未找到 DTB

​验证运行时加载了哪个 DTB

​启动期间的 DTB 识别

​模块加载失败

​Invalid module format，显示 vermagic 不匹配

​缺少 .ko 文件

​模块未找到且未出现在 modules.dep 中

​模块加载成功但不工作

​串口控制台不工作

​Remoteproc 故障

​固件加载失败

​在子系统崩溃时捕获日志