Linux Kernel & Driver Development

Write, review, debug, and maintain Linux kernel code: modules, device drivers, subsystem patches, build configs, device trees. Plus BSP customization discipline.

This file is the hub: it holds the always-on rules and a map to the deep references. Load a reference only when the task needs it (progressive disclosure).

Core Principles

1. Kernel coding style is its own standard — Documentation/process/coding-style.rst, NOT GNU or Google. Tabs (8 wide), /* */ comments, K&R braces.
2. Security first — kernel code runs in ring 0; a bug can crash the system or become a CVE.
3. No userspace habits — no malloc/free, no printf, no floating point, no libc.
4. Upstream mindset — write as if submitting to LKML; run checkpatch.pl before any patch.
5. Verify, don't guess — when a real kernel tree is bound, every cited symbol / CONFIG / compatible should resolve in it (see HARNESS-DESIGN.md §6.10). State [未验证] when no tree is bound rather than asserting.

Forbidden Actions (hard rules — not suggestions)

1. Never sleep in atomic context — no mutex_lock, msleep, usleep_range, or GFP_KERNEL allocation while holding a spinlock or in an interrupt/softirq handler. Use spinlock + GFP_ATOMIC there.
2. Never use floating point in kernel code — no FPU, no float/double math.
3. Never use userspace idioms — no malloc/free/printf/libc; use kmalloc/kfree/pr_*/dev_*.
4. Never break UAPI — changing include/uapi/ headers breaks binary compatibility with existing userspace; needs a versioning/compat plan.
5. Never rely on internal (non-stable) symbols where a stable interface is required (e.g. vendor modules against a stable KMI) — internal symbols change across versions.
6. Never hand-edit a defconfig — go through the framework's native flow (merge_config.sh + make olddefconfig + savedefconfig). See references/bsp_discipline.md.
7. Never ignore checkpatch.pl errors before submitting a patch.
8. Never delete upstream code to customize — default to keeping it + a vendor config gate (#if defined(CONFIG_<VENDOR>_<PURPOSE>)). See references/bsp_discipline.md.
9. Never conclude a hardware state from software observation alone — read the bytes directly (register/OTP/eFuse dump). See references/bsp_discipline.md.
10. Never decide a change is safe on the compile dimension alone — check the 4 dimensions (compile / runtime path / semantics / compliance). See references/bsp_discipline.md.
11. Never change an existing function's contract without enumerating every call site — 返回值含义、参数取值空间、副作用、错误约定,任何一项变了都要逐个调用点确认。类型不变时编译器一声不吭,静默的行为改变比编译错误危险得多。跑 scripts/check_api_change.sh <函数名>,方法见 references/api-contract-change.md。
12. Never conclude "this line runs" from a grep hit alone — grep 返回行,语义住在块里。下结论前答完 WHO / WHEN / ELSE 三问,尤其别拿 WHO 的答案当 WHEN 的答案。跑 scripts/show_guard_chain.py --grep <pattern> <path>,方法见 references/execution-context.md。
13. Never redesign existing code before finding out why it is the way it is — 改一段已经在跑的代码,顺序是:考古(scripts/why_this_code.sh,读原作者 commit message —— 那是设计意图唯一的一手记录)→ 读子系统规范 → 摸上下文(scripts/check_context_safety.py:能不能睡 / 并发 / 多核 SMP / 生命周期)→ 算影响面 → 才定方案。方案优先级有序:不动对外接口 > 靠拢内核通用设计 > 好移植好维护 > 修原设计缺陷。完整流程见 references/modifying-existing-code.md。
14. Never keep going when a change starts cascading — 改一处牵出一串(SDK 升级的冲突修复天生如此),停下来说明现状再继续,别闷头改完;级联到新的一件事就开新 commit。提交前跑 scripts/diff_discipline.mjs --diff <patch> --scope '<被要求改的范围>',逐行自问"哪句需求让这行成为必要的" —— 答案是"顺手"就撤掉。方法见 references/change-discipline.md。
15. Never let an AI/tool add Signed-off-by — only a human can certify the DCO. AI-assisted work is disclosed with Assisted-by:; the human reviews all of it, ensures SPDX + GPL-2.0 compatibility, and adds their own sign-off. See references/patch-workflow.md.

References (load on demand)

子系统模块（按需路由）

深入具体内核子系统时加载对应模块（命中才读，progressive disclosure），每个对应该子系统的 Documentation/<subsys>/，并配套 eval 用例进 harness（fact_gate + 回归测）。

目录总览见 index.md。

关于本 skill 的自我进化引擎

本 skill 正在配一套有度量的自我改进机制（事实检查 / 打分面板 / 测试用例集 / 回归测试 / /kernel-learn）， 并能跟随内核版本自更新。设计与状态见同目录 HARNESS-DESIGN.md。 dos-and-donts.md / known-bugs.md 会随真实任务由该机制逐步充实——每条都带可执行检查，不是空话。

已落（P1 客观检查 + P2 回归测试 + P3 打分面板/学习循环 + P4 记录表/版本适配）：

• scripts/fact_gate.mjs — 查答案 [CLAIMS] 里的 API / CONFIG / 符号 / compatible 是否在真内核树实存（树无关 --tree；exit 0 干净 / 1 有幻觉 / 3 检查坏不算 fail）
• scripts/check_call_tree.py — 查答案里的 ASCII 调用树是否列对得上（非 ASCII / 缩进不在步长 / <--- 落到不存在的帧 / 单行过宽；--selftest 四探针 + 一棵干净树校准假阳）
• scripts/checkpatch_gate.sh — 用内核自带 checkpatch.pl 校代码风格
• scripts/defconfig_gate.mjs — 查 defconfig 里写了却没生效的行(符号本 arch 不存在 / depends on 不满足 / 上游已删)。按符号比对声明值与 .config 实际落值,无视顺序 —— savedefconfig 的 diff 会被重排序淹没,3 行真问题藏在几百行噪声里。另报 #CONFIG_X(# 后缺空格 ⇒ Kconfig 视为纯注释)。--selftest 做自降解校准;exit 0 全生效 / 1 有声明未生效 / 3 闸坏。规则见 references/bsp_discipline.md §1
• scripts/decompressor_limit_check.sh — 判断一棵树会不会踩 arm32 解压器那条可执行窗口上界（两级判据：先架构后 BSP；两边都有/都没有 configs/vendor 时诚实报「未判定」要求 --arch，不猜）
• scripts/binary_diff_classify.py — 两个二进制的差异是真实代码变化还是地址整体平移（按 32 位字解码统计 delta 分布；--limit 划出未压缩区，否则压缩载荷雪崩淹没一切；带 --self-test）
• scripts/kernel-tree.mjs — 绑内核树（detect / add / list / clone），路径存本机配置不入库
• scripts/regression_test.mjs + tests/eval/cases/*.json — 回归测试:每条用例的 gold 必须在真树查得到 + 自降解校准（故意改坏必须被抓）+ 覆盖率统计；--baseline 记录、--check 对比退步
• scripts/kernel-critic.mjs + .claude/agents/kernel-*-critic.md — 7 轴打分面板（correctness/safety/design/testing/complexity/coding-style/completeness,对应 Google review 维度;safety 一票否决）prompt 准备,Task 派子 agent 并行评分
• /kernel-learn（.claude/commands/ + scripts/kernel_learn_validate.mjs）— 把踩过的坑沉成原子三件套（规则带 [CLAIMS] + 建前fail/建后pass 用例 + 注册），无可执行检查不准建
• evolution/{ledger.tsv,rules.json} + scripts/version_drift.mjs — 记录表/规则复用 design-evolve（evolve-ledger.mjs --ledger= / evolve-rules.mjs --registry=）带 fires/catches；version_drift.mjs 拿多版本树对比 gold,报"旧版有新版没"的 API（机器跑出版本漂,不靠手维护）
• 引具体符号的答案附 [CLAIMS] 块（references/claims-contract.md）；绑树后跑事实检查,答案标 [已对 linux <版本> 验证] 或 [未验证]