# 工作进度与源码获取说明（换机交接）

**体例**：[DOCUMENTATION_STYLE.md](DOCUMENTATION_STYLE.md)。**平台对照两行表**见根 [README.md](../../README.md)；本文记录**阶段事实、clone 命令与磁盘经验**。

面向：**Google Kaisa**；主线问题 **Linux HDMI**（`STREAM_PCM_PARAMS` 约 -5）、**Windows 3.5mm**；对照 ChromeOS 正常。

**与 [Linux HDMI 路线图](../linux-hdmi/Linux_HDMI_Audio_Roadmap.md) 的分工**：**路线图** = **阶段顺序与建议行动**（该读哪一阶段、成功标准长什么样）；**本文** = **真机事实**——**日期**、**内核/`uname -r`**、**补丁是否已应用**、**clone/磁盘**、**阻塞**。不要在本文件写「替代路线图」的阶段定义；阶段含义以路线图为准，本文只记**当下状态**。

---

## 文档导航与 Linux HDMI 阶段

| 资源 | 路径 |
| ---- | ---- |
| **文档架构与进度分工**（入口分层、Mermaid、与本文/next 关系） | [DOCUMENTATION_ARCHITECTURE.md](DOCUMENTATION_ARCHITECTURE.md) |
| **文档体例与全项目改写约定** | [DOCUMENTATION_STYLE.md](DOCUMENTATION_STYLE.md) |
| 全文档索引（按主题） | [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`）。

### 验证上下文记录模板（FR5）

一次**补丁验证**或**内核构建**后，建议在本文「Linux HDMI」段落或顶部追加**可复现上下文**：

| 项 | 记录 |
|----|------|
| **`uname -r`** | 与验证时一致 |
| **内核包** | `dpkg -l \| grep linux-image` 是否含 **`linux-image-unsigned-*`**（自编） |
| **`kernel-src`** | **已准备**（例如 `kernel-src/linux-hwe-6.17-6.17.0/`）/ **未建**（声明计划） |
| **补丁** | 0001/0002/0003 是否已 **`PATCH=` + `apply`**（以树内事实为准） |

### `patch` 预检失败时（FR6）

若 **`patch -p1 --dry-run` 失败**，**禁止**使用 **`patch --force`** 掩盖问题。应记录：**stderr 片段**、**源码树版本**、**下一步**（对齐 `apt source` 版本 / 手工合并）。流程见 **[`patches/ubuntu-hwe-6.17/README.md`](../../patches/ubuntu-hwe-6.17/README.md)**。

**Linux HDMI（2026-04-04）**：**阶段 A 已完成**——`speaker-test` 对 **`plughw:0,2/0,3/0,4`** 均为 **不报错、静默无声**；**`0,0` 为 3.5mm**；采数时内核 **`6.17.0-20-generic`**。记录见 [`audio_topology/collected/PHASE_A_speaker-test_jack-Kaisa_20260404.md`](../../audio_topology/collected/PHASE_A_speaker-test_jack-Kaisa_20260404.md)。

**Linux HDMI（2026-04-05）**：**阶段 B 已落地**——自编 **HWE 6.17** 已 **`PATCH=` 应用 [0001](../../patches/ubuntu-hwe-6.17/0001-ASoC-SOF-ipc3-pcm-await-DSP-reply-for-FREE-and-trigger.patch) + [0002](../../patches/ubuntu-hwe-6.17/0002-ASoC-SOF-ipc3-pcm-dump-STREAM_PCM_PARAMS-fields.patch) + [0003](../../patches/ubuntu-hwe-6.17/0003-ASoC-SOF-hda-dai-dev_dbg-hda_link_dma_hw_params.patch)** 并完成编译；**日常启动即该自编内核**。若 **`uname -r`** 与官方同号，以 **`dpkg -l | grep linux-image`** 是否 **`linux-image-unsigned-*`** 为准，见 [OPERATION_Install_CustomKernel_Ubuntu_HWE617.md](../kernel-build/OPERATION_Install_CustomKernel_Ubuntu_HWE617.md)。**HDMI 仍无声**：按 [FIX_PLAN](../linux-hdmi/FIX_PLAN_HDMI_FROM_SOURCE_ANALYSIS.md) **阶段 C** 与 [路线图 3–4](../linux-hdmi/Linux_HDMI_Audio_Roadmap.md)。

---

## 一、当前结论与状态

| 方向 | 状态 |
|------|------|
| 固件（intel-signed vs community） | 已实验：**单独换固件不能恢复 HDMI**；可能影响插拔检测，需按 OPERATION 文档回退 |
| 拓扑 | 与 ChromeOS **等效**（采集结论见 `audio_topology/ANALYSIS_Audio.md`） |
| Ubuntu HWE 6.17 补丁 | **0001**（FREE/trigger；**不解决** `STREAM_PCM_PARAMS`）、**0002**（`STREAM_PCM_PARAMS` 字段 `spcm_dbg` 诊断，**不改载荷**）在 `patches/ubuntu-hwe-6.17/`。**STREAM_PCM_PARAMS** 对照见 `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)。**失败含义与补树入口**（FR15）：[PREFLIGHT_NOTES.md](PREFLIGHT_NOTES.md)（与脚本 **stderr** 一一对应）。
- **常见阻塞**：未克隆 `chromiumos_kernel/v5.15/`；或仅有部分 `kernel-src/linux-hwe-6.17-6.17.0/`（缺 `debian/` 则无法 `binary-generic`，需在本机 `apt source linux-hwe-6.17=…` 拉完整源码包）。
- **0002（诊断）**：`0002-*.patch` 仅在 `sof_debug` 含 payload dump 位时打印 `STREAM_PCM_PARAMS` 字段；**行为性**新补丁仍不宜无依据大块移植，见 `STREAM_PCM_PARAMS_CHROME_UBUNTU_NOTES.md`，优先 **trace / 上游复现** 后再写最小 hunk。

---

*本文档随工作机迁移更新；不修改 `.cursor/plans/` 下的计划文件。*