# next.md

> 仓库根目录默认 **`~/文档/chromebox_10th_audio_driver`**；路径不同只改 `REPO_ROOT`。  
> 结论请同步 [WORK_PROGRESS](docs/meta/WORK_PROGRESS.md)；文档入口见 [DOCUMENTATION_ARCHITECTURE](docs/meta/DOCUMENTATION_ARCHITECTURE.md)。

本文对应流程：**验证 SOF dmesg 诊断补丁 →（按需 apply）→ deps + 编译 HWE 6.17 →（可选）安装与真机验证**。补丁文件：[`patches/ubuntu-hwe-6.17/SOF-hw_params_trace-full-chain-dmesg.patch`](patches/ubuntu-hwe-6.17/SOF-hw_params_trace-full-chain-dmesg.patch)。细节见 [patches/ubuntu-hwe-6.17/README.md](patches/ubuntu-hwe-6.17/README.md)。

---

## 前置条件

- 源码树：[`kernel-src/linux-hwe-6.17-6.17.0/`](kernel-src/linux-hwe-6.17-6.17.0/) 存在且含 **`debian/rules`**，与目标 `uname -r` 前缀一致（见 [kernel-src/README.md](kernel-src/README.md)）。
- 环境：Ubuntu（或已配置 `build-dep linux-hwe-6.17`）；编译耗时长、磁盘占用大（常见需 **≥35～50GB** 余量）。

---

## 0）环境变量（可选）

```bash
export REPO_ROOT="$HOME/文档/chromebox_10th_audio_driver"
export SRC="$REPO_ROOT/kernel-src/linux-hwe-6.17-6.17.0"
cd "$REPO_ROOT"
```

---

## 1）验证补丁（dry-run）

推荐在仓库根目录执行：

```bash
./scripts/verify-ubuntu-hwe-sof-dmesg-trace-patch.sh
```

- 默认 `SRC=$REPO_ROOT/kernel-src/linux-hwe-6.17-6.17.0`，`PATCH` 指向上述 `SOF-hw_params_trace-full-chain-dmesg.patch`。
- **成功**：输出 **`patch --dry-run 通过`** 或 **`当前源码树已包含该补丁内容`**（后者表示**无需再 apply**）。

手工等价：

```bash
cd "$SRC"
patch -p1 --dry-run --batch < "$REPO_ROOT/patches/ubuntu-hwe-6.17/SOF-hw_params_trace-full-chain-dmesg.patch"
```

若 dry-run **失败**（上下文不匹配），先对齐 `apt source` 版本与补丁目标，**勿** `patch --force`。

---

## 2）应用补丁（仅当尚未包含）

仅当第 1 步 dry-run **通过**且**不是**「已包含」时执行一次：

```bash
export PATCH="$PWD/patches/ubuntu-hwe-6.17/SOF-hw_params_trace-full-chain-dmesg.patch"
./scripts/ubuntu-hwe-617-build.sh apply
```

若脚本已提示「已包含」，**跳过本步**。

---

## 3）依赖与编译

使用 [`scripts/ubuntu-hwe-617-build.sh`](scripts/ubuntu-hwe-617-build.sh)：

| 步骤 | 命令 | 说明 |
|------|------|------|
| 依赖（通常一次） | `./scripts/ubuntu-hwe-617-build.sh deps` | 需 `sudo`（如 `build-dep linux-hwe-6.17`） |
| 构建 | `./scripts/ubuntu-hwe-617-build.sh build` | `fakeroot debian/rules clean && binary-generic`；**deb 产出在 `SRC` 的父目录**（`kernel-src/`） |

并行度可用 **`CONCURRENCY_LEVEL`**（或脚本内 `JOBS`）控制。

```bash
export CONCURRENCY_LEVEL="$(nproc)"
./scripts/ubuntu-hwe-617-build.sh deps
./scripts/ubuntu-hwe-617-build.sh build
```

树不干净时可在 **`$SRC`** 下按需 `make mrproper` 后再 `build`（见 kernel-src README）。

---

## 4）安装（可选，真机测 `hw_params_trace`）

**unsigned** 镜像 + modules 等，可用脚本（与手动 `dpkg -i` 等价思路）：

```bash
./scripts/ubuntu-hwe-617-build.sh install
sudo reboot
```

装前可在 `kernel-src/` 下 **`ls -la *.deb`** 核对版本。若本机已装**同 ABI 的官方 signed** 与 **unsigned** 冲突，按 [OPERATION_Install_CustomKernel_Ubuntu_HWE617.md §2.1](docs/kernel-build/OPERATION_Install_CustomKernel_Ubuntu_HWE617.md) 处理后再装。

### `apt purge` 镜像包时出现：`rmdir: 删除 '/lib/modules/6.17.0-20-generic' 失败: 目录非空`

在只执行例如：

```text
sudo apt purge linux-image-6.17.0-20-generic
# 或
sudo apt purge linux-image-unsigned-6.17.0-20-generic
```

的**清除配置文件**阶段，可能打印上述 **`rmdir` 失败**（与你终端里一致）。

- **原因**：`/lib/modules/6.17.0-20-generic/` 里仍有 **`linux-modules-6.17.0-20-generic`**（以及 `linux-modules-extra-*`、`linux-modules-iwlwifi-*` 等**同 ABI**）安装的文件；镜像包维护脚本试图删掉「本应随镜像一起空掉的」目录时，目录**非空**就会报错。
- **通常怎么处理**：多数情况下这是**非致命**提示，**不代表** purge 命令整体失败；也**不代表**该 ABI 的模块已从系统卸光。若要从磁盘**整套拆掉** `6.17.0-20`，需按 [OPERATION 文档](docs/kernel-build/OPERATION_Install_CustomKernel_Ubuntu_HWE617.md) 核对并卸/换 **`linux-modules-*`** 等同 ABI 包；若接下来要**重装自编 unsigned**，按文档装回 image + modules 即可。
- **自查**：`dpkg -l | grep 6.17.0-20` 看还有哪些包仍为 **`ii`**。

---

## 5）重启后：启用 trace 与 dmesg

进入自编内核且 **`snd_sof` 已加载**（SOF 机器）后：

```bash
echo 1 | sudo tee /sys/module/snd_sof/parameters/hw_params_trace
# 播放 HDMI 音频后：
sudo dmesg | grep SOF_TRACE
```

**说明**：只跑官方签名内核**验不出**上述补丁；需装 **unsigned** 自编包并重启后再测。

---

## 6）真机运行时预检（可选）

已加载 `snd_sof` 时，可用：

```bash
./scripts/verify-ubuntu-hwe617-patches-runtime.sh
```

跳过 HDMI `speaker-test`、仅 dry-run + 模块检查：

```bash
RUN_HDMI_TEST=0 ./scripts/verify-ubuntu-hwe617-patches-runtime.sh
```

指定 HDMI 设备（需把变量传给 root）：

```bash
sudo env HDMI_PLUGHW=plughw:0,3 ./scripts/verify-ubuntu-hwe617-patches-runtime.sh
```

说明见 [patches/ubuntu-hwe-6.17/VERIFY_PATCHES.md](patches/ubuntu-hwe-6.17/VERIFY_PATCHES.md)。

---

## 若仍无声或需排障上下文

见 [CHROMEOS515_UBUNTU617_HDMI_IMPLEMENTATION_AND_GAPS.md](docs/linux-hdmi/CHROMEOS515_UBUNTU617_HDMI_IMPLEMENTATION_AND_GAPS.md) 相关章节。

**桌面 PipeWire（Kaisa）**：若仅 **`stereo-fallback`**、无法选 HDMI 或需热插拔默认输出，见 [OPERATION_PipeWire_Kaisa_HDMI.md](docs/linux-hdmi/OPERATION_PipeWire_Kaisa_HDMI.md) 与仓库内 [`docs/linux-hdmi/wireplumber/50-kaisa-sof-rt5682-hdmi.conf`](docs/linux-hdmi/wireplumber/50-kaisa-sof-rt5682-hdmi.conf)。

---

## 用完

验证结果摘要写入 **WORK_PROGRESS** 后，可清空或覆盖本文件。