From 4f9b23d1446ac9281b8c54fbd9e8c0f67cf9eac2 Mon Sep 17 00:00:00 2001 From: jack Date: Sun, 5 Apr 2026 13:24:31 +0800 Subject: [PATCH] bmad base --- README.md | 81 +-- REPO_INDEX.md | 23 +- .../1-1-root-readme-index-chain.md | 63 ++ .../1-2-roadmap-vs-work-progress-boundary.md | 44 ++ .../1-3-excluded-paths-and-triage.md | 31 + .../1-4-index-sync-on-doc-change.md | 31 + .../1-5-hwe-hdmi-scripts-discoverable.md | 27 + .../1-6-linux-windows-doc-boundary.md | 29 + .../2-1-patch-dry-run-and-patch-env.md | 27 + .../2-2-record-uname-kernel-src.md | 27 + .../2-3-no-force-on-dry-run-failure.md | 29 + .../3-1-custom-kernel-install-rollback.md | 27 + .../3-2-build-failure-repro-record.md | 27 + .../4-1-verify-path-and-verify-ok.md | 27 + .../4-2-hdmi-logs-and-redaction.md | 27 + .../5-1-reference-text-collaboration.md | 27 + .../5-2-dual-tree-diff-export.md | 28 + .../5-3-dual-tree-path-entries.md | 27 + .../6-1-work-progress-stages-blocks.md | 27 + .../6-2-preflight-missing-trees.md | 31 + .../6-3-minimal-upstream-info-pack.md | 27 + .../6-4-roadmap-work-progress-crossref.md | 29 + .../7-1-upstream-gate-after-verify.md | 27 + .../sprint-status.yaml | 58 ++ .../planning-artifacts/architecture.md | 479 ++++++++++++++ _bmad-output/planning-artifacts/epics.md | 617 ++++++++++++++++++ .../implementation-readiness-report.md | 59 ++ _bmad-output/planning-artifacts/prd.md | 410 ++++++++++++ _bmad-output/project-context.md | 88 +++ _bmad/_config/files-manifest.csv | 16 +- _bmad/_config/ides/cursor.yaml | 2 +- _bmad/_config/manifest.yaml | 18 +- _bmad/bmb/config.yaml | 2 +- _bmad/bmm/config.yaml | 2 +- _bmad/cis/config.yaml | 2 +- _bmad/core/config.yaml | 2 +- _bmad/gds/config.yaml | 2 +- _bmad/tea/config.yaml | 2 +- _bmad/wds/config.yaml | 2 +- audio_topology/ANALYSIS_Audio.md | 2 + audio_topology/COLLECT.md | 12 +- .../OPERATION_Force_Intel_Signed_Firmware.md | 6 +- audio_topology/REPAIR_Plan_Audio.md | 23 +- ...HASE_A_speaker-test_jack-Kaisa_20260404.md | 66 ++ .../collected/README_TRACE_KAISA.md | 2 +- .../collected/UPSTREAM_REPRO_PACKAGE_INDEX.md | 2 +- ...-20-generic_jack-Kaisa_20260405_085924.txt | 41 ++ .../h3-topology-check-jack-Kaisa_20260404.md | 5 +- docs/INDEX.md | 47 +- docs/LLM_INDEX.md | 86 +++ docs/Linux_HDMI_Audio_Roadmap.md | 2 + docs/WORK_PROGRESS.md | 2 + docs/development-guide.md | 66 ++ docs/index.md | 48 ++ .../OPERATION_ChromeOS_Kernel_Deep_Diff.md | 6 +- ...TION_Install_CustomKernel_Ubuntu_HWE617.md | 6 +- .../CHROMEOS_KAISA_AUDIO_KERNEL_PATHS.md | 132 ++++ .../CHROMEOS_VS_UBUNTU_HDMI_NOTES.md | 6 +- .../FIX_PLAN_HDMI_FROM_SOURCE_ANALYSIS.md | 126 ++++ ...ERNEL_SRC_LINUX_HWE617_HDMI_3.5MM_PATHS.md | 149 +++++ docs/linux-hdmi/Linux_HDMI_Audio_Roadmap.md | 20 +- .../OPERATION_Kaisa_SOF_HDMI_Trace.md | 3 +- .../PHASE_A_DEVICE_MAP_CHROMEOS_COLLECTED.md | 64 ++ .../REANALYSIS_Linux_HDMI_Audio_Kaisa.md | 49 +- .../SOF_FIRMWARE_TOPO_Kaisa_CHECKLIST.md | 4 +- .../SOURCE_DIFF_CHROMEOS515_UBUNTU617.md | 124 ++++ .../UPSTREAM_SOF_Kaisa_HDMI_REPRO.md | 13 +- .../CHROMEOS_vs_UBUNTU617_SOUND_AUTODIFF.md | 24 +- docs/meta/DOCUMENTATION_ARCHITECTURE.md | 69 ++ docs/meta/DOCUMENTATION_STYLE.md | 78 +++ .../OPERATION_DualBoot_Ubuntu24_Windows.md | 9 +- docs/meta/PREFLIGHT_NOTES.md | 20 + docs/meta/WORK_PROGRESS.md | 29 +- docs/project-overview.md | 63 ++ docs/project-scan-report.json | 80 +++ docs/source-tree-analysis.md | 46 ++ .../windows/HARDWARE_ID_DRIVER_MAP_Windows.md | 2 +- docs/windows/OPERATION_Windows_Audio.md | 4 +- kernel-src/README.md | 6 + next.md | 38 +- patches/ubuntu-hwe-6.17/README.md | 23 + .../STREAM_PCM_PARAMS_CHROME_UBUNTU_NOTES.md | 7 +- patches/ubuntu-hwe-6.17/VERIFY_PATCHES.md | 70 ++ .../verify-ubuntu-hwe617-patches-runtime.sh | 122 ++++ 84 files changed, 4109 insertions(+), 197 deletions(-) create mode 100644 _bmad-output/implementation-artifacts/1-1-root-readme-index-chain.md create mode 100644 _bmad-output/implementation-artifacts/1-2-roadmap-vs-work-progress-boundary.md create mode 100644 _bmad-output/implementation-artifacts/1-3-excluded-paths-and-triage.md create mode 100644 _bmad-output/implementation-artifacts/1-4-index-sync-on-doc-change.md create mode 100644 _bmad-output/implementation-artifacts/1-5-hwe-hdmi-scripts-discoverable.md create mode 100644 _bmad-output/implementation-artifacts/1-6-linux-windows-doc-boundary.md create mode 100644 _bmad-output/implementation-artifacts/2-1-patch-dry-run-and-patch-env.md create mode 100644 _bmad-output/implementation-artifacts/2-2-record-uname-kernel-src.md create mode 100644 _bmad-output/implementation-artifacts/2-3-no-force-on-dry-run-failure.md create mode 100644 _bmad-output/implementation-artifacts/3-1-custom-kernel-install-rollback.md create mode 100644 _bmad-output/implementation-artifacts/3-2-build-failure-repro-record.md create mode 100644 _bmad-output/implementation-artifacts/4-1-verify-path-and-verify-ok.md create mode 100644 _bmad-output/implementation-artifacts/4-2-hdmi-logs-and-redaction.md create mode 100644 _bmad-output/implementation-artifacts/5-1-reference-text-collaboration.md create mode 100644 _bmad-output/implementation-artifacts/5-2-dual-tree-diff-export.md create mode 100644 _bmad-output/implementation-artifacts/5-3-dual-tree-path-entries.md create mode 100644 _bmad-output/implementation-artifacts/6-1-work-progress-stages-blocks.md create mode 100644 _bmad-output/implementation-artifacts/6-2-preflight-missing-trees.md create mode 100644 _bmad-output/implementation-artifacts/6-3-minimal-upstream-info-pack.md create mode 100644 _bmad-output/implementation-artifacts/6-4-roadmap-work-progress-crossref.md create mode 100644 _bmad-output/implementation-artifacts/7-1-upstream-gate-after-verify.md create mode 100644 _bmad-output/implementation-artifacts/sprint-status.yaml create mode 100644 _bmad-output/planning-artifacts/architecture.md create mode 100644 _bmad-output/planning-artifacts/epics.md create mode 100644 _bmad-output/planning-artifacts/implementation-readiness-report.md create mode 100644 _bmad-output/planning-artifacts/prd.md create mode 100644 _bmad-output/project-context.md create mode 100644 audio_topology/collected/PHASE_A_speaker-test_jack-Kaisa_20260404.md create mode 100644 audio_topology/collected/dmesg_storyC_PATCHED_6.17.0-20-generic_jack-Kaisa_20260405_085924.txt create mode 100644 docs/LLM_INDEX.md create mode 100644 docs/development-guide.md create mode 100644 docs/index.md create mode 100644 docs/linux-hdmi/CHROMEOS_KAISA_AUDIO_KERNEL_PATHS.md create mode 100644 docs/linux-hdmi/FIX_PLAN_HDMI_FROM_SOURCE_ANALYSIS.md create mode 100644 docs/linux-hdmi/KERNEL_SRC_LINUX_HWE617_HDMI_3.5MM_PATHS.md create mode 100644 docs/linux-hdmi/PHASE_A_DEVICE_MAP_CHROMEOS_COLLECTED.md create mode 100644 docs/linux-hdmi/SOURCE_DIFF_CHROMEOS515_UBUNTU617.md create mode 100644 docs/meta/DOCUMENTATION_ARCHITECTURE.md create mode 100644 docs/meta/DOCUMENTATION_STYLE.md create mode 100644 docs/meta/PREFLIGHT_NOTES.md create mode 100644 docs/project-overview.md create mode 100644 docs/project-scan-report.json create mode 100644 docs/source-tree-analysis.md create mode 100644 patches/ubuntu-hwe-6.17/VERIFY_PATCHES.md create mode 100755 scripts/verify-ubuntu-hwe617-patches-runtime.sh diff --git a/README.md b/README.md index 27e98ee5c5..6675216640 100644 --- a/README.md +++ b/README.md @@ -1,73 +1,74 @@ # chromebox_10th_audio_driver -修复 Chromebox 刷写 Coreboot 后，安装 Windows/Linux 时的声音问题。 +Kaisa（Chromebox 10 / Coreboot）上 **Linux / Windows** 音频排查文档；主线 **Ubuntu HWE 6.17**、**SOF / iDisp**、仓库补丁 `0001–0003`。 -## 文档入口（请先读） +## 文档入口 -**全仓库仅本文件为 README**；`docs/` 下详细目录见 [docs/INDEX.md](docs/INDEX.md)（非 README，避免双层入口）。 +**仅本文件为根 README**；主题表 [docs/INDEX.md](docs/INDEX.md)。子目录勿再建 README。 | 你想… | 打开 | | ----- | ---- | -| **全仓库路径索引**（含脚本、补丁、大目录说明） | [REPO_INDEX.md](REPO_INDEX.md) | -| **BMad 帮助目录（中文版，译自 bmad-help.csv）** | [bmad-help.zh-CN.md](bmad-help.zh-CN.md) | -| **解决 Linux HDMI 无声**（分阶段步骤、已排除项、成功标准） | [docs/linux-hdmi/Linux_HDMI_Audio_Roadmap.md](docs/linux-hdmi/Linux_HDMI_Audio_Roadmap.md) | -| **按主题浏览全部文档** | [docs/INDEX.md](docs/INDEX.md) | -| Linux / Windows 分平台思路与文档索引 | [audio_topology/REPAIR_Plan_Audio.md](audio_topology/REPAIR_Plan_Audio.md) | -| 三平台技术分析与对比 | [audio_topology/ANALYSIS_Audio.md](audio_topology/ANALYSIS_Audio.md) | -| 换机交接、源码克隆、实验结论 | [docs/meta/WORK_PROGRESS.md](docs/meta/WORK_PROGRESS.md) | +| 全路径（脚本/补丁/大目录） | [REPO_INDEX.md](REPO_INDEX.md) | +| BMad 菜单码（中文） | [bmad-help.zh-CN.md](bmad-help.zh-CN.md) | +| Linux HDMI 路线图 | [docs/linux-hdmi/Linux_HDMI_Audio_Roadmap.md](docs/linux-hdmi/Linux_HDMI_Audio_Roadmap.md) | +| 分平台总览 | [audio_topology/REPAIR_Plan_Audio.md](audio_topology/REPAIR_Plan_Audio.md) | +| 三平台技术分析 | [audio_topology/ANALYSIS_Audio.md](audio_topology/ANALYSIS_Audio.md) | +| 换机 / 阶段 / clone | [docs/meta/WORK_PROGRESS.md](docs/meta/WORK_PROGRESS.md) | +| 入口分层、进度分工（图） | [docs/meta/DOCUMENTATION_ARCHITECTURE.md](docs/meta/DOCUMENTATION_ARCHITECTURE.md) | +| 体例与改写约定 | [docs/meta/DOCUMENTATION_STYLE.md](docs/meta/DOCUMENTATION_STYLE.md) | +| 产品需求（PRD）/ 能力契约 | [_bmad-output/planning-artifacts/prd.md](_bmad-output/planning-artifacts/prd.md) | +| 架构决策（BMad CA） | [_bmad-output/planning-artifacts/architecture.md](_bmad-output/planning-artifacts/architecture.md) | +| Epic / Story（BMad CE） | [_bmad-output/planning-artifacts/epics.md](_bmad-output/planning-artifacts/epics.md) | --- ## 当前问题概况 +| 平台 | HDMI | 3.5mm | 插拔提示 | +|------|------|-------|----------| +| Linux | 无 | 有（选对 `aplay -L` 里 `plughw`）；**`0,2` 未必是 3.5mm** | 有 | +| Windows | 有 | 无 | 无 | -| 平台 | HDMI 声音 | 3.5mm 耳机声音 | 插入/拔出提示 | -| ------- | ------- | ---------- | ------- | -| Linux | 无 | **有**（选对 `aplay -L` 里耳机/模拟对应 **plughw** 时可播）；**`plughw:0,2` 不是 3.5mm 那条** | 有 | -| Windows | 有 | 无 | 无 | - - -**目标平台**：Chromebox（10 代 Intel，Google **Kaisa**），Coreboot 刷机后。 +**范围（FR20）**：上表为跨平台现象对照。**PRD 交付主线**为 **Linux HDMI**（见 [docs/INDEX.md](docs/INDEX.md)）。Windows 列仅作同款硬件参考；Windows 操作入口见 [INDEX · Windows 专项](docs/INDEX.md)，**不**属 PRD 必达的 Linux HDMI 方案。 --- -## 任务列表（与路线图对齐） +## 任务列表（对齐路线图） -> **建议顺序**：共通拓扑与文档 → Linux HDMI 按 [路线图](docs/linux-hdmi/Linux_HDMI_Audio_Roadmap.md) 分阶段推进 → Windows 3.5mm。 +顺序建议：拓扑与文档 → [Linux HDMI 路线图](docs/linux-hdmi/Linux_HDMI_Audio_Roadmap.md) → Windows 3.5mm。 -### 共通与文档 +### 共通 | 任务 | 说明 | | ---- | ---- | -| C1 | 硬件拓扑（HDMI、3.5mm、codec）：C1a Linux / C1b Windows 采集已完成；C1c 原生 ChromeOS 待补 | -| C2 | Coreboot 与原生 ChromeOS 固件音频差异（记录） | -| C3 | 分平台文档： [REPAIR_Plan_Audio.md](audio_topology/REPAIR_Plan_Audio.md) 与各 OPERATION | -| C4 | 已验证机型与固件版本（待补充） | +| C1 | 拓扑采集：C1a Linux / C1b Windows 已做；C1c ChromeOS 待补 | +| C2 | Coreboot vs 原生 ChromeOS 固件差异（记录） | +| C3 | [REPAIR_Plan_Audio.md](audio_topology/REPAIR_Plan_Audio.md) 与各 OPERATION | +| C4 | 已验证机型与固件版本（待补） | -### Linux（L1–L4 对应 HDMI 路线图阶段） +### Linux（L1–L4） -| 任务 | 对应路线图 | 说明 | -| ---- | ---------- | ---- | -| L1 | [路线图](docs/linux-hdmi/Linux_HDMI_Audio_Roadmap.md) | ALSA / PipeWire 用户态基线：`aplay`、`speaker-test`、采集脚本 | -| L2 | [路线图](docs/linux-hdmi/Linux_HDMI_Audio_Roadmap.md) | HDMI 走 SOF + iDisp；与内核/固件兼容性结论见 [ANALYSIS_Audio.md](audio_topology/ANALYSIS_Audio.md) | -| L3 | [路线图](docs/linux-hdmi/Linux_HDMI_Audio_Roadmap.md) | 固件实验（低期望）、HWE 6.17、0001 补丁与自编内核 | -| L4 | [路线图](docs/linux-hdmi/Linux_HDMI_Audio_Roadmap.md) + [docs/INDEX.md](docs/INDEX.md) | 脚本、补丁目录、深度 diff、上游复现 | +| 阶段 | 说明 | +|------|------| +| L1 | 用户态基线：`aplay`、`speaker-test`、采集 | +| L2 | SOF+iDisp；细节 [ANALYSIS_Audio.md](audio_topology/ANALYSIS_Audio.md) | +| L3 | 固件/HWE/0001/自编内核 | +| L4 | 脚本、补丁、diff、上游：[INDEX](docs/INDEX.md) | + +均对齐 [路线图](docs/linux-hdmi/Linux_HDMI_Audio_Roadmap.md)。 ### Windows | 任务 | 说明 | | ---- | ---- | -| W1–W4 | 3.5mm / CoolStar / ALC5682、插拔提示等： [docs/windows/OPERATION_Windows_Audio.md](docs/windows/OPERATION_Windows_Audio.md) | +| W1–W4 | [docs/windows/OPERATION_Windows_Audio.md](docs/windows/OPERATION_Windows_Audio.md) | --- -## 参考速链 +## 速链 -- Ubuntu HWE 6.17 源码与补丁：[kernel-src/README.md](kernel-src/README.md)、[patches/ubuntu-hwe-6.17/](patches/ubuntu-hwe-6.17/) -- 自编内核安装：[docs/kernel-build/OPERATION_Install_CustomKernel_Ubuntu_HWE617.md](docs/kernel-build/OPERATION_Install_CustomKernel_Ubuntu_HWE617.md) -- Linux SOF 固件实验与回退：[audio_topology/OPERATION_Force_Intel_Signed_Firmware.md](audio_topology/OPERATION_Force_Intel_Signed_Firmware.md) +- 源码与补丁：[kernel-src/README.md](kernel-src/README.md)、[patches/ubuntu-hwe-6.17/](patches/ubuntu-hwe-6.17/) +- 装自编 deb：[docs/kernel-build/OPERATION_Install_CustomKernel_Ubuntu_HWE617.md](docs/kernel-build/OPERATION_Install_CustomKernel_Ubuntu_HWE617.md) +- 固件实验：[audio_topology/OPERATION_Force_Intel_Signed_Firmware.md](audio_topology/OPERATION_Force_Intel_Signed_Firmware.md) - 双系统：[docs/meta/OPERATION_DualBoot_Ubuntu24_Windows.md](docs/meta/OPERATION_DualBoot_Ubuntu24_Windows.md) - -**脚本一览**（`ubuntu-hwe-617-build.sh`、采集、diff、trace 等）： [docs/INDEX.md](docs/INDEX.md) 文末「脚本」表。 - -**拓扑采集脚本说明**：[audio_topology/COLLECT.md](audio_topology/COLLECT.md) +- 脚本表：[docs/INDEX.md](docs/INDEX.md) 文末 · 采集：[audio_topology/COLLECT.md](audio_topology/COLLECT.md) diff --git a/REPO_INDEX.md b/REPO_INDEX.md index a3dc8b5858..d8f43f4c66 100644 --- a/REPO_INDEX.md +++ b/REPO_INDEX.md @@ -1,13 +1,8 @@ # 全仓库索引（Index Docs） -面向 **LLM / 换机交接**：快速定位本仓库「与 Chromebox 音频、Linux HDMI、内核补丁」相关的路径。 -**详细文档主题索引**仍以 [docs/INDEX.md](./docs/INDEX.md) 为准（表格更全）。 +Chromebox 音频 / HDMI / 补丁相关**路径速查**。主题文档表以 [docs/INDEX.md](./docs/INDEX.md) 为准。 ---- - -## 未纳入逐条列举的目录 - -以下体积大或为上游/工具树，本索引**只作说明**，不展开每个文件： +## 大目录（不逐文件列举） | 路径 | 说明 | | ---- | ---- | @@ -15,7 +10,16 @@ | [`kernel-src/linux-hwe-6.17-*/`](./kernel-src/) | Ubuntu HWE 内核解压树、`.dsc` / `.deb` / 构建日志；说明见 [`kernel-src/README.md`](./kernel-src/README.md) | | [`chromiumos_kernel/v5.15/`](./chromiumos_kernel/v5.15/) | ChromiumOS 5.15 对照用内核树（浅克隆/sparse 常见） | | [`_bmad/`](./_bmad/) | BMad Method 安装模块（技能与工作流）；总目录见 [`_bmad/_config/bmad-help.csv`](./_bmad/_config/bmad-help.csv) | -| [`_bmad-output/`](./_bmad-output/) | BMad 生成物输出目录（若存在） | +| [`_bmad-output/`](./_bmad-output/) | BMad 生成物输出目录（若存在）；**PRD** 见下表 | + +--- + +## [`_bmad-output/`](./_bmad-output/) — BMad 生成物（节选） + +| 文件 | 说明 | +| ---- | ---- | +| [planning-artifacts/prd.md](./_bmad-output/planning-artifacts/prd.md) | **产品需求文档（PRD）**：愿景、成功标准、用户旅程、范围、**FR/NFR** | +| [project-context.md](./_bmad-output/project-context.md) | 项目上下文（GPC；与 PRD 互补） | --- @@ -35,6 +39,8 @@ | 文件 / 目录 | 说明 | | ----------- | ---- | | [docs/INDEX.md](./docs/INDEX.md) | **`docs/` 主题索引**（Linux HDMI、内核安装、脚本等） | +| [docs/meta/DOCUMENTATION_STYLE.md](./docs/meta/DOCUMENTATION_STYLE.md) | **文档体例与改写约定**（全项目） | +| [docs/meta/PREFLIGHT_NOTES.md](./docs/meta/PREFLIGHT_NOTES.md) | 双树预检失败含义与补树入口 | | [docs/WORK_PROGRESS.md](./docs/WORK_PROGRESS.md) | 重定向 → `docs/meta/WORK_PROGRESS.md` | | [docs/Linux_HDMI_Audio_Roadmap.md](./docs/Linux_HDMI_Audio_Roadmap.md) | 重定向 → `docs/linux-hdmi/Linux_HDMI_Audio_Roadmap.md` | | [docs/linux-hdmi/](./docs/linux-hdmi/) | HDMI 路线图、重分析、ChromeOS 对照、trace、上游复现 | @@ -81,6 +87,7 @@ | ---- | ---- | | [ubuntu-hwe-617-build.sh](./scripts/ubuntu-hwe-617-build.sh) | `apply` / `deps` / `build` / `install` HWE 6.17 deb | | [verify-ubuntu-hwe617-0001-patch.sh](./scripts/verify-ubuntu-hwe617-0001-patch.sh) | 0001 补丁 `patch --dry-run` | +| [verify-ubuntu-hwe617-patches-runtime.sh](./scripts/verify-ubuntu-hwe617-patches-runtime.sh) | 真机验证 0001 源码 + 0002/0003 运行时（成功输出 `VERIFY_OK`） | | [linux-hdmi-followup-workflow.sh](./scripts/linux-hdmi-followup-workflow.sh) | HDMI 后续 diff / 文档入口 | | [diff-chromeos-ubuntu-sound.sh](./scripts/diff-chromeos-ubuntu-sound.sh) | `sound/soc` 统计对照 | | [preflight-chromeos-ubuntu-diff.sh](./scripts/preflight-chromeos-ubuntu-diff.sh) | 双树预检并跑 diff + export | diff --git a/_bmad-output/implementation-artifacts/1-1-root-readme-index-chain.md b/_bmad-output/implementation-artifacts/1-1-root-readme-index-chain.md new file mode 100644 index 0000000000..2441b897e1 --- /dev/null +++ b/_bmad-output/implementation-artifacts/1-1-root-readme-index-chain.md @@ -0,0 +1,63 @@ +# Story 1.1: 根入口与主题索引链完整 + +Status: done + +## Story + +As a **协作者或维护者**， +I want **从根 `README` 经 `docs/INDEX.md`（及 `REPO_INDEX` 速查）到达路线图与 `WORK_PROGRESS`**， +So that **我能在 ≤30 分钟内定位「下一步读什么」**。 + +## Acceptance Criteria + +1. **Given** 仅克隆仓库且未口头交接 **When** 依次打开 `README.md` → `docs/INDEX.md` **Then** 能找到指向 `Linux_HDMI_Audio_Roadmap.md` 与 `docs/meta/WORK_PROGRESS.md` 的明确链接 **And** 链接可点击且路径存在（或重定向说明存在） +2. **Given** 需要全路径速查 **When** 打开 `REPO_INDEX.md` **Then** 能定位 `scripts/`、`patches/`、`kernel-src/` 等关键目录的说明入口 +3. **（增强）** BMad 规划链：从 `README` / `INDEX` 可发现 **PRD、architecture、epics** 与 **project-context** + +## Tasks / Subtasks + +- [x] Task 1：核对 `README` 文档入口表含路线图、`WORK_PROGRESS`、`INDEX`（AC: #1） + - [x] 1.1 路径存在性检查（相对路径自洽） +- [x] Task 2：核对 `docs/INDEX.md` 含 HDMI 主路线图、`WORK_PROGRESS`、BMad 产出（AC: #1、#3） + - [x] 2.1 补充 **architecture.md**、**epics.md** 至 BMad 表（此前缺失 architecture/epics 显式入口） +- [x] Task 3：根 `README` 增加架构与 Epic 表行，与 `INDEX` 一致（AC: #3） +- [x] Task 4：`REPO_INDEX.md` 仍作为全路径速查；抽查与 Story 1.1 一致性（AC: #2） + +## Dev Notes + +- **棕地仓库**：无单元测试套件；验证 = 链接与文件存在性 + 人工阅读。 +- **架构约束**：`docs/INDEX` 与根 `README` 变更应同事务（NFR4）；本 Story 同一变更集内完成。 +- **勿** 新建子目录 README（根 README 已声明）。 + +### References + +- [Source: _bmad-output/planning-artifacts/epics.md — Story 1.1] +- [Source: _bmad-output/planning-artifacts/architecture.md — Navigation Anchors] +- [Source: _bmad-output/project-context.md — 文档] + +## Dev Agent Record + +### Agent Model Used + +Cursor Agent（用户发起「全都要」一站式执行） + +### Completion Notes List + +- 已在 `docs/INDEX.md` 的 **BMad 规划产出** 表中增加 **architecture.md**、**epics.md** 链接。 +- 已在根 `README.md` 文档入口表增加 **架构决策**、**Epic/Story** 两行，使 `README → INDEX → 路线图/WORK_PROGRESS` 与 **规划三角（PRD / Architecture / Epics）** 同链可发现。 + +### File List + +- `README.md`（修改） +- `docs/INDEX.md`（修改） +- `_bmad-output/planning-artifacts/implementation-readiness-report.md`（新建，IR） +- `_bmad-output/implementation-artifacts/sprint-status.yaml`（新建） +- `_bmad-output/implementation-artifacts/1-1-root-readme-index-chain.md`（本文件） + +### Change Log + +- 2026-04-05：Story 1.1 实现；INDEX/README 补齐 architecture & epics；IR + sprint 状态初始化。 + +## Senior Developer Review (AI) + +（可选，待独立 code-review 工作流填写） diff --git a/_bmad-output/implementation-artifacts/1-2-roadmap-vs-work-progress-boundary.md b/_bmad-output/implementation-artifacts/1-2-roadmap-vs-work-progress-boundary.md new file mode 100644 index 0000000000..5d17600c8b --- /dev/null +++ b/_bmad-output/implementation-artifacts/1-2-roadmap-vs-work-progress-boundary.md @@ -0,0 +1,44 @@ +# Story 1.2: 路线图与 WORK_PROGRESS 职责边界可读 + +Status: done + +## Story + +As a **读者**， +I want **在文档中看清「路线图管顺序、WORK_PROGRESS 管事实」**， +So that **我不会把阶段规划与换机/验证事实混为一谈**。 + +## Acceptance Criteria + +1. **Given** 阅读 `Linux_HDMI_Audio_Roadmap.md` 与 `docs/meta/WORK_PROGRESS.md` **When** 对比开篇说明 **Then** 明确：路线图 = 阶段顺序与建议；`WORK_PROGRESS` = 日期、内核、阻塞与换机事实 **And** 二者互相有交叉引用链接 + +## Tasks / Subtasks + +- [x] Task 1：在路线图开篇增加「文档角色」表与指向 `WORK_PROGRESS` 的链接（AC #1） +- [x] Task 2：在 `WORK_PROGRESS` 开篇增加与路线图分工的段落及反向链接（AC #1） + +## Dev Notes + +- 与 FR2、PRD「路线图 vs 进度」一致；不删既有导航表，仅补强分工语义。 + +### References + +- [Source: epics.md — Story 1.2] +- [Source: prd.md — FR2] + +## Dev Agent Record + +### Completion Notes List + +- 路线图：新增 **「文档角色（与 WORK_PROGRESS 的分工）」** 表；页眉增加指向 `WORK_PROGRESS.md` 的速链。 +- `WORK_PROGRESS`：在体例段后增加 **与路线图分工** 短段，并链回 `Linux_HDMI_Audio_Roadmap.md`。 + +### File List + +- `docs/linux-hdmi/Linux_HDMI_Audio_Roadmap.md` +- `docs/meta/WORK_PROGRESS.md` +- `_bmad-output/implementation-artifacts/1-2-roadmap-vs-work-progress-boundary.md`（本文件） + +### Change Log + +- 2026-04-05：Story 1.2 完成；双文档职责边界显式化。 diff --git a/_bmad-output/implementation-artifacts/1-3-excluded-paths-and-triage.md b/_bmad-output/implementation-artifacts/1-3-excluded-paths-and-triage.md new file mode 100644 index 0000000000..6a7d804535 --- /dev/null +++ b/_bmad-output/implementation-artifacts/1-3-excluded-paths-and-triage.md @@ -0,0 +1,31 @@ +# Story 1.3: 已排除路径与现象分流可引用 + +Status: done + +## Story + +As a **读者**， +I want **在现象分流时能查到「已知不成立路径」与继续对照的入口**， +So that **我不重复已记录弯路**。 + +## Acceptance Criteria + +1. **Given** HDMI 调试/无声 **When** 经 `INDEX` 进入路线图「已排除」、REANALYSIS、FIX_PLAN **Then** 能区分用户态试错 vs 内核/IPC 对照入口 **And** 与既有 `ANALYSIS_Audio` 等无矛盾 + +## Tasks / Subtasks + +- [x] 在 `docs/INDEX.md` 增加 **「HDMI 现象分流」** 表与简短分流说明（FR3） + +## Dev Notes + +- 路线图 §二 仍为「已排除」主表；INDEX 只做入口聚合。 + +## Dev Agent Record + +### File List + +- `docs/INDEX.md` + +### Change Log + +- 2026-04-05：Story 1.3 完成。 diff --git a/_bmad-output/implementation-artifacts/1-4-index-sync-on-doc-change.md b/_bmad-output/implementation-artifacts/1-4-index-sync-on-doc-change.md new file mode 100644 index 0000000000..ff053dbd40 --- /dev/null +++ b/_bmad-output/implementation-artifacts/1-4-index-sync-on-doc-change.md @@ -0,0 +1,31 @@ +# Story 1.4: 主题文档变更时同步索引 + +Status: done + +## Story + +As a **维护者**， +I want **新增或移动 `docs/` 下主题文档时，同一变更集更新 `INDEX`/`REPO_INDEX`**， +So that **不出现孤岛页**。 + +## Acceptance Criteria + +1. **Given** 新增主题文档 **When** 合并/提交 **Then** `INDEX` 或 `REPO_INDEX` 可发现 **And** NFR4 同事务 + +## Tasks / Subtasks + +- [x] 在 `DOCUMENTATION_STYLE.md` §2、§6 强化 **NFR4** 与 MR 说明中列出索引变更（FR18；NFR4） +- [x] 新增 `PREFLIGHT_NOTES.md` 并写入 **INDEX**、**REPO_INDEX**（本变更集） + +## Dev Agent Record + +### File List + +- `docs/meta/DOCUMENTATION_STYLE.md` +- `docs/meta/PREFLIGHT_NOTES.md` +- `docs/INDEX.md` +- `REPO_INDEX.md` + +### Change Log + +- 2026-04-05：Story 1.4 完成。 diff --git a/_bmad-output/implementation-artifacts/1-5-hwe-hdmi-scripts-discoverable.md b/_bmad-output/implementation-artifacts/1-5-hwe-hdmi-scripts-discoverable.md new file mode 100644 index 0000000000..1889c7694e --- /dev/null +++ b/_bmad-output/implementation-artifacts/1-5-hwe-hdmi-scripts-discoverable.md @@ -0,0 +1,27 @@ +# Story 1.5: HWE/HDMI 相关脚本可发现 + +Status: done + +## Story + +As a **协作者**， +I want **从 `INDEX` 或脚本表找到 `verify-*` / `ubuntu-hwe-*` 等脚本的用途与入口**， +So that **我不依赖聊天即可运行正确脚本**。 + +## Acceptance Criteria + +1. **Given** `docs/INDEX.md` 脚本表 **When** 查找验证/构建/diff **Then** 能定位 `verify-ubuntu-hwe617-patches-runtime.sh`、`ubuntu-hwe-617-build.sh` 等 **And** 链到 `VERIFY_PATCHES`/`README` + +## Tasks / Subtasks + +- [x] 在 `docs/INDEX.md` 脚本节增加 **FR19** 可发现性说明与 `VERIFY_PATCHES` 锚点 + +## Dev Agent Record + +### File List + +- `docs/INDEX.md` + +### Change Log + +- 2026-04-05：Story 1.5 完成。 diff --git a/_bmad-output/implementation-artifacts/1-6-linux-windows-doc-boundary.md b/_bmad-output/implementation-artifacts/1-6-linux-windows-doc-boundary.md new file mode 100644 index 0000000000..2265ea36b7 --- /dev/null +++ b/_bmad-output/implementation-artifacts/1-6-linux-windows-doc-boundary.md @@ -0,0 +1,29 @@ +# Story 1.6: Linux 与 Windows 文档分界可见 + +Status: done + +## Story + +As a **读者**， +I want **从索引或总览识别 Linux HDMI 主线与 Windows 文档入口**， +So that **我不把 Windows 操作当作 Linux HDMI 交付范围**。 + +## Acceptance Criteria + +1. **Given** `INDEX` 或根 `README` **When** 查跨平台信息 **Then** 分节明确 **And** 与 PRD FR20 一致 + +## Tasks / Subtasks + +- [x] `docs/INDEX.md` **Windows 专项** 增加 FR20 范围说明 +- [x] 根 `README.md` **当前问题概况** 表后增加 FR20 段落 + +## Dev Agent Record + +### File List + +- `docs/INDEX.md` +- `README.md` + +### Change Log + +- 2026-04-05：Story 1.6 完成。 diff --git a/_bmad-output/implementation-artifacts/2-1-patch-dry-run-and-patch-env.md b/_bmad-output/implementation-artifacts/2-1-patch-dry-run-and-patch-env.md new file mode 100644 index 0000000000..58db7e5c59 --- /dev/null +++ b/_bmad-output/implementation-artifacts/2-1-patch-dry-run-and-patch-env.md @@ -0,0 +1,27 @@ +# Story 2.1: 补丁预检与单文件应用路径 + +Status: done + +## Story + +As a **维护者**， +I want **对 `patches/ubuntu-hwe-6.17/` 中补丁在正确树上执行 `patch -p1 --dry-run` 并按 `PATCH=` 单文件应用**， +So that **应用前可判读成功/失败**。 + +## Acceptance Criteria + +1. **Given** 对齐的 `kernel-src` **When** 按 README 设置 `PATCH=` 并 dry-run **Then** 输出可判读 **And** 0001→0002、0003 独立说明可见 + +## Tasks / Subtasks + +- [x] `patches/ubuntu-hwe-6.17/README.md`：新增 **预检（dry-run）** 与顺序说明（FR4） + +## Dev Agent Record + +### File List + +- `patches/ubuntu-hwe-6.17/README.md` + +### Change Log + +- 2026-04-05：Story 2.1 完成。 diff --git a/_bmad-output/implementation-artifacts/2-2-record-uname-kernel-src.md b/_bmad-output/implementation-artifacts/2-2-record-uname-kernel-src.md new file mode 100644 index 0000000000..3141fcd0ba --- /dev/null +++ b/_bmad-output/implementation-artifacts/2-2-record-uname-kernel-src.md @@ -0,0 +1,27 @@ +# Story 2.2: 记录 uname 与 kernel-src 状态 + +Status: done + +## Story + +As a **维护者**， +I want **在 `WORK_PROGRESS` 或约定位置记录 `uname -r`、包来源与 `kernel-src` 状态**， +So that **他人能复现同一验证上下文**。 + +## Acceptance Criteria + +1. **Given** 补丁验证或构建 **When** 更新 `WORK_PROGRESS` **Then** 含 `uname -r`、内核线、`kernel-src` 已准备/未建 **And** 与 FR5、NFR5 叙述一致 + +## Tasks / Subtasks + +- [x] `docs/meta/WORK_PROGRESS.md`：新增 **验证上下文记录模板（FR5）** 表 + +## Dev Agent Record + +### File List + +- `docs/meta/WORK_PROGRESS.md` + +### Change Log + +- 2026-04-05：Story 2.2 完成。 diff --git a/_bmad-output/implementation-artifacts/2-3-no-force-on-dry-run-failure.md b/_bmad-output/implementation-artifacts/2-3-no-force-on-dry-run-failure.md new file mode 100644 index 0000000000..ec0e5fe052 --- /dev/null +++ b/_bmad-output/implementation-artifacts/2-3-no-force-on-dry-run-failure.md @@ -0,0 +1,29 @@ +# Story 2.3: 预检失败时不强制覆盖 + +Status: done + +## Story + +As a **维护者**， +I want **在 dry-run 失败时不使用 `patch --force` 掩盖问题**， +So that **我核对树版本或手工合并**。 + +## Acceptance Criteria + +1. **Given** dry-run 失败 **When** 查阅 `patches/.../README` **Then** 禁止 `patch --force` **And** `WORK_PROGRESS` 可记失败原因 + +## Tasks / Subtasks + +- [x] `patches/ubuntu-hwe-6.17/README.md`：**禁止在未解决失败时 patch --force** +- [x] `docs/meta/WORK_PROGRESS.md`：**patch 预检失败时（FR6）** + +## Dev Agent Record + +### File List + +- `patches/ubuntu-hwe-6.17/README.md` +- `docs/meta/WORK_PROGRESS.md` + +### Change Log + +- 2026-04-05：Story 2.3 完成。 diff --git a/_bmad-output/implementation-artifacts/3-1-custom-kernel-install-rollback.md b/_bmad-output/implementation-artifacts/3-1-custom-kernel-install-rollback.md new file mode 100644 index 0000000000..b404b73b1c --- /dev/null +++ b/_bmad-output/implementation-artifacts/3-1-custom-kernel-install-rollback.md @@ -0,0 +1,27 @@ +# Story 3.1: 自编内核安装与回退可执行 + +Status: done + +## Story + +As a **维护者**， +I want **按 `OPERATION_Install_CustomKernel_Ubuntu_HWE617.md` 完成安装与回退**， +So that **我可恢复可启动状态**（旅程 E）。 + +## Acceptance Criteria + +1. **Given** 已构建或未构建 deb **When** 跟随安装 OPERATION **Then** unsigned、模块包等以该文档为准 **And** 与 `WORK_PROGRESS` 可对照 + +## Tasks / Subtasks + +- [x] `docs/kernel-build/OPERATION_Install_CustomKernel_Ubuntu_HWE617.md`：开篇增加 **与 WORK_PROGRESS（FR7）** 互链 + +## Dev Agent Record + +### File List + +- `docs/kernel-build/OPERATION_Install_CustomKernel_Ubuntu_HWE617.md` + +### Change Log + +- 2026-04-05：Story 3.1 完成。 diff --git a/_bmad-output/implementation-artifacts/3-2-build-failure-repro-record.md b/_bmad-output/implementation-artifacts/3-2-build-failure-repro-record.md new file mode 100644 index 0000000000..d8582630f8 --- /dev/null +++ b/_bmad-output/implementation-artifacts/3-2-build-failure-repro-record.md @@ -0,0 +1,27 @@ +# Story 3.2: 完整内核构建失败可复现记录 + +Status: done + +## Story + +As a **维护者**， +I want **在 `binary-generic` 等失败时记录并行度、日志路径与空间事实**， +So that **重试或协作排查有据**。 + +## Acceptance Criteria + +1. **Given** 构建失败 **When** 更新 `WORK_PROGRESS` **Then** 记录并行、日志、磁盘等 **And** 符合 NFR6 + +## Tasks / Subtasks + +- [x] `kernel-src/README.md`：新增 **完整构建失败时（FR8；NFR6）** 指引 + +## Dev Agent Record + +### File List + +- `kernel-src/README.md` + +### Change Log + +- 2026-04-05：Story 3.2 完成。 diff --git a/_bmad-output/implementation-artifacts/4-1-verify-path-and-verify-ok.md b/_bmad-output/implementation-artifacts/4-1-verify-path-and-verify-ok.md new file mode 100644 index 0000000000..1d60b21d93 --- /dev/null +++ b/_bmad-output/implementation-artifacts/4-1-verify-path-and-verify-ok.md @@ -0,0 +1,27 @@ +# Story 4.1: 钉扎验证路径与可判读结果 + +Status: done + +## Story + +As a **维护者**， +I want **运行 `VERIFY_PATCHES.md` 与 `verify-ubuntu-hwe617-patches-runtime.sh` 所钉扎的路径**， +So that **我得到通过/失败与 `VERIFY_OK`（若适用）的明确语义**。 + +## Acceptance Criteria + +1. **Given** 基线环境 **When** 按 `VERIFY_PATCHES` 运行 **Then** 退出码可判读 **And** 不声称 CI 替代本机验证 + +## Tasks / Subtasks + +- [x] `patches/ubuntu-hwe-6.17/VERIFY_PATCHES.md`：增加 **本机验证为权威（FR9）** 段落 + +## Dev Agent Record + +### File List + +- `patches/ubuntu-hwe-6.17/VERIFY_PATCHES.md` + +### Change Log + +- 2026-04-05：Story 4.1 完成。 diff --git a/_bmad-output/implementation-artifacts/4-2-hdmi-logs-and-redaction.md b/_bmad-output/implementation-artifacts/4-2-hdmi-logs-and-redaction.md new file mode 100644 index 0000000000..7300ca9095 --- /dev/null +++ b/_bmad-output/implementation-artifacts/4-2-hdmi-logs-and-redaction.md @@ -0,0 +1,27 @@ +# Story 4.2: HDMI 试播日志工件与脱敏 + +Status: done + +## Story + +As a **维护者**， +I want **保存 HDMI 相关 dmesg/脚本输出，并在对外分享前按 `COLLECT.md` 脱敏**， +So that **证据可对齐路线图成功标准且不泄露隐私**。 + +## Acceptance Criteria + +1. **Given** HDMI 试播 **When** 保存到 `collected/` **Then** 可对照路线图成功标准 **And** 对外遵循 NFR1 / UPSTREAM 例外 + +## Tasks / Subtasks + +- [x] `audio_topology/COLLECT.md`：**对外分享与脱敏**、**HDMI 试播日志工件（FR10）** + +## Dev Agent Record + +### File List + +- `audio_topology/COLLECT.md` + +### Change Log + +- 2026-04-05：Story 4.2 完成。 diff --git a/_bmad-output/implementation-artifacts/5-1-reference-text-collaboration.md b/_bmad-output/implementation-artifacts/5-1-reference-text-collaboration.md new file mode 100644 index 0000000000..d60ac55d63 --- /dev/null +++ b/_bmad-output/implementation-artifacts/5-1-reference-text-collaboration.md @@ -0,0 +1,27 @@ +# Story 5.1: 无树时的 reference/ 文本协作 + +Status: done + +## Story + +As a **协作者**， +I want **仅依赖 `patches/.../reference/` 与补丁讨论 PR**， +So that **无完整 `kernel-src` 时仍能文本级协作**。 + +## Acceptance Criteria + +1. **Given** 未检出完整 Ubuntu 树 **When** 引用 `reference/` 与补丁说明 **Then** 能支撑审查式讨论 **And** 与 `DIFF_SUMMARY` 不矛盾 + +## Tasks / Subtasks + +- [x] `patches/ubuntu-hwe-6.17/README.md`：新增 **`reference/`（无完整树时的文本协作）**（FR11） + +## Dev Agent Record + +### File List + +- `patches/ubuntu-hwe-6.17/README.md` + +### Change Log + +- 2026-04-05：Story 5.1 完成。 diff --git a/_bmad-output/implementation-artifacts/5-2-dual-tree-diff-export.md b/_bmad-output/implementation-artifacts/5-2-dual-tree-diff-export.md new file mode 100644 index 0000000000..808074b22b --- /dev/null +++ b/_bmad-output/implementation-artifacts/5-2-dual-tree-diff-export.md @@ -0,0 +1,28 @@ +# Story 5.2: 双树齐备时的对照与导出 + +Status: done + +## Story + +As a **维护者**， +I want **在 `chromiumos_kernel/v5.15/` 与 `kernel-src/` 可用时运行预检/diff 导出脚本**， +So that **我能做 ChromiumOS ↔ Ubuntu 文件级对照**。 + +## Acceptance Criteria + +1. **Given** 双树满足前置 **When** 按 `INDEX` 与脚本执行 **Then** 产出可引用路径 **And** 可选记入 `WORK_PROGRESS` + +## Tasks / Subtasks + +- [x] `docs/meta/WORK_PROGRESS.md` §六：链到 **PREFLIGHT_NOTES**（与 `preflight-chromeos-ubuntu-diff.sh` 对齐）（FR12；与 FR15 共用） + +## Dev Agent Record + +### File List + +- `docs/meta/WORK_PROGRESS.md` +- `docs/meta/PREFLIGHT_NOTES.md`（新建） + +### Change Log + +- 2026-04-05：Story 5.2 完成。 diff --git a/_bmad-output/implementation-artifacts/5-3-dual-tree-path-entries.md b/_bmad-output/implementation-artifacts/5-3-dual-tree-path-entries.md new file mode 100644 index 0000000000..25a9da8d2c --- /dev/null +++ b/_bmad-output/implementation-artifacts/5-3-dual-tree-path-entries.md @@ -0,0 +1,27 @@ +# Story 5.3: 双树约定路径与入口说明 + +Status: done + +## Story + +As a **读者**， +I want **在固定文档中找到 ChromiumOS 5.15 与 `kernel-src` 的克隆与索引入口**， +So that **我能自行准备对照树**。 + +## Acceptance Criteria + +1. **Given** `CHROMEOS_KAISA_AUDIO_KERNEL_PATHS.md` 与 `KERNEL_SRC_LINUX_HWE617_HDMI_3.5MM_PATHS.md` **When** 从 `INDEX` 进入 **Then** 与 `WORK_PROGRESS` 克隆说明一致 + +## Tasks / Subtasks + +- [x] 本 Story 以既有 `docs/INDEX.md` 表与 `WORK_PROGRESS` §二、§三、**PREFLIGHT_NOTES** 互链为验收；无新增矛盾路径表述（FR13） + +## Dev Agent Record + +### File List + +- （核对）`docs/INDEX.md`、`docs/meta/WORK_PROGRESS.md`、`docs/meta/PREFLIGHT_NOTES.md` + +### Change Log + +- 2026-04-05：Story 5.3 核对完成；PREFLIGHT_NOTES 强化路径可发现性。 diff --git a/_bmad-output/implementation-artifacts/6-1-work-progress-stages-blocks.md b/_bmad-output/implementation-artifacts/6-1-work-progress-stages-blocks.md new file mode 100644 index 0000000000..f46f65212a --- /dev/null +++ b/_bmad-output/implementation-artifacts/6-1-work-progress-stages-blocks.md @@ -0,0 +1,27 @@ +# Story 6.1: WORK_PROGRESS 更新阶段与阻塞 + +Status: done + +## Story + +As a **维护者**， +I want **在 `WORK_PROGRESS` 中更新阶段结论、日期与阻塞项**， +So that **协作与未来的自己都能看见卡在哪**。 + +## Acceptance Criteria + +1. **Given** 阶段推进 **When** 编辑 `WORK_PROGRESS` **Then** 含日期、内核/补丁、阻塞 **And** 与路线图阶段可核对 + +## Tasks / Subtasks + +- [x] `WORK_PROGRESS` 已含 **Linux HDMI** 时间线段落；本批次增加 **验证上下文模板**、**预检** 链，强化可维护性（FR14） + +## Dev Agent Record + +### File List + +- `docs/meta/WORK_PROGRESS.md` + +### Change Log + +- 2026-04-05：Story 6.1 完成（与 FR5/FR6 小节协同）。 diff --git a/_bmad-output/implementation-artifacts/6-2-preflight-missing-trees.md b/_bmad-output/implementation-artifacts/6-2-preflight-missing-trees.md new file mode 100644 index 0000000000..2997f3b55c --- /dev/null +++ b/_bmad-output/implementation-artifacts/6-2-preflight-missing-trees.md @@ -0,0 +1,31 @@ +# Story 6.2: 预检可读（缺树/缺包） + +Status: done + +## Story + +As a **协作者**， +I want **从 `WORK_PROGRESS` 或预检脚本输出判断缺哪类树/包**， +So that **我能按清单补齐而非盲试**。 + +## Acceptance Criteria + +1. **Given** 运行 `preflight-chromeos-ubuntu-diff.sh` **When** 失败 **Then** 能映射缺 ChromiumOS / 缺 kernel-src **And** 与旅程 B 一致 + +## Tasks / Subtasks + +- [x] 新建 **`docs/meta/PREFLIGHT_NOTES.md`**（stderr 与补树入口对照表） +- [x] `WORK_PROGRESS` §六 链到 **PREFLIGHT_NOTES**（FR15） + +## Dev Agent Record + +### File List + +- `docs/meta/PREFLIGHT_NOTES.md` +- `docs/meta/WORK_PROGRESS.md` +- `docs/INDEX.md` +- `REPO_INDEX.md` + +### Change Log + +- 2026-04-05：Story 6.2 完成。 diff --git a/_bmad-output/implementation-artifacts/6-3-minimal-upstream-info-pack.md b/_bmad-output/implementation-artifacts/6-3-minimal-upstream-info-pack.md new file mode 100644 index 0000000000..d0ce505378 --- /dev/null +++ b/_bmad-output/implementation-artifacts/6-3-minimal-upstream-info-pack.md @@ -0,0 +1,27 @@ +# Story 6.3: 信息采集清单与最小信息包 + +Status: done + +## Story + +As a **只读使用者**， +I want **用 `UPSTREAM_SOF_Kaisa_HDMI_REPRO.md` 等清单组织最小信息包**， +So that **我不自动触发上游协同义务**。 + +## Acceptance Criteria + +1. **Given** 仅对外描述问题 **When** 按清单采集 **Then** 最小必要 **And** 不发 issue 非本仓库必达（FR16） + +## Tasks / Subtasks + +- [x] `docs/linux-hdmi/UPSTREAM_SOF_Kaisa_HDMI_REPRO.md`：增加 **最小信息包（FR16）** 说明 + +## Dev Agent Record + +### File List + +- `docs/linux-hdmi/UPSTREAM_SOF_Kaisa_HDMI_REPRO.md` + +### Change Log + +- 2026-04-05：Story 6.3 完成。 diff --git a/_bmad-output/implementation-artifacts/6-4-roadmap-work-progress-crossref.md b/_bmad-output/implementation-artifacts/6-4-roadmap-work-progress-crossref.md new file mode 100644 index 0000000000..2620d10eb3 --- /dev/null +++ b/_bmad-output/implementation-artifacts/6-4-roadmap-work-progress-crossref.md @@ -0,0 +1,29 @@ +# Story 6.4: 路线图与 WORK_PROGRESS 交叉引用 + +Status: done + +## Story + +As a **维护者**， +I want **在阶段或结论变更时更新路线图与 `WORK_PROGRESS` 的交叉引用**， +So that **两文档不矛盾**。 + +## Acceptance Criteria + +1. **Given** 阶段跳转 **When** 更新其一 **Then** 另一处同步或引用 **And** 不回归 FR2 + +## Tasks / Subtasks + +- [x] `docs/meta/DOCUMENTATION_ARCHITECTURE.md`：**FR17** 交叉更新说明 +- [x] `docs/linux-hdmi/Linux_HDMI_Audio_Roadmap.md` §五：链到 **DOCUMENTATION_ARCHITECTURE · FR17** + +## Dev Agent Record + +### File List + +- `docs/meta/DOCUMENTATION_ARCHITECTURE.md` +- `docs/linux-hdmi/Linux_HDMI_Audio_Roadmap.md` + +### Change Log + +- 2026-04-05：Story 6.4 完成。 diff --git a/_bmad-output/implementation-artifacts/7-1-upstream-gate-after-verify.md b/_bmad-output/implementation-artifacts/7-1-upstream-gate-after-verify.md new file mode 100644 index 0000000000..241f3fffbe --- /dev/null +++ b/_bmad-output/implementation-artifacts/7-1-upstream-gate-after-verify.md @@ -0,0 +1,27 @@ +# Story 7.1: 验证通过后的上游材料闸门 + +Status: done + +## Story + +As a **维护者**， +I want **仅在成功标准定义的验证结论已具备时，准备 `UPSTREAM_*` 类材料**， +So that **上游沟通不早于验证**。 + +## Acceptance Criteria + +1. **Given** 成功标准未满足 **When** 评估上游 issue **Then** 文档明确非并行里程碑 **And** 材料与 COLLECT/脱敏一致 + +## Tasks / Subtasks + +- [x] `docs/linux-hdmi/UPSTREAM_SOF_Kaisa_HDMI_REPRO.md`：文首 **闸门（FR21）** 与 FR16 小节协同 + +## Dev Agent Record + +### File List + +- `docs/linux-hdmi/UPSTREAM_SOF_Kaisa_HDMI_REPRO.md` + +### Change Log + +- 2026-04-05：Story 7.1 完成。 diff --git a/_bmad-output/implementation-artifacts/sprint-status.yaml b/_bmad-output/implementation-artifacts/sprint-status.yaml new file mode 100644 index 0000000000..1b2349ce59 --- /dev/null +++ b/_bmad-output/implementation-artifacts/sprint-status.yaml @@ -0,0 +1,58 @@ +# generated: 2026-04-05T14:30:00+08:00 +# last_updated: 2026-04-05T18:00:00+08:00 +# project: chromebox_10th_audio_driver +# project_key: NOKEY +# tracking_system: file-system +# story_location: "{project-root}/_bmad-output/implementation-artifacts" + +# STATUS DEFINITIONS: 见 BMad sprint-planning workflow + +generated: "2026-04-05T14:30:00+08:00" +last_updated: "2026-04-05T18:00:00+08:00" +project: chromebox_10th_audio_driver +project_key: NOKEY +tracking_system: file-system +story_location: "{project-root}/_bmad-output/implementation-artifacts" + +development_status: + epic-1: done + 1-1-root-readme-index-chain: done + 1-2-roadmap-vs-work-progress-boundary: done + 1-3-excluded-paths-and-triage: done + 1-4-index-sync-on-doc-change: done + 1-5-hwe-hdmi-scripts-discoverable: done + 1-6-linux-windows-doc-boundary: done + epic-1-retrospective: optional + + epic-2: done + 2-1-patch-dry-run-and-patch-env: done + 2-2-record-uname-kernel-src: done + 2-3-no-force-on-dry-run-failure: done + epic-2-retrospective: optional + + epic-3: done + 3-1-custom-kernel-install-rollback: done + 3-2-build-failure-repro-record: done + epic-3-retrospective: optional + + epic-4: done + 4-1-verify-path-and-verify-ok: done + 4-2-hdmi-logs-and-redaction: done + epic-4-retrospective: optional + + epic-5: done + 5-1-reference-text-collaboration: done + 5-2-dual-tree-diff-export: done + 5-3-dual-tree-path-entries: done + epic-5-retrospective: optional + + epic-6: done + 6-1-work-progress-stages-blocks: done + 6-2-preflight-missing-trees: done + 6-3-minimal-upstream-info-pack: done + 6-4-roadmap-work-progress-crossref: done + epic-6-retrospective: optional + + epic-7: done + 7-1-upstream-gate-after-verify: done + epic-7-retrospective: optional diff --git a/_bmad-output/planning-artifacts/architecture.md b/_bmad-output/planning-artifacts/architecture.md new file mode 100644 index 0000000000..a4f2c4fe5e --- /dev/null +++ b/_bmad-output/planning-artifacts/architecture.md @@ -0,0 +1,479 @@ +--- +stepsCompleted: + - 1 + - 2 + - 3 + - 4 + - 5 + - 6 + - 7 + - 8 +inputDocuments: + - _bmad-output/planning-artifacts/prd.md + - _bmad-output/project-context.md + - _bmad-output/problem-solution-2026-04-04-linux-hdmi-kaisa.md + - docs/INDEX.md + - docs/linux-hdmi/Linux_HDMI_Audio_Roadmap.md +workflowType: architecture +lastStep: 8 +status: complete +completedAt: '2026-04-05T12:00:00+08:00' +project_name: chromebox_10th_audio_driver +user_name: Jack +date: '2026-04-05T12:26:51+08:00' +--- + +# Architecture Decision Document + +_This document builds collaboratively through step-by-step discovery. Sections are appended as we work through each architectural decision together._ + +## Project Context Analysis + +### Requirements Overview + +**Functional Requirements:** +PRD 定义 **FR1–FR21**，覆盖：单一文档入口与路线图 / `WORK_PROGRESS` 分工（FR1–FR3）；Ubuntu HWE 源码树上补丁预检与应用、禁止强制 `patch`（FR4–FR6）；自编内核安装/回退与构建失败可复现记录（FR7–FR8）；文档化验证路径与 HDMI 相关日志工件（FR9–FR10）；`reference/` 与双树对照流程（FR11–FR13）；进度与预检透明（FR14–FR17）；索引维护与脚本可发现（FR18–FR19）；Linux 与 Windows 文档分界（FR20）；**验证结论具备后**再准备上游材料（FR21）。 +**架构含义**：系统边界是「仓库内可执行的文档 + 脚本 + 补丁」，不是单一运行时服务；一致性依赖 **版本钉扎** 与 **artifact 路径约定**。 + +**Non-Functional Requirements:** +**NFR1–NFR2** 约束对外分享前的脱敏与密钥；**NFR3–NFR4** 约束体例与索引变更；**NFR5–NFR6** 约束验证基线与构建/资源事实记录；**NFR7** 约束版本库内摘录的来源与许可。 +**架构含义**：安全与合规主要体现在 **日志与摘录治理**，而非网络边界。 + +**Scale & Complexity:** +- **主领域**：棕地 **Linux 内核 / SOF / 文档与工具链**（非典型 Web 全栈）。 +- **复杂度**：部署规模 **低**；**领域与可复现性**为主要风险面。 +- **逻辑组件（约 5 类）**：文档与索引；补丁与 `kernel-src` 构建；验证与采集；对照与 diff 导出；协作元数据（`WORK_PROGRESS` / PRD）。 + +### Technical Constraints & Dependencies + +- **基线环境**：文档以 **Ubuntu 24.04 + linux-hwe-6.17** 为验证叙述主线；其它环境不自动满足 FR9（见 PRD / NFR5）。 +- **大目录**：`kernel-src/`、`chromiumos_kernel/v5.15/` 常不提交，架构上依赖 **路径约定 + README/笔记**，而非「仓库内必有完整树」。 +- **上游顺序**：路线图阶段 4 / FR21：**验证之后再考虑**上游协同，架构上**不得**把上游 issue 当作并行前置依赖。 + +### Cross-Cutting Concerns Identified + +- **内核与源码树版本一致**（`uname -r` ↔ `kernel-src` ↔ 补丁对象）。 +- **可复现性**（脚本退出语义、`VERIFY_OK`、构建日志位置）。 +- **隐私与摘录**（dmesg、上游清单、许可证）。 +- **文档导航不碎裂**（INDEX / REPO_INDEX / 路线图 / `WORK_PROGRESS` 交叉引用）。 + +### Failure Modes（约束被违反时） + +| 情形 | 后果 | 架构上应坚持的约束 | +|------|------|---------------------| +| **`kernel-src` 与运行内核不一致**仍打补丁/宣称验证 | FR4–FR6、NFR5 失效；结论不可引用 | 任何「已验证」叙述必须带 **`uname -r` + 树来源** | +| **未更新 INDEX** 即移动主题文档 | FR18、NFR4 失效；协作者迷路 | 结构变更与索引**同一变更集** | +| **未脱敏即贴全量 dmesg 到公开 issue** | NFR1 失效 | 对外主体以 **`UPSTREAM_*` / COLLECT** 为准 | + +### Explicit Non-Goals（本仓库架构不承担） + +- **无** 7×24 在线服务、**无** 多租户、**无** 统一 API 网关。 +- **无** 强制「仓库内必含完整 `chromiumos_kernel` / `kernel-src`」——架构上为 **可选外置树 + 文档钉扎路径**。 +- **无** 将 **PipeWire / CRAS** 作为交付内核——用户态栈仅作**现象分流**引用（与 PRD 一致）。 + +### FR → 逻辑组件（追溯草图） + +| 逻辑组件 | 主要 FR | +|----------|---------| +| **文档与入口** | FR1–FR3, FR18–FR20 | +| **补丁与源码树** | FR4–FR6, FR11–FR13 | +| **构建 / 安装 / 恢复** | FR7–FR8 | +| **验证与日志** | FR9–FR10 | +| **协作与进度** | FR14–FR17 | +| **上游（条件）** | FR21 | + +（正式可追溯矩阵可在 **Epic/Story** 阶段细化。） + +### Human–Machine Boundaries + +| 层级 | 责任主体 | 架构含义 | +|------|----------|----------| +| **策略与范围** | PRD / 路线图 | 不写进内核；**冲突以 PRD 为准** | +| **可执行步骤** | Bash 脚本 + `PATCH=` | 代理/人必须按**同一入口**调用，避免「口头路径」 | +| **内核行为** | 上游 + 本仓库补丁 | **不**假装能替代固件拓扑；**对照**用 ChromiumOS 树 | +| **事实记录** | `WORK_PROGRESS` + `collected/` | **单一事实源**与路线图阶段对齐 | + +### Artifact Flow（简化） + +```text +docs（意图） → PATCH/dry-run → kernel-src 树 → debian/rules 构建 → 安装/回退 + ↓ + verify-* / 采集 → 日志与 collected → 对照 reference/ 或双树 diff + ↓ + （条件）UPSTREAM 材料 ← 仅当 FR21 前提满足 +``` + +架构决策应**不**在这条链外再发明「隐式步骤」。 + +### ADR 衔接（若后续引入） + +若仓库内增加 **ADR（Architecture Decision Record）**，建议 **一条 ADR 对应一类可重复冲突**，并 **引用**本文件与 PRD；**避免** ADR 与 PRD 形成第二套需求源。 + +### Compatibility Matrix（声明级） + +- **主线**：Ubuntu **24.04 (Noble)** + **linux-hwe-6.17** 文档与验证叙述。 +- **其它 Ubuntu / 发行版**：**不**列入默认支持矩阵；个案仅记录在 **`WORK_PROGRESS`**。 + +### Single-Maintainer & Precedence + +- **文档与脚本分叉**风险：依赖 **`WORK_PROGRESS` 日期 + 路线图阶段** 可读（与 PRD Scoping 一致）。 +- **本文档与 PRD**：若冲突，**以 PRD 为准**；本文服务于 **实现一致性** 与代理可重复行为，而非替代需求定义。 + +## Starter Template Evaluation + +### Primary Technology Domain + +本仓库为 **棕地 Linux 内核 / SOF 相关文档与补丁工程**，**非**典型 Web 应用；不适用 Next.js/Vite 等应用脚手架。所谓「Starter」指：**工程基底与可重复初始化契约**（目录约定、`kernel-src` 对齐、`PATCH=` 流程、验证与采集路径），而非生成新运行时服务。 + +### Starter Options Considered + +| 方向 | 说明 | 结论 | +|------|------|------| +| Web 全栈脚手架 | 与 PRD 主域不符 | **不采纳** | +| 纯文档 + Bash + 既有补丁/构建入口 | 与当前仓库与 FR4–FR8 一致 | **默认采纳（主基底）** | +| 可选 Python 辅助 | 仅当脚本/预检复杂度显著增加时，从同一 Bash 入口调用 | **条件采纳** | +| Devcontainer | 可选降低环境漂移说明成本；**不**替代 Ubuntu+HWE 基线验证叙述 | **可选旁路** | +| Nix/Flake | 可锁工具链，但与文档主线并行成本高 | **默认不列为架构主线** | +| 最小 CI | 可跑无秘密的校验/文档检查；**不**等同于 FR9 验证 | **可选** | + +### Selected Starter: 棕地仓库 + Ubuntu HWE / `kernel-src` / 补丁工作流（主叙述） + +**Rationale for Selection:** +在对比矩阵与多角色讨论下，选择 **最少新依赖、与 PRD 对齐、人机边界清晰** 的基底。从第一性原理，本仓库「初始化」应落实为 **版本钉扎与路径契约**，而非新应用模板。 + +**Initialization（叙述级「命令」语义，非单一上游 CLI）：** + +1. 克隆本仓库；按 `README` / 路线图将 **`kernel-src`**（或等价路径）对齐到 **`uname -r`** 与文档钉扎的 HWE 版本。 +2. 使用仓库内 **同一入口脚本** 进行 `PATCH=` 预检与应用（禁止未文档化的「口头路径」）。 +3. 按 PRD 执行构建、安装/回退与 **`verify-*`/采集**；将 **`uname -r`、树来源、日志路径** 写入 `WORK_PROGRESS` 或约定工件位置。 +4. （可选）在复杂度需要时引入 **Python 子脚本** 或 **CI**，但必须 **不改变** 下文的入口与验证契约。 + +**目标机与验证边界（协作澄清）：** + +- **本机即目标机**：PRD 所述验证与采集，**默认在唯一目标主机（当前使用中的机器）上执行**；不要求单独的「实验室金机」叙事。`uname -r`、`kernel-src` 与补丁对象的一致性均针对该主机。 +- **术语区分**：**「本机验证」**（满足 FR9 的路径与工件）与 **「CI / 预检门禁」**（若存在）不得混称为「已验证」；**CI 通过不替代** 在本机执行的验证与日志约定。 +- **入口唯一性**：可选 Python 或 CI 仅能为 **子路径**；**README 与文档声明的 Bash/文档入口** 仍为权威；辅助脚本不得自称唯一入口。 + +**Architectural Decisions Provided by This「Starter」:** + +- **语言与运行时**：默认 **Bash + 文档**；Python/Node **仅作可选辅助**，且不得成为唯一入口。 +- **构建与验证**：以 **Ubuntu 24.04 + linux-hwe** 文档主线为准；其它环境不自动满足 FR9。 +- **大目录策略**：`kernel-src` / 对照树 **外置或可选**；架构依赖 **路径约定与记录**，而非「克隆即完整树」。 +- **测试与质量**：**验证脚本 + artifact**；CI 若存在，定位为 **预检/补充**，**不**替代本机验证。 +- **协作**：**INDEX、`WORK_PROGRESS`、路线图** 为导航与事实主轴；Starter **不**引入第二套需求源。 +- **读者分层**：主线只写 **初始化契约**；Devcontainer、Nix、CI 等写入 **旁注**，并标明 **不替代** Ubuntu+HWE 与本机验证。 + +**Note:** 实现阶段的首个故事应是：**在文档与脚本中显式固定上述初始化与验证契约**（含 `kernel-src` 对齐检查与日志位置），再迭代可选工具。 + +## Core Architectural Decisions + +### Decision Priority Analysis + +**Critical（阻塞实现一致性）：** 工件与目录契约；补丁与 `kernel-src` 流程。 +**Important（显著塑造协作方式）：** 验证与可复现；文档与协作入口。 +**Deferred / 门槛驱动：** 可选 Python 辅助、可选 CI——仅在有明确痛点时引入，且不得破坏入口与验证契约（与 Starter Template Evaluation 一致）。 + +### 1. 工件与目录契约 + +| 决策 | 内容 | 依据 | +|------|------|------| +| 补丁落位 | **`patches/ubuntu-hwe-6.17/`** 为当前 HWE 线钉扎目录；若未来换内核线，**新建** `patches/<新线>/`，**不**在旧目录混用不同 `uname -r` 语义。 | PRD FR4–FR6；现有补丁布局 | +| 采集与事实工件 | 采集类 Markdown **优先**落在既有约定路径（如 **`audio_topology/collected/`**），遵循 **`audio_topology/COLLECT.md`**；避免在仓库根再建与现有并行的第二套 collected。 | FR10；COLLECT 体例 | +| 验证输出语义 | **`VERIFY_OK`**、跳过 HDMI 测试（如 **`RUN_HDMI_TEST=0`**）等以 **`patches/ubuntu-hwe-6.17/VERIFY_PATCHES.md`** 与 **`scripts/verify-*.sh`** 为准；架构层**不**新增隐式成功条件。 | project-context；验证脚本 | + +### 2. 补丁与源码树流程 + +| 决策 | 内容 | 依据 | +|------|------|------| +| 应用方式 | 每次 **`apply`** 使用 **`PATCH=`** 指向**单文件**；顺序 **0001 → 0002**；**0003** 与 0001/2 **独立**（与 `patches/ubuntu-hwe-6.17/README.md` 一致）。 | FR4–FR6 | +| 树与内核 | **`kernel-src/`** 与运行内核 **`uname -r`** 一致后方可宣称补丁相关结论；**`chromiumos_kernel/v5.15/`** 为**对照基准**，大体积 **不**强制入库。 | Step 2；`kernel-src/README.md` | +| 新补丁前 | 设计新补丁前应对照 **ChromeOS 5.15 ↔ 当前 HWE** 与 **`patches/ubuntu-hwe-6.17/DIFF_SUMMARY.txt`**，避免重复已否决路径。 | project-context | + +### 3. 验证与可复现 + +| 决策 | 内容 | 依据 | +|------|------|------| +| 验证权威 | **本机即目标机**：FR9 所指「已按文档验证」= 在 **当前目标机** 上按 **`VERIFY_PATCHES` + `verify-*`** 执行并保留约定工件；**不**与 CI 绿标混称「已验证」。 | Starter 澄清；PRD FR9 | +| CI（若存在） | 仅作 **预检/门禁**（无秘密的脚本或文档检查）；**不**替代本机验证。 | NFR5–NFR6；Starter | +| 可复现记录 | 构建失败、回退等事实记在 **`docs/meta/WORK_PROGRESS.md`** 与各 **OPERATION** 约定位置，不另造影子日志体系。 | FR7–FR8 | + +### 4. 文档与协作 + +| 决策 | 内容 | 依据 | +|------|------|------| +| 入口 | **根目录仅 `README.md`**；主题入口 **`docs/INDEX.md`**，全路径 **`REPO_INDEX.md`**；`docs/` 结构变更须 **同变更集** 更新索引。 | FR1、FR18–FR19 | +| 进度与阶段 | Linux HDMI 以 **`docs/linux-hdmi/Linux_HDMI_Audio_Roadmap.md`** 为准；阶段结论与换机信息同步 **`docs/meta/WORK_PROGRESS.md`**。 | FR2–FR3 | +| 体例 | 改写与语言约定以 **`docs/meta/DOCUMENTATION_STYLE.md`** 为准。 | NFR3–NFR4 | + +### 5. 可选辅助工具（门槛） + +| 决策 | 内容 | 依据 | +|------|------|------| +| 新语言/脚手架 | **不**在仓库根引入 Node/Python **应用式**脚手架。 | Starter；project-context | +| Python | 仅当 Bash 难以维护时，增加 **由 Bash 调用的** Python 辅助；**不**把 Python 当作唯一入口。 | Starter | +| CI | **可选**；引入时须在文档中标明 **「预检 ≠ FR9 本机验证」**，且不依赖密钥。 | Starter | + +### Decision Impact Analysis + +**实现顺序建议：** +1）保持 **`PATCH=` / `kernel-src` / `verify-*`** 单一叙事与脚本退出语义；2）任何新目录或新脚本先补 **INDEX / REPO_INDEX** 与 **`WORK_PROGRESS`**；3）再评估 Python/CI。 + +**跨组件依赖：** +文档入口 → 脚本可发现性（FR18–FR19）；补丁流程 → 验证工件与 `WORK_PROGRESS`；三者缺一则 FR9 与协作透明度链条断裂。 + +## Implementation Patterns & Consistency Rules + +### Pattern Categories Defined + +**Critical conflict points（多代理易分歧处）：** +脚本命名与放置、`PATCH=`/`kernel-src` 路径叙事、`VERIFY_OK` 语义、文档与索引同事务、采集文件命名、失败时日志形态。 + +**不适用（本仓库非 Web/API 服务）：** 数据库表名、REST 路由、JSON 字段风格等——**不在此重复约束**；若未来出现，另开 ADR。 + +### Naming Patterns + +**Shell 脚本（`scripts/`）：** + +- **小写字母 + 连字符**；与现有 **`verify-*`**、**`ubuntu-hwe-*`** 前缀体系一致，**不**引入第三套动词/前缀（如随意新建 `tools/run.sh` 作为并列权威入口）。 +- 新脚本名称应 **可扫一眼知用途**（验证 / 构建 / 辅助），并在文件头或 `--help` 写明**工作目录**（通常为仓库根）。 + +**补丁与单文件应用：** + +- 叙述 **`PATCH=`** 时，**权威** 为 **`patches/ubuntu-hwe-6.17/README.md`**（及同目录 README 体系）；**单文件、顺序 0001→0002、0003 独立** 的语义不得在不同文档中互相矛盾。 + +**文档与采集文件：** + +- 采集类 Markdown 命名须 **可排序、可检索**，遵循 **`audio_topology/COLLECT.md`**（及同类体例）。 +- 新主题文档避免「孤岛文件名」；与 **INDEX / REPO_INDEX** 登记名一致或可追溯。 + +### Structure Patterns + +**目录与权威入口：** + +- **`kernel-src/`** 的工作目录与构建叙述 **以 `kernel-src/README.md` 为准**；不在随机笔记中定义第二套「默认路径」。 +- 新可执行能力 **优先** 落在 **`scripts/`**；避免在仓库根散落多个未登记的 `.sh` 作为「正式入口」。 + +**文档变更与索引：** + +- 变更 **`docs/`** 结构、新增或移动 **重要 OPERATION / 路线图级** 文档时，**同一变更集** 更新 **`docs/INDEX.md` 和/或 `REPO_INDEX.md`**（与 Core Architectural Decisions 一致，升为模式级）。 + +### Format Patterns + +**验证成功语义：** + +- **`VERIFY_OK`** 仅用于 **仓库已约定的验证脚本** 成功路径；其它语言或工具 **不得** 打印同名字符串冒充通过。 + +**失败与调试输出（Bash）：** + +- 失败时建议在 **stderr** 输出 **至少一行可 `grep` 的前缀**（含脚本名或仓库约定前缀），便于写入 **`WORK_PROGRESS`** 与复现记录。 +- **对外** 粘贴日志仍遵守 **NFR1 脱敏**；本机调试与内部记录不受「前缀」约束冲突。 + +### Process Patterns + +**错误与退出：** + +- 脚本以现有惯例为准（如 **`set -e`**）；**退出码** 与 **`VERIFY_OK`** 的约定以 **`VERIFY_PATCHES.md`** 与对应 **`verify-*.sh`** 为准，**不**在架构层新增隐式成功条件。 + +**协作流程：** + +- **最小必要 diff**；不顺带重构无关文件。大目录遵守 **`.gitignore`**，不提交整树。 + +### Enforcement Guidelines + +**All AI Agents MUST:** + +- 新增/改名 **`scripts/`** 下脚本时，**对齐现有命名风格** 并更新 **`docs/INDEX.md`**（若脚本已列入索引表）或相关 OPERATION。 +- 任何 **`PATCH=`、`kernel-src`、验证流程** 的改写，**同步** **`patches/.../README`**、**`VERIFY_PATCHES.md`** 或 **`kernel-src/README.md`** 之一，避免「口头路径」。 +- 不动 **`docs/`** 导航结构，或 **同事务** 更新 **INDEX / REPO_INDEX**。 + +**Pattern enforcement：** 代码审查与自检时对照本节 **+ `_bmad-output/project-context.md`**；冲突以 **PRD** 与 **Core Architectural Decisions** 为准。 + +### Pattern Examples + +**Good examples:** + +- 新验证脚本：`scripts/verify--.sh`，并在 `VERIFY_PATCHES.md` 或 `docs/INDEX.md` 脚本表中登记。 +- 文档：新增 `docs/linux-hdmi/OPERATION_Foo.md` 且 **同一 MR** 修改 `docs/INDEX.md` 链接。 + +**Anti-patterns:** + +- 在聊天或 issue 里写「你本机 `cd` 到某路径再 patch」，但 **仓库内无任何 README/脚本** 对应。 +- 非约定脚本在 stdout/stderr 打印 **`VERIFY_OK`**。 +- 移动 `docs/` 下文件却 **不** 更新 INDEX，导致代理与用户迷路。 + +## Project Structure & Boundaries + +### Complete Project Directory Structure（逻辑视图） + +仓库以 **文档 + 脚本 + 补丁 + 可选大目录** 为主；下列为 **协作常用边界**（非逐文件穷举）。 + +```text +chromebox_10th_audio_driver/ +├── README.md # 唯一根 README；总入口 +├── REPO_INDEX.md # 全路径速查 +├── docs/ +│ ├── INDEX.md # docs 主题索引（必维护） +│ ├── linux-hdmi/ # HDMI 路线图、对照、trace、上游材料 +│ ├── kernel-build/ # 自编内核安装、深度 diff 操作 +│ ├── meta/ # WORK_PROGRESS、双系统、体例引用 +│ └── windows/ # Windows 音频（与 Linux 文档分界） +├── audio_topology/ # 拓扑分析、采集脚本、修复计划 +│ └── collected/ # 真机采集/trace 工件（命名遵循 COLLECT.md） +├── patches/ +│ └── ubuntu-hwe-6.17/ # 钉扎 HWE 线补丁；PATCH= 单文件应用 +├── scripts/ # Bash 入口；verify-* / ubuntu-hwe-* / diff 工具链 +├── kernel-src/ # linux-hwe 解压与构建（常 .gitignore；说明见 README） +├── chromiumos_kernel/v5.15/ # 对照树（可选克隆；索引见 docs/linux-hdmi/…） +├── _bmad-output/ +│ └── planning-artifacts/ # PRD、architecture.md、project-context 等 +└── .cursor/ # 编辑器技能（非业务交付物） +``` + +**可选/忽略提交：** `kernel-src/`、`chromiumos_kernel/` 整树；**业务事实** 以 **README + WORK_PROGRESS + 脚本参数** 钉扎。 + +### Navigation Anchors（导航锚点） + +新协作者优先沿下列 **固定锚点** 定位可执行路径（与 `README` / `docs/INDEX.md` 一致）： + +| 目的 | 锚点路径 | +|------|----------| +| 补丁与 `PATCH=` 语义 | `patches/ubuntu-hwe-6.17/README.md` | +| 验证流程与 `VERIFY_OK` | `patches/ubuntu-hwe-6.17/VERIFY_PATCHES.md`、`scripts/verify-ubuntu-hwe617-patches-runtime.sh` | +| 源码树与 `uname -r` 对齐 | `kernel-src/README.md` | +| 主题文档总表 | `docs/INDEX.md` | +| 进度与换机事实 | `docs/meta/WORK_PROGRESS.md` | + +**目录分工（避免混淆）：** **`audio_topology/`** — 拓扑脚本、采集规范与 `collected/` 原始工件；**`docs/linux-hdmi/`** — HDMI 路线图、重分析与对照结论文档。二者交叉引用，**不**互相当作对方唯一入口。 + +**构建/安装故事：** **`scripts/ubuntu-hwe-617-build.sh`** 与 **`docs/kernel-build/`** 在叙述上视为 **同一工作流的脚本侧与文档侧**（索引与 OPERATION 互链）。 + +### Structure Failure Modes & Guards（结构相关失效与防护） + +- **索引漂移**：`docs/` 移动或新增 OPERATION → **同一变更集** 更新 `docs/INDEX.md` / `REPO_INDEX.md`（见 Implementation Patterns）。 +- **树不一致**：补丁/验证叙事须同时锚定 **`patches/.../README.md`**、**`kernel-src/README.md`** 与 **`uname -r`**。 +- **双叙事冲突**：`audio_topology/` 与 `docs/linux-hdmi/` **分工**见上表；阶段真相以 **`docs/meta/WORK_PROGRESS.md`** 与路线图为准。 +- **脚本不可发现**：新脚本须进入 **INDEX 或 REPO_INDEX 脚本表**（若适用）。 +- **采集不可检索**：`audio_topology/collected/` 命名遵循 **`audio_topology/COLLECT.md`**。 +- **多内核线（未来）**：新 HWE 线 → **`patches/<新线>/`** 独立 README/验证说明，**不**与旧线混用补丁编号语义。 +- **规划 vs 需求**：**`_bmad-output/`** 为规划契约；需求冲突 **以 PRD 为准**。 + +### Architectural Boundaries + +| 边界 | 含义 | +|------|------| +| **文档 vs 可执行** | 意图与步骤在 **`docs/`**；**同一操作** 的入口在 **`scripts/`** 与 **`patches/.../README`**，不在聊天里另起一套路径。 | +| **补丁 vs 运行内核** | 补丁只针对与 **`uname -r`** 对齐的 **`kernel-src`**；对照在 **`chromiumos_kernel`**，**不**混为「运行树」。 | +| **Linux vs Windows** | 分目录 **`docs/linux-hdmi`** vs **`docs/windows`**；共享硬件事实时 **交叉引用**，不合并成单一含糊文档。 | +| **BMad 生成物** | **`_bmad-output/`** 为规划/契约；**不**替代 PRD 作为需求源。 | + +### Requirements to Structure Mapping（FR 簇 → 位置） + +| FR 范围 | 主要落点 | +|---------|----------| +| FR1–FR3 入口与进度 | `README.md`、`docs/INDEX.md`、`docs/meta/WORK_PROGRESS.md`、`docs/linux-hdmi/Linux_HDMI_Audio_Roadmap.md` | +| FR4–FR6 补丁 | `patches/ubuntu-hwe-6.17/`、`VERIFY_PATCHES.md`、`scripts/verify-*.sh` | +| FR7–FR8 构建/安装 | `kernel-src/README.md`、`docs/kernel-build/`、`scripts/ubuntu-hwe-617-build.sh` | +| FR9–FR10 验证与采集 | `scripts/verify-*.sh`、`audio_topology/collected/`、`audio_topology/COLLECT.md` | +| FR11–FR13 对照 | `chromiumos_kernel/`、`docs/linux-hdmi/*PATHS*.md`、`scripts/*chromeos*diff*.sh` | +| FR14–FR17 透明协作 | `docs/meta/WORK_PROGRESS.md`、路线图、补丁 README | +| FR18–FR19 索引与脚本可发现 | `docs/INDEX.md`、`REPO_INDEX.md` | +| FR20 平台分界 | `docs/linux-hdmi/` vs `docs/windows/` | +| FR21 上游（条件） | `docs/linux-hdmi/UPSTREAM_*` 等（仅验证后） | + +### Integration Points（与 Artifact Flow 一致） + +- **内部：** `docs` → `PATCH=` / `kernel-src` → `scripts` 构建与 `verify-*` → `collected` / `WORK_PROGRESS`。 +- **外部：** 上游内核/固件/发行版包 **不**入库；通过 **文档链接与版本号** 钉扎。 + +### File Organization Patterns（摘要） + +- **配置：** 无应用级 `package.json` 主线；宿主依赖在 **OPERATION** 与 **`kernel-src/README.md`** 中叙述。 +- **「源码」：** 内核改动以 **`patches/*.patch`** 与 **`kernel-src/`** 工作副本表达。 +- **测试：** **无** 单元测试树；**验证** = `verify-*` + 文档化手工步骤（FR9）。 + +### Development Workflow Integration + +- **日常：** 读 **`README` → INDEX → 路线图**；改补丁则 **`patches/` + kernel-src 对齐**；验证则 **`verify-*` + WORK_PROGRESS**。 +- **构建：** `scripts/ubuntu-hwe-617-build.sh` 与 `kernel-src/README.md` 对齐。 +- **部署：** **deb 安装/回退** 由 **`docs/kernel-build/`** 与构建脚本叙述；**无**容器/多机部署主线。 + +## Architecture Validation Results + +### Coherence Validation + +**Decision Compatibility：** Starter（Bash + 文档入口）、Core Decisions（补丁 / 本机验证 / 索引）、Implementation Patterns（`VERIFY_OK`、INDEX 同事务）、Project Structure（Navigation Anchors 与失效防护）**相互一致**；未混入与 PRD 冲突的第二套 Web/应用栈。 + +**Pattern Consistency：** 命名、路径权威与「本机验证 vs CI」边界在 **Patterns** 与 **Structure Failure Modes** 中可交叉引用，无矛盾条款。 + +**Structure Alignment：** 逻辑目录树与 **FR→位置映射**、**Artifact Flow** 对齐；大目录外置与锚点表支持 Step 2 中的失败模式约束。 + +### Requirements Coverage Validation + +**Functional Requirements：** FR1–FR21 均在 **Project Context Analysis**、**Core Architectural Decisions** 或 **Requirements to Structure Mapping** 中有落点；FR21 保持为 **验证通过后的条件路径**（与 PRD 一致）。 + +**Non-Functional Requirements：** NFR1–NFR7 通过 **脱敏、索引、WORK_PROGRESS、可复现记录、摘录与许可** 等叙述覆盖；未过度承诺性能、多租户或在线 SLA。 + +### Implementation Readiness Validation + +**Decision & pattern completeness：** 关键决策与代理可执行规则已写清；**无** 要求钉死具体内核次版本号（由 `uname -r` + 文档钉扎承担）。 + +**Structure completeness：** 提供 **逻辑树 + Navigation Anchors**，避免与 `REPO_INDEX` 逐文件重复；集成点与 **Development Workflow** 已摘要。 + +**诚实范围：** 本仓库 **无** 可替代 FR9 的仓库级自动化测试套件；FR9 仍以 **本机 `verify-*` + 约定工件 + `WORK_PROGRESS`** 为准（与 Starter、Core Decisions 一致）。 + +### Gap Analysis Results + +| 优先级 | 说明 | +|--------|------| +| **非阻塞** | Epic/Story 级可追溯矩阵可在后续规划细化。 | +| **非阻塞** | 若引入 **第二条 `patches/<内核线>/`**，须为新线增加 **独立 README 与验证叙述**（Structure 与下表已预警）。 | +| **可选** | 可选 CI 仅作预检；**不**在本文扩写具体 CI 语法（保持与 PRD 一致）。 | + +### Party Mode & Review Supplements（Step 7） + +- **变更防呆：** 与补丁或本机验证相关的变更，应能 **指回** `patches/.../README` 或 `VERIFY_PATCHES.md`，或本文 **Navigation Anchors** 中的等价路径。 +- **双索引分流：** 默认 **`README` → `docs/INDEX.md`**；已知文件名或全路径速查时 **`REPO_INDEX.md`**。 +- **后续内核线：** 新 HWE/补丁线 → **`patches/<新线>/`** + **独立验证说明**；不与旧线混用补丁编号语义。 + +### Architecture Completeness Checklist + +**Requirements & constraints** + +- [x] 项目上下文、规模、技术约束与跨切面关切已分析 +- [x] 失败模式与非目标已声明 + +**Decisions & patterns** + +- [x] Starter 与核心决策已文档化 +- [x] 实现模式与反模式已给出 +- [x] 项目结构与边界、FR 映射已建立 + +**Validation** + +- [x] 一致性、需求覆盖与实现就绪已复核 +- [x] 已知缺口已标注为非阻塞或后续增强 + +### Architecture Readiness Assessment + +**Overall status：** **READY** — 可作为代理与维护者的 **单一技术叙事** 与 PRD 对齐实现；冲突时 **以 PRD 为准**。 + +**Confidence level：** **高**（棕地文档 + 脚本 + 补丁；约束闭合，未虚构运行时服务）。 + +**Strengths：** 路径锚点清晰；验证与索引规则可执行；与 `project-context.md` 可并列使用。 + +**Areas for future enhancement：** 第二条补丁线的独立验证包；可选 CI 的文档化（若引入）。 + +### Implementation Handoff + +**AI agent guidelines：** + +- 遵循 **`_bmad-output/project-context.md`** 与本 **`architecture.md`**；变更 **最小必要**，并维护 **INDEX / REPO_INDEX**。 +- 补丁与验证：**`PATCH=`**、**`kernel-src` 对齐**、**`verify-*`** 与 **`VERIFY_OK`** 语义以仓库内 **README / VERIFY_PATCHES** 为准。 + +**First implementation priority（与 Starter Note 一致）：** 在文档与脚本中 **显式固定** 初始化与验证契约（含 `kernel-src` 与 `uname -r` 检查、日志与 `WORK_PROGRESS` 路径），再迭代可选工具或 CI。 + +--- + +## Architecture Workflow Completion + +**BMad Create Architecture** 流程已在本仓库 **`architecture.md`** 中跑通 **Step 1–8**（`stepsCompleted` 与 `status` 见文首 YAML）。后续实现与拆故事请以 **PRD** 与 **`docs/linux-hdmi/Linux_HDMI_Audio_Roadmap.md`** 为调度主线。 diff --git a/_bmad-output/planning-artifacts/epics.md b/_bmad-output/planning-artifacts/epics.md new file mode 100644 index 0000000000..486164580c --- /dev/null +++ b/_bmad-output/planning-artifacts/epics.md @@ -0,0 +1,617 @@ +--- +stepsCompleted: + - 1 + - 2 + - 3 + - 4 +workflowType: epics-and-stories +status: complete +completedAt: '2026-04-05T14:00:00+08:00' +inputDocuments: + - _bmad-output/planning-artifacts/prd.md + - _bmad-output/planning-artifacts/architecture.md + - _bmad-output/project-context.md +--- + +# chromebox_10th_audio_driver - Epic Breakdown + +## Overview + +This document provides the complete epic and story breakdown for chromebox_10th_audio_driver, decomposing the requirements from the PRD, UX Design if it exists, and Architecture requirements into implementable stories. + +## Requirements Inventory + +### Functional Requirements + +FR1: **维护者或协作者**能够仅通过 **`README` → 索引 → 路线图 / `WORK_PROGRESS`** 定位当前工作阶段与下一步阅读顺序。 + +FR2: **读者**能够区分 **路线图**（阶段顺序）与 **`WORK_PROGRESS`**（事实与换机状态）的职责边界。 + +FR3: **读者**能够查阅 **Linux HDMI 已排除或低期望方向**，并在**现象分流**时区分「已知不成立路径」与「需继续对照内核/用户态」的路径（引用既有分析文档）。 + +FR4: **维护者**能够将仓库内 **指定补丁** 应用于**与运行内核版本一致**的 **Ubuntu HWE 源码树**，并在应用前获得 **`patch` 预检结果**（成功/失败）。 + +FR5: **维护者**能够记录当前验证所对应的 **`uname -r`**、内核包来源与 **`kernel-src`** 树状态（含「未建源树」声明）。 + +FR6: **维护者**在 **`patch` 预检失败**时**不**以强制覆盖方式掩盖失败，而转入核对或手工合并。 + +FR7: **维护者**能够按照 **`OPERATION_Install_CustomKernel_Ubuntu_HWE617.md`** 等权威说明完成 **自编内核的安装与回退**；**安装范围**（含 **unsigned、模块包完整性、相关固件/无线等**）以该 OPERATION 为准，**不**在 PRD 内逐包枚举。 + +FR8: **维护者**在 **完整内核构建**失败时，能够记录 **并行度/日志位置** 等可复现信息，以便重试或协作排查。 + +FR9: **维护者**能够运行 **`VERIFY_PATCHES.md` 或文档当前版本**所钉扎的验证路径（与补丁版本、内核线一致），并得到 **通过/失败** 的可判读结果。 + +FR10: **维护者**能够保存 **HDMI 相关试播** 的 **内核日志工件**，并使其可与 **路线图成功标准** 对照；**对外分享前**可按 **`audio_topology/COLLECT.md`** 等采集说明做**脱敏**（细则见 **Non-Functional Requirements**）。 + +FR11: **维护者或协作者**能够在 **不构建内核** 的前提下，使用 **文本级对照材料**（如 **`patches/ubuntu-hwe-6.17/reference/`**）支撑讨论；**无完整源码树**时仍可就 **`reference/`**、补丁与 **PR** 进行文本级协作。 + +FR12: **维护者**在 **双源码树可用**时，能够执行或引用 **ChromiumOS 与 Ubuntu 树之间的对照流程**（脚本或操作说明）。 + +FR13: **读者**能够找到 **ChromiumOS 5.15** 与 **`kernel-src`** 的**约定路径与入口说明**。 + +FR14: **维护者**能够在 **`WORK_PROGRESS`** 中更新 **阶段结论、日期与阻塞项**。 + +FR15: **协作者**能够根据 **`WORK_PROGRESS`** 判断 **预检是否通过**或 **缺哪类树/包**。 + +FR16: **只读使用者**能够使用 **信息采集清单** 组织 **最小信息包**，**而不自动触发**上游协同义务。 + +FR17: **维护者**在阶段或结论变更时，能够完成 **`WORK_PROGRESS` 与路线图**的**交叉引用更新**。 + +FR18: **维护者**在新增或重组主题文档时，能够按约定**更新** **`docs/INDEX.md` / `REPO_INDEX.md`**（或等效索引），避免孤岛页；**大段摘录上游文档或代码**时须**标明来源与许可证**（与 **developer_tool** 许可证约定一致）。 + +FR19: **协作者**能够从索引或脚本表**定位**与 **HWE / HDMI** 相关的 **脚本及用途**。 + +FR20: **读者**能够从索引或总览中识别 **Linux HDMI 主线文档**与 **Windows / 其他平台** 文档的**入口分界**（本 PRD **不**交付 Windows 方案）。 + +FR21: **维护者**在 **Success Criteria 所定义的验证结论已具备**之后，能够准备 **上游复现/对外沟通** 所需材料（此前**无**必须完成的对外义务）。 + +### NonFunctional Requirements + +NFR1: **对外分享** dmesg / 采集前，**维护者**须按 **`audio_topology/COLLECT.md`**（或等效采集说明）对 **序列号、MAC、账号** 等可识别信息做**脱敏或裁剪**；**默认**不将未脱敏日志提交至公共 issue。**例外**：若 **上游 / issue** 在 **`UPSTREAM_SOF_Kaisa_HDMI_REPRO.md`** 等清单中**明确要求**某工具的全量输出，按该清单执行，并遵循**最小必要**与清单内说明。 + +NFR2: **维护者**不得在仓库中提交 **密钥、Cookie、个人账号口令** 等机密；脚本与文档示例使用占位符。 + +NFR3: 面向用户/协作者的说明须与 **`docs/meta/DOCUMENTATION_STYLE.md`** 及 **`project-context`** 中的语言与入口约定一致（**简体中文**为主，与 BMM 配置一致）。 + +NFR4: **新增主题文档**或**改变 `docs/` 导航结构**时，须在**同一变更或紧随提交**中**同步** **`docs/INDEX.md` / `REPO_INDEX.md`**（或等效索引）；**仅修改根 README 短链**且**不改变主题归属**时，**不**强制全文重链（与 **FR18** 配套）。 + +NFR5: **验证脚本**在文档声明的**环境基线**（**Ubuntu 24.04 + 与文档一致的 `linux-hwe-6.17` 线**）且**前置条件满足**时，须具备**可重复**的通过/失败语义；**其它发行版或内核线**仅作类比，**不声称**满足 **FR9** 的验证义务，除非在 **`WORK_PROGRESS`** 或文档中**单独记录**环境与结论。 + +NFR6: **完整内核构建**的耗时与磁盘占用**不作为**用户响应时间类指标；在文档与 **`WORK_PROGRESS`** 中**如实记录**典型量级与失败模式（如并行、空间不足）。 + +NFR7: 进入本仓库**版本库**的上游**摘录**（含大段文档或代码）须**可追溯来源与许可证**；**优先**以 **链接 + 短引** 替代长粘贴；**合理使用**边界按 **`developer_tool`** 与上游许可执行。 + +### Additional Requirements + +（来自 `architecture.md` 与棕地约定，用于 Epic/Story 分解时的技术约束。） + +- **工程基底**：非 Web 脚手架；初始化契约 = **目录约定、`kernel-src` 与 `uname -r` 对齐、`PATCH=` 流程、验证与采集路径**。 +- **本机即目标机**：FR9 所述验证默认在 **当前目标主机** 执行；**CI（若存在）** 仅为预检，**不**替代本机验证。 +- **入口唯一性**：可选 Python/CI 为子路径；**README 与文档声明的 Bash/文档入口** 为权威。 +- **补丁与树**：`patches/ubuntu-hwe-6.17/` 钉扎当前 HWE 线；新线 → `patches/<新线>/` 独立 README/验证叙述；**`PATCH=`** 单文件、顺序 0001→0002、0003 独立。 +- **导航锚点**：`patches/.../README`、`VERIFY_PATCHES.md`、`kernel-src/README.md`、`docs/INDEX.md`、`docs/meta/WORK_PROGRESS.md` 为固定锚点；**`audio_topology/`** 与 **`docs/linux-hdmi/`** 分工明确（采集 vs 路线图/结论）。 +- **实现模式**：`scripts/` 小写连字符；**`VERIFY_OK`** 仅用于约定脚本；文档与索引 **同事务** 更新；失败输出建议 stderr 可 grep 前缀。 +- **变更防呆**：补丁/本机验证相关变更应能指回 **README 锚点** 或等价路径。 +- **双索引**：默认 **README → `docs/INDEX.md`**；已知路径用 **`REPO_INDEX.md`**。 +- **规划 vs 需求**：`_bmad-output/` 为规划契约；冲突 **以 PRD 为准**。 + +### UX Design Requirements + +未发现 `{planning_artifacts}/*ux*.md` 或独立 UX 规格。本仓库主交付物为 **Bash / 补丁 / Markdown**，**无**以 UI 组件实现为主的 UX 规格；若后续新增 UX 文档，可在此节追加 **UX-DR*** 并回写 Story。 + +### FR Coverage Map + +| FR | Epic | 简述 | +|----|------|------| +| FR1 | Epic 1 | 入口链定位阶段与下一步 | +| FR2 | Epic 1 | 路线图 vs `WORK_PROGRESS` 分工 | +| FR3 | Epic 1 | 已排除路径与现象分流 | +| FR4 | Epic 2 | 补丁预检与应用 | +| FR5 | Epic 2 | 记录 `uname -r` 与 `kernel-src` 状态 | +| FR6 | Epic 2 | 预检失败不强制覆盖 | +| FR7 | Epic 3 | 自编内核安装/回退 | +| FR8 | Epic 3 | 构建失败可复现记录 | +| FR9 | Epic 4 | 钉扎验证路径与通过/失败语义 | +| FR10 | Epic 4 | HDMI 日志工件与脱敏引用 | +| FR11 | Epic 5 | 文本级 `reference/` 协作 | +| FR12 | Epic 5 | 双树对照流程 | +| FR13 | Epic 5 | ChromiumOS 与 `kernel-src` 路径入口 | +| FR14 | Epic 6 | `WORK_PROGRESS` 更新阶段与阻塞 | +| FR15 | Epic 6 | 预检与缺树/缺包可读 | +| FR16 | Epic 6 | 信息采集清单、最小信息包 | +| FR17 | Epic 6 | 路线图与 `WORK_PROGRESS` 交叉引用 | +| FR18 | Epic 1 | 索引更新与摘录来源 | +| FR19 | Epic 1 | 脚本表可发现 | +| FR20 | Epic 1 | Linux vs Windows 文档分界 | +| FR21 | Epic 7 | 验证后上游材料（条件） | + +### NFR 与 Epic 关联（摘要） + +| NFR | 主要 Epic | 说明 | +|-----|------------|------| +| NFR1 | Epic 4 | 对外分享前脱敏（`COLLECT.md`） | +| NFR2 | 全局 | 仓库不提交密钥；各 Epic 涉及示例时遵守 | +| NFR3 | Epic 1 | 体例与语言与 `DOCUMENTATION_STYLE` 一致 | +| NFR4 | Epic 1 | 导航变更同事务更新索引 | +| NFR5 | Epic 4 | 基线环境下验证语义可重复 | +| NFR6 | Epic 3 | 构建资源/失败事实记录 | +| NFR7 | Epic 1、Epic 5 | 摘录来源与许可证可追溯 | + +## Epic List + +### Epic 1：单一入口与文档可发现 + +**用户价值：** 维护者/协作者/读者能在**不依赖口头交接**的情况下，从根入口经索引到达路线图、工作进度与平台分界，并找到脚本与主题文档。 + +**涵盖 FR：** FR1、FR2、FR3、FR18、FR19、FR20 + +**说明：** 以「防迷路」为主交付；不依赖后续 Epic 即可单独验收（例如索引与 README 自洽）。 + +--- + +### Epic 2：补丁与源码树对齐 + +**用户价值：** 维护者能在与运行内核一致的 HWE 树上对仓库补丁做 **dry-run / 应用**，并诚实记录 **`uname -r` 与 `kernel-src` 状态**；预检失败时走核对/合并而非强贴。 + +**涵盖 FR：** FR4、FR5、FR6 + +**说明：** 与 Epic 3、4 推荐顺序为 **先对齐树与补丁，再构建/验证**，但本 Epic 本身可在「已有对齐树」假设下独立完成。 + +--- + +### Epic 3：自编内核构建、安装与恢复 + +**用户价值：** 维护者能按权威 OPERATION 完成 **自编 deb 的安装与回退**；完整构建失败时能留下 **并行度、日志位置** 等可复现信息。 + +**涵盖 FR：** FR7、FR8 + +**说明：** 恢复路径引用既有安装文档，不将 HDMI 排错与可启动性混写（与 PRD 旅程 E 一致）。 + +--- + +### Epic 4：验证与证据链 + +**用户价值：** 维护者能在文档钉扎环境下运行 **`verify-*` / `VERIFY_PATCHES` 路径**，得到可判读通过/失败；并保存 **HDMI 相关日志工件**，对外分享遵循脱敏约定。 + +**涵盖 FR：** FR9、FR10 + +**说明：** **本机验证**为权威；与架构一致——**无**仓库级自动化测试套件替代 FR9。 + +--- + +### Epic 5：文本对照与双树协作 + +**用户价值：** 协作者在不构建或双树齐备两种情况下，都能用 **`reference/`**、导出/diff 脚本与路径说明，完成 **ChromiumOS ↔ Ubuntu** 对照讨论。 + +**涵盖 FR：** FR11、FR12、FR13 + +**说明：** FR11 可在无完整树时独立产生价值；FR12 依赖双树可用时为增强能力。 + +--- + +### Epic 6：进度事实与协作透明 + +**用户价值：** 维护者与协作者能依赖 **`WORK_PROGRESS`** 与预检信息判断阻塞；只读者能用采集清单组织信息包而不触发上游义务；阶段变更时 **路线图与进度** 交叉引用一致。 + +**涵盖 FR：** FR14、FR15、FR16、FR17 + +**说明：** 与 Epic 1 互补——Epic 1 偏「静态导航结构」，本 Epic 偏「随时间变化的事实与协作」。 + +--- + +### Epic 7：上游与对外材料（条件触发） + +**用户价值：** 在 **成功标准所定义的验证结论已具备** 后，维护者能准备 **上游复现/对外沟通** 所需材料；此前无对外必达义务。 + +**涵盖 FR：** FR21 + +**说明：** 显式后置；不与 Epic 4 并行强制。 + +--- + +**自然推进顺序（建议，非硬依赖）：** Epic 1 → Epic 2 → Epic 3 → Epic 4；Epic 5 可与 2–4 穿插；Epic 6 贯穿；Epic 7 仅在条件满足后启动。 + +--- + +## Epic 1：单一入口与文档可发现 — Stories + +### Story 1.1：根入口与主题索引链完整 + +As a **协作者或维护者**， +I want **从根 `README` 经 `docs/INDEX.md`（及 `REPO_INDEX` 速查）到达路线图与 `WORK_PROGRESS`**， +So that **我能在 ≤30 分钟内定位「下一步读什么」**。 + +**Acceptance Criteria:** + +**Given** 仅克隆仓库且未口头交接 +**When** 我依次打开 `README.md` → `docs/INDEX.md` +**Then** 我能找到指向 `Linux_HDMI_Audio_Roadmap.md` 与 `docs/meta/WORK_PROGRESS.md` 的明确链接 +**And** 链接可点击且路径存在（或重定向说明存在） + +**Given** 需要全路径速查 +**When** 我打开 `REPO_INDEX.md` +**Then** 我能定位 `scripts/`、`patches/`、`kernel-src/` 等关键目录的说明入口 + +**追溯：** FR1；NFR3（与体例一致） + +--- + +### Story 1.2：路线图与 WORK_PROGRESS 职责边界可读 + +As a **读者**， +I want **在文档中看清「路线图管顺序、WORK_PROGRESS 管事实」**， +So that **我不会把阶段规划与换机/验证事实混为一谈**。 + +**Acceptance Criteria:** + +**Given** 我阅读 `docs/linux-hdmi/Linux_HDMI_Audio_Roadmap.md` 与 `docs/meta/WORK_PROGRESS.md` +**When** 对比两者开篇或 meta 说明 +**Then** 至少一处明确写出：路线图 = 阶段顺序与建议；`WORK_PROGRESS` = 日期、内核、阻塞与换机事实 +**And** 二者互相有交叉引用链接 + +**追溯：** FR2 + +--- + +### Story 1.3：已排除路径与现象分流可引用 + +As a **读者**， +I want **在现象分流时能查到「已知不成立路径」与继续对照的入口**， +So that **我不重复已记录弯路**。 + +**Acceptance Criteria:** + +**Given** 我处于 HDMI 调试/无声场景 +**When** 我按 `INDEX` 进入 `REANALYSIS` / `FIX_PLAN` / 路线图「已排除」相关节 +**Then** 我能区分用户态试错 vs 内核/IPC 对照路径的文档入口 +**And** 引用与 `FR3` 及 `ANALYSIS_Audio` 等现有分析一致，不新增矛盾结论 + +**追溯：** FR3 + +--- + +### Story 1.4：主题文档变更时同步索引 + +As a **维护者**， +I want **新增或移动 `docs/` 下主题文档时，同一变更集更新 `INDEX`/`REPO_INDEX`**， +So that **不出现孤岛页**。 + +**Acceptance Criteria:** + +**Given** 新增或重命名某主题 Markdown（OPERATION/路线图除外的小修） +**When** 合并请求或提交说明中列出索引变更 +**Then** `docs/INDEX.md` 或 `REPO_INDEX.md` 中可发现新路径 +**And** 符合 NFR4（同事务或紧随提交） + +**追溯：** FR18；NFR4 + +--- + +### Story 1.5：HWE/HDMI 相关脚本可发现 + +As a **协作者**， +I want **从 `INDEX` 或脚本表找到 `verify-*` / `ubuntu-hwe-*` 等脚本的用途与入口**， +So that **我不依赖聊天即可运行正确脚本**。 + +**Acceptance Criteria:** + +**Given** `docs/INDEX.md`（或文末脚本表） +**When** 我查找「验证」「构建」「diff」类任务 +**Then** 至少能定位到 `scripts/verify-ubuntu-hwe617-patches-runtime.sh`、`scripts/ubuntu-hwe-617-build.sh` 等条目的说明或链到 `VERIFY_PATCHES`/`README` +**And** 脚本注释或 `--help` 与文档描述不矛盾 + +**追溯：** FR19 + +--- + +### Story 1.6：Linux 与 Windows 文档分界可见 + +As a **读者**， +I want **从索引或总览识别 Linux HDMI 主线与 Windows 文档入口**， +So that **我不把 Windows 操作当作 Linux HDMI 交付范围**。 + +**Acceptance Criteria:** + +**Given** `docs/INDEX.md` 或根 `README` 任务表 +**When** 我查找跨平台信息 +**Then** Linux 与 Windows 分节或表格明确，且与 PRD FR20 一致（本 PRD 不交付 Windows 方案） + +**追溯：** FR20；NFR3 + +--- + +## Epic 2：补丁与源码树对齐 — Stories + +### Story 2.1：补丁预检与单文件应用路径 + +As a **维护者**， +I want **对 `patches/ubuntu-hwe-6.17/` 中补丁在正确树上执行 `patch -p1 --dry-run` 并按 `PATCH=` 单文件应用**， +So that **应用前可判读成功/失败**。 + +**Acceptance Criteria:** + +**Given** `kernel-src/` 与 `uname -r` 对齐（或文档声明未建源树） +**When** 我按 `patches/ubuntu-hwe-6.17/README.md` 设置 `PATCH=` 并对单 patch 执行 dry-run +**Then** 预检输出可判读成功或失败原因 +**And** 顺序约定 0001→0002、0003 独立在 README 中可见 + +**追溯：** FR4 + +--- + +### Story 2.2：记录 uname 与 kernel-src 状态 + +As a **维护者**， +I want **在 `WORK_PROGRESS` 或约定位置记录 `uname -r`、包来源与 `kernel-src` 状态**， +So that **他人能复现同一验证上下文**。 + +**Acceptance Criteria:** + +**Given** 一次补丁相关验证或构建 +**When** 我更新 `docs/meta/WORK_PROGRESS.md` +**Then** 至少包含：`uname -r`、与补丁对应的内核线说明、`kernel-src` 已准备/未准备 +**And** 与 FR5、NFR5 叙述一致 + +**追溯：** FR5 + +--- + +### Story 2.3：预检失败时不强制覆盖 + +As a **维护者**， +I want **在 dry-run 失败时不使用 `patch --force` 掩盖问题**， +So that **我核对树版本或手工合并**。 + +**Acceptance Criteria:** + +**Given** `patch -p1 --dry-run` 失败 +**When** 我查阅 `patches/.../README` 与 `project-context` +**Then** 流程明确禁止在未解决 dry-run 失败时 `patch --force` +**And** `WORK_PROGRESS` 可记录「失败原因 + 下一步」而非假成功 + +**追溯：** FR6；与 PRD api_surface 一致 + +--- + +## Epic 3：自编内核构建、安装与恢复 — Stories + +### Story 3.1：自编内核安装与回退可执行 + +As a **维护者**， +I want **按 `OPERATION_Install_CustomKernel_Ubuntu_HWE617.md` 完成安装与回退**， +So that **我可恢复可启动状态**（旅程 E）。 + +**Acceptance Criteria:** + +**Given** 已构建或未构建 deb 的场景 +**When** 我跟随 `docs/kernel-build/` 中安装 OPERATION +**Then** unsigned、模块包、Secure Boot 等范围以该文档为准且与 `WORK_PROGRESS` 可对照 +**And** 回退后 `uname -r` 与进度记录一致 + +**追溯：** FR7 + +--- + +### Story 3.2：完整内核构建失败可复现记录 + +As a **维护者**， +I want **在 `binary-generic` 等失败时记录并行度、日志路径与空间事实**， +So that **重试或协作排查有据**。 + +**Acceptance Criteria:** + +**Given** `fakeroot debian/rules binary-generic` 或等价失败 +**When** 我更新 `WORK_PROGRESS` +**Then** 记录含：并行相关环境变量（若适用）、日志文件路径、磁盘/错误摘要 +**And** 符合 NFR6 + +**追溯：** FR8；NFR6 + +--- + +## Epic 4：验证与证据链 — Stories + +### Story 4.1：钉扎验证路径与可判读结果 + +As a **维护者**， +I want **运行 `VERIFY_PATCHES.md` 与 `verify-ubuntu-hwe617-patches-runtime.sh` 所钉扎的路径**， +So that **我得到通过/失败与 `VERIFY_OK`（若适用）的明确语义**。 + +**Acceptance Criteria:** + +**Given** Ubuntu 24.04 + 文档基线内核与前置满足 +**When** 我按 `VERIFY_PATCHES` 运行验证脚本 +**Then** 退出码与输出可判读成功或失败，且与 `uname -r`、补丁版本一致 +**And** 不声称 CI 替代本机验证（架构） + +**追溯：** FR9；NFR5 + +--- + +### Story 4.2：HDMI 试播日志工件与脱敏 + +As a **维护者**， +I want **保存 HDMI 相关 dmesg/脚本输出，并在对外分享前按 `COLLECT.md` 脱敏**， +So that **证据可对齐路线图成功标准且不泄露隐私**。 + +**Acceptance Criteria:** + +**Given** 一次 HDMI 试播或验证 +**When** 我将日志保存到 `audio_topology/collected/` 或约定位置 +**Then** 可与路线图成功标准对照；若对外分享，遵循 `COLLECT.md` 与 NFR1 +**And** 未脱敏不全文贴公共 issue（除非 UPSTREAM 清单明确要求） + +**追溯：** FR10；NFR1 + +--- + +## Epic 5：文本对照与双树协作 — Stories + +### Story 5.1：无树时的 reference/ 文本协作 + +As a **协作者**， +I want **仅依赖 `patches/.../reference/` 与补丁讨论 PR**， +So that **无完整 `kernel-src` 时仍能文本级协作**。 + +**Acceptance Criteria:** + +**Given** 未检出完整 Ubuntu 树 +**When** 我引用 `reference/` 下已有 unified diff 与补丁说明 +**Then** 能支撑代码审查式讨论（FR11） +**And** 与 `DIFF_SUMMARY` 不矛盾 + +**追溯：** FR11 + +--- + +### Story 5.2：双树齐备时的对照与导出 + +As a **维护者**， +I want **在 `chromiumos_kernel/v5.15/` 与 `kernel-src/` 可用时运行预检/diff 导出脚本**， +So that **我能做 ChromiumOS ↔ Ubuntu 文件级对照**。 + +**Acceptance Criteria:** + +**Given** 双树路径满足 `preflight`/`export` 脚本前置 +**When** 我按 `docs/INDEX` 与脚本 `--help` 执行 +**Then** 产出可引用路径或 diff 片段，并记入 `WORK_PROGRESS` 可选 + +**追溯：** FR12 + +--- + +### Story 5.3：双树约定路径与入口说明 + +As a **读者**， +I want **在固定文档中找到 ChromiumOS 5.15 与 `kernel-src` 的克隆与索引入口**， +So that **我能自行准备对照树**。 + +**Acceptance Criteria:** + +**Given** `CHROMEOS_KAISA_AUDIO_KERNEL_PATHS.md` 与 `KERNEL_SRC_LINUX_HWE617_HDMI_3.5MM_PATHS.md`（或等效） +**When** 我从 `INDEX` 进入 +**Then** 路径与 `WORK_PROGRESS` 克隆说明一致，可定位关键文件 + +**追溯：** FR13；NFR7（摘录来源） + +--- + +## Epic 6：进度事实与协作透明 — Stories + +### Story 6.1：WORK_PROGRESS 更新阶段与阻塞 + +As a **维护者**， +I want **在 `WORK_PROGRESS` 中更新阶段结论、日期与阻塞项**， +So that **协作与未来的自己都能看见卡在哪**。 + +**Acceptance Criteria:** + +**Given** 阶段推进或验证结论变化 +**When** 我编辑 `docs/meta/WORK_PROGRESS.md` +**Then** 含日期、内核/补丁标识、阻塞（若有） +**And** 与路线图阶段可交叉核对 + +**追溯：** FR14 + +--- + +### Story 6.2：预检可读（缺树/缺包） + +As a **协作者**， +I want **从 `WORK_PROGRESS` 或预检脚本输出判断缺哪类树/包**， +So that **我能按清单补齐而非盲试**。 + +**Acceptance Criteria:** + +**Given** 运行 `preflight-chromeos-ubuntu-diff.sh` 或类似预检 +**When** 失败或部分通过 +**Then** `WORK_PROGRESS` 或脚本输出能映射到「缺 ChromiumOS」「缺 kernel-src」等类别 +**And** 与旅程 B 一致 + +**追溯：** FR15 + +--- + +### Story 6.3：信息采集清单与最小信息包 + +As a **只读使用者**， +I want **用 `UPSTREAM_SOF_Kaisa_HDMI_REPRO.md` 等清单组织最小信息包**， +So that **我不自动触发上游协同义务**。 + +**Acceptance Criteria:** + +**Given** 仅对外描述问题 +**When** 我按清单采集 +**Then** 信息包最小必要，且不将「发 issue」列为本仓库必达（FR16） + +**追溯：** FR16 + +--- + +### Story 6.4：路线图与 WORK_PROGRESS 交叉引用 + +As a **维护者**， +I want **在阶段或结论变更时更新路线图与 `WORK_PROGRESS` 的交叉引用**， +So that **两文档不矛盾**。 + +**Acceptance Criteria:** + +**Given** 阶段跳转或重要结论 +**When** 我更新其中任一文档 +**Then** 另一处同步或引用更新，避免 FR2 回归 + +**追溯：** FR17 + +--- + +## Epic 7：上游与对外材料（条件触发）— Stories + +### Story 7.1：验证通过后的上游材料闸门 + +As a **维护者**， +I want **仅在成功标准定义的验证结论已具备时，准备 `UPSTREAM_*` 类材料**， +So that **上游沟通不早于验证**。 + +**Acceptance Criteria:** + +**Given** 路线图/成功标准中「验证结论」未满足 +**When** 评估是否启动上游 issue/投递 +**Then** 文档明确：不将上游协同作为与验证并行里程碑（FR21、业务成功） +**And** 一旦准备材料，材料与 `COLLECT`/脱敏一致 + +**追溯：** FR21；NFR1 + +--- + +## Final Validation（Step 4） + +### FR / NFR 覆盖 + +| 检查项 | 结果 | +|--------|------| +| FR1–FR21 | 均在至少一个 Story「追溯」中出现；**无遗漏** | +| NFR1–NFR7 | 在 Story 与/或「NFR 与 Epic 关联」表中体现；**无遗漏** | + +### 与 Architecture 的一致性 + +| 检查项 | 结果 | +|--------|------| +| Starter / 初始化 | 架构为 **棕地文档 + Bash + 补丁契约**；**无** Web 脚手架；Epic 1 Story 1.1 为 **入口链文档**，**不**要求「从模板克隆应用」，与 `architecture.md` **一致** | +| 数据库 / 实体 | 本仓库 **无** 应用数据库；不适用「逐 Story 建表」规则 | + +### Story 质量与依赖 + +| 检查项 | 结果 | +|--------|------| +| 单代理可完成 | 各 Story 为文档/脚本/流程变更粒度，**可**由单次会话完成 | +| AC | 均含 Given/When/Then（及 And） | +| 同 Epic 内顺序 | 以 **1.1→1.2…** 为推荐顺序；文档类 Story **多可并行**，**无**「必须等未来 Story 实现才能写文档」的硬依赖 | +| Epic 间 | 各 Epic 可独立交付用户价值；**建议**顺序见 Epic List 节，**非**硬依赖阻塞 | + +### 结论 + +**VALIDATED** — `epics.md` 可作为实现与拆冲刺的输入；若 PRD 或架构变更，需回写 Story 与覆盖表。 + +--- + +**BMad Create Epics and Stories（CE）工作流已完成**（`stepsCompleted` 含 Step 4）。 diff --git a/_bmad-output/planning-artifacts/implementation-readiness-report.md b/_bmad-output/planning-artifacts/implementation-readiness-report.md new file mode 100644 index 0000000000..6285c4f00e --- /dev/null +++ b/_bmad-output/planning-artifacts/implementation-readiness-report.md @@ -0,0 +1,59 @@ +# Implementation Readiness Assessment Report + +**Date:** 2026-04-05 +**Project:** chromebox_10th_audio_driver +**范围：** PRD、Architecture、`epics.md` 与棕地工具仓库语境 + +--- + +## 1. 文档发现 + +| 工件 | 路径 | 状态 | +|------|------|------| +| PRD | `_bmad-output/planning-artifacts/prd.md` | 完整；FR1–FR21、NFR1–NFR7 | +| Architecture | `_bmad-output/planning-artifacts/architecture.md` | 完整；Step 1–8、`status: complete` | +| Epics & Stories | `_bmad-output/planning-artifacts/epics.md` | 完整；7 Epic、21 Story、Final Validation Step 4 | +| Project context | `_bmad-output/project-context.md` | 与 PRD/架构一致 | +| UX 规格 | 无 | **预期内**（非 UI 主交付物） | + +--- + +## 2. 追溯与对齐 + +| 检查项 | 结论 | +|--------|------| +| FR → Epic/Story | `epics.md` 中 FR 覆盖表 + 各 Story「追溯」**完整** | +| Architecture → Story | 棕地契约（`PATCH=`、本机验证、INDEX）已在 Story 与 Additional Requirements 中体现 | +| PRD 顺序约束 | FR21 / 上游后置与 Epic 7 一致 | +| 技术栈假设 | Bash + Markdown + 内核补丁；**无**矛盾的数据库/API 层假设 | + +--- + +## 3. Epic/Story 质量（摘要） + +| 检查项 | 结论 | +|--------|------| +| 用户价值导向 | Epic 按「导航 / 补丁 / 构建 / 验证 / 对照 / 协作 / 上游」划分，**非**纯技术分层 | +| Story 粒度 | 文档/脚本可单次迭代；AC 含 Given/When/Then | +| 依赖 | 文档类 Story 可并行；**无**「必须未来 Story 先实现」的硬阻塞 | +| 与 Architecture 的 Starter | 非 Web 脚手架；与架构 **Starter Template Evaluation** 一致 | + +--- + +## 4. 风险与缺口（非阻塞） + +| 项 | 说明 | +|----|------| +| 自动化测试 | 仓库以验证脚本与手工步骤为主；**不**要求 pytest/Jest 覆盖 FR9 | +| 第二条内核线 | 未来 `patches/<线>/` 需独立 README；已在架构与 Story 中预警 | +| IR 与 UX | 无独立 UX 文档；**不**阻塞实现准备度 | + +--- + +## 5. 总评 + +**READY FOR IMPLEMENTATION** — 可进入 **Sprint 跟踪**、**Create Story**、**Dev Story** 循环。建议优先 Epic 1（入口与可发现性），与 `README` / `docs/INDEX.md` 维护同步。 + +--- + +*本报告为 BMad **Check Implementation Readiness（IR）** 的一站式摘要；若 PRD 或架构有重大变更，应重跑对齐检查。* diff --git a/_bmad-output/planning-artifacts/prd.md b/_bmad-output/planning-artifacts/prd.md new file mode 100644 index 0000000000..1563927358 --- /dev/null +++ b/_bmad-output/planning-artifacts/prd.md @@ -0,0 +1,410 @@ +--- +stepsCompleted: + - step-01-init + - step-02-discovery + - step-02b-vision + - step-02c-executive-summary + - step-03-success + - step-04-journeys + - step-05-domain + - step-06-innovation + - step-07-project-type + - step-08-scoping + - step-09-functional + - step-10-nonfunctional + - step-11-polish + - step-12-complete +inputDocuments: + - README.md + - docs/linux-hdmi/Linux_HDMI_Audio_Roadmap.md + - docs/meta/WORK_PROGRESS.md + - docs/linux-hdmi/CHROMEOS_KAISA_AUDIO_KERNEL_PATHS.md + - docs/linux-hdmi/KERNEL_SRC_LINUX_HWE617_HDMI_3.5MM_PATHS.md + - kernel-src/README.md + - _bmad-output/project-context.md + - _bmad-output/problem-solution-2026-04-04-linux-hdmi-kaisa.md + - chromiumos_kernel/v5.15/ + - kernel-src/ +documentCounts: + briefCount: 0 + researchCount: 1 + brainstormingCount: 0 + projectDocsCount: 8 +workflowType: prd +classification: + projectType: developer_tool + domain: general + complexity: low + projectContext: brownfield +--- + +# Product Requirements Document - chromebox_10th_audio_driver + +**Author:** Jack +**Date:** 2026-04-05T11:54:55+08:00 + +## 文档结构（目录） + +| 章节 | 内容摘要 | +|------|----------| +| [Executive Summary](#executive-summary) | 问题范围、差异点、不交付项 | +| [Project Classification](#project-classification) | developer_tool / brownfield 等 | +| [Success Criteria](#success-criteria) | 用户/业务/技术成功、可量化结果 | +| [Product Scope](#product-scope) | MVP / Growth / Vision、上游后置 | +| [User Journeys](#user-journeys) | 五类旅程与能力汇总 | +| [developer_tool Specific Requirements](#developer_tool-specific-requirements) | 语言、安装、接口、迁移 | +| [Project Scoping & Phased Development](#project-scoping--phased-development) | 与路线图阶段对齐、MVP 顺序 | +| [Functional Requirements](#functional-requirements) | 能力契约 FR1–FR21 | +| [Non-Functional Requirements](#non-functional-requirements) | 隐私、文档、可复现、许可 | + +**追溯链**：愿景 → 成功标准 → 用户旅程 → **FR/NFR**；实现与 Epic 应能回溯至对应条目。 + +## Executive Summary + +本仓库将 **Google Kaisa（Chromebox 10 / Coreboot）** 在 **Linux（Ubuntu 24.04 + linux-hwe-6.17）** 下的 **HDMI 无输出 / SOF IPC 失败（典型如 `STREAM_PCM_PARAMS`、约 -5）** 问题，收敛为一条**可复现、可交接**的 **developer_tool** 路径：以 **路线图阶段**划分行动，每阶段有**可核对的完成判据**；以 **补丁、`verify-*`、自编内核构建、ChromiumOS 5.15（`chromiumos_kernel/v5.15/`）与 Ubuntu HWE（`kernel-src/`）双树 diff 与导出脚本** 支撑**同一结论在不同机器上可被重复验证**。**首要成功标准（可观察）**：他人能在**明确文档入口**下复现**构建与验证步骤**，并产出**可对齐的日志/证据**（dmesg、脚本输出等）；**周期（如换机后 ≤N 天）** 可后续在成功标准中量化。**不承诺**「限时必出声」；**承诺**路径、证据与索引分层可读。**主要受众**为**维护者本人与少数协作者**。文档治理：**路线图**管阶段与顺序；**WORK_PROGRESS** 管事实与换机/clone——卡死时以二者及预检脚本为权威入口。**明确不包含**：**ChromeOS 用户态 CRAS** 深度适配；**亦不将** **Windows 音频驱动/成套闭源驱动方案** 纳入本 PRD 交付范围（相关说明保留在仓库其他文档）。**约束**：自编内核涉及**磁盘空间、模块包完整性、Secure Boot/unsigned 安装**，以既有 `kernel-src` 与安装 OPERATION 为准，本 PRD 不展开逐步操作。 + +### What Makes This Special + +与零散帖子或一次性操作相比，差异集中在：**（1）证据链**——从现象到 **IPC 载荷**与 **ChromiumOS ↔ Ubuntu HWE** 对照，避免仅靠换 tplg/固件试错；**（2）工具链可复现**——`PATCH=`、构建、验证与 diff 导出使重复实验成为约定；**（3）治理与期望**——防迷路、成功标准优先「可复现与可验证」，**不将「上游短期合入或发行版默认修复」** 假定为必然结果。核心洞察：失败多表现为 **hw_params / IPC 契约与固件预期不一致**；对照基准应是 **ChromiumOS 内核树与同机 trace**，而非与 Chrome 行为不对等的替代内核包。 + +## Project Classification + +| 维度 | 取值 | +|------|------| +| **项目类型** | developer_tool | +| **领域** | general | +| **领域复杂度（CSV 维度）** | low | +| **项目语境** | brownfield | + +## Success Criteria + +### User Success + +- **协作者 / 换机**：在**未口头交接**的前提下，仅凭 **`README` → `INDEX` → 路线图 / `WORK_PROGRESS`** 能定位当前阶段，并执行**至少一条**已文档化的验证路径（如 `verify-*`、采集脚本或 `speaker-test` 流程），得到**可对比的产出物**（日志、`collected/`、脚本退出码）。 +- **「值得」时刻**：当 **`VERIFY_OK`** 或等价结论出现，或 **HDMI 播放尝试** 能产生**与路线图一致、可解释**的 dmesg（含或不含 IPC 载荷），而非「黑盒无声」。 +- **情感**：从「不知道该信哪篇帖」转为「**下一步在路线图 / 修复计划里有编号**」。 + +### Business Success + +本仓库语境下，**「业务」**指项目可持续性与可信度，而非收入指标。 + +- **维护诚实度**：`WORK_PROGRESS` 与路线图**阶段声明**与真机状态一致；**不宣称**尚未验证的项为已解决。 +- **协作成本**：新协作者**首次**跑通文档化验证路径时的**阻塞**（缺树、缺 deb 包、浅克隆等）在 `WORK_PROGRESS` 或预检中有**明确记录与缓解链接**。 +- **上游相关（顺序约束）**：**仅在**验证路径已给出**明确结论**（已修复 / 已定位责任组件 / 已文档化不可行边界）**之后**，再评估是否启动 **`UPSTREAM_SOF_*` 类对外沟通**。**不**采用「先发 issue 再慢慢试」为默认顺序；**上游协同不作为**验证完成**之前的并行里程碑**。 + +### Technical Success + +- **Linux 主线**：在目标 **`linux-hwe-6.17`** 与仓库补丁策略下，**构建与安装**可重复；**验证脚本**与 **`uname -r`**、已装模块包一致。 +- **根因方向**：对 **HDMI IPC 失败** 具备**可引用**的对照材料（双树 diff、trace 或**验证后**再补充的上游链接），而非仅「换过固件」。 +- **回归**：自编内核场景下，**3.5mm / WiFi** 等**非目标子系统**不因验证流程被**未记录地**破坏。 + +### Measurable Outcomes + +| 类型 | 指标（与 `Linux_HDMI_Audio_Roadmap.md` 对齐） | +|------|-----------------------------------------------| +| **客观** | 对目标 HDMI 口试播时，与本次播放**相关**的 **`STREAM_PCM_PARAMS` / `ipc tx error`** 在 dmesg 中**消失**，或已被**文档解释**为无害 / 已规避。 | +| **主观** | 目标口有**稳定可听**输出。 | +| **复现** | 在**另一台按文档准备的机器**上，同一验证命令可重复执行并产出**同类**证据结构。 | +| **可选量化** | 换机后 **≤N 天**内完成首次成功验证（**N** 后续填入）。 | + +## Product Scope + +### MVP - Minimum Viable Product + +- **文档入口**：根 `README`、`docs/INDEX`、`Linux_HDMI_Audio_Roadmap`、`WORK_PROGRESS` **互相可导航**。 +- **工具链最小**：**0001**（及按需 **0002 / 0003**）的 **apply → 构建 → 安装** 路径**可重复**；**`verify-*`** 在约定环境下有**明确通过 / 失败语义**。 +- **证据最小**：一次 **HDMI 试播** 的 **dmesg 基线** + **可选** trace 配置说明（指向现有 OPERATION）。 + +### Growth Features (Post-MVP) + +- **双树深度**：`chromiumos_kernel/v5.15/` 与 `kernel-src/` **齐全**时，**自动化 / 半自动化** diff 与 `reference/` 导出**例行化**。 +- **Trace / 深度对照**：按路线图阶段 3，完善 **IPC / 载荷** 与板级对照（与现有脚本一致）。 +- **上游协同（显式后置）**：**仅当**验证已解决或**清晰界定**问题责任后，再启用 **`UPSTREAM_SOF_Kaisa_HDMI_REPRO.md` 类投递**；本 PRD **不**将「发上游」列为与验证并行的必达项。 + +### Vision (Future) + +- **Linux HDMI** 在 Kaisa + 约定栈上具备**明确结论**（修复路径、固件 / 拓扑变更、或**文档化边界**）。 +- **本仓库**成为同款硬件在 **Linux SOF** 路径上的**可引用协作基线**；与社区的**持续协同**以**验证结论**为前提展开。 + +## User Journeys + +### 旅程 A — 维护者（主路径 · 阶段推进） + +**开场**：真机 HDMI 仍无声，3.5mm 正常；dmesg 已有 IPC 线索。 +**发展**：打开**路线图**，确认处于阶段 2 或 3；按 **`WORK_PROGRESS`** 核对内核与补丁版本；运行 **`verify-*`** 或构建脚本，得到 **`VERIFY_OK`** 或**可行动的失败原因**。 +**高潮**：自编内核与补丁与文档一致，**证据链**（dmesg + 可选 trace）能对照 **Chrome 树笔记**。 +**结局**：在 **`WORK_PROGRESS`** 中**诚实更新阶段与日期**（与路线图交叉引用）；下一步在路线图中有**编号**。 +**恢复**：若自编内核导致启动异常，**不**在 PRD 内展开逐步排错；**回退 / unsigned / Secure Boot** 以现有 **`OPERATION_Install_CustomKernel_Ubuntu_HWE617.md`** 与 GRUB 说明为准；详见**旅程 E**。维护者在验证记录中注明是否已回退可用内核。 + +**决策点**：若同一阶段内 **第三次** 仍只有「现象变化、结论不变」，**先**更新 `WORK_PROGRESS` 与采集文件时间戳，**再**改补丁或参数。 +**可观测检查点**：`verify` 输出或 dmesg 片段与 **`uname -r`**、**`dpkg -l | grep linux-image`** 可同屏对应。 +**完成定义（DoD）**：`WORK_PROGRESS` 中含**可引用**的日期/内核/补丁标识，且与路线图阶段**一致**。 + +### 旅程 B — 新协作者（换机 · 易错恢复） + +**开场**：新克隆仓库，尚无完整 **`kernel-src`** 或 **ChromiumOS** 仅为浅克隆。 +**发展**：**第一动作**：打开 **`WORK_PROGRESS`** 与（若存在）**预检脚本**，对照「缺树 / 缺包」**是否被写明**；再执行文档中的 **`apt source` / 补 clone**。 +**高潮**：阻塞从「心里慌」变为**清单上可勾选**；第一次验证命令产出**可对比日志**。 +**结局**：建立「卡死时信 **`WORK_PROGRESS` + 预检**」；**上游 issue 不替代**本地验证。 + +**决策点**：若预检失败项 **>2 项**，**优先**补齐与运行内核一致的 **`kernel-src` 完整树**（或记明「本机仅文档化、未构建」），再跑 verify。 +**可观测检查点**：预检退出码与 `WORK_PROGRESS` 中 **「已满足 / 未满足」** 一行对齐。 +**完成定义（DoD）**：未通过项有**负责人或推迟原因**（磁盘、时间等），避免「静默卡住」。 + +### 旅程 C — 边缘：验证「全绿」但 HDMI 仍无声 + +**开场**：脚本通过、构建成功，主观仍无声。 +**发展**：回到路线图**成功标准**：区分「IPC 相关日志已干净」与「仍无声」；查 **FIX_PLAN / REANALYSIS**，核对 **设备号与物理口**、路由。 +**高潮**：现象归入**已文档化分支**（如阶段 C/D），不叠加未记录补丁。 +**结局**：结论写回 **`WORK_PROGRESS`**；**上游协同**仅当验证已界定责任后再评估。 + +**决策点**：若 **IPC 已干净** 仍无声，**先**完成 **设备号 ↔ 物理口** 对照（可链到 `collected/`），再进入 FIX_PLAN 下一分支。 +**可观测检查点**：同一次试播前后 **dmesg 过滤** 与路线图**成功标准**可对照。 +**完成定义（DoD）**：**设备映射或 FIX_PLAN 分支** 至少更新**一处**可追溯文档。 + +### 旅程 D — 只读使用者（查结论、不构建） + +**开场**：同款硬件用户，**不愿**自建内核。 +**发展**：从路线图**已排除项**、**已否决路径**获益；若需对外描述问题，使用 **`UPSTREAM_SOF_Kaisa_HDMI_REPRO.md`** 等**采集清单**作**最小信息打包**（**不等于**启动上游协同）。 +**高潮**：预期对齐：本仓库**不承诺**一键出声，**承诺**防弯路与可核对叙事。 +**结局**：若决定深入构建，转入旅程 B。 + +**决策点**：若仍尝试**纯用户态**改路由，**标注**为实验性质，**不与**内核 IPC 根因结论混写。 +**可观测检查点**：至少**引用一条**路线图「已排除项」说明**未重复**已知弯路。 +**完成定义（DoD）**：对外或自用说明中**可见**对已记录弯路的**显式回避**。 + +### 旅程 E — 恢复与可启动性（短旅程） + +**开场**：自编或模块实验后**无法启动**或**无网络**等严重回归。 +**发展**：优先 **GRUB 选旧内核**、按 **安装 OPERATION** 处理 **unsigned / Secure Boot**。 +**高潮**：机器回到**可重复验证**状态。 +**结局**：在 **`WORK_PROGRESS`** 记**回退事实**（版本、是否恢复）；恢复细节**不**与 HDMI 调试混写，但**必须**可追溯。 + +**决策点**：若 GRUB 旧内核仍无法启动，**停止** HDMI 主线，**以恢复为 P0**；`WORK_PROGRESS` 记 **P0 阻塞**。 +**可观测检查点**：回退后 **`uname -r`** 与 `WORK_PROGRESS` **「当前可用内核」** 一致。 +**完成定义（DoD）**：**可启动内核**与记录一致，HDMI 主线才可继续。 + +### Journey Requirements Summary + +| 能力域 | 需求 | +|--------|------| +| **入门与导航** | **README → INDEX → 路线图 / `WORK_PROGRESS`** 单一链条。 | +| **最短命令路径** | 预检 / `verify-*` / 构建入口在文档中有**单点引用**（指向 `WORK_PROGRESS` 或脚本 `--help`）。 | +| **可执行验证** | `verify-*`、构建脚本、**明确退出语义**。 | +| **阻塞透明** | 预检、`WORK_PROGRESS`**列出**缺树/缺包。 | +| **期望管理** | 路线图「已排除项」、成功标准主客观分离。 | +| **顺序约束** | 验证先行，**上游协同后置**。 | +| **恢复与可信** | **GRUB / unsigned / Secure Boot** 以 **OPERATION** 为准；旅程 E 专责**可启动性**。 | +| **只读信息包** | 引用 **UPSTREAM/采集清单** 做**最小信息打包**，**不**自动触发上游流程。 | +| **状态更新责任** | 阶段或结论变更时**同步** `WORK_PROGRESS` 与路线图**交叉引用**。 | +| **决策纪律** | 重复尝试无新结论时，**先**更新 `WORK_PROGRESS` 与采集物，**再**变配置。 | +| **可观测检查点** | 每阶段至少保留 **可与 `uname -r`/包表对齐** 的证据；恢复类以 **P0** 记入 `WORK_PROGRESS`。 | +| **文档结构维护** | 大改 `docs/` 时**同步** **INDEX / REPO_INDEX**（与仓库约定一致）。 | + +## developer_tool Specific Requirements + +### Project-Type Overview + +本仓库在 BMad 分类中为 **developer_tool**：交付物以 **可执行脚本、Git 格式补丁、Markdown 文档与索引** 为主，服务于 **可复现构建、验证与双树对照**，而非独立 GUI 或上架应用。受众为 **维护者本人与少数协作者**（与 Executive Summary 一致）。**索引用途分工**：**`docs/index.md`**（小写）便于 AI 检索；**`docs/INDEX.md`** 为人读总目——二者须与 **`project-context`** 及换机约定保持一致。**验证基线**以 **Ubuntu 24.04 + linux-hwe-6.17** 为主；其他发行版仅作**类比**，不纳入本 PRD 的验证义务。 + +### Technical Architecture Considerations + +- **宿主**：以 **Ubuntu 24.04 + linux-hwe-6.17** 为文档与验证基线；真机以 **`uname -r`** 与 **`kernel-src`** 树版本一致为准。 +- **源码布局**：**`kernel-src/`**（Ubuntu HWE 解压树 + 构建产物约定）、**`chromiumos_kernel/v5.15/`**（ChromiumOS 对照树）；二者体积大，遵守 **`.gitignore`**，以 **README / 索引笔记** 为入口。 +- **补丁管线**：**`patches/ubuntu-hwe-6.17/`** 内 **0001–0003** 按仓库 README 顺序；**`PATCH=`** 指向**单文件** 再 **`apply`**。 +- **自动化**：**`scripts/`** 下构建、验证、diff 导出脚本；依赖路径在注释或 `--help` 中写明。 + +### language_matrix + +| 语言 / 形态 | 用途 | +|-------------|------| +| **Bash** | 构建、验证、采集、预检脚本（`set -e` 等以现有脚本为准）。 | +| **Markdown** | 文档主体；入口 **README**、**`docs/INDEX.md`**、路线图与 `WORK_PROGRESS`。 | +| **C（内核）** | 仅通过 **补丁** 修改；不在 PRD 中要求独立应用工程。 | +| **Git** | 克隆 **ChromiumOS** 树、**unshallow**、按路径 diff（见 `OPERATION_ChromeOS_Kernel_Deep_Diff.md` 等）。 | + +### installation_methods + +- **Ubuntu 内核源码**：`apt source linux-hwe-6.17=<与运行内核一致的 Version>`，解压至 **`kernel-src/`**（见 **`kernel-src/README.md`**）。 +- **构建依赖**：`scripts/ubuntu-hwe-617-build.sh` 的 **`deps`** / **`apt build-dep linux-hwe-6.17`**；Noble 上包名以文档为准。 +- **Debian 式完整 generic 构建**：在解压树内使用 **`fakeroot debian/rules clean`**、**`fakeroot debian/rules binary-generic`**；若曾 **`make defconfig` / `prepare`** 导致 tree 不洁，须在源码根 **`make mrproper`**（或等价清理）后再打包——**详见 `kernel-src/README.md`**（含磁盘与失败模式）。**高并行**下 **`binary-generic`** 可能因 **`make` 并行/信号量** 等失败（见历史日志如 `semop`）；可**降低并行**（如 **`CONCURRENCY_LEVEL`**）重试，具体以 **`WORK_PROGRESS`** 与构建日志为准，本 PRD 不规定固定线程数。 +- **ChromiumOS 内核**：浅克隆 + 可选 sparse-checkout（见 **`docs/meta/WORK_PROGRESS.md`**），本仓库路径 **`chromiumos_kernel/v5.15/`**。 +- **安装自编 deb**：**`docs/kernel-build/OPERATION_Install_CustomKernel_Ubuntu_HWE617.md`**（unsigned、模块包、Secure Boot）。 +- **IDE**：无强制 IDE；编辑器与 `patch`/`git` 即可。 + +### api_surface（工具与接口面） + +| 接口类型 | 说明 | +|----------|------| +| **环境变量** | 如 **`PATCH=`** 指向单补丁文件；**必须**与当前正在操作的 **`kernel-src/linux-hwe-*`** 树根及版本一致；**先** **`patch -p1 --dry-run`** 再正式应用；**禁止**在 **`dry-run` 失败** 时使用 **`patch --force`** 强行覆盖——应改为手工合并或核对树版本。 | +| **脚本子命令** | **`ubuntu-hwe-617-build.sh`**：`apply` / `deps` / `build` 等（以脚本 `--help` 为准）。 | +| **验证** | **`verify-ubuntu-hwe617-patches-runtime.sh`** 等；成功时可 **`VERIFY_OK`**。 | +| **预检 / diff** | **`preflight-chromeos-ubuntu-diff.sh`**、**`export-chromeos-ubuntu-sound-file-diffs.sh`** 等；双树齐全时启用。 | + +### code_examples + +- **补丁应用与构建**：**`patches/ubuntu-hwe-6.17/README.md`**、**`kernel-src/README.md`**（含 **`mrproper`** 与 **`binary-generic`** 注意）。 +- **验证**：**`patches/ubuntu-hwe-6.17/VERIFY_PATCHES.md`**。 +- **对照与导出**：**`scripts/export-chromeos-ubuntu-sound-file-diffs.sh`**、**`docs/kernel-build/OPERATION_ChromeOS_Kernel_Deep_Diff.md`**。 +- **只读 / 文本级对照（无需本机构建）**：**`patches/ubuntu-hwe-6.17/reference/`** 下已有 **unified diff**；可配合上述 **export** / **diff** 脚本做文件级对比。 +- **索引**：**`docs/INDEX.md`**、**`REPO_INDEX.md`**（全路径）。 + +### migration_guide（迁移与版本演进） + +- **内核小版本升级**（如 6.17.0-19 → -20）：在 **`kernel-src/`** 重新 **`apt source`** 对齐 **`uname -r`**；**`make mrproper`** 后再 **`fakeroot debian/rules binary-generic`**（见 **`kernel-src/README.md`**）。 +- **补丁重贴**：在新树 **`patch -p1 --dry-run`**；**`DIFF_SUMMARY.txt`** 与 **reference/** 对照变更范围。 +- **ChromiumOS 树**：浅克隆若 **`git log` 单条**，需 **`git fetch --unshallow`** 后再做历史向分析（见 **`CHROMEOS_KAISA_AUDIO_KERNEL_PATHS.md`** 附录）。 +- **文档搬迁**：换机时同步 **`WORK_PROGRESS`** 与路线图阶段；大目录不提交，**只迁移或重拉**说明留在 **`WORK_PROGRESS`**。 + +### Implementation Considerations + +- **最小 diff**：变更以仓库既有体例为准（**`project-context`**）。 +- **`PATCH=` 安全使用**：**禁止**对错误版本树强贴；**dry-run** 失败时先核对 **`uname -r`**、`dpkg -s` 与 **`kernel-src`** 树是否同源。 +- **许可证**：**ChromiumOS 内核树**、**Ubuntu 源码包** 各自遵循**上游许可证**；本仓库**自产**文档、脚本与补丁的许可以**仓库根目录及既有约定**为准（若有 `LICENSE` / 贡献说明则从其规定）。 +- **可观测性**：验证与构建日志建议保留在 **`kernel-src/`** 或约定文件名，并在 **`WORK_PROGRESS`** 引用。 +- **跳过项**：不写 **visual_design**、**store_compliance**；不写 CRAS/Windows 驱动交付（见 Executive Summary）。 + +## Project Scoping & Phased Development + +### MVP Strategy & Philosophy + +- **MVP 取向**：**问题解决型 + 可验证学习**——最小可用 = **他人能按文档复现验证并留下可对齐证据**（与 Executive Summary 一致）。 +- **资源假设**：**1 名核心维护者 + 0～少数协作者**；技能：**Linux 命令行、Git、`patch`**；无专职测试/设计。 + +### Alignment: PRD Phases vs Linux HDMI Roadmap + +| 本 PRD | 路线图（`docs/linux-hdmi/Linux_HDMI_Audio_Roadmap.md`） | 摘要 | +|--------|--------------------------------------------------------|------| +| **MVP** | **阶段 1–2** 中与「可复现验证」相关的子集 | 用户态基线 + HWE/补丁/自编内核与 **`verify-*`**；**不**强制完整 ChromiumOS 树。 | +| **Post-MVP · 增长** | **阶段 3** | 双树、diff 导出、可选 trace、深度对照。 | +| **Post-MVP · 扩展** | **阶段 4** | **上游协同**；**仅**在成功标准中「验证之后再考虑」的前提下启用。 | + +### MVP Dependency Order + +1. 文档入口链可用（`README` → `INDEX` / `index` → 路线图 / `WORK_PROGRESS`）。 +2. **运行内核**与 **`kernel-src`**（或书面声明未建源树）一致。 +3. **`PATCH=`**：`dry-run` → `apply`（至少 **0001**）。 +4. 至少一条 **`verify-*`** 有记录（日志或退出码）。 +5. **`WORK_PROGRESS`** 与路线图阶段对齐更新。 + +### Mapping: README L1–L4 + +- **L1** → MVP（阶段 1 用户态基线）。 +- **L2** → MVP 以文档与采集为主；深度 SOF 对照属 Post-MVP（阶段 3）。 +- **L3** → MVP 核心（阶段 2：HWE、补丁、自编内核）。 +- **L4** → MVP 含脚本+补丁可用；**双树例行 diff** 属 Post-MVP Phase 2。 + +### MVP Feature Set（Phase 1） + +**核心旅程（最小）**：**旅程 A**、**旅程 B** 主路径；**旅程 E** 以引用 **OPERATION** 为满足。 + +**Must-have 能力** + +| 能力 | 说明 | +|------|------| +| **文档入口链** | `README` → `INDEX` / `index` → 路线图 / `WORK_PROGRESS`。 | +| **补丁与验证** | **`PATCH=` + dry-run**；**`verify-*`** 有明确通过/失败语义。 | +| **与运行内核一致** | **`kernel-src`**（或等价说明）与 **`uname -r`** 对齐后方可宣称验证完成。 | +| **阶段诚实** | `WORK_PROGRESS` 与路线图阶段一致。 | + +**MVP 明确不强制**：本机已检出完整 **`chromiumos_kernel/v5.15/`**（无树时仍可依赖 **`patches/.../reference/`** 只读对照，见 **developer_tool** 节）。 + +### MVP Completion Checklist (lightweight) + +- [ ] 协作者 **≤30 分钟**内可定位「下一步三个入口文件」（自测）。 +- [ ] `WORK_PROGRESS` 含最近一次验证或指向 `audio_topology/collected/` 等采集物。 +- [ ] 路线图 **阶段 1–2** 与 `WORK_PROGRESS` **无矛盾**。 + +### Anti-scope（MVP 不纳入） + +- 路线图 **阶段 3** 的**完整**双树自动化（**只读 reference/** 除外）。 +- 路线图 **阶段 4** 上游协同（见 **Success Criteria**）。 +- **完整** `chromiumos_kernel` 检出（MVP 不强制）。 + +### Post-MVP Features + +**Phase 2（增长）— 对齐路线图阶段 3** + +- 双树齐备时 **diff 导出例行化**、**trace / 深度对照**（与现有脚本一致）。 +- **`reference/`** 与预检的文档化（降低「必须本机构建」门槛）。 + +**Phase 3（扩展）— 对齐路线图阶段 4** + +- **验证界定责任之后**的 **上游协同**（`UPSTREAM_*`）。 +- **Linux HDMI** 明确结论或文档化边界（与 **Vision** 一致）。 + +### Risk Mitigation Strategy + +| 风险 | 缓解 | +|------|------| +| **技术** | 高并行 **`binary-generic` 失败** → 降并行、日志见 `WORK_PROGRESS`；**`PATCH=`** 先 **dry-run**、**禁止 `patch --force`**。 | +| **期望** | 「限时出声」类预期 → 由 Executive Summary 与旅程 **D** 约束。 | +| **资源** | 磁盘/时间不足 → 阻塞写入 `WORK_PROGRESS`；**单点维护者**停顿 → 依赖 **`WORK_PROGRESS` 日期 + 路线图阶段** 仍可读，否则 Phase 2 推进条件不足。 | + +## Functional Requirements + +### 文档与导航 + +- **FR1**：**维护者或协作者**能够仅通过 **`README` → 索引 → 路线图 / `WORK_PROGRESS`** 定位当前工作阶段与下一步阅读顺序。 +- **FR2**：**读者**能够区分 **路线图**（阶段顺序）与 **`WORK_PROGRESS`**（事实与换机状态）的职责边界。 +- **FR3**：**读者**能够查阅 **Linux HDMI 已排除或低期望方向**，并在**现象分流**时区分「已知不成立路径」与「需继续对照内核/用户态」的路径（引用既有分析文档）。 + +### 补丁与内核源码对齐 + +- **FR4**：**维护者**能够将仓库内 **指定补丁** 应用于**与运行内核版本一致**的 **Ubuntu HWE 源码树**，并在应用前获得 **`patch` 预检结果**（成功/失败）。 +- **FR5**：**维护者**能够记录当前验证所对应的 **`uname -r`**、内核包来源与 **`kernel-src`** 树状态（含「未建源树」声明）。 +- **FR6**：**维护者**在 **`patch` 预检失败**时**不**以强制覆盖方式掩盖失败，而转入核对或手工合并。 + +### 构建、安装与恢复 + +- **FR7**：**维护者**能够按照 **`OPERATION_Install_CustomKernel_Ubuntu_HWE617.md`** 等权威说明完成 **自编内核的安装与回退**；**安装范围**（含 **unsigned、模块包完整性、相关固件/无线等**）以该 OPERATION 为准，**不**在 PRD 内逐包枚举。 +- **FR8**：**维护者**在 **完整内核构建**失败时，能够记录 **并行度/日志位置** 等可复现信息，以便重试或协作排查。 + +### 验证与诊断 + +- **FR9**：**维护者**能够运行 **`VERIFY_PATCHES.md` 或文档当前版本**所钉扎的验证路径（与补丁版本、内核线一致），并得到 **通过/失败** 的可判读结果。 +- **FR10**：**维护者**能够保存 **HDMI 相关试播** 的 **内核日志工件**，并使其可与 **路线图成功标准** 对照；**对外分享前**可按 **`audio_topology/COLLECT.md`** 等采集说明做**脱敏**（细则见 **Non-Functional Requirements**）。 + +### 对照与参考 + +- **FR11**：**维护者或协作者**能够在 **不构建内核** 的前提下，使用 **文本级对照材料**（如 **`patches/ubuntu-hwe-6.17/reference/`**）支撑讨论；**无完整源码树**时仍可就 **`reference/`**、补丁与 **PR** 进行文本级协作。 +- **FR12**：**维护者**在 **双源码树可用**时，能够执行或引用 **ChromiumOS 与 Ubuntu 树之间的对照流程**（脚本或操作说明）。 +- **FR13**：**读者**能够找到 **ChromiumOS 5.15** 与 **`kernel-src`** 的**约定路径与入口说明**。 + +### 协作与进度 + +- **FR14**：**维护者**能够在 **`WORK_PROGRESS`** 中更新 **阶段结论、日期与阻塞项**。 +- **FR15**：**协作者**能够根据 **`WORK_PROGRESS`** 判断 **预检是否通过**或 **缺哪类树/包**。 +- **FR16**：**只读使用者**能够使用 **信息采集清单** 组织 **最小信息包**，**而不自动触发**上游协同义务。 +- **FR17**：**维护者**在阶段或结论变更时，能够完成 **`WORK_PROGRESS` 与路线图**的**交叉引用更新**。 + +### 索引与可发现性 + +- **FR18**：**维护者**在新增或重组主题文档时，能够按约定**更新** **`docs/INDEX.md` / `REPO_INDEX.md`**（或等效索引），避免孤岛页；**大段摘录上游文档或代码**时须**标明来源与许可证**（与 **developer_tool** 许可证约定一致）。 +- **FR19**：**协作者**能够从索引或脚本表**定位**与 **HWE / HDMI** 相关的 **脚本及用途**。 + +### 范围分界与上游（条件触发） + +- **FR20**：**读者**能够从索引或总览中识别 **Linux HDMI 主线文档**与 **Windows / 其他平台** 文档的**入口分界**（本 PRD **不**交付 Windows 方案）。 +- **FR21**：**维护者**在 **Success Criteria 所定义的验证结论已具备**之后，能够准备 **上游复现/对外沟通** 所需材料（此前**无**必须完成的对外义务）。 + +## Non-Functional Requirements + +### Privacy & Data Handling + +- **NFR1**：**对外分享** dmesg / 采集前，**维护者**须按 **`audio_topology/COLLECT.md`**（或等效采集说明）对 **序列号、MAC、账号** 等可识别信息做**脱敏或裁剪**；**默认**不将未脱敏日志提交至公共 issue。**例外**：若 **上游 / issue** 在 **`UPSTREAM_SOF_Kaisa_HDMI_REPRO.md`** 等清单中**明确要求**某工具的全量输出，按该清单执行，并遵循**最小必要**与清单内说明。 +- **NFR2**：**维护者**不得在仓库中提交 **密钥、Cookie、个人账号口令** 等机密；脚本与文档示例使用占位符。 + +### Documentation & Consistency + +- **NFR3**：面向用户/协作者的说明须与 **`docs/meta/DOCUMENTATION_STYLE.md`** 及 **`project-context`** 中的语言与入口约定一致（**简体中文**为主，与 BMM 配置一致）。 +- **NFR4**：**新增主题文档**或**改变 `docs/` 导航结构**时，须在**同一变更或紧随提交**中**同步** **`docs/INDEX.md` / `REPO_INDEX.md`**（或等效索引）；**仅修改根 README 短链**且**不改变主题归属**时，**不**强制全文重链（与 **FR18** 配套）。 + +### Reproducibility & Environment + +- **NFR5**：**验证脚本**在文档声明的**环境基线**（**Ubuntu 24.04 + 与文档一致的 `linux-hwe-6.17` 线**）且**前置条件满足**时，须具备**可重复**的通过/失败语义；**其它发行版或内核线**仅作类比，**不声称**满足 **FR9** 的验证义务，除非在 **`WORK_PROGRESS`** 或文档中**单独记录**环境与结论。 +- **NFR6**：**完整内核构建**的耗时与磁盘占用**不作为**用户响应时间类指标；在文档与 **`WORK_PROGRESS`** 中**如实记录**典型量级与失败模式（如并行、空间不足）。 + +### Licensing & Attribution + +- **NFR7**：进入本仓库**版本库**的上游**摘录**（含大段文档或代码）须**可追溯来源与许可证**；**优先**以 **链接 + 短引** 替代长粘贴；**合理使用**边界按 **`developer_tool`** 与上游许可执行。 diff --git a/_bmad-output/project-context.md b/_bmad-output/project-context.md new file mode 100644 index 0000000000..304eb60ba1 --- /dev/null +++ b/_bmad-output/project-context.md @@ -0,0 +1,88 @@ +--- +project_name: chromebox_10th_audio_driver +user_name: Jack +date: '2026-04-05T11:26:09+08:00' +sections_completed: + - technology_stack + - language_and_scripts + - kernel_patches + - documentation + - verification_and_testing + - workflow_and_git + - critical_dont_miss +document_note: GPC 一次性生成（棕地：文档/脚本/内核补丁）；非 Web 应用仓库 +--- + +# 面向 AI 代理的项目上下文（Project Context） + +本文件列出在本仓库内**实现与修改**时必须遵守的规则与易错点；优先写「代理容易忽略」的约定，避免重复常识。 + +--- + +## 技术栈与版本 + +| 类别 | 内容 | +|------|------| +| **宿主与内核实验** | 文档以 **Ubuntu 24.04 + linux-hwe-6.17** 为基准；真机验证需与 **`uname -r`** 及 **`kernel-src` 树版本**一致。 | +| **语言** | **Bash**（`set -e` 等以现有脚本为准）、**Markdown**（文档主体）。 | +| **内核工件** | **Git 格式的补丁**（`patches/ubuntu-hwe-6.17/0001–0003`）；对照树可选 **`chromiumos_kernel/v5.15`**、**`kernel-src/linux-hwe-*`**（体积大，常不提交）。 | + +### 源码与对照树（BMad PRD / 技术分析须覆盖） + +以下目录为仓库约定位置；**Create PRD** 或源码级需求分析时，应视为与文档同级的输入范围（整树过大时可只登记路径 + 已检入的索引笔记）。 + +| 路径 | 角色 | +|------|------| +| **`chromiumos_kernel/v5.15/`** | **ChromiumOS** 第三方 Linux 内核 **5.15** 分支（克隆说明见 [docs/meta/WORK_PROGRESS.md](../docs/meta/WORK_PROGRESS.md)）。用于 HDMI / SOF / machine 层与 Ubuntu HWE 的**对照基准**。关键文件索引：[docs/linux-hdmi/CHROMEOS_KAISA_AUDIO_KERNEL_PATHS.md](../docs/linux-hdmi/CHROMEOS_KAISA_AUDIO_KERNEL_PATHS.md)。 | +| **`kernel-src/`** | **Ubuntu** `linux-hwe-*` 源码树放置与构建说明（**非** ChromiumOS 用户态；与上表配对做双树 diff）。入口：[kernel-src/README.md](../kernel-src/README.md)；对称笔记：[docs/linux-hdmi/KERNEL_SRC_LINUX_HWE617_HDMI_3.5MM_PATHS.md](../docs/linux-hdmi/KERNEL_SRC_LINUX_HWE617_HDMI_3.5MM_PATHS.md)。 | +| **非核心** | 无 `package.json` 类主应用；不要默认引入 Node/Python 项目脚手架。 | + +--- + +## 关键实现规则 + +### 文档 + +- **体例与全项目改写约定**：[**docs/meta/DOCUMENTATION_STYLE.md**](../docs/meta/DOCUMENTATION_STYLE.md)（语言、命名、进度类分工）。 +- **唯一根 README**：仓库根目录仅 **[README.md](../README.md)**；新增主题文档须在 **[docs/INDEX.md](../docs/INDEX.md)**（及需要时 **[REPO_INDEX.md](../REPO_INDEX.md)**）增加链接，避免孤岛页。 +- **路线图与进度**：Linux HDMI 以 **[docs/linux-hdmi/Linux_HDMI_Audio_Roadmap.md](../docs/linux-hdmi/Linux_HDMI_Audio_Roadmap.md)** 为准；交接与阶段结论同步 **[docs/meta/WORK_PROGRESS.md](../docs/meta/WORK_PROGRESS.md)**。 +- **语言**：`document_output_language` 为中文时，用户面向说明以**简体中文**为主，与 **`_bmad/bmm/config.yaml`** 一致。 + +### Shell 脚本（`scripts/`） + +- 新脚本放在 **`scripts/`**，命名与现有 **`ubuntu-hwe-617-build.sh`**、**`verify-ubuntu-hwe617-patches-runtime.sh`** 风格一致（小写、连字符）。 +- 依赖 **`kernel-src`** 或 **`PATCH=`** 路径时，在脚本注释或 `--help` 中写明**工作目录**（通常仓库根）。 + +### 内核补丁（`patches/ubuntu-hwe-6.17/`） + +- **应用顺序**：先 **0001**，再 **0002**；**0003** 可选且与 0001/0002 **独立**（仅 `hda-dai.c`）。每次 **`apply`** 用环境变量 **`PATCH=...`** 指向**单文件**，见 **[README.md](../patches/ubuntu-hwe-6.17/README.md)**。 +- **0002 日志**：需 **`sof_debug` 含 bit 11（2048）** 与 **`dynamic_debug`**（如 `file ipc3-pcm.c +p`）；属诊断增强，**不改变** IPC 载荷语义。 +- **0003**：依赖 **`dynamic_debug`**（`hda-dai.c +p`）；用于观察 **`stream_tag`** 等，**不改变** DMA 行为。 +- 设计新补丁前应对照 **ChromeOS 5.15 ↔ 6.17** 流程与 **[DIFF_SUMMARY.txt](../patches/ubuntu-hwe-6.17/DIFF_SUMMARY.txt)**，避免重复已否决路径。 + +### 验证与「测试」 + +- 补丁验证流程以 **[VERIFY_PATCHES.md](../patches/ubuntu-hwe-6.17/VERIFY_PATCHES.md)** 与 **`scripts/verify-ubuntu-hwe617-patches-runtime.sh`** 为准；成功时脚本可输出 **`VERIFY_OK`**。 +- **`RUN_HDMI_TEST=0`** 可跳过 **`speaker-test`**；HDMI 设备号因机而异，可用环境变量（如脚本中的 HDMI plughw）覆盖默认值。 +- **现象区分**：**`plughw:0,2` 不一定是 3.5mm**；耳机/模拟口以 **`aplay -L`** 与采集文档为准，避免在文档中写死错误映射。 + +### 工作流与 Git + +- 变更范围：**最小必要 diff**；不顺带大重构无关文件。 +- 大目录（**`kernel-src/`**、完整 **`chromiumos_kernel/`**）遵守 **`.gitignore`**，勿提交二进制或整树 tarball。 + +--- + +## 严禁遗漏（易错） + +1. **文档入口**：改 `docs/` 结构时同步 **INDEX / REPO_INDEX**，否则代理与用户都会迷路。 +2. **内核版本一致性**：补丁说明、**dmesg**、**`verify-*`** 必须与**当前运行的内核构建**一致。 +3. **勿把本仓库当成前端项目**：无 ESLint/React 约定；规则以 **Bash、内核补丁、Markdown** 为准。 +4. **HDMI 仍无声时**：以 **[FIX_PLAN_HDMI_FROM_SOURCE_ANALYSIS.md](../docs/linux-hdmi/FIX_PLAN_HDMI_FROM_SOURCE_ANALYSIS.md)** 与路线图阶段为准，避免在未读源码对照的情况下硬改路由。 + +--- + +## 维护 + +- 与 **BMad** 并列的索引：**[docs/index.md](../docs/index.md)**（小写，AI 检索）、**[docs/INDEX.md](../docs/INDEX.md)**（人用总目）。 +- 更新本文件时机：变更补丁策略、验证方式或文档入口约定时。 diff --git a/_bmad/_config/files-manifest.csv b/_bmad/_config/files-manifest.csv index 19d62eacc7..7f2b57a861 100644 --- a/_bmad/_config/files-manifest.csv +++ b/_bmad/_config/files-manifest.csv @@ -1,6 +1,6 @@ type,name,module,path,hash "csv","agent-manifest","_config","_config/agent-manifest.csv","28fe3ddda5e1b4639ea81334b6837ff3ceb739dc578f7775fff7135982920c68" -"yaml","manifest","_config","_config/manifest.yaml","7439f803546099b8f95e29306fcff8725a199529f132ec12be87c14be42dd16e" +"yaml","manifest","_config","_config/manifest.yaml","18698166470a9230a96230c6f9540c6a0cebc257ad7a858e1d57ec91f26a9093" "csv","module-help","bmb","bmb/bmad-bmb-setup/assets/module-help.csv","a32a9e9c6b7e16c9e0bd6a837aeafcf41afad79c3f7c2a8de2c946d0c871d886" "csv","module-help","bmb","bmb/bmad-module-builder/assets/setup-skill-template/assets/module-help.csv","e5b0818d33b4d59e4813d3008c9f5c3179d2c8407dd9ee0e96436ca41fa69594" "csv","module-help","bmb","bmb/module-help.csv","a32a9e9c6b7e16c9e0bd6a837aeafcf41afad79c3f7c2a8de2c946d0c871d886" @@ -81,7 +81,7 @@ type,name,module,path,hash "py","test-scaffold-standalone-module","bmb","bmb/bmad-module-builder/scripts/tests/test-scaffold-standalone-module.py","f2d9a2b67a94cb24c4b88d75650ae9b5e69a157886c4a4b15e5d2c09dc685935" "py","test-validate-module","bmb","bmb/bmad-module-builder/scripts/tests/test-validate-module.py","6e456ef3411691cdfca399841282c02b3755888844ad52bd085453257b31fe64" "py","validate-module","bmb","bmb/bmad-module-builder/scripts/validate-module.py","dc30874f9a4fc224e9329ecb4fd8e66c2bbbe75802cab2793b453629d8cb9efc" -"yaml","config","bmb","bmb/config.yaml","63587a47286265898f24ff20e370113db11c46da878e953f05ba809218696762" +"yaml","config","bmb","bmb/config.yaml","e61a3b92fa781256d5e7e4d54cb2f39742fdcd21f24b73669c12d6421c054d8e" "yaml","module","bmb","bmb/bmad-bmb-setup/assets/module.yaml","d9cb53ff118c5c45d393b5a0f3498cdfc20d7f47acf491970157d36a7e9f5462" "yaml","module","bmb","bmb/bmad-module-builder/assets/setup-skill-template/assets/module.yaml","9ebacf189dcd2e353509bfa0fa70c90b84d5fe749022a3571e5321598e1ae9fa" "csv","documentation-requirements","bmm","bmm/1-analysis/bmad-document-project/documentation-requirements.csv","d1253b99e88250f2130516b56027ed706e643bfec3d99316727a4c6ec65c6c1d" @@ -314,7 +314,7 @@ type,name,module,path,hash "yaml","bmad-skill-manifest","bmm","bmm/4-implementation/bmad-agent-qa/bmad-skill-manifest.yaml","00e680311146df8b7e4f1da1ecf88ff7c6da87049becb3551139f83fca1a3563" "yaml","bmad-skill-manifest","bmm","bmm/4-implementation/bmad-agent-quick-flow-solo-dev/bmad-skill-manifest.yaml","6c3c47eb61554b1d8cd9ccdf202ffff2f20bb8ab7966356ae82825dc2ae3171f" "yaml","bmad-skill-manifest","bmm","bmm/4-implementation/bmad-agent-sm/bmad-skill-manifest.yaml","ac92ed5eb5dd6e2975fc9a2170ef2c6d917872521979d349ec5f5a14e323dbf6" -"yaml","config","bmm","bmm/config.yaml","4b72023dc561cc32c6191e38d211bc52e7a80f7552db3fc14a70c08d0f2ff77a" +"yaml","config","bmm","bmm/config.yaml","8b2b141e8ef2c6c533d848ecd4a3b8e82f47c054b699d23a944afcd9de9f0186" "yaml","sprint-status-template","bmm","bmm/4-implementation/bmad-sprint-planning/sprint-status-template.yaml","b46a7bfb7d226f00bd064f111e527eee54ad470d177382a9a15f1a6dde21544c" "csv","design-methods","cis","cis/skills/bmad-cis-design-thinking/design-methods.csv","6735e9777620398e35b7b8ccb21e9263d9164241c3b9973eb76f5112fb3a8fc9" "csv","innovation-frameworks","cis","cis/skills/bmad-cis-innovation-strategy/innovation-frameworks.csv","9a14473b1d667467172d8d161e91829c174e476a030a983f12ec6af249c4e42f" @@ -351,7 +351,7 @@ type,name,module,path,hash "yaml","bmad-skill-manifest","cis","cis/skills/bmad-cis-innovation-strategy/bmad-skill-manifest.yaml","ea1b058a23cd4fb442f2e7bc7a3a871b73391c0d18c32ddad020dd56b20425ee" "yaml","bmad-skill-manifest","cis","cis/skills/bmad-cis-problem-solving/bmad-skill-manifest.yaml","ea1b058a23cd4fb442f2e7bc7a3a871b73391c0d18c32ddad020dd56b20425ee" "yaml","bmad-skill-manifest","cis","cis/skills/bmad-cis-storytelling/bmad-skill-manifest.yaml","ea1b058a23cd4fb442f2e7bc7a3a871b73391c0d18c32ddad020dd56b20425ee" -"yaml","config","cis","cis/config.yaml","68fda5efd59d3176b30f7fb6aed671005ec293f106ced8c4c76f119efcdcaaf3" +"yaml","config","cis","cis/config.yaml","a8b7ba5c6f61bcdd9506daef3f253c871815bfadf6c7273e2db1a047afd0c02b" "csv","brain-methods","core","core/bmad-brainstorming/brain-methods.csv","0ab5878b1dbc9e3fa98cb72abfc3920a586b9e2b42609211bb0516eefd542039" "csv","methods","core","core/bmad-advanced-elicitation/methods.csv","e08b2e22fec700274982e37be608d6c3d1d4d0c04fa0bae05aa9dba2454e6141" "csv","module-help","core","core/module-help.csv","79cb3524f9ee81751b6faf549e67cbaace7fa96f71b93b09db1da8e29bf9db81" @@ -390,7 +390,7 @@ type,name,module,path,hash "py","bmad_init","core","core/bmad-init/scripts/bmad_init.py","1b09aaadd599d12ba11bd61e86cb9ce7ce85e2d83f725ad8567b99ff00cbceeb" "py","test_analyze_sources","core","core/bmad-distillator/scripts/tests/test_analyze_sources.py","d90525311f8010aaf8d7d9212a370468a697866190bae78c35d0aae9b7f23fdf" "py","test_bmad_init","core","core/bmad-init/scripts/tests/test_bmad_init.py","84daa73b4e6adf4adbf203081a570b16859e090104a554ae46a295c9af3cb9bb" -"yaml","config","core","core/config.yaml","2c1022c2b0bbc48edc8f2569329b8ceee20f9f36d1757b2774950f4388b49704" +"yaml","config","core","core/config.yaml","49f036f8bec7ca936587eef536785ae148b44aa195dd7ce78d59dc90205efffa" "yaml","core-module","core","core/bmad-init/resources/core-module.yaml","eff85de02831f466e46a6a093d860642220295556a09c59e1b7f893950a6cdc9" "csv","documentation-requirements","gds","gds/workflows/gds-document-project/documentation-requirements.csv","d1253b99e88250f2130516b56027ed706e643bfec3d99316727a4c6ec65c6c1d" "csv","domain-complexity","gds","gds/workflows/2-design/create-prd/data/domain-complexity.csv","f775f09fb4dc1b9214ca22db4a3994ce53343d976d7f6e5384949835db6d2770" @@ -752,7 +752,7 @@ type,name,module,path,hash "yaml","bmad-skill-manifest","gds","gds/workflows/gds-quick-flow/gds-quick-dev/bmad-skill-manifest.yaml","ea1b058a23cd4fb442f2e7bc7a3a871b73391c0d18c32ddad020dd56b20425ee" "yaml","bmad-skill-manifest","gds","gds/workflows/gds-quick-flow/gds-quick-dev-new-preview/bmad-skill-manifest.yaml","ea1b058a23cd4fb442f2e7bc7a3a871b73391c0d18c32ddad020dd56b20425ee" "yaml","bmad-skill-manifest","gds","gds/workflows/gds-quick-flow/gds-quick-spec/bmad-skill-manifest.yaml","ea1b058a23cd4fb442f2e7bc7a3a871b73391c0d18c32ddad020dd56b20425ee" -"yaml","config","gds","gds/config.yaml","9b3f4369b8041905124f1b9e98084945a66db42fcfbacc8859e87ab8042cc4a4" +"yaml","config","gds","gds/config.yaml","7b1cdf007d62fd58859c3fa18e21f91ba9b679a2ab35f3581acaf166e65e061a" "yaml","decision-catalog","gds","gds/workflows/3-technical/gds-game-architecture/decision-catalog.yaml","9b11cc159e4e74e7c3c9782bc3772ca7fc9192afee712c4eed0938994bbc3412" "yaml","engine-mcps","gds","gds/workflows/3-technical/gds-game-architecture/engine-mcps.yaml","5a2388ec24cb3eaf94273dd31ff98792aa02659cdaa1e9800af7e507e1cd6e77" "yaml","sprint-status-template","gds","gds/workflows/4-production/gds-sprint-planning/sprint-status-template.yaml","0d7fe922f21d4f00e538c265ff90e470c3e2eca761e663d84b7a1320b2f25980" @@ -1330,7 +1330,7 @@ type,name,module,path,hash "yaml","bmad-skill-manifest","tea","tea/workflows/testarch/bmad-testarch-test-design/bmad-skill-manifest.yaml","ea1b058a23cd4fb442f2e7bc7a3a871b73391c0d18c32ddad020dd56b20425ee" "yaml","bmad-skill-manifest","tea","tea/workflows/testarch/bmad-testarch-test-review/bmad-skill-manifest.yaml","ea1b058a23cd4fb442f2e7bc7a3a871b73391c0d18c32ddad020dd56b20425ee" "yaml","bmad-skill-manifest","tea","tea/workflows/testarch/bmad-testarch-trace/bmad-skill-manifest.yaml","ea1b058a23cd4fb442f2e7bc7a3a871b73391c0d18c32ddad020dd56b20425ee" -"yaml","config","tea","tea/config.yaml","b24b534880ace78550479cd5647af3799457131339d4cd502dc83c511e193471" +"yaml","config","tea","tea/config.yaml","f709764f6fc1aa0a6efe012cd3327347f5f6e3bb4cdfebc9345b0fbd79835d9e" "yaml","curriculum","tea","tea/workflows/testarch/bmad-teach-me-testing/data/curriculum.yaml","08d70f30f848537a5dcf138128bde0665d203236bab470d87e33791e4b3d3eee" "yaml","github-actions-template","tea","tea/workflows/testarch/bmad-testarch-ci/github-actions-template.yaml","dbf33e640d9017650b5eed7af28f8914172a0dcfd04552a0342ef61b459b28c2" "yaml","gitlab-ci-template","tea","tea/workflows/testarch/bmad-testarch-ci/gitlab-ci-template.yaml","af7d7e50802c1f4cbdfdfc20b0cd8a86ba5cec5b9eaedaec29e4c8aec6049ae6" @@ -1980,7 +1980,7 @@ type,name,module,path,hash "yaml","bmad-skill-manifest","wds","wds/workflows/wds-6-asset-generation/bmad-skill-manifest.yaml","ea1b058a23cd4fb442f2e7bc7a3a871b73391c0d18c32ddad020dd56b20425ee" "yaml","bmad-skill-manifest","wds","wds/workflows/wds-7-design-system/bmad-skill-manifest.yaml","ea1b058a23cd4fb442f2e7bc7a3a871b73391c0d18c32ddad020dd56b20425ee" "yaml","bmad-skill-manifest","wds","wds/workflows/wds-8-product-evolution/bmad-skill-manifest.yaml","ea1b058a23cd4fb442f2e7bc7a3a871b73391c0d18c32ddad020dd56b20425ee" -"yaml","config","wds","wds/config.yaml","77092ebe1cc887e67d48cc8da0e210465b99bc573bb8f2d09113075024b758be" +"yaml","config","wds","wds/config.yaml","0ffa2039083f9c305dfb77413860f791be53157a7af52f003987a7e61f0f1bd5" "yaml","design-delivery.template","wds","wds/workflows/wds-4-ux-design/templates/design-delivery.template.yaml","90f89ab05cfedb482866af69bfb78e4b466b3772ce99ebca835a1b0790f2c957" "yaml","platform-requirements.template","wds","wds/workflows/wds-0-project-setup/resources/wds-1-project-brief/templates/platform-requirements.template.yaml","35c1c99f144f6ab59a20257f735a25bdea6ebfff21854b7cf62f361fcf2643e6" "yaml","platform-requirements.template","wds","wds/workflows/wds-1-project-brief/templates/platform-requirements.template.yaml","35c1c99f144f6ab59a20257f735a25bdea6ebfff21854b7cf62f361fcf2643e6" diff --git a/_bmad/_config/ides/cursor.yaml b/_bmad/_config/ides/cursor.yaml index f8b623ccd3..5e38b28008 100644 --- a/_bmad/_config/ides/cursor.yaml +++ b/_bmad/_config/ides/cursor.yaml @@ -1,5 +1,5 @@ ide: cursor configured_date: 2026-04-04T12:36:19.353Z -last_updated: 2026-04-04T12:41:26.091Z +last_updated: 2026-04-05T03:20:51.740Z configuration: _noConfigNeeded: true diff --git a/_bmad/_config/manifest.yaml b/_bmad/_config/manifest.yaml index 89e928ee8c..92c991aa29 100644 --- a/_bmad/_config/manifest.yaml +++ b/_bmad/_config/manifest.yaml @@ -1,54 +1,54 @@ installation: version: 6.2.2 installDate: 2026-04-04T12:05:56.591Z - lastUpdated: 2026-04-04T12:41:25.564Z + lastUpdated: 2026-04-05T03:20:51.168Z modules: - name: core version: 6.2.2 installDate: 2026-04-04T12:05:41.608Z - lastUpdated: 2026-04-04T12:40:51.147Z + lastUpdated: 2026-04-05T03:20:44.113Z source: built-in npmPackage: null repoUrl: null - name: bmm version: 6.2.2 installDate: 2026-04-04T12:35:44.347Z - lastUpdated: 2026-04-04T12:40:51.147Z + lastUpdated: 2026-04-05T03:20:44.113Z source: built-in npmPackage: null repoUrl: null - name: bmb - version: 1.4.0 + version: 1.1.0 installDate: 2026-04-04T12:03:34.779Z - lastUpdated: 2026-04-04T12:41:01.622Z + lastUpdated: 2026-04-05T03:20:45.522Z source: external npmPackage: bmad-builder repoUrl: https://github.com/bmad-code-org/bmad-builder - name: cis version: 0.1.9 installDate: 2026-04-04T12:03:51.321Z - lastUpdated: 2026-04-04T12:41:12.658Z + lastUpdated: 2026-04-05T03:20:46.712Z source: external npmPackage: bmad-creative-intelligence-suite repoUrl: https://github.com/bmad-code-org/bmad-module-creative-intelligence-suite - name: gds version: 0.2.2 installDate: 2026-04-04T12:35:48.758Z - lastUpdated: 2026-04-04T12:41:14.172Z + lastUpdated: 2026-04-05T03:20:47.809Z source: external npmPackage: bmad-game-dev-studio repoUrl: https://github.com/bmad-code-org/bmad-module-game-dev-studio.git - name: tea version: 1.7.2 installDate: 2026-04-04T12:03:57.228Z - lastUpdated: 2026-04-04T12:41:15.220Z + lastUpdated: 2026-04-05T03:20:48.928Z source: external npmPackage: bmad-method-test-architecture-enterprise repoUrl: https://github.com/bmad-code-org/bmad-method-test-architecture-enterprise - name: wds version: 0.3.1 installDate: 2026-04-04T12:05:22.032Z - lastUpdated: 2026-04-04T12:41:25.564Z + lastUpdated: 2026-04-05T03:20:51.168Z source: external npmPackage: bmad-method-wds-expansion repoUrl: https://github.com/bmad-code-org/bmad-method-wds-expansion diff --git a/_bmad/bmb/config.yaml b/_bmad/bmb/config.yaml index 90fcf396fb..c738dce3d0 100644 --- a/_bmad/bmb/config.yaml +++ b/_bmad/bmb/config.yaml @@ -1,7 +1,7 @@ # BMB Module Configuration # Generated by BMAD installer # Version: 6.2.2 -# Date: 2026-04-04T12:40:50.996Z +# Date: 2026-04-05T03:20:43.963Z bmad_builder_output_folder: "{project-root}/skills" bmad_builder_reports: "{project-root}/skills/reports" diff --git a/_bmad/bmm/config.yaml b/_bmad/bmm/config.yaml index 1b864d5329..ad5b381a78 100644 --- a/_bmad/bmm/config.yaml +++ b/_bmad/bmm/config.yaml @@ -1,7 +1,7 @@ # BMM Module Configuration # Generated by BMAD installer # Version: 6.2.2 -# Date: 2026-04-04T12:40:50.997Z +# Date: 2026-04-05T03:20:43.964Z project_name: chromebox_10th_audio_driver user_skill_level: intermediate diff --git a/_bmad/cis/config.yaml b/_bmad/cis/config.yaml index 24b952b043..12cd5287ed 100644 --- a/_bmad/cis/config.yaml +++ b/_bmad/cis/config.yaml @@ -1,7 +1,7 @@ # CIS Module Configuration # Generated by BMAD installer # Version: 6.2.2 -# Date: 2026-04-04T12:40:50.997Z +# Date: 2026-04-05T03:20:43.965Z visual_tools: intermediate diff --git a/_bmad/core/config.yaml b/_bmad/core/config.yaml index 5da0375ade..c9fbfcf627 100644 --- a/_bmad/core/config.yaml +++ b/_bmad/core/config.yaml @@ -1,7 +1,7 @@ # CORE Module Configuration # Generated by BMAD installer # Version: 6.2.2 -# Date: 2026-04-04T12:40:50.998Z +# Date: 2026-04-05T03:20:43.965Z user_name: Jack communication_language: Chinese diff --git a/_bmad/gds/config.yaml b/_bmad/gds/config.yaml index ece685fe8e..54851ccffb 100644 --- a/_bmad/gds/config.yaml +++ b/_bmad/gds/config.yaml @@ -1,7 +1,7 @@ # GDS Module Configuration # Generated by BMAD installer # Version: 6.2.2 -# Date: 2026-04-04T12:40:50.998Z +# Date: 2026-04-05T03:20:43.966Z project_name: chromebox_10th_audio_driver game_dev_experience: intermediate diff --git a/_bmad/tea/config.yaml b/_bmad/tea/config.yaml index e12303e344..87334c6ac2 100644 --- a/_bmad/tea/config.yaml +++ b/_bmad/tea/config.yaml @@ -1,7 +1,7 @@ # TEA Module Configuration # Generated by BMAD installer # Version: 6.2.2 -# Date: 2026-04-04T12:40:50.999Z +# Date: 2026-04-05T03:20:43.966Z test_artifacts: "{project-root}/_bmad-output/test-artifacts" tea_use_playwright_utils: true diff --git a/_bmad/wds/config.yaml b/_bmad/wds/config.yaml index 8b0a3eb1fa..868aefee2b 100644 --- a/_bmad/wds/config.yaml +++ b/_bmad/wds/config.yaml @@ -1,7 +1,7 @@ # WDS Module Configuration # Generated by BMAD installer # Version: 6.2.2 -# Date: 2026-04-04T12:40:51.000Z +# Date: 2026-04-05T03:20:43.967Z project_knowledge: "{project-root}/docs" project_type: digital_product diff --git a/audio_topology/ANALYSIS_Audio.md b/audio_topology/ANALYSIS_Audio.md index 465061e30f..3ef2a24b17 100644 --- a/audio_topology/ANALYSIS_Audio.md +++ b/audio_topology/ANALYSIS_Audio.md @@ -2,6 +2,8 @@ 基于 `collected/` 目录下采集数据的对比，分析 Chromebox 10 代（Kaisa）在三平台上的音频差异。 +**问题两行表**与根目录 [README.md](../README.md) 对齐（维护时优先改 README，再视需要同步本节 §〇）。 + > **说明**：Linux 采集时 HDMI1 已插入显示器。dmesg 中 -5 错误出现在 pcm3（HDMI2）、pcm4（HDMI3），pcm2（HDMI1）是否有相同问题需结合实际接法确认。 --- diff --git a/audio_topology/COLLECT.md b/audio_topology/COLLECT.md index 8028ca1f6c..da622be63a 100644 --- a/audio_topology/COLLECT.md +++ b/audio_topology/COLLECT.md @@ -1,6 +1,16 @@ # 音频拓扑收集 -用于 C1a/C1b/C1c 任务：收集 Chromebox 10 代在 Linux / Windows / 原生 ChromeOS 下的音频硬件拓扑信息。 +**体例**：[../docs/meta/DOCUMENTATION_STYLE.md](../docs/meta/DOCUMENTATION_STYLE.md)。任务编号 **C1** 与根 [README.md](../README.md) 任务表一致。 + +用于 C1a/C1b/C1c：收集 Chromebox 10 代在 Linux / Windows / 原生 ChromeOS 下的音频拓扑。 + +## 对外分享与脱敏（NFR1） + +采集输出可能含 **hostname、MAC、序列号、账号** 等。在并入**公共 issue**或外发前，按 **本文** 与 **[UPSTREAM_SOF_Kaisa_HDMI_REPRO.md](../docs/linux-hdmi/UPSTREAM_SOF_Kaisa_HDMI_REPRO.md)** 做裁剪或脱敏；**默认**不贴未脱敏全量日志。若上游清单**明确要求**某工具全量输出，按该清单执行并遵循 **最小必要**。 + +## HDMI 试播日志工件（FR10） + +**HDMI 相关** dmesg、trace、脚本输出建议保存到 **`audio_topology/collected/`**（命名与 [README_TRACE_KAISA.md](collected/README_TRACE_KAISA.md) 约定一致），便于与 [路线图 · § 四、成功标准](../docs/linux-hdmi/Linux_HDMI_Audio_Roadmap.md) 对照。 ## 目录结构 diff --git a/audio_topology/OPERATION_Force_Intel_Signed_Firmware.md b/audio_topology/OPERATION_Force_Intel_Signed_Firmware.md index 5b5c984020..03f799c302 100644 --- a/audio_topology/OPERATION_Force_Intel_Signed_Firmware.md +++ b/audio_topology/OPERATION_Force_Intel_Signed_Firmware.md @@ -1,12 +1,14 @@ # 操作说明：强制 Linux 使用 intel-signed 固件 -针对 Chromebox 10 代（Kaisa）在 Linux 下 HDMI 无声、`STREAM_PCM_PARAMS ipc failed (-5)` 的问题，尝试强制使用 intel-signed 固件（ChromeOS 上可正常工作的版本）。 +**体例**：[../docs/meta/DOCUMENTATION_STYLE.md](../docs/meta/DOCUMENTATION_STYLE.md)。**结论（仅换固件不能单独恢复 HDMI）**见 [Linux_HDMI_Audio_Roadmap.md](../docs/linux-hdmi/Linux_HDMI_Audio_Roadmap.md) §二、[ANALYSIS_Audio.md](ANALYSIS_Audio.md)；本文只写**操作**。 + +在 HDMI 无声、`STREAM_PCM_PARAMS` 失败场景下，尝试强制 **intel-signed** 固件路径（Chrome 常用）。 --- ## 背景说明 -- **当前现象**：Linux 加载 `intel/sof/community/sof-cml.ri`（实际通过 `sof-cml.ri.zst -> sof-cnl.ri.zst` 加载），ChromeOS 使用 `intel/sof/intel-signed/` 下的对应固件 +- **现象**：Linux 常加载 `community/sof-cml.ri`（经 `sof-cml.ri.zst` → `sof-cnl.ri.zst`）；ChromeOS 可用 `intel-signed/` - **原因**：内核在检测到 Google Chromebook/BIOS 时，会通过 DMI 强制使用 community 路径（见 `sof-pci-dev.c` 中 `community_key_platforms`） - **建议**：先尝试**方式二**（替换文件）做快速验证；若有效且希望持久化，再考虑**方式一**（模块参数） diff --git a/audio_topology/REPAIR_Plan_Audio.md b/audio_topology/REPAIR_Plan_Audio.md index 53819fe59c..465d225719 100644 --- a/audio_topology/REPAIR_Plan_Audio.md +++ b/audio_topology/REPAIR_Plan_Audio.md @@ -1,23 +1,20 @@ # Chromebox 10 代（Kaisa）声音驱动修复方案 -Coreboot 刷机后，Linux 与 Windows 的音频问题**表现相反**，需**分平台**处理。本文给出目标、原因概要、推荐执行顺序；细节与命令见各专项文档。 +Coreboot 刷机后，Linux 与 Windows 的音频问题**表现相反**，需**分平台**处理。本文给出**目标与执行顺序**；现象两行表见根 [README.md](../README.md)，拓扑证据见 [ANALYSIS_Audio.md](ANALYSIS_Audio.md)。 -**对比分析**：[ANALYSIS_Audio.md](ANALYSIS_Audio.md) +**Linux HDMI 主路线图**：[../docs/linux-hdmi/Linux_HDMI_Audio_Roadmap.md](../docs/linux-hdmi/Linux_HDMI_Audio_Roadmap.md) · **全索引**：[../docs/INDEX.md](../docs/INDEX.md) · **体例**：[../docs/meta/DOCUMENTATION_STYLE.md](../docs/meta/DOCUMENTATION_STYLE.md) + +与路线图冲突时以路线图为准并更新互链。 --- ## 目标状态 - -| 平台 | HDMI | 3.5mm | 插拔提示 | -| ------------- | ---- | ----- | ---- | -| **目标** | 有 | 有 | 有 | -| Linux（当前典型） | 无 | 有 | 有 | -| Windows（当前典型） | 有 | 无 | 无 | - -**Linux HDMI：分阶段路线图与未来步骤（主文档）**：[../docs/linux-hdmi/Linux_HDMI_Audio_Roadmap.md](../docs/linux-hdmi/Linux_HDMI_Audio_Roadmap.md) -**全仓库文档索引**：[../docs/INDEX.md](../docs/INDEX.md) -下文第一节保留具体操作顺序；与路线图冲突时以路线图为准并更新互链。 +| 平台 | HDMI | 3.5mm | 插拔提示 | +|------|------|-------|----------| +| **目标** | 有 | 有 | 有 | +| Linux（当前典型） | 无 | 有 | 有 | +| Windows（当前典型） | 有 | 无 | 无 | --- @@ -41,7 +38,7 @@ Coreboot 刷机后，Linux 与 Windows 的音频问题**表现相反**，需** 3. **固件实验（预期有限）** 用 intel-signed 覆盖 community 的 `sof-cnl.ri.zst` **在本项目已实测不能单独恢复 HDMI**；若仍要试参数/路径，见 [OPERATION_Force_Intel_Signed_Firmware.md](OPERATION_Force_Intel_Signed_Firmware.md)，并注意回退清单。 4. **自行维护内核（进阶 / 新补丁设计）** - 对照 ChromeOS 5.15 与 Ubuntu HWE 6.17：`set_idisp_hdmi_link()` 在 ChromeOS 使用 `dpcm_playback`，在 6.17 使用 **`playback_only`**——这是上游对 `struct snd_soc_dai_link` 的重命名，**不能**把 `dpcm_playback` 写回 6.17。历史上曾试 **0001/0002**（已自仓库移除；0002 真机未恢复 HDMI）。新补丁应基于 **`ipc3.c` / `pcm.c` / `hda-dai.c`** 等与 `STREAM_PCM_PARAMS` 链路的差异再写，见 [patches/ubuntu-hwe-6.17/DIFF_SUMMARY.txt](../patches/ubuntu-hwe-6.17/DIFF_SUMMARY.txt)、[ChromeOS 深度 diff 流程](../docs/kernel-build/OPERATION_ChromeOS_Kernel_Deep_Diff.md)、[Linux HDMI 重新分析](../docs/linux-hdmi/REANALYSIS_Linux_HDMI_Audio_Kaisa.md)。 + 对照 ChromeOS 5.15 与 Ubuntu HWE 6.17：`set_idisp_hdmi_link()` 在 ChromeOS 使用 `dpcm_playback`，在 6.17 使用 **`playback_only`**——这是上游对 `struct snd_soc_dai_link` 的重命名，**不能**把 `dpcm_playback` 写回 6.17。历史上曾试 **错误 TRIGGER 0002**（已从仓库删除）；现网补丁 **0001/0002（诊断）/0003** 见 [patches/ubuntu-hwe-6.17/README.md](../patches/ubuntu-hwe-6.17/README.md)。新功能性补丁应基于 **`ipc3.c` / `pcm.c` / `hda-dai.c`** 等与 `STREAM_PCM_PARAMS` 链路的差异再写，见 [DIFF_SUMMARY.txt](../patches/ubuntu-hwe-6.17/DIFF_SUMMARY.txt)、[ChromeOS 深度 diff 流程](../docs/kernel-build/OPERATION_ChromeOS_Kernel_Deep_Diff.md)、[REANALYSIS](../docs/linux-hdmi/REANALYSIS_Linux_HDMI_Audio_Kaisa.md)。 应用补丁与编译（**必须**显式指定 `PATCH`；无预置补丁时跳过 `apply`）： diff --git a/audio_topology/collected/PHASE_A_speaker-test_jack-Kaisa_20260404.md b/audio_topology/collected/PHASE_A_speaker-test_jack-Kaisa_20260404.md new file mode 100644 index 0000000000..ac4b3f491c --- /dev/null +++ b/audio_topology/collected/PHASE_A_speaker-test_jack-Kaisa_20260404.md @@ -0,0 +1,66 @@ +# 阶段 A：speaker-test 实测记录（jack-Kaisa） + +**日期**：2026-04-04（终端会话） · **主机**：jack-Kaisa +**对应计划**：[FIX_PLAN](../../docs/linux-hdmi/FIX_PLAN_HDMI_FROM_SOURCE_ANALYSIS.md) 阶段 A / [PHASE_A_DEVICE_MAP](../../docs/linux-hdmi/PHASE_A_DEVICE_MAP_CHROMEOS_COLLECTED.md)。**目的**：区分 ALSA **报错** vs **静默**。 + +**内核**（`uname -a`，与阶段 A 实测同一次会话）： + +``` +Linux jack-Kaisa 6.17.0-20-generic #20~24.04.1 SMP PREEMPT_DYNAMIC Sun Apr 5 06:33:32 CST 2026 x86_64 x86_64 x86_64 GNU/Linux +``` + +**后续（2026-04-05）**：机器已改为 **日常启动自编内核**，构建时 **`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`** 与上表仍相同，属常见（ABI 对齐）；请以 **`linux-image-unsigned-*` 已安装且 GRUB 默认项指向该 deb** 为准。上表 **speaker-test / dmesg grep** 为 **阶段 A 基线**；在编内核上 **复测 HDMI** 时建议另存 `collected/` 新文件并附 **`uname -a`**、**`dpkg -l | grep linux-image`**。 + +--- + +## 命令（示例） + +```bash +timeout 8 speaker-test -D plughw:0,N -c2 -t sine -f 1000 +``` + +其中 **`N`** 为下表 device。 + +--- + +## 结果 + +| plughw | ALSA 名称（`aplay -l`） | speaker-test 通道名 | 终端是否报错 | 听感 | +|--------|-------------------------|---------------------|--------------|------| +| **0,0** | Port1（3.5mm） | 左前方 / 右前方 | 否 | （未在本文记录；一般为模拟输出） | +| **0,2** | HDMI1 | Front Left / Front Right | 否 | **无声** | +| **0,3** | HDMI2 | Unknown / Unknown | 否 | **无声** | +| **0,4** | HDMI3 | Unknown / Unknown | 否 | **无声** | + +**结论**： + +- **0,2 / 0,3 / 0,4** 均为 **不报错、无 ALSA 打开失败**，但 **HDMI 无声音**（**静默**）。 +- **0,3 / 0,4** 显示 **Unknown** 可能与 **ELD/插拔/显示器识别** 有关；**0,2** 显示 **FL/FR** 仍无声，不改变「HDMI 整体失败」的总判断。 +- **阶段 A**：已排除「仅 PipeWire 选错 sink」作为主要矛盾（**直连 ALSA 仍无声**）。 +- **下一步**：按路线图进入 **阶段 B**——**HWE 6.17 自编内核 + 0001**，见 [FIX_PLAN_HDMI_FROM_SOURCE_ANALYSIS.md](../../docs/linux-hdmi/FIX_PLAN_HDMI_FROM_SOURCE_ANALYSIS.md)、[patches/ubuntu-hwe-6.17/README.md](../../patches/ubuntu-hwe-6.17/README.md)。 + +--- + +## 附：`aplay -l` 摘录（同会话） + +``` +card 0: sofrt5682 [sof-rt5682], device 0: Port1 (*) [] +card 0: sofrt5682 [sof-rt5682], device 2: HDMI1 (*) [] +card 0: sofrt5682 [sof-rt5682], device 3: HDMI2 (*) [] +card 0: sofrt5682 [sof-rt5682], device 4: HDMI3 (*) [] +``` + +## dmesg 补充（`6.17.0-20-generic`，播放 HDMI1 后） + +在 **`timeout 8 speaker-test -D plughw:0,2 ...`** 结束后执行： + +```bash +sudo dmesg | grep -iE 'STREAM_PCM|sof_ipc|HDMI|pcm[234]|ASoC error' +``` + +**结果**：**无输出**（上述模式在 **当前 dmesg 缓冲区** 内 **无匹配行**）。 + +**说明**： + +- 与「**终端无报错、但 HDMI 仍无声**」一致：**未在常用关键词下看到内核报错**。 +- **无匹配不等于** IPC/固件侧一定「完全正常」：日志可能被冲掉、级别不足、或需 **`dynamic_debug` / `sof_debug`** 才可见；阶段 B 可配合 [0002](../../patches/ubuntu-hwe-6.17/0002-ASoC-SOF-ipc3-pcm-dump-STREAM_PCM_PARAMS-fields.patch) 与 [OPERATION_Kaisa_SOF_HDMI_Trace.md](../../docs/linux-hdmi/OPERATION_Kaisa_SOF_HDMI_Trace.md) 再观测。 diff --git a/audio_topology/collected/README_TRACE_KAISA.md b/audio_topology/collected/README_TRACE_KAISA.md index 56d8b97036..173b2f3f06 100644 --- a/audio_topology/collected/README_TRACE_KAISA.md +++ b/audio_topology/collected/README_TRACE_KAISA.md @@ -1,6 +1,6 @@ # Kaisa：SOF 观测日志存放说明 -本目录用于存放 **jack-Kaisa 真机** 在开启 **dynamic_debug** 与 **`snd_sof sof_debug=0x800`** 后采集的 dmesg，用于分析 `STREAM_PCM_PARAMS` 失败时的 IPC 载荷。 +**操作规范**：[../../docs/linux-hdmi/OPERATION_Kaisa_SOF_HDMI_Trace.md](../../docs/linux-hdmi/OPERATION_Kaisa_SOF_HDMI_Trace.md)。本目录存 **jack-Kaisa** 在 **dynamic_debug** + **`sof_debug=0x800`** 下的 dmesg，供 **`STREAM_PCM_PARAMS`** IPC 载荷分析（非通用说明文）。 ## 症状基线（计划「下一处修改」分叉用，2026-04-05） diff --git a/audio_topology/collected/UPSTREAM_REPRO_PACKAGE_INDEX.md b/audio_topology/collected/UPSTREAM_REPRO_PACKAGE_INDEX.md index cfd5b1a91f..2953037a4f 100644 --- a/audio_topology/collected/UPSTREAM_REPRO_PACKAGE_INDEX.md +++ b/audio_topology/collected/UPSTREAM_REPRO_PACKAGE_INDEX.md @@ -1,6 +1,6 @@ # Kaisa HDMI / SOF：上游复现包就绪索引 -对应 **`docs/linux-hdmi/UPSTREAM_SOF_Kaisa_HDMI_REPRO.md`**。下列为本仓库**已有**材料，投递 SOF / alsa-devel 时可直接引用路径（按需附 `alsa-info` 与固件 sha256）。 +**清单正文与模板**：[../../docs/linux-hdmi/UPSTREAM_SOF_Kaisa_HDMI_REPRO.md](../../docs/linux-hdmi/UPSTREAM_SOF_Kaisa_HDMI_REPRO.md)。下列仅为本仓库**已有文件路径**索引（投递时按需附 `alsa-info`、sha256）。 | 材料 | 路径 / 命令 | |------|-------------| diff --git a/audio_topology/collected/dmesg_storyC_PATCHED_6.17.0-20-generic_jack-Kaisa_20260405_085924.txt b/audio_topology/collected/dmesg_storyC_PATCHED_6.17.0-20-generic_jack-Kaisa_20260405_085924.txt new file mode 100644 index 0000000000..191c52e2c1 --- /dev/null +++ b/audio_topology/collected/dmesg_storyC_PATCHED_6.17.0-20-generic_jack-Kaisa_20260405_085924.txt @@ -0,0 +1,41 @@ +# Story C — PATCHED（仅本次 ring buffer 内自 clear 后的记录） +# 主机: jack-Kaisa +# 时间: Sun, 05 Apr 2026 08:59:24 +0800 +# 内核: 6.17.0-20-generic +# auto: speaker-test 设备=plughw:0,2 退出码=0（124=timeout） +# +### dpkg（镜像包） +期望状态=未知(u)/安装(i)/删除(r)/清除(p)/保持(h) +| 状态=未安装(n)/已安装(i)/仅存配置(c)/仅解压缩(U)/配置失败(F)/不完全安装(H)/触发器等待(W)/触发器未决(T) +|/ 错误?=(无)/须重装(R) (状态，错误：大写=故障) +||/ 名称 版本 体系结构 描述 ++++-=============================-====================-============-================================= +rc linux-image-6.17.0-20-generic 6.17.0-20.20~24.04.1 amd64 Signed kernel image generic +期望状态=未知(u)/安装(i)/删除(r)/清除(p)/保持(h) +| 状态=未安装(n)/已安装(i)/仅存配置(c)/仅解压缩(U)/配置失败(F)/不完全安装(H)/触发器等待(W)/触发器未决(T) +|/ 错误?=(无)/须重装(R) (状态，错误：大写=故障) +||/ 名称 版本 体系结构 描述 ++++-======================================-====================-============-===================================== +ii linux-image-unsigned-6.17.0-20-generic 6.17.0-20.20~24.04.1 amd64 Linux kernel image for version 6.17.0 + +### speaker-test 输出（stderr/stdout） + +speaker-test 1.2.9 + +重播设备是plughw:0,2 +流参数是 48000Hz，S16_LE，2 频道 +正使用朋克噪声16个8音度 +频率被设为 48000Hz（被要求为48000Hz） +缓冲大小在范围96到16384 +时间段大小从48到4096 +使用最大缓冲大小 16384 +时间段=4 +时间段大小被设为=4096 +缓冲大小被设为=16384 + 0 - Front Left + 1 - Front Right +每时间段时间=5.631754 + +### dmesg（过滤：SOF / HDMI / IPC） + +### dmesg（未过滤全文，ring 较短时即「仅本次」） diff --git a/audio_topology/collected/h3-topology-check-jack-Kaisa_20260404.md b/audio_topology/collected/h3-topology-check-jack-Kaisa_20260404.md index fc0b966ca9..aaa933e3f3 100644 --- a/audio_topology/collected/h3-topology-check-jack-Kaisa_20260404.md +++ b/audio_topology/collected/h3-topology-check-jack-Kaisa_20260404.md @@ -1,8 +1,7 @@ # H3 / Story B：真机拓扑与 IPC `comp_id` 核对（jack-Kaisa） -**时间**：2026-04-04 -**内核**：`6.17.0-20-generic`（`uname -r`） -**方法**：`zstd -dc …/sof-cml-rt5682.tplg.zst | alsatplg -d -` 解码二进制拓扑；对照 `dmesg` 与已保存 **`STREAM_PCM_PARAMS` 载荷**（`comp_id=0x14`）。 +**清单类说明**：[../../docs/linux-hdmi/SOF_FIRMWARE_TOPO_Kaisa_CHECKLIST.md](../../docs/linux-hdmi/SOF_FIRMWARE_TOPO_Kaisa_CHECKLIST.md)。**时间**：2026-04-04 · **内核**：`6.17.0-20-generic` +**方法**：`zstd -dc …/sof-cml-rt5682.tplg.zst | alsatplg -d -`；对照 `dmesg` 与 **`STREAM_PCM_PARAMS`** 载荷（`comp_id=0x14`）。 --- diff --git a/docs/INDEX.md b/docs/INDEX.md index 1f4961e568..971a44ebf6 100644 --- a/docs/INDEX.md +++ b/docs/INDEX.md @@ -1,17 +1,26 @@ # 文档索引 -本仓库 **仅根目录 [README.md](../README.md) 为 README**；本文件为 `docs/` 下按主题分类的**详细索引**（非 README）。 +仅根 [README.md](../README.md) 为仓库 README；本页为 `docs/` **主题表**。全路径：[REPO_INDEX.md](../REPO_INDEX.md)。 -**全仓库路径索引**（含 `audio_topology/`、`patches/`、`scripts/`、`kernel-src/` 等）：[../REPO_INDEX.md](../REPO_INDEX.md) +**HDMI 主文** [linux-hdmi/Linux_HDMI_Audio_Roadmap.md](linux-hdmi/Linux_HDMI_Audio_Roadmap.md) · **架构/进度** [meta/DOCUMENTATION_ARCHITECTURE.md](meta/DOCUMENTATION_ARCHITECTURE.md) · **体例** [meta/DOCUMENTATION_STYLE.md](meta/DOCUMENTATION_STYLE.md) · **LLM 短表** [LLM_INDEX.md](LLM_INDEX.md) -**优先阅读（Linux HDMI 无声）**：[linux-hdmi/Linux_HDMI_Audio_Roadmap.md](linux-hdmi/Linux_HDMI_Audio_Roadmap.md) - -## `docs/` 根目录（重定向占位） +## `docs/` 根（占位） | 文档 | 说明 | | ---- | ---- | -| [WORK_PROGRESS.md](WORK_PROGRESS.md) | 仅指向 [meta/WORK_PROGRESS.md](meta/WORK_PROGRESS.md) | -| [Linux_HDMI_Audio_Roadmap.md](Linux_HDMI_Audio_Roadmap.md) | 仅指向 [linux-hdmi/Linux_HDMI_Audio_Roadmap.md](linux-hdmi/Linux_HDMI_Audio_Roadmap.md) | +| [LLM_INDEX.md](LLM_INDEX.md) | `[ID]` 短表 | +| [index.md](index.md) | BMad AI 索引；project-scan / [project-context.md](../_bmad-output/project-context.md) | +| [WORK_PROGRESS.md](WORK_PROGRESS.md) | → [meta/WORK_PROGRESS.md](meta/WORK_PROGRESS.md) | +| [Linux_HDMI_Audio_Roadmap.md](Linux_HDMI_Audio_Roadmap.md) | → [linux-hdmi/Linux_HDMI_Audio_Roadmap.md](linux-hdmi/Linux_HDMI_Audio_Roadmap.md) | + +## BMad 规划产出 + +| 文档 | 说明 | +| ---- | ---- | +| [_bmad-output/planning-artifacts/prd.md](../_bmad-output/planning-artifacts/prd.md) | **PRD**：愿景、成功标准、用户旅程、范围、**FR/NFR**（能力契约）；与 [linux-hdmi 路线图](linux-hdmi/Linux_HDMI_Audio_Roadmap.md)、[WORK_PROGRESS](meta/WORK_PROGRESS.md) 互补 | +| [_bmad-output/planning-artifacts/architecture.md](../_bmad-output/planning-artifacts/architecture.md) | **架构决策**：Starter、核心决策、实现模式、项目结构、验证结果；与 PRD 冲突时 **以 PRD 为准** | +| [_bmad-output/planning-artifacts/epics.md](../_bmad-output/planning-artifacts/epics.md) | **Epic / Story** 分解与最终校验（CE 产出） | +| [_bmad-output/project-context.md](../_bmad-output/project-context.md) | 面向代理的项目上下文（体例、补丁顺序、验证约定） | --- @@ -20,12 +29,27 @@ | 文档 | 说明 | | ---- | ---- | | [linux-hdmi/Linux_HDMI_Audio_Roadmap.md](linux-hdmi/Linux_HDMI_Audio_Roadmap.md) | **主路线图**：分阶段行动、已排除项、成功标准 | +| [linux-hdmi/FIX_PLAN_HDMI_FROM_SOURCE_ANALYSIS.md](linux-hdmi/FIX_PLAN_HDMI_FROM_SOURCE_ANALYSIS.md) | **修复计划**（基于源码对比）：阶段 A–D、决策分支、不宜投入项；与主路线图互补 | +| [linux-hdmi/PHASE_A_DEVICE_MAP_CHROMEOS_COLLECTED.md](linux-hdmi/PHASE_A_DEVICE_MAP_CHROMEOS_COLLECTED.md) | **阶段 A**：用 `audio_topology/collected/` 中 **ChromeOS 采集** 对照 **ALSA device 与 HDMI1/2/3**（Kaisa） | | [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/CHROMEOS_KAISA_AUDIO_KERNEL_PATHS.md](linux-hdmi/CHROMEOS_KAISA_AUDIO_KERNEL_PATHS.md) | ChromiumOS 5.15 内核：`sof_rt5682` / `sof_board_helpers` 下 **HDMI（iDisp）** 与 **3.5mm（rt5682）** 路径研读笔记 | +| [linux-hdmi/KERNEL_SRC_LINUX_HWE617_HDMI_3.5MM_PATHS.md](linux-hdmi/KERNEL_SRC_LINUX_HWE617_HDMI_3.5MM_PATHS.md) | **`kernel-src`（Ubuntu HWE 6.17 树）**：上游 **`sof_rt5682` / `sof_board_helpers` / `hda-dai`** 下 HDMI 与 3.5mm 实现研读（与 ChromeOS 笔记对照） | +| [linux-hdmi/SOURCE_DIFF_CHROMEOS515_UBUNTU617.md](linux-hdmi/SOURCE_DIFF_CHROMEOS515_UBUNTU617.md) | **ChromiumOS 5.15 ↔ Ubuntu HWE 6.17** 源码对比分析落盘：`sof_board_helpers` / `sof_rt5682` / `ipc3-pcm` / `hda-dai` 差异要点与 `reference/` diff 索引 | | [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` 自动对照摘要（由脚本生成） | +### HDMI 现象分流（读哪篇） + +| 场景 | 入口文档 | +|------|----------| +| **已记录弯路 / 低期望方向**（换 tplg、仅换固件、Mainline 5.15 等） | [路线图 · 二、已排除](linux-hdmi/Linux_HDMI_Audio_Roadmap.md) | +| **内核 / IPC / `STREAM_PCM_PARAMS` 对照与修复分支** | [FIX_PLAN…](linux-hdmi/FIX_PLAN_HDMI_FROM_SOURCE_ANALYSIS.md)、[REANALYSIS…](linux-hdmi/REANALYSIS_Linux_HDMI_Audio_Kaisa.md)、[SOURCE_DIFF…](linux-hdmi/SOURCE_DIFF_CHROMEOS515_UBUNTU617.md) | +| **用户态路由、三平台拓扑总览** | [ANALYSIS_Audio.md](../audio_topology/ANALYSIS_Audio.md) | + +*用户态试错* 与 *内核/IPC 对照* 分流：前者以 **`aplay -L` / PipeWire 路由** 等现象为主时多查 **ANALYSIS**；后者以 **dmesg 中 IPC/载荷** 为主时走 **FIX_PLAN / REANALYSIS / 路线图**。* + ## 内核构建、补丁与安装 | 文档 | 说明 | @@ -34,6 +58,7 @@ | [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 / 0002（诊断）补丁、如何 `PATCH=...` 应用 | +| [../patches/ubuntu-hwe-6.17/VERIFY_PATCHES.md](../patches/ubuntu-hwe-6.17/VERIFY_PATCHES.md) | **0001/0002/0003 验证说明**与一键脚本入口 | | [../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 对照 | @@ -50,6 +75,9 @@ | 文档 | 说明 | | ---- | ---- | +| [meta/DOCUMENTATION_STYLE.md](meta/DOCUMENTATION_STYLE.md) | **体例与改写约定**：语言、入口互链、命名、术语、进度类分工；**全项目文档**自检清单 | +| [meta/DOCUMENTATION_ARCHITECTURE.md](meta/DOCUMENTATION_ARCHITECTURE.md) | **文档架构备忘**：README / INDEX / REPO_INDEX / BMad 入口关系，**进度类文档分工**（WORK_PROGRESS、next、路线图），Mermaid 图 | +| [meta/PREFLIGHT_NOTES.md](meta/PREFLIGHT_NOTES.md) | **双树预检**失败含义与补树入口（与 `preflight-chromeos-ubuntu-diff.sh` stderr 对应） | | [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 分平台修复思路与文档索引 | @@ -57,6 +85,8 @@ ## Windows 专项 +**范围说明（FR20）**：**Linux HDMI 主线**见上表「Linux HDMI」「内核构建」等节；下列为 **Windows 排障**，**非**本仓库 PRD 的 Linux HDMI 交付范围，仅作同款硬件交叉参考。 + | 文档 | 说明 | | ---- | ---- | | [windows/OPERATION_Windows_Audio.md](windows/OPERATION_Windows_Audio.md) | CoolStar / ALC5682 全流程 | @@ -64,10 +94,13 @@ ## 脚本（仓库根 `scripts/`） +**可发现性（FR19）**：验证 / 构建 / 双树 diff 入口如下；细节以各脚本 `--help` 与 **`patches/.../VERIFY_PATCHES.md`** 为准。 + | 脚本 | 说明 | | ---- | ---- | | [../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/verify-ubuntu-hwe617-patches-runtime.sh](../scripts/verify-ubuntu-hwe617-patches-runtime.sh) | **真机**：0001 源码 + 0002/0003 运行时（`sof_debug`、dynamic_debug、可选 `speaker-test`），成功打印 `VERIFY_OK` | | [../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 | diff --git a/docs/LLM_INDEX.md b/docs/LLM_INDEX.md new file mode 100644 index 0000000000..2b307ec849 --- /dev/null +++ b/docs/LLM_INDEX.md @@ -0,0 +1,86 @@ +# Directory Index（`docs/`） + +面向 **LLM / 代理**：用**短描述**定位文件，避免通读全文。人读总目录仍以 **[INDEX.md](./INDEX.md)** 为准；**[index.md](./index.md)** 为 BMad 主索引。 + +**全项目怎么写、改**：先读 **[meta/DOCUMENTATION_STYLE.md](./meta/DOCUMENTATION_STYLE.md)**。 + +--- + +## `docs/` 根目录 + +| 文件 | 简述 | +|------|------| +| [INDEX.md](./INDEX.md) | 按主题分类的**完整链入表**（主入口之一） | +| [index.md](./index.md) | BMad Document Project 产出：AI 检索主索引 | +| [LLM_INDEX.md](./LLM_INDEX.md) | **本文件**：全目录轻量摘要（Index Docs） | +| [project-overview.md](./project-overview.md) | BMad 扫描：项目概览与分类 | +| [source-tree-analysis.md](./source-tree-analysis.md) | BMad 扫描：目录树与关键路径 | +| [development-guide.md](./development-guide.md) | 构建、验证脚本、文档维护约定 | +| [project-scan-report.json](./project-scan-report.json) | BMad 扫描状态元数据（JSON） | +| [WORK_PROGRESS.md](./WORK_PROGRESS.md) | 占位：指向 **meta/WORK_PROGRESS.md** | +| [Linux_HDMI_Audio_Roadmap.md](./Linux_HDMI_Audio_Roadmap.md) | 占位：指向 **linux-hdmi/** 路线图 | + +--- + +## 仓库根 `_bmad-output/`（相对 `docs/` 为 `../_bmad-output/`） + +| 文件 | 简述 | +|------|------| +| [../_bmad-output/planning-artifacts/prd.md](../_bmad-output/planning-artifacts/prd.md) | **PRD**：成功标准、旅程、**FR/NFR**（能力契约） | +| [../_bmad-output/project-context.md](../_bmad-output/project-context.md) | GPC：补丁、验证、文档入口约定 | + +--- + +## `meta/` + +| 文件 | 简述 | +|------|------| +| [DOCUMENTATION_STYLE.md](./meta/DOCUMENTATION_STYLE.md) | **体例宪章**：语言、入口、命名、术语、进度分工 | +| [DOCUMENTATION_ARCHITECTURE.md](./meta/DOCUMENTATION_ARCHITECTURE.md) | 文档入口分层、进度类分工、Mermaid | +| [WORK_PROGRESS.md](./meta/WORK_PROGRESS.md) | 换机交接、阶段结论、源码获取 | +| [CHROMEOS_vs_UBUNTU617_SOUND_AUTODIFF.md](./meta/CHROMEOS_vs_UBUNTU617_SOUND_AUTODIFF.md) | `sound/soc` 自动对照脚本结果摘要 | +| [OPERATION_DualBoot_Ubuntu24_Windows.md](./meta/OPERATION_DualBoot_Ubuntu24_Windows.md) | Ubuntu 24.04 与 Windows 双系统安装 | + +--- + +## `linux-hdmi/` + +| 文件 | 简述 | +|------|------| +| [Linux_HDMI_Audio_Roadmap.md](./linux-hdmi/Linux_HDMI_Audio_Roadmap.md) | Linux HDMI 无声：主路线图与成功标准 | +| [FIX_PLAN_HDMI_FROM_SOURCE_ANALYSIS.md](./linux-hdmi/FIX_PLAN_HDMI_FROM_SOURCE_ANALYSIS.md) | 基于源码对比的修复计划（阶段 A–D） | +| [REANALYSIS_Linux_HDMI_Audio_Kaisa.md](./linux-hdmi/REANALYSIS_Linux_HDMI_Audio_Kaisa.md) | 重分析：Mainline 误区、安装坑、优先级（现象表见路线图） | +| [PHASE_A_DEVICE_MAP_CHROMEOS_COLLECTED.md](./linux-hdmi/PHASE_A_DEVICE_MAP_CHROMEOS_COLLECTED.md) | 阶段 A：ChromeOS 采集与 ALSA 对应 | +| [CHROMEOS_KAISA_AUDIO_KERNEL_PATHS.md](./linux-hdmi/CHROMEOS_KAISA_AUDIO_KERNEL_PATHS.md) | ChromiumOS 5.15：HDMI 与 3.5mm 路径笔记 | +| [KERNEL_SRC_LINUX_HWE617_HDMI_3.5MM_PATHS.md](./linux-hdmi/KERNEL_SRC_LINUX_HWE617_HDMI_3.5MM_PATHS.md) | HWE 6.17 树：iDisp/rt5682/hda-dai 研读 | +| [SOURCE_DIFF_CHROMEOS515_UBUNTU617.md](./linux-hdmi/SOURCE_DIFF_CHROMEOS515_UBUNTU617.md) | ChromeOS 5.15 与 6.17 源码对比要点 | +| [CHROMEOS_VS_UBUNTU_HDMI_NOTES.md](./linux-hdmi/CHROMEOS_VS_UBUNTU_HDMI_NOTES.md) | HDMI/iDisp API 两系统对照 | +| [OPERATION_Kaisa_SOF_HDMI_Trace.md](./linux-hdmi/OPERATION_Kaisa_SOF_HDMI_Trace.md) | `STREAM_PCM_PARAMS` 与 IPC 载荷观测操作 | +| [SOF_FIRMWARE_TOPO_Kaisa_CHECKLIST.md](./linux-hdmi/SOF_FIRMWARE_TOPO_Kaisa_CHECKLIST.md) | SOF 固件与拓扑一致性核对清单 | +| [UPSTREAM_SOF_Kaisa_HDMI_REPRO.md](./linux-hdmi/UPSTREAM_SOF_Kaisa_HDMI_REPRO.md) | 上游复现材料与邮件模板 | + +--- + +## `kernel-build/` + +| 文件 | 简述 | +|------|------| +| [OPERATION_Install_CustomKernel_Ubuntu_HWE617.md](./kernel-build/OPERATION_Install_CustomKernel_Ubuntu_HWE617.md) | 装 deb（与 kernel-src README 分工：本文偏安装） | +| [OPERATION_ChromeOS_Kernel_Deep_Diff.md](./kernel-build/OPERATION_ChromeOS_Kernel_Deep_Diff.md) | unshallow / diff 主操作（AUTODIFF 仅统计） | + +--- + +## `windows/` + +| 文件 | 简述 | +|------|------| +| [OPERATION_Windows_Audio.md](./windows/OPERATION_Windows_Audio.md) | CoolStar 顺序与排障（概况表见根 README） | +| [HARDWARE_ID_DRIVER_MAP_Windows.md](./windows/HARDWARE_ID_DRIVER_MAP_Windows.md) | Hardware ID → 驱动包（与 OPERATION 分工） | + +--- + +## 使用建议 + +1. **任务**：Linux HDMI → 优先 **linux-hdmi/Linux_HDMI_Audio_Roadmap** + **FIX_PLAN**；换机状态 → **meta/WORK_PROGRESS**。 +2. **补丁/编译**：仓库 **[patches/README](../patches/ubuntu-hwe-6.17/README.md)**、**[kernel-src/README](../kernel-src/README.md)**（在 `docs/` 外，见 **[REPO_INDEX.md](../REPO_INDEX.md)**）。 +3. 更新本索引：在 `docs/` 下**新增/删除**主题文档后，重跑 **`[ID] Index Docs`** 或手工增删一行。 diff --git a/docs/Linux_HDMI_Audio_Roadmap.md b/docs/Linux_HDMI_Audio_Roadmap.md index 7805d34e8c..33780cfd45 100644 --- a/docs/Linux_HDMI_Audio_Roadmap.md +++ b/docs/Linux_HDMI_Audio_Roadmap.md @@ -1,3 +1,5 @@ # 文档已迁移 Linux HDMI 路线图现位于：[linux-hdmi/Linux_HDMI_Audio_Roadmap.md](linux-hdmi/Linux_HDMI_Audio_Roadmap.md)。 + +文档体例见：[meta/DOCUMENTATION_STYLE.md](meta/DOCUMENTATION_STYLE.md)。 diff --git a/docs/WORK_PROGRESS.md b/docs/WORK_PROGRESS.md index e83ba2b3c2..a53fdcfe06 100644 --- a/docs/WORK_PROGRESS.md +++ b/docs/WORK_PROGRESS.md @@ -1,3 +1,5 @@ # 文档已迁移 换机交接与进度说明现位于：[meta/WORK_PROGRESS.md](meta/WORK_PROGRESS.md)。 + +文档体例见：[meta/DOCUMENTATION_STYLE.md](meta/DOCUMENTATION_STYLE.md)。 diff --git a/docs/development-guide.md b/docs/development-guide.md new file mode 100644 index 0000000000..c55c899a02 --- /dev/null +++ b/docs/development-guide.md @@ -0,0 +1,66 @@ +# 开发与实验指南（chromebox_10th_audio_driver） + +**体例**：[meta/DOCUMENTATION_STYLE.md](meta/DOCUMENTATION_STYLE.md)。**面向：** 维护文档、打补丁、真机验证。 + +--- + +## 前置条件 + +- **Linux（推荐 Ubuntu 24.04 Noble）**：与 **HWE 6.17** 内核文档路径一致。 +- 工具：**bash**、**git**、**patch**；编内核时需 **fakeroot**、**dpkg-dev**、**debhelper** 等（见 **kernel-src/README.md** 与 **`scripts/ubuntu-hwe-617-build.sh deps`**）。 +- 大目录：**kernel-src** 解压与 **deb 构建** 需 **数十 GB** 磁盘空间。 + +--- + +## 克隆与目录 + +```bash +git clone <本仓库 URL> chromebox_10th_audio_driver +cd chromebox_10th_audio_driver +``` + +可选：按 **docs/meta/WORK_PROGRESS.md** 拉取 **chromiumos_kernel**、**kernel-src**（不提交二进制/大 tarball）。 + +--- + +## 应用补丁并构建（摘要） + +```bash +export PATCH="$PWD/patches/ubuntu-hwe-6.17/0001-....patch" +./scripts/ubuntu-hwe-617-build.sh apply +# 按需继续 0002、0003 +./scripts/ubuntu-hwe-617-build.sh deps +./scripts/ubuntu-hwe-617-build.sh build +``` + +完整安装 **linux-image-unsigned**、**modules**、**modules-extra**：**docs/kernel-build/OPERATION_Install_CustomKernel_Ubuntu_HWE617.md**。 + +--- + +## 验证补丁（真机） + +```bash +./scripts/verify-ubuntu-hwe617-patches-runtime.sh +RUN_HDMI_TEST=0 ./scripts/verify-ubuntu-hwe617-patches-runtime.sh # 不跑 speaker-test +``` + +说明：**patches/ubuntu-hwe-6.17/VERIFY_PATCHES.md**。 + +--- + +## 文档维护约定 + +- **全项目体例与改写自检**：[meta/DOCUMENTATION_STYLE.md](meta/DOCUMENTATION_STYLE.md)。 +- 新主题：在 **docs/INDEX.md**（或 **REPO_INDEX.md**）增加**一条**链入，避免孤岛文档。 +- 用户向说明：默认 **中文**（与 **\_bmad/bmm/config.yaml** 一致）。 +- **勿**在无请求时批量修改 **.cursor/plans/**（见 **WORK_PROGRESS** 说明）。 + +--- + +## 常用引用 + +| 文档 | 内容 | +|------|------| +| **docs/linux-hdmi/Linux_HDMI_Audio_Roadmap.md** | Linux HDMI 分阶段路线图 | +| **patches/ubuntu-hwe-6.17/DIFF_SUMMARY.txt** | 补丁设计与 smoke | +| **audio_topology/REPAIR_Plan_Audio.md** | Linux / Windows 分平台修复总览 | diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000000..c0b79cc60d --- /dev/null +++ b/docs/index.md @@ -0,0 +1,48 @@ +# chromebox_10th_audio_driver — BMad 文档主索引 + +**栈**：Bash、Markdown、HWE 6.17 补丁 · **更新**：2026-04-05 + +> BMad document-project 产出，与 [project-scan-report.json](./project-scan-report.json) 对齐。**人读**以 [INDEX.md](./INDEX.md) 为准。 + +--- + +## 简述 + +Kaisa + Coreboot 跨平台音频；补丁 `0001–0003`；可选 `kernel-src` / `chromiumos_kernel` 对照。 + +--- + +## 快速参考 + +| 项 | 内容 | +|----|------| +| 入口 | [README.md](../README.md)、[REPO_INDEX.md](../REPO_INDEX.md) | +| 产出 | 下表 | + +--- + +## 本工作流产出 + +| 文档 | 说明 | +|------|------| +| [project-overview.md](./project-overview.md) | 概览 | +| [source-tree-analysis.md](./source-tree-analysis.md) | 目录树 | +| [development-guide.md](./development-guide.md) | 构建与维护 | +| [project-scan-report.json](./project-scan-report.json) | 扫描元数据 | +| [_bmad-output/project-context.md](../_bmad-output/project-context.md) | GPC | +| [_bmad-output/planning-artifacts/prd.md](../_bmad-output/planning-artifacts/prd.md) | **PRD**（Create PRD）：成功标准、用户旅程、**FR/NFR** 能力契约 | +| [meta/DOCUMENTATION_ARCHITECTURE.md](./meta/DOCUMENTATION_ARCHITECTURE.md) | 入口与进度分工 | +| [meta/DOCUMENTATION_STYLE.md](./meta/DOCUMENTATION_STYLE.md) | 体例 | +| [LLM_INDEX.md](./LLM_INDEX.md) | `[ID]` 短表 | + +--- + +## 衔接 + +[INDEX.md](./INDEX.md) · [linux-hdmi/Linux_HDMI_Audio_Roadmap.md](./linux-hdmi/Linux_HDMI_Audio_Roadmap.md) + +--- + +## 棕地提示 + +大改文档时带 **index.md**、**INDEX.md**、**meta/WORK_PROGRESS.md**；内核相关对齐 **`uname -r`** 与 **patches/ubuntu-hwe-6.17/README.md**。 diff --git a/docs/kernel-build/OPERATION_ChromeOS_Kernel_Deep_Diff.md b/docs/kernel-build/OPERATION_ChromeOS_Kernel_Deep_Diff.md index 888552babd..d14cc2ae53 100644 --- a/docs/kernel-build/OPERATION_ChromeOS_Kernel_Deep_Diff.md +++ b/docs/kernel-build/OPERATION_ChromeOS_Kernel_Deep_Diff.md @@ -1,8 +1,10 @@ # ChromiumOS 5.15 内核：拉全历史、查提交、与 Ubuntu HWE 6.17 做关键文件 diff -面向：在仓库 [`chromiumos_kernel/v5.15/`](../chromiumos_kernel/v5.15) 对照 **ChromeOS** 与 **`kernel-src/linux-hwe-6.17-6.17.0/`**（Noble 源码树），为 **Kaisa HDMI / `STREAM_PCM_PARAMS`** 相关的新内核补丁做设计输入。 +**体例**：[../meta/DOCUMENTATION_STYLE.md](../meta/DOCUMENTATION_STYLE.md)。**自动对照统计摘要**见 [CHROMEOS_vs_UBUNTU617_SOUND_AUTODIFF.md](../meta/CHROMEOS_vs_UBUNTU617_SOUND_AUTODIFF.md)（**以本文为操作主文档**，AUTODIFF 不重复 unshallow 全流程）。 -克隆说明与分支名见 [`../meta/WORK_PROGRESS.md`](../meta/WORK_PROGRESS.md) 第二节。 +面向：[`chromiumos_kernel/v5.15/`](../chromiumos_kernel/v5.15) 与 **`kernel-src/linux-hwe-6.17-6.17.0/`** 对照，为 **Kaisa HDMI / `STREAM_PCM_PARAMS`** 补丁提供设计输入。 + +克隆与分支名见 [WORK_PROGRESS.md](../meta/WORK_PROGRESS.md) 第二节。 --- diff --git a/docs/kernel-build/OPERATION_Install_CustomKernel_Ubuntu_HWE617.md b/docs/kernel-build/OPERATION_Install_CustomKernel_Ubuntu_HWE617.md index 946215cfe3..959e026d4a 100644 --- a/docs/kernel-build/OPERATION_Install_CustomKernel_Ubuntu_HWE617.md +++ b/docs/kernel-build/OPERATION_Install_CustomKernel_Ubuntu_HWE617.md @@ -1,6 +1,10 @@ # Ubuntu 24.04：安装自编译 HWE 6.17 内核 deb（自定义补丁或上游源码树产物） -面向：**先按第 0 节在 Noble 上编译出 deb**，再在 **`kernel-src/`**（与源码 **`kernel-src/linux-hwe-6.17-6.17.0/`** 同级）得到 `linux-image-unsigned-*`、`linux-modules-*` 等包，然后在 **目标机** 上安装并重启验证。也可只读 **第 1 节起**（仅安装他人编译好的 deb）。 +**体例**：[../meta/DOCUMENTATION_STYLE.md](../meta/DOCUMENTATION_STYLE.md)。**如何 `apt source`、清理源码树**见 [kernel-src/README.md](../../kernel-src/README.md)；**本文只写 deb 路径约定与安装步骤**。 + +**与 WORK_PROGRESS（FR7）**：安装、回退、当前 **`uname -r`** 与自编包标识等**事实**，请同步 **[WORK_PROGRESS.md](../meta/WORK_PROGRESS.md)**；**unsigned、模块包、Secure Boot** 等范围**以本文为准**（PRD 不逐包枚举）。回退步骤见本文 **回滚** 与 **GRUB** 各节。 + +面向：**先按第 0 节在 Noble 上编译出 deb**，再在 **`kernel-src/`**（与 **`kernel-src/linux-hwe-6.17-6.17.0/`** 同级）得到 `linux-image-unsigned-*`、`linux-modules-*` 等，再在 **目标机** 安装并重启。也可从 **第 1 节** 起只读（安装现成 deb）。 ### 路径约定（本仓库） diff --git a/docs/linux-hdmi/CHROMEOS_KAISA_AUDIO_KERNEL_PATHS.md b/docs/linux-hdmi/CHROMEOS_KAISA_AUDIO_KERNEL_PATHS.md new file mode 100644 index 0000000000..e182023adb --- /dev/null +++ b/docs/linux-hdmi/CHROMEOS_KAISA_AUDIO_KERNEL_PATHS.md @@ -0,0 +1,132 @@ +# ChromiumOS 5.15 内核：Kaisa 相关 HDMI 与 3.5mm 音频路径（研读笔记） + +**体例**：[../meta/DOCUMENTATION_STYLE.md](../meta/DOCUMENTATION_STYLE.md)。基于 **[chromiumos_kernel/v5.15/](../../chromiumos_kernel/v5.15/)** 的 **ChromeOS 5.15** machine 层 **HDMI（iDisp）** 与 **3.5mm（rt5682）**。**Ubuntu 6.17 对称笔记**：[KERNEL_SRC_LINUX_HWE617_HDMI_3.5MM_PATHS.md](KERNEL_SRC_LINUX_HWE617_HDMI_3.5MM_PATHS.md)。 + +--- + +## 1. 目的与范围 + +| 项目 | 说明 | +|------|------| +| **本文覆盖** | **内核**：`sof_rt5682` machine、`sof_board_helpers` 中的 DAI link 构造、与 **Intel HDA / iDisp**、**SSP + rt5682** 的衔接；以及 **SOF 侧**与 **拓扑（tplg）** 绑定的概念（不解析 tplg 二进制）。 | +| **本文不覆盖** | **ChromeOS 用户态音频栈 CRAS**（混音、路由、策略）——**不在** `chromiumos_kernel` 树内；与 Ubuntu 上 **PipeWire** 的差异属产品层，见 [REANALYSIS_Linux_HDMI_Audio_Kaisa.md](REANALYSIS_Linux_HDMI_Audio_Kaisa.md) §7.3。 | +| **与 Ubuntu 对照** | IPC 载荷、`STREAM_PCM_PARAMS` 与 6.17 差异见 [STREAM_PCM_PARAMS_CHROME_UBUNTU_NOTES.md](../../patches/ubuntu-hwe-6.17/STREAM_PCM_PARAMS_CHROME_UBUNTU_NOTES.md)；板级文件 unified diff 见 [reference](../../patches/ubuntu-hwe-6.17/reference/)。 | + +--- + +## 2. 术语 + +- **iDisp**：Intel **Display Audio**（HDMI/DP 数字音频）在 HDA 扩展总线上的 **显示类 codec 端点**；machine 里常命名为 **`iDisp1` / `iDisp2` / …**。 +- **SOF / tplg**：固件与 **拓扑** 描述 PCM、pipeline、与 **SSP / iDisp Pin** 的绑定；真机 dmesg 中可见 `sof-cml-rt5682.tplg` 等，清单见 [SOF_FIRMWARE_TOPO_Kaisa_CHECKLIST.md](SOF_FIRMWARE_TOPO_Kaisa_CHECKLIST.md)。 +- **pcm2/3/4 与物理口**：ALSA **device 编号**与机箱 **HDMI1/2/3 丝印** 需 **实测对照**，不可凭编号推断。 + +--- + +## 3. HDMI（iDisp）在内核中的实现要点 + +### 3.1 Machine 层：DAI link 的生成 + +核心在 **[sound/soc/intel/boards/sof_board_helpers.c](../../chromiumos_kernel/v5.15/sound/soc/intel/boards/sof_board_helpers.c)**： + +- **`sof_intel_board_set_dai_link()`**（约 414 行起）按 **`DEFAULT_LINK_ORDER`** 依次创建：**Codec（耳机）→ DMIC → iDisp HDMI → …**（见同文件约 82–89 行宏 **`DEFAULT_LINK_ORDER`**）。 +- **HDMI 回放**：**`SOF_LINK_IDISP_HDMI`** 分支（约 506–520 行）对 **`i = 1 .. ctx->hdmi_num`** 调用 **`set_idisp_hdmi_link()`**。 + +**`set_idisp_hdmi_link()`**（约 203–258 行）为每条 HDMI 建立一条 **BE DAI link**： + +- **link 名**：`iDisp{hdmi_id}`（如 `iDisp1`、`iDisp2`）。 +- **CPU 侧（SOF）**：`iDisp{hdmi_id} Pin`。 +- **Codec 侧**：若 **`idisp_codec == true`**，使用 **`ehdaudio0D2`** + **`intel-hdmi-hifi{hdmi_id}`**；否则 **dummy codec**。 +- **Platform**：固定为 **`0000:00:1f.3`**（PCH HDaudio/SOF 设备），见 **`platform_component`**（约 98–103 行）。 +- **DPCM**：**`dpcm_playback = 1`**，**`no_pcm = 1`**（BE 无独立 PCM，由前端 FE 经 DPCM 连接）。 + +**HDMI 控制节点**：**`sof_intel_board_card_late_probe()`**（约 23–37 行）在存在 **iDisp codec** 时调用 **`hda_dsp_hdmi_build_controls()`**，用于 **HDMI 相关 mixer/ELD** 等（与显示器音频能力相关）。 + +### 3.2 `sof_rt5682` 中 HDMI 路数与 iDisp 标志 + +**[sound/soc/intel/boards/sof_rt5682.c](../../chromiumos_kernel/v5.15/sound/soc/intel/boards/sof_rt5682.c)** 的 **`sof_audio_probe()`**（约 629 行起）： + +- 非 BYT/CHT 时：**`ctx->hdmi_num`** 来自 quirk 的 **`SOF_RT5682_NUM_HDMIDEV`** 域（约 667–671 行）；若为 **0** 则默认 **3** 条 HDMI DAI。 +- 若 ACPI machine **`mach_params.codec_mask & IDISP_CODEC_MASK`**，则 **`ctx->hdmi.idisp_codec = true`**（约 673–674 行），与上节 **真实 HDA HDMI codec** 路径一致。 + +### 3.3 SOF Intel：`hda-dai.c` 中与 link / stream 相关的路径（Chrome 5.15 树） + +**[sound/soc/sof/intel/hda-dai.c](../../chromiumos_kernel/v5.15/sound/soc/sof/intel/hda-dai.c)** 中，**`hda_link_dma_hw_params()`**（约 207–247 行）在完成 **`snd_soc_dai_set_stream`** 等后，调用 **`hda_link_dma_params()`**（约 174–204 行）。在 **playback** 下，**`hda_link_dma_params()`** 按 **`params->link_index`** 在 **`bus->hlink_list`** 上找到对应 **link**，并调用 **`snd_hdac_ext_link_set_stream_id(link, stream_tag)`**（约 194–199 行）。 + +> **说明**：Ubuntu HWE 6.17 同文件已演进为 **`hda_dai_widget_dma_ops`** 等抽象，与 Chrome 5.15 **逐行不一致**；**IPC `STREAM_PCM_PARAMS` 行为对照** 以 [STREAM_PCM_PARAMS_CHROME_UBUNTU_NOTES.md](../../patches/ubuntu-hwe-6.17/STREAM_PCM_PARAMS_CHROME_UBUNTU_NOTES.md) 为准，本文只标 **Chrome 树内函数链**。 + +--- + +## 4. 3.5mm（耳机 / ALC5682）在内核中的实现要点 + +### 4.1 与 HDMI 独立的 Codec BE：`SOF_LINK_CODEC` + +同一套 **`sof_intel_board_set_dai_link()`** 中，**`SOF_LINK_CODEC`**（约 458–474 行）调用 **`set_ssp_codec_link()`**，为 **耳机 Codec** 建立 **SSP{x}-Codec** 类 **BE link**： + +- **CPU 侧**：**`SSP{ssp_codec} Pin`**（非 BYT/CHT 命名）。 +- **Codec 侧**：由 **`sof_card_dai_links_create()`**（**[sof_rt5682.c](../../chromiumos_kernel/v5.15/sound/soc/intel/boards/sof_rt5682.c)** 约 526 行起）填入 **`rt5682_component`** / **`rt5682s_component`** 等，例如 **RT5682**：**`i2c-10EC5682:00` + `rt5682-aif1`**（约 501–505 行）。 +- **`ctx->codec_link->init = sof_rt5682_codec_init`**（约 560 行）。 + +### 4.2 `sof_rt5682_codec_init`：插孔、jack、时钟 + +**`sof_rt5682_codec_init()`**（约 184–287 行）负责： + +- **MCLK / ASRC**：在 **`SOF_RT5682_MCLK_EN`** 且 **24 MHz MCLK** 等条件下，对 **RT5682** 调用 **`rt5682_sel_asrc_clk_src()`**（约 214–218 行）。 +- **耳机插孔**：**`snd_soc_card_jack_new_pins`**，pin **「Headphone Jack」/「Headset Mic」**（约 173–182、259–265 行），并 **`snd_soc_component_set_jack`**（约 276–280 行）。 + +### 4.3 `sof_rt5682_hw_params`：PLL / BCLK / TDM + +**`sof_rt5682_ops.hw_params`**（约 297–419 行）在播放参数协商阶段配置 **PLL、sysclk、TDM slot**（**`snd_soc_dai_set_pll` / `set_sysclk` / `set_tdm_slot`**），与 **拓扑中的 mclk/格式** 一致。 + +--- + +## 5. Kaisa（Google Rex）相关 quirk + +ChromeOS **DMI** 表中 **无「Kaisa」字符串**；与 **Chromebox Rex / Kaisa** 同族产品常匹配 **`DMI_PRODUCT_FAMILY == "Google_Rex"`**： + +**[sof_rt5682.c](../../chromiumos_kernel/v5.15/sound/soc/intel/boards/sof_rt5682.c)** **`sof_rt5682_quirk_table`**（约 157–168 行）中 **Rex** 条目 **`driver_data`** 包含： + +- **`SOF_RT5682_SSP_CODEC(2)`**：耳机 Codec 走 **SSP2**。 +- **`SOF_RT5682_NUM_HDMIDEV(3)`**：**3 条** iDisp HDMI DAI（与 **`aplay` 中多路 HDMI PCM** 对应关系需实测）。 +- **BT offload** 等标志（同块 `driver_data`）。 + +**ACPI / platform id**：**`board_ids[]`**（约 762 行起）中另有 **`tgl_rt5682_def`**、**`adl_rt5682_def`** 等 **固定 `driver_data`** 的板名；**Rex/Kaisa** 以 **DMI quirk** 为主时，**`pdev->id_entry->driver_data`** 可能在 probe 中覆盖（见约 639–640 行）。 + +--- + +## 6. 与 Ubuntu HWE 6.17 的差异入口（仓库内已有） + +| 材料 | 路径 | +|------|------| +| **双树对比分析（可读摘要）** | [SOURCE_DIFF_CHROMEOS515_UBUNTU617.md](SOURCE_DIFF_CHROMEOS515_UBUNTU617.md) | +| 板级 **`sof_rt5682.c` / `sof_board_helpers.c`** unified diff | [patches/ubuntu-hwe-6.17/reference/diff-u_sound_soc_intel_boards_sof_rt5682.c.txt](../../patches/ubuntu-hwe-6.17/reference/diff-u_sound_soc_intel_boards_sof_rt5682.c.txt)、[`..._sof_board_helpers.c.txt`](../../patches/ubuntu-hwe-6.17/reference/diff-u_sound_soc_intel_boards_sof_board_helpers.c.txt) | +| 重导脚本 | [scripts/export-boards-chrome-ubuntu-diff.sh](../../scripts/export-boards-chrome-ubuntu-diff.sh) | +| `STREAM_PCM_PARAMS` / `ipc3-pcm` / `hda-pcm` / `hda-dai` | [STREAM_PCM_PARAMS_CHROME_UBUNTU_NOTES.md](../../patches/ubuntu-hwe-6.17/STREAM_PCM_PARAMS_CHROME_UBUNTU_NOTES.md)、[export-chromeos-ubuntu-sound-file-diffs.sh](../../scripts/export-chromeos-ubuntu-sound-file-diffs.sh) | +| 深度 diff 流程 | [OPERATION_ChromeOS_Kernel_Deep_Diff.md](../kernel-build/OPERATION_ChromeOS_Kernel_Deep_Diff.md) | + +--- + +## 7. 参考命令（研读与历史） + +```bash +cd chromiumos_kernel/v5.15 +# 若需完整提交历史（当前仓库可能为浅克隆，rev-list 为 1）： +git fetch --unshallow origin # 见 OPERATION_ChromeOS_Kernel_Deep_Diff.md +git --no-pager log --oneline -30 -- sound/soc/intel/boards/sof_rt5682.c +``` + +--- + +## 8. 附录：本仓库 `chromiumos_kernel` 的 `git log` 说明 + +当前若 **`git rev-list --count HEAD`** 为 **1**（浅克隆），则 **`git log -- `** 仅能显示 **单条提交**，无法罗列 Chrome 侧演进。完整 **`git log`** 需在 **`git fetch --unshallow`** 后重试，并将有意义提交摘要 **追加** 至本节。 + +--- + +## 9. 小结（回答「HDMI vs 3.5mm 在内核里怎么实现」） + +| 输出 | ChromeOS 5.15 内核侧主路径 | +|------|---------------------------| +| **HDMI / DP 数字音频** | **`sof_board_helpers.c`**：**`set_idisp_hdmi_link`** → **`iDispN Pin`** +（可选）**`ehdaudio0D2` / `intel-hdmi-hifiN`**；条数由 **`ctx->hdmi_num`**（**`sof_rt5682` quirk** + 默认 3）决定；**late_probe** 里 **HDA HDMI controls**。 | +| **3.5mm / 耳机（ALC5682）** | **`sof_board_helpers.c`**：**`set_ssp_codec_link`** → **`SSPx Pin`** + **I2C rt5682 `rt5682-aif1`**；**`sof_rt5682.c`**：**`sof_rt5682_codec_init` / `sof_rt5682_hw_params`** 管 **jack、PLL、TDM**。 | + +两条路径在 machine 层 **并列**（**`DEFAULT_LINK_ORDER`**），经 **SOF 固件拓扑** 与 **DPCM** 接到不同 **FE/BE**；**用户态选路** 在 ChromeOS 上由 **CRAS** 完成，**不在本文树内**。 diff --git a/docs/linux-hdmi/CHROMEOS_VS_UBUNTU_HDMI_NOTES.md b/docs/linux-hdmi/CHROMEOS_VS_UBUNTU_HDMI_NOTES.md index 0f43590d30..e6aefc212d 100644 --- a/docs/linux-hdmi/CHROMEOS_VS_UBUNTU_HDMI_NOTES.md +++ b/docs/linux-hdmi/CHROMEOS_VS_UBUNTU_HDMI_NOTES.md @@ -26,11 +26,11 @@ --- -## 三、后续补丁方向（原 0001/0002 已移除） +## 三、历史上的 TRIGGER 实验与当前 `patches/` 状态 -曾尝试在 `set_idisp_hdmi_link` 中增加 **`SND_SOC_DPCM_TRIGGER_POST`**（旧称 0002），**Kaisa 真机 HDMI 仍无声**；该补丁已从仓库删除。 +曾尝试在 `set_idisp_hdmi_link` 中增加 **`SND_SOC_DPCM_TRIGGER_POST`**（旧称 **错误 0002**），**真机 HDMI 仍无声**；该补丁**已删除**。 -新补丁应在细读 **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)。 +**当前仓库**仍保留 **0001**（FREE/trigger）、**0002**（`STREAM_PCM_PARAMS` 诊断）、可选 **0003**（`hda-dai` `dev_dbg`），见 [`patches/ubuntu-hwe-6.17/README.md`](../../patches/ubuntu-hwe-6.17/README.md)。新功能性补丁应在细读两树 **`ipc3.c` / `pcm.c` / `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)。 --- diff --git a/docs/linux-hdmi/FIX_PLAN_HDMI_FROM_SOURCE_ANALYSIS.md b/docs/linux-hdmi/FIX_PLAN_HDMI_FROM_SOURCE_ANALYSIS.md new file mode 100644 index 0000000000..8e13b6c47a --- /dev/null +++ b/docs/linux-hdmi/FIX_PLAN_HDMI_FROM_SOURCE_ANALYSIS.md @@ -0,0 +1,126 @@ +# 基于源码对比分析的 Linux HDMI 无声修复计划（Kaisa / SOF / iDisp） + +依据 **[SOURCE_DIFF_CHROMEOS515_UBUNTU617.md](SOURCE_DIFF_CHROMEOS515_UBUNTU617.md)**、**[STREAM_PCM_PARAMS_CHROME_UBUNTU_NOTES.md](../../patches/ubuntu-hwe-6.17/STREAM_PCM_PARAMS_CHROME_UBUNTU_NOTES.md)**，把源码对比结论落实为 **阶段 A–D**、**决策分支**与**不宜投入项**。 + +**阶段顺序、成功标准、维护**以主路线图 **[Linux_HDMI_Audio_Roadmap.md](Linux_HDMI_Audio_Roadmap.md)** 为准；本文只多写「**对比推导出的工程分支**」，避免与路线图重复描述现象。 + +**适用范围**：Google Kaisa + Coreboot + Ubuntu Noble + HWE 6.17；其它机型可借用 **阶段 A** 套路。 + +--- + +## 一、源码对比给出的工程结论（修复策略前提） + +| 结论 | 对修复的含义 | +|------|----------------| +| **`ipc3-pcm.c` 中 `STREAM_PCM_PARAMS` 载荷构造** 与 Chrome 5.15 **语义一致** | **不宜**把「盲改 `struct sof_ipc_pcm_params` 各字段」作为第一刀；真机载荷解码已自洽时见 STREAM_PCM 笔记 §5。 | +| **`hda-dai.c` 5.15↔6.17 为架构级差异（~千行 diff）** | **不宜**整文件 backport；仅对 **trace/bisect 指向的具体函数**（如 **`hda_link_dma_hw_params`**、`format_val` 分支）做 **最小补丁** 并与上游讨论。 | +| **板级 `set_idisp_hdmi_link` 逻辑在两树同构**（`iDispN` + `ehdaudio0D2` / `intel-hdmi-hifiN`） | **不宜**期待单靠「恢复 Chrome 的 `dpcm_playback` 字面量」修复问题；6.17 已用 **`playback_only`** 等价表达。 | +| **Google_Rex 在 6.17 常不显式写 HDMI 条数** | **默认 3 条 iDisp BE** 与 Chrome 显式 `NUM_HDMIDEV(3)` 常等价；**优先**查 **IPC/HDA/固件**，而非先改 Rex DMI 行补 `SOF_NUM_IDISP_HDMI`**（除非采集证明 `hdmi_num`/枚举异常）。 | +| **0001 补丁对齐 FREE/trigger** | 解决的是 **IPC 事务完整性**（与 Chrome 一致），**不**改变 `hw_params` / `STREAM_PCM_PARAMS` 填充；仍属 **阶段 B** 必做验证项。 | + +--- + +## 二、分阶段修复计划 + +### 阶段 A：区分「路由假象」与「真失败」（用户态 + ALSA） + +**目标**：确认是 **PipeWire 只显示一个 sink**，还是 **ALSA 层也打不开 HDMI PCM**。 + +| 步骤 | 动作 | 产出 | +|------|------|------| +| A1 | `aplay -L`、`aplay -l`，记录所有 **hdmi / HDMI / iDisp** 相关 device | 文本或截图 | +| A2 | 对每个候选 **`plughw:卡号,设备号`** 执行 **`speaker-test -c2 -l1`**（时长可短）；**设备与 HDMI1/2/3 对应** 可用同机 ChromeOS 已采集结果对照，见 [PHASE_A_DEVICE_MAP_CHROMEOS_COLLECTED.md](PHASE_A_DEVICE_MAP_CHROMEOS_COLLECTED.md) | 成功/失败/报错原文 | +| A3 | 图形界面检查 **默认输出** 是否锁死在错误设备 | — | +| A4 | 运行 **[collect_linux_audio_topology.sh](../../audio_topology/collect_linux_audio_topology.sh)**（建议 sudo），保存到 **`audio_topology/collected/`** | 带日期的采集包 | + +**决策**： + +- **若 ALSA 直连某 HDMI 设备可响**：优先 **WirePlumber/PipeWire profile**（用户态），不必先改内核。 +- **若所有 HDMI 设备均失败或 dmesg 出现 `STREAM_PCM_PARAMS` / `ipc` 错误**：进入 **阶段 B**。 + +**参考**：[REPAIR_Plan_Audio.md](../../audio_topology/REPAIR_Plan_Audio.md) §1.2、[REANALYSIS_Linux_HDMI_Audio_Kaisa.md](REANALYSIS_Linux_HDMI_Audio_Kaisa.md) §3。 + +--- + +### 阶段 B：HWE 6.17 自编内核 + 仓库 0001（及可选诊断补丁） + +**目标**：在 **与发行版版本对齐** 的源码上，验证 **FREE/trigger 与 Chrome 对齐** 后，HDMI 是否改善；并保留 **可对比的 dmesg**。 + +| 步骤 | 动作 | 产出 | +|------|------|------| +| B1 | `apt source linux-hwe-6.17=<与 `uname -r` 前缀一致的 Version>`，见 [kernel-src/README.md](../../kernel-src/README.md) | 解压树与 `.dsc` 记录 | +| B2 | [verify-ubuntu-hwe617-0001-patch.sh](../../scripts/verify-ubuntu-hwe617-0001-patch.sh) dry-run | 通过或「已应用」说明 | +| B3 | `PATCH=$PWD/patches/ubuntu-hwe-6.17/0001-....patch` → [ubuntu-hwe-617-build.sh](../../scripts/ubuntu-hwe-617-build.sh) `apply` → `deps` → `build` | 构建日志 | +| B4 | 安装 **linux-image-unsigned**、**linux-modules**、**linux-modules-extra**、按需 **iwlwifi**，见 [OPERATION_Install_CustomKernel_Ubuntu_HWE617.md](../kernel-build/OPERATION_Install_CustomKernel_Ubuntu_HWE617.md) | 可启动系统 | +| B5 | 重复 **阶段 A** + `dmesg` 过滤（`sof`、`STREAM_PCM`、`ipc`、`iDisp`） | 前后对比的 `collected/` | + +**可选（诊断、不改变成功路径语义时）**： + +- **0002**：`STREAM_PCM_PARAMS` 字段 **`spcm_dbg`**（需 `sof_debug` 位）；见 [DIFF_SUMMARY.txt](../../patches/ubuntu-hwe-6.17/DIFF_SUMMARY.txt)。 +- **0003**：`hda-dai.c` 内 **`hda_link_dma_hw_params` 前 `dev_dbg`**（需 dynamic_debug）；见同目录 README。 + +**决策**： + +- **HDMI 恢复**：固化内核版本与补丁列表，在 [WORK_PROGRESS.md](../meta/WORK_PROGRESS.md) 记结论。 +- **仍失败且仍为 `STREAM_PCM_PARAMS -EIO`**：进入 **阶段 C**（**不要**在 `ipc3-pcm.c` 里对载荷做无依据微调）。 + +--- + +### 阶段 C：按对比结论锁定「下一刀」——HDA 链路与可观测性 + +**目标**：在 **主机侧** 证实或排除 **link DMA / `stream_tag` / `format_val` / 时序** 问题；**仍不**建议整文件替换 `hda-dai.c`。 + +| 步骤 | 动作 | 依据 | +|------|------|------| +| C1 | 对 **`hda_link_dma_hw_params`**、**`snd_hdac_ext_bus_link_set_stream_id`**（及需要的 **`hda_dsp_pcm_hw_params`**）开 **dynamic_debug** 或 **0003**，复现一次 HDMI 播放 | [STREAM_PCM_PARAMS_CHROME_UBUNTU_NOTES.md](../../patches/ubuntu-hwe-6.17/STREAM_PCM_PARAMS_CHROME_UBUNTU_NOTES.md) §6.1 | +| C2 | 可选：root 下跑 **[collect-hda-link-ftrace.sh](../../scripts/collect-hda-link-ftrace.sh)**，保存 **function_graph** | 同节；样例见 `audio_topology/collected/hda_link_ftrace_*.txt` | +| C3 | 若证据指向 **`hstream->format_val`** 与 **dspless** 分支：再评估 **极小补丁**（高风险，需上游参与） | 同文件 §6.2、§6.3 | + +**产出**：**能说明「先 set_stream_id 还是先 PARAMS」** 的日志或 ftrace 片段，作为 **最小内核补丁** 或 **上游 issue** 附件。 + +--- + +### 阶段 D：双树 diff 与上游复现包 + +**目标**：在 **阶段 C** 仍无解或判定为 **固件/拓扑组合** 时，转向 **社区**而非继续盲试。 + +| 步骤 | 动作 | 产出 | +|------|------|------| +| D1 | 确认 **双树** 存在：`chromiumos_kernel/v5.15`、`kernel-src/linux-hwe-6.17-*`；必要时 **unshallow**，见 [OPERATION_ChromeOS_Kernel_Deep_Diff.md](../kernel-build/OPERATION_ChromeOS_Kernel_Deep_Diff.md) | — | +| D2 | [export-boards-chrome-ubuntu-diff.sh](../../scripts/export-boards-chrome-ubuntu-diff.sh)、[export-chromeos-ubuntu-sound-file-diffs.sh](../../scripts/export-chromeos-ubuntu-sound-file-diffs.sh) | `patches/ubuntu-hwe-6.17/reference/*.txt` | +| D3 | 阅读 **[SOURCE_DIFF_CHROMEOS515_UBUNTU617.md](SOURCE_DIFF_CHROMEOS515_UBUNTU617.md)**，**仅**对 diff 中与 **iDisp/HDMI** 相关的 hunk 提 **最小移植假设**（若有） | 设计笔记 | +| D4 | 按 [UPSTREAM_SOF_Kaisa_HDMI_REPRO.md](UPSTREAM_SOF_Kaisa_HDMI_REPRO.md) 准备 **alsa-info、dmesg、拓扑/固件版本、复现命令** | 可发送上游的包 | + +--- + +## 三、明确延后或不做的事项（与源码对比一致） + +| 事项 | 原因 | +|------|------| +| **仅换 tplg / 仅换 intel-signed 固件** | 仓库已证 **单独不足以** 恢复 HDMI；见路线图 §二、[ANALYSIS_Audio.md](../../audio_topology/ANALYSIS_Audio.md)。 | +| **Ubuntu Mainline 5.15 deb 当「ChromeOS 5.15 替身」** | 真机易出现 **3.5mm/WiFi 全挂**；见 [REANALYSIS_Linux_HDMI_Audio_Kaisa.md](REANALYSIS_Linux_HDMI_Audio_Kaisa.md)。 | +| **整文件覆盖 `hda-dai.c` 或 `ipc3-pcm.c` hw_params 段** | 架构/语义分析见 [SOURCE_DIFF](SOURCE_DIFF_CHROMEOS515_UBUNTU617.md)、STREAM_PCM 笔记。 | +| **把 5.15 的 `dpcm_playback` 写回 6.17** | API 已迁至 **`playback_only`**；见 SOURCE_DIFF §2.1、[CHROMEOS_VS_UBUNTU_HDMI_NOTES.md](CHROMEOS_VS_UBUNTU_HDMI_NOTES.md)。 | + +--- + +## 四、成功标准（与主路线图一致） + +- **客观**：目标 HDMI 口播放时，**无**与本次播放相关的 **`STREAM_PCM_PARAMS` 失败** / **`ipc tx error`**（或已确认为无害）。 +- **主观**：显示器音频输出稳定可听。 +- **回归**：**3.5mm、WiFi** 等与 HDMI 补丁无关项无退化（自编内核时 **modules-extra / iwlwifi** 装全）。 + +--- + +## 五、文档关系 + +| 文档 | 角色 | +|------|------| +| [Linux_HDMI_Audio_Roadmap.md](Linux_HDMI_Audio_Roadmap.md) | **主路线图**（阶段编号 L1–L4 与 README 任务表对应） | +| 本文 | **源码对比驱动的修复计划**（决策树 + 优先级） | +| [SOURCE_DIFF_CHROMEOS515_UBUNTU617.md](SOURCE_DIFF_CHROMEOS515_UBUNTU617.md) | 双树差异摘要 | +| [CHROMEOS_KAISA_AUDIO_KERNEL_PATHS.md](CHROMEOS_KAISA_AUDIO_KERNEL_PATHS.md) / [KERNEL_SRC_LINUX_HWE617_HDMI_3.5MM_PATHS.md](KERNEL_SRC_LINUX_HWE617_HDMI_3.5MM_PATHS.md) | 单树研读笔记 | + +--- + +**维护**：实验阶段推进时，在 [WORK_PROGRESS.md](../meta/WORK_PROGRESS.md) 更新「Linux HDMI 当前阶段」；避免仅改本文而不更新主路线图与进度。 diff --git a/docs/linux-hdmi/KERNEL_SRC_LINUX_HWE617_HDMI_3.5MM_PATHS.md b/docs/linux-hdmi/KERNEL_SRC_LINUX_HWE617_HDMI_3.5MM_PATHS.md new file mode 100644 index 0000000000..6bf2d6506e --- /dev/null +++ b/docs/linux-hdmi/KERNEL_SRC_LINUX_HWE617_HDMI_3.5MM_PATHS.md @@ -0,0 +1,149 @@ +# Linux 上游（Ubuntu HWE 6.17 树）：HDMI（iDisp）与 3.5mm（rt5682）内核实现研读 + +**体例**：[../meta/DOCUMENTATION_STYLE.md](../meta/DOCUMENTATION_STYLE.md)。基于 **`kernel-src/linux-hwe-6.17-6.17.0/`**（[kernel-src/README.md](../../kernel-src/README.md)）说明 **6.17** 上 HDMI（iDisp）与 3.5mm（rt5682）衔接。**ChromiumOS 5.15 对称笔记**：[CHROMEOS_KAISA_AUDIO_KERNEL_PATHS.md](CHROMEOS_KAISA_AUDIO_KERNEL_PATHS.md)（行号与 API 以 **6.17** 本文为准）。 + +--- + +## 1. 目的与范围 + +| 项目 | 说明 | +|------|------| +| **本文覆盖** | `sof_board_helpers.c` 中 DAI link 构造、`sof_rt5682.c` 中 quirk 与 `ctx` 初始化、`hda-dai.c` 中 HDA 扩展总线 link 与 stream tag 绑定；**不涉及** PipeWire/WirePlumber 路由策略。 | +| **源码根** | 相对路径：`kernel-src/linux-hwe-6.17-6.17.0/`（若本机未迁入，按 `kernel-src/README.md` 拉取）。 | + +--- + +## 2. 数据路径总览（概念） + +```mermaid +flowchart LR + subgraph fe [用户可见 PCM] + ALSA_FE[ALSA FE / DPCM 前端] + end + subgraph be_analog [模拟耳机链] + SSPx[SSPx Pin SOF] + RT5682[rt5682 I2C rt5682-aif1] + end + subgraph be_hdmi [HDMI 数字链] + iDisp[iDispN Pin SOF] + Ehda[ehdaudio0D2 intel-hdmi-hifiN] + end + ALSA_FE --> SSPx + ALSA_FE --> iDisp + SSPx --> RT5682 + iDisp --> Ehda +``` + +- **耳机 / 3.5mm**：**SSP** 上的 **I2S/TDM** 到 **Realtek rt5682**（板级多为 `rt5682-aif1`）。 +- **HDMI**：**SOF 侧 `iDispN Pin`** 经 **HDA 扩展 link** 接到 **Intel display audio codec**（`ehdaudio0D2` 上的 `intel-hdmi-hifiN`），或拓扑中 **dummy codec**（`idisp_codec == false` 时）。 + +--- + +## 3. HDMI（iDisp）实现要点 + +### 3.1 `DEFAULT_LINK_ORDER` 与 BE 生成 + +文件：**`sound/soc/intel/boards/sof_board_helpers.c`** + +- 与 `sof_rt5682` 配套的顺序宏 **`DEFAULT_LINK_ORDER`**：先 **Codec（耳机）**，再 DMIC，再 **iDisp HDMI**，再 AMP / BT offload / HDMI-In 等（约 145–152 行）。 +- **`set_idisp_hdmi_link()`**（约 274–329 行）为每个 HDMI 索引建立一条 BE： + - **link 名**：`iDisp{hdmi_id}`； + - **CPU DAI**：`iDisp{hdmi_id} Pin`； + - **`idisp_codec == true`**：`ehdaudio0D2` + `intel-hdmi-hifi{hdmi_id}`； + - **否则**：`snd_soc_dummy_dlc`； + - **`no_pcm = 1`**、**`playback_only = 1`**；**`hdmi_id == 1`** 时 **`init = hdmi_init`**（用于保存 `hdmi_comp` 供 late_probe 使用）。 + +### 3.2 `hdmi_num` 与 Google Rex（Kaisa 族）quirk + +**`sof_intel_board_get_ctx()`**（约 736–775 行）： + +- 从 **`board_quirk`** 的 **`SOF_NUM_IDISP_HDMI_MASK`** 解析 **`ctx->hdmi_num`**； +- **若为 0，则默认 `ctx->hdmi_num = 3`**（约 751–755 行）。 + +**`sof_rt5682.c`** 中 **Google_Rex** 条目（约 115–126 行）的 **`driver_data`** 包含 **SSP 端口、BT offload** 等，**未** 显式设置 **`SOF_NUM_IDISP_HDMI(n)`**。因此在 **6.17 树** 上 Rex 仍会得到 **默认 3 条** iDisp HDMI BE（与 ChromeOS 5.15 条目中显式 **`SOF_RT5682_NUM_HDMIDEV(3)`** 的写法不同，**效果上** 常一致）。 + +**`sof_audio_probe()`**（约 634 行起）：若 ACPI **`mach_params.codec_mask & IDISP_CODEC_MASK`**，则 **`ctx->hdmi.idisp_codec = true`**（约 665–666 行），与真实 HDA HDMI codec 路径一致。 + +### 3.3 `late_probe`：HDMI 控制与 ELD + +**`sof_intel_board_card_late_probe()`**（`sof_board_helpers.c` 约 23–37 行）：在 **`hdmi_num != 0`** 且 **`idisp_codec`** 且已取得 **`hdmi_comp`** 时，调用 **`hda_dsp_hdmi_build_controls()`**，用于 **HDMI 相关控件 / ELD** 等。 + +**`sof_rt5682.c`** 的 **`sof_card_late_probe()`**（约 404–420 行）在部分 AMP 特殊处理之后，**委托** **`sof_intel_board_card_late_probe(card)`**。 + +### 3.4 SOF Intel：`hda-dai.c` 与 link DMA（6.17 抽象） + +文件：**`sound/soc/sof/intel/hda-dai.c`** + +- 通过 **`hda_dai_get_ops()`**（约 69–104 行）按 **DAI widget** 选择 **`hda_dai_widget_dma_ops`**（含 **`get_hlink` / `get_hext_stream`** 等）；支持 **DSpless** 等变体时走 **`hda_select_dai_widget_ops`**。 +- **`hda_link_dma_hw_params()`**（约 156–213 行）：取得 **`hdac_ext_link`** 与 **`hext_stream`** 后，在 **playback** 路径上： + - 打 **`dev_dbg(..., "hda_link_dma_hw_params: link %p stream_tag %d\n", ...)`**（约 191–193 行）； + - 调用 **`snd_hdac_ext_bus_link_set_stream_id(hlink, stream_tag)`**（约 190–195 行）——把 **HDA 扩展总线 link** 与 **stream tag** 绑定（与旧版 **`snd_hdac_ext_link_set_stream_id`** 语义同级，属 API 封装演进）。 +- 清理路径 **`hda_link_dma_cleanup()`**（约 106–154 行）对 playback 调用 **`snd_hdac_ext_bus_link_clear_stream_id`**（约 128–130 行）。 + +> **对照**：ChromiumOS 5.15 笔记中函数名与 **无 widget ops 表** 的写法不同；**IPC3/IPC4、`STREAM_PCM_PARAMS`** 级别差异仍以 [STREAM_PCM_PARAMS_CHROME_UBUNTU_NOTES.md](../../patches/ubuntu-hwe-6.17/STREAM_PCM_PARAMS_CHROME_UBUNTU_NOTES.md) 为准。 + +--- + +## 4. 3.5mm / 耳机（rt5682）实现要点 + +### 4.1 BE：`set_ssp_codec_link` + Codec 侧绑定 + +**`set_ssp_codec_link()`**（`sof_board_helpers.c` 约 178–222 行）： + +- **link 名**：`SSP{ssp_codec}-Codec`； +- **CPU DAI**：非 BYT/CHT 时为 **`SSP{ssp_codec} Pin`**； +- **`no_pcm = 1`**；**codecs** 由 machine 填充。 + +**`sof_card_dai_links_create()`**（`sof_rt5682.c` 约 526–624 行）在调用 **`sof_intel_board_set_dai_link()`** 之后，为 **RT5682** 设置： + +- **`ctx->codec_link->codecs = rt5682_component`**（约 547–549 行）； +- **`rt5682_component`** 示例（约 501–505 行）：**`i2c-10EC5682:00`** + **`rt5682-aif1`**（具体 ACPI/I2C 名以机器为准）； +- **`init` / `exit` / `ops`**：**`sof_rt5682_codec_init`**、**`sof_rt5682_codec_exit`**、**`sof_rt5682_ops`**（约 560–562 行）。 + +### 4.2 `sof_rt5682_codec_init`：MCLK/ASRC、Jack + +**`sof_rt5682_codec_init()`**（约 141 行起）：按 **codec 类型** 处理 **MCLK**、**24 MHz ASRC**（**`rt5682_sel_asrc_clk_src`** 等）、**legacy CPU** 时钟行为；并注册 **Headphone / Headset Mic** jack（与 **jack_pins**、**sof_widgets** / **sof_map** 一致，见约 130–139、427–439 行）。 + +### 4.3 `sof_rt5682_hw_params`：PLL、sysclk、TDM + +**`sof_rt5682_hw_params()`**（约 297–397 行）：设置 **PLL**、**sysclk**、**`snd_soc_dai_set_tdm_slot`**，与拓扑中的格式一致。 + +### 4.4 Google Rex 的 SSP 分配（6.17） + +**Rex** quirk（约 120–125 行）：**`SOF_SSP_PORT_CODEC(2)`** ——— 耳机 Codec 走 **SSP2**（与 ChromeOS 5.15 条目中 **SSP2** 一致）。 + +--- + +## 5. 与 ChromiumOS 5.15 笔记的关系 + +**双树 unified diff 与对比摘要全文**：[SOURCE_DIFF_CHROMEOS515_UBUNTU617.md](SOURCE_DIFF_CHROMEOS515_UBUNTU617.md)。 + +| 主题 | ChromiumOS 5.15 文档 | 本文（HWE 6.17 树） | +|------|----------------------|---------------------| +| Machine 分层 | [CHROMEOS_KAISA_AUDIO_KERNEL_PATHS.md](CHROMEOS_KAISA_AUDIO_KERNEL_PATHS.md) | 同文件 **`sof_board_helpers.c` / `sof_rt5682.c`**，行号与 Rex **quirk 位域** 以 **本树** 为准 | +| HDA link DMA | 旧式 **`hda_link_dma_params`** 调用链 | **`hda_dai_widget_dma_ops`** + **`snd_hdac_ext_bus_link_set_stream_id`** | +| Rex HDMI 条数 | 显式 **`SOF_RT5682_NUM_HDMIDEV(3)`** | 6.17 Rex **未**写 `SOF_NUM_IDISP_HDMI`，**默认 3** | + +--- + +## 6. 参考命令 + +```bash +cd kernel-src/linux-hwe-6.17-6.17.0 +# 快速定位本笔记涉及的符号 +rg -n "set_idisp_hdmi_link|DEFAULT_LINK_ORDER|sof_intel_board_get_ctx" sound/soc/intel/boards/sof_board_helpers.c +rg -n "Google_Rex|sof_rt5682_codec_init|IDISP_CODEC_MASK" sound/soc/intel/boards/sof_rt5682.c +rg -n "hda_link_dma_hw_params|hda_dai_get_ops|snd_hdac_ext_bus_link_set_stream_id" sound/soc/sof/intel/hda-dai.c +``` + +--- + +## 7. 小结 + +| 输出 | Linux HWE 6.17（`kernel-src` 树）主路径 | +|------|----------------------------------------| +| **HDMI / DisplayPort 数字音频** | **`sof_board_helpers.c`**：`set_idisp_hdmi_link` → **`iDispN Pin`** +（可选）**`ehdaudio0D2` / `intel-hdmi-hifiN`**；条数 **`ctx->hdmi_num`**（quirk 或 **默认 3**）；**`late_probe`** → **`hda_dsp_hdmi_build_controls`**。 | +| **3.5mm / 耳机** | **`set_ssp_codec_link`** → **`SSPx Pin`** + **`rt5682-aif1`**；**`sof_rt5682_codec_init` / `sof_rt5682_hw_params`** 管 **jack、PLL、TDM**。 | +| **HDA 与 DMA** | **`hda-dai.c`**：**`hda_link_dma_hw_params`** 内 **`snd_hdac_ext_bus_link_set_stream_id`** 绑定 link 与 stream tag。 | + +用户态 **多 sink / profile** 是否出现，还取决于 **PipeWire/WirePlumber** 与 **ALSA 卡拓扑**；内核侧上述 **BE** 与 **link DMA** 建好后，应配合 **`aplay -L`** / **`pactl list sinks`**（若安装）或 **直接 ALSA** 验证。 diff --git a/docs/linux-hdmi/Linux_HDMI_Audio_Roadmap.md b/docs/linux-hdmi/Linux_HDMI_Audio_Roadmap.md index 6823006439..adc7569efa 100644 --- a/docs/linux-hdmi/Linux_HDMI_Audio_Roadmap.md +++ b/docs/linux-hdmi/Linux_HDMI_Audio_Roadmap.md @@ -3,7 +3,19 @@ 本文是 **Google Kaisa（Chromebox 10 代）+ Coreboot** 下 Linux **HDMI 无声音**问题的 **主路线图**。技术细节与论证见各专项文档；本文只固定 **顺序、产出物与维护方式**。 **全文档索引**：[INDEX.md](../INDEX.md) -**项目总览与问题表**：[../../README.md](../../README.md) +**项目总览与问题表**：[../../README.md](../../README.md) +**换机事实与当前状态**：[WORK_PROGRESS.md](../meta/WORK_PROGRESS.md)（与本文分工见下表） + +--- + +## 文档角色（与 `WORK_PROGRESS` 的分工） + +| 文档 | 职责 | +| ---- | ---- | +| **本文（路线图）** | **阶段顺序与建议**：各阶段「该做什么」、已排除方向、成功标准、维护方式（Mermaid 与章节编号） | +| **[`WORK_PROGRESS.md`](../meta/WORK_PROGRESS.md)** | **真机事实**：换机/clone、**日期**、**当前 `uname -r` / 补丁应用**、**阻塞项** | + +读 **顺序** 以本文为准；查 **「现在卡在哪、上次验证是哪天内核」** 以 `WORK_PROGRESS` 为准。两文件**互相链接**；若冲突，对照后更新 **事实**（`WORK_PROGRESS`）或 **阶段定义**（本文）。 --- @@ -14,6 +26,8 @@ - **dmesg 常见线索**：`STREAM_PCM_PARAMS` IPC 失败、约 **-5（EIO）**，常与 **pcm2/3/4（HDMI1/2/3）** 某条相关（物理口与编号需实测对照）。 - **非本仓库机型**：其它机器 HDMI 无声原因可能完全不同（独显、默认 sink、PipeWire 等），**勿直接套用**本仓库内核补丁；可借用 [阶段 1](#阶段-1用户态基线) 的排查套路，根因结论见各文档。 +**源码对比后的修复分支（A–D 决策）**：[FIX_PLAN_HDMI_FROM_SOURCE_ANALYSIS.md](FIX_PLAN_HDMI_FROM_SOURCE_ANALYSIS.md)（与本文互补，勿两处重复维护同一张现象表）。 + --- ## 二、已排除或低期望方向 @@ -91,7 +105,7 @@ flowchart LR ## 五、维护与「当前阶段」 -- **路线图正文**为本文件；**换机与源码 URL、实验结论**以 [WORK_PROGRESS.md](../meta/WORK_PROGRESS.md) 为准，两者应同步（WORK_PROGRESS 内「Linux HDMI 当前阶段」见该文件顶部）。 +- **路线图正文**为本文件；**换机与源码 URL、实验结论**以 [WORK_PROGRESS.md](../meta/WORK_PROGRESS.md) 为准，两者应同步（WORK_PROGRESS 内「Linux HDMI 当前阶段」见该文件顶部）。**阶段或成功标准相关结论变更时**，须按 [DOCUMENTATION_ARCHITECTURE · FR17](../meta/DOCUMENTATION_ARCHITECTURE.md) 交叉核对两处，避免事实矛盾。 - **任务编号 L1–L4** 与阶段对应关系见根 [README.md](../../README.md) 任务列表。 --- @@ -100,6 +114,8 @@ flowchart LR | 用途 | 链接 | | ---- | ---- | +| **源码对比驱动的修复计划**（阶段 A–D、决策分支） | [FIX_PLAN_HDMI_FROM_SOURCE_ANALYSIS.md](FIX_PLAN_HDMI_FROM_SOURCE_ANALYSIS.md) | +| 双树源码对比摘要 | [SOURCE_DIFF_CHROMEOS515_UBUNTU617.md](SOURCE_DIFF_CHROMEOS515_UBUNTU617.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) | diff --git a/docs/linux-hdmi/OPERATION_Kaisa_SOF_HDMI_Trace.md b/docs/linux-hdmi/OPERATION_Kaisa_SOF_HDMI_Trace.md index 732b523ea3..61144d5c22 100644 --- a/docs/linux-hdmi/OPERATION_Kaisa_SOF_HDMI_Trace.md +++ b/docs/linux-hdmi/OPERATION_Kaisa_SOF_HDMI_Trace.md @@ -1,6 +1,7 @@ # Kaisa：SOF HDMI `STREAM_PCM_PARAMS` 观测（dynamic_debug + IPC 载荷） -在 **jack-Kaisa 真机**（非本仓库 PVE/容器）上执行。目的：在 `STREAM_PCM_PARAMS` 失败前后看到 **发往 DSP 的 IPC 载荷**（`comp_id`、`buffer`、`stream_tag`、格式等），与拓扑/固件预期对照。 +**背景与现象**：见 [Linux_HDMI_Audio_Roadmap.md](Linux_HDMI_Audio_Roadmap.md) §一。 +在 **jack-Kaisa 真机**（非 PVE/容器）上执行；目的：在 `STREAM_PCM_PARAMS` 失败前后看到 **发往 DSP 的 IPC 载荷**（`comp_id`、`buffer`、`stream_tag`、格式等），与拓扑/固件预期对照。 ## 1. 前置条件 diff --git a/docs/linux-hdmi/PHASE_A_DEVICE_MAP_CHROMEOS_COLLECTED.md b/docs/linux-hdmi/PHASE_A_DEVICE_MAP_CHROMEOS_COLLECTED.md new file mode 100644 index 0000000000..6491fc963c --- /dev/null +++ b/docs/linux-hdmi/PHASE_A_DEVICE_MAP_CHROMEOS_COLLECTED.md @@ -0,0 +1,64 @@ +# 阶段 A：用 ChromeOS 采集确定 ALSA 设备对应关系（Kaisa） + +与 **[FIX_PLAN_HDMI_FROM_SOURCE_ANALYSIS.md](FIX_PLAN_HDMI_FROM_SOURCE_ANALYSIS.md) 阶段 A** 同一目标；本文只固化 **Kaisa 上 card0 device 与 HDMI1/2/3 的映射**及仓库内采集文件指针。 + +**设备编号与 HDMI1/2/3 命名** 可与同机 **ChromeOS 已采集** 的 `aplay` / CRAS 输出对照，减少盲目试错。 + +**数据来源（仓库内）**： + +| 采集文件 | 内容要点 | +|----------|----------| +| [audio_topology/collected/audio_topology_chromeos_localhost_20260214_101603.txt](../../audio_topology/collected/audio_topology_chromeos_localhost_20260214_101603.txt) | 含 **`aplay -l`**、**`aplay -L`**、HDMI codec / ELD 片段 | +| [audio_topology/collected/audio_linux_scripts_on_chromeos_localhost_20260214_104859_20260214_104933.txt](../../audio_topology/collected/audio_linux_scripts_on_chromeos_localhost_20260214_104859_20260214_104933.txt) | 在 ChromeOS 上跑的脚本输出，含 **`aplay -l`** | +| [audio_topology/collected/audio_chrome_system.txt](../../audio_topology/collected/audio_chrome_system.txt) | **`cras_test_client --dump_server_info`**：CRAS 节点与 **`pcm=N`**、显示器名 | + +**Linux 侧同类采集（对照用）**： + +- [audio_topology/collected/audio_topology_linux_jack-Kaisa_20260404_200845.txt](../../audio_topology/collected/audio_topology_linux_jack-Kaisa_20260404_200845.txt)：`aplay -l` 与 ChromeOS **同一编号模式**（card 0，device 0/2/3/4）。 + +--- + +## 1. 本机（采集时）确定的映射：`card 0` = `sof-rt5682` + +以下摘自 ChromeOS 采集中的 **`aplay -l`**（三处文件一致）： + +| device | ALSA 名称 | 用途 | +|--------|-----------|------| +| **0** | Port1 | **模拟输出 / 耳机**（与 3.5mm 链路对应） | +| **1** | DMIC | 麦克风（回放阶段 A 可忽略） | +| **2** | HDMI1 | HDMI 数字音频一路 | +| **3** | HDMI2 | HDMI 数字音频一路 | +| **4** | HDMI3 | HDMI 数字音频一路 | + +**阶段 A 测试 HDMI 时**，优先对 **`plughw:0,2`**、**`plughw:0,3`**、**`plughw:0,4`** 分别执行 `speaker-test`（若你当前系统上 **card 号不是 0**，以本机 `aplay -l` 为准，仅 **device 与名称** 沿用此表）。 + +--- + +## 2. CRAS 节点与 `pcm=N`（ChromeOS 用户态） + +摘自 [audio_chrome_system.txt](../../audio_topology/collected/audio_chrome_system.txt) 中 **Output Nodes**： + +- **`sof-rt5682 HDMI/DP,pcm=2`** ↔ 与 ALSA **device 2（HDMI1）** 一条链（命名上「HDMI1」与 pcm 编号不同属正常：丝印 HDMI1/2/3 对应 **device 2/3/4**）。 +- **`sof-rt5682 HDMI/DP,pcm=4`** ↔ **device 4（HDMI3）**。 +- 采集时 **ASUS MG279** 插在 **HDMI2** 对应节点（CRAS 显示为 **HDMI / 已插**），与 **`device 3: HDMI2`** 一致。 + +**注意**：**机箱丝印 HDMI1/2/3** 与 **ALSA 的 HDMI1/2/3 字符串** 是否一一对应，仍建议用 **插拔单根线 + 看 `aplay -L` / ELD** 做一次实测；上表保证的是 **软件层 device 编号与 CRAS/ALSA 命名** 在采集机上的一致性。 + +--- + +## 3. 与阶段 A 文档的关系 + +- 阶段 A 步骤仍见 [FIX_PLAN_HDMI_FROM_SOURCE_ANALYSIS.md](FIX_PLAN_HDMI_FROM_SOURCE_ANALYSIS.md) **阶段 A**、[REPAIR_Plan_Audio.md](../../audio_topology/REPAIR_Plan_Audio.md) §1.2。 +- 本文只解决 **「先试哪几个 `plughw:卡,设备`」**，不替代本机 **`aplay -l`** 核对（内核/驱动更新后 card 号可能变化）。 + +--- + +## 4. 采集脚本（补充 ChromeOS 时） + +若需更新 ChromeOS 侧拓扑，见 [audio_topology/COLLECT.md](../../audio_topology/COLLECT.md) 与仓库内 **ChromeOS** 采集脚本；新文件建议仍放入 **`audio_topology/collected/`** 并带日期与主机名。 + +--- + +## 5. Ubuntu 实测快照（阶段 A 完成） + +- **[PHASE_A_speaker-test_jack-Kaisa_20260404.md](../../audio_topology/collected/PHASE_A_speaker-test_jack-Kaisa_20260404.md)**：`plughw:0,2/3/4` **不报错、HDMI 无声**；`0,0` 为 3.5mm。下一步 **阶段 B**（0001 自编内核）。 diff --git a/docs/linux-hdmi/REANALYSIS_Linux_HDMI_Audio_Kaisa.md b/docs/linux-hdmi/REANALYSIS_Linux_HDMI_Audio_Kaisa.md index 749db66445..1b940d6e64 100644 --- a/docs/linux-hdmi/REANALYSIS_Linux_HDMI_Audio_Kaisa.md +++ b/docs/linux-hdmi/REANALYSIS_Linux_HDMI_Audio_Kaisa.md @@ -1,43 +1,20 @@ # Kaisa（Chromebox 10 代）Linux HDMI 音频：重新分析与修复路径 -本文在已有采集与对照结论基础上，**合并真机后续结果**（含：自编 HWE 6.17、历史 HDMI 补丁实验、安装方式与 WiFi 回归等），重新整理「问题是什么、什么已基本排除、下一步该怎么试」。 +在已有采集与路线图结论上，补充**重分析**（自编内核、Mainline 5.15 误区、安装踩坑）与**可执行优先级**。**现象与已排除项**以 **[Linux_HDMI_Audio_Roadmap.md](Linux_HDMI_Audio_Roadmap.md) §一、§二** 为准，本文不重复扩表。 -**仍请以以下为权威细节**： - -- 三平台对比与 dmesg：`audio_topology/ANALYSIS_Audio.md` -- 总修复顺序与文档索引：`audio_topology/REPAIR_Plan_Audio.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` +**权威交叉引用**：三平台数据 `audio_topology/ANALYSIS_Audio.md`；总顺序 `audio_topology/REPAIR_Plan_Audio.md`；API 对照 `CHROMEOS_VS_UBUNTU_HDMI_NOTES.md`；diff 流程 `../kernel-build/OPERATION_ChromeOS_Kernel_Deep_Diff.md`；安装 deb `../kernel-build/OPERATION_Install_CustomKernel_Ubuntu_HWE617.md`。 --- -## 一、现象（Linux 侧） +## 一、排除项（与路线图一致；仅补充一句） -- 机器：**Google Kaisa**，Coreboot 环境；声卡为 **SOF + `sof-rt5682`** 一类拓扑，HDMI 走 **iDisp / DisplayPort 音频** 链路。 -- **3.5mm**：Linux 上通常 **正常**。 -- **HDMI**：Linux 上 **无输出或无法稳定打开 PCM**；历史 dmesg 典型为 **`STREAM_PCM_PARAMS` IPC 失败、约 -5（EIO）**，常与 **pcm2/3/4（HDMI1/2/3）** 中某几条相关（物理口与 pcm 编号需实测对照）。 -- **对照**：同机 **ChromeOS（5.15 内核）HDMI 正常**；**Windows HDMI 正常**。说明硬件与显示器链路整体可用，**问题集中在 Linux 内核/SOF/用户态路由**，而非「线坏了」一类。 +**[Linux_HDMI_Audio_Roadmap.md](Linux_HDMI_Audio_Roadmap.md) §二** 已汇总 tplg、仅换固件、旧 TRIGGER 补丁、Mainline 5.15、NHLT。**请勿在本节另建一张长表**；若路线图更新，以路线图为准。 + +**Mainline 5.15 ≠ ChromeOS 5.15**：前者为 kernel.ubuntu.com Mainline 等与 Noble 的组合；后者为 Google 定制 + CRAS。**不能**用 Mainline 5.15 deb「复现 Chrome 行为」。详细步骤与真机结论见 **§3** 第 2 小节与文末**附录**。 --- -## 二、已基本排除或证明「单独不够」的方向 - -| 方向 | 结论 | 依据（仓库内） | -|------|------|----------------| -| **拓扑 tplg** | 与 ChromeOS **等效**（解压后规模一致、端点一致） | `ANALYSIS_Audio.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」** | - -**重要区分**：**ChromeOS 上正常的「5.15」** 是 **Google 定制内核 + CRAS + 其配置/补丁**；**Ubuntu Mainline 的 5.15** 是 **Vanilla 主线 + 与 Noble 用户态/固件/模块集合的组合**，**二者不能等同**。因此在 Mainline 5.15 上「HDMI 仍坏 + 其它输出也坏」**并不能推翻**「发行版 6.x 相对某条 Ubuntu/Chrome 5.15 路径在 HDMI 上存在差异」这类判断，只能说明 **单靠换 Mainline 5.15 deb 不是可行修复手段**。 - -**推论（修订）**：HDMI 仍优先从 **6.x 下 SOF / Intel / DPCM / iDisp** 与 **Kaisa + Coreboot** 的交互继续查（含上游报 bug、bisect **Ubuntu 或上游 linux.git**）；**不要**把「装了 Mainline 5.15」误认为「复现了 ChromeOS 5.15 行为」。 - ---- - -## 三、自定义内核相关：避免「假阴性」 +## 二、自定义内核相关：避免「假阴性」 在继续改内核前，建议先确认实验条件可靠（否则会出现「补丁无效」误判）： @@ -47,7 +24,7 @@ --- -## 四、推荐修复路径（按性价比重排） +## 三、推荐修复路径（按性价比重排） 下列顺序在 **不推翻已有结论** 的前提下，把精力集中到最可能见效的方向。 @@ -96,7 +73,7 @@ --- -## 五、结论摘要（给决策用） +## 四、结论摘要（给决策用） ```mermaid flowchart LR @@ -111,14 +88,14 @@ flowchart LR ``` - **HDMI 问题性质**：更可能是 **Linux（尤其 6.x 发行版栈）里 SOF/Intel/iDisp 路径与 Kaisa + Coreboot 的组合问题**；拓扑与「只换一份 SOF 固件」已反复证明**不够**。 -- **旧 0001/0002**：已自仓库移除；**新补丁**按 [`../kernel-build/OPERATION_ChromeOS_Kernel_Deep_Diff.md`](../kernel-build/OPERATION_ChromeOS_Kernel_Deep_Diff.md) 流程重做。 +- **历史 0002（`set_idisp_hdmi_link` 内 TRIGGER_POST）**：已从仓库删除。**0001**（FREE/trigger）与**当前** `patches/ubuntu-hwe-6.17/` 内 **0002（诊断）/0003** 仍以目录 [README](../../patches/ubuntu-hwe-6.17/README.md) 为准；**新功能性补丁**按 [`../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）** 装全，并保留可启动旧内核。 --- -## 六、文档维护建议 +## 五、文档维护建议 若你完成 **5.15 Live** 或 **上游 issue** 链接，可把结果摘要回写到 `../../audio_topology/ANALYSIS_Audio.md`（新增一小节）与 `../meta/WORK_PROGRESS.md` 状态表，避免后人重复踩旧实验补丁/仅装两 deb/unsigned 冲突等坑。 @@ -205,14 +182,14 @@ uname -r --- -## 七、当前在 **6.17.0-20-generic** 上的建议 + 如何查 **ChromeOS 定制补丁** +## 六、当前在 **6.17.0-20-generic** 上的建议 + 如何查 **ChromeOS 定制补丁** ### 7.1 对「jack-Kaisa @ 6.17.0-20」的优先级建议 - **这是合理的主力内核**：官方 **signed** HWE，模块栈与 Noble 用户态匹配，比自编 unsigned / Mainline 5.15 **更适合日常与排障**。 - **先固定一条基线**：在本内核上再采一份 `dmesg`（SOF/HDMI 段）、`aplay -L`、`alsa-info`，命名带 `6.17.0-20`，放进 `audio_topology/collected/`，与旧版 6.17.0-14/19 对比是否 **IPC 行号/PCM 编号** 有变化。 - **并行两条线**（不必等 ChromeOS diff 做完才报上游）： - 1. **上游**：用 **6.17.0-20** + Kaisa + Coreboot +「ChromeOS 同机 HDMI 正常」打 **SOF/ALSA** issue 或邮件列表（材料见第四节）。 + 1. **上游**：用 **6.17.0-20** + Kaisa + Coreboot +「ChromeOS 同机 HDMI 正常」打 **SOF/ALSA** issue 或邮件列表（材料见上文 **§三**「上游协同」与 [UPSTREAM_SOF_Kaisa_HDMI_REPRO.md](UPSTREAM_SOF_Kaisa_HDMI_REPRO.md)）。 2. **内核 diff**：在本地对 **ChromiumOS 5.15 树** 做 **有范围的 git 历史 / 文件 diff**（见 7.2），找 **与 SOF / Intel / HDMI / CML / rt5682** 相关的提交，再判断能否 **移植到 6.17** 或交给上游。 ### 7.2 查看 ChromeOS **内核**里与音频相关的定制（推荐流程） diff --git a/docs/linux-hdmi/SOF_FIRMWARE_TOPO_Kaisa_CHECKLIST.md b/docs/linux-hdmi/SOF_FIRMWARE_TOPO_Kaisa_CHECKLIST.md index 2123e51295..36be565e37 100644 --- a/docs/linux-hdmi/SOF_FIRMWARE_TOPO_Kaisa_CHECKLIST.md +++ b/docs/linux-hdmi/SOF_FIRMWARE_TOPO_Kaisa_CHECKLIST.md @@ -1,8 +1,8 @@ # Kaisa：SOF 固件与拓扑一致性核对（排除 comp_id / 拓扑不匹配） -目的：在出现 `STREAM_PCM_PARAMS` **-EIO (-5)** 时，确认 **本机加载的固件与 tplg** 与项目基线一致，避免「内核与拓扑/固件版本错配」类问题。 +**体例**：[../meta/DOCUMENTATION_STYLE.md](../meta/DOCUMENTATION_STYLE.md)。**现象与「仅换固件不够」**见 [Linux_HDMI_Audio_Roadmap.md](Linux_HDMI_Audio_Roadmap.md) §二、[ANALYSIS_Audio.md](../../audio_topology/ANALYSIS_Audio.md)。 -基线分析见 **`audio_topology/ANALYSIS_Audio.md`**（第四节、第五节）。 +在 `STREAM_PCM_PARAMS` **-5** 时，核对 **本机固件/tplg** 与基线一致，排除错配；**深度 IPC 载荷**见 [OPERATION_Kaisa_SOF_HDMI_Trace.md](OPERATION_Kaisa_SOF_HDMI_Trace.md)。 ## 在 Kaisa 上采集 diff --git a/docs/linux-hdmi/SOURCE_DIFF_CHROMEOS515_UBUNTU617.md b/docs/linux-hdmi/SOURCE_DIFF_CHROMEOS515_UBUNTU617.md new file mode 100644 index 0000000000..bf71013a1b --- /dev/null +++ b/docs/linux-hdmi/SOURCE_DIFF_CHROMEOS515_UBUNTU617.md @@ -0,0 +1,124 @@ +# ChromiumOS 5.15 与 Ubuntu HWE 6.17 源码对比分析（HDMI / SOF / 板级） + +**体例**：[../meta/DOCUMENTATION_STYLE.md](../meta/DOCUMENTATION_STYLE.md)。**单文件 API 对照**（`set_idisp_hdmi_link`）：[CHROMEOS_VS_UBUNTU_HDMI_NOTES.md](CHROMEOS_VS_UBUNTU_HDMI_NOTES.md)。**`STREAM_PCM_PARAMS` 三文件链**：[STREAM_PCM_PARAMS_CHROME_UBUNTU_NOTES.md](../../patches/ubuntu-hwe-6.17/STREAM_PCM_PARAMS_CHROME_UBUNTU_NOTES.md)。 + +本文汇总两树上与 **Kaisa / `sof-rt5682` / iDisp** 相关的 **`diff -u` 可读结论**，并指向 **reference/** 与专项笔记。 + +**对照树（相对仓库根）**： + +| 树 | 路径 | +|----|--------| +| ChromiumOS 5.15 | `chromiumos_kernel/v5.15/` | +| Ubuntu HWE 6.17 | `kernel-src/linux-hwe-6.17-6.17.0/` | + +**重新生成 diff**（路径以本机为准）： + +```bash +./scripts/export-boards-chrome-ubuntu-diff.sh +./scripts/export-chromeos-ubuntu-sound-file-diffs.sh +# 输出默认：patches/ubuntu-hwe-6.17/reference/（可能被 .gitignore） +``` + +--- + +## 1. 参考文件体量（行数） + +对 `reference/diff-u_*.txt` 作 `wc -l` 的**数量级**（随双树版本略有浮动）： + +| 文件 | 约行数 | 主题 | +|------|--------|------| +| `diff-u_sound_soc_intel_boards_sof_board_helpers.c.txt` | ~360 | 板级 helper：DAI link、ctx、`dpcm_*`→`playback_only`/`capture_only`、新增 HDA 外置 codec 链 | +| `diff-u_sound_soc_intel_boards_sof_rt5682.c.txt` | ~720 | `sof_rt5682`：quirk 位域迁到公共头、DMI 表、Rex 行、codec_init/hw_params | +| `diff-u_sound_soc_sof_ipc3-pcm.c.txt` | ~170 | IPC3 PCM：`asoc_substream_to_rtd`→`snd_soc_substream_to_rtd`、日志与载荷可观测性 | +| `diff-u_sound_soc_sof_ipc3.c.txt` | ~290 | IPC3 核心（与 PCM/流控相邻） | +| `diff-u_sound_soc_sof_pcm.c.txt` | ~690 | SOF 通用 `pcm.c` | +| `diff-u_sound_soc_sof_intel_hda-dai.c.txt` | ~1365 | **HDA DAI / Link DMA**：5.15 与 6.17 **架构级差异**，非逐行可移植 | + +--- + +## 2. `sof_board_helpers.c`：行为与 API 迁移 + +### 2.1 DAI link 标志（与 ASoC 上游一致） + +- **5.15（Chrome）**：`struct snd_soc_dai_link` 仍大量使用 **`dpcm_playback` / `dpcm_capture`**。 +- **6.17**：上游已统一为 **`playback_only` / `capture_only`**（语义对应，见 `include/sound/soc.h`）。 + +**对 HDMI 的含义**：`set_idisp_hdmi_link` 在 5.15 为 `dpcm_playback = 1`，在 6.17 为 **`playback_only = 1`**。**勿**把旧标志名机械写回 6.17 补丁。 + +### 2.2 6.17 新增能力（与 Kaisa 无直接冲突） + +- **`SOF_LINK_HDA`**：`set_hda_codec_link()`、**Analog/Digital** 与 **HDA 外置 codec** 相关 widget/route（`hda_init` 等），在 `calculate_num_links` / `sof_intel_board_set_dai_link` 中增加分支。 +- **与 iDisp HDMI**：`set_idisp_hdmi_link()` 的 **CPU=`iDispN Pin`、codec=`ehdaudio0D2`/`intel-hdmi-hifiN`** 结构在两边仍可对齐阅读；差异主要在 **周边**（DPCM 标志名、EXPORT、模块 NS）。 + +### 2.3 辅助符号重构 + +- **5.15**：导出 **`get_codec_dai_by_name()`**。 +- **6.17**：改为 **`sof_intel_board_get_ctx()`**，在 **ctx** 中解析 **`board_quirk`** → **`hdmi_num`（默认 3）**、**SSP 端口**、**BT offload**、**HDMI-In mask** 等，与 [KERNEL_SRC_LINUX_HWE617_HDMI_3.5MM_PATHS.md](KERNEL_SRC_LINUX_HWE617_HDMI_3.5MM_PATHS.md) 一致。 + +### 2.4 类型与头文件 + +- Codec/AMP 类型由 **`enum sof_ssp_codec` + `sof_ssp_get_codec_name`** 等，迁为 **`enum snd_soc_acpi_intel_codec` + `snd_soc_acpi_intel_get_codec_name`**（ACPI 匹配层统一）。 + +--- + +## 3. `sof_rt5682.c`：quirk 模型与 Google Rex + +### 3.1 Quirk 位域 + +- **5.15**：本文件内自定义 **`SOF_RT5682_SSP_CODEC`**、**`SOF_RT5682_NUM_HDMIDEV`**、**`SOF_BT_OFFLOAD_SSP`** 等宏。 +- **6.17**：上述位移入 **`sof_board_helpers.h`** 等公共定义：**`SOF_SSP_PORT_CODEC`**、**`SOF_NUM_IDISP_HDMI`**、**`SOF_SSP_PORT_BT_OFFLOAD`**、**`SOF_BT_OFFLOAD_PRESENT`** 等，避免 machine 驱动各自重复。 + +### 3.2 DMI 表差异 + +- 部分 **5.15 独有** 条目（如 **Google_Hatch**、部分 **Ice Lake**）在 **6.17 上游** 可能被合并、移动或删除；以 **`diff-u_sound_soc_intel_boards_sof_rt5682.c.txt`** 为准。 +- **Google_Rex**： + - **5.15** 常显式带 **`SOF_RT5682_NUM_HDMIDEV(3)`**（或等价位域）。 + - **6.17** Rex 行往往 **不写 `SOF_NUM_IDISP_HDMI`**，依赖 **`sof_intel_board_get_ctx()` 默认 `hdmi_num = 3`**（与 [KERNEL_SRC_LINUX_HWE617_HDMI_3.5MM_PATHS.md](KERNEL_SRC_LINUX_HWE617_HDMI_3.5MM_PATHS.md) 小结一致）。 + +### 3.3 `codec_init` / `hw_params` + +- **MCLK / legacy**：由直接测 **`sof_rt5682_quirk & SOF_RT5682_MCLK_BYTCHT_EN`**，改为 **`ctx->rt5682.is_legacy_cpu`** 等 **ctx 字段**（更清晰，利于多板共用）。 + +--- + +## 4. `ipc3-pcm.c`：IPC 载荷与仓库补丁 + +- **API**：`asoc_substream_to_rtd` → **`snd_soc_substream_to_rtd`**（上游重命名）。 +- **`STREAM_PCM_PARAMS` 填充**：**`struct sof_ipc_pcm_params` 各字段语义** 在两边 **一致**（详见 [STREAM_PCM_PARAMS_CHROME_UBUNTU_NOTES.md](../../patches/ubuntu-hwe-6.17/STREAM_PCM_PARAMS_CHROME_UBUNTU_NOTES.md) §1）。 +- **6.17 上游** 已增加 **`spcm_dbg`**、可选 **`SOF_DBG_DUMP_IPC_MESSAGE_PAYLOAD`** 下的字段摘要（与仓库 **0002** 诊断思路同向）。 +- **FREE / trigger**：5.15 使用 **`sof_ipc_tx_message` 等待回复** 的路径与 Ubuntu 原版 **no_reply** 差异，由仓库 **[0001](../../patches/ubuntu-hwe-6.17/0001-ASoC-SOF-ipc3-pcm-await-DSP-reply-for-FREE-and-trigger.patch)** 对齐；**不改变** `hw_params` / `STREAM_PCM_PARAMS` 构造逻辑（见 [DIFF_SUMMARY.txt](../../patches/ubuntu-hwe-6.17/DIFF_SUMMARY.txt)）。 + +--- + +## 5. `hda-dai.c`：为何不宜整文件移植 + +- **5.15**：以 **`hda_pipe_params`**、**`hda_check_fes`** 等为中心的传统 link/stream 路径。 +- **6.17**：引入 **`hda_dai_config()`** 经 **tplg_ops->dai_config**；**Link DMA** 经 **`hda_dai_widget_dma_ops`**（**`get_hlink` / `get_hext_stream` / `snd_hdac_ext_bus_link_set_stream_id`** 等），并配合 **IPC4 头文件**、**DSpless** 等分支。 + +**结论**：**~千行量级** unified diff 表明 **整文件 backport 不可行**；排查 HDMI 应 **针对具体函数**（如 **`hda_link_dma_hw_params`**）与 **trace**，见 [STREAM_PCM_PARAMS_CHROME_UBUNTU_NOTES.md](../../patches/ubuntu-hwe-6.17/STREAM_PCM_PARAMS_CHROME_UBUNTU_NOTES.md) §3、§6。 + +--- + +## 6. 与专项文档的映射 + +| 主题 | 文档 | +|------|------| +| `STREAM_PCM_PARAMS` / `hda-pcm` format_val / 下一刀优先级 | [STREAM_PCM_PARAMS_CHROME_UBUNTU_NOTES.md](../../patches/ubuntu-hwe-6.17/STREAM_PCM_PARAMS_CHROME_UBUNTU_NOTES.md) | +| 补丁说明、0001/0002/0003、smoke 对象文件 | [DIFF_SUMMARY.txt](../../patches/ubuntu-hwe-6.17/DIFF_SUMMARY.txt)、[patches/ubuntu-hwe-6.17/README.md](../../patches/ubuntu-hwe-6.17/README.md) | +| 全 `sound/soc` 自动对照摘要 | [meta/CHROMEOS_vs_UBUNTU617_SOUND_AUTODIFF.md](../meta/CHROMEOS_vs_UBUNTU617_SOUND_AUTODIFF.md) | +| ChromeOS 5.15 单树路径笔记 | [CHROMEOS_KAISA_AUDIO_KERNEL_PATHS.md](CHROMEOS_KAISA_AUDIO_KERNEL_PATHS.md) | +| HWE 6.17 单树路径笔记 | [KERNEL_SRC_LINUX_HWE617_HDMI_3.5MM_PATHS.md](KERNEL_SRC_LINUX_HWE617_HDMI_3.5MM_PATHS.md) | +| 路线图与修复阶段 | [Linux_HDMI_Audio_Roadmap.md](Linux_HDMI_Audio_Roadmap.md) | +| **可执行修复计划**（阶段 A–D、决策分支） | [FIX_PLAN_HDMI_FROM_SOURCE_ANALYSIS.md](FIX_PLAN_HDMI_FROM_SOURCE_ANALYSIS.md) | + +--- + +## 7. 小结 + +| 层次 | Chrome 5.15 vs Ubuntu 6.17 | +|------|-----------------------------| +| **板级 HDMI/SSP** | **逻辑同构**（`iDispN`、`SSP-Codec`），差异主要是 **ASoC 标志名**、**quirk 宏归属**、**6.17 额外 HDA 外置 codec 链** | +| **IPC3 `STREAM_PCM_PARAMS`** | **载荷构造一致**；差异在 **日志与诊断**；行为修复见 **0001**（FREE/trigger），非 hw_params 盲改 | +| **HDA Link DMA** | **架构重写**；仅宜 **点状** 对照与实验，见 **STREAM_PCM_PARAMS** 笔记 §6 | + +以上与「**先用户态基线 → 0001 自编内核 → hda-dai/trace/上游**」的仓库路线图一致；逐步执行见 [FIX_PLAN_HDMI_FROM_SOURCE_ANALYSIS.md](FIX_PLAN_HDMI_FROM_SOURCE_ANALYSIS.md)。 diff --git a/docs/linux-hdmi/UPSTREAM_SOF_Kaisa_HDMI_REPRO.md b/docs/linux-hdmi/UPSTREAM_SOF_Kaisa_HDMI_REPRO.md index dc68d32950..a55a8d70be 100644 --- a/docs/linux-hdmi/UPSTREAM_SOF_Kaisa_HDMI_REPRO.md +++ b/docs/linux-hdmi/UPSTREAM_SOF_Kaisa_HDMI_REPRO.md @@ -1,5 +1,11 @@ # 上游复现包：Google Kaisa + Linux `STREAM_PCM_PARAMS -5`（HDMI） +**闸门（FR21）**：仅在 [路线图](Linux_HDMI_Audio_Roadmap.md) **§ 四、成功标准** 所定义的验证结论已具备（或本清单明确要求的诊断材料）后，再启动上游 issue/邮件。**本仓库无**「必须对外发 issue」的里程碑。材料准备与对外分享须遵守 **脱敏**（**[COLLECT.md](../../audio_topology/COLLECT.md)**、**NFR1**）；清单若要求特定全量输出，按清单执行。 + +**最小信息包（FR16）**：下列章节用于组织**最小必要**复现信息；**不**因阅读本清单而自动产生「必须联系上游」的协作义务。 + +--- + 在 **`patches/ubuntu-hwe-6.17/STREAM_PCM_PARAMS_CHROME_UBUNTU_NOTES.md`** 对照结论下，**行为性**修复仍 **无单一、已证实的内核 hunk** 可安全提交；仓库内 **`0002-*.patch` 仅为 `STREAM_PCM_PARAMS` 可观测性（诊断），不视为修复**。优先把下列材料交给 **thesofproject/sof** 或 **alsa-devel**。 ## 1. 硬件与引导 @@ -28,9 +34,10 @@ ## 5. 已尝试且不足以单独修复的方向（避免重复提问） -- 仅替换 intel-signed / community SOF 固件：**HDMI 仍失败**（见 `ANALYSIS_Audio.md`）。 -- 与 Chrome 拓扑 **等效**（解压规模一致）：见同一文档。 -- **`ipc3-pcm.c` 0001 类补丁**（FREE/trigger 回复路径）：**不改变** `STREAM_PCM_PARAMS` 发送逻辑（见 `patches/ubuntu-hwe-6.17/DIFF_SUMMARY.txt` 与 `STREAM_PCM_PARAMS_CHROME_UBUNTU_NOTES.md`）。 +与 **[Linux_HDMI_Audio_Roadmap.md](Linux_HDMI_Audio_Roadmap.md) §二**、**[REANALYSIS_Linux_HDMI_Audio_Kaisa.md](REANALYSIS_Linux_HDMI_Audio_Kaisa.md)** 一致处从略。摘要： + +- 仅换固件 / tplg 等：**不能单独恢复 HDMI**（见 `ANALYSIS_Audio.md`、路线图）。 +- **0001**（FREE/trigger）：**不改变** `STREAM_PCM_PARAMS` 载荷语义（见 `DIFF_SUMMARY.txt`、`STREAM_PCM_PARAMS_CHROME_UBUNTU_NOTES.md`）。 ## 6. 邮件/ Issue 正文模板（可复制） diff --git a/docs/meta/CHROMEOS_vs_UBUNTU617_SOUND_AUTODIFF.md b/docs/meta/CHROMEOS_vs_UBUNTU617_SOUND_AUTODIFF.md index ba9c832ce9..61b4396a95 100644 --- a/docs/meta/CHROMEOS_vs_UBUNTU617_SOUND_AUTODIFF.md +++ b/docs/meta/CHROMEOS_vs_UBUNTU617_SOUND_AUTODIFF.md @@ -1,30 +1,14 @@ # ChromiumOS 5.15 与 Ubuntu HWE 6.17：音频子树自动对照结果 -本文档由仓库内脚本/命令**自动生成摘要**（非手工逐行审查结论）。用于回答：**ChromeOS 树与 6.17 在 SOF/Intel 音频上差多大、该先看哪些文件**。 +由脚本/命令生成的**统计摘要**（非逐行审查）。**`unshallow`、导出 diff 的全流程**见 **[OPERATION_ChromeOS_Kernel_Deep_Diff.md](../kernel-build/OPERATION_ChromeOS_Kernel_Deep_Diff.md)**；本文 **§1** 仅一句判断，**§2 起**为目录级规模与优先读文件。 -**操作清单**（`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)。 - -**路径约定**（本仓库）： - -- ChromeOS：`chromiumos_kernel/v5.15/`（分支示例 `release-R144-16503.B-chromeos-5.15`） -- Ubuntu：`kernel-src/linux-hwe-6.17-6.17.0/` +**路径约定**：ChromeOS → `chromiumos_kernel/v5.15/`；Ubuntu → `kernel-src/linux-hwe-6.17-6.17.0/`。 --- -## 1. Git 历史：当前克隆多为「浅克隆」 +## 1. Git 历史（不重复操作篇） -若使用 `git clone --depth 1`，本地 **`git rev-list --count HEAD` 为 1**，则 **`git log -- sound/...` 几乎看不到 Chrome 的逐条提交**，无法按「补丁列表」浏览。 - -**要拉完整历史**（在 `chromiumos_kernel/v5.15` 内，耗时与磁盘较大）： - -```bash -git fetch --unshallow origin -# 或重新克隆时不加 --depth 1 -``` - -若提示 **`--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)）。 - -然后再执行： +若 **`git rev-list --count HEAD` 为 1**（浅克隆），须先按 **Deep Diff 文档 §2** 拉全历史，再： ```bash git log --oneline -50 -- sound/soc/sof sound/soc/intel include/sound diff --git a/docs/meta/DOCUMENTATION_ARCHITECTURE.md b/docs/meta/DOCUMENTATION_ARCHITECTURE.md new file mode 100644 index 0000000000..6acaad6d05 --- /dev/null +++ b/docs/meta/DOCUMENTATION_ARCHITECTURE.md @@ -0,0 +1,69 @@ +# 文档架构与进度备忘 + +**分工**：[DOCUMENTATION_STYLE.md](./DOCUMENTATION_STYLE.md) 管**怎么写**；本文管**入口与进度文件往哪放**。不替代 [INDEX.md](../INDEX.md) 全表。 + +--- + +## 1. 人读入口 + +根目录 **唯一** [README.md](../../README.md) → [INDEX.md](../INDEX.md)（主题）/ [REPO_INDEX.md](../../REPO_INDEX.md)（路径）/ [WORK_PROGRESS.md](WORK_PROGRESS.md)（阶段与 clone）。 + +```mermaid +flowchart LR + R["README"] + R --> A["INDEX"] + R --> B["REPO_INDEX"] + R --> C["WORK_PROGRESS"] + A --> H["linux-hdmi/"] + B --> S["scripts/\npatches/"] +``` + +| 入口 | 用途 | +|------|------| +| README | 概况、任务、速链 | +| INDEX | 按主题找文 | +| REPO_INDEX | 路径与文件名 | +| WORK_PROGRESS | 阶段、结论、clone | + +--- + +## 2. AI / BMad + +| 文件 | 作用 | +|------|------| +| [index.md](../index.md) | AI 主索引（勿与 INDEX 合并） | +| [_bmad-output/project-context.md](../../_bmad-output/project-context.md) | GPC 规则 | +| _bmad-output/* 草稿 | 结论应收敛到 docs/ 或 WORK_PROGRESS | + +--- + +## 3. `docs/` 分区（概览） + +linux-hdmi（路线图 / FIX_PLAN）· kernel-build · meta · windows；根级占位链到 meta/ 与 BMad。跨平台纲：[REPAIR_Plan_Audio.md](../../audio_topology/REPAIR_Plan_Audio.md)。 + +--- + +## 4. 进度类文件 + +| 文件 | 内容 | +|------|------| +| WORK_PROGRESS | 事实、阶段、版本、clone | +| [next.md](../../next.md) | 临时下一步；**有重启须写重启后** | +| Roadmap | 目标、排除项、成功标准 | +| FIX_PLAN | 源码对比分支 A–D | + +**路线图与 `WORK_PROGRESS` 交叉更新（FR17）**：阶段跳转或重要结论变更时，更新 [路线图](../linux-hdmi/Linux_HDMI_Audio_Roadmap.md) **§ 五、维护与「当前阶段」** 与 [WORK_PROGRESS](WORK_PROGRESS.md) 顶部「Linux HDMI」段落之一，须**核对另一处**链接与事实，避免与 FR2 分工冲突。 + +--- + +## 5. 改文自检（1 分钟） + +1. 新文已在 **INDEX**（必要时 **REPO_INDEX**）加一行。 +2. Linux HDMI 阶段结论已写 **WORK_PROGRESS** 首段。 +3. 短期步骤（含重启）已更新 **next.md**。 + +--- + +## 6. 边界 + +勿仅为「好看」批量改 `linux-hdmi/` 文件名。真要搬迁：**grep 旧路径 → 改 INDEX / REPO_INDEX / WORK_PROGRESS → 再移动**。 diff --git a/docs/meta/DOCUMENTATION_STYLE.md b/docs/meta/DOCUMENTATION_STYLE.md new file mode 100644 index 0000000000..f7d29e0d78 --- /dev/null +++ b/docs/meta/DOCUMENTATION_STYLE.md @@ -0,0 +1,78 @@ +# 文档体例与改写约定（全项目） + +**范围**：本仓库**自有**说明文字——**`README.md`**、**`docs/`**、**`audio_topology/`**、**`patches/**/README*.md`**、根目录 **`next.md`**、**`REPO_INDEX.md`**、**`help.md`** 等。 +**不包含**：**`_bmad/`**（BMad 安装树）、**`.cursor/`** 技能包、**`kernel-src/`**/**`chromiumos_kernel/`** 内上游源码（除非本仓库另有 `README` 说明）。 + +**目的**：统一口吻、入口与术语，便于本人、代理与换机交接阅读；与 **[DOCUMENTATION_ARCHITECTURE.md](./DOCUMENTATION_ARCHITECTURE.md)**（结构）互补——**本文管「怎么写」**，架构文管「往哪放」。 + +--- + +## 1. 语言与语气 + +| 项 | 约定 | +|----|------| +| **默认** | **简体中文**（与 `_bmad/bmm/config.yaml` 中 `document_output_language` 一致）。 | +| **技术专名** | 保留英文：`SOF`、`iDisp`、`PIPEWIRE`、`plughw`、`STREAM_PCM_PARAMS`、`dynamic_debug`、内核符号与路径。 | +| **句式** | 说明体：先**可执行结论**或**指向**，再背景；避免口号式空话。 | +| **版本与事实** | 写内核版本、`uname`、deb 后缀时**写全**或指到 `WORK_PROGRESS`/操作记录，避免半句过时数字。 | + +--- + +## 2. 入口与互链（硬约定） + +| 规则 | 说明 | +|------|------| +| **唯一根 README** | 仅 **[README.md](../../README.md)**；不在子目录另立「第二 README」抢入口。 | +| **主题索引** | 新增/改名主题文档后，在 **[docs/INDEX.md](../INDEX.md)** 增加或更新**一行**链入；全路径速查维护 **[REPO_INDEX.md](../../REPO_INDEX.md)**。 | +| **占位文件** | `docs/WORK_PROGRESS.md`、`docs/Linux_HDMI_Audio_Roadmap.md` 仅作**重定向**，正文以 **`meta/`**、**`linux-hdmi/`** 为准。 | +| **BMad** | **`docs/index.md`**（小写）与 **`INDEX.md`** 并存；代理规则 **`_bmad-output/project-context.md`**；勿合并二者。 | +| **NFR4 同事务** | 新增或移动主题文档、或改变 **`docs/` 导航结构**时，在**同一变更集**（或**紧随**的提交）中更新 **`docs/INDEX.md`** 与/或 **`REPO_INDEX.md`**；见 §6。 | + +--- + +## 3. 文件命名（建议） + +| 模式 | 用途 | +|------|------| +| **`OPERATION_*.md`** | 可重复执行的操作步骤（安装、trace、采集）。 | +| **`FIX_PLAN_*.md`** / **`REPAIR_Plan_*.md`** | 分阶段修复策略或跨平台总方案。 | +| **`*_Roadmap.md`** | 路线图、成功标准、已排除项。 | +| **`PHASE_*` / `ANALYSIS_*`** | 阶段结论或对比分析。 | + +--- + +## 4. 术语简表（Kaisa / 音频） + +| 用语 | 含义 | +|------|------| +| **Kaisa** | Google Chromebox 10 代参考板名称。 | +| **Coreboot** | 替代原厂固件后的引导环境（本仓库问题前提之一）。 | +| **HWE 6.17** | Ubuntu 24.04 的 **linux-hwe-6.17** 内核线（文档与补丁默认对齐对象）。 | +| **ChromeOS 5.15 / ChromiumOS 5.15** | 对照用内核分支语境；**不等于** Ubuntu Mainline 5.15 包。 | + +--- + +## 5. 进度类文档分工（勿混写） + +| 文件 | 只写 | +|------|------| +| **`docs/meta/WORK_PROGRESS.md`** | 已验证事实、阶段结论、clone/版本命令。 | +| **`next.md`（根）** | **临时**下一步；**含重启时**须分 **重启前 / 重启后**。 | +| **路线图 / FIX_PLAN** | 目标、分支、不宜投入项；不写日常命令流水账。 | + +--- + +## 6. 改写清单（全项目落地时自检） + +- [ ] 新文档已出现在 **INDEX**（及需要的 **REPO_INDEX**）中；合并请求或提交说明中**点明**索引行变更（便于评审 NFR4）。 +- [ ] **现象与「已排除项」扩表**：优先只维护 **[linux-hdmi/Linux_HDMI_Audio_Roadmap.md](../linux-hdmi/Linux_HDMI_Audio_Roadmap.md) §一、§二**；其它文用**互链**代替复制表格。 +- [ ] 无与 **路线图 / WORK_PROGRESS** 矛盾的「唯一真相」表述。 +- [ ] 链接为**相对路径**（仓库内），避免仅域名依赖。 +- [ ] 大目录（`kernel-src` 等）仍遵守 **`.gitignore`**，文档只描述路径不承诺提交内容。 + +--- + +## 7. 与 Index Docs 的关系 + +- **`[ID]`** 产出的 **[LLM_INDEX.md](../LLM_INDEX.md)**：按文件**短描述**导航。 +- 体例变更时：先改**本文**，再视需要更新 **LLM_INDEX** 一行摘要。 diff --git a/docs/meta/OPERATION_DualBoot_Ubuntu24_Windows.md b/docs/meta/OPERATION_DualBoot_Ubuntu24_Windows.md index 196c36d930..1992aaa752 100644 --- a/docs/meta/OPERATION_DualBoot_Ubuntu24_Windows.md +++ b/docs/meta/OPERATION_DualBoot_Ubuntu24_Windows.md @@ -1,9 +1,10 @@ # Ubuntu 24.04 + Windows 双系统安装（Chromebox 10th / Kaisa / coreboot） -本文给出一条可复现的双系统路径：**先装 Windows，再装 Ubuntu 24.04**（推荐），并覆盖常见坑：UEFI 启动项、GRUB 修复、时钟、以及本项目关心的 **Windows 音频驱动（CoolStar/ALC5682/SOF）** 与 **Linux HWE 6.17 内核编译/安装** 的衔接。 +**体例**：[DOCUMENTATION_STYLE.md](DOCUMENTATION_STYLE.md)。**内核编译磁盘空间、源码 clone** 见 [WORK_PROGRESS.md](WORK_PROGRESS.md)；**自编内核安装**见 [../kernel-build/OPERATION_Install_CustomKernel_Ubuntu_HWE617.md](../kernel-build/OPERATION_Install_CustomKernel_Ubuntu_HWE617.md)。本文只写 **分区与安装顺序**。 -> 适用范围：coreboot/UEFI 引导的 Chromebox（Kaisa 类），磁盘为 NVMe/SATA 均可。 -> 说明：不同机型 BIOS 菜单与快捷键略有差异，但总体流程一致。 +可复现路径：**先 Windows，再 Ubuntu 24.04**（推荐）；含 UEFI/GRUB/时钟及与 **CoolStar 音频**、**HWE 6.17** 工作的衔接说明。 + +> 适用范围：coreboot/UEFI 的 Chromebox（Kaisa 类）；机型菜单差异略过。 --- @@ -30,7 +31,7 @@ - （可选）`/home`（ext4）按需 - （可选）swap：8–32GB（看内存与休眠需求） -> 若你计划在 Ubuntu 上编译 `linux-hwe-6.17` deb：建议 Ubuntu 分区额外留出 **≥35–50GB 空闲**（见本仓库 `docs/meta/WORK_PROGRESS.md` 的经验）。 +> 编译 `linux-hwe-6.17` deb 所需分区空闲：见 **WORK_PROGRESS.md**（与上文「衔接」一致）。 --- diff --git a/docs/meta/PREFLIGHT_NOTES.md b/docs/meta/PREFLIGHT_NOTES.md new file mode 100644 index 0000000000..4b4f83a9cd --- /dev/null +++ b/docs/meta/PREFLIGHT_NOTES.md @@ -0,0 +1,20 @@ +# 双树预检：失败含义与补树入口 + +**体例**：[DOCUMENTATION_STYLE.md](DOCUMENTATION_STYLE.md)。对应脚本：**[`scripts/preflight-chromeos-ubuntu-diff.sh`](../../scripts/preflight-chromeos-ubuntu-diff.sh)**（环境变量 **`CH`**、**`UB`** 可覆盖默认路径）。 + +## 默认路径 + +| 变量 | 默认 | 检查 | +|------|------|------| +| `CH` | `$REPO_ROOT/chromiumos_kernel/v5.15` | 需存在 **`$CH/sound/soc`** | +| `UB` | `$REPO_ROOT/kernel-src/linux-hwe-6.17-6.17.0` | 需存在 **`$UB/sound/soc`** | + +## 预检失败时如何补 + +| 脚本输出（摘要） | 含义 | 下一步 | +|------------------|------|--------| +| `缺少 ChromiumOS 树: .../chromiumos_kernel/v5.15/sound/soc` | 未克隆或未 sparse 出 `sound/soc` | [WORK_PROGRESS.md](WORK_PROGRESS.md) **§ 二**（克隆示例） | +| `缺少 Ubuntu 源码树: .../kernel-src/.../sound/soc` | 未 `apt source` 或路径不对 | [kernel-src/README.md](../../kernel-src/README.md) | +| 两者皆缺 | 双树均未就绪 | 按上表分两行各补 | + +预检通过后，脚本会调用 **`diff-chromeos-ubuntu-sound.sh`** 与 **`export-chromeos-ubuntu-sound-file-diffs.sh`**；产出与 `WORK_PROGRESS` **§ 六** 说明一致。 diff --git a/docs/meta/WORK_PROGRESS.md b/docs/meta/WORK_PROGRESS.md index fa76994bc7..7e6371cb4f 100644 --- a/docs/meta/WORK_PROGRESS.md +++ b/docs/meta/WORK_PROGRESS.md @@ -1,6 +1,10 @@ # 工作进度与源码获取说明（换机交接） -面向机型：**Google Kaisa（Chromebox 10 代）**；核心问题：**Linux HDMI 无声（`STREAM_PCM_PARAMS` IPC 约 -5）**、**Windows 3.5mm 无声**；对照：**ChromeOS 上 HDMI / 3.5mm 正常**。 +**体例**：[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/磁盘**、**阻塞**。不要在本文件写「替代路线图」的阶段定义；阶段含义以路线图为准，本文只记**当下状态**。 --- @@ -8,12 +12,33 @@ | 资源 | 路径 | | ---- | ---- | +| **文档架构与进度分工**（入口分层、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)。 + --- ## 一、当前结论与状态 @@ -130,7 +155,7 @@ fakeroot debian/rules binary-generic ## 六、ChromeOS 对照计划执行状态（本仓库快照） -- **预检脚本**（两棵树齐全后自动跑 diff + export）：[`scripts/preflight-chromeos-ubuntu-diff.sh`](../../scripts/preflight-chromeos-ubuntu-diff.sh)。 +- **预检脚本**（两棵树齐全后自动跑 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。 diff --git a/docs/project-overview.md b/docs/project-overview.md new file mode 100644 index 0000000000..d67ca24b21 --- /dev/null +++ b/docs/project-overview.md @@ -0,0 +1,63 @@ +# chromebox_10th_audio_driver — 项目概览（BMad 文档扫描） + +**日期：** 2026-04-05 +**类型：** 近类 **infra**（脚本、补丁、自动化与文档为主；非典型 Terraform 独占仓库） +**架构：** 单体仓库（monolith），以 **文档索引 + Shell 脚本 + 内核补丁** 组织工作 + +**文档体例**：[meta/DOCUMENTATION_STYLE.md](meta/DOCUMENTATION_STYLE.md) + +--- + +## 摘要 + +本仓库面向 **Google Kaisa（Chromebox 10 代）** 在 **Coreboot** 环境下的 **跨平台音频问题**（Linux HDMI、Windows 3.5mm 等），集中存放： + +- **操作文档与路线图**（`docs/`，含 Linux HDMI 主路线图）； +- **Ubuntu HWE 6.17 内核补丁**（`patches/ubuntu-hwe-6.17/`，0001–0003）与验证说明； +- **自动化脚本**（`scripts/`，构建、diff、采集）； +- **可选对照源码树路径**（`chromiumos_kernel/`、`kernel-src/`，大文件常不提交）。 + +**不是**以单一 `package.json` / Web 应用为核心的「典型 web 项目」；AI 代理实现变更时应以 **最小 diff、对齐现有文档结构** 为准。 + +--- + +## 分类 + +| 项 | 内容 | +|----|------| +| **仓库类型** | 单体（monolith） | +| **主要语言** | Bash、Markdown；内核相关为 C（补丁上下文） | +| **架构模式** | 文档驱动 + 可重复实验脚本（内核构建、补丁应用、采集） | + +--- + +## 技术栈摘要 + +| 类别 | 技术/工件 | +|------|-----------| +| 自动化 | Bash、`ubuntu-hwe-617-build.sh` | +| 内核 | Ubuntu `linux-hwe-6.17` 源码（`apt source`）、可选 `chromiumos_kernel/v5.15` | +| 文档 | CommonMark Markdown，`docs/INDEX.md` 为主题索引 | +| 版本控制 | Git | + +--- + +## 关键能力（功能视角） + +- Linux：**SOF / iDisp / HDMI** 排查路径、自编内核、**0001/0002/0003** 验证脚本。 +- 采集：`audio_topology/collected/`、拓扑与 dmesg 基线。 +- 对照：ChromeOS 5.15 与 Ubuntu 6.17 **sound/soc** diff 脚本与 reference。 + +--- + +## 架构要点 + +- **文档入口**：根目录仅 **[README.md](../README.md)**；详细索引为 **[INDEX.md](INDEX.md)** 与 **[REPO_INDEX.md](../REPO_INDEX.md)**。 +- **补丁与验证**：**[patches/ubuntu-hwe-6.17/VERIFY_PATCHES.md](../patches/ubuntu-hwe-6.17/VERIFY_PATCHES.md)**。 +- **BMad 主索引（本工作流）**：[index.md](index.md)（与 `INDEX.md` 并存：`INDEX.md` 为人用总目，`index.md` 面向 AI 检索约定）。 + +--- + +## 后续（棕地 PRD / 功能规划） + +文档改写约定：[meta/DOCUMENTATION_STYLE.md](meta/DOCUMENTATION_STYLE.md)。规划新功能时请将 **`docs/index.md`** 与 **`docs/INDEX.md`** 一并纳入上下文；内核修改对齐 **`uname -r`** 与 **`patches/ubuntu-hwe-6.17/README.md`**。 diff --git a/docs/project-scan-report.json b/docs/project-scan-report.json new file mode 100644 index 0000000000..7150f8c048 --- /dev/null +++ b/docs/project-scan-report.json @@ -0,0 +1,80 @@ +{ + "workflow_version": "1.2.0", + "timestamps": { + "started": "2026-04-05T11:23:13+08:00", + "last_updated": "2026-04-05T11:23:13+08:00", + "completed": "2026-04-05T11:23:13+08:00" + }, + "mode": "initial_scan", + "scan_level": "quick", + "project_root": "/home/jack/文档/chromebox_10th_audio_driver", + "project_knowledge": "docs", + "completed_steps": [ + { + "step": "step_0.5", + "status": "completed", + "timestamp": "2026-04-05T11:23:13+08:00", + "summary": "已加载 documentation-requirements.csv（12 类）；采用 quick 扫描策略" + }, + { + "step": "step_1", + "status": "completed", + "timestamp": "2026-04-05T11:23:13+08:00", + "summary": "单体仓库；近类 infra（脚本/补丁/自动化）；无 package.json 主应用" + }, + { + "step": "step_2", + "status": "completed", + "timestamp": "2026-04-05T11:23:13+08:00", + "summary": "已清点 README、docs/INDEX.md、REPO_INDEX.md、audio_topology、kernel 相关文档" + }, + { + "step": "step_3", + "status": "completed", + "timestamp": "2026-04-05T11:23:13+08:00", + "summary": "技术栈：Bash、Markdown、内核补丁 diff、可选 Ubuntu HWE 6.17 源码树" + }, + { + "step": "step_4", + "status": "completed", + "timestamp": "2026-04-05T11:23:13+08:00", + "summary": "quick：未生成 api-contracts/data-models（本类型不要求）" + }, + { + "step": "step_5_to_12", + "status": "completed", + "timestamp": "2026-04-05T11:23:13+08:00", + "summary": "已写入 project-overview、source-tree-analysis、development-guide、index.md" + } + ], + "current_step": "completed", + "project_classification": { + "repository_type": "monolith", + "project_type_id": "infra", + "project_types": [ + { + "part_id": "root", + "project_type_id": "infra", + "display_name": "文档与内核补丁工具链（近类 infra）" + } + ], + "primary_languages": "Bash, Markdown" + }, + "findings": { + "technology_stack": "无 Node/Python 应用包管理作为核心；脚本 + 补丁 + 文档", + "outputs_generated": [ + "project-overview.md", + "source-tree-analysis.md", + "development-guide.md", + "index.md" + ] + }, + "outputs_generated": [ + "project-scan-report.json", + "project-overview.md", + "source-tree-analysis.md", + "development-guide.md", + "index.md" + ], + "resume_instructions": "工作流已完成" +} diff --git a/docs/source-tree-analysis.md b/docs/source-tree-analysis.md new file mode 100644 index 0000000000..411933974a --- /dev/null +++ b/docs/source-tree-analysis.md @@ -0,0 +1,46 @@ +# 源码树说明（Quick Scan） + +**体例**：[meta/DOCUMENTATION_STYLE.md](meta/DOCUMENTATION_STYLE.md)。**扫描级别：** quick（基于目录与关键文件，非全量读源） + +--- + +## 仓库根目录（节选） + +``` +chromebox_10th_audio_driver/ +├── README.md # 全仓库唯一根 README；文档入口表 +├── REPO_INDEX.md # 全路径索引（脚本、补丁、大目录） +├── help.md / bmad-help.zh-CN.md +├── next.md +├── docs/ # 主题文档（INDEX.md、linux-hdmi/、meta/、kernel-build/ 等） +├── scripts/ # 构建、diff、验证、采集脚本 +├── patches/ +│ └── ubuntu-hwe-6.17/ # 0001–0003 补丁、VERIFY_PATCHES.md、STREAM_PCM 笔记 +├── audio_topology/ # 拓扑采集脚本、collected/ 真机输出 +├── chromiumos_kernel/ # 可选：ChromiumOS 5.15 对照树 +├── kernel-src/ # 可选：Ubuntu HWE 6.17 解压源码（常 gitignore） +├── design-artifacts/ +├── _bmad/ # BMad 模块配置与工作流 +└── _bmad-output/ # BMad 输出目录 +``` + +--- + +## 关键目录用途 + +| 路径 | 用途 | +|------|------| +| **docs/** | 人读文档主区；**INDEX.md** 分类索引 | +| **scripts/** | `ubuntu-hwe-617-build.sh`、`verify-ubuntu-hwe617-patches-runtime.sh`、`diff-*` 等 | +| **patches/ubuntu-hwe-6.17/** | 内核补丁与对照笔记 | +| **audio_topology/** | 三平台音频采集与 **REPAIR_Plan_Audio.md** | +| **chromiumos_kernel/v5.15** | ChromeOS 内核对照（若已克隆） | +| **kernel-src/** | 本机 `apt source` 的 HWE 树（若存在） | + +--- + +## 入口点（开发/实验） + +- **应用补丁并编内核**：`scripts/ubuntu-hwe-617-build.sh` + 环境变量 `PATCH=`（见 **patches/ubuntu-hwe-6.17/README.md**）。 +- **补丁真机验证**：`scripts/verify-ubuntu-hwe617-patches-runtime.sh`（成功输出 `VERIFY_OK`）。 +- **文档导航**：从 **docs/INDEX.md** 或 **本工作流生成的 index.md** 进入子主题。 diff --git a/docs/windows/HARDWARE_ID_DRIVER_MAP_Windows.md b/docs/windows/HARDWARE_ID_DRIVER_MAP_Windows.md index 2993ab50b1..8f400fc0c6 100644 --- a/docs/windows/HARDWARE_ID_DRIVER_MAP_Windows.md +++ b/docs/windows/HARDWARE_ID_DRIVER_MAP_Windows.md @@ -1,6 +1,6 @@ # Windows：设备管理器 Hardware ID → 驱动包映射（Kaisa / Chromebox 10 代） -本文面向 **Coreboot + Windows** 下的音频排障：把「设备管理器里看到的 Hardware ID / 实例 ID」**对应到应装哪一类驱动包**，以及**不要用**哪类通用包。 +**体例**：[../meta/DOCUMENTATION_STYLE.md](../meta/DOCUMENTATION_STYLE.md)。**安装顺序与现象**见 [OPERATION_Windows_Audio.md](OPERATION_Windows_Audio.md)，本文只列 **ID → 包类型**。 > 采集样例（真实硬件）见 `collected/audio_topology_windows_DESKTOP-56TM6AL_20260213_205300.txt`。 > 安装顺序与故障现象仍见 [OPERATION_Windows_Audio.md](OPERATION_Windows_Audio.md)。 diff --git a/docs/windows/OPERATION_Windows_Audio.md b/docs/windows/OPERATION_Windows_Audio.md index fd6c96431f..7bde5d954f 100644 --- a/docs/windows/OPERATION_Windows_Audio.md +++ b/docs/windows/OPERATION_Windows_Audio.md @@ -1,6 +1,8 @@ # Windows 音频修复说明（Chromebox 10 代 / Kaisa） -针对 **Coreboot 刷机后**：HDMI（英特尔显示器音频）正常，**3.5mm / Realtek ALC5682 I2S 无声、无插拔提示** 的情况。与 Linux 问题相反，修法依赖 **CoolStar / Chrultrabook 驱动栈**，不是桌面机通用 Realtek 安装包。 +**体例**：[../meta/DOCUMENTATION_STYLE.md](../meta/DOCUMENTATION_STYLE.md)。**Linux / Windows 两行概况**见根 [README.md](../../README.md)；本文只写 **Windows 侧** CoolStar / ALC5682。 + +针对 **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`。 diff --git a/kernel-src/README.md b/kernel-src/README.md index d2b279bc0e..b6a41ebe7f 100644 --- a/kernel-src/README.md +++ b/kernel-src/README.md @@ -1,5 +1,7 @@ # Ubuntu HWE 6.17 内核源码（本机目录，不随仓库提交） +**体例**：[../docs/meta/DOCUMENTATION_STYLE.md](../docs/meta/DOCUMENTATION_STYLE.md)。**安装 deb**见 [../docs/kernel-build/OPERATION_Install_CustomKernel_Ubuntu_HWE617.md](../docs/kernel-build/OPERATION_Install_CustomKernel_Ubuntu_HWE617.md)。 + 若旧环境把解压树放在 `~/kernel-src/linux-hwe-6.17-6.17.0/`，可迁入本仓库： ```bash @@ -42,4 +44,8 @@ export SRC="$PWD/linux-hwe-6.17-6.17.0" 编译成功后，deb 通常在本目录（`kernel-src/`）。**在目标机上安装与重启**的完整说明见：[docs/kernel-build/OPERATION_Install_CustomKernel_Ubuntu_HWE617.md](../docs/kernel-build/OPERATION_Install_CustomKernel_Ubuntu_HWE617.md)（含 `linux-base` 依赖、`linux-image-unsigned` 与 Secure Boot、可选 headers/DKMS）。 +## 完整构建失败时（FR8；NFR6） + +记录并写入 **[WORK_PROGRESS](../docs/meta/WORK_PROGRESS.md)**（便于协作重试）：**并行相关**（如 `CONCURRENCY_LEVEL`、`DEB_BUILD_OPTIONS`、`make -j`）、**命令末尾错误摘要**、**若曾 `tee` 的日志路径**、**磁盘空间**（`df -h`）、**是否遇 `source tree is not clean`**（见上文 `mrproper` 注意）。耗时与占用仅作事实记录，不作为 SLA。 + 根目录 `.gitignore` 已忽略 `linux-hwe-6.17-*` 与 `*.orig.tar.*` 等，换机后请在本目录重新 `apt source`。 diff --git a/next.md b/next.md index 84f35ff448..357d856c09 100644 --- a/next.md +++ b/next.md @@ -1,24 +1,36 @@ -下一步（按顺序） +# next.md（临时） -1. 重启 → GRUB Advanced → 选 **非** `6.17.0-20` 的内核进入系统。 +> 只记**下一步**；有**重启**须写「重启后」。结论 → [WORK_PROGRESS](docs/meta/WORK_PROGRESS.md)；入口关系 → [DOCUMENTATION_ARCHITECTURE](docs/meta/DOCUMENTATION_ARCHITECTURE.md)。 + +--- + +## 当前批次（可整段替换） + +### 重启前 + +1. GRUB Advanced → 选 **非** `6.17.0-20` 内核进入。 2. `sudo apt remove linux-image-6.17.0-20-generic`（按提示处理 modules）。 -3. `cd ~/文档/chromebox_10th_audio_driver/kernel-src`，按仓库文档 `**OPERATION_Install_CustomKernel_Ubuntu_HWE617.md` §2.1** 安装 **仅 6.17.0-20** 的 deb：`linux-image-unsigned` + `linux-modules` + `linux-modules-extra` + `linux-modules-iwlwifi`（版本后缀 `6.17.0-20.20~24.04.1`）→ `sudo apt-get install -f` → `sudo update-grub`。 - - +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`。 +```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 +``` -linux-modules-6.17.0-20-generic_6.17.0-20.20~24.04.1_amd64.deb \ +4. **再重启**。 -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 +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)。 +--- +## 用完 -1. 重启进 `6.17.0-20-generic`，确认 `dpkg -l linux-image-unsigned-6.17.0-20-generic` 为 **ii**。 -2. `sudo ./scripts/collect-storyc-dmesg.sh auto PATCHED`（或 `clear` → 试 HDMI → `save PATCHED`）。 -3. **设备扫全**（0,2 / 0,3 / 0,4）已完成，见 `**stories-hdmi-kaisa-bp-2026-04-04.md`**。若要看 **IPC/`STREAM_PCM_PARAMS`**，请用 `**OPERATION_Kaisa_SOF_HDMI_Trace.md**`（`**sof_debug=0x800**` + `dynamic_debug`）。 - +摘要进 **WORK_PROGRESS** 后，可**清空或覆盖**本文件。 diff --git a/patches/ubuntu-hwe-6.17/README.md b/patches/ubuntu-hwe-6.17/README.md index 411e919e80..acd7ff7fa2 100644 --- a/patches/ubuntu-hwe-6.17/README.md +++ b/patches/ubuntu-hwe-6.17/README.md @@ -1,5 +1,7 @@ # Ubuntu HWE 6.17：内核补丁目录 +仓库级文档体例：[../../docs/meta/DOCUMENTATION_STYLE.md](../../docs/meta/DOCUMENTATION_STYLE.md)。**真机验证步骤**：[VERIFY_PATCHES.md](VERIFY_PATCHES.md)。 + **当前状态** - **`0001-ASoC-SOF-ipc3-pcm-await-DSP-reply-for-FREE-and-trigger.patch`**：对齐 ChromiumOS 5.15，对 `STREAM_PCM_FREE` 与 trigger 使用 `sof_ipc_tx_message()` + `struct sof_ipc_reply`，替代 `sof_ipc_tx_message_no_reply()`。 @@ -24,6 +26,25 @@ 4. 编译见 [`kernel-src/README.md`](../../kernel-src/README.md) 与 [`scripts/ubuntu-hwe-617-build.sh`](../../scripts/ubuntu-hwe-617-build.sh)。 +## 预检（`patch --dry-run`） + +在**与运行内核版本一致**的 `kernel-src/linux-hwe-6.17-*/` 根目录下，对**单个**补丁文件： + +```bash +cd /path/to/kernel-src/linux-hwe-6.17-6.17.0 +patch -p1 --dry-run < /path/to/repo/patches/ubuntu-hwe-6.17/0001-....patch +``` + +输出应可判读 **成功**、**已应用（reversed / already applied）** 或 **失败原因**（上下文不匹配等）。**顺序**：先 **0001** 再 **0002**；**0003** 独立，可单独 dry-run。 + +## 禁止在未解决失败时 `patch --force` + +若 **`patch -p1 --dry-run` 失败**，**不得**使用 **`patch --force`** 强行贴补丁。应核对：**源码树版本**是否与 `uname -r` / `apt source` 一致，或改为**手工合并** hunk；将失败摘要与下一步记入 [`docs/meta/WORK_PROGRESS.md`](../../docs/meta/WORK_PROGRESS.md)。 + +## `reference/`（无完整树时的文本协作） + +目录 **[`reference/`](reference/)** 含关键文件的 **unified diff 摘录**（与 [`DIFF_SUMMARY.txt`](DIFF_SUMMARY.txt)、仓库补丁一致），便于在**未检出完整 `kernel-src`** 时做 PR/审查式讨论；完整双树流程见 [`docs/kernel-build/OPERATION_ChromeOS_Kernel_Deep_Diff.md`](../../docs/kernel-build/OPERATION_ChromeOS_Kernel_Deep_Diff.md)。 + ## 启用 0002 的可读日志 - **`snd-sof`** 模块参数 **`sof_debug`**：`SOF_DBG_DUMP_IPC_MESSAGE_PAYLOAD` 为 **bit 11**，单独开启时十进制为 **`2048`**（与其它标志按位或即可组合）。 @@ -36,3 +57,5 @@ 或使用 `debugfs` 中 `dynamic_debug` 的等价写法；再配合 `dmesg -w` 观察。 设计补丁前请先完成 ChromeOS 5.15 与 6.17 的对照流程，见 [`docs/kernel-build/OPERATION_ChromeOS_Kernel_Deep_Diff.md`](../../docs/kernel-build/OPERATION_ChromeOS_Kernel_Deep_Diff.md) 与 [`DIFF_SUMMARY.txt`](DIFF_SUMMARY.txt)。**`STREAM_PCM_PARAMS` / HDMI** 专项结论见 [`STREAM_PCM_PARAMS_CHROME_UBUNTU_NOTES.md`](STREAM_PCM_PARAMS_CHROME_UBUNTU_NOTES.md)。 + +**验证说明与一键脚本**：见 **[VERIFY_PATCHES.md](VERIFY_PATCHES.md)**；真机执行：`../../scripts/verify-ubuntu-hwe617-patches-runtime.sh`（`RUN_HDMI_TEST=0` 可跳过 `speaker-test`）。 diff --git a/patches/ubuntu-hwe-6.17/STREAM_PCM_PARAMS_CHROME_UBUNTU_NOTES.md b/patches/ubuntu-hwe-6.17/STREAM_PCM_PARAMS_CHROME_UBUNTU_NOTES.md index 4f377badcb..448f8e06cd 100644 --- a/patches/ubuntu-hwe-6.17/STREAM_PCM_PARAMS_CHROME_UBUNTU_NOTES.md +++ b/patches/ubuntu-hwe-6.17/STREAM_PCM_PARAMS_CHROME_UBUNTU_NOTES.md @@ -1,11 +1,8 @@ # ChromeOS 5.15 vs Ubuntu HWE 6.17：`STREAM_PCM_PARAMS` 相关路径对照 -对照树： +**体例**：[../../docs/meta/DOCUMENTATION_STYLE.md](../../docs/meta/DOCUMENTATION_STYLE.md)。**板级/多文件汇总**：[../../docs/linux-hdmi/SOURCE_DIFF_CHROMEOS515_UBUNTU617.md](../../docs/linux-hdmi/SOURCE_DIFF_CHROMEOS515_UBUNTU617.md)。 -- `chromiumos_kernel/v5.15/` -- `kernel-src/linux-hwe-6.17-6.17.0/` - -工具：`diff -u` 三文件体量约为 `ipc3-pcm.c` ~150 行、`hda-pcm.c` ~200 行、`hda-dai.c` **~1300+ 行**（架构差异大，不宜整文件移植）。 +对照树：`chromiumos_kernel/v5.15/`、`kernel-src/linux-hwe-6.17-6.17.0/`。以下三文件 `diff -u` 体量：`ipc3-pcm` ~150 行、`hda-pcm` ~200 行、`hda-dai` **~1300+**（不宜整文件移植）。 ## 1. `sound/soc/sof/ipc3-pcm.c` — `sof_ipc3_pcm_hw_params` diff --git a/patches/ubuntu-hwe-6.17/VERIFY_PATCHES.md b/patches/ubuntu-hwe-6.17/VERIFY_PATCHES.md new file mode 100644 index 0000000000..b3a4e2e8ea --- /dev/null +++ b/patches/ubuntu-hwe-6.17/VERIFY_PATCHES.md @@ -0,0 +1,70 @@ +# Ubuntu HWE 6.17：0001 / 0002 / 0003 补丁验证说明 + +**补丁含义与 `PATCH=` 应用顺序**：[README.md](README.md)。本文与 **[`scripts/verify-ubuntu-hwe617-patches-runtime.sh`](../../scripts/verify-ubuntu-hwe617-patches-runtime.sh)** 对应：**0001** 验**源码树**，**0002/0003** 验**运行内核 + dynamic_debug**（可选 `speaker-test`）。 + +**本机验证为权威（FR9）**：仓库若存在 CI 或仅做脚本语法检查，**不**替代在 **Ubuntu 24.04** 与文档钉扎的 **`linux-hwe-6.17` 线**上、**前置条件满足**时的本机执行；与 [**architecture.md**](../../_bmad-output/planning-artifacts/architecture.md) 中「本机即目标机」一致。 + +**一键验证**（真机、需 `sudo` 部分）： + +```bash +cd /path/to/chromebox_10th_audio_driver +./scripts/verify-ubuntu-hwe617-patches-runtime.sh +``` + +环境变量见下文「脚本行为」。 + +--- + +## 0001：FREE / trigger 等待 DSP 回复 + +| 项目 | 说明 | +|------|------| +| **补丁做什么** | `ipc3-pcm.c` 中 **`sof_ipc3_pcm_stream_pcm_free`**、**`sof_ipc3_pcm_trigger`** 里 **`sof_ipc_tx_message_no_reply` → `sof_ipc_tx_message(..., &reply, sizeof(reply))`**。 | +| **为何没有专用 dmesg** | 不增加新的固定打印；**不能**像 0002/0003 那样单靠一条 `dmesg` 判定。 | +| **如何验证** | 在**用于编内核的源码树**上：`patch -p1 --dry-run` 通过或 **already applied**；或人工确认上述两处为 **`sof_ipc_tx_message` + `reply`**。 | +| **脚本** | 调用 **[`scripts/verify-ubuntu-hwe617-0001-patch.sh`](../../scripts/verify-ubuntu-hwe617-0001-patch.sh)**（`SRC` 默认 `kernel-src/linux-hwe-6.17-6.17.0/`）。 | +| **运行中内核** | 若自编镜像来自该树，即视为已包含 0001；可用 **`dpkg -l \| grep linux-image-unsigned`** 与 **`uname -r`** 对照安装文档。 | + +--- + +## 0002：`STREAM_PCM_PARAMS` 字段 `spcm_dbg`（诊断） + +| 项目 | 说明 | +|------|------| +| **前提** | **`sof_debug` 含 `SOF_DBG_DUMP_IPC_MESSAGE_PAYLOAD`**（bit 11 = **2048** 或 **`0x800`**）。模块参数 **0444**，须在 **`/etc/modprobe.d`** 设 `options snd_sof sof_debug=0x800` 后**重启**（或等价加载方式）。 | +| **dynamic_debug** | **`file sound/soc/sof/ipc3-pcm.c +p`**（路径以 **`/sys/kernel/debug/dynamic_debug/control`** 中实际行为准）。 | +| **播放验证** | 对 HDMI 设备执行 **`speaker-test`** 触发 **`hw_params`** 后，`dmesg` 应出现 **两行** 以 **`STREAM_PCM_PARAMS:`** 开头（含 **`comp_id`**、**`buf pages`** 等）。 | +| **参考** | [OPERATION_Kaisa_SOF_HDMI_Trace.md](../../docs/linux-hdmi/OPERATION_Kaisa_SOF_HDMI_Trace.md)、[STREAM_PCM_PARAMS_CHROME_UBUNTU_NOTES.md](STREAM_PCM_PARAMS_CHROME_UBUNTU_NOTES.md)。 | + +--- + +## 0003：`hda_link_dma_hw_params` 内 `dev_dbg`（诊断） + +| 项目 | 说明 | +|------|------| +| **说明** | Ubuntu HWE 6.17 **上游** `hda-dai.c` 在对应位置**已有**同类 **`dev_dbg`**；0003 主要为**花括号/结构**对齐补丁目录；**观测方式相同**。 | +| **dynamic_debug** | **`file sound/soc/sof/intel/hda-dai.c +p`**。 | +| **播放验证** | HDMI 播放后 `dmesg` 含 **`hda_link_dma_hw_params: link`** 与 **`stream_tag`**。 | +| **参考** | [STREAM_PCM_PARAMS_CHROME_UBUNTU_NOTES.md](STREAM_PCM_PARAMS_CHROME_UBUNTU_NOTES.md) §6.1、[DIFF_SUMMARY.txt](DIFF_SUMMARY.txt)。 | + +--- + +## 脚本行为（`verify-ubuntu-hwe617-patches-runtime.sh`） + +| 变量 | 默认 | 含义 | +|------|------|------| +| `SRC` | `kernel-src/linux-hwe-6.17-6.17.0`（相对仓库根） | 0001 **dry-run** 所用源码树 | +| `RUN_HDMI_TEST` | `1` | `1`：执行 **`speaker-test`** + **dmesg** 检查 0002/0003 关键字；`0`：仅检查 **snd_sof**、**sof_debug**、**dynamic_debug** 开关 | +| `HDMI_PLUGHW` | `plughw:0,2` | 触发 **`hw_params`** 的 ALSA 设备（按 `aplay -l` 改） | + +成功时脚本以 **退出码 0** 结束，并打印 **`VERIFY_OK: all checks passed`**。 + +--- + +## 相关文件 + +| 文件 | 说明 | +|------|------| +| [README.md](README.md) | 补丁应用顺序与 `sof_debug` 备忘 | +| [DIFF_SUMMARY.txt](DIFF_SUMMARY.txt) | 0001/0002/0003 设计与 smoke 说明 | +| [`scripts/verify-ubuntu-hwe617-0001-patch.sh`](../../scripts/verify-ubuntu-hwe617-0001-patch.sh) | 仅 0001 **patch dry-run** | diff --git a/scripts/verify-ubuntu-hwe617-patches-runtime.sh b/scripts/verify-ubuntu-hwe617-patches-runtime.sh new file mode 100755 index 0000000000..27d01741f5 --- /dev/null +++ b/scripts/verify-ubuntu-hwe617-patches-runtime.sh @@ -0,0 +1,122 @@ +#!/usr/bin/env bash +# 在真机上验证 Ubuntu HWE 6.17 仓库补丁 0001（源码 dry-run）+ 0002/0003（运行时 + 可选 HDMI 播放）。 +# 成功：退出 0，并打印 VERIFY_OK。 +# +# 用法： +# ./scripts/verify-ubuntu-hwe617-patches-runtime.sh +# RUN_HDMI_TEST=0 ./scripts/verify-ubuntu-hwe617-patches-runtime.sh # 不跑 speaker-test +# HDMI_PLUGHW=plughw:0,3 ./scripts/verify-ubuntu-hwe617-patches-runtime.sh +# +# 依赖：bash、grep、timeout；RUN_HDMI_TEST=1 时需 speaker-test、sudo、dmesg、debugfs。 +set -euo pipefail + +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +REPO_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)" +SRC="${SRC:-$REPO_ROOT/kernel-src/linux-hwe-6.17-6.17.0}" +RUN_HDMI_TEST="${RUN_HDMI_TEST:-1}" +HDMI_PLUGHW="${HDMI_PLUGHW:-plughw:0,2}" + +RED='\033[0;31m' +GRN='\033[0;32m' +RST='\033[0m' + +pass() { echo -e "${GRN}OK${RST}: $*"; } +fail() { echo -e "${RED}FAIL${RST}: $*" >&2; exit 1; } +info() { echo "==> $*"; } + +info "Repository root: $REPO_ROOT" +info "SRC (0001 dry-run): $SRC" + +# --- 0001: patch dry-run --- +info "Step 0001: ipc3-pcm FREE/trigger patch (dry-run)" +if [[ ! -f "$SRC/sound/soc/sof/ipc3-pcm.c" ]]; then + fail "Missing $SRC/sound/soc/sof/ipc3-pcm.c — set SRC= to your linux-hwe-6.17 tree or see kernel-src/README.md" +fi +if ! OUT="$("$REPO_ROOT/scripts/verify-ubuntu-hwe617-0001-patch.sh" 2>&1)"; then + echo "$OUT" + fail "0001 patch dry-run failed" +fi +echo "$OUT" +pass "0001 patch applies or is already present in ipc3-pcm.c" + +# --- Module snd_sof --- +if [[ ! -d /sys/module/snd_sof ]]; then + fail "snd_sof not loaded (is this a SOF machine? lsmod | grep snd_sof)" +fi +pass "module snd_sof is loaded" + +# --- 0002 prerequisite: sof_debug bit 11 --- +SD="/sys/module/snd_sof/parameters/sof_debug" +if [[ ! -r "$SD" ]]; then + fail "cannot read $SD" +fi +V="$(cat "$SD" | tr -d '\n')" +if [[ "$V" =~ ^0[xX] ]]; then + VN=$((16#${V#0x})) +else + VN=$((10#$V)) +fi +if (( (VN & 2048) != 2048 )); then + fail "sof_debug must include bit 11 (2048 / 0x800) for 0002; got $V. See patches/ubuntu-hwe-6.17/VERIFY_PATCHES.md" +fi +pass "sof_debug includes SOF_DBG_DUMP_IPC_MESSAGE_PAYLOAD (bit 11): $V" + +# --- debugfs --- +if [[ ! -f /sys/kernel/debug/dynamic_debug/control ]]; then + sudo mount -t debugfs none /sys/kernel/debug 2>/dev/null || true +fi +if [[ ! -f /sys/kernel/debug/dynamic_debug/control ]]; then + fail "dynamic_debug not available (mount debugfs; run script with sudo if permission denied below)" +fi + +DD_CTRL="/sys/kernel/debug/dynamic_debug/control" +enable_dd() { + local f="$1" + sudo sh -c "echo 'file ${f} +p' >> '$DD_CTRL'" || fail "dynamic_debug +p for $f" +} + +info "Step 0002: enable ipc3-pcm.c dynamic_debug" +enable_dd "sound/soc/sof/ipc3-pcm.c" +pass "dynamic_debug: sound/soc/sof/ipc3-pcm.c +p" + +info "Step 0003: enable hda-dai.c dynamic_debug" +enable_dd "sound/soc/sof/intel/hda-dai.c" +pass "dynamic_debug: sound/soc/sof/intel/hda-dai.c +p" + +if [[ "$RUN_HDMI_TEST" != "1" ]]; then + echo "" + pass "RUN_HDMI_TEST=0 — skipped speaker-test / dmesg content checks" + echo "" + echo -e "${GRN}VERIFY_OK: all checks passed${RST} (0001 source + prerequisites for 0002/0003)" + exit 0 +fi + +if ! command -v speaker-test >/dev/null 2>&1; then + fail "speaker-test not found; install alsa-utils or set RUN_HDMI_TEST=0" +fi + +info "Step 0002/0003 playback: speaker-test on $HDMI_PLUGHW (sudo dmesg -C first)" +sudo dmesg -C 2>/dev/null || true +if ! timeout 8 speaker-test -D "$HDMI_PLUGHW" -c2 -t sine -f 440 2>/dev/null; then + fail "speaker-test failed for $HDMI_PLUGHW — check aplay -l and HDMI_PLUGHW=" +fi + +sleep 0.3 +DM="$(sudo dmesg -T 2>/dev/null || sudo dmesg)" + +if ! echo "$DM" | grep -qF "STREAM_PCM_PARAMS: comp_id"; then + fail "0002: no 'STREAM_PCM_PARAMS: comp_id' in dmesg after playback (sof_debug + ipc3-pcm +p?)" +fi +if ! echo "$DM" | grep -qF "STREAM_PCM_PARAMS: buf pages"; then + fail "0002: no second STREAM_PCM_PARAMS line (buf pages) in dmesg" +fi +pass "0002: STREAM_PCM_PARAMS field lines present in dmesg" + +if ! echo "$DM" | grep -qF "hda_link_dma_hw_params"; then + fail "0003: no 'hda_link_dma_hw_params' in dmesg after playback (hda-dai +p?)" +fi +pass "0003: hda_link_dma_hw_params line present in dmesg" + +echo "" +echo -e "${GRN}VERIFY_OK: all checks passed${RST} (0001 source + 0002/0003 runtime + HDMI playback)" +exit 0