brunobraga.net: First Kernel Patch

First Kernel Patch

posted Oct 25, 2009 4:21 AM by Bruno Braga [ updated Oct 25, 2009 6:22 AM ]

This is interesting topic I would like to share.

Recently, I participated on the 1st Japan Linux Symposium, held in Tokyo last week, and I could meet many amazing people from the Linux movement. One of them was Greg Kroah, who is currently one of the top maintainers of the Linux Kernel, working closely to Linus Torvalds.

His presentation was about "Write & Submit Your First Linux Kernel Patch", and gave me insights that it is easier to participate than anyone thinks. Of course, you gotta clean out a lot of toilets until you get somewhat noticed, but at least I could grasp that it is not so difficult as it seems.

Of course, Greg helped a lot (thanks) to incentive everyone to participate. Not all open source communities are like that, a kind of pride thing and inner-circle closed (which, IMO, goes against the OS principle, but I agree that some level of control is required to avoid chaos). Well, the differences happen a lot in the Kernel as well (you can see some here), some getting even too intense, but in general the community is pretty opened to newcomers.

Well, anyway, during the 45min lesson with him, plus a little (hours) of search on the web, I could finally place my first contribution (yet to be accepted to the main tree though): http://patchwork.kernel.org/patch/55147/

So I will document here my steps (you can also see similar stuff from here and here).

The official presentation and guidelines from Greg are available at: http://github.com/gregkh/kernel-tutorial

1) Kernel Source code

Follow the steps below for starting to work on the kernel source code:

# get the kernel source code
$ git clone git://github.com/github/linux-2.6.git
$ cd linux-2.6

# create a git branch "tutorial" for you to work on (it is not recommended to work on the master)
$ git checkout -f -b tutorial

2) Updating the source code

The example below was based on the "homework" given to me to work with. I suppose that anyone can start from the staging drivers, which is a part of the Kernel source code that is not officially accepted, so it should cause no big trouble to other modules or the core code.

# check the file consistency (Greg gave us a particular driver on staging drivers to fix coding style) - you can search yourself for other files with issues
$ ./scripts/checkpatch.pl --file drivers/staging/comedi/drivers/adl_pci8164.c

# -----------------------
# the result should be something like:

WARNING: printk() should include KERN_ facility level
#131: FILE: staging/comedi/drivers/adl_pci8164.c:131:
+ printk("comedi: attempt to attach...\n");
[...]
total: 0 errors, 10 warnings, 391 lines checked

The checkpatch.pl script is amazing, as it shows which consistency errors and warnings should be treated in the code. This also serves as guidelines for starters such as myself to get used to the coding style of the Kernel, and what you should pay attention to when developing things from scratch.

Once you do your changes, you do the check again:

# check the file consistency again (until there are no errors//warnings)
$ ./scripts/checkpatch.pl --file drivers/staging/comedi/drivers/adl_pci8164.c

# -----------------------
# the result should be something like:

total: 0 errors, 0 warnings, 392 lines checked
drivers/staging/comedi/drivers/adl_pci8164.c has no obvious style problems and is ready for submission.

Don't forget to compile the kernel or module where you changed, otherwise you will make a lot of people angry later... This part was a little bit tricky for me (although others did not face the same problem).

# re-compile the kernel to make sure everything is fine (but only partial, that will be more than enough for this exercise)
$ make M=drivers/staging/comedi/drivers/

If you have problems here, try to look for examples on "make menuconfig" and MakeFiles.

3) Patching

When your changes are ready to be patched, you can then commit them to your git branch:

# commit your changes to your git branch
$ git commit -a
# This action will open the VI editor (in Ubuntu is set by default - search the web if you need to manually define one), so that you can place the commit message (what is your change about).

# prepare the patch for the changes you've made
$ git format-patch -s -n master..tutorial

# this action will create a patch file, with name based on the commit message you wrote before.
# -----------------------
# the result should be something like:

0001-Corrected-coding-style-excessive-curly-braces-and-p.patch

# check the file consistency for the patch
$ ./scripts/checkpatch.pl --file 0001-Corrected-coding-style-excessive-curly-braces-and-p.patch

# -----------------------
# the result should be something like:

total: 0 errors, 0 warnings, 126 lines checked
0001-Corrected-coding-style-excessive-curly-braces-and-p.patch has no obvious style problems and is ready for submission.

I found some articles informing ways to add the "Sign-off" automatically, by updating the mains bash script (~/.bashrc). This did not work for me very good. So what I did was to update the git configuration myself, for the current clone:

# commit your changes to your git branch
$ git config -a

# define special configuration
# see details below on msmtp
$ git config --add sendemail.smtpserver /usr/bin/msmtp
$ git config --add user.name "BRAGA, Bruno"
$ git config --add user.email bruno.braga@gmail.com

# my git configuration is:
$ git config --list
# ---------------

sendemail.smtpserver=/usr/bin/msmtp
core.repositoryformatversion=0
core.filemode=true
core.bare=false
core.logallrefupdates=true
remote.origin.url=git://github.com/github/linux-2.6.git
remote.origin.fetch=+refs/heads/*:refs/remotes/origin/*
branch.master.remote=origin
branch.master.merge=refs/heads/master
user.name=BRAGA, Bruno
user.email=bruno.braga@gmail.com

# ---------------

# use --global if you want those settings to be default for any git clone.

Lastly, you need to send the patch to the maintainers and the mailing list:

# send the email using git functionality
$ git send-email --from "BRAGA, Bruno <bruno.braga@gmail.com>" --to "LKML <linux-kernel@vger.kernel.org>" --cc "Greg Kroah <greg@kroah.com>" 0001-Corrected-coding-style-excessive-curly-braces-and-p.patch

Here there is another trick. To use the "git send-email" tool, actually you need to define a mailing tool and the SMTP settings for it. I've seen that people is mainly using msmtp tool for that, so I decided to go the same way. So here is what I did:

# install msmtp
$ sudo apt-get install msmtp

# configure msmtp
$ vim ~/.msmtprc

# this will open the VI editor (you can use another one if you like), then you add the settings:
# --------------

account default
host smtp.gmail.com
port 587
auth on
user {your account name here}@gmail.com
password {your password here}
tls on
tls_starttls on
tls_trust_file ~/.certs/Thawte_Premium_Server_CA.pem
from {your account name here}@gmail.com

# --------------

# since you NEED to leave your password as text on this file, it is recommended to change the permissions (default permissions allow everyone to see this file):
$ chmod 600 ~/.msmtprc

# the job here is not finished, as you need to leave the Thawte certificate file on the defined address. So here is how you do it:

# download the certificates (Verisign offers that)
$ wget https://www.verisign.com/support/thawte-roots.zip

# unpack the files (I recommend doing that on /tmp/ folder)
$ unzip thawte-roots.zip

# go to the folder where you need to get the certificate (this may vary a little bit on time, but you can just look for it within the contents downloaded)
$ cd Thawte SSLWeb Server Roots/thawte Premium Server CA/

# create the certificate directory if you don't have one
$ mkdir ~/.certs

# copy and properly rename it (remove spaces is good one)
$ cp Thawte Premium Server CA.pem ~/.certs/Thawte_Premium_Server_CA.pem

If you have issues with the msmtp, see other posts, such as in here.

Done!

Not that difficult, huh? Of course, first patch experience is mere fixing code formatting and style, but it is a starting point, and you should be proud to participate. Greg himself told that his first patches were similar stuff, and even the almighty Googlers' (Google employees) contributions are partially english spelling fixes (you can see statistics at Greg Kroah Hartman on the Linux Kernel 28:00 - I am serious!)... So, what are you waiting for?