Commit | Line | Data |
---|---|---|
1da177e4 LT |
1 | |
2 | How to Get Your Change Into the Linux Kernel | |
3 | or | |
4 | Care And Operation Of Your Linus Torvalds | |
5 | ||
6 | ||
7 | ||
8 | For a person or company who wishes to submit a change to the Linux | |
9 | kernel, the process can sometimes be daunting if you're not familiar | |
10 | with "the system." This text is a collection of suggestions which | |
11 | can greatly increase the chances of your change being accepted. | |
12 | ||
bc7455fa RD |
13 | Read Documentation/SubmitChecklist for a list of items to check |
14 | before submitting code. If you are submitting a driver, also read | |
15 | Documentation/SubmittingDrivers. | |
1da177e4 LT |
16 | |
17 | ||
18 | ||
19 | -------------------------------------------- | |
20 | SECTION 1 - CREATING AND SENDING YOUR CHANGE | |
21 | -------------------------------------------- | |
22 | ||
23 | ||
24 | ||
25 | 1) "diff -up" | |
26 | ------------ | |
27 | ||
28 | Use "diff -up" or "diff -uprN" to create patches. | |
29 | ||
30 | All changes to the Linux kernel occur in the form of patches, as | |
31 | generated by diff(1). When creating your patch, make sure to create it | |
32 | in "unified diff" format, as supplied by the '-u' argument to diff(1). | |
33 | Also, please use the '-p' argument which shows which C function each | |
34 | change is in - that makes the resultant diff a lot easier to read. | |
35 | Patches should be based in the root kernel source directory, | |
36 | not in any lower subdirectory. | |
37 | ||
38 | To create a patch for a single file, it is often sufficient to do: | |
39 | ||
84da7c08 | 40 | SRCTREE= linux-2.6 |
1da177e4 LT |
41 | MYFILE= drivers/net/mydriver.c |
42 | ||
43 | cd $SRCTREE | |
44 | cp $MYFILE $MYFILE.orig | |
45 | vi $MYFILE # make your change | |
46 | cd .. | |
47 | diff -up $SRCTREE/$MYFILE{.orig,} > /tmp/patch | |
48 | ||
49 | To create a patch for multiple files, you should unpack a "vanilla", | |
50 | or unmodified kernel source tree, and generate a diff against your | |
51 | own source tree. For example: | |
52 | ||
84da7c08 | 53 | MYSRC= /devel/linux-2.6 |
1da177e4 | 54 | |
84da7c08 RD |
55 | tar xvfz linux-2.6.12.tar.gz |
56 | mv linux-2.6.12 linux-2.6.12-vanilla | |
57 | diff -uprN -X linux-2.6.12-vanilla/Documentation/dontdiff \ | |
58 | linux-2.6.12-vanilla $MYSRC > /tmp/patch | |
1da177e4 LT |
59 | |
60 | "dontdiff" is a list of files which are generated by the kernel during | |
61 | the build process, and should be ignored in any diff(1)-generated | |
84da7c08 RD |
62 | patch. The "dontdiff" file is included in the kernel tree in |
63 | 2.6.12 and later. For earlier kernel versions, you can get it | |
64 | from <http://www.xenotime.net/linux/doc/dontdiff>. | |
1da177e4 LT |
65 | |
66 | Make sure your patch does not include any extra files which do not | |
67 | belong in a patch submission. Make sure to review your patch -after- | |
68 | generated it with diff(1), to ensure accuracy. | |
69 | ||
70 | If your changes produce a lot of deltas, you may want to look into | |
71 | splitting them into individual patches which modify things in | |
84da7c08 | 72 | logical stages. This will facilitate easier reviewing by other |
1da177e4 | 73 | kernel developers, very important if you want your patch accepted. |
84da7c08 | 74 | There are a number of scripts which can aid in this: |
1da177e4 LT |
75 | |
76 | Quilt: | |
77 | http://savannah.nongnu.org/projects/quilt | |
78 | ||
1da177e4 | 79 | Andrew Morton's patch scripts: |
5b0ed2c6 XVP |
80 | http://www.zip.com.au/~akpm/linux/patches/ |
81 | Instead of these scripts, quilt is the recommended patch management | |
82 | tool (see above). | |
84da7c08 RD |
83 | |
84 | ||
1da177e4 LT |
85 | |
86 | 2) Describe your changes. | |
87 | ||
88 | Describe the technical detail of the change(s) your patch includes. | |
89 | ||
90 | Be as specific as possible. The WORST descriptions possible include | |
91 | things like "update driver X", "bug fix for driver X", or "this patch | |
92 | includes updates for subsystem X. Please apply." | |
93 | ||
94 | If your description starts to get long, that's a sign that you probably | |
95 | need to split up your patch. See #3, next. | |
96 | ||
97 | ||
98 | ||
99 | 3) Separate your changes. | |
100 | ||
5b0ed2c6 | 101 | Separate _logical changes_ into a single patch file. |
1da177e4 LT |
102 | |
103 | For example, if your changes include both bug fixes and performance | |
104 | enhancements for a single driver, separate those changes into two | |
105 | or more patches. If your changes include an API update, and a new | |
106 | driver which uses that new API, separate those into two patches. | |
107 | ||
108 | On the other hand, if you make a single change to numerous files, | |
109 | group those changes into a single patch. Thus a single logical change | |
110 | is contained within a single patch. | |
111 | ||
112 | If one patch depends on another patch in order for a change to be | |
113 | complete, that is OK. Simply note "this patch depends on patch X" | |
114 | in your patch description. | |
115 | ||
5b0ed2c6 XVP |
116 | If you cannot condense your patch set into a smaller set of patches, |
117 | then only post say 15 or so at a time and wait for review and integration. | |
118 | ||
119 | ||
1da177e4 LT |
120 | |
121 | 4) Select e-mail destination. | |
122 | ||
123 | Look through the MAINTAINERS file and the source code, and determine | |
124 | if your change applies to a specific subsystem of the kernel, with | |
125 | an assigned maintainer. If so, e-mail that person. | |
126 | ||
127 | If no maintainer is listed, or the maintainer does not respond, send | |
128 | your patch to the primary Linux kernel developer's mailing list, | |
129 | linux-kernel@vger.kernel.org. Most kernel developers monitor this | |
130 | e-mail list, and can comment on your changes. | |
131 | ||
5b0ed2c6 XVP |
132 | |
133 | Do not send more than 15 patches at once to the vger mailing lists!!! | |
134 | ||
135 | ||
1da177e4 | 136 | Linus Torvalds is the final arbiter of all changes accepted into the |
99ddcc7e LT |
137 | Linux kernel. His e-mail address is <torvalds@linux-foundation.org>. |
138 | He gets a lot of e-mail, so typically you should do your best to -avoid- | |
139 | sending him e-mail. | |
1da177e4 LT |
140 | |
141 | Patches which are bug fixes, are "obvious" changes, or similarly | |
142 | require little discussion should be sent or CC'd to Linus. Patches | |
143 | which require discussion or do not have a clear advantage should | |
144 | usually be sent first to linux-kernel. Only after the patch is | |
145 | discussed should the patch then be submitted to Linus. | |
146 | ||
1da177e4 LT |
147 | |
148 | ||
149 | 5) Select your CC (e-mail carbon copy) list. | |
150 | ||
151 | Unless you have a reason NOT to do so, CC linux-kernel@vger.kernel.org. | |
152 | ||
153 | Other kernel developers besides Linus need to be aware of your change, | |
154 | so that they may comment on it and offer code review and suggestions. | |
155 | linux-kernel is the primary Linux kernel developer mailing list. | |
156 | Other mailing lists are available for specific subsystems, such as | |
157 | USB, framebuffer devices, the VFS, the SCSI subsystem, etc. See the | |
158 | MAINTAINERS file for a mailing list that relates specifically to | |
159 | your change. | |
160 | ||
5b0ed2c6 XVP |
161 | Majordomo lists of VGER.KERNEL.ORG at: |
162 | <http://vger.kernel.org/vger-lists.html> | |
163 | ||
1caf1f0f PJ |
164 | If changes affect userland-kernel interfaces, please send |
165 | the MAN-PAGES maintainer (as listed in the MAINTAINERS file) | |
166 | a man-pages patch, or at least a notification of the change, | |
167 | so that some information makes its way into the manual pages. | |
168 | ||
1da177e4 LT |
169 | Even if the maintainer did not respond in step #4, make sure to ALWAYS |
170 | copy the maintainer when you change their code. | |
171 | ||
172 | For small patches you may want to CC the Trivial Patch Monkey | |
f62870db | 173 | trivial@kernel.org managed by Adrian Bunk; which collects "trivial" |
1da177e4 LT |
174 | patches. Trivial patches must qualify for one of the following rules: |
175 | Spelling fixes in documentation | |
8e9cb8fd | 176 | Spelling fixes which could break grep(1) |
1da177e4 LT |
177 | Warning fixes (cluttering with useless warnings is bad) |
178 | Compilation fixes (only if they are actually correct) | |
179 | Runtime fixes (only if they actually fix things) | |
8e9cb8fd | 180 | Removing use of deprecated functions/macros (eg. check_region) |
1da177e4 LT |
181 | Contact detail and documentation fixes |
182 | Non-portable code replaced by portable code (even in arch-specific, | |
183 | since people copy, as long as it's trivial) | |
8e9cb8fd | 184 | Any fix by the author/maintainer of the file (ie. patch monkey |
1da177e4 | 185 | in re-transmission mode) |
f62870db | 186 | URL: <http://www.kernel.org/pub/linux/kernel/people/bunk/trivial/> |
84da7c08 | 187 | |
1da177e4 LT |
188 | |
189 | ||
190 | ||
191 | 6) No MIME, no links, no compression, no attachments. Just plain text. | |
192 | ||
193 | Linus and other kernel developers need to be able to read and comment | |
194 | on the changes you are submitting. It is important for a kernel | |
195 | developer to be able to "quote" your changes, using standard e-mail | |
196 | tools, so that they may comment on specific portions of your code. | |
197 | ||
198 | For this reason, all patches should be submitting e-mail "inline". | |
199 | WARNING: Be wary of your editor's word-wrap corrupting your patch, | |
200 | if you choose to cut-n-paste your patch. | |
201 | ||
202 | Do not attach the patch as a MIME attachment, compressed or not. | |
203 | Many popular e-mail applications will not always transmit a MIME | |
204 | attachment as plain text, making it impossible to comment on your | |
205 | code. A MIME attachment also takes Linus a bit more time to process, | |
206 | decreasing the likelihood of your MIME-attached change being accepted. | |
207 | ||
208 | Exception: If your mailer is mangling patches then someone may ask | |
209 | you to re-send them using MIME. | |
210 | ||
211 | ||
683e91cb KK |
212 | WARNING: Some mailers like Mozilla send your messages with |
213 | ---- message header ---- | |
214 | Content-Type: text/plain; charset=us-ascii; format=flowed | |
215 | ---- message header ---- | |
216 | The problem is that "format=flowed" makes some of the mailers | |
217 | on receiving side to replace TABs with spaces and do similar | |
218 | changes. Thus the patches from you can look corrupted. | |
219 | ||
220 | To fix this just make your mozilla defaults/pref/mailnews.js file to look like: | |
221 | pref("mailnews.send_plaintext_flowed", false); // RFC 2646======= | |
222 | pref("mailnews.display.disable_format_flowed_support", true); | |
223 | ||
224 | ||
1da177e4 LT |
225 | |
226 | 7) E-mail size. | |
227 | ||
228 | When sending patches to Linus, always follow step #6. | |
229 | ||
230 | Large changes are not appropriate for mailing lists, and some | |
231 | maintainers. If your patch, uncompressed, exceeds 40 kB in size, | |
232 | it is preferred that you store your patch on an Internet-accessible | |
233 | server, and provide instead a URL (link) pointing to your patch. | |
234 | ||
235 | ||
236 | ||
237 | 8) Name your kernel version. | |
238 | ||
239 | It is important to note, either in the subject line or in the patch | |
240 | description, the kernel version to which this patch applies. | |
241 | ||
242 | If the patch does not apply cleanly to the latest kernel version, | |
243 | Linus will not apply it. | |
244 | ||
245 | ||
246 | ||
247 | 9) Don't get discouraged. Re-submit. | |
248 | ||
249 | After you have submitted your change, be patient and wait. If Linus | |
250 | likes your change and applies it, it will appear in the next version | |
251 | of the kernel that he releases. | |
252 | ||
253 | However, if your change doesn't appear in the next version of the | |
254 | kernel, there could be any number of reasons. It's YOUR job to | |
255 | narrow down those reasons, correct what was wrong, and submit your | |
256 | updated change. | |
257 | ||
258 | It is quite common for Linus to "drop" your patch without comment. | |
259 | That's the nature of the system. If he drops your patch, it could be | |
260 | due to | |
8e9cb8fd | 261 | * Your patch did not apply cleanly to the latest kernel version. |
1da177e4 | 262 | * Your patch was not sufficiently discussed on linux-kernel. |
8e9cb8fd PM |
263 | * A style issue (see section 2). |
264 | * An e-mail formatting issue (re-read this section). | |
265 | * A technical problem with your change. | |
266 | * He gets tons of e-mail, and yours got lost in the shuffle. | |
267 | * You are being annoying. | |
1da177e4 LT |
268 | |
269 | When in doubt, solicit comments on linux-kernel mailing list. | |
270 | ||
271 | ||
272 | ||
273 | 10) Include PATCH in the subject | |
274 | ||
275 | Due to high e-mail traffic to Linus, and to linux-kernel, it is common | |
276 | convention to prefix your subject line with [PATCH]. This lets Linus | |
277 | and other kernel developers more easily distinguish patches from other | |
278 | e-mail discussions. | |
279 | ||
280 | ||
281 | ||
282 | 11) Sign your work | |
283 | ||
284 | To improve tracking of who did what, especially with patches that can | |
285 | percolate to their final resting place in the kernel through several | |
286 | layers of maintainers, we've introduced a "sign-off" procedure on | |
287 | patches that are being emailed around. | |
288 | ||
289 | The sign-off is a simple line at the end of the explanation for the | |
290 | patch, which certifies that you wrote it or otherwise have the right to | |
291 | pass it on as a open-source patch. The rules are pretty simple: if you | |
292 | can certify the below: | |
293 | ||
cbd83da8 | 294 | Developer's Certificate of Origin 1.1 |
1da177e4 LT |
295 | |
296 | By making a contribution to this project, I certify that: | |
297 | ||
298 | (a) The contribution was created in whole or in part by me and I | |
299 | have the right to submit it under the open source license | |
300 | indicated in the file; or | |
301 | ||
302 | (b) The contribution is based upon previous work that, to the best | |
303 | of my knowledge, is covered under an appropriate open source | |
304 | license and I have the right under that license to submit that | |
305 | work with modifications, whether created in whole or in part | |
306 | by me, under the same open source license (unless I am | |
307 | permitted to submit under a different license), as indicated | |
308 | in the file; or | |
309 | ||
310 | (c) The contribution was provided directly to me by some other | |
311 | person who certified (a), (b) or (c) and I have not modified | |
312 | it. | |
313 | ||
cbd83da8 LT |
314 | (d) I understand and agree that this project and the contribution |
315 | are public and that a record of the contribution (including all | |
316 | personal information I submit with it, including my sign-off) is | |
317 | maintained indefinitely and may be redistributed consistent with | |
318 | this project or the open source license(s) involved. | |
319 | ||
1da177e4 LT |
320 | then you just add a line saying |
321 | ||
9fd5559c | 322 | Signed-off-by: Random J Developer <random@developer.example.org> |
1da177e4 | 323 | |
af45f32d GK |
324 | using your real name (sorry, no pseudonyms or anonymous contributions.) |
325 | ||
1da177e4 LT |
326 | Some people also put extra tags at the end. They'll just be ignored for |
327 | now, but you can do this to mark internal company procedures or just | |
328 | point out some special detail about the sign-off. | |
329 | ||
330 | ||
75f8426c | 331 | 12) The canonical patch format |
84da7c08 | 332 | |
75f8426c PJ |
333 | The canonical patch subject line is: |
334 | ||
d6b9acc0 | 335 | Subject: [PATCH 001/123] subsystem: summary phrase |
75f8426c PJ |
336 | |
337 | The canonical patch message body contains the following: | |
338 | ||
339 | - A "from" line specifying the patch author. | |
340 | ||
341 | - An empty line. | |
342 | ||
343 | - The body of the explanation, which will be copied to the | |
344 | permanent changelog to describe this patch. | |
345 | ||
346 | - The "Signed-off-by:" lines, described above, which will | |
347 | also go in the changelog. | |
348 | ||
349 | - A marker line containing simply "---". | |
350 | ||
351 | - Any additional comments not suitable for the changelog. | |
352 | ||
353 | - The actual patch (diff output). | |
354 | ||
355 | The Subject line format makes it very easy to sort the emails | |
356 | alphabetically by subject line - pretty much any email reader will | |
357 | support that - since because the sequence number is zero-padded, | |
358 | the numerical and alphabetic sort is the same. | |
359 | ||
d6b9acc0 PJ |
360 | The "subsystem" in the email's Subject should identify which |
361 | area or subsystem of the kernel is being patched. | |
362 | ||
363 | The "summary phrase" in the email's Subject should concisely | |
364 | describe the patch which that email contains. The "summary | |
365 | phrase" should not be a filename. Do not use the same "summary | |
366 | phrase" for every patch in a whole patch series. | |
367 | ||
368 | Bear in mind that the "summary phrase" of your email becomes | |
369 | a globally-unique identifier for that patch. It propagates | |
370 | all the way into the git changelog. The "summary phrase" may | |
371 | later be used in developer discussions which refer to the patch. | |
372 | People will want to google for the "summary phrase" to read | |
373 | discussion regarding that patch. | |
374 | ||
375 | A couple of example Subjects: | |
376 | ||
377 | Subject: [patch 2/5] ext2: improve scalability of bitmap searching | |
378 | Subject: [PATCHv2 001/207] x86: fix eflags tracking | |
75f8426c PJ |
379 | |
380 | The "from" line must be the very first line in the message body, | |
381 | and has the form: | |
382 | ||
383 | From: Original Author <author@example.com> | |
384 | ||
385 | The "from" line specifies who will be credited as the author of the | |
386 | patch in the permanent changelog. If the "from" line is missing, | |
387 | then the "From:" line from the email header will be used to determine | |
388 | the patch author in the changelog. | |
389 | ||
390 | The explanation body will be committed to the permanent source | |
391 | changelog, so should make sense to a competent reader who has long | |
392 | since forgotten the immediate details of the discussion that might | |
393 | have led to this patch. | |
394 | ||
395 | The "---" marker line serves the essential purpose of marking for patch | |
396 | handling tools where the changelog message ends. | |
397 | ||
398 | One good use for the additional comments after the "---" marker is for | |
399 | a diffstat, to show what files have changed, and the number of inserted | |
400 | and deleted lines per file. A diffstat is especially useful on bigger | |
401 | patches. Other comments relevant only to the moment or the maintainer, | |
402 | not suitable for the permanent changelog, should also go here. | |
58591e8a RD |
403 | Use diffstat options "-p 1 -w 70" so that filenames are listed from the |
404 | top of the kernel source tree and don't use too much horizontal space | |
405 | (easily fit in 80 columns, maybe with some indentation). | |
75f8426c PJ |
406 | |
407 | See more details on the proper patch format in the following | |
408 | references. | |
409 | ||
410 | ||
84da7c08 RD |
411 | |
412 | ||
1da177e4 LT |
413 | ----------------------------------- |
414 | SECTION 2 - HINTS, TIPS, AND TRICKS | |
415 | ----------------------------------- | |
416 | ||
417 | This section lists many of the common "rules" associated with code | |
418 | submitted to the kernel. There are always exceptions... but you must | |
419 | have a really good reason for doing so. You could probably call this | |
420 | section Linus Computer Science 101. | |
421 | ||
422 | ||
423 | ||
424 | 1) Read Documentation/CodingStyle | |
425 | ||
426 | Nuff said. If your code deviates too much from this, it is likely | |
427 | to be rejected without further review, and without comment. | |
428 | ||
429 | ||
430 | ||
431 | 2) #ifdefs are ugly | |
432 | ||
433 | Code cluttered with ifdefs is difficult to read and maintain. Don't do | |
434 | it. Instead, put your ifdefs in a header, and conditionally define | |
435 | 'static inline' functions, or macros, which are used in the code. | |
436 | Let the compiler optimize away the "no-op" case. | |
437 | ||
438 | Simple example, of poor code: | |
439 | ||
440 | dev = alloc_etherdev (sizeof(struct funky_private)); | |
441 | if (!dev) | |
442 | return -ENODEV; | |
443 | #ifdef CONFIG_NET_FUNKINESS | |
444 | init_funky_net(dev); | |
445 | #endif | |
446 | ||
447 | Cleaned-up example: | |
448 | ||
449 | (in header) | |
450 | #ifndef CONFIG_NET_FUNKINESS | |
451 | static inline void init_funky_net (struct net_device *d) {} | |
452 | #endif | |
453 | ||
454 | (in the code itself) | |
455 | dev = alloc_etherdev (sizeof(struct funky_private)); | |
456 | if (!dev) | |
457 | return -ENODEV; | |
458 | init_funky_net(dev); | |
459 | ||
460 | ||
461 | ||
462 | 3) 'static inline' is better than a macro | |
463 | ||
464 | Static inline functions are greatly preferred over macros. | |
465 | They provide type safety, have no length limitations, no formatting | |
466 | limitations, and under gcc they are as cheap as macros. | |
467 | ||
468 | Macros should only be used for cases where a static inline is clearly | |
469 | suboptimal [there a few, isolated cases of this in fast paths], | |
470 | or where it is impossible to use a static inline function [such as | |
471 | string-izing]. | |
472 | ||
473 | 'static inline' is preferred over 'static __inline__', 'extern inline', | |
474 | and 'extern __inline__'. | |
475 | ||
476 | ||
477 | ||
478 | 4) Don't over-design. | |
479 | ||
480 | Don't try to anticipate nebulous future cases which may or may not | |
84da7c08 | 481 | be useful: "Make it as simple as you can, and no simpler." |
1da177e4 | 482 | |
5b0ed2c6 XVP |
483 | |
484 | ||
485 | ---------------------- | |
486 | SECTION 3 - REFERENCES | |
487 | ---------------------- | |
488 | ||
489 | Andrew Morton, "The perfect patch" (tpp). | |
490 | <http://www.zip.com.au/~akpm/linux/patches/stuff/tpp.txt> | |
491 | ||
8e9cb8fd | 492 | Jeff Garzik, "Linux kernel patch submission format". |
5b0ed2c6 XVP |
493 | <http://linux.yyz.us/patch-format.html> |
494 | ||
8e9cb8fd | 495 | Greg Kroah-Hartman, "How to piss off a kernel subsystem maintainer". |
5b0ed2c6 XVP |
496 | <http://www.kroah.com/log/2005/03/31/> |
497 | <http://www.kroah.com/log/2005/07/08/> | |
498 | <http://www.kroah.com/log/2005/10/19/> | |
e1b114ee | 499 | <http://www.kroah.com/log/2006/01/11/> |
5b0ed2c6 | 500 | |
bc7455fa | 501 | NO!!!! No more huge patch bombs to linux-kernel@vger.kernel.org people! |
5b0ed2c6 XVP |
502 | <http://marc.theaimsgroup.com/?l=linux-kernel&m=112112749912944&w=2> |
503 | ||
8e9cb8fd | 504 | Kernel Documentation/CodingStyle: |
5b0ed2c6 XVP |
505 | <http://sosdg.org/~coywolf/lxr/source/Documentation/CodingStyle> |
506 | ||
8e9cb8fd | 507 | Linus Torvalds's mail on the canonical patch format: |
5b0ed2c6 XVP |
508 | <http://lkml.org/lkml/2005/4/7/183> |
509 | -- |