Based on kernel version 2.6.26. Page generated on 2008-07-16 21:13 EST.
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 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. 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 40 SRCTREE= linux-2.6 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 53 MYSRC= /devel/linux-2.6 54 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 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 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>. 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 72 logical stages. This will facilitate easier reviewing by other 73 kernel developers, very important if you want your patch accepted. 74 There are a number of scripts which can aid in this: 75 76 Quilt: 77 http://savannah.nongnu.org/projects/quilt 78 79 Andrew Morton's patch scripts: 80 http://www.zip.com.au/~akpm/linux/patches/ 81 Instead of these scripts, quilt is the recommended patch management 82 tool (see above). 83 84 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 101 Separate _logical changes_ into a single patch file. 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 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 120 121 4) Style check your changes. 122 123 Check your patch for basic style violations, details of which can be 124 found in Documentation/CodingStyle. Failure to do so simply wastes 125 the reviewers time and will get your patch rejected, probably 126 without even being read. 127 128 At a minimum you should check your patches with the patch style 129 checker prior to submission (scripts/checkpatch.pl). You should 130 be able to justify all violations that remain in your patch. 131 132 133 134 5) Select e-mail destination. 135 136 Look through the MAINTAINERS file and the source code, and determine 137 if your change applies to a specific subsystem of the kernel, with 138 an assigned maintainer. If so, e-mail that person. 139 140 If no maintainer is listed, or the maintainer does not respond, send 141 your patch to the primary Linux kernel developer's mailing list, 142 linux-kernel[AT]vger.kernel.org[DOT] Most kernel developers monitor this 143 e-mail list, and can comment on your changes. 144 145 146 Do not send more than 15 patches at once to the vger mailing lists!!! 147 148 149 Linus Torvalds is the final arbiter of all changes accepted into the 150 Linux kernel. His e-mail address is <torvalds[AT]linux-foundation.org>[DOT] 151 He gets a lot of e-mail, so typically you should do your best to -avoid- 152 sending him e-mail. 153 154 Patches which are bug fixes, are "obvious" changes, or similarly 155 require little discussion should be sent or CC'd to Linus. Patches 156 which require discussion or do not have a clear advantage should 157 usually be sent first to linux-kernel. Only after the patch is 158 discussed should the patch then be submitted to Linus. 159 160 161 162 6) Select your CC (e-mail carbon copy) list. 163 164 Unless you have a reason NOT to do so, CC linux-kernel[AT]vger.kernel.org[DOT] 165 166 Other kernel developers besides Linus need to be aware of your change, 167 so that they may comment on it and offer code review and suggestions. 168 linux-kernel is the primary Linux kernel developer mailing list. 169 Other mailing lists are available for specific subsystems, such as 170 USB, framebuffer devices, the VFS, the SCSI subsystem, etc. See the 171 MAINTAINERS file for a mailing list that relates specifically to 172 your change. 173 174 Majordomo lists of VGER.KERNEL.ORG at: 175 <http://vger.kernel.org/vger-lists.html> 176 177 If changes affect userland-kernel interfaces, please send 178 the MAN-PAGES maintainer (as listed in the MAINTAINERS file) 179 a man-pages patch, or at least a notification of the change, 180 so that some information makes its way into the manual pages. 181 182 Even if the maintainer did not respond in step #4, make sure to ALWAYS 183 copy the maintainer when you change their code. 184 185 For small patches you may want to CC the Trivial Patch Monkey 186 trivial[AT]kernel[DOT]org managed by Adrian Bunk; which collects "trivial" 187 patches. Trivial patches must qualify for one of the following rules: 188 Spelling fixes in documentation 189 Spelling fixes which could break grep(1) 190 Warning fixes (cluttering with useless warnings is bad) 191 Compilation fixes (only if they are actually correct) 192 Runtime fixes (only if they actually fix things) 193 Removing use of deprecated functions/macros (eg. check_region) 194 Contact detail and documentation fixes 195 Non-portable code replaced by portable code (even in arch-specific, 196 since people copy, as long as it's trivial) 197 Any fix by the author/maintainer of the file (ie. patch monkey 198 in re-transmission mode) 199 URL: <http://www.kernel.org/pub/linux/kernel/people/bunk/trivial/> 200 201 202 203 7) No MIME, no links, no compression, no attachments. Just plain text. 204 205 Linus and other kernel developers need to be able to read and comment 206 on the changes you are submitting. It is important for a kernel 207 developer to be able to "quote" your changes, using standard e-mail 208 tools, so that they may comment on specific portions of your code. 209 210 For this reason, all patches should be submitting e-mail "inline". 211 WARNING: Be wary of your editor's word-wrap corrupting your patch, 212 if you choose to cut-n-paste your patch. 213 214 Do not attach the patch as a MIME attachment, compressed or not. 215 Many popular e-mail applications will not always transmit a MIME 216 attachment as plain text, making it impossible to comment on your 217 code. A MIME attachment also takes Linus a bit more time to process, 218 decreasing the likelihood of your MIME-attached change being accepted. 219 220 Exception: If your mailer is mangling patches then someone may ask 221 you to re-send them using MIME. 222 223 See Documentation/email-clients.txt for hints about configuring 224 your e-mail client so that it sends your patches untouched. 225 226 8) E-mail size. 227 228 When sending patches to Linus, always follow step #7. 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 9) 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 10) 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 261 * Your patch did not apply cleanly to the latest kernel version. 262 * Your patch was not sufficiently discussed on linux-kernel. 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. 268 269 When in doubt, solicit comments on linux-kernel mailing list. 270 271 272 273 11) 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 12) 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 294 Developer's Certificate of Origin 1.1 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 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 320 then you just add a line saying 321 322 Signed-off-by: Random J Developer <random[AT]developer.example[DOT]org> 323 324 using your real name (sorry, no pseudonyms or anonymous contributions.) 325 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 331 13) When to use Acked-by: and Cc: 332 333 The Signed-off-by: tag indicates that the signer was involved in the 334 development of the patch, or that he/she was in the patch's delivery path. 335 336 If a person was not directly involved in the preparation or handling of a 337 patch but wishes to signify and record their approval of it then they can 338 arrange to have an Acked-by: line added to the patch's changelog. 339 340 Acked-by: is often used by the maintainer of the affected code when that 341 maintainer neither contributed to nor forwarded the patch. 342 343 Acked-by: is not as formal as Signed-off-by:. It is a record that the acker 344 has at least reviewed the patch and has indicated acceptance. Hence patch 345 mergers will sometimes manually convert an acker's "yep, looks good to me" 346 into an Acked-by:. 347 348 Acked-by: does not necessarily indicate acknowledgement of the entire patch. 349 For example, if a patch affects multiple subsystems and has an Acked-by: from 350 one subsystem maintainer then this usually indicates acknowledgement of just 351 the part which affects that maintainer's code. Judgement should be used here. 352 When in doubt people should refer to the original discussion in the mailing 353 list archives. 354 355 If a person has had the opportunity to comment on a patch, but has not 356 provided such comments, you may optionally add a "Cc:" tag to the patch. 357 This is the only tag which might be added without an explicit action by the 358 person it names. This tag documents that potentially interested parties 359 have been included in the discussion 360 361 362 14) Using Test-by: and Reviewed-by: 363 364 A Tested-by: tag indicates that the patch has been successfully tested (in 365 some environment) by the person named. This tag informs maintainers that 366 some testing has been performed, provides a means to locate testers for 367 future patches, and ensures credit for the testers. 368 369 Reviewed-by:, instead, indicates that the patch has been reviewed and found 370 acceptable according to the Reviewer's Statement: 371 372 Reviewer's statement of oversight 373 374 By offering my Reviewed-by: tag, I state that: 375 376 (a) I have carried out a technical review of this patch to 377 evaluate its appropriateness and readiness for inclusion into 378 the mainline kernel. 379 380 (b) Any problems, concerns, or questions relating to the patch 381 have been communicated back to the submitter. I am satisfied 382 with the submitter's response to my comments. 383 384 (c) While there may be things that could be improved with this 385 submission, I believe that it is, at this time, (1) a 386 worthwhile modification to the kernel, and (2) free of known 387 issues which would argue against its inclusion. 388 389 (d) While I have reviewed the patch and believe it to be sound, I 390 do not (unless explicitly stated elsewhere) make any 391 warranties or guarantees that it will achieve its stated 392 purpose or function properly in any given situation. 393 394 A Reviewed-by tag is a statement of opinion that the patch is an 395 appropriate modification of the kernel without any remaining serious 396 technical issues. Any interested reviewer (who has done the work) can 397 offer a Reviewed-by tag for a patch. This tag serves to give credit to 398 reviewers and to inform maintainers of the degree of review which has been 399 done on the patch. Reviewed-by: tags, when supplied by reviewers known to 400 understand the subject area and to perform thorough reviews, will normally 401 increase the liklihood of your patch getting into the kernel. 402 403 404 15) The canonical patch format 405 406 The canonical patch subject line is: 407 408 Subject: [PATCH 001/123] subsystem: summary phrase 409 410 The canonical patch message body contains the following: 411 412 - A "from" line specifying the patch author. 413 414 - An empty line. 415 416 - The body of the explanation, which will be copied to the 417 permanent changelog to describe this patch. 418 419 - The "Signed-off-by:" lines, described above, which will 420 also go in the changelog. 421 422 - A marker line containing simply "---". 423 424 - Any additional comments not suitable for the changelog. 425 426 - The actual patch (diff output). 427 428 The Subject line format makes it very easy to sort the emails 429 alphabetically by subject line - pretty much any email reader will 430 support that - since because the sequence number is zero-padded, 431 the numerical and alphabetic sort is the same. 432 433 The "subsystem" in the email's Subject should identify which 434 area or subsystem of the kernel is being patched. 435 436 The "summary phrase" in the email's Subject should concisely 437 describe the patch which that email contains. The "summary 438 phrase" should not be a filename. Do not use the same "summary 439 phrase" for every patch in a whole patch series (where a "patch 440 series" is an ordered sequence of multiple, related patches). 441 442 Bear in mind that the "summary phrase" of your email becomes 443 a globally-unique identifier for that patch. It propagates 444 all the way into the git changelog. The "summary phrase" may 445 later be used in developer discussions which refer to the patch. 446 People will want to google for the "summary phrase" to read 447 discussion regarding that patch. 448 449 A couple of example Subjects: 450 451 Subject: [patch 2/5] ext2: improve scalability of bitmap searching 452 Subject: [PATCHv2 001/207] x86: fix eflags tracking 453 454 The "from" line must be the very first line in the message body, 455 and has the form: 456 457 From: Original Author <author[AT]example[DOT]com> 458 459 The "from" line specifies who will be credited as the author of the 460 patch in the permanent changelog. If the "from" line is missing, 461 then the "From:" line from the email header will be used to determine 462 the patch author in the changelog. 463 464 The explanation body will be committed to the permanent source 465 changelog, so should make sense to a competent reader who has long 466 since forgotten the immediate details of the discussion that might 467 have led to this patch. 468 469 The "---" marker line serves the essential purpose of marking for patch 470 handling tools where the changelog message ends. 471 472 One good use for the additional comments after the "---" marker is for 473 a diffstat, to show what files have changed, and the number of inserted 474 and deleted lines per file. A diffstat is especially useful on bigger 475 patches. Other comments relevant only to the moment or the maintainer, 476 not suitable for the permanent changelog, should also go here. 477 Use diffstat options "-p 1 -w 70" so that filenames are listed from the 478 top of the kernel source tree and don't use too much horizontal space 479 (easily fit in 80 columns, maybe with some indentation). 480 481 See more details on the proper patch format in the following 482 references. 483 484 485 486 487 ----------------------------------- 488 SECTION 2 - HINTS, TIPS, AND TRICKS 489 ----------------------------------- 490 491 This section lists many of the common "rules" associated with code 492 submitted to the kernel. There are always exceptions... but you must 493 have a really good reason for doing so. You could probably call this 494 section Linus Computer Science 101. 495 496 497 498 1) Read Documentation/CodingStyle 499 500 Nuff said. If your code deviates too much from this, it is likely 501 to be rejected without further review, and without comment. 502 503 One significant exception is when moving code from one file to 504 another -- in this case you should not modify the moved code at all in 505 the same patch which moves it. This clearly delineates the act of 506 moving the code and your changes. This greatly aids review of the 507 actual differences and allows tools to better track the history of 508 the code itself. 509 510 Check your patches with the patch style checker prior to submission 511 (scripts/checkpatch.pl). The style checker should be viewed as 512 a guide not as the final word. If your code looks better with 513 a violation then its probably best left alone. 514 515 The checker reports at three levels: 516 - ERROR: things that are very likely to be wrong 517 - WARNING: things requiring careful review 518 - CHECK: things requiring thought 519 520 You should be able to justify all violations that remain in your 521 patch. 522 523 524 525 2) #ifdefs are ugly 526 527 Code cluttered with ifdefs is difficult to read and maintain. Don't do 528 it. Instead, put your ifdefs in a header, and conditionally define 529 'static inline' functions, or macros, which are used in the code. 530 Let the compiler optimize away the "no-op" case. 531 532 Simple example, of poor code: 533 534 dev = alloc_etherdev (sizeof(struct funky_private)); 535 if (!dev) 536 return -ENODEV; 537 #ifdef CONFIG_NET_FUNKINESS 538 init_funky_net(dev); 539 #endif 540 541 Cleaned-up example: 542 543 (in header) 544 #ifndef CONFIG_NET_FUNKINESS 545 static inline void init_funky_net (struct net_device *d) {} 546 #endif 547 548 (in the code itself) 549 dev = alloc_etherdev (sizeof(struct funky_private)); 550 if (!dev) 551 return -ENODEV; 552 init_funky_net(dev); 553 554 555 556 3) 'static inline' is better than a macro 557 558 Static inline functions are greatly preferred over macros. 559 They provide type safety, have no length limitations, no formatting 560 limitations, and under gcc they are as cheap as macros. 561 562 Macros should only be used for cases where a static inline is clearly 563 suboptimal [there are a few, isolated cases of this in fast paths], 564 or where it is impossible to use a static inline function [such as 565 string-izing]. 566 567 'static inline' is preferred over 'static __inline__', 'extern inline', 568 and 'extern __inline__'. 569 570 571 572 4) Don't over-design. 573 574 Don't try to anticipate nebulous future cases which may or may not 575 be useful: "Make it as simple as you can, and no simpler." 576 577 578 579 ---------------------- 580 SECTION 3 - REFERENCES 581 ---------------------- 582 583 Andrew Morton, "The perfect patch" (tpp). 584 <http://www.zip.com.au/~akpm/linux/patches/stuff/tpp.txt> 585 586 Jeff Garzik, "Linux kernel patch submission format". 587 <http://linux.yyz.us/patch-format.html> 588 589 Greg Kroah-Hartman, "How to piss off a kernel subsystem maintainer". 590 <http://www.kroah.com/log/2005/03/31/> 591 <http://www.kroah.com/log/2005/07/08/> 592 <http://www.kroah.com/log/2005/10/19/> 593 <http://www.kroah.com/log/2006/01/11/> 594 595 NO!!!! No more huge patch bombs to linux-kernel[AT]vger.kernel[DOT]org people! 596 <http://marc.theaimsgroup.com/?l=linux-kernel&m=112112749912944&w=2> 597 598 Kernel Documentation/CodingStyle: 599 <http://users.sosdg.org/~qiyong/lxr/source/Documentation/CodingStyle> 600 601 Linus Torvalds's mail on the canonical patch format: 602 <http://lkml.org/lkml/2005/4/7/183> 603 --
