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

docs(kaisa): make UCM HiFi the only supported path

Browse Source 
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
This commit is contained in:
jack
2026-04-08 15:22:45 +08:00
parent 17f0a4521f
commit bda6b60c15
33 changed files with 384 additions and 1780 deletions
Download Patch File Download Diff File Expand all files Collapse all files

10
_bmad-output/planning-artifacts/epics.md
View File

@@ -80,21 +80,21 @@ workflowType: epics
**目标：** 满足 **SC1** 与 **FR1、FR2、FR9**；新贡献者 10 分钟内找到 Linux HDMI 主线。
### Story 1.1：INDEX 与 OPERATION/REPRO
### Story 1.1：INDEX 与 OPERATION
作为一名**维护者**，
我希望 **INDEX.md** 能链到 **OPERATION** 与 **REPRO**，
我希望 **INDEX.md** 能链到 **OPERATION**，
以便 **不必搜全库**（**FR1**）。
**验收标准：**
- **Given** 仓库根已克隆
- **When** 打开 `docs/INDEX.md`
- **Then** 存在指向 `OPERATION_PipeWire_Kaisa_ProAudio.md`、`OPERATION_PipeWire_Kaisa_UCM_HiFi.md` 与 `REPRO_Kaisa_Deb_ProAudio_Manual.md` 的条目
- **Then** 存在指向 `OPERATION_PipeWire_Kaisa_UCM_HiFi.md` 的条目
### Story 1.2：（已收敛）路线图
**状态：** **`Linux_HDMI_Audio_Roadmap.md`** 与 **WORK_PROGRESS** 类长文已删除；**FR2** 以 **OPERATION + REPRO** 为事实源。
**状态：** **`Linux_HDMI_Audio_Roadmap.md`** 与 **WORK_PROGRESS** 类长文已删除；**FR2** 以 **OPERATION** 为事实源。
### Story 1.3：README 与 PRD / BMad 链
@@ -125,7 +125,7 @@ workflowType: epics
### Story 3.1：OPERATION 覆盖 pro-audio / EBUSY / IEC958 / 全自动
作为一名 **Kaisa 用户**，
我希望 **OPERATION_PipeWire_Kaisa_ProAudio.md** 说明 **pro-audio**、**`speaker-test -D pulse`**、**IEC958',N** 与 **§4.3 安装器**，
我希望 **OPERATION_PipeWire_Kaisa_UCM_HiFi.md** 说明 **UCM2 / HiFi**、**`speaker-test -D pulse`**、**IEC958',N**、以及安装器脚本（disable + install），
以便 **排障不靠口口相传**（**FR5**）。
**验收标准：**

24
_bmad-output/planning-artifacts/prd.md
View File

@@ -4,9 +4,7 @@ stepsCompleted:
inputDocuments:
- README.md
- docs/INDEX.md
- docs/linux-hdmi/OPERATION_PipeWire_Kaisa_ProAudio.md
- docs/linux-hdmi/OPERATION_PipeWire_Kaisa_UCM_HiFi.md
- docs/linux-hdmi/REPRO_Kaisa_Deb_ProAudio_Manual.md
workflowType: prd
brownfield_synthesis: true
synthesis_note: 棕地仓库；经 [VP] 校验后 [EP] 修订（SC↔FR 映射、可脚本化验收附录）。
@@ -19,13 +17,13 @@ last_edited: '2026-04-06'
**日期：** 2026-04-06
**状态：** 基线重建；已按 **`prd-validation-report.md`** 做 [EP] 修订（P2/P4）
**2026-04 文档收敛**：仓库已删除 ChromiumOS 长文、路线图、WORK_PROGRESS 等；**事实与验收**以 **README.md**、**OPERATION_PipeWire_Kaisa_ProAudio.md**、**OPERATION_PipeWire_Kaisa_UCM_HiFi.md**、**REPRO_Kaisa_Deb_ProAudio_Manual.md** 为准。旧名 **OPERATION_PipeWire_Kaisa_HDMI.md** 仅为重定向 stub。
**2026-04 文档收敛**：仓库已删除 ChromiumOS 长文、路线图、WORK_PROGRESS 等；**事实与验收**以 **README.md** 与 **OPERATION_PipeWire_Kaisa_UCM_HiFi.md** 为准。
---
## 1. 摘要
本「产品」为 **Google Kaisa（Chromebox 10 代 / Coreboot）跨平台音频** 的 **文档、脚本与 deb** 单体仓库，**交付主线**是 **Linux 下 HDMI 可稳定出声**（PipeWire / pro-audio / IEC958）；**自编内核与 SOF 诊断补丁**已不在仓库内维护。保留 **ChromeOS 源码树对照** 与 **拓扑采集**。
本「产品」为 **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** 手顺）。
@@ -64,7 +62,7 @@ last_edited: '2026-04-06'
| 角色 | 目标 | 主要触点 |
|------|------|----------|
| **维护者 / Jack** | 可选内核对照、脚本 | `chromiumos_kernel/`、`scripts/`（HWE 源码树本机自行 `apt source`） |
| **另一台 Kaisa 用户** | 在 Ubuntu + PipeWire 上让 HDMI 有声 | `OPERATION_PipeWire_Kaisa_ProAudio.md`、`50-kaisa-sof-rt5682-hdmi.conf`、deb 内工具 |
| **另一台 Kaisa 用户** | 在 Ubuntu + PipeWire 上让 HDMI 有声 | `OPERATION_PipeWire_Kaisa_UCM_HiFi.md`、UCM2 overlay、WirePlumber `60-kaisa-ucm.lua` |
| **上游读者** | IPC/内核对照 | 本地两棵内核树 + 可选 `reference/chromeos-ubuntu-sound-diffs/`（本机 diff 输出） |
---
@@ -88,11 +86,11 @@ last_edited: '2026-04-06'
| ID | 能力 | 验收要点 |
|----|------|----------|
| **FR1** | **文档索引** | 人读 **INDEX.md** 可到达 **OPERATION**、**REPRO**。 |
| **FR2** | **Linux HDMI 技术路线** | **ProAudio / UCM 文档** 覆盖 pro-audio、UCM、deb；**REPRO** 为验收手顺。 |
| **FR5** | **桌面 HDMI 操作说明** | **ProAudio 文档** 覆盖 **pro-audio**、**plughw EBUSY**、**IEC958 §4.2**、**§4.3 登录自动 restore**。 |
| **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 片段示例** | **`50-kaisa-sof-rt5682-hdmi.conf`** 可复制到 **`~/.config/wireplumber/...`**。 |
| **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`**。 |
@@ -104,10 +102,8 @@ last_edited: '2026-04-06'
```bash
test -f docs/INDEX.md
test -f docs/linux-hdmi/OPERATION_PipeWire_Kaisa_ProAudio.md
test -f docs/linux-hdmi/OPERATION_PipeWire_Kaisa_UCM_HiFi.md
test -f docs/linux-hdmi/REPRO_Kaisa_Deb_ProAudio_Manual.md
grep -q 'OPERATION_PipeWire_Kaisa_ProAudio' docs/INDEX.md
grep -q 'OPERATION_PipeWire_Kaisa_UCM_HiFi' docs/INDEX.md
```
---
@@ -120,7 +116,7 @@ grep -q 'OPERATION_PipeWire_Kaisa_ProAudio' docs/INDEX.md
| **NFR2** | **可维护性** | 大目录（如 `chromiumos_kernel/`、本机 HWE 解压树）**不强制入库**；对照脚本用 **`UB=`** 指向本机路径。 |
| **NFR3** | **变更粒度** | 代码/脚本以 **最小 diff** 对齐现有风格；避免无关重构。 |
| **NFR4** | **安全与权限** | 用户态修复以 **`systemctl --user`** 为主；**避免**要求普通用户长期 **root** 改系统 ALSA 全局状态作为唯一路径。 |
| **NFR5** | **诚实边界** | **`pro-audio`** 下 GNOME 可能 **列出多路 Pro N**；文档说明与 **「仅插线才显示」** 的取舍。 |
| **NFR5** | **诚实边界** | 桌面输出列表的表现依赖版本与策略；以 **UCM Jack-driven** 作为主交付，解释其与「常驻多路输出」策略的取舍。 |
---
@@ -146,9 +142,7 @@ grep -q 'OPERATION_PipeWire_Kaisa_ProAudio' docs/INDEX.md
## 10. 参考（仓库内）
- [docs/INDEX.md](../../docs/INDEX.md)
- [docs/linux-hdmi/OPERATION_PipeWire_Kaisa_ProAudio.md](../../docs/linux-hdmi/OPERATION_PipeWire_Kaisa_ProAudio.md)
- [docs/linux-hdmi/OPERATION_PipeWire_Kaisa_UCM_HiFi.md](../../docs/linux-hdmi/OPERATION_PipeWire_Kaisa_UCM_HiFi.md)
- [docs/linux-hdmi/REPRO_Kaisa_Deb_ProAudio_Manual.md](../../docs/linux-hdmi/REPRO_Kaisa_Deb_ProAudio_Manual.md)
- [README.md](../../README.md)
---