Create and submit your first Linux kernel patch using GIT

ezeke

　　参考资料：

• 　　How to Participate in the Linux Community http://www.linuxfoundation.org/content/how-participate-linux-community
  
• 　　Kernel Documents目录下的相关文档，例如：Changes, CodingStyle, development-process, HOWTO, SubmitChecklist, SubmittingDrivers, SubmittingPatches 等等
  
• 　　HOWTO: Create and submit your first Linux kernel patch using GIT  http://linux.koolsolutions.com/2011/02/26/howto-create-and-submit-your-first-linux-kernel-patch/
  
• 　　Hacking Linux Kernel
  

　　HOWTO: Create and submit your first Linux kernel patch using GIT
　　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>　　# 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>　　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 ..." 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 …” 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>　　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
　　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
　　—
　　 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  (maintainer:X86 ARCHITECTURE...)
　　Ingo Molnar  (maintainer:X86 ARCHITECTURE...,commit_signer:5/8=62%)
　　&quot;H. Peter Anvin&quot;  (maintainer:X86 ARCHITECTURE...,commit_signer:3/8=38%)
　　x86@kernel.org (maintainer:X86 ARCHITECTURE...)
　　Don Zickus  (commit_signer:2/8=25%)
　　Peter Zijlstra  (commit_signer:2/8=25%)
　　Borislav Petkov  (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 &quot;KKoolwal &quot; --to &quot;Kushal Koolwal &quot; --cc &quot;KK &quot; 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 &quot;Kushal Koolwal &quot; --to &quot;Thomas Gleixner &quot; --to &quot;Ingo Molnar &quot; --to &quot;H. Peter Anvin &quot; --to &quot;x86@kernel.org&quot; --cc &quot;linux-kernel@vger.kernel.org&quot; 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!