1 2 How to Get Your Change Into the Linux Kernel 3 or 4 Care And Operation Of Your Linus Torvalds 5 6 7 8For a person or company who wishes to submit a change to the Linux 9kernel, the process can sometimes be daunting if you're not familiar 10with "the system." This text is a collection of suggestions which 11can greatly increase the chances of your change being accepted. 12 13If you are submitting a driver, also read Documentation/SubmittingDrivers. 14 15 16 17-------------------------------------------- 18SECTION 1 - CREATING AND SENDING YOUR CHANGE 19-------------------------------------------- 20 21 22 231) "diff -u" 24------------ 25 26Use "diff -u" or "diff -urN" to create patches. 27 28All changes to the Linux kernel occur in the form of patches, as 29generated by diff(1). When creating your patch, make sure to create it 30in "unified diff" format, as supplied by the '-u' argument to diff(1). 31Patches should be based in the root kernel source directory, not in 32any lower subdirectory. 33 34To create a patch for a single file, it is often sufficient to do: 35 36 SRCTREE= /devel/linux-2.4 37 MYFILE= drivers/net/mydriver.c 38 39 cd $SRCTREE 40 cp $MYFILE $MYFILE.orig 41 vi $MYFILE # make your change 42 diff -u $MYFILE.orig $MYFILE > /tmp/patch 43 44To create a patch for multiple files, you should unpack a "vanilla", 45or unmodified kernel source tree, and generate a diff against your 46own source tree. For example: 47 48 MYSRC= /devel/linux-2.4 49 50 tar xvfz linux-2.4.0-test11.tar.gz 51 mv linux linux-vanilla 52 wget http://www.moses.uklinux.net/patches/dontdiff 53 diff -urN -X dontdiff linux-vanilla $MYSRC > /tmp/patch 54 rm -f dontdiff 55 56"dontdiff" is a list of files which are generated by the kernel during 57the build process, and should be ignored in any diff(1)-generated 58patch. dontdiff is maintained by Tigran Aivazian <tigran@veritas.com> 59 60Make sure your patch does not include any extra files which do not 61belong in a patch submission. Make sure to review your patch -after- 62generated it with diff(1), to ensure accuracy. 63 64 652) Describe your changes. 66 67Describe the technical detail of the change(s) your patch includes. 68 69Be as specific as possible. The WORST descriptions possible include 70things like "update driver X", "bug fix for driver X", or "this patch 71includes updates for subsystem X. Please apply." 72 73If your description starts to get long, that's a sign that you probably 74need to split up your patch. See #3, next. 75 76 77 783) Separate your changes. 79 80Separate each logical change into its own patch. 81 82For example, if your changes include both bug fixes and performance 83enhancements for a single driver, separate those changes into two 84or more patches. If your changes include an API update, and a new 85driver which uses that new API, separate those into two patches. 86 87On the other hand, if you make a single change to numerous files, 88group those changes into a single patch. Thus a single logical change 89is contained within a single patch. 90 91If one patch depends on another patch in order for a change to be 92complete, that is OK. Simply note "this patch depends on patch X" 93in your patch description. 94 95 964) Select e-mail destination. 97 98Look through the MAINTAINERS file and the source code, and determine 99if your change applies to a specific subsystem of the kernel, with 100an assigned maintainer. If so, e-mail that person. 101 102If no maintainer is listed, or the maintainer does not respond, send 103your patch to the primary Linux kernel developer's mailing list, 104linux-kernel@vger.kernel.org. Most kernel developers monitor this 105e-mail list, and can comment on your changes. 106 107Linus Torvalds is the final arbiter of all changes accepted into the 108Linux kernel. His e-mail address is torvalds@transmeta.com. He gets 109a lot of e-mail, so typically you should do your best to -avoid- sending 110him e-mail. 111 112Patches which are bug fixes, are "obvious" changes, or similarly 113require little discussion should be sent or CC'd to Linus. Patches 114which require discussion or do not have a clear advantage should 115usually be sent first to linux-kernel. Only after the patch is 116discussed should the patch then be submitted to Linus. 117 118 119 1205) Select your CC (e-mail carbon copy) list. 121 122Unless you have a reason NOT to do so, CC linux-kernel@vger.kernel.org. 123 124Other kernel developers besides Linus need to be aware of your change, 125so that they may comment on it and offer code review and suggestions. 126linux-kernel is the primary Linux kernel developer mailing list. 127Other mailing lists are available for specific subsystems, such as 128USB, framebuffer devices, the VFS, the SCSI subsystem, etc. See the 129MAINTAINERS file for a mailing list that relates specifically to 130your change. 131 132Even if the maintainer did not respond in step #4, make sure to ALWAYS 133copy the maintainer when you change their code. 134 135 136 1376) No MIME, no links, no compression, no attachments. Just plain text. 138 139Linus and other kernel developers need to be able to read and comment 140on the changes you are submitting. It is important for a kernel 141developer to be able to "quote" your changes, using standard e-mail 142tools, so that they may comment on specific portions of your code. 143 144For this reason, all patches should be submitting e-mail "inline". 145WARNING: Be wary of your editor's word-wrap corrupting your patch, 146if you choose to cut-n-paste your patch. 147 148Do not attach the patch as a MIME attachment, compressed or not. 149Many popular e-mail applications will not always transmit a MIME 150attachment as plain text, making it impossible to comment on your 151code. A MIME attachment also takes Linus a bit more time to process, 152decreasing the likelihood of your MIME-attached change being accepted. 153 154Exception: If your mailer is mangling patches then someone may ask 155you to re-send them using MIME. 156 157 158 1597) E-mail size. 160 161When sending patches to Linus, always follow step #6. 162 163Large changes are not appropriate for mailing lists, and some 164maintainers. If your patch, uncompressed, exceeds 40 kB in size, 165it is preferred that you store your patch on an Internet-accessible 166server, and provide instead a URL (link) pointing to your patch. 167 168 169 1708) Name your kernel version. 171 172It is important to note, either in the subject line or in the patch 173description, the kernel version to which this patch applies. 174 175If the patch does not apply cleanly to the latest kernel version, 176Linus will not apply it. 177 178 179 1809) Don't get discouraged. Re-submit. 181 182After you have submitted your change, be patient and wait. If Linus 183likes your change and applies it, it will appear in the next version 184of the kernel that he releases. 185 186However, if your change doesn't appear in the next version of the 187kernel, there could be any number of reasons. It's YOUR job to 188narrow down those reasons, correct what was wrong, and submit your 189updated change. 190 191It is quite common for Linus to "drop" your patch without comment. 192That's the nature of the system. If he drops your patch, it could be 193due to 194* Your patch did not apply cleanly to the latest kernel version 195* Your patch was not sufficiently discussed on linux-kernel. 196* A style issue (see section 2), 197* An e-mail formatting issue (re-read this section) 198* A technical problem with your change 199* He gets tons of e-mail, and yours got lost in the shuffle 200* You are being annoying (See Figure 1) 201 202When in doubt, solicit comments on linux-kernel mailing list. 203 204 205 20610) Include PATCH in the subject 207 208Due to high e-mail traffic to Linus, and to linux-kernel, it is common 209convention to prefix your subject line with [PATCH]. This lets Linus 210and other kernel developers more easily distinguish patches from other 211e-mail discussions. 212 213 214 215----------------------------------- 216SECTION 2 - HINTS, TIPS, AND TRICKS 217----------------------------------- 218 219This section lists many of the common "rules" associated with code 220submitted to the kernel. There are always exceptions... but you must 221have a really good reason for doing so. You could probably call this 222section Linus Computer Science 101. 223 224 225 2261) Read Documentation/CodingStyle 227 228Nuff said. If your code deviates too much from this, it is likely 229to be rejected without further review, and without comment. 230 231 232 2332) #ifdefs are ugly 234 235Code cluttered with ifdefs is difficult to read and maintain. Don't do 236it. Instead, put your ifdefs in a header, and conditionally define 237'static inline' functions, or macros, which are used in the code. 238Let the compiler optimize away the "no-op" case. 239 240Simple example, of poor code: 241 242 dev = init_etherdev (NULL, 0); 243 if (!dev) 244 return -ENODEV; 245 #ifdef CONFIG_NET_FUNKINESS 246 init_funky_net(dev); 247 #endif 248 249Cleaned-up example: 250 251(in header) 252 #ifndef CONFIG_NET_FUNKINESS 253 static inline void init_funky_net (struct net_device *d) {} 254 #endif 255 256(in the code itself) 257 dev = init_etherdev (NULL, 0); 258 if (!dev) 259 return -ENODEV; 260 init_funky_net(dev); 261 262 263 2643) 'static inline' is better than a macro 265 266Static inline functions are greatly preferred over macros. 267They provide type safety, have no length limitations, no formatting 268limitations, and under gcc they are as cheap as macros. 269 270Macros should only be used for cases where a static inline is clearly 271suboptimal [there a few, isolated cases of this in fast paths], 272or where it is impossible to use a static inline function [such as 273string-izing]. 274 275'static inline' is preferred over 'static __inline__', 'extern inline', 276and 'extern __inline__'. 277 278 279 2804) Don't over-design. 281 282Don't try to anticipate nebulous future cases which may or may not 283be useful: "Make it as simple as you can, and no simpler" 284 285 286 287