GCC

Linux 代码片段注释与分析 Skill 模板（中文、正文无链接）

目标

把一段 Linux C 代码改写成“可独立阅读”的分析稿：保留原码结构与宏，去掉原英文注释，只在需要处补充中文就地注释，并按固定章节输出。

除函数外，本模板同样覆盖以下代码单元：

• 静态变量 / 全局对象
• struct ... = {} 初始化对象
• id_table / 匹配表 / 描述符表
• ops / driver / dev_pm_ops / 回调表
• MODULE_*、module_*driver、module_param 等模块级宏
• 其他对绑定、注册、能力选择、全局行为有直接影响的声明与宏

---

输出结构模板

1) 标题

• 用 ## 做大标题
• 大标题只包含：本次片段里会出现 ### 小标题的代码单元名列表（用空格分隔）
• 代码单元名列表末尾追加一句概括（不含括号）

示例：

## foo bar baz driver_ops module_init 同步提交、注册与回调绑定路径梳理

---

2) 大标题下两段（必须有）

作用与实现要点

• 只写策略与设计点，不复述基础流程

• 覆盖这些点（按实际出现取用）：

  • 状态机与状态位流转
  • 分支选择理由（为什么走这条路）
  • 能力门控与特性开关
  • 参数检查与早退路径
  • 一次性标志位 / 回调绑定 / 表项绑定
  • 后台机制影响（worker / hrtimer / trace / 调度点 / PM）
  • 静态对象、匹配表、driver/ops 表、模块宏分别由谁消费、在什么阶段生效
  • 非函数代码单元如何影响函数路径（如 id->data、.pm、.probe、.id_table、模块参数回退值）

平台关注：单核、无 MMU、ARMv7-M（STM32H750）

• 说明语义是否变化；强调锁 / 状态位 / 时间基准 / 后台机制 / 寄存器访问顺序在该平台的意义

• 若无差异，直接写这一句（原样照抄）：

  • 本段逻辑与单核/无MMU无直接差异，依赖底层 ops 与系统定时机制

---

3) 每个代码单元的输出模板

每个代码单元使用：

### 代码单元名 中文作用

并按下面顺序输出：

1. 代码单元定义前添加注释块

2. 输出原代码（不省略），但：

   • 删除原英文注释（/* ... */ 与 // ... 都删）
   • 保留宏、类型、结构体字段访问、必要的代码本身

3. 只在需要处添加中文注释（/* ... */），其余不加

---

中文注释写作规则模板

注释写什么

对需要加注释的语句，注释要同时交代（用自然语句写，不用标签词）：

• 这一行做了什么
• 为什么要这样做
• 触发点是什么（什么状态 / 什么场景下会走到这里）
• 产生什么影响（引用计数、状态位、电源、等待点、资源回收、可见性 / 顺序性、设备匹配、回调绑定、模块装载行为）

避免只写抽象名词（例如“门控 / 关键路径”这种不落地的词）。

需要加注释的语句范围

出现以下元素时优先加注释（按实际出现取用）：

• 分支选择点（if/else/switch、早退、goto 失败路径）
• 位操作：set_bit/clear_bit/test_bit/test_and_set_bit/test_and_clear_bit
• trace_*、ktime_*、时间戳与超时相关
• worker / workqueue / hrtimer / 定时器回调提交与取消
• 能力门控、特性开关、一次性标志位
• 参数合法性检查、边界值处理
• 等待与唤醒、完成量、队列推进、内存屏障
• 时钟、复位、电源、pinctrl、DMA、ioremap、IRQ 申请与释放
• 回调表字段绑定、匹配表字段、driver 描述符字段、模块注册宏、模块参数宏

注释排版与就地解释

单行判断示例形态（注释紧跟判断语句）：

if (cond) /* 解释 cond 表达的状态/门控意义，以及不满足会走向哪里 */
    goto fail;

复合判断分行示例形态（每段就地解释）：

if (a &&  /* 解释 a 表示的状态位/资源是否就绪 */
    b &&  /* 解释 b 的含义，以及它为何需要与 a 同时成立 */
    c)    /* 解释 c 代表的门控/时序点，整体成立会进入哪个分支 */
    return -EINVAL;

结构体字段初始化示例形态：

static const struct xxx_ops ops = {
    .foo = bar, /* 把 foo 回调绑定到 bar，后续由上层框架在对应阶段调用 */
    .baz = qux, /* 这一项决定某类能力是否由驱动显式接管 */
};

匹配表项示例形态：

{
    .id   = 0x12345678, /* 这一匹配值命中后，会让总线把设备交给本驱动继续 probe */
    .mask = 0xffffffff, /* 掩码决定比较时哪些位必须参与匹配，影响同系列不同修订版如何归类 */
    .data = &variant_x, /* probe 里通常会把它转成 variant，后续能力分支都从这里展开 */
},

模块宏示例形态：

MODULE_DEVICE_TABLE(bus, ids); /* 导出匹配表给模块自动装载机制，使设备出现时能关联到本驱动 */

module_param(fmax, uint, 0444); /* 暴露模块参数，影响 probe 中未显式给定配置时的回退值 */

关于 goto / 回收 / 等待点的写法

遇到以下语句时，注释必须说明“为什么要这么写，以及避免了什么问题”：

• goto out_*、失败回收路径
• 引用计数增减配平
• 等待点（completion/waitqueue/spin 等待）、唤醒点
• 内存屏障与可见性相关语句
• 回调表绑定
• 匹配表绑定
• driver 描述符注册
• 模块注册宏
• 模块参数入口

禁用措辞

• 注释里不要出现“关键行”字样
• 分析正文与注释中避免使用“约束”“条件”“后果”等标签化写法（直接用自然语句描述触发点与影响）
• 不要只写“这里做了初始化”“这里进行了配置”“这个结构体很重要”，要写清谁读取它、何时生效、它把后续流程导向哪里

---

代码处理规则模板

• 原码完整输出，不省略分支、标签、回收段、表项、宏、模块声明
• 删除原英文注释
• 不改变量名与控制流，不重排语句（除非为了把复合判断拆行，并保持语义等价）
• 宏、导出符号、结构体声明等保留原样
• 对非函数代码单元，不得因为“不是函数”而省略正文输出
• 若片段中存在静态对象、匹配表、driver/ops 表、模块宏，必须与函数一样单独成节分析

---

获取上下文与对齐方式模板

• 以 Linux 主线同名文件为主，对照相邻函数、静态对象、匹配表与调用链推断语义
• 可用网页检索核对版本差异与命名，但正文不出现任何 URL、链接形态或可点击引用标记
• 通过 Linux 主线源码查看上下文思考
• 如确实需要交代来源信息，放在“对话附注”里，用纯文本描述，不写 URL
• 对 ops / driver / id_table / MODULE_* 这类单元，不只看本地片段，还要结合其被谁消费来解释
• 对表项和宏，必须顺着调用者或框架消费路径补上下文

---

代码单元注释块模板（直接套用）

函数类代码单元

/**
 * @brief 一句话说明该函数做什么（面向调用方的语义）
 * @param xxx 解释参数含义、取值范围、与状态位/资源的关系
 * @return 返回值语义，错误码或状态码代表什么
 *
 * 补充说明：
 * - 说明回调绑定/一次性标志位/等待点与唤醒点之间的关联
 * - 说明与状态位、引用计数、资源生命周期的关系
 */

非函数类代码单元

/**
 * 这段代码单元负责什么。
 * 它会被谁读取或消费。
 * 它在什么阶段生效。
 * 它如何影响设备匹配、驱动注册、电源管理、能力选择、模块装载或全局行为。
 *
 * 补充说明：
 * - 说明与相关函数、回调表、匹配表或模块参数之间的关系
 * - 若是表项或宏，说明关键字段或宏参数分别改变了什么行为
 */

---

新增强制规则

• 若片段中出现以下内容，必须单独成节，不得只在“作用与实现要点”里一笔带过：

  • static const struct dev_pm_ops ...
  • static const struct xxx_id ...[]
  • static const struct of_device_id ...[]
  • static struct platform_driver ...
  • static struct amba_driver ...
  • static const struct xxx_ops ...
  • MODULE_DEVICE_TABLE(...)
  • module_platform_driver(...)
  • module_amba_driver(...)
  • module_param(...)
  • MODULE_DESCRIPTION(...)
  • MODULE_LICENSE(...)
  • 其他影响注册、匹配、装载或能力选择的静态对象与宏

• 分析这些单元时必须说明：

  • 谁消费它
  • 在什么阶段生效
  • 它与哪个函数或回调绑定
  • 它如何改变 probe / remove / PM / IRQ / 模块装载路径

• 如果片段里修改了全局静态 ops，必须说明这是全局对象、绑定发生在哪里、后续哪些路径会受影响

• 对 module_*driver(...) 这类宏，必须解释它是注册封装，最终把哪个 driver 对象接入哪类总线框架

• 对 module_param(...)，必须解释它影响哪条回退路径或默认配置

---

交付输出占位模板（你后续每次都可用）

## <代码单元A> <代码单元B> <代码单元C> <一句概括>

### 作用与实现要点
- ...

### 平台关注：单核、无 MMU、ARMv7-M（STM32H750）
- 本段逻辑与单核/无MMU无直接差异，依赖底层 ops 与系统定时机制

### <代码单元A> <中文作用>
<函数 doxygen 注释块 或 非函数代码单元注释块>
<删掉英文注释后的完整原码 + 中文就地注释>

### <代码单元B> <中文作用>
...

### <代码单元C> <中文作用>
...

---

文章编写

1. 如下是要求写作时使用的skill，请按照此模板进行编写。
2. 不要有人称
3. 需要给出标题
4. 对给的素材内容要做脱敏和去隐私化处理

---
name: 04-process-docs-write
description: 用于撰写/改写文档（Markdown/MDX），强调清晰、面向读者；当需要写 README、设计文档或使用说明时使用。
allowed-tools: Read, Write, Grep, Bash, Glob
---

# Documentation Writing Skill

## When writing documentation

### Start here

1. **Who is this for?** Match complexity to audience. Don't oversimplify hard things or overcomplicate simple ones.
2. **What do they need?** Get them to the answer fast. Nobody wants to be in docs longer than necessary.
3. **What did you struggle with?** Those common questions you had when learning? Answer them (without literally including the question).

### Writing process

**Draft:**

- Write out the steps/explanation as you'd tell a colleague
- Lead with what to do, then explain why
- Use headings that state your point: "Set SAML before adding users" not "SAML configuration timing"

**Edit:**

- Read aloud. Does it sound like you talking? If it's too formal, simplify.
- Cut anything that doesn't directly help the reader
- Check each paragraph has one clear purpose
- Verify examples actually work (don't give examples that error)

**Polish:**

- Make links descriptive (never "here")
- Backticks only for code/variables, **bold** for UI elements
- American spelling, serial commas
- Keep images minimal and scoped tight

**Format:**

- Run prettier on the file after making edits: `yarn prettier --write <file-path>`
- This ensures consistent formatting across all documentation

### Common patterns

**Instructions:**

```markdown
Run:
\`\`\`
command-to-run
\`\`\`

Then:
\`\`\`
next-command
\`\`\`

This ensures you're getting the latest changes.

Not: “(remember to run X before Y…)” buried in a paragraph.

Headings:

• “Use environment variables for configuration” ✅
• “Environment variables” ❌ (too vague)
• “How to use environment variables for configuration” ❌ (too wordy)

Links:

• “Check out the SAML documentation“ ✅
• “Read the docs here“ ❌

Watch out for

• Describing tasks as “easy” (you don’t know the reader’s context)
• Using “we” when talking about Metabase features (use “Metabase” or “it”)
• Formal language: “utilize”, “reference”, “offerings”
• Too peppy: multiple exclamation points
• Burying the action in explanation
• Code examples that don’t work
• Numbers that will become outdated

Quick reference

Write This	Not This
people, companies	users
summarize	aggregate
take a look at	reference
can’t, don’t	cannot, do not
Filter button	`Filter` button
Check out the docs	Click here

Linux 技术知识深度解析提示词模板

---

[技术中文名]：全面了解与深度解析

文件路径：[文件路径]
技术中文名：[技术中文名]
功能概述：[功能概述]

介绍

请围绕 [技术中文名] 做一次系统、完整、偏工程实践的技术解析，内容以 Linux 技术栈为背景，输出一篇结构清晰、术语准确、适合技术文档沉淀的文章。
要求内容尽量具体，避免空泛描述，不使用比喻、拟人、夸张等修辞。
如果涉及版本、内核特性、项目演进、实现差异，请尽量指出具体版本或阶段。
如果存在争议或实现依赖发行版/内核版本，请明确说明。

---

历史与背景

请从以下方面展开：

1. 诞生背景

   • 这项技术是为了解决什么具体问题而出现的？
   • 在它出现之前，行业或 Linux 生态通常采用什么方案？
   • 旧方案的主要痛点是什么？

2. 发展历程

   • 该技术经历了哪些关键里程碑？
   • 是否有重要版本迭代、架构变化、接口变化或社区分叉？
   • 哪些版本或阶段对今天的使用方式影响最大？

3. 社区与生态现状

   • 当前社区活跃度如何？
   • 是否被主流 Linux 发行版、云原生平台、容器平台、虚拟化平台或企业环境广泛采用？
   • 当前主流应用场景和代表性项目有哪些？

---

核心原理与设计

请从以下方面展开：

1. 核心工作原理

   • 它在 Linux 系统中的工作机制是什么？
   • 它依赖哪些内核能力、用户态组件、守护进程、配置文件、系统调用、数据结构或运行时机制？
   • 它的关键执行流程是什么？

2. 设计目标

   • 它的设计重点是什么？
   • 它重点解决的是性能、资源控制、隔离、安全、可维护性、兼容性、可观测性，还是部署效率？

3. 核心优势

   • 它相比传统方案或同类技术的主要优势是什么？
   • 这些优势在生产环境里体现在哪些方面？

4. 局限性与缺点

   • 它有哪些已知问题、局限性或副作用？
   • 在哪些场景下它的能力边界比较明显？
   • 它是否依赖特定内核版本、发行版特性、权限模型或硬件能力？

5. 不适用场景

   • 哪些情况下不建议选择它？
   • 原因是什么？
   • 替代方案一般是什么？

---

使用场景

请从以下方面展开：

1. 适合使用的场景

   • 它在哪些业务或技术场景下是优先选择？

   • 请给出 3 到 5 个具体场景，并说明原因。

   • 每个场景请尽量包含：

     • 场景背景
     • 为什么适合
     • 实际收益
     • 需要注意的问题

2. 不推荐使用的场景

   • 哪些业务或技术场景不适合使用它？
   • 是因为性能、复杂度、资源开销、运维成本、兼容性，还是安全边界问题？

3. 生产实践建议

   • 如果在生产环境落地，通常要关注哪些配置点、监控指标、排障方法和风险控制措施？

---

对比分析

请将 [技术中文名] 与 [相似技术1]、[相似技术2]、[相似技术3] 进行详细对比。
如果主题本身是 Linux 容器、虚拟化、服务管理、网络、文件系统、安全机制、可观测性组件，请结合该类别常见对手进行横向分析。

请至少从以下维度对比：

1. 实现方式

   • 它们分别基于什么原理实现？
   • 是内核态能力、用户态封装、守护进程模型，还是混合架构？

2. 性能开销

   • CPU、内存、I/O、网络路径上的额外开销如何？
   • 在高并发、低延迟、大吞吐场景下差异体现在哪里？

3. 资源占用

   • 常驻资源消耗如何？
   • 是否需要额外的后台进程、镜像层、元数据管理或专用运行时？

4. 隔离级别

   • 进程隔离、文件系统隔离、网络隔离、权限隔离和安全边界分别如何？
   • 是进程级隔离、内核共享隔离，还是硬件级虚拟化隔离？

5. 启动速度

   • 启动和销毁速度如何？
   • 更适合长生命周期服务还是短生命周期任务？

6. 运维复杂度

   • 配置、调试、监控、升级、兼容性处理的复杂度如何？

7. 适用场景差异

   • 各自更适合什么场景？
   • 在什么前提下应该优先选 A 而不是 B？

请在这一节最后输出一张总结表，字段建议包含：

对比维度	[技术中文名]	[相似技术1]	[相似技术2]	[相似技术3]
实现方式
性能开销
资源占用
隔离级别
启动速度
运维复杂度
推荐场景

---

总结

请从以下方面收束全文：

1. 关键特性总结

   • 用条理清晰的方式总结该技术最重要的能力和限制。

2. 选型建议

   • 如果是架构师、运维工程师、平台工程师或开发工程师，在什么情况下应该优先考虑它？

3. 学习建议

   • 如果要系统学习这项技术，建议按什么顺序掌握？
   • 分别从基础概念、运行机制、配置方法、调试排障、性能优化、生产实践几个层面给出建议。

4. 实践路线

   • 给出一个从入门到深入的学习路径，尽量包含：

     • 先学什么
     • 再学什么
     • 最后深入什么
     • 建议掌握哪些命令、日志、配置文件、观测指标和实验方法

---

输出要求

请严格遵守以下要求：

• 文章开头必须包含标题。

• 输出结构必须严格按照：

  • 标题
  • 文件路径 / 技术中文名 / 功能概述
  • 介绍
  • 历史与背景
  • 核心原理与设计
  • 使用场景
  • 对比分析
  • 总结

• 不使用比喻、类比、拟人、夸张表达。

• 尽量使用技术术语，但解释要清楚。

• 如果涉及版本差异、发行版差异或实现差异，请明确说明。

• 如果结论依赖特定前提，请写清前提条件。

• 如果是 Linux 相关主题，优先参考官方文档、内核文档、项目主页和 man page。Linux 内核官方文档对 namespaces 与 cgroup 等底层机制有权威说明；systemd 官方文档适合服务管理与 unit 体系；LXC 官方文档适合容器配置与 cgroup 接口说明。([Linux内核文档][1])

• 如果可能，请补充命令示例、配置片段、典型排障思路和常见误区。

• 对比分析部分必须包含表格。

获取上下文与对齐方式模板

• 以 Linux 主线同名文件为主，对照相邻函数与调用链推断语义
• 可用网页检索核对版本差异与命名，但正文不出现任何 URL、链接形态或可点击引用标记
• 通过https://code.googlesource.com/linux/torvalds/linux/+/refs/heads/master进行查看上下文思考
• 如确实需要交代来源信息，放在“对话附注”里，用纯文本描述，不写 URL

---