5.7 KiB
5.7 KiB
project_name, user_name, date, sections_completed, document_note
| project_name | user_name | date | sections_completed | document_note | |||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
| chromebox_10th_audio_driver | Jack | 2026-04-05T11:26:09+08:00 |
|
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）。用于 HDMI / SOF / machine 层与 Ubuntu HWE 的对照基准。关键文件索引：docs/linux-hdmi/CHROMEOS_KAISA_AUDIO_KERNEL_PATHS.md。 |
kernel-src/ |
Ubuntu linux-hwe-* 源码树放置与构建说明（非 ChromiumOS 用户态；与上表配对做双树 diff）。入口：kernel-src/README.md；对称笔记：docs/linux-hdmi/KERNEL_SRC_LINUX_HWE617_HDMI_3.5MM_PATHS.md。 |
| 非核心 | 无 package.json 类主应用；不要默认引入 Node/Python 项目脚手架。 |
关键实现规则
文档
- 体例与全项目改写约定：docs/meta/DOCUMENTATION_STYLE.md（语言、命名、进度类分工）。
- 唯一根 README：仓库根目录仅 README.md；新增主题文档须在 docs/INDEX.md（及需要时 REPO_INDEX.md）增加链接，避免孤岛页。
- 路线图与进度：Linux HDMI 以 docs/linux-hdmi/Linux_HDMI_Audio_Roadmap.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。 - 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，避免重复已否决路径。
验证与「测试」
- 补丁验证流程以 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。
严禁遗漏（易错）
- 文档入口：改
docs/结构时同步 INDEX / REPO_INDEX，否则代理与用户都会迷路。 - 内核版本一致性：补丁说明、dmesg、
verify-*必须与当前运行的内核构建一致。 - 勿把本仓库当成前端项目：无 ESLint/React 约定；规则以 Bash、内核补丁、Markdown 为准。
- HDMI 仍无声时：以 FIX_PLAN_HDMI_FROM_SOURCE_ANALYSIS.md 与路线图阶段为准，避免在未读源码对照的情况下硬改路由。
维护
- 与 BMad 并列的索引：docs/index.md（小写，AI 检索）、docs/INDEX.md（人用总目）。
- 更新本文件时机：变更补丁策略、验证方式或文档入口约定时。