1 .. _process_howto:
2
3 HOWTO do Linux kernel development
4 =================================
5
6 This is the be-all, end-all document on this t
7 instructions on how to become a Linux kernel d
8 to work with the Linux kernel development comm
9 contain anything related to the technical aspe
10 but will help point you in the right direction
11
12 If anything in this document becomes out of da
13 to the maintainer of this file, who is listed
14 document.
15
16
17 Introduction
18 ------------
19
20 So, you want to learn how to become a Linux ke
21 have been told by your manager, "Go write a Li
22 device." This document's goal is to teach you
23 know to achieve this by describing the process
24 and hints on how to work with the community.
25 explain some of the reasons why the community
26
27 The kernel is written mostly in C, with some a
28 parts written in assembly. A good understandin
29 kernel development. Assembly (any architectur
30 you plan to do low-level development for that
31 are not a good substitute for a solid C educat
32 experience, the following books are good for,
33
34 - "The C Programming Language" by Kernighan a
35 - "Practical C Programming" by Steve Oualline
36 - "C: A Reference Manual" by Harbison and St
37
38 The kernel is written using GNU C and the GNU
39 adheres to the ISO C11 standard, it uses a num
40 not featured in the standard. The kernel is a
41 environment, with no reliance on the standard
42 portions of the C standard are not supported.
43 divisions and floating point are not allowed.
44 difficult to understand the assumptions the ke
45 and the extensions that it uses, and unfortuna
46 definitive reference for them. Please check t
47 gcc`) for some information on them.
48
49 Please remember that you are trying to learn h
50 existing development community. It is a diver
51 high standards for coding, style and procedure
52 been created over time based on what they have
53 such a large and geographically dispersed team
54 possible about these standards ahead of time,
55 documented; do not expect people to adapt to y
56 of doing things.
57
58
59 Legal Issues
60 ------------
61
62 The Linux kernel source code is released under
63 COPYING in the main directory of the source tr
64 rules and how to use `SPDX <https://spdx.org/>
65 described in :ref:`Documentation/process/licen
66 If you have further questions about the licens
67 not ask on the Linux kernel mailing list. The
68 not lawyers, and you should not rely on their
69
70 For common questions and answers about the GPL
71
72 https://www.gnu.org/licenses/gpl-faq.h
73
74
75 Documentation
76 -------------
77
78 The Linux kernel source tree has a large range
79 invaluable for learning how to interact with t
80 new features are added to the kernel, it is re
81 documentation files are also added which expla
82 When a kernel change causes the interface that
83 userspace to change, it is recommended that yo
84 a patch to the manual pages explaining the cha
85 maintainer at alx@kernel.org, and CC the list
86
87 Here is a list of files that are in the kernel
88 required reading:
89
90 :ref:`Documentation/admin-guide/README.rst <
91 This file gives a short background on the
92 what is necessary to do to configure and b
93 who are new to the kernel should start her
94
95 :ref:`Documentation/process/changes.rst <cha
96 This file gives a list of the minimum leve
97 packages that are necessary to build and r
98 successfully.
99
100 :ref:`Documentation/process/coding-style.rst
101 This describes the Linux kernel coding sty
102 rationale behind it. All new code is expec
103 guidelines in this document. Most maintain
104 patches if these rules are followed, and m
105 review code if it is in the proper style.
106
107 :ref:`Documentation/process/submitting-patch
108 This file describes in explicit detail how
109 and send a patch, including (but not limit
110
111 - Email contents
112 - Email format
113 - Who to send it to
114
115 Following these rules will not guarantee s
116 subject to scrutiny for content and style)
117 will almost always prevent it.
118
119 Other excellent descriptions of how to cre
120
121 "The Perfect Patch"
122 https://www.ozlabs.org/~akpm/s
123
124 "Linux kernel patch submission format"
125 https://web.archive.org/web/20
126
127 :ref:`Documentation/process/stable-api-nonse
128 This file describes the rationale behind t
129 not have a stable API within the kernel, i
130
131 - Subsystem shim-layers (for compatibili
132 - Driver portability between Operating S
133 - Mitigating rapid change within the ker
134 preventing rapid change)
135
136 This document is crucial for understanding
137 philosophy and is very important for peopl
138 development on other Operating Systems.
139
140 :ref:`Documentation/process/security-bugs.rs
141 If you feel you have found a security prob
142 please follow the steps in this document t
143 developers, and help solve the issue.
144
145 :ref:`Documentation/process/management-style
146 This document describes how Linux kernel m
147 shared ethos behind their methodologies.
148 for anyone new to kernel development (or a
149 it), as it resolves a lot of common miscon
150 about the unique behavior of kernel mainta
151
152 :ref:`Documentation/process/stable-kernel-ru
153 This file describes the rules on how the s
154 happen, and what to do if you want to get
155 releases.
156
157 :ref:`Documentation/process/kernel-docs.rst
158 A list of external documentation that pert
159 development. Please consult this list if
160 are looking for within the in-kernel docum
161
162 :ref:`Documentation/process/applying-patches
163 A good introduction describing exactly wha
164 apply it to the different development bran
165
166 The kernel also has a large number of document
167 automatically generated from the source code i
168 ReStructuredText markups (ReST), like this one
169 full description of the in-kernel API, and rul
170 locking properly.
171
172 All such documents can be generated as PDF or
173
174 make pdfdocs
175 make htmldocs
176
177 respectively from the main kernel source direc
178
179 The documents that uses ReST markup will be ge
180 They can also be generated on LaTeX and ePub f
181
182 make latexdocs
183 make epubdocs
184
185 Becoming A Kernel Developer
186 ---------------------------
187
188 If you do not know anything about Linux kernel
189 look at the Linux KernelNewbies project:
190
191 https://kernelnewbies.org
192
193 It consists of a helpful mailing list where yo
194 of basic kernel development question (make sur
195 first, before asking something that has alread
196 past.) It also has an IRC channel that you ca
197 real-time, and a lot of helpful documentation
198 learning about Linux kernel development.
199
200 The website has basic information about code o
201 and current projects (both in-tree and out-of-
202 some basic logistical information, like how to
203 apply a patch.
204
205 If you do not know where you want to start, bu
206 some task to start doing to join into the kern
207 go to the Linux Kernel Janitor's project:
208
209 https://kernelnewbies.org/KernelJanito
210
211 It is a great place to start. It describes a
212 problems that need to be cleaned up and fixed
213 source tree. Working with the developers in c
214 will learn the basics of getting your patch in
215 and possibly be pointed in the direction of wh
216 you do not already have an idea.
217
218 Before making any actual modifications to the
219 imperative to understand how the code in quest
220 purpose, nothing is better than reading throug
221 bits are commented well), perhaps even with th
222 tools. One such tool that is particularly rec
223 Cross-Reference project, which is able to pres
224 self-referential, indexed webpage format. An e
225 repository of the kernel code may be found at:
226
227 https://elixir.bootlin.com/
228
229
230 The development process
231 -----------------------
232
233 Linux kernel development process currently con
234 main kernel "branches" and lots of different s
235 branches. These different branches are:
236
237 - Linus's mainline tree
238 - Various stable trees with multiple major n
239 - Subsystem-specific trees
240 - linux-next integration testing tree
241
242 Mainline tree
243 ~~~~~~~~~~~~~
244
245 The mainline tree is maintained by Linus Torva
246 https://kernel.org or in the repo. Its develo
247
248 - As soon as a new kernel is released a two
249 during this period of time maintainers can
250 Linus, usually the patches that have alrea
251 linux-next for a few weeks. The preferred
252 is using git (the kernel's source manageme
253 can be found at https://git-scm.com/) but
254 fine.
255 - After two weeks a -rc1 kernel is released
256 new kernel as rock solid as possible. Mos
257 should fix a regression. Bugs that have a
258 regressions, so only push these kinds of f
259 Please note that a whole new driver (or fi
260 after -rc1 because there is no risk of cau
261 change as long as the change is self-conta
262 outside of the code that is being added.
263 patches to Linus after -rc1 is released, b
264 sent to a public mailing list for review.
265 - A new -rc is released whenever Linus deems
266 be in a reasonably sane state adequate for
267 release a new -rc kernel every week.
268 - Process continues until the kernel is cons
269 process should last around 6 weeks.
270
271 It is worth mentioning what Andrew Morton wrot
272 mailing list about kernel releases:
273
274 *"Nobody knows when a kernel will be r
275 released according to perceived bug st
276 preconceived timeline."*
277
278 Various stable trees with multiple major numbe
279 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
280
281 Kernels with 3-part versions are -stable kerne
282 relatively small and critical fixes for securi
283 regressions discovered in a given major mainli
284 in a major stable series increments the third
285 number, keeping the first two parts the same.
286
287 This is the recommended branch for users who w
288 kernel and are not interested in helping test
289 versions.
290
291 Stable trees are maintained by the "stable" te<
292 are released as needs dictate. The normal rel
293 two weeks, but it can be longer if there are n
294 security-related problem, instead, can cause a
295 instantly.
296
297 The file :ref:`Documentation/process/stable-ke
298 in the kernel tree documents what kinds of cha
299 the -stable tree, and how the release process
300
301 Subsystem-specific trees
302 ~~~~~~~~~~~~~~~~~~~~~~~~
303
304 The maintainers of the various kernel subsyste
305 kernel subsystem developers --- expose their c
306 development in source repositories. That way,
307 happening in the different areas of the kernel
308 development is rapid, a developer may be asked
309 onto such a subsystem kernel tree so that conf
310 submission and other already ongoing work are
311
312 Most of these repositories are git trees, but
313 in use, or patch queues being published as qui
314 these subsystem repositories are listed in the
315 of them can be browsed at https://git.kernel.o
316
317 Before a proposed patch is committed to such a
318 subject to review which primarily happens on m
319 respective section below). For several kernel
320 process is tracked with the tool patchwork. P
321 interface which shows patch postings, any comm
322 revisions to it, and maintainers can mark patc
323 accepted, or rejected. Most of these patchwor
324 https://patchwork.kernel.org/.
325
326 linux-next integration testing tree
327 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
328
329 Before updates from subsystem trees are merged
330 they need to be integration-tested. For this
331 testing repository exists into which virtually
332 pulled on an almost daily basis:
333
334 https://git.kernel.org/pub/scm/linux/k
335
336 This way, the linux-next gives a summary outlo
337 expected to go into the mainline kernel at the
338 Adventurous testers are very welcome to runtim
339
340
341 Bug Reporting
342 -------------
343
344 The file 'Documentation/admin-guide/reporting-
345 source directory describes how to report a pos
346 what kind of information is needed by the kern
347 down the problem.
348
349
350 Managing bug reports
351 --------------------
352
353 One of the best ways to put into practice your
354 bugs reported by other people. Not only will y
355 more stable, but you'll also learn to fix real
356 improve your skills, and other developers will
357 Fixing bugs is one of the best ways to get mer
358 because not many people like wasting time fixi
359
360 To work on already reported bug reports, find
361 Check the MAINTAINERS file where bugs for that
362 it will be a mailing list, rarely a bugtracker
363 place for recent reports and help where you se
364 https://bugzilla.kernel.org for bug reports; o
365 use it actively for reporting or tracking, nev
366 kernel get filed there.
367
368
369 Mailing lists
370 -------------
371
372 As some of the above documents describe, the m
373 developers participate on the Linux Kernel Mai
374 to subscribe and unsubscribe from the list can
375
376 https://subspace.kernel.org/subscribin
377
378 There are archives of the mailing list on the
379 places. Use a search engine to find these arc
380
381 https://lore.kernel.org/linux-kernel/
382
383 It is highly recommended that you search the a
384 you want to bring up, before you post it to th
385 already discussed in detail are only recorded
386 archives.
387
388 Most of the individual kernel subsystems also
389 mailing list where they do their development e
390 MAINTAINERS file for a list of what these list
391 groups.
392
393 Many of the lists are hosted on kernel.org. In
394 found at:
395
396 https://subspace.kernel.org
397
398 Please remember to follow good behavioral habi
399 Though a bit cheesy, the following URL has som
400 interacting with the list (or any list):
401
402 https://subspace.kernel.org/etiquette.
403
404 If multiple people respond to your mail, the C
405 get pretty large. Don't remove anybody from th
406 reason, or don't reply only to the list addres
407 mail twice, one from the sender and the one fr
408 to tune that by adding fancy mail-headers, peo
409
410 Remember to keep the context and the attributi
411 keep the "John Kernelhacker wrote ...:" lines
412 add your statements between the individual quo
413 writing at the top of the mail.
414
415 If you add patches to your mail, make sure the
416 as stated in :ref:`Documentation/process/submi
417 Kernel developers don't want to deal with
418 attachments or compressed patches; they may wa
419 individual lines of your patch, which works on
420 use a mail program that does not mangle spaces
421 good first test is to send the mail to yoursel
422 own patch by yourself. If that doesn't work, g
423 or change it until it works.
424
425 Above all, please remember to show respect to
426
427
428 Working with the community
429 --------------------------
430
431 The goal of the kernel community is to provide
432 there is. When you submit a patch for accepta
433 on its technical merits and those alone. So,
434 expecting?
435
436 - criticism
437 - comments
438 - requests for change
439 - requests for justification
440 - silence
441
442 Remember, this is part of getting your patch i
443 to be able to take criticism and comments abou
444 them at a technical level and either rework yo
445 clear and concise reasoning as to why those ch
446 If there are no responses to your posting, wai
447 again, sometimes things get lost in the huge v
448
449 What should you not do?
450
451 - expect your patch to be accepted without q
452 - become defensive
453 - ignore comments
454 - resubmit the patch without making any of t
455
456 In a community that is looking for the best te
457 there will always be differing opinions on how
458 You have to be cooperative, and willing to ada
459 the kernel. Or at least be willing to prove y
460 Remember, being wrong is acceptable as long as
461 toward a solution that is right.
462
463 It is normal that the answers to your first pa
464 of a dozen things you should correct. This do
465 patch will not be accepted, and it is **not**
466 personally. Simply correct all issues raised
467 resend it.
468
469
470 Differences between the kernel community and c
471 ----------------------------------------------
472
473 The kernel community works differently than mo
474 development environments. Here are a list of
475 do to avoid problems:
476
477 Good things to say regarding your proposed c
478
479 - "This solves multiple problems."
480 - "This deletes 2000 lines of code."
481 - "Here is a patch that explains what I am
482 - "I tested it on 5 different architecture
483 - "Here is a series of small patches that.
484 - "This increases performance on typical m
485
486 Bad things you should avoid saying:
487
488 - "We did it this way in AIX/ptx/Solaris,
489 good..."
490 - "I've being doing this for 20 years, so.
491 - "This is required for my company to make
492 - "This is for our Enterprise product line
493 - "Here is my 1000 page design document th
494 - "I've been working on this for 6 months.
495 - "Here's a 5000 line patch that..."
496 - "I rewrote all of the current mess, and
497 - "I have a deadline, and this patch needs
498
499 Another way the kernel community is different
500 software engineering work environments is the
501 interaction. One benefit of using email and i
502 communication is the lack of discrimination ba
503 The Linux kernel work environment is accepting
504 because all you are is an email address. The
505 helps to level the playing field because you c
506 a person's name. A man may be named Andrea and
507 Most women who have worked in the Linux kernel
508 opinion have had positive experiences.
509
510 The language barrier can cause problems for so
511 comfortable with English. A good grasp of the
512 order to get ideas across properly on mailing
513 recommended that you check your emails to make
514 English before sending them.
515
516
517 Break up your changes
518 ---------------------
519
520 The Linux kernel community does not gladly acc
521 dropped on it all at once. The changes need t
522 discussed, and broken up into tiny, individual
523 the exact opposite of what companies are used
524 should also be introduced very early in the de
525 you can receive feedback on what you are doing
526 community feel that you are working with them,
527 as a dumping ground for your feature. However
528 one time to a mailing list, your patch series
529 that almost all of the time.
530
531 The reasons for breaking things up are the fol
532
533 1) Small patches increase the likelihood that
534 applied, since they don't take much time or
535 correctness. A 5 line patch can be applied
536 barely a second glance. However, a 500 line
537 review for correctness (the time it takes i
538 proportional to the size of the patch, or s
539
540 Small patches also make it very easy to deb
541 wrong. It's much easier to back out patche
542 to dissect a very large patch after it's be
543 something).
544
545 2) It's important not only to send small patch
546 and simplify (or simply re-order) patches b
547
548 Here is an analogy from kernel developer Al Vi
549
550 *"Think of a teacher grading homework
551 teacher does not want to see the stude
552 before they came up with the solution.
553 cleanest, most elegant answer. A good
554 would never submit her intermediate wo
555 solution.*
556
557 *The same is true of kernel developmen
558 reviewers do not want to see the thoug
559 solution to the problem one is solving
560 simple and elegant solution."*
561
562 It may be challenging to keep the balance betw
563 solution and working together with the communi
564 unfinished work. Therefore it is good to get e
565 get feedback to improve your work, but also ke
566 chunks that they may get already accepted, eve
567 not ready for inclusion now.
568
569 Also realize that it is not acceptable to send
570 that are unfinished and will be "fixed up late
571
572
573 Justify your change
574 -------------------
575
576 Along with breaking up your patches, it is ver
577 the Linux community know why they should add t
578 must be justified as being needed and useful.
579
580
581 Document your change
582 --------------------
583
584 When sending in your patches, pay special atte
585 the text in your email. This information will
586 information for the patch, and will be preserv
587 all time. It should describe the patch comple
588
589 - why the change is necessary
590 - the overall design approach in the patch
591 - implementation details
592 - testing results
593
594 For more details on what this should all look
595 ChangeLog section of the document:
596
597 "The Perfect Patch"
598 https://www.ozlabs.org/~akpm/stuff/tpp.t
599
600
601 All of these things are sometimes very hard to
602 perfect these practices (if at all). It's a co
603 improvement that requires a lot of patience an
604 don't give up, it's possible. Many have done i
605 start exactly where you are now.
606
607
608
609
610 ----------
611
612 Thanks to Paolo Ciarrocchi who allowed the "De
613 (https://lwn.net/Articles/94386/) section
614 to be based on text he had written, and to Ran
615 Huizenga for some of the list of things you sh
616 Also thanks to Pat Mochel, Hanna Linder, Randy
617 Vojtech Pavlik, Jan Kara, Josh Boyer, Kees Coo
618 Kleen, Vadim Lobanov, Jesper Juhl, Adrian Bunk
619 David A. Wheeler, Junio Hamano, Michael Kerris
620 their review, comments, and contributions. Wi
621 document would not have been possible.
622
623
624
625 Maintainer: Greg Kroah-Hartman <greg@kroah.com>
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.