> ## 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.

# 常见内核故障

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

## 启动失败

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

**首先检查：**

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

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

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

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

有关串行控制台设置，请参阅[内核日志](./kernel-logging)。

### 启动时内核 panic

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

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

Qualcomm Linux 上的常见原因：

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

## 设备树问题

### DTB 认证失败

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

日志特征：

```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 !
```

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

### 未找到 DTB

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

**修复：**

1. 验证 DTB 已包含在打包的 `dtb.bin` 中：

   如果使用传统的拼接式 dtb 打包：

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

   如果使用基于 FIT 的打包：

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

2. 检查开发板 DTS 文件已列在 Yocto 机器配置的 `KERNEL_DEVICETREE` 中。

3. 重新刷写 `dtb.bin`：

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

### 在运行时验证加载了哪个 DTB

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

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

### 启动期间的 DTB 识别

有关设备树识别的更多信息，请参阅[常见 DTB 问题](./common-dt-issues)。

## 模块加载失败

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

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

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

**诊断：**

```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
```

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

### 缺少 `.ko` 文件

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

**诊断：**

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

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

### 未找到模块且 modules.dep 中缺失

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

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

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

### 模块可加载但不工作

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

```bash theme={null}
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）尚未就绪         |

对于延迟探测，检查哪些设备仍处于待处理状态：

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

## 串行控制台不工作

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

1. **验证 Kconfig：**

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

2. **验证内核命令行：**

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

3. **获取早期启动消息：** 在内核命令行中添加 `earlycon`。这样可以在 UART 驱动完全初始化之前启用输出。

4. **检查线缆和波特率：** 确认设备和主机终端均为 115200 波特、8N1、无硬件流控。

## Remoteproc 故障

### 固件加载失败

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

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

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

### 子系统崩溃时捕获日志

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

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

崩溃日志示例：

```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
```

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

```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
```

将 `.elf` 文件传输到主机，并使用 Qualcomm Crash Analysis Portal（QCAP）进行分析。有关更多详情，请参阅[配置远程处理器子系统](./configure-the-remoteprocessor-remoteproc-subsystems)。