jack
bda6b60c15
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
156 lines
8.0 KiB
Markdown
156 lines
8.0 KiB
Markdown
---
|
||
stepsCompleted:
|
||
- prd-brownfield-synthesis-2026-04-06
|
||
inputDocuments:
|
||
- README.md
|
||
- docs/INDEX.md
|
||
- docs/linux-hdmi/OPERATION_PipeWire_Kaisa_UCM_HiFi.md
|
||
workflowType: prd
|
||
brownfield_synthesis: true
|
||
synthesis_note: 棕地仓库；经 [VP] 校验后 [EP] 修订（SC↔FR 映射、可脚本化验收附录）。
|
||
last_edited: '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（文档索引链）**
|
||
|
||
```bash
|
||
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. 参考（仓库内）
|
||
|
||
- [docs/INDEX.md](../../docs/INDEX.md)
|
||
- [docs/linux-hdmi/OPERATION_PipeWire_Kaisa_UCM_HiFi.md](../../docs/linux-hdmi/OPERATION_PipeWire_Kaisa_UCM_HiFi.md)
|
||
- [README.md](../../README.md)
|
||
|
||
---
|
||
|
||
## 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] 中处理。
|