: How to be a kernel driver maintainer
PATCH 1/1 : How to be a kernel driver maintainer
Since this discussion of getting driver authors to submit their driver for inclusion I started writing a document to send them. I think it's best included in the kernel tree.
Documentation/HOWTO-KernelMaintainer new file +150 -0
@@ -0,0 +1,150 @@ + How to be a kernel driver maintainer + ------------------------------------ + + +This document explains what you must know before becoming the maintainer +of a portion of the Linux kernel. Please read SubmittingPatches and +SubmittingDrivers and CodingStyle, also in the Documentation/ directory. + + +Why should I submit my driver? +------------------------------ + +This is often the the question a driver maintainer is faced with. Most +driver authors really don't see the benefit of having their code in the +main kernel. + +The primary benefit is availability. When people want to compile a kernel, +they want to have everything there in the kernel tree. No one (not even +kernel developers) likes having to search for, download, and build +external drivers out-of-tree (outside the stock kernel source). It's often +difficult to find the right driver (one known to work correctly), and is +even harder to find one that works on the kernel version they are +building. + +The benefit to users compiling their own kernel is immense. The benefit to +distributions is even greater. Linux distributions already have a large +amount of work to provide a kernel that works for most users. If a driver +has to be provided for users that isn't in the primary kernel source, it +adds additional work to maintaining (tracking the external driver, +patching it into the build system, often times fixing build problems). +With a driver in the kernel source, it's as simple as tracking the main +kernel tree. + +This assumes that the distribution finds your driver worth the time of +doing all this. If they don't, then the few users needing your driver will +probably never get it (since most users are not capable of compiling their +own modules). + +Having drivers in the main kernel tree benefits everyone. + + +What should I do to prepare for code submission? +------------------------------------------------ + +First you need to inspect your code and make sure it meets criteria for +inclusion. Read Documentation/CodingStyle for help on proper coding format +(indentation, comment style, etc). + +Once you have properly formatted the code, you also need to check a few +other areas. Most drivers include backward compatibility for older kernels +(usually ifdef's with LINUX_VERSION_CODE). This backward compatibility +needs to be removed. It's considered a waste of code for the driver to be +backward compatible within the kernel source tree, since it is going to be +compiled with a known version of the kernel. + +Proper location in the kernel source needs to be determined. Find drivers +similar to yours, and use the same location. For example, USB network +drivers go in drivers/usb/net/, and filesystems go in fs/. + +The driver should then be prepared for building from the main source tree +in this location. A proper Makefile and Kconfig file in the Kbuild format +should be provided. Most times it is enough to just add your entries to +existing files. Here are some good rules to follow: + + - If your driver is a single source file (or single .c with a single .h), + then it's typical to place the driver in an existing directory. Also, + modify existing Makefile/Kconfig for that directory. + + - If your driver is made up of several source files, then it is typical + to create a subdirectory for it under the existing directory where it + applies. Separate Makefile should be included, with a reference in the + above Makefile to make sure to descend into the one you created. + + + In this case, it is usually still correct to just add the Kconfig + entry to the existing one. Unless your driver has 2 or more config + options (debug options, extra features, etc), then creating a + standalone Kconfig may be best. Make sure to source this new Kconfig + from the parent directory. + +Lastly, you'll need to create an entry in the MAINTAINERS file. It should +reference you or the team responsible for the code being submitted (this +should be the same person/team submitting the code). + + +Code review +----------- + +Once your patches are ready, you can submit them to the linux-kernel +mailing list. However, since most drivers fall under some subsystem (net, +usb, etc), then it is often required that you also Cc the mailing list for +this subsystem (see MAINTAINERS file for help finding the correct +address). + +The code review process is there for two reasons. First, it ensures that +only good code, that follows current API's and coding practices, gets into +the kernel. The kernel developers know you have good intentions of +maintaining your driver, but too often a driver is submitted to the +kernel, and some time later becomes unmaintained. Then developers who are +not familiar with the code or it's purpose are left with keeping it +compiling and working. So the code needs to be readable, and easily +modified. + +Secondly, the code review helps you to make your driver better. The folks +looking at your code have been doing Linux kernel work for years, and are +intimately familiar with all the nuances of the code. They can help with +locking issues as well as big-endian/little-endian and 64-bit portability. + +Be prepared to take some heavy criticism. It's very rare than anyone comes +out of this process without a scratch. Usually code review takes several +tries. You'll need to follow the suggested changes, and make them to your +code. Once you've made the changes required, resubmit. Try not to take it +personally. The suggestions are meant to help you, your code, and your +users (and is often times seen as a right of passage). + + +What is expected of me after my driver is accepted? +--------------------------------------------------- + +The real work of maintainership begins after your code is in the tree. +This is where some maintainers fail, and is the reason the kernel +developers are so reluctant to allow new drivers into the main tree. + +There are two aspects of maintaining your driver in the kernel tree. The +obvious first duty is to keep your code synced to the kernel source. This +means submitting regular patch updates to the linux-kernel mailing list +and to the particular tree maintainer (e.g. Linus or Andrew). Now that +your code is included and properly styled and coded (with that shiny new +driver smell), it should be fairly easy to keep it that way. + +The other side of the coin is keeping changes in the kernel synced to your +code. Often times, it is necessary to change a kernel API (driver model, +USB stack changes, networking subsystem change, etc). These sorts of +changes usually affect a large number of drivers. It is not feasible for +these changes to be individually submitted to the driver maintainers. So +instead, the changes are made together in the kernel tree. If your driver +is affected, you are expected to pick up these changes and merge them with +your primary code (e.g. if you have a CVS repo for maintaining your code). +Usually this job is made easier if you use the same source control system +that the kernel maintainers use (currently, git), but this is not +required. + +There are times where changes to your driver may happen that are not the +API type of changes described above. A user of your driver may submit a +patch directly to Linus to fix an obvious bug in the code. Sometimes these +trivial and obvious patches will be accepted without feedback from the +driver maintainer. Don't take this personally. We're all in this together. +Just pick up the change and keep in sync with it. If you think the change +was incorrect, try to find the mailing list thread or log comments +regarding the change to see what was going on. Then email the patch author +about the change to start discussion.
Signature · 3 lines
Ben Collins <[email protected]> Developer Ubuntu Linux
Quoted 18 lines · Ben Collins
+The other side of the coin is keeping changes in the kernel synced to your
+code. Often times, it is necessary to change a kernel API (driver model,(quoted diff) +2
-0+USB stack changes, networking subsystem change, etc). These sorts of +changes usually affect a large number of drivers. It is not feasiblefor
+these changes to be individually submitted to the driver maintainers. So
+instead, the changes are made together in the kernel tree. If your driver
+is affected, you are expected to pick up these changes and merge them with
+your primary code (e.g. if you have a CVS repo for maintaining your code).
+Usually this job is made easier if you use the same source control system
Documentation/HOWTO-KernelMaintainer line 140
Quoted 2 lines
Documentation/HOWTO-KernelMaintainer new file +2
-0+that the kernel maintainers use (currently, git), but this is not +required.
I don't quite agree with this part. This encourages cvs use, and "cvs mentality". I *much* rather have something written as "the primary location of your driver becomes the kernel.org git tree. This may feel like you're giving away control, but it's not really. If you maintain your driver there, people will still send patches via you for approval/review. Of course you can keep a master copy in your own version control repository, however be aware that most users will see the kernel.org tree one as THE drivers. In addition, merging changes and keeping uptodate is a lot harder that way. And worse, keeping the "main" version outside the kernel.org tree tends to cause huge deviations and backlogs between your main tree and the "real" kernel.org tree, with the result that it becomes impossible to find regressions when you DO merge the changes over.
Quoted 27 lines · Arjan van de Ven
Quoted 18 lines · Ben Collins
+The other side of the coin is keeping changes in the kernel synced to your
+code. Often times, it is necessary to change a kernel API (driver model,(quoted diff) +2
-0+USB stack changes, networking subsystem change, etc). These sorts of +changes usually affect a large number of drivers. It is not feasiblefor
+these changes to be individually submitted to the driver maintainers. So
+instead, the changes are made together in the kernel tree. If your driver
+is affected, you are expected to pick up these changes and merge them with
+your primary code (e.g. if you have a CVS repo for maintaining your code).
+Usually this job is made easier if you use the same source control systemDocumentation/HOWTO-KernelMaintainer line 140
Quoted 2 lines
Documentation/HOWTO-KernelMaintainer new file +2
-0+that the kernel maintainers use (currently, git), but this is not +required.I don't quite agree with this part. This encourages cvs use, and "cvs mentality". I *much* rather have something written as "the primary location of your driver becomes the kernel.org git tree. This may feel like you're giving away control, but it's not really. If you maintain your driver there, people will still send patches via you for
Quoted 8 lines
approval/review. Of course you can keep a master copy in your own version control repository, however be aware that most users will see the kernel.org tree one as THE drivers. In addition, merging changes and keeping uptodate is a lot harder that way. And worse, keeping the "main" version outside the kernel.org tree tends to cause huge deviations and backlogs between your main tree and the "real" kernel.org tree, with the result that it becomes impossible to find regressions when you DO merge the changes over.
But this isn't at al true. Almost all subsystems maintain the primary tree outside of the kernel, with the kernel being the primary _stable_ tree. USB, Netdev, Alsa, etc. All changes go someplace else before being pushed to the primary kernel tree. 99% of the time, patches are going somewhere else before going into the main kernel. So the above paragraphs is really misleading.
Signature · 3 lines
Ben Collins <[email protected]> Developer Ubuntu Linux
Quoted 4 lines
But this isn't at al true. Almost all subsystems maintain the primary tree outside of the kernel, with the kernel being the primary _stable_ tree. USB, Netdev,
patches yes. but usually only small stuff
Quoted 3 lines
Alsa, etc. All changes go someplace else before being
pushed to the primary kernel tree. 99% of the time, patches are going somewhere else before going into the main kernel.
that's different... that's a patch queue. That's not the same as being the prime repository.
Quoted 2 lines
So the above
paragraphs is really misleading.
I guess neither is good then. I certainly would absolutely not want to encourage developers to have a main "real driver" outside the kernel source. Linus calls that "the cvs mentality" and time after time that has proven to be really bad. You mention alsa, and to some degree alsa is suffering from this ;(
(this is different from net/usb/scsi where changes are queued but merged regularly and near immediately in case of bugfixes, unlike things like alsa and firewire where basically the only choice is "all or nothing" where "all" is bugfixes and new bugs)
Quoted 4 lines · Arjan van de Ven
Quoted 3 lines
But this isn't at al true. Almost all subsystems maintain the primary tree outside of the kernel, with the kernel being the primary _stable_ tree. USB, Netdev,
Quoted 8 lines
patches yes. but usually only small stuff
Quoted 3 lines
Alsa, etc. All changes go someplace else before being
pushed to the primary kernel tree. 99% of the time, patches are going somewhere else before going into the main kernel.that's different... that's a patch queue. That's not the same as being the prime repository.
this deserves expanding.
What net/usb/scsi queue is *deltas* to the kernel.org kernel. This is fundamentally different from having the main driver be in its own repository. Each delta is meant to do a certain change to the driver, eg it's a CHANGE BASED thing. While "own repository" is "here is new code" (even though you can disguise it as changes pretty well). The linux development model is based on introducing changes, not on introducing new code (of course the difference goes away if you introduce a new driver, but that's a corner case)
The result is also highly different. In the net/usb/scsi case, there is no "we need to move changes in mainline to our tree or they get lost". The only thing needed would be resolving conflicts in the proposed changes in the subsystem maintainers queue and the changes already in mainline.
Note: this is independent of what kind of tool is used to store and distribute such changes. quilt and git are used most, but git can also be used in a CVS way if you want. But it's the "the main driver is in the kernel, and we have proposed improvements to it" that counts (versus "we have the main driver that we push to the kernel occasionally if we feel like it").
PATCH 1/1 : How to be a kernel driver maintainer
In reply to Ben CollinsHere's an updated document. I integrated the suggestions. For Arjan, I added a new section at the end. Hopefully that addresses the concerns for cvs-mentality.
Documentation/HOWTO-KernelMaintainer new file +206 -0
@@ -0,0 +1,206 @@ + How to be a kernel driver maintainer + ------------------------------------ + + +This document explains what you must know before becoming the maintainer +of a portion of the Linux kernel. Please read SubmittingPatches, +SubmittingDrivers and CodingStyle, also in the Documentation/ directory. + +With the large amount of hardware available for Linux, it's becoming +increasingly common for drivers for new or rare hardware to be maintained +outside of the main kernel tree. Usually these drivers end up in the +kernel tree once they are stable, but many times users and distribution +maintainers are left with collecting these external drivers in order to +support the required hardware. + +The purpose of this document is to provide information for the authors of +these drivers to eventually have their code in the mainline kernel tree. + + +Why should I submit my driver? +------------------------------ + +This is often the question a driver maintainer is faced with. Most driver +authors really don't see the benefit of having their code in the main +kernel. Some even see it as giving up control of their code. This is +simply not the case, and then end result is always beneficial to users and +developers alike. + +The primary benefit is availability. When people want to compile a kernel, +they want to have everything there in the kernel tree. No one (not even +kernel developers) likes having to search for, download, and build +external drivers out-of-tree (outside the stock kernel source). It's often +difficult to find the right driver (one known to work correctly), and is +even harder to find one that works on the kernel version they are +building. + +The benefit to users compiling their own kernel is immense. The benefit to +distributions is even greater. Linux distributions already have a large +amount of work to provide a kernel that works for most users. If a driver +has to be provided for users that isn't in the primary kernel source, it +adds additional work to maintaining (tracking the external driver, +patching it into the build system, often times fixing build problems). +With a driver in the kernel source, it's as simple as tracking the main +kernel tree. + +This assumes that the distribution finds your driver worth the time of +doing all this. If they don't, then the few users needing your driver will +probably never get it (since most users are not capable of compiling their +own modules). + +Another benefit of having the driver in the kernel tree is to promote the +hardware that it supports. Many companies who have written drivers for +their hardware to run under Linux have not yet taken the leap to placing +the driver in the main kernel. The "Old Way" of providing downloadable +drivers doesn't work as well for Linux, since it's almost impossible to +provide pre-compiled versions for any given system. Having the driver in +the kernel tree means it will always be available. It also means that +users wishing to purchase hardware that "Just Works" with Linux will have +more options. A well written and stable driver is a good reason for a user +to choose that particular type of hardware. + +Having drivers in the main kernel tree benefits everyone. + + +What should I do to prepare for code submission? +------------------------------------------------ + +First you need to inspect your code and make sure it meets criteria for +inclusion. Read Documentation/CodingStyle for help on proper coding format +(indentation, comment style, etc). It is strongly suggested that your +driver builds cleanly when checked by the "sparse" tool. You will probably +need to annotate the driver so sparse can tell that it is following the +kernel's rules for address space accesses and endianness. Adding these +annotations is a simple, but time-consuming, operation that often exposes +real portability problems in drivers. + +Once you have properly formatted the code, you also need to check a few +other areas. Most drivers include backward compatibility for older kernels +(usually ifdef's with LINUX_VERSION_CODE). This backward compatibility +needs to be removed. It's considered a waste of code for the driver to be +backward compatible within the kernel source tree, since it is going to be +compiled with a known version of the kernel. + +Proper location in the kernel source needs to be determined. Find drivers +similar to yours, and use the same location. For example, USB network +drivers go in drivers/usb/net/, and filesystems go in fs/. + +The driver should then be prepared for building from the main source tree +in this location. A proper Makefile and Kconfig file in the Kbuild format +should be provided. Most times it is enough to just add your entries to +existing files. Here are some good rules to follow: + + - If your driver is a single source file (or single .c with a single .h), + then it's typical to place the driver in an existing directory. Also, + modify existing Makefile/Kconfig for that directory. + + - If your driver is made up of several source files, then it is typical + to create a subdirectory for it under the existing directory where it + applies. Separate Makefile should be included, with a reference in the + parent Makefile to make sure to descend into the one you created. + + + In this case, it is usually still correct to just add the Kconfig + entry to the existing one. Unless your driver has 2 or more config + options (debug options, extra features, etc), then creating a + standalone Kconfig may be best. Make sure to source this new Kconfig + from the parent directory. + + - When creating the Kconfig entries be sure to keep in mind the criteria + for the driver to be build. For example, a wireless network driver may + need to "depend on NET && IEEE80211". Also, if you driver is specific + to a certain architecture, be sure the Kconfig entry reflects this. DO + NOT force your driver to a specific architecture simply because the + driver is not written portably. + +Lastly, you'll need to create an entry in the MAINTAINERS file. It should +reference you or the team responsible for the code being submitted (this +should be the same person/team submitting the code). + + +Code review +----------- + +Once your patches are ready, you can submit them to the linux-kernel +mailing list. However, since most drivers fall under some subsystem (net, +usb, etc), then it is often required that you also Cc the mailing list for +this subsystem (see MAINTAINERS file for help finding the correct +address). + +The code review process is there for two reasons. First, it ensures that +only good code, that follows current API's and coding practices, gets into +the kernel. The kernel developers know you have good intentions of +maintaining your driver, but too often a driver is submitted to the +kernel, and some time later becomes unmaintained. Then developers who are +not familiar with the code or it's purpose are left with keeping it +compiling and working. So the code needs to be readable, and easily +modified. + +Secondly, the code review helps you to make your driver better. The folks +looking at your code have been doing Linux kernel work for years, and are +intimately familiar with all the nuances of the code. They can help with +locking issues as well as big-endian/little-endian and 64-bit portability. + +Be prepared to take some heavy criticism. It's very rare that anyone comes +out of this process without a scratch. Usually code review takes several +tries. You'll need to follow the suggested changes, and make these to your +code, or have clear, acceptable reasons for *not* following the +suggestions. Code reviewers are generally receptive to reasoned argument. +If you do not follow a reviewer's initial suggestions, you should add +descriptive comments to the appropriate parts of the driver, so that +future contributors can understand why things are in a possibly unexpected +state. Once you've made the changes required, resubmit. Try not to take it +personally. The suggestions are meant to help you, your code, and your +users (and is often times seen as a rite of passage). + + +What is expected of me after my driver is accepted? +--------------------------------------------------- + +The real work of maintainership begins after your code is in the tree. +This is where some maintainers fail, and is the reason the kernel +developers are so reluctant to allow new drivers into the main tree. + +There are two aspects of maintaining your driver in the kernel tree. The +obvious first duty is to keep your code synced to the kernel source. This +means submitting regular patch updates to the linux-kernel mailing list +and to the particular tree maintainer (e.g. Linus or Andrew). Now that +your code is included and properly styled and coded (with that shiny new +driver smell), it should be fairly easy to keep it that way. + +The other side of the coin is keeping changes in the kernel synced to your +code. Often times, it is necessary to change a kernel API (driver model, +USB stack changes, networking subsystem change, etc). These sorts of +changes usually affect a large number of drivers. It is not feasible for +these changes to be individually submitted to the driver maintainers. So +instead, the changes are made together in the kernel tree. If your driver +is affected, you are expected to pick up these changes and merge them with +your primary code (e.g. if you have a CVS repo for maintaining your code). +Usually this job is made easier if you use the same source control system +that the kernel maintainers use (currently, git), but this is not +required. + +There are times where changes to your driver may happen that are not the +API type of changes described above. A user of your driver may submit a +patch directly to Linus to fix an obvious bug in the code. Sometimes these +trivial and obvious patches will be accepted without feedback from the +driver maintainer. Don't take this personally. We're all in this together. +Just pick up the change and keep in sync with it. If you think the change +was incorrect, try to find the mailing list thread or log comments +regarding the change to see what was going on. Then email the patch author +about the change to start discussion. + + +How should I maintain my code after it's in the kernel tree? +------------------------------------------------------------ + +The suggested, and certainly the easiest method, is to start a git tree +cloned from the primary kernel tree. In this way, you are able to +automatically track the kernel changes by pulling from Linus' tree. You +can read more about maintaining a kernel git tree at +http://linux.yyz.us/git-howto.html. + +Whatever you decide to use for keeping your kernel tree, just remember +that the kernel tree source is the primary code. Your repository should +mainly be used for queuing patches, and doing development. Users should +not have to regularly go to your source in order to get a stable and +usable driver.
Signature · 3 lines
Ben Collins <[email protected]> Developer Ubuntu Linux
FYI, I am keeping this document available here:
http://people.ubuntu.com/~bcollins/HOWTO-KernelMaintainer.txt
for anyone wishing to reference it via a stable URL.
Signature · 3 lines
Ben Collins <[email protected]> Developer Ubuntu Linux
Quoted 3 lines · Ben Collins
Here's an updated document. I integrated the suggestions. For Arjan, I added a new section at the end. Hopefully that addresses the concerns for cvs-mentality.
it doesn't enough ;(
you still do a major suggestion to keep the code in a repo outside the kernel. For a single driver really that's at best "optional" and shouldn't be the prime recommendation.
"If your driver is affected, you are expected to pick up these changes and merge them with your primary code (e.g. if you have a CVS repo for maintaining your code)."
that sentence is just really the one that I hate. It's bogus. It still calls the private CVS copy "primary".
If you do the right thing (and store deltas against mainline and not full code except for scratch stuff) then this is no question of "merging back from mainline" at all.
Quoted 6 lines · Arjan van de Ven
Quoted 3 lines
Alsa, etc. All changes go someplace else before being
pushed to the primary kernel tree. 99% of the time, patches are going somewhere else before going into the main kernel.that's different... that's a patch queue. That's not the same as being the prime repository.
As a data point, ocfs2 is dropping its subversion repository and
moving to exactly this model -- ocfs2 development is a set of patches pending for mainline, with mainline as the prime repository. Really, there's no other way to do it. Otherwise, you get way out of sync.
Joel
Signature · 9 lines
"The suffering man ought really to consume his own smoke; there is no good in emitting smoke till you have made it into fire." - thomas carlyle Joel Becker Principal Software Developer Oracle E-mail: [email protected] Phone: (650) 506-8127
Quoted 15 lines · Arjan van de Ven
Quoted 3 lines · Ben Collins
Here's an updated document. I integrated the suggestions. For Arjan, I added a new section at the end. Hopefully that addresses the concerns for cvs-mentality.
it doesn't enough ;(
you still do a major suggestion to keep the code in a repo outside the kernel. For a single driver really that's at best "optional" and shouldn't be the prime recommendation.
"If your driver is affected, you are expected to pick up these changes and merge them with your primary code (e.g. if you have a CVS repo for maintaining your code)."
Quoted 5 lines
that sentence is just really the one that I hate. It's bogus. It still calls the private CVS copy "primary".
If you do the right thing (and store deltas against mainline and not full code except for scratch stuff) then this is no question of "merging back from mainline" at all.
But it says "your primary code". I'm not sure of another way to put it. Obviously, they have to do their work, and their development on something that isn't in Linus tree. If they are doing this work, they need to make sure that when they diff for patches, that they merge changes before diffing. The only way this is close to automatic is with git. Any other method requires manually merging.
How else would you explain this without telling them that git is required?
Signature · 3 lines
Ben Collins <[email protected]> Developer Ubuntu Linux
Quoted 10 lines · Ben Collins
But it says "your primary code". I'm not sure of another way to put it. Obviously, they have to do their work, and their development on something that isn't in Linus tree. If they are doing this work, they need to make sure that when they diff for patches, that they merge changes before diffing. The only way this is close to automatic is with git. Any other method requires manually merging.
How else would you explain this without telling them that git is required?
I have my name on one driver ;) Once the driver is in the kernel I no longer need worry about the source nor backups of my driver, okay? The primary code is in mainstream, this is how it works for 'leaf node' driver maintainers, at least from my limited perspective.
During development I had to rediff against -mm_latest, as that is how drivers (usually?) start the path to mainstream. But the only part need merging for a new driver is the Kconfig entry, a trivial issue?
Cheers,
Grant.
Quoted 16 lines · Ben Collins
Quoted 15 lines · Arjan van de Ven
Quoted 3 lines · Ben Collins
Here's an updated document. I integrated the suggestions. For Arjan, I added a new section at the end. Hopefully that addresses the concerns for cvs-mentality.
it doesn't enough ;(
you still do a major suggestion to keep the code in a repo outside the kernel. For a single driver really that's at best "optional" and shouldn't be the prime recommendation.
"If your driver is affected, you are expected to pick up these changes and merge them with your primary code (e.g. if you have a CVS repo for maintaining your code)."
Quoted 7 lines
Quoted 5 lines
that sentence is just really the one that I hate. It's bogus. It still calls the private CVS copy "primary".
If you do the right thing (and store deltas against mainline and not full code except for scratch stuff) then this is no question of "merging back from mainline" at all.But it says "your primary code". I'm not sure of another way to put it.
"your temporary development copy"
Quoted 5 lines
Obviously, they have to do their work, and their development on something that isn't in Linus tree. If they are doing this work, they need to make sure that when they diff for patches, that they merge changes before diffing. The only way this is close to automatic is with git. Any other method requires manually merging.
not correct. quilt is a very excellent counter example of that.
Quoted 8 lines · Arjan van de Ven
Quoted 6 lines
Obviously, they have to do their work, and their development on something that isn't in Linus tree. If they are doing this work, they need to make sure that when they diff for patches, that they merge changes before diffing. The only way this is close to automatic is with git. Any other method requires manually merging.
not correct. quilt is a very excellent counter example of that.
Yes. Anything that keeps a nice patch series that you can merge as a nice patch series works fine.
For example, Al Viro used to use (still uses?) RCS to maintain his work-in-progress. That worked fine, because he had a process where he would just extract them as patches.
The reason CVS doesn't work well is partly because CVS just sucks at so many levels, and because people start using it as more than a "series of patches" repository. People might cherry-pick one or two changes from a CVS, but it quickly becomes totally impossible to do anything sane at all, or even to cherry-pick more than a few patches, because after a while you've lost the ability to pick out individual changes.
Something like quilt works fine, because individual patches never get lost in other patches (they might get merged with another patch on purpose, but that's a separate issue). Anything that understands the notion of changesets and can be taught to re-order them should be able to work the same way.
So the important thing is to have _some_ proper linear changeset history, preferably one where you can re-order them (so that if you cherry-pick a set of changesets, you can mark them as having been merged, and keep the _rest_ as a linear changeset history).
CVS just sucks. End of story. It works badly at so many levels that it's just not even funny.
Linus
So is there a document I can point to that explains how to maintain your code properly? It's somewhat out of scope, so I really don't want a HOWTO within a HOWTO.
Signature · 3 lines
Ben Collins <[email protected]> Developer Ubuntu Linux
Hi!
Quoted 5 lines
Since this discussion of getting driver authors to submit their driver for inclusion I started writing a document to send them. I think it's best included in the kernel tree.
Signed-off-by Ben Collins <[email protected]>
Well, nice document, but it does not really match the title. I expected something like "how to be Jeff Garzik" and it is more "how to get your driver into kernel and keep it there". It does not deal with taking patches from other people, etc... I think it should go into submitting driver howto or something like that.
Pavel
Quoted 10 lines
Documentation/HOWTO-KernelMaintainer new file +7
-0@@ -0,0 +1,150 @@ + How to be a kernel driver maintainer + ------------------------------------ + + +This document explains what you must know before becoming the maintainer +of a portion of the Linux kernel. Please read SubmittingPatches and +SubmittingDrivers and CodingStyle, also in the Documentation/ directory.
Signature · 1 line
Thanks, Sharp!
Quoted 6 lines · Pavel Machek
Hi!
Quoted 4 lines
Since this discussion of getting driver authors to submit their driver for inclusion I started writing a document to send them. I think it's best included in the kernel tree.
Quoted 7 lines
Quoted 1 line
Signed-off-by Ben Collins <[email protected]>Well, nice document, but it does not really match the title. I expected something like "how to be Jeff Garzik" and it is more "how to get your driver into kernel and keep it there". It does not deal with taking patches from other people, etc... I think it should go into submitting driver howto or something like that.
Guess it could be renamed "How to become a kernel driver maintainer"
Signature · 3 lines
Ben Collins <[email protected]> Developer Ubuntu Linux
[Updated]: How to become a kernel driver maintainer
In reply to Arjan van de VenOnly small changes, title and a little rewording regarding "local development copy". I will submit a patch if there are no more changes to this document.
How to become a kernel driver maintainer
----------------------------------------
This document explains what you must know before becoming the maintainer of a portion of the Linux kernel. Please read SubmittingPatches, SubmittingDrivers and CodingStyle, also in the Documentation/ directory.
With the large amount of hardware available for Linux, it's becoming increasingly common for drivers for new or rare hardware to be maintained
outside of the main kernel tree. Usually these drivers end up in the kernel tree once they are stable, but many times users and distribution maintainers are left with collecting these external drivers in order to support the required hardware.
The purpose of this document is to provide information for the authors of
these drivers to eventually have their code in the mainline kernel tree.
Why should I submit my driver?
------------------------------
This is often the question a driver maintainer is faced with. Most driver
authors really don't see the benefit of having their code in the main kernel. Some even see it as giving up control of their code. This is simply not the case, and then end result is always beneficial to users and
developers alike.
The primary benefit is availability. When people want to compile a kernel,
they want to have everything there in the kernel tree. No one (not even kernel developers) likes having to search for, download, and build external drivers out-of-tree (outside the stock kernel source). It's often
difficult to find the right driver (one known to work correctly), and is even harder to find one that works on the kernel version they are building.
The benefit to users compiling their own kernel is immense. The benefit to
distributions is even greater. Linux distributions already have a large amount of work to provide a kernel that works for most users. If a driver
has to be provided for users that isn't in the primary kernel source, it adds additional work to maintaining (tracking the external driver, patching it into the build system, often times fixing build problems). With a driver in the kernel source, it's as simple as tracking the main kernel tree.
This assumes that the distribution finds your driver worth the time of doing all this. If they don't, then the few users needing your driver will
probably never get it (since most users are not capable of compiling their
own modules).
Another benefit of having the driver in the kernel tree is to promote the
hardware that it supports. Many companies who have written drivers for their hardware to run under Linux have not yet taken the leap to placing the driver in the main kernel. The "Old Way" of providing downloadable drivers doesn't work as well for Linux, since it's almost impossible to provide pre-compiled versions for any given system. Having the driver in the kernel tree means it will always be available. It also means that users wishing to purchase hardware that "Just Works" with Linux will have
more options. A well written and stable driver is a good reason for a user
to choose that particular type of hardware.
Having drivers in the main kernel tree benefits everyone.
What should I do to prepare for code submission?
------------------------------------------------
First you need to inspect your code and make sure it meets criteria for inclusion. Read Documentation/CodingStyle for help on proper coding format
(indentation, comment style, etc). It is strongly suggested that your driver builds cleanly when checked by the "sparse" tool. You will probably
need to annotate the driver so sparse can tell that it is following the kernel's rules for address space accesses and endianness. Adding these annotations is a simple, but time-consuming, operation that often exposes
real portability problems in drivers.
Once you have properly formatted the code, you also need to check a few other areas. Most drivers include backward compatibility for older kernels
(usually ifdef's with LINUX_VERSION_CODE). This backward compatibility needs to be removed. It's considered a waste of code for the driver to be
backward compatible within the kernel source tree, since it is going to be
compiled with a known version of the kernel.
Proper location in the kernel source needs to be determined. Find drivers
similar to yours, and use the same location. For example, USB network drivers go in drivers/usb/net/, and filesystems go in fs/.
The driver should then be prepared for building from the main source tree
in this location. A proper Makefile and Kconfig file in the Kbuild format
should be provided. Most times it is enough to just add your entries to existing files. Here are some good rules to follow:
- If your driver is a single source file (or single .c with a
single .h),
then it's typical to place the driver in an existing directory. Also, modify existing Makefile/Kconfig for that directory.
- If your driver is made up of several source files, then it is typical to create a subdirectory for it under the existing directory where it applies. Separate Makefile should be included, with a reference in
the
parent Makefile to make sure to descend into the one you created.
+ In this case, it is usually still correct to just add the Kconfig entry to the existing one. Unless your driver has 2 or more config options (debug options, extra features, etc), then creating a standalone Kconfig may be best. Make sure to source this newKconfig
from the parent directory.
- When creating the Kconfig entries be sure to keep in mind the
criteria
for the driver to be build. For example, a wireless network driver
may
need to "depend on NET && IEEE80211". Also, if you driver is
specific
to a certain architecture, be sure the Kconfig entry reflects this.
DO
NOT force your driver to a specific architecture simply because the driver is not written portably.
Lastly, you'll need to create an entry in the MAINTAINERS file. It should
reference you or the team responsible for the code being submitted (this should be the same person/team submitting the code).
Code review
-----------
Once your patches are ready, you can submit them to the linux-kernel mailing list. However, since most drivers fall under some subsystem (net,
usb, etc), then it is often required that you also Cc the mailing list for
this subsystem (see MAINTAINERS file for help finding the correct address).
The code review process is there for two reasons. First, it ensures that only good code, that follows current API's and coding practices, gets into
the kernel. The kernel developers know you have good intentions of maintaining your driver, but too often a driver is submitted to the kernel, and some time later becomes unmaintained. Then developers who are
not familiar with the code or it's purpose are left with keeping it compiling and working. So the code needs to be readable, and easily modified.
Secondly, the code review helps you to make your driver better. The folks
looking at your code have been doing Linux kernel work for years, and are
intimately familiar with all the nuances of the code. They can help with locking issues as well as big-endian/little-endian and 64-bit portability.
Be prepared to take some heavy criticism. It's very rare that anyone comes
out of this process without a scratch. Usually code review takes several tries. You'll need to follow the suggested changes, and make these to your
code, or have clear, acceptable reasons for *not* following the suggestions. Code reviewers are generally receptive to reasoned argument.
If you do not follow a reviewer's initial suggestions, you should add descriptive comments to the appropriate parts of the driver, so that future contributors can understand why things are in a possibly unexpected
state. Once you've made the changes required, resubmit. Try not to take it
personally. The suggestions are meant to help you, your code, and your users (and is often times seen as a rite of passage).
What is expected of me after my driver is accepted?
---------------------------------------------------
The real work of maintainership begins after your code is in the tree. This is where some maintainers fail, and is the reason the kernel developers are so reluctant to allow new drivers into the main tree.
There are two aspects of maintaining your driver in the kernel tree. The obvious first duty is to keep your code synced to the kernel source. This
means submitting regular patch updates to the linux-kernel mailing list and to the particular tree maintainer (e.g. Linus or Andrew). Now that your code is included and properly styled and coded (with that shiny new driver smell), it should be fairly easy to keep it that way.
The other side of the coin is keeping changes in the kernel synced to your
code. Often times, it is necessary to change a kernel API (driver model, USB stack changes, networking subsystem change, etc). These sorts of changes usually affect a large number of drivers. It is not feasible for these changes to be individually submitted to the driver maintainers. So instead, the changes are made together in the kernel tree. If your driver
is affected, you are expected to pick up these changes and merge them with
your temporary development copy. Usually this job is made easier if you use the same source control system that the kernel maintainers use (currently, git), but this is not required. Using git, however, allows you
to merge more easily.
There are times where changes to your driver may happen that are not the API type of changes described above. A user of your driver may submit a patch directly to Linus to fix an obvious bug in the code. Sometimes these
trivial and obvious patches will be accepted without feedback from the driver maintainer. Don't take this personally. We're all in this together.
Just pick up the change and keep in sync with it. If you think the change
was incorrect, try to find the mailing list thread or log comments regarding the change to see what was going on. Then email the patch author
about the change to start discussion.
How should I maintain my code after it's in the kernel tree?
------------------------------------------------------------
The suggested, and certainly the easiest method, is to start a git tree cloned from the primary kernel tree. In this way, you are able to automatically track the kernel changes by pulling from Linus' tree. You can read more about maintaining a kernel git tree at
http://linux.yyz.us/git-howto.html.
Whatever you decide to use for keeping your kernel tree, just remember that the kernel tree source is the primary code. Your repository should mainly be used for queuing patches, and doing development. Users should not have to regularly go to your source in order to get a stable and usable driver.
Signature · 4 lines
Ubuntu - http://www.ubuntu.com/ Debian - http://www.debian.org/ Linux 1394 - http://www.linux1394.org/ SwissDisk - http://www.swissdisk.com/
Re: [Updated]: How to become a kernel driver maintainer
On 3/8/06, Ben Collins <[email protected]> wrote:
Nice work Ben. A few comments and suggestions below.
Quoted 3 lines
authors really don't see the benefit of having their code in the main kernel. Some even see it as giving up control of their code. This is simply not the case, and then end result is always beneficial to users
s/and then end result/and the end result /
Quoted 9 lines
What should I do to prepare for code submission?
------------------------------------------------First you need to inspect your code and make sure it meets criteria for inclusion. Read
Documentation/CodingStylefor help on proper coding format
(indentation, comment style, etc). It is strongly suggested that your driver builds cleanly when checked by the "sparse" tool. You will
suggested text:
driver builds cleanly without warnings from the compiler or the "sparse" tool.
Quoted 5 lines
- When creating the
Kconfigentries be sure to keep in mind the
criteria
for the driver to be build. For example, a wireless network driver
may
Quoted 7 lines
need to "depend on NET && IEEE80211". Also, if you driver isspecific
to a certain architecture, be sure theKconfigentry reflects this.
DO
NOT force your driver to a specific architecture simply because the driver is not written portably.
Suggested addition:
Also make sure you provide useful help text for every entry you add
to Kconfig so that users of your driver will be able to read about what it does, what hardware it supports and perhaps find a reference to more extensive documentation.
Quoted 5 lines
Lastly, you'll need to create an entry in the
MAINTAINERSfile. It should
reference you or the team responsible for the code being submitted (this should be the same person/team submitting the code).
Suggested addition:
Optionally you may also want to add an entry to the CREDITS file.
Quoted 4 lines
not familiar with the code or it's purpose are left with keeping it compiling and working. So the code needs to be readable, and easily modified.
s/modified/modifiable/
Quoted 2 lines
Secondly, the code review helps you to make your driver better. The folks
s/folks/people/ ???
Quoted 5 lines
There are times where changes to your driver may happen that are not the API type of changes described above. A user of your driver may submit a patch directly to Linus to fix an obvious bug in the code. Sometimes these
trivial and obvious patches will be accepted without feedback from the
Quoted 9 lines
driver maintainer. Don't take this personally. We're all in this together.
Just pick up the change and keep in sync with it. If you think the change
was incorrect, try to find the mailing list thread or log comments regarding the change to see what was going on. Then email the patch author
about the change to start discussion.
Perhaps add a bit of text here about integrating patches send to you, as maintainer of the driver, by random people.
--
Jesper Juhl <[email protected]>
Don't top-post http://www.catb.org/~esr/jargon/html/T/top-post.html
Plain text mails only, please http://www.expita.com/nomime.html
Re: [Updated]: How to become a kernel driver maintainer
Quoted 5 lines
Quoted 3 lines
about the change to start discussion.
Perhaps add a bit of text here about integrating patches send to you, as maintainer of the driver, by random people.
it's not integrating.
It's reviewing and passing on for merge ;)
fundamental difference. You don't "own" the driver in the tree. You just keep it nice and shiny and clean. Best done by blessing patches, and by developing in "patches" not "new codebase". The entire "new codebase" thinking is the problem with CVS-think. Think in patches (once merged), not in code/tree.
Re: [Updated]: How to become a kernel driver maintainer
Quoted 6 lines · Arjan van de Ven
Quoted 5 lines
Quoted 3 lines
about the change to start discussion.
Perhaps add a bit of text here about integrating patches send to you, as maintainer of the driver, by random people.
Quoted 8 lines
it's not integrating.
It's reviewing and passing on for merge ;)
fundamental difference. You don't "own" the driver in the tree. You just keep it nice and shiny and clean. Best done by blessing patches, and by developing in "patches" not "new codebase". The entire "new codebase" thinking is the problem with CVS-think. Think in patches (once merged), not in code/tree.
Yeah, right, that's basically what I meant even if it's not what I actually said.
I just wanted to say that it should be described that you also have a responsability as maintainer for working with other people, review their patches, sign off on them, make sure they get picked up and forwarded to the proper people etc etc.
Thank you for making it more clear.
--
Jesper Juhl <[email protected]>
Don't top-post http://www.catb.org/~esr/jargon/html/T/top-post.html
Plain text mails only, please http://www.expita.com/nomime.html
Re: [Updated]: How to become a kernel driver maintainer
In reply to Ben CollinsQuoted 3 lines · On Wed, 08 Mar 2006 13:03:33 -0500 Ben Collins wrote:
Only small changes, title and a little rewording regarding "local development copy". I will submit a patch if there are no more changes to this document.
in addition to other comments:
Quoted 3 lines
Another benefit of having the driver in the kernel tree is to promote the
hardware that it supports. Many companies who have written drivers for
s/who/that/ (companies are not a person; "who" is for persons)
Quoted 8 lines
their hardware to run under Linux have not yet taken the leap to placing the driver in the main kernel. The "Old Way" of providing downloadable drivers doesn't work as well for Linux, since it's almost impossible to provide pre-compiled versions for any given system. Having the driver in the kernel tree means it will always be available. It also means that users wishing to purchase hardware that "Just Works" with Linux will have
more options. A well written and stable driver is a good reason for a
well-written
Quoted 21 lines
user
to choose that particular type of hardware.Having drivers in the main kernel tree benefits everyone.
What should I do to prepare for code submission?
------------------------------------------------First you need to inspect your code and make sure it meets criteria for inclusion. Read
Documentation/CodingStylefor help on proper coding format
(indentation, comment style, etc). It is strongly suggested that your driver builds cleanly when checked by the "sparse" tool. You will probably
need to annotate the driver so sparse can tell that it is following the kernel's rules for address space accesses and endianness. Adding these annotations is a simple, but time-consuming, operation that often exposes
real portability problems in drivers.
Quoted 9 lines
Once you have properly formatted the code, you also need to check a few other areas. Most drivers include backward compatibility for older kernels
(usually ifdef's withLINUX_VERSION_CODE). This backward compatibility needs to be removed. It's considered a waste of code for the driver to be
backward compatible within the kernel source tree, since it is going to be
compiled with a known version of the kernel.
Also use "make checkstack", "make buildcheck", and "make namespacecheck" to check for problems that they can detect.
Quoted 9 lines
Proper location in the kernel source needs to be determined. Find drivers
similar to yours, and use the same location. For example, USB network drivers go indrivers/usb/net/, and filesystems go infs/.The driver should then be prepared for building from the main source tree
in this location. A properMakefileandKconfigfile in theKbuildformat
and Kbuild Makefile & Kconfig files are described in Documentation/kbuild/*
Quoted 8 lines
should be provided. Most times it is enough to just add your entries to existing files. Here are some good rules to follow:
- If your driver is a single source file (or single .c with a
single .h),
then it's typical to place the driver in an existing directory. Also, modify existing Makefile/Kconfig for that directory.
Quoted 8 lines
- If your driver is made up of several source files, then it is typical to create a subdirectory for it under the existing directory where it applies. Separate
Makefileshould be included, with a reference in
the
parentMakefileto make sure to descend into the one you created.+ In this case, it is usually still correct to just add the
Kconfigentry to the existing one. Unless your driver has 2 or more config
s/Unless/If/
Quoted 9 lines
options (debug options, extra features, etc), then creating a standalone
Kconfigmay be best. Make sure to source this newKconfig
from the parent directory.- When creating the
Kconfigentries be sure to keep in mind the
criteria
for the driver to be build. For example, a wireless network driver
may
s/build/built/
Quoted 2 lines
need to "depend on NET && IEEE80211". Also, if you driver isspecific
s/you/your/
Quoted 9 lines
to a certain architecture, be sure the
Kconfigentry reflects this.
DO
NOT force your driver to a specific architecture simply because the driver is not written portably.Lastly, you'll need to create an entry in the
MAINTAINERSfile. It should
reference you or the team responsible for the code being submitted (this should be the same person/team submitting the code).
and the mailing list that should be used for correspondence.
Quoted 10 lines
Code review
-----------Once your patches are ready, you can submit them to the linux-kernel mailing list. However, since most drivers fall under some subsystem (net,
usb, etc), then it is often required that you also Cc the mailing list for
this subsystem (seeMAINTAINERSfile for help finding the correct address).
I disagree that lkml should always be used. It is becoming terribly over-burdened recently so either people are spending more time reading too much email or they are ignoring it. It would be better IMO to send patches for focused mailing lists that are appropriate for the driver.
Quoted 8 lines
The code review process is there for two reasons. First, it ensures that only good code, that follows current API's and coding practices, gets into
the kernel. The kernel developers know you have good intentions of maintaining your driver, but too often a driver is submitted to the kernel, and some time later becomes unmaintained. Then developers who are
not familiar with the code or it's purpose are left with keeping it
s/it's/its/
Quoted 10 lines
compiling and working. So the code needs to be readable, and easily modified.
What is expected of me after my driver is accepted?
---------------------------------------------------The real work of maintainership begins after your code is in the tree. This is where some maintainers fail, and is the reason the kernel developers are so reluctant to allow new drivers into the main tree.
I disagree with that last part. I guess I have seen some reluctance occasionally, but I don't think that it's the (main) reason for drivers not being accepted into the kernel tree.
Quoted 8 lines
How should I maintain my code after it's in the kernel tree?
------------------------------------------------------------Whatever you decide to use for keeping your kernel tree, just remember that the kernel tree source is the primary code. Your repository should mainly be used for queuing patches, and doing development. Users should not have to regularly go to your source in order to get a stable and usable driver.
amen.
---
~Randy
PATCH v3 1/1 : How to become a kernel driver maintainer
In reply to Jesper JuhlThis got back-burnered for awhile, but here's the fixed up copy from the last round of feedback. Thanks to everyone that's given input. It's all been helpful and I think this copy reflects everything that was discussed last time.
If there's no major changes requested, the next time will be in diff format for Documentation/ inclusion.
Signature · 4 lines
Ubuntu - http://www.ubuntu.com/ Debian - http://www.debian.org/ Linux 1394 - http://www.linux1394.org/ SwissDisk - http://www.swissdisk.com/
How to become a kernel driver maintainer
----------------------------------------
This document explains what you must know before becoming the maintainer of a portion of the Linux kernel. Please read SubmittingPatches, SubmittingDrivers and CodingStyle, also in the Documentation/ directory.
With the large amount of hardware available for Linux, it's becoming increasingly common for drivers for new or rare hardware to be maintained outside of the main kernel tree. Usually these drivers end up in the kernel tree once they are stable, but many times users and distribution maintainers are left with collecting these external drivers in order to support the required hardware.
The purpose of this document is to provide information for the authors of these drivers to eventually have their code in the mainline kernel tree.
Why should I submit my driver?
------------------------------
This is often the question a driver maintainer is faced with. Most driver authors really don't see the benefit of having their code in the main kernel. Some even see it as giving up control of their code. This is simply not the case, and the end result is always beneficial to users and developers alike.
The primary benefit is availability. When people want to compile a kernel, they want to have everything there in the kernel tree. No one (not even kernel developers) likes having to search for, download, and build external drivers out-of-tree (outside the stock kernel source). It's often difficult to find the right driver (one known to work correctly), and is even harder to find one that works on the kernel version they are building.
The benefit to users compiling their own kernel is immense. The benefit to distributions is even greater. Linux distributions already have a large amount of work to provide a kernel that works for most users. If a driver has to be provided for users that isn't in the primary kernel source, it adds additional work to maintaining (tracking the external driver, patching it into the build system, often times fixing build problems). With a driver in the kernel source, it's as simple as tracking the main kernel tree.
This assumes that the distribution finds your driver worth the time of doing all this. If they don't, then the few users needing your driver will probably never get it (since most users are not capable of compiling their own modules).
Another benefit of having the driver in the kernel tree is to promote the hardware that it supports. Many companies that have written drivers for their hardware to run under Linux have not yet taken the leap to placing the driver in the main kernel. The "Old Way" of providing downloadable drivers doesn't work as well for Linux, since it's almost impossible to provide pre-compiled versions for any given system. Having the driver in the kernel tree means it will always be available. It also means that users wishing to purchase hardware that "Just Works" with Linux will have more options. A well-written and stable driver is a good reason for a user to choose that particular type of hardware.
Having drivers in the main kernel tree benefits everyone.
What should I do to prepare for code submission?
------------------------------------------------
First you need to inspect your code and make sure it meets criteria for inclusion. Read Documentation/CodingStyle for help on proper coding format (indentation, comment style, etc). It is strongly suggested that your driver builds cleanly when checked by the "sparse" tool. You will probably need to annotate the driver so sparse can tell that it is following the kernel's rules for address space accesses and endianness. Adding these annotations is a simple, but time-consuming, operation that often exposes real portability problems in drivers.
There are also many targets in the kernel build system (KBuild) that will help check your code as well. These targets are listed if you type "make help" in the kernel tree. Some targets of note are, checkstack, buildcheck and namespacecheck. You can also add C=1 to the make arguments, in order to use the sparse tool for checking your code.
Once you have properly formatted the code, you also need to check a few other areas. Most drivers include backward compatibility for older kernels (usually ifdef's with LINUX_VERSION_CODE). This backward compatibility needs to be removed. It's considered a waste of code for the driver to be backward compatible within the kernel source tree, since it is going to be compiled with a known version of the kernel.
Proper location in the kernel source needs to be determined. Find drivers similar to yours, and use the same location. For example, USB network drivers go in drivers/usb/net/, and filesystems go in fs/.
The driver should then be prepared for building from the main source tree in this location. A proper Makefile and Kconfig file in the Kbuild format should be provided. Most times it is enough to just add your entries to existing files. Here are some good rules to follow:
- If your driver is a single source file (or single .c with a single .h), then it's typical to place the driver in an existing directory. Also, modify existing Makefile/Kconfig for that directory.
- If your driver is made up of several source files, then it is typical to create a subdirectory for it under the existing directory where it applies. Separate Makefile should be included, with a reference in the parent Makefile to make sure to descend into the one you created.
+ In this case, it is usually still correct to just add the Kconfig entry to the existing one. If your driver has 2 or more config options (debug options, extra features, etc), then creating a standalone Kconfig may be best. Make sure to source this new Kconfig from the parent directory.
- When creating the Kconfig entries be sure to keep in mind the criteria for the driver to be built. For example, a wireless network driver may need to "depend on NET && IEEE80211". Also, if your driver is specific to a certain architecture, be sure the Kconfig entry reflects this. DO NOT force your driver to a specific architecture simply because the driver is not written portably.
- Make sure you provide useful help text for every entry you add to Kconfig so that users of your driver will be able to read about what it does, what hardware it supports and perhaps find a reference to more extensive documentation.
More info on the kbuild system is available in Documentation/kbuild/ in the kernel source tree.
Lastly, you'll need to create an entry in the MAINTAINERS file. It should reference you or the team responsible for the code being submitted (this should be the same person/team submitting the code). Also include, if available, a mailing that should be used for correspondence.
Code review
-----------
Once your patches are ready, you can submit them to the linux-kernel mailing list. However, since most drivers fall under some subsystem (net, usb, etc), then it is often more appropriate to send them to the mailing list for this subsystem (see MAINTAINERS file for help finding the correct address).
The code review process is there for two reasons. First, it ensures that only good code, that follows current API's and coding practices, gets into the kernel. The kernel developers know you have good intentions of maintaining your driver, but too often a driver is submitted to the kernel, and some time later becomes unmaintained. Then developers who are not familiar with the code or its purpose are left with keeping it compiling and working. So the code needs to be readable, and easily modifiable.
Secondly, the code review helps you to make your driver better. The people looking at your code have been doing Linux kernel work for years, and are intimately familiar with all the nuances of the code. They can help with locking issues as well as big-endian/little-endian and 64-bit portability.
Be prepared to take some heavy criticism. It's very rare that anyone comes out of this process without a scratch. Usually code review takes several tries. You'll need to follow the suggested changes, and make these to your code, or have clear, acceptable reasons for *not* following the suggestions. Code reviewers are generally receptive to reasoned argument. If you do not follow a reviewer's initial suggestions, you should add descriptive comments to the appropriate parts of the driver, so that future contributors can understand why things are in a possibly unexpected state. Once you've made the changes required, resubmit. Try not to take it personally. The suggestions are meant to help you, your code, and your users (and is often times seen as a rite of passage).
What is expected of me after my driver is accepted?
---------------------------------------------------
The real work of maintainership begins after your code is in the tree. This is where some maintainers fail, and is the reason the kernel developers are so reluctant to allow new drivers into the main tree.
There are two aspects of maintaining your driver in the kernel tree. The obvious first duty is to keep your code synced to the kernel source. This means submitting regular patch updates to the linux-kernel mailing list and to the particular tree maintainer (e.g. Linus or Andrew). Now that your code is included and properly styled and coded (with that shiny new driver smell), it should be fairly easy to keep it that way.
The other side of the coin is keeping changes in the kernel synced to your code. Often times, it is necessary to change a kernel API (driver model, USB stack changes, networking subsystem change, etc). These sorts of changes usually affect a large number of drivers. It is not feasible for these changes to be individually submitted to the driver maintainers. So instead, the changes are made together in the kernel tree. If your driver is affected, you are expected to pick up these changes and merge them with your temporary development copy. Usually this job is made easier if you use the same source control system that the kernel maintainers use (currently, git), but this is not required. Using git, however, allows you to merge more easily.
There are times where changes to your driver may happen that are not the API type of changes described above. A user of your driver may submit a patch directly to Linus to fix an obvious bug in the code. Sometimes these trivial and obvious patches will be accepted without feedback from the driver maintainer. Don't take this personally. We're all in this together. Just pick up the change and keep in sync with it. If you think the change was incorrect, try to find the mailing list thread or log comments regarding the change to see what was going on. Then email the patch author about the change to start discussion.
How should I maintain my code after it's in the kernel tree?
------------------------------------------------------------
The suggested, and certainly the easiest method, is to start a git tree cloned from the primary kernel tree. In this way, you are able to automatically track the kernel changes by pulling from Linus' tree. You can read more about maintaining a kernel git tree at
http://linux.yyz.us/git-howto.html.
Whatever you decide to use for keeping your kernel tree, just remember that the kernel tree source is the primary code. Your repository should mainly be used for queuing patches, and doing development. Users should not have to regularly go to your source in order to get a stable and usable driver.
Re: [Updated v3]: How to become a kernel driver maintainer
Quoted 7 lines · On Fri, 02 Jun 2006 17:38:36 -0400 Ben Collins wrote:
This got back-burnered for awhile, but here's the fixed up copy from the last round of feedback. Thanks to everyone that's given input. It's all been helpful and I think this copy reflects everything that was discussed last time.
If there's no major changes requested, the next time will be in diff format for
Documentation/inclusion.
Having the text inline for review/comments sure would be a lot easier on reviewers.
| There are also many targets in the kernel build system (KBuild) that will | help check your code as well. These targets are listed if you type "make | help" in the kernel tree. Some targets of note are, checkstack, | buildcheck and namespacecheck. You can also add C=1 to the make arguments, | in order to use the sparse tool for checking your code.
'buildcheck' is gone. It is done automatically at the end of every build.
Grammar fixes:
Some targets of note are "checkstack" and "namespacecheck". You can also add C=1 to the 'make' arguments
in order to use the sparse tool for checking your code.
| - When creating the Kconfig entries
I would add something like:
Also do not enable (y or m) Kconfig options by default. Users should enable them and we don't want to increase kernel size for people who don't need this.
Spello:
and your users (and is often times seen as a rite of passage). "oftentimes"
and later:
Often times, it is necessary
"Oftentimes,"
| This is where some maintainers fail, and is the reason the kernel | developers are so reluctant to allow new drivers into the main tree.
I still disagree with that conclusion (as I also wrote on 8-Mar-2006). I think that it's basically a matter of if the (driver) submitter is willing to do the work as documented in Documentation/* and listen to review feedback and act on that or explain why changes shouldn't be made, then the code will likely be accepted (if it's *correct*, of course).
| There are times where changes
should be
"times when" or "places where"
---
~Randy
Re: [Updated v3]: How to become a kernel driver maintainer
In reply to Ben CollinsQuoted 3 lines · Ben Collins
The real work of maintainership begins after your code is in the tree. This is where some maintainers fail, and is the reason the kernel developers are so reluctant to allow new drivers into the main tree.
I don't think this is true. On-going maintenance of a driver is quite minor over time, unless you are adding new support, or if there are bugs in your driver. We will gladly accept any driver, as long as it follows the proper coding style rules and plays nice with the rest of the kernel.
Quoted 11 lines
The other side of the coin is keeping changes in the kernel synced to your code. Often times, it is necessary to change a kernel API (driver model, USB stack changes, networking subsystem change, etc). These sorts of changes usually affect a large number of drivers. It is not feasible for these changes to be individually submitted to the driver maintainers. So instead, the changes are made together in the kernel tree. If your driver is affected, you are expected to pick up these changes and merge them with your temporary development copy. Usually this job is made easier if you use the same source control system that the kernel maintainers use (currently, git), but this is not required. Using git, however, allows you to merge more easily.
Almost always, the person doing the API change fixes all in-kernel versions of the api change. So the driver author/maintainer does not have to fix up anything.
Quoted 12 lines
There are times where changes to your driver may happen that are not the API type of changes described above. A user of your driver may submit a patch directly to Linus to fix an obvious bug in the code. Sometimes these trivial and obvious patches will be accepted without feedback from the driver maintainer. Don't take this personally. We're all in this together. Just pick up the change and keep in sync with it. If you think the change was incorrect, try to find the mailing list thread or log comments regarding the change to see what was going on. Then email the patch author about the change to start discussion.
Quoted 8 lines
How should I maintain my code after it's in the kernel tree?
------------------------------------------------------------The suggested, and certainly the easiest method, is to start a git tree cloned from the primary kernel tree. In this way, you are able to automatically track the kernel changes by pulling from Linus' tree. You can read more about maintaining a kernel git tree at
http://linux.yyz.us/git-howto.html.
I disagree, quilt is _much_ easier for maintaining patches against a common tree. Combined with ketchup and it makes things dirt simple.
Everything else looks good, very nice job.
thanks,
greg k-h
Re: [Updated v3]: How to become a kernel driver maintainer
In reply to Ben CollinsQuoted 3 lines
With the large amount of hardware available for Linux, it's becoming
I do not know about LK customs, but in school we were always forced to write truncations out ("it is" rather than "it's").
Quoted 3 lines
Some even see it as giving up control of their code. This is simply not the case, and the end result is always beneficial to users and developers alike.
Frankly, they have to give up their coding style. A common style throughout the kernel is reasonable, though. But in some aspects it really gets nitpicky (spaces vs tabs to name one).
Quoted 2 lines
The code review process is there for two reasons. First, it ensures that only good code, that follows current API's and coding practices, gets into
Should read: "that follows current APIs"
Quoted 1 line
locking issues as well as big-endian/little-endian and 64-bit portability.
Suggestion: "as well as endianness and ..."
Jan Engelhardt