提交内核补丁patch_block comments use * on subsequent lines

提交内核补丁
荣涛 2021年10月28日

文档修改日志

1. 引言

2. 克隆内核

# 从 GitHub克隆Linux内核
$ git clone --depth=32 https://github.com/torvalds/linux
# 切换分支
$ git checkout master
# 同步
$ git pull upstream master
1
2
3
4
5
6

3. 创建一个分支

$ git checkout -b "new-branch-name"
1

4. 修改源代码

5. 提交修改

# 首先添加修改的文件
$ git add .
# 提交修改
$ git commit -s -v
1
2
3
4

命令git commit -s -v 命令运行后将会打开一个编辑器，该编辑器会从 $GIT_EDITOR 或 $EDITOR 环境变量中进行选择。

• -s 命令行参数会在提交信息的末尾按照提交者名字加上一行 Signed-off-by。你在每一条提交信息的最后都能看到这一行，例如 - 00cc1633。这一行的主要目的是追踪谁做的修改。
• -v 选项按照合并格式显示 HEAD 提交和即将进行的最新提交之间的差异。这样做不是必须的，但有时候却很有用。再来说下提交信息，实际上，一条提交信息由两部分组成：

第一部分放在第一行，它包括了一句对所做修改的简短描述。这一行以 [PATCH] 做前缀，后面跟上子系统、驱动或架构的名字，以及在 : 之后的简述信息。例如：

[PATCH] staging/dgap: Use strpbrk() instead of dgap_sindex()
1

简述信息之后，我们通常空一行再加上对本次提交的详尽描述。在我们的这个例子中，这些信息如下所示：

The <linux/string.h> provides strpbrk() function that does the same that the
dgap_sindex(). Let's use already defined function instead of writing custom.
1
2

在提交信息的最后是 Sign-off-by 这一行。注意，提交信息的每一行不能超过 80 个字符并且提交信息必须详细地描述你所做的修改。千万不要只写一条类似于 Custom function removed 这样的信息，你需要描述你做了什么以及为什么这样做。补丁的审核者必须据此知道他们正在审核什么内容，除此之外，这里的提交信息本身也非常有用。每当你不能理解一些东西的时候，我们都可以使用 git blame 命令来阅读关于修改的描述。

6. 生成补丁文件

提交修改之后，是时候生成补丁文件了。我们可以使用 format-patch 命令来完成：

$ git format-patch master
0001-staging-dgap-Use-strpbrk-instead-of-dgap_sindex.patch
# 或者
$ git format-patch master --stdout > dgap-patch-1.patch
1
2
3
4

7. 发送到 Linux 内核邮件列表

最后一步就是在我们生成补丁之后将之发送到 Linux 内核邮件列表。当然，你可以使用任意的邮件客户端，不过 git 为此提供了一个专门的命令：git send-email。

在发送补丁之前，你需要知道发到哪里。虽然你可以直接把它发送到 linux-kernel@vger.kernel.org 这个邮件列表，但这很可能让你的补丁因为巨大的消息流而被忽略掉。最好的选择是将补丁发送到你的修改所属子系统的维护者那里。你可以使用 get_maintainer.pl 这个脚本来找到这些维护者的名字。你所需要做的就是将你代码所在的文件或目录作为参数传递给脚本。如下面的输出

$ ./scripts/get_maintainer.pl include/linux/sched.h 
Ingo Molnar <mingo@redhat.com> (maintainer:SCHEDULER)
Peter Zijlstra <peterz@infradead.org> (maintainer:SCHEDULER)
Juri Lelli <juri.lelli@redhat.com> (maintainer:SCHEDULER)
Vincent Guittot <vincent.guittot@linaro.org> (maintainer:SCHEDULER)
Dietmar Eggemann <dietmar.eggemann@arm.com> (reviewer:SCHEDULER)
Steven Rostedt <rostedt@goodmis.org> (reviewer:SCHEDULER)
Ben Segall <bsegall@google.com> (reviewer:SCHEDULER)
Mel Gorman <mgorman@suse.de> (reviewer:SCHEDULER)
Daniel Bristot de Oliveira <bristot@redhat.com> (reviewer:SCHEDULER)
Alexei Starovoitov <ast@kernel.org> (supporter:BPF (Safe dynamic programs and tools))
Daniel Borkmann <daniel@iogearbox.net> (supporter:BPF (Safe dynamic programs and tools))
Andrii Nakryiko <andrii@kernel.org> (supporter:BPF (Safe dynamic programs and tools))
Martin KaFai Lau <kafai@fb.com> (reviewer:BPF (Safe dynamic programs and tools))
Song Liu <songliubraving@fb.com> (reviewer:BPF (Safe dynamic programs and tools))
Yonghong Song <yhs@fb.com> (reviewer:BPF (Safe dynamic programs and tools))
John Fastabend <john.fastabend@gmail.com> (reviewer:BPF (Safe dynamic programs and tools))
KP Singh <kpsingh@kernel.org> (reviewer:BPF (Safe dynamic programs and tools))
linux-kernel@vger.kernel.org (open list:SCHEDULER)
netdev@vger.kernel.org (open list:BPF (Safe dynamic programs and tools))
bpf@vger.kernel.org (open list:BPF (Safe dynamic programs and tools))
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

你将会看到一组姓名和与之相关的邮件地址。现在你可以通过下面的命令发送补丁了：

$ git send-email --from "Rong Tao <rongtao@cestc.cn>" \
  --to "Lidza Louina <lidza.louina@gmail.com>" \
  --cc "Mark Hounschell <markh@compro.net>"                   \
  --cc "Daeseok Youn <daeseok.youn@gmail.com>"                \
  --cc "Greg Kroah-Hartman <gregkh@linuxfoundation.org>"      \
  --cc "driverdev-devel@linuxdriverproject.org"               \
  --cc "devel@driverdev.osuosl.org"                           \
  --cc "linux-kernel@vger.kernel.org"
1
2
3
4
5
6
7
8

这就是全部的过程。补丁被发出去了，现在你所需要做的就是等待 Linux 内核开发者的反馈。在你发送完补丁并且维护者接受它之后，你将在维护者的仓库中看到它 (例如前文你看到的补丁)。一段时间后，维护者将会向 Linus 发送一个拉取请求，之后你就会在主线仓库里看到你的补丁了。

8. 一些建议

在该部分的最后，我想给你一些建议，这些建议大都是关于在 Linux 内核的开发过程中需要做什么以及不能做什么的：

• 考虑，考虑，再考虑。在你决定发送补丁之前再三考虑。
• 在你每次改完 Linux 内核源代码之后 - 试着编译它。我指的是任何修改之后，都要不断的编译。没有人喜欢那些连编译都不通过修改。
• Linux 内核有一套代码规范指南，你需要遵守它。有一个很棒的脚本可以帮你检查所做的修改。这个脚本就是 - scripts/checkpatch.pl。只需要将被改动的源码文件传递给它即可，然后你就会看到如下输出：

$ ./scripts/checkpatch.pl -f drivers/staging/dgap/dgap.c
WARNING: Block comments use * on subsequent lines
#94: FILE: drivers/staging/dgap/dgap.c:94:
+/*
+     SUPPORTED PRODUCTS

CHECK: spaces preferred around that '|' (ctx:VxV)
#143: FILE: drivers/staging/dgap/dgap.c:143:
+	{ PPCM,        PCI_DEV_XEM_NAME,     64, (T_PCXM|T_PCLITE|T_PCIBUS) },

1
2
3
4
5
6
7
8
9
10

在 git diff命令的帮助下，你也会看到一些有问题的地方：

• Linus 不接受 github pull requests
• 如果你的修改是由一些不同的且不相关的改动所组成的，你需要通过分离提交来切分修改。git format-patch 命令将会为每个提交生成一个补丁，每个补丁的标题会包含一个 vN 前缀，其中 N 是补丁的编号。如果你打算发送一系列补丁，也许给 git format-patch 命令传递 --cover-letter 选项会对此很有帮助。这会生成一个附加文件，该文件包括的附函可以用来描述你的补丁集所做的改动。在 git send-email 命令中使用 --in-reply-to 选项也是一个好主意，该选项允许你将补丁集作为对附函的回复发送出去。对于维护者来说，你补丁集的结构看起来就像下面这样：

你可以将 message-id 参数传递给 --in-reply-to 选项，该选项可以在 git send-email 命令的输出中找到。

有一件非常重要的事，那就是你的邮件必须是纯文本格式。通常来说，send-email 和 format-patch 这两个命令在内核开发中都是非常有用的，所以请查阅这些命令的的相关文档，你会发现很多有用的选项，例如：git send-email 和 git format-patch。

• 如果你发完补丁之后没有得到立即答复，请不要惊讶，因为维护者们都是很忙的。
• scripts 目录包含了很多对 Linux 内核开发有用的脚本。我们已经看过此目录中的两个脚本了：checkpatch.pl 和 get_maintainer.pl。除此之外，你还可以找到 stackusage 脚本，它可以打印栈的使用情况，extract-vmlinux 脚本可以提取出未经压缩的内镜镜像，还有很多其他的脚本。在 scripts 目录之外，你也会发现很多有用的脚本，这些脚本是 Lorenzo Stoakes 为内核开发而编写的。
• 订阅 Linux 内核邮件列表。lkml 列表中每天都会有大量的信件，但是阅读它们并了解一些类似于 Linux 内核目前开发状态的内容是很有帮助的。除了 lkml 之外，还有一些其他的邮件列表，它们分别对应于不同的 Linux 内核子系统。
• 如果你发的补丁第一次没有被接受，你就会收到 Linux 内核开发者的反馈。请做一些修改然后以 [PATCH vN](N 是补丁版本号) 为前缀重新发送补丁，例如：

[PATCH v2] staging/dgap: Use strpbrk() instead of dgap_sindex()
1

同样的，这次的补丁也必须包括更新日志以便描述自上一次的补丁以来所做的修改。当然，本文并不是对 Linux 内核开发详尽无遗的指导清单，但是一些最重要的事项已经都被阐明了。

Happy Hacking!

9. 参考链接

• Linux内核构建与开发
• 内核邮件列表lkml