jack/chromebox_10th_audio_driver
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

更新源码

Browse Source
This commit is contained in:
jack
2026-04-04 18:13:40 +08:00
parent 2e20b8e2c5
commit beed35ec13
31 changed files with 1632 additions and 209 deletions
Download Patch File Download Diff File Expand all files Collapse all files

66
docs/INDEX.md Normal file
View File

@@ -0,0 +1,66 @@
# 文档索引
本仓库 **仅根目录 [README.md](../README.md) 为 README**；本文件为 `docs/` 下按主题分类的**详细索引**（非 README）。
**优先阅读（Linux HDMI 无声）**：[linux-hdmi/Linux_HDMI_Audio_Roadmap.md](linux-hdmi/Linux_HDMI_Audio_Roadmap.md)
---
## Linux HDMI（核心）
| 文档 | 说明 |
| ---- | ---- |
| [linux-hdmi/Linux_HDMI_Audio_Roadmap.md](linux-hdmi/Linux_HDMI_Audio_Roadmap.md) | **主路线图**：分阶段行动、已排除项、成功标准 |
| [linux-hdmi/REANALYSIS_Linux_HDMI_Audio_Kaisa.md](linux-hdmi/REANALYSIS_Linux_HDMI_Audio_Kaisa.md) | 现象、已排除方向、Mainline 5.15 误区、推荐路径 |
| [linux-hdmi/CHROMEOS_VS_UBUNTU_HDMI_NOTES.md](linux-hdmi/CHROMEOS_VS_UBUNTU_HDMI_NOTES.md) | ChromeOS 与 Ubuntu 6.17 的 iDisp/HDMI API 对照 |
| [linux-hdmi/UPSTREAM_SOF_Kaisa_HDMI_REPRO.md](linux-hdmi/UPSTREAM_SOF_Kaisa_HDMI_REPRO.md) | 提交 SOF/ALSA 上游所需材料与邮件模板 |
| [linux-hdmi/OPERATION_Kaisa_SOF_HDMI_Trace.md](linux-hdmi/OPERATION_Kaisa_SOF_HDMI_Trace.md) | 深度 trace：`sof_debug`、带 IPC 载荷的 dmesg |
| [meta/CHROMEOS_vs_UBUNTU617_SOUND_AUTODIFF.md](meta/CHROMEOS_vs_UBUNTU617_SOUND_AUTODIFF.md) | `sound/soc` 自动对照摘要（由脚本生成） |
## 内核构建、补丁与安装
| 文档 | 说明 |
| ---- | ---- |
| [kernel-src/README.md](../kernel-src/README.md) | 拉取 HWE 6.17 源码、`apt source`、与 `debian/rules` 注意 |
| [kernel-build/OPERATION_Install_CustomKernel_Ubuntu_HWE617.md](kernel-build/OPERATION_Install_CustomKernel_Ubuntu_HWE617.md) | 安装自编 deb、`linux-image-unsigned`、模块包、Secure Boot |
| [kernel-build/OPERATION_ChromeOS_Kernel_Deep_Diff.md](kernel-build/OPERATION_ChromeOS_Kernel_Deep_Diff.md) | ChromiumOS 5.15 树 unshallow、`git log`、导出关键文件 diff |
| [../patches/ubuntu-hwe-6.17/README.md](../patches/ubuntu-hwe-6.17/README.md) | 预置 0001 补丁、如何 `PATCH=...` 应用 |
| [../patches/ubuntu-hwe-6.17/DIFF_SUMMARY.txt](../patches/ubuntu-hwe-6.17/DIFF_SUMMARY.txt) | 补丁设计备忘与 smoke 对象文件 |
| [../patches/ubuntu-hwe-6.17/STREAM_PCM_PARAMS_CHROME_UBUNTU_NOTES.md](../patches/ubuntu-hwe-6.17/STREAM_PCM_PARAMS_CHROME_UBUNTU_NOTES.md) | `STREAM_PCM_PARAMS` 链路的 Chrome 与 6.17 对照 |
## 固件、拓扑与采集
| 文档 | 说明 |
| ---- | ---- |
| [linux-hdmi/SOF_FIRMWARE_TOPO_Kaisa_CHECKLIST.md](linux-hdmi/SOF_FIRMWARE_TOPO_Kaisa_CHECKLIST.md) | 固件与拓扑快照清单 |
| [../audio_topology/OPERATION_Force_Intel_Signed_Firmware.md](../audio_topology/OPERATION_Force_Intel_Signed_Firmware.md) | intel-signed 固件路径与回退 |
| [../audio_topology/COLLECT.md](../audio_topology/COLLECT.md) | 拓扑采集脚本用法（Linux / Windows / ChromeOS） |
| [../audio_topology/collected/README_TRACE_KAISA.md](../audio_topology/collected/README_TRACE_KAISA.md) | trace 采集输出说明 |
## 双系统、进度与总方案
| 文档 | 说明 |
| ---- | ---- |
| [meta/WORK_PROGRESS.md](meta/WORK_PROGRESS.md) | 换机交接、源码克隆、当前结论、**Linux HDMI 阶段**互链 |
| [meta/OPERATION_DualBoot_Ubuntu24_Windows.md](meta/OPERATION_DualBoot_Ubuntu24_Windows.md) | Ubuntu 24.04 与 Windows 双系统 |
| [../audio_topology/REPAIR_Plan_Audio.md](../audio_topology/REPAIR_Plan_Audio.md) | Linux / Windows 分平台修复思路与文档索引 |
| [../audio_topology/ANALYSIS_Audio.md](../audio_topology/ANALYSIS_Audio.md) | 三平台对比与技术分析 |
## Windows 专项
| 文档 | 说明 |
| ---- | ---- |
| [windows/OPERATION_Windows_Audio.md](windows/OPERATION_Windows_Audio.md) | CoolStar / ALC5682 全流程 |
| [windows/HARDWARE_ID_DRIVER_MAP_Windows.md](windows/HARDWARE_ID_DRIVER_MAP_Windows.md) | 硬件 ID 与驱动映射（若有） |
## 脚本（仓库根 `scripts/`）
| 脚本 | 说明 |
| ---- | ---- |
| [../scripts/ubuntu-hwe-617-build.sh](../scripts/ubuntu-hwe-617-build.sh) | `apply` / `deps` / `build` / `install` |
| [../scripts/verify-ubuntu-hwe617-0001-patch.sh](../scripts/verify-ubuntu-hwe617-0001-patch.sh) | 0001 补丁 dry-run |
| [../scripts/linux-hdmi-followup-workflow.sh](../scripts/linux-hdmi-followup-workflow.sh) | 深度 diff / 上游文档入口 |
| [../scripts/diff-chromeos-ubuntu-sound.sh](../scripts/diff-chromeos-ubuntu-sound.sh) | ChromeOS 与 6.17 `sound/soc` 统计 |
| [../scripts/preflight-chromeos-ubuntu-diff.sh](../scripts/preflight-chromeos-ubuntu-diff.sh) | 预检双树并运行上述 diff + export |
| [../scripts/export-chromeos-ubuntu-sound-file-diffs.sh](../scripts/export-chromeos-ubuntu-sound-file-diffs.sh) | 导出 ipc3/pcm/hda-dai unified diff |
| [../scripts/collect-kaisa-sof-trace.sh](../scripts/collect-kaisa-sof-trace.sh) | SOF trace 采集 |

3
docs/Linux_HDMI_Audio_Roadmap.md Normal file
View File

@@ -0,0 +1,3 @@
# 文档已迁移
Linux HDMI 路线图现位于：[linux-hdmi/Linux_HDMI_Audio_Roadmap.md](linux-hdmi/Linux_HDMI_Audio_Roadmap.md)。

116
docs/WORK_PROGRESS.md
View File

@@ -1,115 +1,3 @@
# 工作进度与源码获取说明（换机交接）
# 文档已迁移
面向机型：**Google Kaisa（Chromebox 10 代）**；核心问题：**Linux HDMI 无声（`STREAM_PCM_PARAMS` IPC 约 -5）**、**Windows 3.5mm 无声**；对照：**ChromeOS 上 HDMI / 3.5mm 正常**。
---
## 一、当前结论与状态
| 方向 | 状态 |
|------|------|
| 固件（intel-signed vs community） | 已实验：**单独换固件不能恢复 HDMI**；可能影响插拔检测，需按 OPERATION 文档回退 |
| 拓扑 | 与 ChromeOS **等效**（采集结论见 `audio_topology/ANALYSIS_Audio.md`） |
| Ubuntu HWE 6.17 补丁 | **0001** 在 `patches/ubuntu-hwe-6.17/`（FREE/trigger 路径；**不解决** `STREAM_PCM_PARAMS`）。**STREAM_PCM_PARAMS** 对照见 `patches/ubuntu-hwe-6.17/STREAM_PCM_PARAMS_CHROME_UBUNTU_NOTES.md`；真机 IPC 载荷观测见 **`docs/OPERATION_Kaisa_SOF_HDMI_Trace.md`**、`audio_topology/collected/README_TRACE_KAISA.md`。上游复现包清单见 **`docs/UPSTREAM_SOF_Kaisa_HDMI_REPRO.md`**。另见 `DIFF_SUMMARY.txt`、`docs/OPERATION_ChromeOS_Kernel_Deep_Diff.md`、`docs/REANALYSIS_Linux_HDMI_Audio_Kaisa.md` |
| Mainline 5.15（kernel.ubuntu.com，如 v5.15.201） | 真机：**HDMI 仍无声**；**3.5mm、WiFi 也异常**（相对 6.17）。**不等于** ChromeOS 5.15；**不建议**作修复主线，应 **GRUB 回 6.17** 并装全 HWE 模块包 | 见 `docs/REANALYSIS_Linux_HDMI_Audio_Kaisa.md` |
| 全量内核编译 `fakeroot debian/rules binary-generic` | **已在具备足够磁盘的环境完成**（`kernel-src/` 下产出 `linux-image-unsigned-*`、`linux-modules-*` 等 deb）；常见遇阻：**磁盘空间不足**（建议 **≥35～50GB**）；勿在同一源码树混用裸 `make` 与 `debian/rules`（需 `make ARCH=x86 mrproper` 清根目录后再打包） |
| Windows 侧 | 以 **CoolStar / Chrultrabook 成套驱动** 与设备管理器排错为主；见 `audio_topology/OPERATION_Windows_Audio.md` |
---
## 二、源码一：ChromiumOS / ChromeOS 内核（对照「HDMI 正常」）
**用途**：对照 **SOF / Intel boards / ACPI match** 等与 HDMI 相关的驱动差异（分支示例：`release-R144-16503.B-chromeos-5.15`）。
**官方仓库（HTTPS）**：
- `https://chromium.googlesource.com/chromiumos/third_party/kernel`
**克隆示例（浅克隆 + 指定分支）**：
```bash
mkdir -p /path/to/chromiumos_kernel && cd /path/to/chromiumos_kernel
git clone --depth 1 -b release-R144-16503.B-chromeos-5.15 \
https://chromium.googlesource.com/chromiumos/third_party/kernel.git v5.15
```
**可选：只检出音频相关目录（减小体积）**（在 `v5.15` 内执行）：
```bash
cd v5.15
git sparse-checkout init --cone
git sparse-checkout set sound/soc/intel sound/soc/sof include/sound
```
**本仓库内路径（若已存在）**：`chromiumos_kernel/v5.15/`（以你机器实际为准）。
---
## 三、源码二：Ubuntu HWE 6.17 内核（与当前运行内核一致）
**用途**：与 ChromeOS 5.15 做 diff / 打补丁 / 编译验证（与当前 Ubuntu 包版本一致）。
**注意**：二进制包名可能是 `linux-image-*`，但**源码包名**为 `linux-hwe-6.17`，**不是** `linux`（`apt source linux=6.17...` 会失败）。
**启用源码仓库**（Noble 示例）：
```bash
sudo sed -i 's/^Types: deb$/Types: deb deb-src/' /etc/apt/sources.list.d/ubuntu.sources
sudo apt update
```
**查本机内核对应的源码包与版本**：
```bash
dpkg -s "linux-image-$(uname -r)" | grep -E '^Source:|^Version:'
apt-cache showsrc linux-hwe-6.17 | grep -E '^Package:|^Version:' | head
```
**下载源码（把 `Version:` 换成 `apt-cache showsrc` 里与当前内核一致的那一行）**：
```bash
mkdir -p /path/to/chromebox_10th_audio_driver/kernel-src && cd /path/to/chromebox_10th_audio_driver/kernel-src
apt source linux-hwe-6.17=6.17.0-19.19~24.04.2
```
解压得到目录类似：`linux-hwe-6.17-6.17.0/`，以及 `.dsc` / `.orig.tar.gz` / `.diff.gz`（大文件已被 `.gitignore` 忽略，不提交仓库；见 `kernel-src/README.md`）。
**编译 generic 包（需足够磁盘与依赖）**：
```bash
sudo apt build-dep linux-hwe-6.17
cd /path/to/chromebox_10th_audio_driver/kernel-src/linux-hwe-6.17-6.17.0
export CONCURRENCY_LEVEL="$(nproc)"
fakeroot debian/rules clean
fakeroot debian/rules binary-generic
```
**仓库内辅助脚本**：`scripts/ubuntu-hwe-617-build.sh`、`scripts/ubuntu-hwe-617-deps-packages.txt`；**README** 中有入口。
---
## 四、换机后建议最短路径
1. 克隆本仓库 `chromebox_10th_audio_driver`。
2. 按需在本仓库 **`kernel-src/`** 下重新拉取 **Ubuntu 源码**（用新机器上的 `uname -r` / `dpkg -s` / `apt-cache showsrc` 核对版本号；**24.04** 上可直接 `apt build-dep linux-hwe-6.17`）。
3. 按需重新克隆 **ChromiumOS kernel** 分支（或从旧机拷贝 `chromiumos_kernel/` 目录）。
4. 阅读：`audio_topology/REPAIR_Plan_Audio.md`、`audio_topology/ANALYSIS_Audio.md`。
---
## 五、文档索引
| 文档 | 说明 |
|------|------|
| `audio_topology/REPAIR_Plan_Audio.md` | Linux / Windows 修复总览 |
| `audio_topology/ANALYSIS_Audio.md` | 三平台对比与 dmesg 要点 |
| `audio_topology/OPERATION_Force_Intel_Signed_Firmware.md` | Linux SOF 固件与回退 |
| `audio_topology/OPERATION_Windows_Audio.md` | Windows CoolStar / ALC5682 |
| `README.md` | 任务列表与参考链接 |
| `docs/OPERATION_Kaisa_SOF_HDMI_Trace.md` | Kaisa：`dynamic_debug` + `sof_debug=0x800`、采集 dmesg |
| `docs/SOF_FIRMWARE_TOPO_Kaisa_CHECKLIST.md` | 固件/tplg 与基线核对 |
| `docs/UPSTREAM_SOF_Kaisa_HDMI_REPRO.md` | 上游 issue/邮件复现包与模板 |
---
*本文档随工作机迁移更新；不修改 `.cursor/plans/` 下的计划文件。*
换机交接与进度说明现位于：[meta/WORK_PROGRESS.md](meta/WORK_PROGRESS.md)。

4
docs/OPERATION_ChromeOS_Kernel_Deep_Diff.md → docs/kernel-build/OPERATION_ChromeOS_Kernel_Deep_Diff.md
View File

@@ -2,7 +2,7 @@
面向：在仓库 [`chromiumos_kernel/v5.15/`](../chromiumos_kernel/v5.15) 对照 **ChromeOS** 与 **`kernel-src/linux-hwe-6.17-6.17.0/`**（Noble 源码树），为 **Kaisa HDMI / `STREAM_PCM_PARAMS`** 相关的新内核补丁做设计输入。
克隆说明与分支名见 [`docs/WORK_PROGRESS.md`](WORK_PROGRESS.md) 第二节。
克隆说明与分支名见 [`../meta/WORK_PROGRESS.md`](../meta/WORK_PROGRESS.md) 第二节。
---
@@ -107,6 +107,6 @@ OUT=/tmp/kaisa-sound-diff \
## 6. 相关文档与脚本
- 差异规模统计：[`docs/CHROMEOS_vs_UBUNTU617_SOUND_AUTODIFF.md`](CHROMEOS_vs_UBUNTU617_SOUND_AUTODIFF.md)，[`scripts/diff-chromeos-ubuntu-sound.sh`](../scripts/diff-chromeos-ubuntu-sound.sh)
- 差异规模统计：[`../meta/CHROMEOS_vs_UBUNTU617_SOUND_AUTODIFF.md`](../meta/CHROMEOS_vs_UBUNTU617_SOUND_AUTODIFF.md)，[`scripts/diff-chromeos-ubuntu-sound.sh`](../scripts/diff-chromeos-ubuntu-sound.sh)
- 补丁目录说明：[`patches/ubuntu-hwe-6.17/README.md`](../patches/ubuntu-hwe-6.17/README.md)
- 摘要：[`patches/ubuntu-hwe-6.17/DIFF_SUMMARY.txt`](../patches/ubuntu-hwe-6.17/DIFF_SUMMARY.txt)

2
docs/OPERATION_Install_CustomKernel_Ubuntu_HWE617.md → docs/kernel-build/OPERATION_Install_CustomKernel_Ubuntu_HWE617.md
View File

@@ -379,7 +379,7 @@ uname -r
应显示 `6.17.0-19-generic`（或你实际安装的 flavor 名称）。
HDMI 音频验证可结合项目内 [CHROMEOS_VS_UBUNTU_HDMI_NOTES.md](CHROMEOS_VS_UBUNTU_HDMI_NOTES.md) 与 [WORK_PROGRESS.md](WORK_PROGRESS.md) 中的排错思路。
HDMI 音频验证可结合项目内 [CHROMEOS_VS_UBUNTU_HDMI_NOTES.md](../linux-hdmi/CHROMEOS_VS_UBUNTU_HDMI_NOTES.md) 与 [WORK_PROGRESS.md](../meta/WORK_PROGRESS.md) 中的排错思路。
---

8
docs/CHROMEOS_VS_UBUNTU_HDMI_NOTES.md → docs/linux-hdmi/CHROMEOS_VS_UBUNTU_HDMI_NOTES.md
View File

@@ -22,7 +22,7 @@
### Ubuntu HWE 6.17（上游已改名）
- 使用 **`link->playback_only = 1;`**（对应 `include/sound/soc.h` 中的 DPCM 语义）。
- **勿**在 6.17 上把 `playback_only` 改回 `dpcm_playback`（字段已移除，无法编译）。历史说明见 [`DIFF_SUMMARY.txt`](../patches/ubuntu-hwe-6.17/DIFF_SUMMARY.txt)。
- **勿**在 6.17 上把 `playback_only` 改回 `dpcm_playback`（字段已移除，无法编译）。历史说明见 [`DIFF_SUMMARY.txt`](../../patches/ubuntu-hwe-6.17/DIFF_SUMMARY.txt)。
---
@@ -30,7 +30,7 @@
曾尝试在 `set_idisp_hdmi_link` 中增加 **`SND_SOC_DPCM_TRIGGER_POST`**（旧称 0002），**Kaisa 真机 HDMI 仍无声**；该补丁已从仓库删除。
新补丁应在细读 **ChromeOS 5.15 与 6.17** 在 **`sound/soc/sof/ipc3.c`、`pcm.c`、`sound/soc/sof/intel/hda-dai.c`** 等上的差异后再设计，流程见 [`docs/OPERATION_ChromeOS_Kernel_Deep_Diff.md`](OPERATION_ChromeOS_Kernel_Deep_Diff.md)、[`docs/CHROMEOS_vs_UBUNTU617_SOUND_AUTODIFF.md`](CHROMEOS_vs_UBUNTU617_SOUND_AUTODIFF.md)、[`patches/ubuntu-hwe-6.17/README.md`](../patches/ubuntu-hwe-6.17/README.md)。
新补丁应在细读 **ChromeOS 5.15 与 6.17** 在 **`sound/soc/sof/ipc3.c`、`pcm.c`、`sound/soc/sof/intel/hda-dai.c`** 等上的差异后再设计，流程见 [`../kernel-build/OPERATION_ChromeOS_Kernel_Deep_Diff.md`](../kernel-build/OPERATION_ChromeOS_Kernel_Deep_Diff.md)、[`../meta/CHROMEOS_vs_UBUNTU617_SOUND_AUTODIFF.md`](../meta/CHROMEOS_vs_UBUNTU617_SOUND_AUTODIFF.md)、[`patches/ubuntu-hwe-6.17/README.md`](../../patches/ubuntu-hwe-6.17/README.md)。
---
@@ -52,6 +52,6 @@ diff -u \
## 五、与项目其它文档的关系
- 三平台现象与 dmesg 要点：`audio_topology/ANALYSIS_Audio.md`
- Ubuntu 打包与磁盘、勿混用 `make`/`debian/rules`：`docs/WORK_PROGRESS.md`
- Ubuntu 打包与磁盘、勿混用 `make`/`debian/rules`：`../meta/WORK_PROGRESS.md`
- HWE 6.17 构建脚本：`scripts/ubuntu-hwe-617-build.sh`（应用补丁需 **`PATCH=...`**）
- ChromeOS 深度 diff 与导出三文件 diff：`docs/OPERATION_ChromeOS_Kernel_Deep_Diff.md`
- ChromeOS 深度 diff 与导出三文件 diff：`../kernel-build/OPERATION_ChromeOS_Kernel_Deep_Diff.md`

105
docs/linux-hdmi/Linux_HDMI_Audio_Roadmap.md Normal file
View File

@@ -0,0 +1,105 @@
# Linux HDMI 无声：路线图与未来步骤
本文是 **Google Kaisa（Chromebox 10 代）+ Coreboot** 下 Linux **HDMI 无声音**问题的 **主路线图**。技术细节与论证见各专项文档；本文只固定 **顺序、产出物与维护方式**。
**全文档索引**：[INDEX.md](../INDEX.md)
**项目总览与问题表**：[../../README.md](../../README.md)
---
## 一、问题与范围
- **硬件**：Google Kaisa；Coreboot；HDMI 走 **SOF + iDisp / DisplayPort 音频** 链路。
- **典型现象**：Linux 下 **HDMI 无输出或无法稳定打开 PCM**；**3.5mm 通常正常**。同机 **ChromeOS / Windows HDMI 正常** 时，问题集中在 **Linux 内核 / SOF / 用户态路由**，而非线缆或显示器本身。
- **dmesg 常见线索**：`STREAM_PCM_PARAMS` IPC 失败、约 **-5（EIO）**，常与 **pcm2/3/4（HDMI1/2/3）** 某条相关（物理口与编号需实测对照）。
- **非本仓库机型**：其它机器 HDMI 无声原因可能完全不同（独显、默认 sink、PipeWire 等），**勿直接套用**本仓库内核补丁；可借用 [阶段 1](#阶段-1用户态基线) 的排查套路，根因结论见各文档。
---
## 二、已排除或低期望方向
下列方向在仓库内**已有结论或真机反馈**；重复投入前请先读链接，避免走弯路。
| 方向 | 结论摘要 | 详见 |
| ---- | -------- | ---- |
| 仅替换拓扑（tplg） | 与 ChromeOS 等效，**单独换 tplg 不能恢复 HDMI** | [ANALYSIS_Audio.md](../../audio_topology/ANALYSIS_Audio.md) |
| 仅换 intel-signed / community SOF 固件 | **不能单独恢复 HDMI**；可能影响插拔检测 | [OPERATION_Force_Intel_Signed_Firmware.md](../../audio_topology/OPERATION_Force_Intel_Signed_Firmware.md)、[WORK_PROGRESS.md](../meta/WORK_PROGRESS.md) |
| 旧 **0002**（iDisp `TRIGGER_POST`） | 真机无效；已从仓库删除 | [REANALYSIS_Linux_HDMI_Audio_Kaisa.md](REANALYSIS_Linux_HDMI_Audio_Kaisa.md)、[DIFF_SUMMARY.txt](../../patches/ubuntu-hwe-6.17/DIFF_SUMMARY.txt) |
| Ubuntu **Mainline 5.15** deb（如 kernel.ubuntu.com） | 真机 **HDMI 仍无声** 且 **3.5mm / WiFi 异常**；**不等于** ChromeOS 5.15 | [REANALYSIS_Linux_HDMI_Audio_Kaisa.md](REANALYSIS_Linux_HDMI_Audio_Kaisa.md) |
| NHLT 缺失 | **不是**根因（ChromeOS 也无 NHLT 仍正常） | [ANALYSIS_Audio.md](../../audio_topology/ANALYSIS_Audio.md) 第六节 |
---
## 三、分阶段路线图
```mermaid
flowchart LR
phase1[phase1_baseline_user]
phase2[phase2_kernel_0001]
phase3[phase3_deep_diff_bisect]
phase4[phase4_upstream_issue]
phase1 --> phase2 --> phase3 --> phase4
```
### 阶段 1：用户态基线
**目的**：确认设备枚举、默认输出、以及 dmesg 是否已出现 IPC 错误（避免「选错 sink」假阳性）。
1. `aplay -L` / `aplay -l`，对 **每个 HDMI 类** `plughw:卡号,设备号` 执行 `speaker-test`（见 [REPAIR_Plan_Audio.md](../../audio_topology/REPAIR_Plan_Audio.md) 1.2 节）。
2. 运行 [collect_linux_audio_topology.sh](../../audio_topology/collect_linux_audio_topology.sh)（建议 `sudo`），输出到 `audio_topology/collected/`；其中含 **SOF / HDMI / IPC 基线** dmesg 过滤。
3. 图形环境下确认默认播放设备未锁死在打不开的 HDMI 上。
**产出**：带时间戳的采集文件，便于前后对比。
### 阶段 2：HWE 6.17 与 0001 补丁
**目的**：在发行版栈上验证仓库内 **0001**（`ipc3-pcm.c`：FREE / trigger 使用 `sof_ipc_tx_message` + 回复），并正确安装自编内核与模块包。
1. 源码与版本：见 [kernel-src/README.md](../../kernel-src/README.md)；在 **Ubuntu Noble** 上与运行内核一致的 `apt source linux-hwe-6.17=...`。
2. 补丁校验： [scripts/verify-ubuntu-hwe617-0001-patch.sh](../../scripts/verify-ubuntu-hwe617-0001-patch.sh)（`patch --dry-run`；若树中已含补丁内容会提示跳过）。
3. 构建与安装：`PATCH=...` [scripts/ubuntu-hwe-617-build.sh](../../scripts/ubuntu-hwe-617-build.sh) `apply` → `deps` → `build`；安装见 [OPERATION_Install_CustomKernel_Ubuntu_HWE617.md](../kernel-build/OPERATION_Install_CustomKernel_Ubuntu_HWE617.md)（**linux-image-unsigned**、`linux-modules` + **modules-extra**、必要时 **iwlwifi** 等）。
4. **0001 与 `STREAM_PCM_PARAMS`**：0001 对齐 ChromeOS 的 FREE/trigger 路径；**不改变** `hw_params` / `STREAM_PCM_PARAMS` 发送逻辑。若 HDMI 仍失败且 dmesg 仍报 **PARAMS**，见 [STREAM_PCM_PARAMS_CHROME_UBUNTU_NOTES.md](../../patches/ubuntu-hwe-6.17/STREAM_PCM_PARAMS_CHROME_UBUNTU_NOTES.md)、[DIFF_SUMMARY.txt](../../patches/ubuntu-hwe-6.17/DIFF_SUMMARY.txt)。
**产出**：可启动的自编内核；复测后新的 `collected/` 与 dmesg 片段。
### 阶段 3：深度对照与可选 trace
**目的**：在 6.x 上定位 **iDisp / SOF IPC** 与 ChromeOS 5.15 的差异，为**新补丁**或 **bisect** 提供依据。
1. 克隆 ChromiumOS 5.15 内核树： [WORK_PROGRESS.md](../meta/WORK_PROGRESS.md) 第二节。
2. 流程与导出：`git` unshallow、按文件 diff： [OPERATION_ChromeOS_Kernel_Deep_Diff.md](../kernel-build/OPERATION_ChromeOS_Kernel_Deep_Diff.md)；脚本 [diff-chromeos-ubuntu-sound.sh](../../scripts/diff-chromeos-ubuntu-sound.sh)、[export-chromeos-ubuntu-sound-file-diffs.sh](../../scripts/export-chromeos-ubuntu-sound-file-diffs.sh)。
3. 仍无声时一键列文档与条件运行对照： [linux-hdmi-followup-workflow.sh](../../scripts/linux-hdmi-followup-workflow.sh)。
4. **可选**：按 [OPERATION_Kaisa_SOF_HDMI_Trace.md](OPERATION_Kaisa_SOF_HDMI_Trace.md)、[README_TRACE_KAISA.md](../../audio_topology/collected/README_TRACE_KAISA.md) 抓取带 IPC 载荷的日志。
**产出**：`reference/` 下 unified diff（若已配置双树）、或明确的「缺哪棵树」记录。
### 阶段 4：上游协同
**目的**：将 **最小复现包** 交给 SOF / ALSA 社区，避免闭门造车。
- 清单与邮件模板： [UPSTREAM_SOF_Kaisa_HDMI_REPRO.md](UPSTREAM_SOF_Kaisa_HDMI_REPRO.md)。
---
## 四、成功标准（建议）
- **客观**：对目标 HDMI 口播放时，**dmesg 中无**与本次播放相关的 **`STREAM_PCM_PARAMS` / `ipc tx error`**（或已确认为无害/已修复）。
- **主观**：显示器扬声器或耳机有稳定输出。
- **回归**：3.5mm、WiFi 等与本次改动无关的子系统无意外损坏（自编内核时注意装全模块包）。
---
## 五、维护与「当前阶段」
- **路线图正文**为本文件；**换机与源码 URL、实验结论**以 [WORK_PROGRESS.md](../meta/WORK_PROGRESS.md) 为准，两者应同步（WORK_PROGRESS 内「Linux HDMI 当前阶段」见该文件顶部）。
- **任务编号 L1–L4** 与阶段对应关系见根 [README.md](../../README.md) 任务列表。
---
## 六、相关文档速链
| 用途 | 链接 |
| ---- | ---- |
| Linux 分步操作与索引 | [REPAIR_Plan_Audio.md](../../audio_topology/REPAIR_Plan_Audio.md) |
| 长文分析（Mainline 误区、自定义内核注意） | [REANALYSIS_Linux_HDMI_Audio_Kaisa.md](REANALYSIS_Linux_HDMI_Audio_Kaisa.md) |
| API 对照（`playback_only` 等） | [CHROMEOS_VS_UBUNTU_HDMI_NOTES.md](CHROMEOS_VS_UBUNTU_HDMI_NOTES.md) |

2
docs/OPERATION_Kaisa_SOF_HDMI_Trace.md → docs/linux-hdmi/OPERATION_Kaisa_SOF_HDMI_Trace.md
View File

@@ -73,7 +73,7 @@ KR=$(uname -r)
sudo dmesg -T > "/tmp/dmesg_sof_TRACE_STREAM_PCM_PARAMS_jack-Kaisa_${KR}_${TS}.txt"
```
5. 将文件复制到本仓库 **`audio_topology/collected/`**（可 scp），并在 `docs/WORK_PROGRESS.md` 或 `docs/REANALYSIS_Linux_HDMI_Audio_Kaisa.md` 中加一行文件名索引。
5. 将文件复制到本仓库 **`audio_topology/collected/`**（可 scp），并在 `../meta/WORK_PROGRESS.md` 或 `REANALYSIS_Linux_HDMI_Audio_Kaisa.md` 中加一行文件名索引。
## 5. 日志中应关注的内容

24
docs/REANALYSIS_Linux_HDMI_Audio_Kaisa.md → docs/linux-hdmi/REANALYSIS_Linux_HDMI_Audio_Kaisa.md
View File

@@ -6,9 +6,9 @@
- 三平台对比与 dmesg：`audio_topology/ANALYSIS_Audio.md`
- 总修复顺序与文档索引：`audio_topology/REPAIR_Plan_Audio.md`
- ChromeOS 5.15 与 6.17 API 对照：`docs/CHROMEOS_VS_UBUNTU_HDMI_NOTES.md`
- ChromeOS 树深度 diff / 新补丁设计入口：`docs/OPERATION_ChromeOS_Kernel_Deep_Diff.md`
- 自编内核安装（含 signed 冲突、modules-extra / iwlwifi）：`docs/OPERATION_Install_CustomKernel_Ubuntu_HWE617.md`
- ChromeOS 5.15 与 6.17 API 对照：`CHROMEOS_VS_UBUNTU_HDMI_NOTES.md`（本目录）
- ChromeOS 树深度 diff / 新补丁设计入口：`../kernel-build/OPERATION_ChromeOS_Kernel_Deep_Diff.md`
- 自编内核安装（含 signed 冲突、modules-extra / iwlwifi）：`../kernel-build/OPERATION_Install_CustomKernel_Ubuntu_HWE617.md`
---
@@ -26,7 +26,7 @@
| 方向 | 结论 | 依据（仓库内） |
|------|------|----------------|
| **拓扑 tplg** | 与 ChromeOS **等效**（解压后规模一致、端点一致） | `ANALYSIS_Audio.md` 第四节、第五节 |
| **仅换 SOF 固件（intel-signed ↔ community）** | **不能单独恢复 HDMI**；还可能影响 3.5mm 插拔检测 | `WORK_PROGRESS.md`、`ANALYSIS_Audio.md` 第五节、`OPERATION_Force_Intel_Signed_Firmware.md` |
| **仅换 SOF 固件（intel-signed ↔ community）** | **不能单独恢复 HDMI**；还可能影响 3.5mm 插拔检测 | `../meta/WORK_PROGRESS.md`、`../../audio_topology/ANALYSIS_Audio.md` 第五节、`../../audio_topology/OPERATION_Force_Intel_Signed_Firmware.md` |
| **NHLT 缺失** | **不是根因**（ChromeOS 也无 NHLT 仍正常） | `ANALYSIS_Audio.md` 第六节 |
| **旧 0002 补丁（`set_idisp_hdmi_link` 里 `SND_SOC_DPCM_TRIGGER_POST`）** | **真机验证仍无 HDMI 声**；补丁**已从仓库删除**，不再维护 | 见 `CHROMEOS_VS_UBUNTU_HDMI_NOTES.md`、`patches/ubuntu-hwe-6.17/DIFF_SUMMARY.txt` |
| **Ubuntu Mainline 5.15（例：`v5.15.201` deb 装在 Noble 上）** | **HDMI 仍无声**；且相对 6.17 **3.5mm 也无声**、**WiFi 也无**（整体音频/无线栈退化） | 真机反馈（jack-Kaisa）；见下文 **「Mainline 5.15 ≠ ChromeOS 5.15」** |
@@ -42,7 +42,7 @@
在继续改内核前，建议先确认实验条件可靠（否则会出现「补丁无效」误判）：
1. **确已启动自编镜像**：`dpkg -l | grep linux-image | grep 6.17.0-19` 应为 **`linux-image-unsigned-...`**，而非仍占位的官方 **`linux-image-6.17.0-19-generic`**（二者互斥，易只装上 modules）。见安装文档第 2.1 节。
2. **模块包装全**：至少 **`linux-modules` + `linux-modules-extra`**，Intel 无线常见还需 **`linux-modules-iwlwifi-*`**；否则会出现 **WiFi 消失** 等与 HDMI 无关的干扰。见 `OPERATION_Install_CustomKernel_Ubuntu_HWE617.md`。
2. **模块包装全**：至少 **`linux-modules` + `linux-modules-extra`**，Intel 无线常见还需 **`linux-modules-iwlwifi-*`**；否则会出现 **WiFi 消失** 等与 HDMI 无关的干扰。见 `../kernel-build/OPERATION_Install_CustomKernel_Ubuntu_HWE617.md`。
3. **用户态与物理口**：`aplay -L` 列出所有 HDMI 类设备后，对 **每个候选 `plughw:卡,设备`** 做 `speaker-test`；系统设置里默认输出勿锁死在错误 sink。
---
@@ -57,7 +57,7 @@
- `aplay -L`（保留 HDMI 相关行）
- `sudo dmesg | grep -iE 'sof|STREAM_PCM|ipc failed|pcm[0-9]|ASoC|iDisp|hdmi'`（尾部 80～120 行即可）
- 可选：`alsa-info` 导出一份文本
- 可选（`STREAM_PCM_PARAMS` 深度）：按 **`docs/OPERATION_Kaisa_SOF_HDMI_Trace.md`** 开启 **`sof_debug=0x800`** 与 **dynamic_debug**，将带 IPC 载荷的 dmesg 放入 `audio_topology/collected/`（见同目录 **`README_TRACE_KAISA.md`**）。
- 可选（`STREAM_PCM_PARAMS` 深度）：按 **`OPERATION_Kaisa_SOF_HDMI_Trace.md`** 开启 **`sof_debug=0x800`** 与 **dynamic_debug**，将带 IPC 载荷的 dmesg 放入 `audio_topology/collected/`（见同目录 **`README_TRACE_KAISA.md`**）。
输出放入 `audio_topology/collected/`，文件名带日期与内核版本，便于 diff。
@@ -111,7 +111,7 @@ flowchart LR
```
- **HDMI 问题性质**：更可能是 **Linux（尤其 6.x 发行版栈）里 SOF/Intel/iDisp 路径与 Kaisa + Coreboot 的组合问题**；拓扑与「只换一份 SOF 固件」已反复证明**不够**。
- **旧 0001/0002**：已自仓库移除；**新补丁**按 [`OPERATION_ChromeOS_Kernel_Deep_Diff.md`](OPERATION_ChromeOS_Kernel_Deep_Diff.md) 流程重做。
- **旧 0001/0002**：已自仓库移除；**新补丁**按 [`../kernel-build/OPERATION_ChromeOS_Kernel_Deep_Diff.md`](../kernel-build/OPERATION_ChromeOS_Kernel_Deep_Diff.md) 流程重做。
- **Mainline 5.15 deb**：在 Kaisa 上 **阴性且引入 3.5mm/WiFi 回归**；**不推荐**继续折腾 Mainline 5.15。**若已安装**：用 GRUB **回到 6.17**，日常以 **完整 HWE 模块包** 为准。
- **仍值得做的对照**（可选、工作量更大）：**Ubuntu 22.04 早期 Live 的 5.15.0-xx-generic**（非 Mainline），或直接把材料交给 **SOF/ALSA 上游**；**bisect** 建议在 **linux.git 或 Ubuntu 同源** 上进行，而非混用 Noble + Mainline 老内核。
- **自编 6.17**：务必 **unsigned（若用）+ modules + extra（+ iwlwifi）** 装全，并保留可启动旧内核。
@@ -120,7 +120,7 @@ flowchart LR
## 六、文档维护建议
若你完成 **5.15 Live** 或 **上游 issue** 链接，可把结果摘要回写到 `audio_topology/ANALYSIS_Audio.md`（新增一小节）与 `docs/WORK_PROGRESS.md` 状态表，避免后人重复踩旧实验补丁/仅装两 deb/unsigned 冲突等坑。
若你完成 **5.15 Live** 或 **上游 issue** 链接，可把结果摘要回写到 `../../audio_topology/ANALYSIS_Audio.md`（新增一小节）与 `../meta/WORK_PROGRESS.md` 状态表，避免后人重复踩旧实验补丁/仅装两 deb/unsigned 冲突等坑。
---
@@ -191,7 +191,7 @@ uname -r
**说明**：
- Mainline **通常没有** Ubuntu HWE 那种 `linux-modules-extra` / `linux-modules-iwlwifi` 分包；多数驱动在 **`linux-modules-…` 一体包**里。
- **`linux-image-unsigned`**：开启 **Secure Boot** 时可能无法启动，需关闭或参考 `docs/OPERATION_Install_CustomKernel_Ubuntu_HWE617.md`。
- **`linux-image-unsigned`**：开启 **Secure Boot** 时可能无法启动，需关闭或参考 `../kernel-build/OPERATION_Install_CustomKernel_Ubuntu_HWE617.md`。
- 务必留好旧内核，以便 GRUB 切回 6.x。
### C. 其它带 5.15 的 Live（备选）
@@ -219,10 +219,10 @@ uname -r
ChromeOS 内核通常是 **v5.15 + 大量提交**；不要指望「一个补丁文件」解决问题，应 **缩小目录 + 看提交说明**。
1. **拿到树**（见 `docs/WORK_PROGRESS.md` 第二节），例如本仓库 `chromiumos_kernel/v5.15/`，分支如 `release-R144-16503.B-chromeos-5.15`。
1. **拿到树**（见 `../meta/WORK_PROGRESS.md` 第二节），例如本仓库 `chromiumos_kernel/v5.15/`，分支如 `release-R144-16503.B-chromeos-5.15`。
2. **操作清单与三文件 diff 导出**：[`docs/OPERATION_ChromeOS_Kernel_Deep_Diff.md`](OPERATION_ChromeOS_Kernel_Deep_Diff.md)（`git fetch --unshallow`、`git log`、`diff` / `export-chromeos-ubuntu-sound-file-diffs.sh`）。
3. **自动对照摘要**（本机可跑）：[`docs/CHROMEOS_vs_UBUNTU617_SOUND_AUTODIFF.md`](CHROMEOS_vs_UBUNTU617_SOUND_AUTODIFF.md)。随时重跑：
2. **操作清单与三文件 diff 导出**：[`../kernel-build/OPERATION_ChromeOS_Kernel_Deep_Diff.md`](../kernel-build/OPERATION_ChromeOS_Kernel_Deep_Diff.md)（`git fetch --unshallow`、`git log`、`diff` / `export-chromeos-ubuntu-sound-file-diffs.sh`）。
3. **自动对照摘要**（本机可跑）：[`../meta/CHROMEOS_vs_UBUNTU617_SOUND_AUTODIFF.md`](../meta/CHROMEOS_vs_UBUNTU617_SOUND_AUTODIFF.md)。随时重跑：
```bash
./scripts/diff-chromeos-ubuntu-sound.sh

4
docs/SOF_FIRMWARE_TOPO_Kaisa_CHECKLIST.md → docs/linux-hdmi/SOF_FIRMWARE_TOPO_Kaisa_CHECKLIST.md
View File

@@ -22,9 +22,9 @@ sha256sum /lib/firmware/intel/sof-tplg/sof-cml-rt5682.tplg.zst 2>/dev/null
| 拓扑文件 | `sof-cml-rt5682.tplg`（Chrome 解压约 35KB）；Linux 常为 `.tplg.zst` | 解压后规模与端点应与 ChromeOS 采集一致 |
| 固件 | CML 平台常见 `sof-cml.ri`；Chrome 倾向 **intel-signed**，Ubuntu 常选 **community** | 已实验证明 **仅换 signed/community 不能单独恢复 HDMI**；仍应记录本机实际路径 |
| dmesg | 无「topology load failed」或明显 ABI 不匹配 | 若有加载错误，优先修复路径/文件再谈 IPC -5 |
| 与 IPC 观测结合 | `docs/OPERATION_Kaisa_SOF_HDMI_Trace.md` | 载荷中 **comp_id** 须与 tplg 中对应 PCM 节点一致；若一致仍 -5，偏向 **固件策略或 DSP bug** |
| 与 IPC 观测结合 | `OPERATION_Kaisa_SOF_HDMI_Trace.md` | 载荷中 **comp_id** 须与 tplg 中对应 PCM 节点一致；若一致仍 -5，偏向 **固件策略或 DSP bug** |
## 结论引用（已有）
- 拓扑 **等效**、仅换固件 **非主因**：见 `ANALYSIS_Audio.md` 第四节、第五节及 `docs/REANALYSIS_Linux_HDMI_Audio_Kaisa.md`。
- 拓扑 **等效**、仅换固件 **非主因**：见 `../../audio_topology/ANALYSIS_Audio.md` 第四节、第五节及 `REANALYSIS_Linux_HDMI_Audio_Kaisa.md`。
- 本清单用于 **回归与上游报障时的环境快照**，不替代内核/驱动根因分析。

6
docs/UPSTREAM_SOF_Kaisa_HDMI_REPRO.md → docs/linux-hdmi/UPSTREAM_SOF_Kaisa_HDMI_REPRO.md
View File

@@ -5,7 +5,7 @@
## 1. 硬件与引导
- 机型：**Google Kaisa**（Chromebox 10 代），Coreboot。
- 对照：**同机 ChromeOS HDMI 正常**；**Windows HDMI 正常**（见仓库 `audio_topology/` 与 `docs/REANALYSIS_Linux_HDMI_Audio_Kaisa.md`）。
- 对照：**同机 ChromeOS HDMI 正常**；**Windows HDMI 正常**（见仓库 `audio_topology/` 与 `REANALYSIS_Linux_HDMI_Audio_Kaisa.md`）。
## 2. 软件版本（请填真机实测）
@@ -20,11 +20,11 @@
仓库已有示例：
`audio_topology/collected/dmesg_sof_STREAM_PCM_PARAMS_HDMI3_jack-Kaisa_6.17.0-19-generic_20260404.txt`
- **`alsa-info` 导出**（或 `aplay -L`、`/proc/asound` 相关片段）。
- **可选（强烈建议）**：按 **`docs/OPERATION_Kaisa_SOF_HDMI_Trace.md`** 采集带 **IPC 载荷十六进制** 的 dmesg，放入 `audio_topology/collected/` 并附文件名。
- **可选（强烈建议）**：按 **`OPERATION_Kaisa_SOF_HDMI_Trace.md`** 采集带 **IPC 载荷十六进制** 的 dmesg，放入 `audio_topology/collected/` 并附文件名。
## 4. 固件与拓扑快照
按 **`docs/SOF_FIRMWARE_TOPO_Kaisa_CHECKLIST.md`** 附：`dmesg` 中固件/tplg 路径、`sha256sum` 结果。
按 **`SOF_FIRMWARE_TOPO_Kaisa_CHECKLIST.md`** 附：`dmesg` 中固件/tplg 路径、`sha256sum` 结果。
## 5. 已尝试且不足以单独修复的方向（避免重复提问）

6
docs/CHROMEOS_vs_UBUNTU617_SOUND_AUTODIFF.md → docs/meta/CHROMEOS_vs_UBUNTU617_SOUND_AUTODIFF.md
View File

@@ -2,7 +2,7 @@
本文档由仓库内脚本/命令**自动生成摘要**（非手工逐行审查结论）。用于回答：**ChromeOS 树与 6.17 在 SOF/Intel 音频上差多大、该先看哪些文件**。
**操作清单**（`git fetch --unshallow`、`git log`、导出 `ipc3`/`pcm`/`hda-dai` 全文 diff）：[`OPERATION_ChromeOS_Kernel_Deep_Diff.md`](OPERATION_ChromeOS_Kernel_Deep_Diff.md)。
**操作清单**（`git fetch --unshallow`、`git log`、导出 `ipc3`/`pcm`/`hda-dai` 全文 diff）：[`../kernel-build/OPERATION_ChromeOS_Kernel_Deep_Diff.md`](../kernel-build/OPERATION_ChromeOS_Kernel_Deep_Diff.md)。
**路径约定**（本仓库）：
@@ -22,7 +22,7 @@ git fetch --unshallow origin
# 或重新克隆时不加 --depth 1
```
若提示 **`--unshallow on a complete repository does not make sense`**，表示已是完整仓库，跳过本步即可（详见 [`OPERATION_ChromeOS_Kernel_Deep_Diff.md`](OPERATION_ChromeOS_Kernel_Deep_Diff.md)）。
若提示 **`--unshallow on a complete repository does not make sense`**，表示已是完整仓库，跳过本步即可（详见 [`../kernel-build/OPERATION_ChromeOS_Kernel_Deep_Diff.md`](../kernel-build/OPERATION_ChromeOS_Kernel_Deep_Diff.md)）。
然后再执行：
@@ -87,7 +87,7 @@ UB=/path/to/linux-hwe-6.17-6.17.0 \
---
## 5. 与 `docs/REANALYSIS_Linux_HDMI_Audio_Kaisa.md` 的关系
## 5. 与 `docs/linux-hdmi/REANALYSIS_Linux_HDMI_Audio_Kaisa.md` 的关系
- 本文档给出 **「从哪里下刀 diff」** 的**量化清单**。
- **ChromeOS 定制补丁的语义**（哪些提交该 port）仍需 **`git log`（非浅克隆）** 或 **人工读 diff** 后结论。

12
docs/OPERATION_DualBoot_Ubuntu24_Windows.md → docs/meta/OPERATION_DualBoot_Ubuntu24_Windows.md
View File

@@ -30,7 +30,7 @@
- （可选）`/home`（ext4）按需
- （可选）swap：8–32GB（看内存与休眠需求）
> 若你计划在 Ubuntu 上编译 `linux-hwe-6.17` deb：建议 Ubuntu 分区额外留出 **≥35–50GB 空闲**（见本仓库 `docs/WORK_PROGRESS.md` 的经验）。
> 若你计划在 Ubuntu 上编译 `linux-hwe-6.17` deb：建议 Ubuntu 分区额外留出 **≥35–50GB 空闲**（见本仓库 `docs/meta/WORK_PROGRESS.md` 的经验）。
---
@@ -46,8 +46,8 @@
**Windows 侧（本项目相关）**：
- 先不要急着装“通用 Realtek 声卡包”。本机 3.5mm 往往依赖 **CoolStar SOF + ALC5682 I2S** 栈。
- 先按本仓库 Windows 指南处理：
- `audio_topology/OPERATION_Windows_Audio.md`
- `audio_topology/HARDWARE_ID_DRIVER_MAP_Windows.md`
- `docs/windows/OPERATION_Windows_Audio.md`
- `docs/windows/HARDWARE_ID_DRIVER_MAP_Windows.md`
### 2) 再安装 Ubuntu 24.04
@@ -148,15 +148,15 @@ timedatectl set-local-rtc 0 --adjust-system-clock
- **Realtek ALC5682 I2S Audio**：硬件 ID 常见 `ACPI\\10EC5682\\...`
按本仓库文档走：
- `audio_topology/OPERATION_Windows_Audio.md`
- `audio_topology/HARDWARE_ID_DRIVER_MAP_Windows.md`
- `docs/windows/OPERATION_Windows_Audio.md`
- `docs/windows/HARDWARE_ID_DRIVER_MAP_Windows.md`
### 2) Linux 内核（HWE 6.17 编译/安装）
若你要在 Ubuntu 24.04 上编译本仓库的 HWE 6.17 内核包：
- 源码放置：`kernel-src/linux-hwe-6.17-6.17.0/`
- 脚本入口：`scripts/ubuntu-hwe-617-build.sh`
- 经验提醒：不要在同一源码树混用裸 `make` 与 `debian/rules`；如做过 smoke-test，打包前可 `make ARCH=x86 mrproper` 清洁树（详见 `docs/WORK_PROGRESS.md`）。
- 经验提醒：不要在同一源码树混用裸 `make` 与 `debian/rules`；如做过 smoke-test，打包前可 `make ARCH=x86 mrproper` 清洁树（详见 `docs/meta/WORK_PROGRESS.md`）。
---

139
docs/meta/WORK_PROGRESS.md Normal file
View File

@@ -0,0 +1,139 @@
# 工作进度与源码获取说明（换机交接）
面向机型：**Google Kaisa（Chromebox 10 代）**；核心问题：**Linux HDMI 无声（`STREAM_PCM_PARAMS` IPC 约 -5）**、**Windows 3.5mm 无声**；对照：**ChromeOS 上 HDMI / 3.5mm 正常**。
---
## 文档导航与 Linux HDMI 阶段
| 资源 | 路径 |
| ---- | ---- |
| 全文档索引（按主题） | [INDEX.md](../INDEX.md) |
| **Linux HDMI 路线图**（分阶段行动、已排除项、成功标准） | [../linux-hdmi/Linux_HDMI_Audio_Roadmap.md](../linux-hdmi/Linux_HDMI_Audio_Roadmap.md) |
| 项目根 README（任务与 L1–L4 映射） | [../../README.md](../../README.md) |
**协作时**：在本文或路线图「五、维护」中注明当前卡在哪一阶段（例如：阶段 2 已装自编内核、阶段 3 待克隆 `chromiumos_kernel/v5.15`）。
---
## 一、当前结论与状态
| 方向 | 状态 |
|------|------|
| 固件（intel-signed vs community） | 已实验：**单独换固件不能恢复 HDMI**；可能影响插拔检测，需按 OPERATION 文档回退 |
| 拓扑 | 与 ChromeOS **等效**（采集结论见 `audio_topology/ANALYSIS_Audio.md`） |
| Ubuntu HWE 6.17 补丁 | **0001** 在 `patches/ubuntu-hwe-6.17/`（FREE/trigger 路径；**不解决** `STREAM_PCM_PARAMS`）。**STREAM_PCM_PARAMS** 对照见 `patches/ubuntu-hwe-6.17/STREAM_PCM_PARAMS_CHROME_UBUNTU_NOTES.md`；真机 IPC 载荷观测见 **`docs/linux-hdmi/OPERATION_Kaisa_SOF_HDMI_Trace.md`**、`audio_topology/collected/README_TRACE_KAISA.md`。上游复现包清单见 **`docs/linux-hdmi/UPSTREAM_SOF_Kaisa_HDMI_REPRO.md`**。另见 `DIFF_SUMMARY.txt`、`docs/kernel-build/OPERATION_ChromeOS_Kernel_Deep_Diff.md`、`docs/linux-hdmi/REANALYSIS_Linux_HDMI_Audio_Kaisa.md` |
| Mainline 5.15（kernel.ubuntu.com，如 v5.15.201） | 真机：**HDMI 仍无声**；**3.5mm、WiFi 也异常**（相对 6.17）。**不等于** ChromeOS 5.15；**不建议**作修复主线，应 **GRUB 回 6.17** 并装全 HWE 模块包 | 见 `docs/linux-hdmi/REANALYSIS_Linux_HDMI_Audio_Kaisa.md` |
| 全量内核编译 `fakeroot debian/rules binary-generic` | **已在具备足够磁盘的环境完成**（`kernel-src/` 下产出 `linux-image-unsigned-*`、`linux-modules-*` 等 deb）；常见遇阻：**磁盘空间不足**（建议 **≥35～50GB**）；勿在同一源码树混用裸 `make` 与 `debian/rules`（需 `make ARCH=x86 mrproper` 清根目录后再打包） |
| Windows 侧 | 以 **CoolStar / Chrultrabook 成套驱动** 与设备管理器排错为主；见 `docs/windows/OPERATION_Windows_Audio.md` |
---
## 二、源码一：ChromiumOS / ChromeOS 内核（对照「HDMI 正常」）
**用途**：对照 **SOF / Intel boards / ACPI match** 等与 HDMI 相关的驱动差异（分支示例：`release-R144-16503.B-chromeos-5.15`）。
**官方仓库（HTTPS）**：
- `https://chromium.googlesource.com/chromiumos/third_party/kernel`
**克隆示例（浅克隆 + 指定分支）**：
```bash
mkdir -p /path/to/chromiumos_kernel && cd /path/to/chromiumos_kernel
git clone --depth 1 -b release-R144-16503.B-chromeos-5.15 \
https://chromium.googlesource.com/chromiumos/third_party/kernel.git v5.15
```
**可选：只检出音频相关目录（减小体积）**（在 `v5.15` 内执行）：
```bash
cd v5.15
git sparse-checkout init --cone
git sparse-checkout set sound/soc/intel sound/soc/sof include/sound
```
**本仓库内路径（若已存在）**：`chromiumos_kernel/v5.15/`（以你机器实际为准）。
---
## 三、源码二：Ubuntu HWE 6.17 内核（与当前运行内核一致）
**用途**：与 ChromeOS 5.15 做 diff / 打补丁 / 编译验证（与当前 Ubuntu 包版本一致）。
**注意**：二进制包名可能是 `linux-image-*`，但**源码包名**为 `linux-hwe-6.17`，**不是** `linux`（`apt source linux=6.17...` 会失败）。
**启用源码仓库**（Noble 示例）：
```bash
sudo sed -i 's/^Types: deb$/Types: deb deb-src/' /etc/apt/sources.list.d/ubuntu.sources
sudo apt update
```
**查本机内核对应的源码包与版本**：
```bash
dpkg -s "linux-image-$(uname -r)" | grep -E '^Source:|^Version:'
apt-cache showsrc linux-hwe-6.17 | grep -E '^Package:|^Version:' | head
```
**下载源码（把 `Version:` 换成 `apt-cache showsrc` 里与当前内核一致的那一行）**：
```bash
mkdir -p /path/to/chromebox_10th_audio_driver/kernel-src && cd /path/to/chromebox_10th_audio_driver/kernel-src
apt source linux-hwe-6.17=6.17.0-19.19~24.04.2
```
解压得到目录类似：`linux-hwe-6.17-6.17.0/`，以及 `.dsc` / `.orig.tar.gz` / `.diff.gz`（大文件已被 `.gitignore` 忽略，不提交仓库；见 `kernel-src/README.md`）。
**编译 generic 包（需足够磁盘与依赖）**：
```bash
sudo apt build-dep linux-hwe-6.17
cd /path/to/chromebox_10th_audio_driver/kernel-src/linux-hwe-6.17-6.17.0
export CONCURRENCY_LEVEL="$(nproc)"
fakeroot debian/rules clean
fakeroot debian/rules binary-generic
```
**仓库内辅助脚本**：`scripts/ubuntu-hwe-617-build.sh`、`scripts/ubuntu-hwe-617-deps-packages.txt`；**README** 中有入口。
---
## 四、换机后建议最短路径
1. 克隆本仓库 `chromebox_10th_audio_driver`。
2. 按需在本仓库 **`kernel-src/`** 下重新拉取 **Ubuntu 源码**（用新机器上的 `uname -r` / `dpkg -s` / `apt-cache showsrc` 核对版本号；**24.04** 上可直接 `apt build-dep linux-hwe-6.17`）。
3. 按需重新克隆 **ChromiumOS kernel** 分支（或从旧机拷贝 `chromiumos_kernel/` 目录）。
4. 阅读：`docs/linux-hdmi/Linux_HDMI_Audio_Roadmap.md`、`docs/INDEX.md`、`audio_topology/REPAIR_Plan_Audio.md`、`audio_topology/ANALYSIS_Audio.md`。
---
## 五、文档索引
| 文档 | 说明 |
|------|------|
| `docs/INDEX.md` | 全文档索引 |
| `docs/linux-hdmi/Linux_HDMI_Audio_Roadmap.md` | Linux HDMI 分阶段路线图 |
| `audio_topology/REPAIR_Plan_Audio.md` | Linux / Windows 修复总览 |
| `audio_topology/ANALYSIS_Audio.md` | 三平台对比与 dmesg 要点 |
| `audio_topology/OPERATION_Force_Intel_Signed_Firmware.md` | Linux SOF 固件与回退 |
| `docs/windows/OPERATION_Windows_Audio.md` | Windows CoolStar / ALC5682 |
| `README.md`（仓库根） | 任务列表与参考链接 |
| `docs/linux-hdmi/OPERATION_Kaisa_SOF_HDMI_Trace.md` | Kaisa：`dynamic_debug` + `sof_debug=0x800`、采集 dmesg |
| `docs/linux-hdmi/SOF_FIRMWARE_TOPO_Kaisa_CHECKLIST.md` | 固件/tplg 与基线核对 |
| `docs/linux-hdmi/UPSTREAM_SOF_Kaisa_HDMI_REPRO.md` | 上游 issue/邮件复现包与模板 |
---
---
## 六、ChromeOS 对照计划执行状态（本仓库快照）
- **预检脚本**（两棵树齐全后自动跑 diff + export）：[`scripts/preflight-chromeos-ubuntu-diff.sh`](../../scripts/preflight-chromeos-ubuntu-diff.sh)。
- **常见阻塞**：未克隆 `chromiumos_kernel/v5.15/`；或仅有部分 `kernel-src/linux-hwe-6.17-6.17.0/`（缺 `debian/` 则无法 `binary-generic`，需在本机 `apt source linux-hwe-6.17=…` 拉完整源码包）。
- **新补丁（0002）**：`STREAM_PCM_PARAMS_CHROME_UBUNTU_NOTES.md` 已说明 `ipc3-pcm` hw_params 与 Chrome 语义一致，**不宜**无依据新增大块补丁；优先 **trace / 上游复现** 后再写最小 hunk。
---
*本文档随工作机迁移更新；不修改 `.cursor/plans/` 下的计划文件。*

107
docs/windows/HARDWARE_ID_DRIVER_MAP_Windows.md Normal file
View File

@@ -0,0 +1,107 @@
# Windows：设备管理器 Hardware ID → 驱动包映射（Kaisa / Chromebox 10 代）
本文面向 **Coreboot + Windows** 下的音频排障：把「设备管理器里看到的 Hardware ID / 实例 ID」**对应到应装哪一类驱动包**，以及**不要用**哪类通用包。
> 采集样例（真实硬件）见 `collected/audio_topology_windows_DESKTOP-56TM6AL_20260213_205300.txt`。
> 安装顺序与故障现象仍见 [OPERATION_Windows_Audio.md](OPERATION_Windows_Audio.md)。
---
## 一、如何拿到 Hardware ID（务必复制完整）
1. **设备管理器** → 找到目标设备（音频相关多在「声音、视频和游戏控制器」）。
2. 右键 → **属性** → **详细信息**。
3. 下拉属性选 **硬件 Id** 或 **设备实例路径**（两者都建议各复制一份）。
4. 若设备在「其他设备」或带黄色感叹号，同样复制 **Hardware Id**。
**PowerShell 快速导出（可选，管理员）**：
```powershell
Get-PnpDevice -Class Media,AudioEndpoint -ErrorAction SilentlyContinue |
Select-Object Status, FriendlyName, InstanceId |
Format-Table -AutoSize
```
---
## 二、ID 形态速查（先认前缀再选包）
| 前缀 / 形态 | 通常含义 | 驱动来源倾向 |
|-------------|----------|----------------|
| `PCI\VEN_8086&DEV_...` | Intel 设备（含 HD Audio 控制器、部分 DSP 相关） | **Inbox Intel** 或 **CoolStar 包内 Intel 组件**（以机型页为准） |
| `PCI\VEN_10EC&DEV_...` | Realtek PCI 设备（多为网卡等，非本机 3.5mm codec） | 一般 **不是** 3.5mm 耳机路径 |
| `HDAUDIO\FUNC_01&VEN_8086&DEV_...` | Intel **HD Audio 函数**（常见为 **显示器音频 / HDMI Audio**） | 多为 **Intel 显示器音频**（系统自带或 Intel 更新），一般 **不是** CoolStar 主战场 |
| `ACPI\10EC5682\...` | ACPI 枚举的 **Realtek ALC5682（I2S）** | **CoolStar 包内 Realtek ALC5682 I2S**（或同机型说明中的 I2S 驱动） |
| `CSAUDIO\...` | **CoolStar 自定义 SOF 音频栈** | **CoolStar SOF Audio (WDM)** 对应驱动包；若 Error 需按 CoolStar 顺序重装 |
| `SWD\MMDEVAPI\{...}` | **音频端点**（扬声器/耳机/显示器名称） | **不是物理驱动**，由上层驱动枚举；排障时看 **Media 类设备** 的 ID |
---
## 三、本仓库实测样例（Kaisa，与采集文件一致）
以下 **InstanceId** 与 `collected/audio_topology_windows_*.txt` 中一致，可作为「设备名 ↔ ID ↔ 驱动包类型」的锚点。
### 1) CoolStar SOF Audio (WDM) — 常为 3.5mm 路径关键依赖
| 项目 | 值 |
|------|-----|
| **友好名称** | CoolStar SOF Audio (WDM) |
| **实例 ID（示例）** | `CSAUDIO\ADSP&CTLR_VEN_8086&CTLR_DEV_02C8\4&...&268435456` |
| **含义** | CoolStar 提供的 **SOF/ADSP** 栈；`CTLR_VEN_8086&CTLR_DEV_02C8` 表示与 **Intel 控制器设备** 绑定。 |
| **应对驱动包** | **CoolStar 包内「SOF Audio / Intel SOF/I2S」类组件**（具体 INF 名随版本变，以机型页与包内 readme 为准）。 |
| **常见故障** | 设备管理器显示 **Error** 时，易出现「ALC5682 显示 OK 但无声音」——优先 **消除该 Error** 再处理 ALC5682。 |
### 2) Realtek ALC5682 I2S Audio — 耳机 Codec
| 项目 | 值 |
|------|-----|
| **友好名称** | Realtek ALC5682 I2S Audio |
| **硬件 ID（示例）** | `ACPI\10EC5682\0`（即 **10EC:5682**） |
| **含义** | **Realtek ALC5682** 走 **I2S**，不是桌面机常见的 HDA PCI 声卡。 |
| **应对驱动包** | **CoolStar 包内「ALC5682 I2S」**（或同文档命名的 Realtek I2S 驱动）。 |
| **不要用** | 网上通用 **Realtek UAD / 台式机 OEM** 安装包强行覆盖（ACPI/I2S 与 Chromebox 不一致）。 |
### 3) 英特尔(R) 显示器音频 — HDMI 正常时常无需再动
| 项目 | 值 |
|------|-----|
| **友好名称** | 英特尔(R) 显示器音频 |
| **实例 ID（示例）** | `HDAUDIO\FUNC_01&VEN_8086&DEV_280B&SUBSYS_80860101&REV_1000\4&...&02` |
| **含义** | Intel **HD Audio 节点**，`DEV_280B` 对应 **Display Audio** 一类设备。 |
| **应对驱动包** | 通常 **Windows 自带 / Intel 显卡驱动附带** 即可；若已 OK，**不要**为修 3.5mm 去乱换通用 Realtek。 |
### 4) CoolStar HD Audio（PCI 类）
采集文件中存在 **CoolStar HD Audio**（`PCI\VEN_...`，内容截断）。一般对应 **CoolStar 包内 HD Audio 总线/控制器** 部分，安装顺序上常 **先于或与 SOF 协同**，以 **CoolStar 机型页 README** 为准。
---
## 四、映射表（按「你看到的 ID」→「该装哪类包」）
| 你在 Hardware Id / 实例 ID 里看到 | 应优先找的驱动包类型（CoolStar / Chrultrabook） |
|-----------------------------------|-----------------------------------------------|
| `CSAUDIO\...` | **SOF / ADSP（CoolStar SOF Audio）** |
| `ACPI\10EC5682...` 或含 `10EC5682` | **Realtek ALC5682 I2S** |
| `HDAUDIO\...VEN_8086&DEV_280B...` | **Intel 显示器音频**（HDMI）；**一般不是** 3.5mm 根因 |
| `PCI\VEN_8086&DEV_02C8...`（若出现在音频控制器相关设备上） | 与 **Intel 音频控制器** 相关；**配合 CoolStar SOF 包** 安装/更新 |
| 仅有 `SWD\MMDEVAPI\{...}` | **端点**；请回到 **Media** 类设备查 `CSAUDIO` / `ACPI\10EC5682` |
---
## 五、与 `pnputil` 对照（可选）
若需确认某台机器上 **哪个 INF 已安装**、便于冲突排查：
```cmd
pnputil /enum-drivers | findstr /i "coolstar realtek intel sof"
```
（输出因系统语言与驱动版本而异；把可疑 `oem*.inf` 与设备管理器里驱动版本对照即可。）
---
## 六、参考
- 操作步骤（安装顺序、Error 处理）：[OPERATION_Windows_Audio.md](OPERATION_Windows_Audio.md)
- 三平台对比：[ANALYSIS_Audio.md](../../audio_topology/ANALYSIS_Audio.md)
- Chrultrabook 安装后音频：<https://docs.chrultrabook.com/docs/installing/post-install.html>

93
docs/windows/OPERATION_Windows_Audio.md Normal file
View File

@@ -0,0 +1,93 @@
# Windows 音频修复说明（Chromebox 10 代 / Kaisa）
针对 **Coreboot 刷机后**：HDMI（英特尔显示器音频）正常，**3.5mm / Realtek ALC5682 I2S 无声、无插拔提示** 的情况。与 Linux 问题相反，修法依赖 **CoolStar / Chrultrabook 驱动栈**，不是桌面机通用 Realtek 安装包。
分析背景见 [ANALYSIS_Audio.md](../../audio_topology/ANALYSIS_Audio.md)；采集样例见 `audio_topology/collected/audio_topology_windows_*.txt`。
**Hardware ID → 驱动包类型映射**（按设备管理器里的 `CSAUDIO\...` / `ACPI\10EC5682\...` / `HDAUDIO\...VEN_8086&DEV_280B...` 等对号入座）：见 [HARDWARE_ID_DRIVER_MAP_Windows.md](HARDWARE_ID_DRIVER_MAP_Windows.md)。
---
## 现象与要点（对照设备管理器）
| 设备 | 常见状态 | 含义 |
|------|----------|------|
| **英特尔(R) 显示器音频** | OK | HDMI 走 HDA，一般无需再动 |
| **Realtek ALC5682 I2S Audio** | OK 但无声 | I2S codec 驱动已挂，但路由或与 SOF 协同异常 |
| **CoolStar SOF Audio (WDM)** | **Error** | 不少机型上 **3.5mm 依赖 SOF 相关栈**；此处报错时，容易出现「ALC5682 看似正常却不出声」 |
**结论**：优先消除 **CoolStar SOF Audio** 错误，再按官方顺序重装 **ALC5682 I2S**，不要单独用网上下载的通用 Realtek 安装程序覆盖。
---
## 一、准备
1. 确认机型为 **Kaisa（puff 系）** 或与你主板一致的 Chrultrabook 条目。
2. 准备 **CoolStar 驱动**：从购买授权时提供的 **驱动门户** 或 [CoolStar Chromebook Windows](https://coolstar.org/chromebook/windows-install.html) 机型页获取 **当前推荐版本**（包内通常含 HD Audio、SOF、I2S 等）。
3. 备份当前系统或创建还原点。
---
## 二、推荐安装顺序（概要）
具体以 **Chrultrabook Post-install** 与 **CoolStar 包内 readme** 为准，常见顺序为：
1. 安装/更新 **CoolStar HD Audio**（若包内要求）。
2. 安装/更新 **CoolStar SOF Audio (Intel/I2S)**（需有效授权时按说明激活）。
3. 安装/更新 **Realtek ALC5682 I2S**（多在同一个包或后续步骤中）。
4. **重启**后再测 3.5mm。
参考：[Chrultrabook Post-install 音频](https://docs.chrultrabook.com/docs/installing/post-install.html)。
---
## 三、设备管理器排查
### 1. 处理 CoolStar SOF Audio (WDM) 的 Error
1. **属性 → 常规**：记录 **错误代码**（如 10、43 等）与文字说明。
2. **属性 → 驱动程序**：
- **更新驱动**：指向 CoolStar 解压目录（**不要让 Windows 自动搜索互联网**）。
- 若无效：**卸载设备**（可选勾选「删除此设备的驱动程序软件」）→ 重启 → 用 **「操作 → 扫描检测硬件改动」** 或重新运行 CoolStar 安装程序。
3. 仍 Error：到 [Chrultrabook 论坛](https://forum.chrultrabook.com/) 搜索 **机型名 + SOF + 错误码**；或向 CoolStar 支持提交工单（附 `pnputil` / 设备实例 ID）。
### 2. Realtek ALC5682 I2S Audio
1. 在 SOF 设备已正常或至少安装流程完整执行后，对 **ALC5682** 再执行一次 **更新驱动**（指定 CoolStar 目录）。
2. 必要时 **卸载 ALC5682** → 重启 → 再安装，避免残留旧 `oem*.inf` 冲突。
3. 不要用 **Alienware/台式机** 等通用 Realtek UAD 包——ACPI/I2S 与 Chromebox 不一致。
---
## 四、系统侧检查
1. **设置 → 系统 → 声音**：默认输出选 **耳机 / Realtek / 模拟**（勿只选「显示器音频」）。
2. 确认 **Windows Audio**、**Windows Audio Endpoint Builder** 服务为「正在运行」。
3. 运行 **声音疑难解答**，排除应用独占或静音。
---
## 五、仍无声时
1. **事件查看器**：应用程序和服务日志 → Microsoft → Windows → Audio 相关项，查看与插拔、驱动加载有关的错误时间是否与重装一致。
2. **论坛**：带关键字 **Kaisa / puff、ALC5682、headphone、jack、CSAUDIO** 检索；同板卡已有解决方案时直接复现步骤。
3. **插孔检测 / 注册表**：属进阶（README **W4**），仅在确认驱动版本与 SOF 状态正常后、且论坛有明确指引时再改，避免系统不稳定。
---
## 六、与仓库任务对应
| README | 内容 |
|--------|------|
| **W1–W2** | 本机驱动需求与芯片确认（ALC5682 I2S + CoolStar SOF） |
| **W3** | 按上文消除 Error、重装 I2S、设默认设备 |
| **W4** | 插拔提示：依赖 HDA/codec 与 jack 检测，多在驱动与 DDI 正确后恢复 |
---
## 参考链接
- <https://docs.chrultrabook.com/docs/installing/post-install.html>
- <https://forum.chrultrabook.com/>
- <https://coolstar.org/chromebook/windows-install.html>
- 对比分析：[ANALYSIS_Audio.md](../../audio_topology/ANALYSIS_Audio.md)