HOWTO: Create and submit your first Linux kernel patch using GIT

這個文章用自己第一次提交patch的經曆詳細介紹了用git提交patch的步驟，值得學習。

From : http://linux.koolsolutions.com/2011/02/26/howto-create-and-submit-your-first-linux-kernel-patch/

 

After working with Linux (mostly as an advanced user) for years, I decided to post my first Linux kernel patch (although trivial but hey you need to start somewhere!) and I was thrilled when it first got accepted by the Subsystem maintainer and then ultimately it trickled into mainline kernel.

What follows is a step-by-step guide on how to submit a Linux kernel patch and hope that it gets accepted into the mainline kernel. This HOW-TO is based on an actual patch that I wrote and submitted and which got accepted into mainline kernel yesterday. The guide mostly highlights the mechanics of sending patches and not necessarily technical design aspects of Linux kernel.

Step 1: Install Git Tools

The first thing we need to do is to make sure that we have necessary tools to create and submit our Linux kernel patch. I am using my Debian Lenny system for this HOW-TO.

# apt-get update
# apt-get install git git-email gitk

Additionally it is a good idea to configure some few parameters that Git will use when it generates your patch:

# git config --add user.name "Kushal Koolwal"
# git config --add user.email "kushalkoolwal@gmail.com"

Step 2: Clone Linus’ Git Tree

The next thing you may want to do is to clone Linus’s Git tree preferably on your Linux machine. Make sure you have enough space (at least 2GB) before you clone the tree. At the time of this writing the total size of the tree was around 950+ MB.

debian:~# cd /usr/src/
debian:/usr/src/# git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux-2.6 mylinux-2.6

Now wait for 30 minutes or so, depending on your Internet connection speed, before the entire tree gets downloaded into your directory mylinux-2.6 (directory will be created automatically since you have specified in the command). Any patchwork should always be done against this tree to make sure that your changes might not conflict with changes made by other developers.

debian:/usr/src/# cd mylinux-2.6
debian:/usr/src/mylinux-2.6# ls
arch COPYING  crypto drivers fs init  Kbuild   kernel  MAINTAINERS  mm   README samples  security  tools  virt block  CREDITS  Documentation  firmware  include  ipc   Kconfig  lib  Makefile net  REPORTING-BUGS  scripts  sound     usr
debian:/usr/src/mylinux-2.6#

From here onwards all the work will be done in /usr/src/mylinux-2.6 directory.

Step 3: Now create a local branch to make your changes

By default when you clone the Git tree you are in the master branch.

# git branch
* master
#

The * above indicates your current branch.

Let’s create a new branch my MenlowRebootFix in which we will do our code changes:

# git branch MenlowRebootFix

Then you need to checkout the above newly created branch:

# git checkout MenlowRebootFix

Confirm that you are in the above branch:

# git branch
*MenlowRebootFix
master
#

Step 4: Make your changes

Now I am going to make changes to the arch/x86/kernel/reboot.c file. After you made your changes to the file and saved it give the following command:

# git commit -a

The above command will open a text editor in the same window on your terminal screen (my default text editor is nano) like this:

# Please enter the commit message for your changes. Lines starting
# with '#' will be ignored, and an empty message aborts the commit.
# On branch Test1
# Changes to be committed:
#   (use "git reset HEAD <file>..." to unstage)
#
#       modified:   arch/x86/kernel/reboot.c
#

Now we will enter our commit log message. Be very careful what you type in the log message because these messages will become part of Linux Git tree commit log and people will be searching your commit based on these messages. Here is what I typed in and here is what my final editor window looked it:

x86: Fix reboot problem on VersaLogic Menlow boards
VersaLogic Menlow based boards hang on reboot unless reboot=bios is used. Add quirk to reboot through the BIOS.
Tested on at least four boards.
# Please enter the commit message for your changes. Lines starting
# with '#' will be ignored, and an empty message aborts the commit.
# On branch Test1
# Changes to be committed:
#   (use "git reset HEAD <file>..." to unstage)
#
#       modified:   arch/x86/kernel/reboot.c
#

Now the text in blue color will become your main subject line of the patch that you will email and will also become the identifier in the Git commit log.

Note: It is very important that you first type the name of the subsystem to which your patch belongs to. In my case since I am modifying the reboot.c file in the x86 architecture directory, I begin by subject line with x86:.

After that you need to leave one empty line. and then type a brief description about your change (in maroon color) which will become the changelog of the Git commit log.

Do not worry about the text in orange color that begins with #. Those will be ignored by Git commit.

Note: If you don’t leave one empty line between your subject and description , your description will become part of the subject line and it will be all mess.

Step 5: Generate your patch

So now you have commit your patch in your local Git repository, it is time to generate the patch that we will email to the respective maintainers and mailing lists. To generate patch simply give the following command:

# git format-patch -s -n master..MenlowRebootFix

This should create a file 0001-x86-Fix-reboot-problem-on-VersaLogic-Menlow-boards.patch in your current directory whose content will be:

From 04056e508c996b023857f8076da7fb54096d10e9 Mon Sep 17 00:00:00 2001
From: Kushal Koolwal <kushalkoolwal@gmail.com>
Date: Sat, 19 Feb 2011 13:14:03 -0800
Subject: [PATCH 1/1] x86: Fix reboot problem on VersaLogic Menlow boards.
VersaLogic Menlow based boards hang on reboot unless reboot=bios is used.

Add quirk to reboot through the BIOS.
Tested on at least four boards.

Signed-off-by: Kushal Koolwal <kushalkoolwal@gmail.com>
—
arch/x86/kernel/reboot.c |    8 ++++++++
1 files changed, 8 insertions(+), 0 deletions(-)
diff –git a/arch/x86/kernel/reboot.c b/arch/x86/kernel/reboot.c
index fc7aae1..715037c 100644
— a/arch/x86/kernel/reboot.c
+++ b/arch/x86/kernel/reboot.c
@@ -285,6 +285,14 @@ static struct dmi_system_id __initdata reboot_dmi_table[] = {
DMI_MATCH(DMI_BOARD_NAME, “P4S800″),
},
},
+       {       /* Handle problems with rebooting on VersaLogic Menlow boards */
+               .callback = set_bios_reboot,
+               .ident = “VersaLogic Menlow based board”,
+               .matches = {
+                       DMI_MATCH(DMI_BOARD_VENDOR, “VersaLogic Corporation”),
+                       DMI_MATCH(DMI_BOARD_NAME, “VersaLogic Menlow board”),
+               },
+       },
{ }
};
–
1.7.2.3

Note how the name of the file was picked from your first line of the Git commit log. Also the option -n adds the patch number [PATCH 1/1] to your subject and the -s option adds the Signed-off-by: line. The email that is picked in the signed off line is picked from your Git’s configuration that you set in Step 1.

Step 6: Check your patch for errors

Next we need to make sure that the patch we are trying to submit does not contain any obvious errors like white spaces, exceeding 80 column limit, etc. There is a perl script called checkpath.pl that is provided with the kernel sources for this purpose:

# scripts/checkpatch.pl 0001-x86-Fix-reboot-problem-on-VersaLogic-Menlow-boards.patch

and you should see something like this:

Output:

total: 0 errors, 0 warnings, 14 lines checked
0001-x86-Fix-reboot-problem-on-VersaLogic-Menlow-boards.patch has no obvious style problems and is ready for submission.

There are other scripts also provided inside the kernel source to fix/clean your patch like:

scripts/cleanfile
scripts/cleanpatch

Step 7: Test your patch

Again it is very important that you apply your patch to the Linus’ Git tree, compile it and test it before sending your patch upstream.

# git checkout master
# patch -p1 0001-x86-Fix-reboot-problem-on-VersaLogic-Menlow-boards.patch
# make-kpkg --append-to-version=test-patch kernel_image kernel_headers

Step 8: Get the list of people to submit patch to

Assuming your patch compiled, worked the way you want it to and your test emails looked good the next step is to get the list of concern people to whom you should email your patch. There are two methods to do that:

Method 1: Use the script provided in the kernel source

# scripts/get_maintainer.pl 0001-x86-Fix-reboot-problem-on-VersaLogic-Menlow-boards.patch

Output:

Thomas Gleixner <tglx@linutronix.de> (maintainer:X86 ARCHITECTURE...)
Ingo Molnar <mingo@redhat.com> (maintainer:X86 ARCHITECTURE...,commit_signer:5/8=62%)
"H. Peter Anvin" <hpa@zytor.com> (maintainer:X86 ARCHITECTURE...,commit_signer:3/8=38%)
x86@kernel.org (maintainer:X86 ARCHITECTURE...)
Don Zickus <dzickus@redhat.com> (commit_signer:2/8=25%)
Peter Zijlstra <a.p.zijlstra@chello.nl> (commit_signer:2/8=25%)
Borislav Petkov <bp@alien8.de> (commit_signer:1/8=12%)
linux-kernel@vger.kernel.org (open list)
#

Method 2: Refer to the MAINTAINERS file

The other method is to refer to the MAINTAINERS file that is provide inside the kernel source tree. You need to at least email your patch to all of the people who have “M” before their name.

Note: Also you need to email your patch to at least one mailing list. If you are not able find any mailing list, based on the above two methods, that is concerned with the subsystem against which you are trying to submit your patch, then you should at least email to Linux Kernel Mailing List (linux-kernel@vger.kernel.org).

Step 9: Test Email your patch

Although you could use any email client and SMTP host that you want and have access to, I found that using Gmail was the best since a lot of kernel developers use that. Now it is very important that you first test your patch by sending it your own email addresses (possible different email account with different mail providers). I use the following:

git send-email --smtp-encryption=tls --smtp-server=smtp.gmail.com --smtp-user=kushalkoolwal@gmail.com --smtp-server-port=587 --to "KKoolwal <myname@koolsolutions.com>" --to "Kushal Koolwal <myname@yahoo.com>" --cc "KK <myname@hotmail.com>" 0001-x86-Fix-reboot-problem-on-VersaLogic-Menlow-boards.patch

After you hit enter, it will ask for your Gmail account password which you need to enter in order to actually send the email.

Now check email accounts listed above to verify if you got the email and everything looks good for submission.

Step 10: Finally Email your patch

If everything looks right then you finally email your patch based on the list of people you found in Step 8. This is what I actually ended up using:

# git send-email --smtp-encryption=tls --smtp-server=smtp.gmail.com --smtp-user=kushalkoolwal@gmail.com --smtp-server-port=587 --from "Kushal Koolwal <kushalkoolwal@gmail.com>" --to "Thomas Gleixner <tglx@linutronix.de>" --to "Ingo Molnar <mingo@redhat.com>" --to "H. Peter Anvin <hpa@zytor.com>" --to "x86@kernel.org" --cc "linux-kernel@vger.kernel.org" 0001-x86-Fix-reboot-problem-on-VersaLogic-Menlow-boards.patch

Here is that commit log of the acceptance of my patch by Ingo Molnar which then trickled from Ingo Molnar’s tree to Stephen Rothwell’s  linux-next tree and finally into Linus Torvald’s mainline Linux kernel tree.

That’s it! Good luck with your first patch!