Submit Patches Step by Step

Submit Patches Step by Step

谢宝友 2017/08/17

本文简介

本文一步一步的演示如何生成一个简单Linux内核补丁，并提交给Linux社区。用以展示向社区提交补丁的步骤。

作者简介

谢宝友，在编程一线工作已经有20年时间，其中接近10年时间工作于Linux操作系统。目前，他是Linux ZTE平台的Maintainer，向社区提交了130个补丁，4000多行代码。同时，他也是《深入理解并行编程》一书的译者。该书作者Paul E.McKeney是IBM Linux中心领导者，Linux RCU Maintainer。
在中兴通讯操作系统产品部工作期间，他作为技术总工参与的嵌入式实时操作系统，获得了行业最高奖----中国工业大奖。

作者联系方式：

mail:

微信或者QQ：373364645

1. 一、应有的心态

Paul在《深入理解并行编程》一书第11.1.2节中说，验证和测试工作都需要良好的心态。应当以一种破坏性的、甚至带一点仇恨的心理来验证代码，有时也应当考虑到：不少人的生命依赖于我们代码正确性的几率。总之，心态对事情的成败有重要的影响。

同样的，在向社区提交补丁之前，我们也应当有正确的心态：

1、我们的代码，可能会影响不少人的生命，所以一定要细心。

2、悲观的说，如果补丁做得不好，会被社区大牛的口水淹死。当然，更可能的情况是，大牛懒得向你吐口水：）所以在提交补丁前，请为自己的声誉负责。

3、乐观的说，社区牛人一般都比较Nice，如果你的水平真的比较牛的话。

4、更进一步乐观的说，你提交的高质量的补丁，可能会为你带来良好的声誉、满意的工作。

5、需要强调一点的是，在社区，千万不要和Maintainer作对。要象对待学校老师那样，谦恭的对待Maintainer。不管你信不信这一点，反正我信了:)

如果你和我一样，有着近乎自大的自信，请接着读完本文^-^

2. 二、准备工作

在开始工作之前，请准备如下工作：

1、安装一份Linux。

不论是ubuntu、centos还是其他Linux发行版本，都是可以的。我个人习惯使用ubuntu 16.04版本。虽然我曾经尝试在windows下面安装git，但是最终你会发现，在windows下面使用git提交补丁几乎可以用痛苦来描述。

2、安装git。

默认的Linux发行版，一般都已经安装好git。如果没有，随便找一本git的书都可以。这里不详述。比较好的git资料有：

3、配置git

A 、配置用户名和邮箱

在配置用户名的时候，请注意社区朋友习惯用英语沟通，也就是名在前，姓在后。这一点会影响社区邮件讨论，因此需要留意。

在配置邮箱时，也要注意。社区会将国内某些著名的邮件服务器屏蔽。因此建议你申请一个gmail邮箱。

以下是我的配置：

xiebaoyou@ThinkPad-T440$ git config -l | grep "user"

user.email=[e-mail]

user.name=Baoyou Xie

B、配置 sendemail

你可以手工修改~/.gitconfig，或者git仓库下的.git/config文件，添加[sendemail]节。该配置用于指定发送补丁时用到的邮件服务器参数。

以下是我的配置，供参考：

[sendemail]

smtpencryption = tls

smtpserver = smtp.gmail.com

smtpuser = [e-mail]

smtpserverport = 587

gmail邮箱的配置比较麻烦，需要按照google的说明，制作证书。配置完成后，请用如下命令，向自己发送一个测试补丁：

git send-email your.patch --to your.mail --cc your.mail

3、下载源码

首先，请用如下命令，拉取linus维护的Linux主分支代码到本地：

git clone ssh://[e-mail]/zte/kernel.git

这个过程比较长，请耐心等待。

一般情况下，Linux主分支代码不够新，如果你基于这个代码制作补丁，很有可能不会顺利的合入到Maintainer那里，换句话说，Maintainer会将补丁发回给你，要求你重新制作。所以，一般情况下，你需要再用以下命令，添加其他分支，特别是linux-next分支。强调一下，你需要习惯基于linux-next分支进行工作。

git remote add linux-next

git remote add staging

git remote add net git://git.kernel.org/pub/scm/linux/kernel/git/davem/net.git

然后用如下命令拉取这三个分支的代码到本地：

git fetch --tags linux-next

git fetch --tags staging

git fetch --tags net

有些Maintainer维护了自己的代码分支，那么，你可以在内核源码目录\MAINTAINERS文件中，找一下相应文件的维护者，及其git地址。

例如，watchdog模块的信息如下：

WATCHDOG DEVICE DRIVERS

M: Wim Van Sebroeck

R: Guenter Roeck

L: [e-mail]

W:

T: git git://

S: Maintained

F: Documentation/devicetree/bindings/watchdog/

F: Documentation/watchdog/

F: drivers/watchdog/

F: include/linux/watchdog.h

F: include/uapi/linux/watchdog.h

其中，git://是其git地址。

你可以用如下命令拉取watchdog代码到本地：

git remote add watchdog git://

git fetch --tags watchdog

当然，这里友情提醒一下，MAINTAINERS里面的信息可能不一定准确，这时候你可能需要借助google，或者问一下社区的朋友，或者直接问一下作者本人。不过，一般情况下，基于linux-next分支工作不会有太大的问题。实在有问题再去打扰作者本人。

4、阅读Documentation/SubmittingPatches，这很重要。

5、检出源码

git branch mybranch next-20170807

这个命令表示将linux-next分支的20170807这个tag作为本地mybranch的基础。

git checkout mybranch

3. 三、寻找软柿子

如果没有奇遇，大厨一般都是从小工做起的。我们不可能一开始就维护一个重要的模块，或者修复一些非常重要的故障。那么我们应当怎么样入手参与社区？这当然要寻找软柿子了。拿着软柿子做出来的补丁，可以让Maintainer无法拒绝合入你的补丁。当然，这么做主要还是为了在Maintainer那里混个脸熟。否则，以后你发的重要补丁，人家可能不会理你。

什么样的柿子最软？下面是答案：

1、消除编译警告

2、编码格式，例如注释里面的单词拼写错误、对齐不规范、代码格式不符合社区要求。

建议是从“消除编译警告”入手。社区很多大牛，都是这样成长起来的。

我们平时编译内核，基本上遇不到编译警告。是不是内核非常完美，没有编译警告，非矣！你用下面这个步骤试一下：

首先，配置内核，选择所有模块：

make ARCH=arm64 allmodconfig

请注意其中“allmodconfig”，很有用的配置，我们暂且可以理解为，将所有模块都编译。这样我们就可以查找所有模块中的编译警告了。

下面这个命令开始编译所有模块：

make ARCH=arm64 EXTRA_CFLAGS="-Wmissing-declarations -Wmissing-prototypes" CROSS_COMPILE=/toolchains/aarch64-linux-gnu/bin/aarch64-linux-gnu-

其中EXTRA_CFLAGS="-Wmissing-declarations -Wmissing-prototypes"参数表示追踪所有missing-declarations、missing-prototypes类型的警告。

CROSS_COMPILE=/toolchains/aarch64-linux-gnu/bin/aarch64-linux-gnu-是指定交叉编译工具链路径，需要根据你的实际情况修改。当然，如果是x86架构，则不需要指定此参数。

在编译的过程中，我们发现如下错误：

scripts/Makefile.build:311: recipe for target 'drivers/staging/fsl-mc/bus/dpio/qbman-portal.o' failed

我们可以简单的忽略 drivers/staging/fsl-mc/bus/dpio/qbman-portal.c这个文件。在drivers/staging/fsl-mc/bus/dpio/Makefile文件中，发现这个文件的编译依赖于宏CONFIG_FSL_MC_DPIO。

于是，我们修改编译命令，以如下命令继续编译：

make CONFIG_ACPI_SPCR_TABLE=n ARCH=arm64 EXTRA_CFLAGS="-Wmissing-declarations -Wmissing-prototypes" CROSS_COMPILE=/toolchains/aarch64-linux-gnu/bin/aarch64-linux-gnu-

请注意该命令中的“ CONFIG_ACPI_SPCR_TABLE=n”，它强制关闭了 CONFIG_ACPI_SPCR_TABLE配置。

当编译完成以后，我们是不是发现有很多警告？特别是在drivers目录下。

下面是我在next-20170807版本中发现的警告：

/dimsum/git/kernel.next/drivers/clk/samsung/clk-s3c2410.c:363:13: warning: no previous prototype for 's3c2410_common_clk_init' [-Wmissing-prototypes]

void __init s3c2410_common_clk_init(struct device_node *np, unsigned long xti_f,

^

CC drivers/clk/samsung/clk-s3c2412.o

/dimsum/git/kernel.next/drivers/clk/samsung/clk-s3c2412.c:254:13: warning: no previous prototype for 's3c2412_common_clk_init' [-Wmissing-prototypes]

void __init s3c2412_common_clk_init(struct device_node *np, unsigned long xti_f,

^

CC drivers/clk/samsung/clk-s3c2443.o

/dimsum/git/kernel.next/drivers/clk/samsung/clk-s3c2443.c:388:13: warning: no previous prototype for 's3c2443_common_clk_init' [-Wmissing-prototypes]

void __init s3c2443_common_clk_init(struct device_node *np, unsigned long xti_f,

下一节，我们就基于这几个警告来制作补丁。

4. 四、制作补丁

要消除这几个警告，当然很简单了。将这几个函数声明为static即可。下面是我的修改：

git diff

diff --git a/drivers/clk/samsung/clk-s3c2410.c b/drivers/clk/samsung/clk-s3c2410.c

index e0650c3..8f4fc5a 100644

--- a/drivers/clk/samsung/clk-s3c2410.c

+++ b/drivers/clk/samsung/clk-s3c2410.c

@@ -360,7 +360,7 @@ static void __init s3c2410_common_clk_register_fixed_ext(

samsung_clk_register_alias(ctx, &xti_alias, 1);

}

-void __init s3c2410_common_clk_init(struct device_node *np, unsigned long xti_f,

+static void __init s3c2410_common_clk_init(struct device_node *np, unsigned long xti_f,

int current_soc,

void __iomem *base)

{

diff --git a/drivers/clk/samsung/clk-s3c2412.c b/drivers/clk/samsung/clk-s3c2412.c

index b8340a4..2a2ce06 100644

--- a/drivers/clk/samsung/clk-s3c2412.c

+++ b/drivers/clk/samsung/clk-s3c2412.c

@@ -251,7 +251,7 @@ static void __init s3c2412_common_clk_register_fixed_ext(

samsung_clk_register_alias(ctx, &xti_alias, 1);

}

-void __init s3c2412_common_clk_init(struct device_node *np, unsigned long xti_f,

+static void __init s3c2412_common_clk_init(struct device_node *np, unsigned long xti_f,

unsigned long ext_f, void __iomem *base)

{

struct samsung_clk_provider *ctx;

diff --git a/drivers/clk/samsung/clk-s3c2443.c b/drivers/clk/samsung/clk-s3c2443.c

index abb935c..f0b88bf 100644

--- a/drivers/clk/samsung/clk-s3c2443.c

+++ b/drivers/clk/samsung/clk-s3c2443.c

@@ -385,7 +385,7 @@ static void __init s3c2443_common_clk_register_fixed_ext(

ARRAY_SIZE(s3c2443_common_frate_clks));

}

-void __init s3c2443_common_clk_init(struct device_node *np, unsigned long xti_f,

+static void __init s3c2443_common_clk_init(struct device_node *np, unsigned long xti_f,

int current_soc,

void __iomem *base)

再编译一次，警告果然被消除了。原来，社区工作如此简单：）

但是请允许我浇一盆冷水！

你先试着用下面的命令做一个补丁出来看看！

git add drivers/clk/samsung/clk-s3c2410.c

git add drivers/clk/samsung/clk-s3c2412.c

git add drivers/clk/samsung/clk-s3c2443.c

git commit drivers/clk/samsung/

[zxic/6718 4930591] this is my test

3 files changed, 3 insertions(+), 3 deletions(-)

git format-patch -s -v 1 -1

生成的补丁内容如下：

cat v1-0001-this-is-my-test.patch

From 493059190e9ca691cf08063ebaf945627a5568c7 Mon Sep 17 00:00:00 2001

From: Baoyou Xie

Date: Thu, 17 Aug 2017 19:23:13 +0800

Subject: [PATCH v1] this is my test

Signed-off-by: Baoyou Xie

---

drivers/clk/samsung/clk-s3c2410.c | 2 +-

drivers/clk/samsung/clk-s3c2412.c | 2 +-

drivers/clk/samsung/clk-s3c2443.c | 2 +-

3 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/drivers/clk/samsung/clk-s3c2410.c b/drivers/clk/samsung/clk-s3c2410.c

index e0650c3..8f4fc5a 100644

--- a/drivers/clk/samsung/clk-s3c2410.c

+++ b/drivers/clk/samsung/clk-s3c2410.c

@@ -360,7 +360,7 @@ static void __init s3c2410_common_clk_register_fixed_ext(

samsung_clk_register_alias(ctx, &xti_alias, 1);

}

-void __init s3c2410_common_clk_init(struct device_node *np, unsigned long xti_f,

+static void __init s3c2410_common_clk_init(struct device_node *np, unsigned long xti_f,

int current_soc,

void __iomem *base)

{

diff --git a/drivers/clk/samsung/clk-s3c2412.c b/drivers/clk/samsung/clk-s3c2412.c

index b8340a4..2a2ce06 100644

--- a/drivers/clk/samsung/clk-s3c2412.c

+++ b/drivers/clk/samsung/clk-s3c2412.c

@@ -251,7 +251,7 @@ static void __init s3c2412_common_clk_register_fixed_ext(

samsung_clk_register_alias(ctx, &xti_alias, 1);

}

-void __init s3c2412_common_clk_init(struct device_node *np, unsigned long xti_f,

+static void __init s3c2412_common_clk_init(struct device_node *np, unsigned long xti_f,

unsigned long ext_f, void __iomem *base)

{

struct samsung_clk_provider *ctx;

diff --git a/drivers/clk/samsung/clk-s3c2443.c b/drivers/clk/samsung/clk-s3c2443.c

index abb935c..f0b88bf 100644

--- a/drivers/clk/samsung/clk-s3c2443.c

+++ b/drivers/clk/samsung/clk-s3c2443.c

@@ -385,7 +385,7 @@ static void __init s3c2443_common_clk_register_fixed_ext(

ARRAY_SIZE(s3c2443_common_frate_clks));

}

-void __init s3c2443_common_clk_init(struct device_node *np, unsigned long xti_f,

+static void __init s3c2443_common_clk_init(struct device_node *np, unsigned long xti_f,

int current_soc,

void __iomem *base)

{

--

2.7.4

你可以试着用git send-email v1-0001-this-is-my-test.patch --to 将补丁发给Maintainer。记得准备好一个盆子，接大家的口水：）

在制作正确的补丁之前，我们需要这个错误的补丁错在何处：

1、应该将它拆分成三个补丁。

也许这一点值得商酌，因为这三个文件都是同一个驱动：clk: samsung。也许Maintainer认为它是同一个驱动，做成一个补丁也是可以的。

我觉得应该拆分成三个。

当然了，应当以Maintainer的意见为准。不同的Maintainer也许会有不同的意见。

2、补丁描述实在太LOW。

3、补丁格式不正确。

4、补丁内容不正确。

下一节我们逐个解决这几个问题。

但是首先我们应当将补丁回退。使用如下命令：

git reset HEAD~1

5. 五、制作正确的补丁

1、补丁描述

补丁第一行是标题，比较重要。它首先应当是模块名称。

但是我们怎么找到drivers/clk/samsung/clk-s3c2412.c文件属于哪个模块？

可以试试下面这个命令，看看drivers/clk/samsung/clk-s3c2412.c文件的历史补丁：

:/dimsum/git/kernel.next# git log drivers/clk/samsung/clk-s3c2412.c

commit 02c952c8f95fd0adf1835704db95215f57cfc8e6

Author: Martin Kaiser

Date: Wed Jan 25 22:42:25 2017 +0100

clk: samsung: mark s3c...._clk_sleep_init() as __init

ok，模块名称是 “clk: samsung”

下面是我为这个补丁添加的描述，其中第一行是标题：

clk: samsung: mark symbols static where possible for s3c2410

We get 1 warnings when building kernel with W=1:

/dimsum/git/kernel.next/drivers/clk/samsung/clk-s3c2410.c:363:13: warning: no previous prototype for 's3c2410_common_clk_init' [-Wmissing-prototypes]

void __init s3c2410_common_clk_init(struct device_node *np, unsigned long xti_f,

In fact, this function is only used in the file in which they are

declared and don't need a declaration, but can be made static.

So this patch marks these functions with 'static'.

这段描述是我从其他补丁中拷贝出来的，有几下几点需要注意：

1、标题中故意添加了“for s3c2410”，以区别于另外两个补丁

2、“1 warnings”这个单词中，错误的使用了复数，这是因为复制的原因

3、“/dimsum/git/kernel.next/”这个路径名与我的本地路径相关，不应当出现在补丁中。

4、警告描述超过了80个字符，但是这是一个特例，这里允许超过80字符。

这些问题，如果不处理的话，Maintainer会不高兴的！如果Maintainer表示了不满，而你不修正的话，这个补丁就会被忽略。

修正后的补丁描述如下：

clk: samsung: mark symbols static where possible for s3c2410

We get 1 warning when building kernel with W=1:

drivers/clk/samsung/clk-s3c2410.c:363:13: warning: no previous prototype for 's3c2410_common_clk_init' [-Wmissing-prototypes]

void __init s3c2410_common_clk_init(struct device_node *np, unsigned long xti_f,

In fact, this function is only used in the file in which they are

declared and don't need a declaration, but can be made static.

So this patch marks these functions with 'static'.

我们的补丁描述一定要注意用词，不要出现将“unused”写为“no used”这样的错误。

反复使用git add，git commit将补丁提交到git仓库。

终于快成功，是不是想庆祝一下。用git命令看看我们刚才提交的三个补丁：

root@ThinkPad-T440:/dimsum/git/kernel.next# git log drivers/clk/samsung/

commit 0539c5bc17247010d17394b0dc9f788959381c8f

Author: Baoyou Xie

Date: Thu Aug 17 20:43:09 2017 +0800

clk: samsung: mark symbols static where possible for s3c2443

We get 1 warning when building kernel with W=1:

drivers/clk/samsung/clk-s3c2443.c:388:13: warning: no previous prototype for 's3c2443_common_clk_init' [-Wmissing-prototypes]

void __init s3c2443_common_clk_init(struct device_node *np, unsigned long xti_f,

In fact, this function is only used in the file in which they are

declared and don't need a declaration, but can be made static.

So this patch marks these functions with 'static'.

commit c231d40296b4ee4667e3559e34b00f738cae1e58

Author: Baoyou Xie

Date: Thu Aug 17 20:41:38 2017 +0800

clk: samsung: mark symbols static where possible for s3c2412

We get 1 warning when building kernel with W=1:

drivers/clk/samsung/clk-s3c2412.c:254:13: warning: no previous prototype for 's3c2412_common_clk_init' [-Wmissing-prototypes]

void __init s3c2412_common_clk_init(struct device_node *np, unsigned long xti_f,

In fact, this function is only used in the file in which they are

declared and don't need a declaration, but can be made static.

So this patch marks these functions with 'static'.

commit ff8ea5ed4947d9a643a216d51f14f6cb87abcb97

Author: Baoyou Xie

Date: Thu Aug 17 20:40:50 2017 +0800

clk: samsung: mark symbols static where possible for s3c2410

但是，你发现补丁描述里面还有什么不正确的吗？？

不过Maintainer也许发现不了这个问题，然后~~~~然后这个补丁也可能被接收入内核。

下面我们生成补丁：

root@ThinkPad-T440:/dimsum/git/kernel.next# git format-patch -s -3

0001-clk-samsung-mark-symbols-static-where-possible-for-s.patch

0002-clk-samsung-mark-symbols-static-where-possible-for-s.patch

0003-clk-samsung-mark-symbols-static-where-possible-for-s.patch

实际上，我们的补丁仍然是错误的。

在发送补丁前，我们需要用脚本检查一下补丁：

root@ThinkPad-T440:/dimsum/git/kernel.next# ./scripts/checkpatch.pl 000*

---------------------------------------------------------------

0001-clk-samsung-mark-symbols-static-where-possible-for-s.patch

---------------------------------------------------------------

WARNING: Possible unwrapped commit description (prefer a maximum 75 chars per line)

#9:

void __init s3c2410_common_clk_init(struct device_node *np, unsigned long xti_f,

WARNING: line over 80 characters

#29: FILE: drivers/clk/samsung/clk-s3c2410.c:363:

+static void __init s3c2410_common_clk_init(struct device_node *np, unsigned long xti_f,

total: 0 errors, 2 warnings, 8 lines checked

请留意输出警告，其中第一个警告是说我们的描述中，有过长的语句。前面已经提到，这个警告可以忽略。

但是第二个警告告诉我们代码行超过80个字符了。这是不能忽略的警告，必须处理。

使用“git reset HEAD~3”命令将三个补丁回退。重新修改代码：

static void __init s3c2410_common_clk_init(struct device_node *np, unsigned long xti_f,

修改为

static void __init

s3c2410_common_clk_init(struct device_node *np, unsigned long xti_f,

也可以修改为

static void __init s3c2410_common_clk_init(struct device_node *np,

unsigned long xti_f,

我个人习惯用第一种方法，因为看其他代码也是第一种修改方法。

重新提交补丁，并用git format-patch命令生成补丁。

六、发送补丁

生成正确的补丁后，请再次用checkpatch.pl检查补丁正确性。

确保无误后，可以准备将它发送给Maintainer了。

但是应该将补丁发给谁？这可以用get_maintainer.pl来查看：

root@ThinkPad-T440:/dimsum/git/kernel.next# ./scripts/get_maintainer.pl 000*

Kukjin Kim (maintainer:ARM/SAMSUNG EXYNOS ARM ARCHITECTURES)

Krzysztof Kozlowski (maintainer:ARM/SAMSUNG EXYNOS ARM ARCHITECTURES)

Sylwester Nawrocki (supporter:SAMSUNG SOC CLOCK DRIVERS)

Tomasz Figa (supporter:SAMSUNG SOC CLOCK DRIVERS)

Chanwoo Choi (supporter:SAMSUNG SOC CLOCK DRIVERS)

Michael Turquette (maintainer:COMMON CLK FRAMEWORK)

Stephen Boyd (maintainer:COMMON CLK FRAMEWORK)

[e-mail] (moderated list:ARM/SAMSUNG EXYNOS ARM ARCHITECTURES)

[e-mail] (moderated list:ARM/SAMSUNG EXYNOS ARM ARCHITECTURES)

[e-mail] (open list:COMMON CLK FRAMEWORK)

[e-mail] (open list)

接下来，可以用git send-email命令发送补丁了：

git send-email 000* --to [e-mail],[e-mail],[e-mail],[e-mail],[e-mail],[e-mail],[e-mail] --cc ,[e-mail],[e-mail],[e-mail]

注意，哪些人应当作为邮件接收者，哪些人应当作为抄送者。在本例中，补丁是属于实验性质的，可以不抄送给邮件列表帐户。

提醒：你应当将补丁先发给自己，检查无误后再发出去。如果你有朋友在社区有较高的威望，也可以抄送给他，必要的时候，也许他能给你一些帮助。这有助于将补丁顺利的合入社区。

重要提醒：本文讲述的，主要是实验性质的补丁，用于打开社区大门。真正重要的补丁，可能需要经过反复修改，才能合入社区。我知道有一些补丁，超过两年时间都没能合入社区，因为总是有需要完善的地方，也许还涉及一些社区政治：）