docs(hdmi): WirePlumber 固化 Kaisa HDMI 输出与默认 sink 优先级

新增仓库内 WirePlumber 片段示例（pro-audio + pro-output 优先级）与
OPERATION_PipeWire_Kaisa_HDMI.md；CHROMEOS515 文档增加 §4.3 链至桌面会话
排障；next.md 补充 PipeWire 链路与内核验证流程更新。

Made-with: Cursor

docs/linux-hdmi/CHROMEOS515_UBUNTU617_HDMI_IMPLEMENTATION_AND_GAPS.md

@@ -0,0 +1,163 @@
+# ChromiumOS 5.15 vs Ubuntu HWE 6.17：HDMI 音频实现方法与 Linux 空缺
+
+**体例**：[../meta/DOCUMENTATION_STYLE.md](../meta/DOCUMENTATION_STYLE.md)。  
+**本文目的**：不是罗列两棵树「所有 diff」，而是先说明 **ChromiumOS 内核里 HDMI（iDisp）音频的实现层次与合理不变量**，再对照 **Linux（HWE 6.17）** 在每一层是 **一致、仅重命名、还是存在可能语义空缺**，并标明**与补丁/固件的边界**，减少「长时间编译补丁却无效」的盲试。
+
+**必读交叉引用**：
+
+- 板级与 `set_idisp_hdmi_link`：[CHROMEOS_KAISA_AUDIO_KERNEL_PATHS.md](CHROMEOS_KAISA_AUDIO_KERNEL_PATHS.md)、[SOURCE_DIFF_CHROMEOS515_UBUNTU617.md](SOURCE_DIFF_CHROMEOS515_UBUNTU617.md)、[Machine/iDisp 精读笔记（Rex、`late_probe`）](CHROMEOS515_MACHINE_IDISP_READING_20260405.md)
+- `STREAM_PCM_PARAMS` 三文件链与真机载荷：[STREAM_PCM_PARAMS_CHROME_UBUNTU_NOTES.md](../../patches/ubuntu-hwe-6.17/STREAM_PCM_PARAMS_CHROME_UBUNTU_NOTES.md)
+- 修复阶段与何时转上游：[FIX_PLAN_HDMI_FROM_SOURCE_ANALYSIS.md](FIX_PLAN_HDMI_FROM_SOURCE_ANALYSIS.md)
+
+**树路径**：Chrome → `chromiumos_kernel/v5.15/`；Ubuntu → `kernel-src/linux-hwe-6.17-6.17.0/`。
+
+---
+
+## 1. 为什么不搞「全量区别提取」
+
+| 做法 | 问题 |
+|------|------|
+| 按目录 `diff -rq` / 逐文件堆行数 | 噪声大，**无法回答**「Chrome 怎么实现 HDMI」 |
+| 见 diff 就移植 | `hda-dai.c` 等为**架构级重写**，整文件 backport 不可行（见 SOURCE_DIFF §5） |
+| 只改 `ipc3-pcm` 载荷 | 真机载荷已**结构合理**（STREAM 笔记 §5），继续盲改 **u32** 期望低 |
+
+**本文方法**：**分层 + 不变量** → 每层对照 Linux → **空缺表**带证据强度。
+
+---
+
+## 2. ChromiumOS 5.15：HDMI 音频实现层次（内核侧）
+
+用户态（CRAS）不在本文；内核从 **machine 绑定 iDisp** 到 **固件收到 IPC** 可粗分为下表。
+
+| 层次 | 角色（通俗） | Chrome 树内主要落点 |
+|------|----------------|---------------------|
+| **A. Machine / board** | 为每条 HDMI 建 **BE DAI link**（`iDispN Pin` ↔ `ehdaudio0D2` / `intel-hdmi-hifiN`），并挂 **DPCM 回放** | `sound/soc/intel/boards/sof_board_helpers.c`：`set_idisp_hdmi_link()`、`sof_intel_board_set_dai_link()`；`sof_rt5682.c`：`ctx->hdmi_num`、IDISP codec 标志 |
+| **B. ASoC / DPCM** | 前端 FE 打开后，经 **DPCM** 把参数传到 BE；**hw_params / trigger** 顺序影响链路是否就绪 | `sound/soc/sof/pcm.c` 等与 **DPCM、子流** 相关逻辑（与具体板拓扑绑定） |
+| **C. HDA / 平台 PCM** | 为 HDAC 流准备 **buffer、period**，并写 **`format_val`**（Chrome **始终**在 `hda_dsp_pcm_hw_params` 里写） | `sound/soc/sof/intel/hda-pcm.c`：`hda_dsp_pcm_hw_params()` |
+| **D. HDA DAI / Link DMA** | 在 **link** 上设置 **stream_tag / stream_id**，建立 **Link DMA** | `sound/soc/sof/intel/hda-dai.c`：`hda_link_dma_hw_params()` → `snd_hdac_ext_bus_link_set_stream_id()`（Chrome 5.15 路径与 6.17 **函数形态不同**，见下节） |
+| **E. IPC3** | 组装 **`SOF_IPC_STREAM_PCM_PARAMS`**，**等待固件回复** | `sound/soc/sof/ipc3-pcm.c`：`sof_ipc3_pcm_hw_params()` → `sof_ipc_tx_message(..., &reply, ...)` |
+| **F. 固件 / tplg** | 解析 PARAMS，若拒绝则 **-EIO**（主机侧常看到 `ipc tx error`） | 不在内核源码树内；与 **拓扑、管道、固件版本** 绑定 |
+
+### 2.1 调用链示意图（逻辑顺序）
+
+```mermaid
+flowchart TB
+  subgraph machine [Machine]
+    IDISP[set_idisp_hdmi_link BE links]
+  end
+  subgraph dpcm [DPCM]
+    FE[FE hw_params]
+    BE[BE hda_dsp_pcm_hw_params]
+  end
+  subgraph hda [HDA platform]
+    FV[format_val buffer period]
+    LINK[hda_link_dma_hw_params set_stream_id]
+  end
+  subgraph ipc [IPC3]
+    PARAMS[sof_ipc3_pcm_hw_params STREAM_PCM_PARAMS]
+  end
+  subgraph fw [Firmware]
+    DSP[SOF firmware tplg]
+  end
+  IDISP --> FE
+  FE --> BE
+  BE --> FV
+  FV --> LINK
+  LINK --> PARAMS
+  PARAMS --> DSP
+```
+
+### 2.2 Chrome 侧可陈述的「不变量」（用于对照 Linux）
+
+1. **板级**：每条 HDMI 有 **`iDispN` + `intel-hdmi-hifiN`** 的 BE link，`dpcm_playback` 语义与上游 **`playback_only`** 对应（见 SOURCE_DIFF §2.1）。
+2. **HDA PCM**：**`hstream->format_val`** 在 **`hda_dsp_pcm_hw_params`** 内**无条件**按 rate/bits/ch 计算（Chrome 5.15 源码，无 `dspless` 分支）。
+3. **IPC**：**`STREAM_PCM_PARAMS`** 通过 **`sof_ipc_tx_message` 带 reply** 发送；载荷字段与 6.17 **语义一致**（STREAM 笔记 §1）。
+4. **Chrome 5.15 SOF 树**：**无** `dspless_mode_selected` 字符串（`rg dspless sound/soc/sof` 为空）—— **DSPless 相关分支为 6.x 演进引入**，不是 Chrome 与 Linux「同一套代码少几行」的关系。
+
+---
+
+## 3. Ubuntu HWE 6.17：同层次对照与「空缺 / 偏离」
+
+| 层次 | Linux 6.17 行为摘要 | 与 Chrome 关系 | 空缺 / 偏离含义 |
+|------|---------------------|----------------|-----------------|
+| **A. Machine** | `playback_only`、`sof_intel_board_get_ctx()`、默认 `hdmi_num` 等 | **逻辑同构**，API 迁移 | **无**「Chrome 有而 Linux 完全没建 iDisp link」的典型空缺；细节见 SOURCE_DIFF §2–3 |
+| **B. DPCM** | `pcm.c` 体量大、含 IPC4/多路径 | 与 5.15 **有 diff** | **不**默认等于 HDMI bug；需 **trace 证明顺序问题** 再动刀 |
+| **C. hda-pcm** | **`format_val`** 仅在 **`!dspless_mode_selected`** 时写入 | **偏离**：Chrome **始终**写 | **可能空缺**：DSPless 路径下 **`format_val` 未按 5.15 写** → 需 **自编实验** 与 **`hw_params_trace`** 对照（见 STREAM 笔记第 6.2、6.4 节） |
+| **D. hda-dai** | **widget / `hda_dai_widget_dma_ops`**、**`get_hlink`** 等 | **架构重写** | **不是**「diff 里少几行」；**不宜整文件移植**；仅 **点状**对照 `hda_link_dma_hw_params` 等（STREAM §6.1） |
+| **E. ipc3-pcm** | **`STREAM_PCM_PARAMS` 载荷构造与 5.15 一致**；上游 FREE/trigger 与 Chrome 差异可单独对照 | **载荷无已知语义空缺**（STREAM §1、§5） | **继续改载荷 blind 期望低**；**-EIO 更可能固件**（STREAM §5、§6.4） |
+| **F. 固件** | 同 tplg/固件版本 | Chrome 正常 / Linux 失败 | **主机侧载荷已自洽时**，优先 **上游复现**（[UPSTREAM_SOF_Kaisa_HDMI_REPRO.md](UPSTREAM_SOF_Kaisa_HDMI_REPRO.md)） |
+
+### 3.1 证据强度说明
+
+- **高**：STREAM 笔记 **§5 真机 hex 解码**、**§6.1 ftrace** 样例。
+- **中**：**hda-pcm** 分支差异（源码对照 Chrome 5.15 vs 6.17）。
+- **低（待证）**：DPCM 顺序、非 iDisp 共用路径上的回归。
+
+---
+
+## 4. 与「几小时编译补丁仍无效」的关系
+
+1. **若补丁只动 `ipc3-pcm` 里 PARAMS 的字段**：在 **§5 已说明载荷合理** 的前提下，**失败不意外**——问题可能已在 **固件**。
+2. **FREE/trigger 与 Chrome 对齐** 类改动：改善 **IPC 事务完整性**，**不**改变 PARAMS 构造；**不**保证 HDMI 有声（需单独评估是否值得维护）。
+3. **`format_val` / DSPless** 类实验：针对 **§3 表 C 层偏离**；若仍 **STREAM_PCM_PARAMS -EIO**，应 **停止盲堆内核补丁**；固件/上游可能性见 [STREAM_PCM_PARAMS_CHROME_UBUNTU_NOTES.md](../../patches/ubuntu-hwe-6.17/STREAM_PCM_PARAMS_CHROME_UBUNTU_NOTES.md) **§6.4**。
+4. **hda-dai 点状修改**：仅当 **trace/日志** 指向具体函数（STREAM §6.1），**不做**无依据大块移植。
+
+### 4.1 决策：仓库里放什么补丁？
+
+**`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)**：全链路 **`dmesg`**（**`hw_params_trace`**），**不改**行为，用于**先定位再写**有针对性的修复。
+
+**新行为补丁**只在 **ftrace / `SOF_TRACE` / 双树** 指向**具体根因**时值得写（与 [FIX_PLAN_HDMI_FROM_SOURCE_ANALYSIS.md](FIX_PLAN_HDMI_FROM_SOURCE_ANALYSIS.md) **阶段 C** 一致），**不**再盲改 **`ipc3-pcm` 载荷内 u32**。**载荷已自洽仍失败**时，固件侧仍可能为主因——见 **§4.2**。
+
+### 4.2 验证优先；老设备与「转上游」的预期
+
+- **没有可复现证据**（清晰 dmesg、前后对比、最小命令）时，**对外发帖/转上游**很难得到实质回复；文档里的 **UPSTREAM 清单**更适合在**你自己已验证过现象**之后，作为**归档与偶发投递**，而不是「没包就指望社区 debug」。
+- **老机型、社区不热**时更应现实：**主线策略**仍是 **本机 trace → 单函数级补丁 A/B → 记入 WORK_PROGRESS**；对「几天内有人接盘」**降低预期**。
+- **单函数级补丁**与上文不矛盾：恰恰是 **先有验证（trace 指向某函数）**，再动刀；**不是**无验证堆补丁。
+
+### 4.3 桌面会话：PipeWire / HDMI 固化（非内核）
+
+内核 **`STREAM_PCM_PARAMS` 已 ok** 仍可能因 **PipeWire profile（`stereo-fallback`）** 无法单独选 HDMI，或需在热插拔时切换默认输出。Kaisa + **`sof-rt5682`** 上的 **WirePlumber 0.5+** 固化步骤见专门操作文：[OPERATION_PipeWire_Kaisa_HDMI.md](OPERATION_PipeWire_Kaisa_HDMI.md)（含 [`wireplumber/50-kaisa-sof-rt5682-hdmi.conf`](wireplumber/50-kaisa-sof-rt5682-hdmi.conf)）。
+
+---
+
+## 5. 深化阅读时建议打开的源码（非「全量 diff」）
+
+| 优先级 | 文件 | 读什么 |
+|--------|------|--------|
+| 1 | `sound/soc/sof/ipc3-pcm.c` | `sof_ipc3_pcm_hw_params`、FREE/trigger（与 Chrome 5.15 对照） |
+| 2 | `sound/soc/sof/intel/hda-pcm.c` | `hda_dsp_pcm_hw_params` 与 **`dspless`**（与 Chrome 5.15 对照） |
+| 3 | `sound/soc/sof/intel/hda-dai.c` | **`hda_link_dma_hw_params`**、`snd_hdac_ext_bus_link_set_stream_id`（与 §6.1） |
+| 4 | `sound/soc/sof/ipc3.c` | 流消息 **log/解析**（与 `ipc tx error` 打印）；**非**载荷填充主路径 |
+| 5 | `sound/soc/sof/intel/hda-dsp.c` | **仅 6.17**：`dspless_mode_selected` 多处分支（Chrome 无对等符号） |
+| 6 | `sound/soc/sof/pcm.c` | **仅当**怀疑 DPCM 顺序时深入 |
+
+**重新生成 unified diff（辅助附录）**：
+
+```bash
+./scripts/export-chromeos-ubuntu-sound-file-diffs.sh
+# 输出：patches/ubuntu-hwe-6.17/reference/（可能 .gitignore）
+```
+
+脚本 [export-chromeos-ubuntu-sound-file-diffs.sh](../../scripts/export-chromeos-ubuntu-sound-file-diffs.sh) 的 `FILES` 已包含 **`hda-ipc.c`、`hda-dsp.c`、`hda-pcm.c`**（与 `ipc3*` / `pcm.c` / `hda-dai.c` 一并输出到 `patches/ubuntu-hwe-6.17/reference/`）。体量约：**hda-ipc ~300 行、hda-dsp ~1100 行、hda-pcm ~200 行** unified diff（随双树版本浮动），**仅作附录核对**，正文仍以**函数级阅读**为准。
+
+---
+
+## 6. 小结
+
+| 问题 | 结论 |
+|------|------|
+| Chrome 的 HDMI 内核实现怎么理解？ | **Machine iDisp → DPCM → hda-pcm（Chrome 始终 format_val）→ hda-dai link DMA → ipc3-pcm PARAMS → 固件** |
+| Linux 最大「可讨论空缺」在哪？ | **DSPless / `format_val` 分支（6.17 有、Chrome 5.15 SOF 无 dspless）**；**hda-dai 架构差异**（点状对照） |
+| 载荷已合理仍 -EIO？ | **主机侧**可试空间收窄后，**固件**常为剩余解释；**对外发帖**须先有复现包（见 STREAM §6.4），**老设备勿指望社区热度**（**§4.2**） |
+
+---
+
+## 7. 文档关系
+
+| 文档 | 角色 |
+|------|------|
+| [SOURCE_DIFF_CHROMEOS515_UBUNTU617.md](SOURCE_DIFF_CHROMEOS515_UBUNTU617.md) | 文件级 diff 体量与板级/ipc3-pcm 摘要 |
+| [STREAM_PCM_PARAMS_CHROME_UBUNTU_NOTES.md](../../patches/ubuntu-hwe-6.17/STREAM_PCM_PARAMS_CHROME_UBUNTU_NOTES.md) | PARAMS 链路与 §6 工程优先级 |
+| 本文 | **实现方法 + Linux 空缺**（方法论），**不**替代上述技术细节表 |
+
+*修订：执行 BMad 计划「ChromeOS vs Linux HDMI 深读」时落稿。*

docs/linux-hdmi/OPERATION_PipeWire_Kaisa_HDMI.md

@@ -0,0 +1,88 @@
+# 操作：Kaisa（sof-rt5682）Ubuntu 上 HDMI 出声与 WirePlumber 固化
+
+**体例**：[../meta/DOCUMENTATION_STYLE.md](../meta/DOCUMENTATION_STYLE.md)。
+
+**适用**：Google **Kaisa**（如 `Google-Kaisa-rev4`）、PipeWire + WirePlumber 0.5+（Ubuntu 24.04 常见）、声卡为 **`alsa_card.pci-0000_00_1f.3-platform-cml_rt5682_def`**（若 PCI 路径不同需改配置）。
+
+**相关**：内核侧 HDMI / SOF 层次见 [CHROMEOS515_UBUNTU617_HDMI_IMPLEMENTATION_AND_GAPS.md](CHROMEOS515_UBUNTU617_HDMI_IMPLEMENTATION_AND_GAPS.md)。
+
+---
+
+## 1. 现象与原因（摘要）
+
+| 现象 | 说明 |
+|------|------|
+| 设置里只有 **「立体声」**、**`pactl list short sinks` 仅 1 个** | 声卡 profile 为 **`stereo-fallback`**，未暴露多路 HDMI PCM。 |
+| GNOME **「测试扬声器」** 无图标 | HDMI / Pro Audio 常无 Front L/R 声道名，**界面不可用**不代表 ALSA 无声；用 **`speaker-test` / `paplay`** 测。 |
+| **`HDMI/DP,pcm=3/4 Jack` = off** | 该路 **未检测到显示器**，勿用 **`plughw:0,3`** / **`0,4`** 指望有声；对齐 **Jack=on** 的 pcm 与物理口。 |
+| **`IEC958',N` 与 `amixer sget 'IEC958 Playback Switch'`** | 本机简单控件名为 **`IEC958',0`** 等；用 **`scontrols \| grep IEC958`** 核对。 |
+
+---
+
+## 2. 固化方案：WirePlumber `wireplumber.conf.d`
+
+在 **`~/.config/wireplumber/wireplumber.conf.d/`** 下放片段（**文件名以 `.conf` 结尾**），实现：
+
+1. **强制 `device.profile = pro-audio`**：始终暴露 **Pro / Pro 2 / Pro 3 / Pro 4**（与 `aplay -l` 中 **Port1 / HDMI1/2/3** 对应）。
+2. **`monitor.alsa.rules` 提高 HDMI 相对模拟口的 `priority.session`**：HDMI sink **可用且优先级更高** 时，WirePlumber 倾向将其设为 **默认输出**；拔出后回退到模拟（以本机行为为准）。
+
+仓库内 **示例文件**（可复制到上述目录）：
+
+- [`wireplumber/50-kaisa-sof-rt5682-hdmi.conf`](wireplumber/50-kaisa-sof-rt5682-hdmi.conf)
+
+安装命令示例：
+
+```bash
+mkdir -p ~/.config/wireplumber/wireplumber.conf.d
+cp /path/to/chromebox_10th_audio_driver/docs/linux-hdmi/wireplumber/50-kaisa-sof-rt5682-hdmi.conf \
+   ~/.config/wireplumber/wireplumber.conf.d/
+systemctl --user restart wireplumber pipewire pipewire-pulse
+```
+
+**优先级（示例文件内）**：`pro-output-0`（模拟）**1000**；`pro-output-3` **1090**；`pro-output-4` **1095**；`pro-output-2`（HDMI1）**1100**。多路 HDMI 同时存在时 **HDMI1 优先**；若你常接 **HDMI2/3**，可把对应 `node.name` 的优先级调到 **高于 1100**。
+
+**PCI 路径变化**：若 `lspci` 中音频 BDF 不是 **`0000:00:1f.3`**，用以下命令查看实际 **`device.name` / `node.name`** 并替换 conf 中的字符串：
+
+```bash
+pactl list cards
+pactl list short sinks
+```
+
+**WirePlumber 大版本升级**：语法可能变化，见 [WirePlumber migration](https://pipewire.pages.freedesktop.org/wireplumber/daemon/configuration/migration.html)。
+
+---
+
+## 3. 验证
+
+```bash
+pactl list cards
+```
+
+**活动配置** 应为 **`pro-audio`**。
+
+```bash
+pactl get-default-sink
+pactl list short sinks
+```
+
+插入 HDMI（**Jack 对应的那路**，如 **pcm=2**）后，默认 sink 宜为 **`...pro-output-2`**（或你优先级最高的那路）。
+
+ALSA 直连测试（不经过 PipeWire 策略）：
+
+```bash
+speaker-test -D plughw:0,2 -c2 -t sine -f 440 -l 3
+```
+
+---
+
+## 4. 可选与兜底
+
+- **`api.acp.auto-port = true`**：可在 **同一条 `device` 匹配规则** 的 `update-props` 中尝试（与 **`pro-audio`** / UCM 可能交互）；**先备份 conf**，再 A/B。
+- **优先级仍不理想**：可用 **user systemd oneshot**（登录执行 `pactl set-card-profile … pro-audio` + `pactl set-default-sink …`）作次级方案。
+
+---
+
+## 5. 参考链接
+
+- [WirePlumber ALSA configuration](https://pipewire.pages.freedesktop.org/wireplumber/daemon/configuration/alsa.html)
+- [设备优先级示例（monitor.alsa.rules）](https://danielpower.ca/blog/wireplumber-device-priority)

docs/linux-hdmi/wireplumber/50-kaisa-sof-rt5682-hdmi.conf

@@ -0,0 +1,64 @@
+monitor.alsa.rules = [
+  {
+    matches = [
+      { "device.name" = "alsa_card.pci-0000_00_1f.3-platform-cml_rt5682_def" }
+    ]
+    actions = {
+      update-props = {
+        device.profile = "pro-audio"
+      }
+    }
+  }
+  {
+    matches = [
+      {
+        node.name = "alsa_output.pci-0000_00_1f.3-platform-cml_rt5682_def.pro-output-0"
+      }
+    ]
+    actions = {
+      update-props = {
+        priority.driver = 1000
+        priority.session = 1000
+      }
+    }
+  }
+  {
+    matches = [
+      {
+        node.name = "alsa_output.pci-0000_00_1f.3-platform-cml_rt5682_def.pro-output-2"
+      }
+    ]
+    actions = {
+      update-props = {
+        priority.driver = 1100
+        priority.session = 1100
+      }
+    }
+  }
+  {
+    matches = [
+      {
+        node.name = "alsa_output.pci-0000_00_1f.3-platform-cml_rt5682_def.pro-output-3"
+      }
+    ]
+    actions = {
+      update-props = {
+        priority.driver = 1090
+        priority.session = 1090
+      }
+    }
+  }
+  {
+    matches = [
+      {
+        node.name = "alsa_output.pci-0000_00_1f.3-platform-cml_rt5682_def.pro-output-4"
+      }
+    ]
+    actions = {
+      update-props = {
+        priority.driver = 1095
+        priority.session = 1095
+      }
+    }
+  }
+]

next.md

@@ -1,36 +1,160 @@
-# next.md（临时）
+# next.md
 
-> 只记**下一步**；有**重启**须写「重启后」。结论 → [WORK_PROGRESS](docs/meta/WORK_PROGRESS.md)；入口关系 → [DOCUMENTATION_ARCHITECTURE](docs/meta/DOCUMENTATION_ARCHITECTURE.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** 余量）。
 
-1. GRUB Advanced → 选 **非** `6.17.0-20` 内核进入。
+---
-2. `sudo apt remove linux-image-6.17.0-20-generic`（按提示处理 modules）。
+
-3. 按 [OPERATION_Install…](docs/kernel-build/OPERATION_Install_CustomKernel_Ubuntu_HWE617.md) §2.1 在 `kernel-src` 装 **仅 6.17.0-20** 的 deb（unsigned + modules + extra + iwlwifi，`6.17.0-20.20~24.04.1`）→ `apt-get install -f` → `update-grub`。
+## 0）环境变量（可选）
 
 ```bash
-cd "/home/jack/文档/chromebox_10th_audio_driver/kernel-src" && sudo dpkg -i \
+export REPO_ROOT="$HOME/文档/chromebox_10th_audio_driver"
-  linux-image-unsigned-6.17.0-20-generic_6.17.0-20.20~24.04.1_amd64.deb \
+export SRC="$REPO_ROOT/kernel-src/linux-hwe-6.17-6.17.0"
-  linux-modules-6.17.0-20-generic_6.17.0-20.20~24.04.1_amd64.deb \
+cd "$REPO_ROOT"
-  linux-modules-extra-6.17.0-20-generic_6.17.0-20.20~24.04.1_amd64.deb \
-  linux-modules-iwlwifi-6.17.0-20-generic_6.17.0-20.20~24.04.1_amd64.deb
 ```
 
-4. **再重启**。
+---
 
-### 重启后
+## 1）验证补丁（dry-run）
 
-1. `uname -r`；`dpkg -l | grep linux-image-unsigned-6.17.0-20` 为 **ii**（见安装文档）。
+推荐在仓库根目录执行：
-2. `sudo ./scripts/collect-storyc-dmesg.sh auto PATCHED`（或试 HDMI 后 `save PATCHED`）。
+
-3. 设备扫全见 [_bmad-output/stories-hdmi-kaisa-bp-2026-04-04.md](_bmad-output/stories-hdmi-kaisa-bp-2026-04-04.md)。
+```bash
-4. IPC / `STREAM_PCM_PARAMS`：[OPERATION_Kaisa_SOF_HDMI_Trace.md](docs/linux-hdmi/OPERATION_Kaisa_SOF_HDMI_Trace.md)。
+./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** 后，可**清空或覆盖**本文件。
+验证结果摘要写入 **WORK_PROGRESS** 后，可清空或覆盖本文件。