From 1f7495e31cfd406c787608e0c153d4e8821fe7f5 Mon Sep 17 00:00:00 2001 From: jack Date: Mon, 6 Apr 2026 12:22:23 +0800 Subject: [PATCH] =?UTF-8?q?docs(hdmi):=20WirePlumber=20=E5=9B=BA=E5=8C=96?= =?UTF-8?q?=20Kaisa=20HDMI=20=E8=BE=93=E5=87=BA=E4=B8=8E=E9=BB=98=E8=AE=A4?= =?UTF-8?q?=20sink=20=E4=BC=98=E5=85=88=E7=BA=A7?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 新增仓库内 WirePlumber 片段示例（pro-audio + pro-output 优先级）与 OPERATION_PipeWire_Kaisa_HDMI.md；CHROMEOS515 文档增加 §4.3 链至桌面会话 排障；next.md 补充 PipeWire 链路与内核验证流程更新。 Made-with: Cursor --- ..._UBUNTU617_HDMI_IMPLEMENTATION_AND_GAPS.md | 163 ++++++++++++++++++ .../OPERATION_PipeWire_Kaisa_HDMI.md | 88 ++++++++++ .../wireplumber/50-kaisa-sof-rt5682-hdmi.conf | 64 +++++++ next.md | 162 +++++++++++++++-- 4 files changed, 458 insertions(+), 19 deletions(-) create mode 100644 docs/linux-hdmi/CHROMEOS515_UBUNTU617_HDMI_IMPLEMENTATION_AND_GAPS.md create mode 100644 docs/linux-hdmi/OPERATION_PipeWire_Kaisa_HDMI.md create mode 100644 docs/linux-hdmi/wireplumber/50-kaisa-sof-rt5682-hdmi.conf diff --git a/docs/linux-hdmi/CHROMEOS515_UBUNTU617_HDMI_IMPLEMENTATION_AND_GAPS.md b/docs/linux-hdmi/CHROMEOS515_UBUNTU617_HDMI_IMPLEMENTATION_AND_GAPS.md new file mode 100644 index 0000000000..15f29697de --- /dev/null +++ b/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 深读」时落稿。* diff --git a/docs/linux-hdmi/OPERATION_PipeWire_Kaisa_HDMI.md b/docs/linux-hdmi/OPERATION_PipeWire_Kaisa_HDMI.md new file mode 100644 index 0000000000..4e15203a7b --- /dev/null +++ b/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) diff --git a/docs/linux-hdmi/wireplumber/50-kaisa-sof-rt5682-hdmi.conf b/docs/linux-hdmi/wireplumber/50-kaisa-sof-rt5682-hdmi.conf new file mode 100644 index 0000000000..e7b963cedc --- /dev/null +++ b/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 + } + } + } +] diff --git a/next.md b/next.md index 357d856c09..f1a8352a20 100644 --- a/next.md +++ b/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 \ - linux-image-unsigned-6.17.0-20-generic_6.17.0-20.20~24.04.1_amd64.deb \ - linux-modules-6.17.0-20-generic_6.17.0-20.20~24.04.1_amd64.deb \ - 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 +export REPO_ROOT="$HOME/文档/chromebox_10th_audio_driver" +export SRC="$REPO_ROOT/kernel-src/linux-hwe-6.17-6.17.0" +cd "$REPO_ROOT" ``` -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)。 -4. IPC / `STREAM_PCM_PARAMS`：[OPERATION_Kaisa_SOF_HDMI_Trace.md](docs/linux-hdmi/OPERATION_Kaisa_SOF_HDMI_Trace.md)。 +推荐在仓库根目录执行： + +```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** 后，可**清空或覆盖**本文件。 +验证结果摘要写入 **WORK_PROGRESS** 后，可清空或覆盖本文件。