英语

Linux 内核补丁提交核对表

以下是一些开发人员若想其内核补丁提交能更快被接受应做的基本事项。

这些都超出了Documentation/process/submitting-patches.rst及其他地方关于提交 Linux 内核补丁所提供的文档范围。

审查你的代码

  1. 如果你使用了某个设施，那么请 #include 定义/声明该设施的文件。不要依赖其他头文件来引入你使用的文件。

  2. 检查你的补丁是否符合Documentation/process/coding-style.rst中详述的通用代码风格。

  3. 所有内存屏障（例如 barrier()、rmb()、wmb()）都需要在源代码中附带注释，解释其逻辑和原因。

审查 Kconfig 更改

  1. 任何新的或修改的 CONFIG 选项都不会弄乱配置菜单，并且默认关闭，除非它们符合 Documentation/kbuild/kconfig-language.rst 中“菜单属性：默认值”部分记录的例外标准。

  2. 所有新的 Kconfig 选项都有帮助文本。

  3. 已针对相关的 Kconfig 组合进行了仔细审查。这通过测试很难做到位——这里需要智力投入。

提供文档

  1. 包括 kernel-doc 来记录全局内核 API。（对于静态函数不是必需的，但包含也可。）

  2. 所有新的 /proc 条目都记录在 Documentation/ 下

  3. 所有新的内核启动参数都记录在 Documentation/admin-guide/kernel-parameters.rst 中。

  4. 所有新的模块参数都使用 MODULE_PARM_DESC() 进行记录

  5. 所有新的用户空间接口都记录在 Documentation/ABI/ 中。更多信息请参阅Linux ABI 描述（或 Documentation/ABI/README）。修改用户空间接口的补丁应抄送至 linux-api@vger.kernel.org。

  6. 如果补丁添加了任何 ioctl，则还需更新 Documentation/userspace-api/ioctl/ioctl-number.rst。

使用工具检查你的代码

  1. 提交前使用补丁风格检查器 (scripts/checkpatch.pl) 检查是否存在轻微违规。你应该能够解释补丁中所有仍然存在的违规。

  2. 使用 sparse 干净地检查。

  3. 使用 make checkstack 并修复发现的任何问题。请注意，checkstack 不会明确指出问题，但任何在栈上使用超过 512 字节的函数都可能是需要更改的候选。

构建你的代码

  1. 干净地构建

  1. 使用适用或修改的 CONFIG 选项 =y、=m 和 =n。没有 gcc 警告/错误，没有链接器警告/错误。

  2. 通过 allnoconfig、allmodconfig

  3. 使用 O=builddir 成功构建

  4. 所有 Documentation/ 更改都能成功构建，没有新的警告/错误。使用 make htmldocs 或 make pdfdocs 检查构建并修复任何问题。

  1. 通过使用本地交叉编译工具或其他构建农场在多个 CPU 架构上构建。请注意，针对不同字长（32 位和 64 位）和不同字节序（大端和小端）的架构进行测试，能有效地捕获由于对可表示数量范围、数据对齐或字节序等方面的错误假设而导致的各种可移植性问题。

  2. 新添加的代码已使用 gcc -W 编译（使用 make KCFLAGS=-W）。这会产生大量“噪音”，但对于发现“警告：有符号与无符号比较”等错误很有用。

  3. 如果你的修改后的源代码依赖或使用了与以下 Kconfig 符号相关的任何内核 API 或功能，那么请测试在禁用和/或 =m（如果该选项可用）相关 Kconfig 符号时的多次构建 [不是同时启用所有这些，只是它们的各种/随机组合]

    CONFIG_SMP, CONFIG_SYSFS, CONFIG_PROC_FS, CONFIG_INPUT, CONFIG_PCI, CONFIG_BLOCK, CONFIG_PM, CONFIG_MAGIC_SYSRQ, CONFIG_NET, CONFIG_INET=n (但后者与 CONFIG_NET=y 结合)。

测试你的代码

  1. 已使用 CONFIG_PREEMPT、CONFIG_DEBUG_PREEMPT、CONFIG_SLUB_DEBUG、CONFIG_DEBUG_PAGEALLOC、CONFIG_DEBUG_MUTEXES、CONFIG_DEBUG_SPINLOCK、CONFIG_DEBUG_ATOMIC_SLEEP、CONFIG_PROVE_RCU 和 CONFIG_DEBUG_OBJECTS_RCU_HEAD 同时启用进行测试。

  2. 已在启用和不启用 CONFIG_SMP 和 CONFIG_PREEMPT 的情况下进行构建和运行时测试。

  3. 所有代码路径都已在启用所有 lockdep 功能的情况下进行演练。

  4. 已检查并注入至少 slab 和页面分配失败。请参阅 Documentation/fault-injection/。如果新代码量大，则可能适合添加特定子系统的故障注入。

  5. 已使用最新的 linux-next 标签进行测试，以确保其仍能与所有其他排队补丁以及 VM、VFS 和其他子系统中的各种更改正常工作。