NOTE: This HOW TO is still in progress. Please do
      not follow it for now.  Check back later for
      a more complete version.

Linux kernel development can be a very confusing process for the uninitiated. It actually makes a lot of sense once you understand it, but there is a bit of a learning curve. Unfortunately, this means that a lot of people who might be willing to test and debug kernel modules simply do not know how to help.

This HOW TO documents my personal experiences in getting to know how I could contribute to the development of a particular kernel module through testing. (The module in question is bcm43xx, but I am attempting to keep this guide more general. However, I will use bcm43xx as an example in many cases.) This involved several steps, which I describe here.

First of all, this guide is being written by a fellow mere mortal. I am not a kernel developer. I have done a small amount of programming at the kernel level, mostly for learning purposes, but never on anything that has been proposed or contributed to the actual Linux kernel.

The main reason why non-kernel-programmers might be interested in this guide is that often people buy new hardware and then find that not all of it works as expected under Linux. This is especially the case with laptops, where the user usually has little choice about the individual components. In my case, I recently bought an HP laptop because it had exactly the specs I was looking for (dual-core Turion 64-bit processor, 1GB of memory, etc.), but then found that the wireless card was an unsupported variety of the Broadcom PCI-Express line. A percentage of those people, like myself, will decide that, rather than giving up, they'd like to know how they can help to get it working.

However, because of the highly distributed nature of Linux development, it can actually take some work just to figure out how to offer help.

In fact, I encourage you not to be shy. In most cases, the kernel developers want your help. Usually there are different varieties of the hardware that they are developing for. Sometimes they do not have the particular version of the chipset that is in your computer, or you have some unique combination of hardware the creates a conflict that they didn't know about. The more information the developers have on different hardware configurations, the better their driver will be.

.. describe branches and Git here.

Although many kernel modules have been incorporated into the “main branch”, and then eventually propagated to the rest of the kernel tree, there are always several kernel drivers that are under development. This is usually true for newer hardware, or hardware for which few specs are available, so that good reverse-engineering is a long process.

Consequently, there is almost always a core mailing list used for discussion among the main developers of the module. (In general, there is more than one developer.) Sometimes, there is also a message forum, though often message forums are specific to a distro rather than being the actual meeting place for the module developers.

So, the first thing to do is to figure out where the actual developers “hang out” and where they keep their resources. This isn't always obvious: for instance, the bcm43xx specs are kept here, while there is a dedicated forum here. That forum has a link to “daily snapshots” here, but it currently gives a 404 error. In actual fact, I eventually discovered that they keep a mailing list here, which is the real place where patches tend to get posted and useful communication happens.

Now, I'm not trying to pick on bcm43xx, but this was far from obvious to me. I now know that it's often a good idea to specifically look for a “development” mailing list. Usually this is the name of the module (bcm43xx) with ”-dev” or ”-devel” appended to it (bcm43xx-dev). Entering that into Google gets the correct mailing list as the first hit.

Once I joined the correct mailing list, I started getting useful information about the bleeding-edge versions of the kernel module in question, and I was able to start applying patches and reporting my results.

As I described earlier, the kernel development process is split into many branches. In fact, each developer has his own branch of the kernel. If he is developing publicly, you may wish to test directly on his version. In other cases, he will keep his version private, but will be posting patches for testing on some public branch. In the bcm43xx case, a lot of development is happening against the “wireless-2.6” branch, so that is what I am currently using for my contributions.

To find out what is most appropriate, don't be shy: Ask. Post a polite message saying, excuse me, what is the best way I can help test? Which kernel tree should I use? If you are testing against a different tree than the developer, you are likely to run into trouble. Patches won't apply properly, or you will not have up-to-date code, and your reports will be generally unhelpful. So make sure you are set up correctly for testing.

By the way, all the kernel branches hosted on kernel.org a are listed here. As you can see, there are quite a few, so choosing the right one is essential.

No two ways about it, Git is an extremely complicated (but powerful) system. There is a somewhat more user-friendly “wrapper” for Git called Cogito. I suggest using it. Changes are very high that it is available in your distro's repository, so use your package manager to download and install it.

By now, you should know the URL of the Git repository you'd like to be testing. You must use Cogito to “clone” it, which means you are making a copy of it on your harddrive, and you are making a local repository so that you can easily undo any changes you make. Here, I will use the “wireless-2.6” kernel tree as an example.

From the list of kernel branches, I can see that “linville/wireless-2.6” is listed about half-way down the page. On the right side of the page there is a few very small links, summary, shortlog, log, tree, git. The git link points to “git:git.kernel.org/pub/scm/linux/kernel/git/linville/wireless-2.6.git”, so I will use Cogito to clone it: cg-clone git:git.kernel.org/pub/scm/linux/kernel/git/linville/wireless-2.6.git

This may take a while, so be patient. It will create a folder in the current directory called “wireless-2.6”. Once it is finished, try compiling the kernel. I won't describe this process here, because there are plenty of good tutorials on how to do it. Here's one, for example. Don't forget to select the kernel options that enable the particular module you are testing!