jack/chromebox_10th_audio_driver
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
1f7495e31cfd406c787608e0c153d4e8821fe7f5
chromebox_10th_audio_driver/_bmad-output/planning-artifacts/prd.md
jack 4f9b23d144 bmad base
2026-04-05 13:24:31 +08:00

31 KiB
Raw Blame History

stepsCompleted, inputDocuments, documentCounts, workflowType, classification
stepsCompleted inputDocuments documentCounts workflowType classification
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
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/
briefCount researchCount brainstormingCount projectDocsCount
0 1 0 8
prd
projectType domain complexity projectContext
developer_tool general low brownfield

Product Requirements Document - chromebox_10th_audio_driver

Author: Jack
Date: 2026-04-05T11:54:55+08:00

文档结构（目录）

章节 内容摘要
Executive Summary 问题范围、差异点、不交付项
Project Classification developer_tool / brownfield 等
Success Criteria 用户/业务/技术成功、可量化结果
Product Scope MVP / Growth / Vision、上游后置
User Journeys 五类旅程与能力汇总
developer_tool Specific Requirements 语言、安装、接口、迁移
Project Scoping & Phased Development 与路线图阶段对齐、MVP 顺序
Functional Requirements 能力契约 FR1–FR21
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 与上游许可执行。
Reference in New Issue View Git Blame Copy Permalink