jack/chromebox_10th_audio_driver
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
bda6b60c15356cb85a60494a37a14fc005fc6ba7
chromebox_10th_audio_driver/_bmad-output/planning-artifacts/prd.md
jack bda6b60c15 docs(kaisa): make UCM HiFi the only supported path 
Promote UCM2/HiFi (Jack-driven) as the primary delivery, add HISTORY.md,
remove ProAudio/REPRO docs and non-UCM scripts, and fix repo-wide references.

Made-with: Cursor
2026-04-08 15:22:45 +08:00

8.0 KiB
Raw Blame History

stepsCompleted, inputDocuments, workflowType, brownfield_synthesis, synthesis_note, last_edited
stepsCompleted inputDocuments workflowType brownfield_synthesis synthesis_note last_edited
prd-brownfield-synthesis-2026-04-06
README.md
docs/INDEX.md
docs/linux-hdmi/OPERATION_PipeWire_Kaisa_UCM_HiFi.md
prd true 棕地仓库；经 [VP] 校验后 [EP] 修订（SC↔FR 映射、可脚本化验收附录）。 2026-04-06

产品需求文档（PRD）— chromebox_10th_audio_driver

作者： Jack
日期： 2026-04-06
状态： 基线重建；已按 prd-validation-report.md 做 [EP] 修订（P2/P4）

2026-04 文档收敛：仓库已删除 ChromiumOS 长文、路线图、WORK_PROGRESS 等；事实与验收以 README.md 与 OPERATION_PipeWire_Kaisa_UCM_HiFi.md 为准。

1. 摘要

本「产品」为 Google Kaisa（Chromebox 10 代 / Coreboot）跨平台音频 的 文档、脚本与 deb 单体仓库，交付主线是 Linux 下 HDMI 可稳定出声（UCM2 + HiFi / IEC958）；自编内核与 SOF 诊断补丁已不在仓库内维护。保留 ChromeOS 源码树对照 与 拓扑采集。

已验证关键用户态根因（Kaisa）：IEC958',0（pcm=2）关闭时 PipeWire 可看似正常但 HDMI 无声；打开后即有声。登录自动恢复见 OPERATION §4.3（规划中；当前 pactl/amixer 手顺）。

2. 愿景与要解决的问题

维度 说明
问题 同机 ChromeOS / Windows HDMI 正常，Linux 常 HDMI 无声或难以选路；需分层区分 内核/SOF/IPC 与 PipeWire/ALSA 混音器。
愿景 维护者可 可重复 构建、验证、采集；最终用户（技术门槛较低时）可通过 安装脚本/未来打包 获得 开箱可用 的 HDMI 音频。
非目标 不承诺任意 x86 机型通用；Windows 3.5mm 等为参考文档，不作为 Linux HDMI 的阻塞依赖（与 README 范围一致）。

3. 成功标准（可验收）

  1. 文档：存在 入口链（根 README → INDEX → OPERATION/REPRO）；Linux HDMI 以用户态路线为主。
  2. （已移除）内核诊断补丁：不再作为仓库交付物；需要时自行在本地内核树实验。
  3. 桌面 HDMI（Kaisa）：文档描述 WirePlumber pro-audio、IEC958',N 根因及 OPERATION §4.3（自动化规划中）。
  4. 对照与采集：ChromeOS ↔ HWE 可在本机双树 diff；audio_topology/ 采集可复现材料。

3.1 成功标准与 FR 对应（追溯）

成功标准 主要支撑的 FR 说明
SC1 文档入口与分流 FR1、FR2、FR9 INDEX → OPERATION/REPRO；README 链至本 PRD。
SC2（历史）内核诊断 — 已收敛：仓库不再包含补丁与 verify 脚本。
SC3 桌面 HDMI 可恢复 FR5、FR6、FR7 OPERATION、WirePlumber 片段、user systemd 说明；与 NFR4 一致。
SC4 对照材料可及 FR8、FR2 两棵内核树 + 可选 reference/chromeos-ubuntu-sound-diffs/；audio_topology/ 采集。

4. 用户旅程（摘要）

角色 目标 主要触点
维护者 / Jack 可选内核对照、脚本 chromiumos_kernel/、scripts/（HWE 源码树本机自行 apt source）
另一台 Kaisa 用户 在 Ubuntu + PipeWire 上让 HDMI 有声 OPERATION_PipeWire_Kaisa_UCM_HiFi.md、UCM2 overlay、WirePlumber 60-kaisa-ucm.lua
上游读者 IPC/内核对照 本地两棵内核树 + 可选 reference/chromeos-ubuntu-sound-diffs/（本机 diff 输出）

5. 范围

5.1 范围内（In）

  • Linux：SOF / iDisp / HDMI 文档、自编 HWE 内核流程、诊断补丁、采集脚本。
  • 桌面：PipeWire / WirePlumber / IEC958 操作说明与 user systemd 自动恢复（见 OPERATION §4.3）。
  • INDEX、代理用 project-context（待 [GPC] 重建）。

5.2 范围外（Out）或低优先级

  • 通用 Linux 发行版 正式包维护（deb/PPA）列为 后续，见 sprint-change-proposal 类叙述；本 PRD 不要求立即上架商店。
  • 图形化「应用」（GUI）非当前必须；CLI/系统服务 可接受。

6. 功能需求（FR）— 能力契约

ID 能力 验收要点
FR1 文档索引 人读 INDEX.md 可到达 OPERATION。
FR2 Linux HDMI 技术路线 UCM 文档 覆盖 UCM2 + HiFi、IEC958、安装/验收/排障。
FR5 桌面 HDMI 操作说明 UCM 文档 覆盖 Jack-driven 端口、IEC958、以及排障注意事项（例如避免在 PipeWire 运行时直连 hw: 试声）。
FR6 登录自动修复（Kaisa） OPERATION §4.3：user systemd 示例 + 手顺；deb ≥0.3.0 不随包提供可执行工具。
FR7 WirePlumber 片段示例 60-kaisa-ucm.lua 通过 api.alsa.use-ucm 与 KAISA_WP_DEVICE_PROFILE 控制默认 profile。
FR8 对照与导出 ChromeOS ↔ Ubuntu：本机两树 diff；可选输出至 reference/chromeos-ubuntu-sound-diffs/（见该目录 README）。
FR9 BMad 规划链 本 PRD 与（可选）architecture / epics 可链接；README 指向 _bmad-output/planning-artifacts/prd.md。

附录 A：FR1 可脚本化验收（可选）

在仓库根执行；用于 CI 或本地 bash -c 快速检查关键文件是否存在。

FR1（文档索引链）

test -f docs/INDEX.md
test -f docs/linux-hdmi/OPERATION_PipeWire_Kaisa_UCM_HiFi.md
grep -q 'OPERATION_PipeWire_Kaisa_UCM_HiFi' docs/INDEX.md

7. 非功能需求（NFR）

ID 类别 要求
NFR1 文档语言 用户面向说明以 简体中文 为主（与 bmm/config 一致）。
NFR2 可维护性 大目录（如 chromiumos_kernel/、本机 HWE 解压树）不强制入库；对照脚本用 UB= 指向本机路径。
NFR3 变更粒度 代码/脚本以 最小 diff 对齐现有风格；避免无关重构。
NFR4 安全与权限 用户态修复以 systemctl --user 为主；避免要求普通用户长期 root 改系统 ALSA 全局状态作为唯一路径。
NFR5 诚实边界 桌面输出列表的表现依赖版本与策略；以 UCM Jack-driven 作为主交付，解释其与「常驻多路输出」策略的取舍。

8. 假设与依赖

  • 产品简报：无独立 Product Brief；棕地事实源以 README.md 与 docs/linux-hdmi/OPERATION_*.md 为准，与本 PRD 并行维护。
  • 硬件：Google Kaisa、Coreboot、sof-rt5682 类 PipeWire 会话。
  • OS：文档基准 Ubuntu 24.04 + linux-hwe-6.17（具体 uname -r 以本机为准）。
  • 外部：PipeWire/WirePlumber 大版本升级可能导致片段语法变化（需跟进上游 migration）。

9. 风险

风险 缓解
上游 UCM/默认 IEC958 未合并，用户仍依赖脚本 文档标明 Phase C；保留 install 路径。
PCI 路径变化 restore 脚本 cml_rt5682 自动检测；WirePlumber 片段需按机改 device.name。
README 与 OPERATION 编号/补丁集合 陈旧 定期 [DP] 扫描或与真机对表。

10. 参考（仓库内）

11. 后续 BMad 步骤（可选）

  • [CA] Create Architecture：若需刷新架构决策文档。
  • [CE] Create Epics and Stories：将 FR 拆为可跟踪 story。
  • [GPC] Generate Project Context：重建 _bmad-output/project-context.md。
  • [VP]：重大改版后再跑校验；当前 P1–P4 已在 [EP] 中处理。
Reference in New Issue View Git Blame Copy Permalink