| |
| How to Get Your Change Into the Linux Kernel |
| or |
| Care And Operation Of Your Linus Torvalds |
| |
| |
| |
| For a person or company who wishes to submit a change to the Linux |
| kernel, the process can sometimes be daunting if you're not familiar |
| with "the system." This text is a collection of suggestions which |
| can greatly increase the chances of your change being accepted. |
| |
| If you are submitting a driver, also read Documentation/SubmittingDrivers. |
| |
| |
| |
| -------------------------------------------- |
| SECTION 1 - CREATING AND SENDING YOUR CHANGE |
| -------------------------------------------- |
| |
| |
| |
| 1) "diff -u" |
| ------------ |
| |
| Use "diff -u" or "diff -urN" to create patches. |
| |
| All changes to the Linux kernel occur in the form of patches, as |
| generated by diff(1). When creating your patch, make sure to create it |
| in "unified diff" format, as supplied by the '-u' argument to diff(1). |
| Patches should be based in the root kernel source directory, not in |
| any lower subdirectory. |
| |
| To create a patch for a single file, it is often sufficient to do: |
| |
| SRCTREE= /devel/linux-2.4 |
| MYFILE= drivers/net/mydriver.c |
| |
| cd $SRCTREE |
| cp $MYFILE $MYFILE.orig |
| vi $MYFILE # make your change |
| diff -u $MYFILE.orig $MYFILE > /tmp/patch |
| |
| To create a patch for multiple files, you should unpack a "vanilla", |
| or unmodified kernel source tree, and generate a diff against your |
| own source tree. For example: |
| |
| MYSRC= /devel/linux-2.4 |
| |
| tar xvfz linux-2.4.0-test11.tar.gz |
| mv linux linux-vanilla |
| wget http://www.moses.uklinux.net/patches/dontdiff |
| diff -urN -X dontdiff linux-vanilla $MYSRC > /tmp/patch |
| rm -f dontdiff |
| |
| "dontdiff" is a list of files which are generated by the kernel during |
| the build process, and should be ignored in any diff(1)-generated |
| patch. dontdiff is maintained by Tigran Aivazian <tigran@veritas.com> |
| |
| Make sure your patch does not include any extra files which do not |
| belong in a patch submission. Make sure to review your patch -after- |
| generated it with diff(1), to ensure accuracy. |
| |
| |
| 2) Describe your changes. |
| |
| Describe the technical detail of the change(s) your patch includes. |
| |
| Be as specific as possible. The WORST descriptions possible include |
| things like "update driver X", "bug fix for driver X", or "this patch |
| includes updates for subsystem X. Please apply." |
| |
| If your description starts to get long, that's a sign that you probably |
| need to split up your patch. See #3, next. |
| |
| |
| |
| 3) Separate your changes. |
| |
| Separate each logical change into its own patch. |
| |
| For example, if your changes include both bug fixes and performance |
| enhancements for a single driver, separate those changes into two |
| or more patches. If your changes include an API update, and a new |
| driver which uses that new API, separate those into two patches. |
| |
| On the other hand, if you make a single change to numerous files, |
| group those changes into a single patch. Thus a single logical change |
| is contained within a single patch. |
| |
| If one patch depends on another patch in order for a change to be |
| complete, that is OK. Simply note "this patch depends on patch X" |
| in your patch description. |
| |
| |
| 4) Select e-mail destination. |
| |
| Look through the MAINTAINERS file and the source code, and determine |
| if your change applies to a specific subsystem of the kernel, with |
| an assigned maintainer. If so, e-mail that person. |
| |
| If no maintainer is listed, or the maintainer does not respond, send |
| your patch to the primary Linux kernel developer's mailing list, |
| linux-kernel@vger.kernel.org. Most kernel developers monitor this |
| e-mail list, and can comment on your changes. |
| |
| Linus Torvalds is the final arbiter of all changes accepted into the |
| Linux kernel. His e-mail address is torvalds@transmeta.com. He gets |
| a lot of e-mail, so typically you should do your best to -avoid- sending |
| him e-mail. |
| |
| Patches which are bug fixes, are "obvious" changes, or similarly |
| require little discussion should be sent or CC'd to Linus. Patches |
| which require discussion or do not have a clear advantage should |
| usually be sent first to linux-kernel. Only after the patch is |
| discussed should the patch then be submitted to Linus. |
| |
| |
| |
| 5) Select your CC (e-mail carbon copy) list. |
| |
| Unless you have a reason NOT to do so, CC linux-kernel@vger.kernel.org. |
| |
| Other kernel developers besides Linus need to be aware of your change, |
| so that they may comment on it and offer code review and suggestions. |
| linux-kernel is the primary Linux kernel developer mailing list. |
| Other mailing lists are available for specific subsystems, such as |
| USB, framebuffer devices, the VFS, the SCSI subsystem, etc. See the |
| MAINTAINERS file for a mailing list that relates specifically to |
| your change. |
| |
| Even if the maintainer did not respond in step #4, make sure to ALWAYS |
| copy the maintainer when you change their code. |
| |
| |
| |
| 6) No MIME, no links, no compression, no attachments. Just plain text. |
| |
| Linus and other kernel developers need to be able to read and comment |
| on the changes you are submitting. It is important for a kernel |
| developer to be able to "quote" your changes, using standard e-mail |
| tools, so that they may comment on specific portions of your code. |
| |
| For this reason, all patches should be submitting e-mail "inline". |
| WARNING: Be wary of your editor's word-wrap corrupting your patch, |
| if you choose to cut-n-paste your patch. |
| |
| Do not attach the patch as a MIME attachment, compressed or not. |
| Many popular e-mail applications will not always transmit a MIME |
| attachment as plain text, making it impossible to comment on your |
| code. A MIME attachment also takes Linus a bit more time to process, |
| decreasing the likelihood of your MIME-attached change being accepted. |
| |
| Exception: If your mailer is mangling patches then someone may ask |
| you to re-send them using MIME. |
| |
| |
| |
| 7) E-mail size. |
| |
| When sending patches to Linus, always follow step #6. |
| |
| Large changes are not appropriate for mailing lists, and some |
| maintainers. If your patch, uncompressed, exceeds 40 kB in size, |
| it is preferred that you store your patch on an Internet-accessible |
| server, and provide instead a URL (link) pointing to your patch. |
| |
| |
| |
| 8) Name your kernel version. |
| |
| It is important to note, either in the subject line or in the patch |
| description, the kernel version to which this patch applies. |
| |
| If the patch does not apply cleanly to the latest kernel version, |
| Linus will not apply it. |
| |
| |
| |
| 9) Don't get discouraged. Re-submit. |
| |
| After you have submitted your change, be patient and wait. If Linus |
| likes your change and applies it, it will appear in the next version |
| of the kernel that he releases. |
| |
| However, if your change doesn't appear in the next version of the |
| kernel, there could be any number of reasons. It's YOUR job to |
| narrow down those reasons, correct what was wrong, and submit your |
| updated change. |
| |
| It is quite common for Linus to "drop" your patch without comment. |
| That's the nature of the system. If he drops your patch, it could be |
| due to |
| * Your patch did not apply cleanly to the latest kernel version |
| * Your patch was not sufficiently discussed on linux-kernel. |
| * A style issue (see section 2), |
| * An e-mail formatting issue (re-read this section) |
| * A technical problem with your change |
| * He gets tons of e-mail, and yours got lost in the shuffle |
| * You are being annoying (See Figure 1) |
| |
| When in doubt, solicit comments on linux-kernel mailing list. |
| |
| |
| |
| 10) Include PATCH in the subject |
| |
| Due to high e-mail traffic to Linus, and to linux-kernel, it is common |
| convention to prefix your subject line with [PATCH]. This lets Linus |
| and other kernel developers more easily distinguish patches from other |
| e-mail discussions. |
| |
| |
| |
| ----------------------------------- |
| SECTION 2 - HINTS, TIPS, AND TRICKS |
| ----------------------------------- |
| |
| This section lists many of the common "rules" associated with code |
| submitted to the kernel. There are always exceptions... but you must |
| have a really good reason for doing so. You could probably call this |
| section Linus Computer Science 101. |
| |
| |
| |
| 1) Read Documentation/CodingStyle |
| |
| Nuff said. If your code deviates too much from this, it is likely |
| to be rejected without further review, and without comment. |
| |
| |
| |
| 2) #ifdefs are ugly |
| |
| Code cluttered with ifdefs is difficult to read and maintain. Don't do |
| it. Instead, put your ifdefs in a header, and conditionally define |
| 'static inline' functions, or macros, which are used in the code. |
| Let the compiler optimize away the "no-op" case. |
| |
| Simple example, of poor code: |
| |
| dev = init_etherdev (NULL, 0); |
| if (!dev) |
| return -ENODEV; |
| #ifdef CONFIG_NET_FUNKINESS |
| init_funky_net(dev); |
| #endif |
| |
| Cleaned-up example: |
| |
| (in header) |
| #ifndef CONFIG_NET_FUNKINESS |
| static inline void init_funky_net (struct net_device *d) {} |
| #endif |
| |
| (in the code itself) |
| dev = init_etherdev (NULL, 0); |
| if (!dev) |
| return -ENODEV; |
| init_funky_net(dev); |
| |
| |
| |
| 3) 'static inline' is better than a macro |
| |
| Static inline functions are greatly preferred over macros. |
| They provide type safety, have no length limitations, no formatting |
| limitations, and under gcc they are as cheap as macros. |
| |
| Macros should only be used for cases where a static inline is clearly |
| suboptimal [there a few, isolated cases of this in fast paths], |
| or where it is impossible to use a static inline function [such as |
| string-izing]. |
| |
| 'static inline' is preferred over 'static __inline__', 'extern inline', |
| and 'extern __inline__'. |
| |
| |
| |
| 4) Don't over-design. |
| |
| Don't try to anticipate nebulous future cases which may or may not |
| be useful: "Make it as simple as you can, and no simpler" |
| |
| |
| |