1 .. SPDX-License-Identifier: GPL-2.0 1 .. SPDX-License-Identifier: GPL-2.0
2 2
3 The tip tree handbook 3 The tip tree handbook
4 ===================== 4 =====================
5 5
6 What is the tip tree? 6 What is the tip tree?
7 --------------------- 7 ---------------------
8 8
9 The tip tree is a collection of several subsys 9 The tip tree is a collection of several subsystems and areas of
10 development. The tip tree is both a direct dev 10 development. The tip tree is both a direct development tree and a
11 aggregation tree for several sub-maintainer tr 11 aggregation tree for several sub-maintainer trees. The tip tree gitweb URL
12 is: https://git.kernel.org/pub/scm/linux/kerne 12 is: https://git.kernel.org/pub/scm/linux/kernel/git/tip/tip.git
13 13
14 The tip tree contains the following subsystems 14 The tip tree contains the following subsystems:
15 15
16 - **x86 architecture** 16 - **x86 architecture**
17 17
18 The x86 architecture development takes pl 18 The x86 architecture development takes place in the tip tree except
19 for the x86 KVM and XEN specific parts wh 19 for the x86 KVM and XEN specific parts which are maintained in the
20 corresponding subsystems and routed direc 20 corresponding subsystems and routed directly to mainline from
21 there. It's still good practice to Cc the 21 there. It's still good practice to Cc the x86 maintainers on
22 x86-specific KVM and XEN patches. 22 x86-specific KVM and XEN patches.
23 23
24 Some x86 subsystems have their own mainta 24 Some x86 subsystems have their own maintainers in addition to the
25 overall x86 maintainers. Please Cc the o 25 overall x86 maintainers. Please Cc the overall x86 maintainers on
26 patches touching files in arch/x86 even w 26 patches touching files in arch/x86 even when they are not called out
27 by the MAINTAINER file. 27 by the MAINTAINER file.
28 28
29 Note, that ``x86@kernel.org`` is not a ma 29 Note, that ``x86@kernel.org`` is not a mailing list. It is merely a
30 mail alias which distributes mails to the 30 mail alias which distributes mails to the x86 top-level maintainer
31 team. Please always Cc the Linux Kernel m 31 team. Please always Cc the Linux Kernel mailing list (LKML)
32 ``linux-kernel@vger.kernel.org``, otherwi 32 ``linux-kernel@vger.kernel.org``, otherwise your mail ends up only in
33 the private inboxes of the maintainers. 33 the private inboxes of the maintainers.
34 34
35 - **Scheduler** 35 - **Scheduler**
36 36
37 Scheduler development takes place in the 37 Scheduler development takes place in the -tip tree, in the
38 sched/core branch - with occasional sub-t 38 sched/core branch - with occasional sub-topic trees for
39 work-in-progress patch-sets. 39 work-in-progress patch-sets.
40 40
41 - **Locking and atomics** 41 - **Locking and atomics**
42 42
43 Locking development (including atomics an 43 Locking development (including atomics and other synchronization
44 primitives that are connected to locking) 44 primitives that are connected to locking) takes place in the -tip
45 tree, in the locking/core branch - with o 45 tree, in the locking/core branch - with occasional sub-topic trees
46 for work-in-progress patch-sets. 46 for work-in-progress patch-sets.
47 47
48 - **Generic interrupt subsystem and interru 48 - **Generic interrupt subsystem and interrupt chip drivers**:
49 49
50 - interrupt core development happens in t 50 - interrupt core development happens in the irq/core branch
51 51
52 - interrupt chip driver development also 52 - interrupt chip driver development also happens in the irq/core
53 branch, but the patches are usually app 53 branch, but the patches are usually applied in a separate maintainer
54 tree and then aggregated into irq/core 54 tree and then aggregated into irq/core
55 55
56 - **Time, timers, timekeeping, NOHZ and rel 56 - **Time, timers, timekeeping, NOHZ and related chip drivers**:
57 57
58 - timekeeping, clocksource core, NTP and 58 - timekeeping, clocksource core, NTP and alarmtimer development
59 happens in the timers/core branch, but 59 happens in the timers/core branch, but patches are usually applied in
60 a separate maintainer tree and then agg 60 a separate maintainer tree and then aggregated into timers/core
61 61
62 - clocksource/event driver development ha 62 - clocksource/event driver development happens in the timers/core
63 branch, but patches are mostly applied 63 branch, but patches are mostly applied in a separate maintainer tree
64 and then aggregated into timers/core 64 and then aggregated into timers/core
65 65
66 - **Performance counters core, architecture 66 - **Performance counters core, architecture support and tooling**:
67 67
68 - perf core and architecture support deve 68 - perf core and architecture support development happens in the
69 perf/core branch 69 perf/core branch
70 70
71 - perf tooling development happens in the 71 - perf tooling development happens in the perf tools maintainer
72 tree and is aggregated into the tip tre 72 tree and is aggregated into the tip tree.
73 73
74 - **CPU hotplug core** 74 - **CPU hotplug core**
75 75
76 - **RAS core** 76 - **RAS core**
77 77
78 Mostly x86-specific RAS patches are colle 78 Mostly x86-specific RAS patches are collected in the tip ras/core
79 branch. 79 branch.
80 80
81 - **EFI core** 81 - **EFI core**
82 82
83 EFI development in the efi git tree. The 83 EFI development in the efi git tree. The collected patches are
84 aggregated in the tip efi/core branch. 84 aggregated in the tip efi/core branch.
85 85
86 - **RCU** 86 - **RCU**
87 87
88 RCU development happens in the linux-rcu 88 RCU development happens in the linux-rcu tree. The resulting changes
89 are aggregated into the tip core/rcu bran 89 are aggregated into the tip core/rcu branch.
90 90
91 - **Various core code components**: 91 - **Various core code components**:
92 92
93 - debugobjects 93 - debugobjects
94 94
95 - objtool 95 - objtool
96 96
97 - random bits and pieces 97 - random bits and pieces
98 98
99 99
100 Patch submission notes 100 Patch submission notes
101 ---------------------- 101 ----------------------
102 102
103 Selecting the tree/branch 103 Selecting the tree/branch
104 ^^^^^^^^^^^^^^^^^^^^^^^^^ 104 ^^^^^^^^^^^^^^^^^^^^^^^^^
105 105
106 In general, development against the head of th 106 In general, development against the head of the tip tree master branch is
107 fine, but for the subsystems which are maintai 107 fine, but for the subsystems which are maintained separately, have their
108 own git tree and are only aggregated into the 108 own git tree and are only aggregated into the tip tree, development should
109 take place against the relevant subsystem tree 109 take place against the relevant subsystem tree or branch.
110 110
111 Bug fixes which target mainline should always 111 Bug fixes which target mainline should always be applicable against the
112 mainline kernel tree. Potential conflicts agai 112 mainline kernel tree. Potential conflicts against changes which are already
113 queued in the tip tree are handled by the main 113 queued in the tip tree are handled by the maintainers.
114 114
115 Patch subject 115 Patch subject
116 ^^^^^^^^^^^^^ 116 ^^^^^^^^^^^^^
117 117
118 The tip tree preferred format for patch subjec 118 The tip tree preferred format for patch subject prefixes is
119 'subsys/component:', e.g. 'x86/apic:', 'x86/mm 119 'subsys/component:', e.g. 'x86/apic:', 'x86/mm/fault:', 'sched/fair:',
120 'genirq/core:'. Please do not use file names o 120 'genirq/core:'. Please do not use file names or complete file paths as
121 prefix. 'git log path/to/file' should give you 121 prefix. 'git log path/to/file' should give you a reasonable hint in most
122 cases. 122 cases.
123 123
124 The condensed patch description in the subject 124 The condensed patch description in the subject line should start with a
125 uppercase letter and should be written in impe 125 uppercase letter and should be written in imperative tone.
126 126
127 127
128 Changelog 128 Changelog
129 ^^^^^^^^^ 129 ^^^^^^^^^
130 130
131 The general rules about changelogs in the :ref 131 The general rules about changelogs in the :ref:`Submitting patches guide
132 <describe_changes>`, apply. 132 <describe_changes>`, apply.
133 133
134 The tip tree maintainers set value on followin 134 The tip tree maintainers set value on following these rules, especially on
135 the request to write changelogs in imperative 135 the request to write changelogs in imperative mood and not impersonating
136 code or the execution of it. This is not just 136 code or the execution of it. This is not just a whim of the
137 maintainers. Changelogs written in abstract wo 137 maintainers. Changelogs written in abstract words are more precise and
138 tend to be less confusing than those written i 138 tend to be less confusing than those written in the form of novels.
139 139
140 It's also useful to structure the changelog in 140 It's also useful to structure the changelog into several paragraphs and not
141 lump everything together into a single one. A 141 lump everything together into a single one. A good structure is to explain
142 the context, the problem and the solution in s 142 the context, the problem and the solution in separate paragraphs and this
143 order. 143 order.
144 144
145 Examples for illustration: 145 Examples for illustration:
146 146
147 Example 1:: 147 Example 1::
148 148
149 x86/intel_rdt/mbm: Fix MBM overflow handle 149 x86/intel_rdt/mbm: Fix MBM overflow handler during hot cpu
150 150
151 When a CPU is dying, we cancel the worker 151 When a CPU is dying, we cancel the worker and schedule a new worker on a
152 different CPU on the same domain. But if t 152 different CPU on the same domain. But if the timer is already about to
153 expire (say 0.99s) then we essentially dou 153 expire (say 0.99s) then we essentially double the interval.
154 154
155 We modify the hot cpu handling to cancel t 155 We modify the hot cpu handling to cancel the delayed work on the dying
156 cpu and run the worker immediately on a di 156 cpu and run the worker immediately on a different cpu in same domain. We
157 do not flush the worker because the MBM ov !! 157 donot flush the worker because the MBM overflow worker reschedules the
158 worker on same CPU and scans the domain->c 158 worker on same CPU and scans the domain->cpu_mask to get the domain
159 pointer. 159 pointer.
160 160
161 Improved version:: 161 Improved version::
162 162
163 x86/intel_rdt/mbm: Fix MBM overflow handle 163 x86/intel_rdt/mbm: Fix MBM overflow handler during CPU hotplug
164 164
165 When a CPU is dying, the overflow worker i 165 When a CPU is dying, the overflow worker is canceled and rescheduled on a
166 different CPU in the same domain. But if t 166 different CPU in the same domain. But if the timer is already about to
167 expire this essentially doubles the interv 167 expire this essentially doubles the interval which might result in a non
168 detected overflow. 168 detected overflow.
169 169
170 Cancel the overflow worker and reschedule 170 Cancel the overflow worker and reschedule it immediately on a different CPU
171 in the same domain. The work could be flus 171 in the same domain. The work could be flushed as well, but that would
172 reschedule it on the same CPU. 172 reschedule it on the same CPU.
173 173
174 Example 2:: 174 Example 2::
175 175
176 time: POSIX CPU timers: Ensure that variab 176 time: POSIX CPU timers: Ensure that variable is initialized
177 177
178 If cpu_timer_sample_group returns -EINVAL, 178 If cpu_timer_sample_group returns -EINVAL, it will not have written into
179 *sample. Checking for cpu_timer_sample_gro 179 *sample. Checking for cpu_timer_sample_group's return value precludes the
180 potential use of an uninitialized value of 180 potential use of an uninitialized value of now in the following block.
181 Given an invalid clock_idx, the previous c 181 Given an invalid clock_idx, the previous code could otherwise overwrite
182 *oldval in an undefined manner. This is no 182 *oldval in an undefined manner. This is now prevented. We also exploit
183 short-circuiting of && to sample the timer 183 short-circuiting of && to sample the timer only if the result will
184 actually be used to update *oldval. 184 actually be used to update *oldval.
185 185
186 Improved version:: 186 Improved version::
187 187
188 posix-cpu-timers: Make set_process_cpu_tim 188 posix-cpu-timers: Make set_process_cpu_timer() more robust
189 189
190 Because the return value of cpu_timer_samp 190 Because the return value of cpu_timer_sample_group() is not checked,
191 compilers and static checkers can legitima 191 compilers and static checkers can legitimately warn about a potential use
192 of the uninitialized variable 'now'. This 192 of the uninitialized variable 'now'. This is not a runtime issue as all
193 call sites hand in valid clock ids. 193 call sites hand in valid clock ids.
194 194
195 Also cpu_timer_sample_group() is invoked u 195 Also cpu_timer_sample_group() is invoked unconditionally even when the
196 result is not used because *oldval is NULL 196 result is not used because *oldval is NULL.
197 197
198 Make the invocation conditional and check 198 Make the invocation conditional and check the return value.
199 199
200 Example 3:: 200 Example 3::
201 201
202 The entity can also be used for other purp 202 The entity can also be used for other purposes.
203 203
204 Let's rename it to be more generic. 204 Let's rename it to be more generic.
205 205
206 Improved version:: 206 Improved version::
207 207
208 The entity can also be used for other purp 208 The entity can also be used for other purposes.
209 209
210 Rename it to be more generic. 210 Rename it to be more generic.
211 211
212 212
213 For complex scenarios, especially race conditi 213 For complex scenarios, especially race conditions and memory ordering
214 issues, it is valuable to depict the scenario 214 issues, it is valuable to depict the scenario with a table which shows
215 the parallelism and the temporal order of even 215 the parallelism and the temporal order of events. Here is an example::
216 216
217 CPU0 CPU1 217 CPU0 CPU1
218 free_irq(X) interrupt 218 free_irq(X) interrupt X
219 spin_lock( 219 spin_lock(desc->lock)
220 wake irq t 220 wake irq thread()
221 spin_unloc 221 spin_unlock(desc->lock)
222 spin_lock(desc->lock) 222 spin_lock(desc->lock)
223 remove action() 223 remove action()
224 shutdown_irq() 224 shutdown_irq()
225 release_resources() thread_han 225 release_resources() thread_handler()
226 spin_unlock(desc->lock) access r 226 spin_unlock(desc->lock) access released resources.
227 ^^^^^^^^ 227 ^^^^^^^^^^^^^^^^^^^^^^^^^
228 synchronize_irq() 228 synchronize_irq()
229 229
230 Lockdep provides similar useful output to depi 230 Lockdep provides similar useful output to depict a possible deadlock
231 scenario:: 231 scenario::
232 232
233 CPU0 CP 233 CPU0 CPU1
234 rtmutex_lock(&rcu->rt_mutex) 234 rtmutex_lock(&rcu->rt_mutex)
235 spin_lock(&rcu->rt_mutex.wait_lock) 235 spin_lock(&rcu->rt_mutex.wait_lock)
236 lo 236 local_irq_disable()
237 sp 237 spin_lock(&timer->it_lock)
238 sp 238 spin_lock(&rcu->mutex.wait_lock)
239 --> Interrupt 239 --> Interrupt
240 spin_lock(&timer->it_lock) 240 spin_lock(&timer->it_lock)
241 241
242 242
243 Function references in changelogs 243 Function references in changelogs
244 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 244 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
245 245
246 When a function is mentioned in the changelog, 246 When a function is mentioned in the changelog, either the text body or the
247 subject line, please use the format 'function_ 247 subject line, please use the format 'function_name()'. Omitting the
248 brackets after the function name can be ambigu 248 brackets after the function name can be ambiguous::
249 249
250 Subject: subsys/component: Make reservation_ 250 Subject: subsys/component: Make reservation_count static
251 251
252 reservation_count is only used in reservatio 252 reservation_count is only used in reservation_stats. Make it static.
253 253
254 The variant with brackets is more precise:: 254 The variant with brackets is more precise::
255 255
256 Subject: subsys/component: Make reservation_ 256 Subject: subsys/component: Make reservation_count() static
257 257
258 reservation_count() is only called from rese 258 reservation_count() is only called from reservation_stats(). Make it
259 static. 259 static.
260 260
261 261
262 Backtraces in changelogs 262 Backtraces in changelogs
263 ^^^^^^^^^^^^^^^^^^^^^^^^ 263 ^^^^^^^^^^^^^^^^^^^^^^^^
264 264
265 See :ref:`backtraces`. 265 See :ref:`backtraces`.
266 266
267 Ordering of commit tags 267 Ordering of commit tags
268 ^^^^^^^^^^^^^^^^^^^^^^^ 268 ^^^^^^^^^^^^^^^^^^^^^^^
269 269
270 To have a uniform view of the commit tags, the 270 To have a uniform view of the commit tags, the tip maintainers use the
271 following tag ordering scheme: 271 following tag ordering scheme:
272 272
273 - Fixes: 12char-SHA1 ("sub/sys: Original subj 273 - Fixes: 12char-SHA1 ("sub/sys: Original subject line")
274 274
275 A Fixes tag should be added even for change 275 A Fixes tag should be added even for changes which do not need to be
276 backported to stable kernels, i.e. when add 276 backported to stable kernels, i.e. when addressing a recently introduced
277 issue which only affects tip or the current 277 issue which only affects tip or the current head of mainline. These tags
278 are helpful to identify the original commit 278 are helpful to identify the original commit and are much more valuable
279 than prominently mentioning the commit whic 279 than prominently mentioning the commit which introduced a problem in the
280 text of the changelog itself because they c 280 text of the changelog itself because they can be automatically
281 extracted. 281 extracted.
282 282
283 The following example illustrates the diffe 283 The following example illustrates the difference::
284 284
285 Commit 285 Commit
286 286
287 abcdef012345678 ("x86/xxx: Replace foo 287 abcdef012345678 ("x86/xxx: Replace foo with bar")
288 288
289 left an unused instance of variable foo a 289 left an unused instance of variable foo around. Remove it.
290 290
291 Signed-off-by: J.Dev <j.dev@mail> 291 Signed-off-by: J.Dev <j.dev@mail>
292 292
293 Please say instead:: 293 Please say instead::
294 294
295 The recent replacement of foo with bar le 295 The recent replacement of foo with bar left an unused instance of
296 variable foo around. Remove it. 296 variable foo around. Remove it.
297 297
298 Fixes: abcdef012345678 ("x86/xxx: Replace 298 Fixes: abcdef012345678 ("x86/xxx: Replace foo with bar")
299 Signed-off-by: J.Dev <j.dev@mail> 299 Signed-off-by: J.Dev <j.dev@mail>
300 300
301 The latter puts the information about the p 301 The latter puts the information about the patch into the focus and
302 amends it with the reference to the commit 302 amends it with the reference to the commit which introduced the issue
303 rather than putting the focus on the origin 303 rather than putting the focus on the original commit in the first place.
304 304
305 - Reported-by: ``Reporter <reporter@mail>`` 305 - Reported-by: ``Reporter <reporter@mail>``
306 306
307 - Closes: ``URL or Message-ID of the bug repo 307 - Closes: ``URL or Message-ID of the bug report this is fixing``
308 308
309 - Originally-by: ``Original author <original-a 309 - Originally-by: ``Original author <original-author@mail>``
310 310
311 - Suggested-by: ``Suggester <suggester@mail>`` 311 - Suggested-by: ``Suggester <suggester@mail>``
312 312
313 - Co-developed-by: ``Co-author <co-author@mail 313 - Co-developed-by: ``Co-author <co-author@mail>``
314 314
315 Signed-off-by: ``Co-author <co-author@mail>` 315 Signed-off-by: ``Co-author <co-author@mail>``
316 316
317 Note, that Co-developed-by and Signed-off-b 317 Note, that Co-developed-by and Signed-off-by of the co-author(s) must
318 come in pairs. 318 come in pairs.
319 319
320 - Signed-off-by: ``Author <author@mail>`` 320 - Signed-off-by: ``Author <author@mail>``
321 321
322 The first Signed-off-by (SOB) after the las 322 The first Signed-off-by (SOB) after the last Co-developed-by/SOB pair is the
323 author SOB, i.e. the person flagged as auth 323 author SOB, i.e. the person flagged as author by git.
324 324
325 - Signed-off-by: ``Patch handler <handler@mail 325 - Signed-off-by: ``Patch handler <handler@mail>``
326 326
327 SOBs after the author SOB are from people h 327 SOBs after the author SOB are from people handling and transporting
328 the patch, but were not involved in develop 328 the patch, but were not involved in development. SOB chains should
329 reflect the **real** route a patch took as 329 reflect the **real** route a patch took as it was propagated to us,
330 with the first SOB entry signalling primary 330 with the first SOB entry signalling primary authorship of a single
331 author. Acks should be given as Acked-by li 331 author. Acks should be given as Acked-by lines and review approvals
332 as Reviewed-by lines. 332 as Reviewed-by lines.
333 333
334 If the handler made modifications to the pa 334 If the handler made modifications to the patch or the changelog, then
335 this should be mentioned **after** the chan 335 this should be mentioned **after** the changelog text and **above**
336 all commit tags in the following format:: 336 all commit tags in the following format::
337 337
338 ... changelog text ends. 338 ... changelog text ends.
339 339
340 [ handler: Replaced foo by bar and update 340 [ handler: Replaced foo by bar and updated changelog ]
341 341
342 First-tag: ..... 342 First-tag: .....
343 343
344 Note the two empty new lines which separate 344 Note the two empty new lines which separate the changelog text and the
345 commit tags from that notice. 345 commit tags from that notice.
346 346
347 If a patch is sent to the mailing list by a 347 If a patch is sent to the mailing list by a handler then the author has
348 to be noted in the first line of the change 348 to be noted in the first line of the changelog with::
349 349
350 From: Author <author@mail> 350 From: Author <author@mail>
351 351
352 Changelog text starts here.... 352 Changelog text starts here....
353 353
354 so the authorship is preserved. The 'From:' 354 so the authorship is preserved. The 'From:' line has to be followed
355 by a empty newline. If that 'From:' line is 355 by a empty newline. If that 'From:' line is missing, then the patch
356 would be attributed to the person who sent 356 would be attributed to the person who sent (transported, handled) it.
357 The 'From:' line is automatically removed w 357 The 'From:' line is automatically removed when the patch is applied
358 and does not show up in the final git chang 358 and does not show up in the final git changelog. It merely affects
359 the authorship information of the resulting 359 the authorship information of the resulting Git commit.
360 360
361 - Tested-by: ``Tester <tester@mail>`` 361 - Tested-by: ``Tester <tester@mail>``
362 362
363 - Reviewed-by: ``Reviewer <reviewer@mail>`` 363 - Reviewed-by: ``Reviewer <reviewer@mail>``
364 364
365 - Acked-by: ``Acker <acker@mail>`` 365 - Acked-by: ``Acker <acker@mail>``
366 366
367 - Cc: ``cc-ed-person <person@mail>`` 367 - Cc: ``cc-ed-person <person@mail>``
368 368
369 If the patch should be backported to stable 369 If the patch should be backported to stable, then please add a '``Cc:
370 stable@vger.kernel.org``' tag, but do not C 370 stable@vger.kernel.org``' tag, but do not Cc stable when sending your
371 mail. 371 mail.
372 372
373 - Link: ``https://link/to/information`` 373 - Link: ``https://link/to/information``
374 374
375 For referring to an email posted to the ker !! 375 For referring to an email on LKML or other kernel mailing lists,
376 use the lore.kernel.org redirector URL:: !! 376 please use the lore.kernel.org redirector URL::
377 377
378 Link: https://lore.kernel.org/email-messa !! 378 https://lore.kernel.org/r/email-message@id
379 379
380 This URL should be used when referring to r !! 380 The kernel.org redirector is considered a stable URL, unlike other email
381 topics, related patch sets, or other notabl !! 381 archives.
382 A convenient way to associate ``Link:`` tra <<
383 message is to use markdown-like bracketed n <<
384 <<
385 A similar approach was attempted before a <<
386 effort [1], but the initial implementatio <<
387 regressions [2], so it was backed out and <<
388 <<
389 Link: https://lore.kernel.org/some-msgid@ <<
390 Link: https://bugzilla.example.org/bug/12 <<
391 <<
392 You can also use ``Link:`` trailers to indi <<
393 patch when applying it to your git tree. In <<
394 dedicated ``patch.msgid.link`` domain inste <<
395 This practice makes it possible for automat <<
396 which link to use to retrieve the original <<
397 example:: <<
398 382
399 Link: https://patch.msgid.link/patch-sour !! 383 Maintainers will add a Link tag referencing the email of the patch
>> 384 submission when they apply a patch to the tip tree. This tag is useful
>> 385 for later reference and is also used for commit notifications.
400 386
401 Please do not use combined tags, e.g. ``Report 387 Please do not use combined tags, e.g. ``Reported-and-tested-by``, as
402 they just complicate automated extraction of t 388 they just complicate automated extraction of tags.
403 389
404 390
405 Links to documentation 391 Links to documentation
406 ^^^^^^^^^^^^^^^^^^^^^^ 392 ^^^^^^^^^^^^^^^^^^^^^^
407 393
408 Providing links to documentation in the change 394 Providing links to documentation in the changelog is a great help to later
409 debugging and analysis. Unfortunately, URLs o 395 debugging and analysis. Unfortunately, URLs often break very quickly
410 because companies restructure their websites f 396 because companies restructure their websites frequently. Non-'volatile'
411 exceptions include the Intel SDM and the AMD A 397 exceptions include the Intel SDM and the AMD APM.
412 398
413 Therefore, for 'volatile' documents, please cr 399 Therefore, for 'volatile' documents, please create an entry in the kernel
414 bugzilla https://bugzilla.kernel.org and attac 400 bugzilla https://bugzilla.kernel.org and attach a copy of these documents
415 to the bugzilla entry. Finally, provide the UR 401 to the bugzilla entry. Finally, provide the URL of the bugzilla entry in
416 the changelog. 402 the changelog.
417 403
418 Patch resend or reminders 404 Patch resend or reminders
419 ^^^^^^^^^^^^^^^^^^^^^^^^^ 405 ^^^^^^^^^^^^^^^^^^^^^^^^^
420 406
421 See :ref:`resend_reminders`. 407 See :ref:`resend_reminders`.
422 408
423 Merge window 409 Merge window
424 ^^^^^^^^^^^^ 410 ^^^^^^^^^^^^
425 411
426 Please do not expect patches to be reviewed or 412 Please do not expect patches to be reviewed or merged by tip
427 maintainers around or during the merge window. 413 maintainers around or during the merge window. The trees are closed
428 to all but urgent fixes during this time. The 414 to all but urgent fixes during this time. They reopen once the merge
429 window closes and a new -rc1 kernel has been r 415 window closes and a new -rc1 kernel has been released.
430 416
431 Large series should be submitted in mergeable 417 Large series should be submitted in mergeable state *at* *least* a week
432 before the merge window opens. Exceptions are 418 before the merge window opens. Exceptions are made for bug fixes and
433 *sometimes* for small standalone drivers for n 419 *sometimes* for small standalone drivers for new hardware or minimally
434 invasive patches for hardware enablement. 420 invasive patches for hardware enablement.
435 421
436 During the merge window, the maintainers inste 422 During the merge window, the maintainers instead focus on following the
437 upstream changes, fixing merge window fallout, 423 upstream changes, fixing merge window fallout, collecting bug fixes, and
438 allowing themselves a breath. Please respect t 424 allowing themselves a breath. Please respect that.
439 425
440 So called _urgent_ branches will be merged int 426 So called _urgent_ branches will be merged into mainline during the
441 stabilization phase of each release. 427 stabilization phase of each release.
442 428
443 429
444 Git 430 Git
445 ^^^ 431 ^^^
446 432
447 The tip maintainers accept git pull requests f 433 The tip maintainers accept git pull requests from maintainers who provide
448 subsystem changes for aggregation in the tip t 434 subsystem changes for aggregation in the tip tree.
449 435
450 Pull requests for new patch submissions are us 436 Pull requests for new patch submissions are usually not accepted and do not
451 replace proper patch submission to the mailing 437 replace proper patch submission to the mailing list. The main reason for
452 this is that the review workflow is email base 438 this is that the review workflow is email based.
453 439
454 If you submit a larger patch series it is help 440 If you submit a larger patch series it is helpful to provide a git branch
455 in a private repository which allows intereste 441 in a private repository which allows interested people to easily pull the
456 series for testing. The usual way to offer thi 442 series for testing. The usual way to offer this is a git URL in the cover
457 letter of the patch series. 443 letter of the patch series.
458 444
459 Testing 445 Testing
460 ^^^^^^^ 446 ^^^^^^^
461 447
462 Code should be tested before submitting to the 448 Code should be tested before submitting to the tip maintainers. Anything
463 other than minor changes should be built, boot 449 other than minor changes should be built, booted and tested with
464 comprehensive (and heavyweight) kernel debuggi 450 comprehensive (and heavyweight) kernel debugging options enabled.
465 451
466 These debugging options can be found in kernel 452 These debugging options can be found in kernel/configs/x86_debug.config
467 and can be added to an existing kernel config 453 and can be added to an existing kernel config by running:
468 454
469 make x86_debug.config 455 make x86_debug.config
470 456
471 Some of these options are x86-specific and can 457 Some of these options are x86-specific and can be left out when testing
472 on other architectures. 458 on other architectures.
473 459
474 .. _maintainer-tip-coding-style: 460 .. _maintainer-tip-coding-style:
475 461
476 Coding style notes 462 Coding style notes
477 ------------------ 463 ------------------
478 464
479 Comment style 465 Comment style
480 ^^^^^^^^^^^^^ 466 ^^^^^^^^^^^^^
481 467
482 Sentences in comments start with an uppercase 468 Sentences in comments start with an uppercase letter.
483 469
484 Single line comments:: 470 Single line comments::
485 471
486 /* This is a single line comment */ 472 /* This is a single line comment */
487 473
488 Multi-line comments:: 474 Multi-line comments::
489 475
490 /* 476 /*
491 * This is a properly formatted 477 * This is a properly formatted
492 * multi-line comment. 478 * multi-line comment.
493 * 479 *
494 * Larger multi-line comments should b 480 * Larger multi-line comments should be split into paragraphs.
495 */ 481 */
496 482
497 No tail comments (see below): 483 No tail comments (see below):
498 484
499 Please refrain from using tail comments. Tai 485 Please refrain from using tail comments. Tail comments disturb the
500 reading flow in almost all contexts, but esp 486 reading flow in almost all contexts, but especially in code::
501 487
502 if (somecondition_is_true) /* Don't pu 488 if (somecondition_is_true) /* Don't put a comment here */
503 dostuff(); /* Neither here */ 489 dostuff(); /* Neither here */
504 490
505 seed = MAGIC_CONSTANT; /* Nor here */ 491 seed = MAGIC_CONSTANT; /* Nor here */
506 492
507 Use freestanding comments instead:: 493 Use freestanding comments instead::
508 494
509 /* This condition is not obvious witho 495 /* This condition is not obvious without a comment */
510 if (somecondition_is_true) { 496 if (somecondition_is_true) {
511 /* This really needs to be doc 497 /* This really needs to be documented */
512 dostuff(); 498 dostuff();
513 } 499 }
514 500
515 /* This magic initialization needs a c 501 /* This magic initialization needs a comment. Maybe not? */
516 seed = MAGIC_CONSTANT; 502 seed = MAGIC_CONSTANT;
517 503
518 Use C++ style, tail comments when documentin 504 Use C++ style, tail comments when documenting structs in headers to
519 achieve a more compact layout and better rea 505 achieve a more compact layout and better readability::
520 506
521 // eax 507 // eax
522 u32 x2apic_shift : 5, // Numbe 508 u32 x2apic_shift : 5, // Number of bits to shift APIC ID right
523 // for t 509 // for the topology ID at the next level
524 : 27; // Reser 510 : 27; // Reserved
525 // ebx 511 // ebx
526 u32 num_processors : 16, // Numbe 512 u32 num_processors : 16, // Number of processors at current level
527 : 16; // Reser 513 : 16; // Reserved
528 514
529 versus:: 515 versus::
530 516
531 /* eax */ 517 /* eax */
532 /* 518 /*
533 * Number of bits to shift API 519 * Number of bits to shift APIC ID right for the topology ID
534 * at the next level 520 * at the next level
535 */ 521 */
536 u32 x2apic_shift : 5, 522 u32 x2apic_shift : 5,
537 /* Reserved */ 523 /* Reserved */
538 : 27; 524 : 27;
539 525
540 /* ebx */ 526 /* ebx */
541 /* Number of processors at cur 527 /* Number of processors at current level */
542 u32 num_processors : 16, 528 u32 num_processors : 16,
543 /* Reserved */ 529 /* Reserved */
544 : 16; 530 : 16;
545 531
546 Comment the important things: 532 Comment the important things:
547 533
548 Comments should be added where the operation 534 Comments should be added where the operation is not obvious. Documenting
549 the obvious is just a distraction:: 535 the obvious is just a distraction::
550 536
551 /* Decrement refcount and check for ze 537 /* Decrement refcount and check for zero */
552 if (refcount_dec_and_test(&p->refcnt)) 538 if (refcount_dec_and_test(&p->refcnt)) {
553 do; 539 do;
554 lots; 540 lots;
555 of; 541 of;
556 magic; 542 magic;
557 things; 543 things;
558 } 544 }
559 545
560 Instead, comments should explain the non-obv 546 Instead, comments should explain the non-obvious details and document
561 constraints:: 547 constraints::
562 548
563 if (refcount_dec_and_test(&p->refcnt)) 549 if (refcount_dec_and_test(&p->refcnt)) {
564 /* 550 /*
565 * Really good explanation why 551 * Really good explanation why the magic things below
566 * need to be done, ordering a 552 * need to be done, ordering and locking constraints,
567 * etc.. 553 * etc..
568 */ 554 */
569 do; 555 do;
570 lots; 556 lots;
571 of; 557 of;
572 magic; 558 magic;
573 /* Needs to be the last operat 559 /* Needs to be the last operation because ... */
574 things; 560 things;
575 } 561 }
576 562
577 Function documentation comments: 563 Function documentation comments:
578 564
579 To document functions and their arguments pl 565 To document functions and their arguments please use kernel-doc format
580 and not free form comments:: 566 and not free form comments::
581 567
582 /** 568 /**
583 * magic_function - Do lots of magic s 569 * magic_function - Do lots of magic stuff
584 * @magic: Pointer to the magic d 570 * @magic: Pointer to the magic data to operate on
585 * @offset: Offset in the data arr 571 * @offset: Offset in the data array of @magic
586 * 572 *
587 * Deep explanation of mysterious thin 573 * Deep explanation of mysterious things done with @magic along
588 * with documentation of the return va 574 * with documentation of the return values.
589 * 575 *
590 * Note, that the argument descriptors 576 * Note, that the argument descriptors above are arranged
591 * in a tabular fashion. 577 * in a tabular fashion.
592 */ 578 */
593 579
594 This applies especially to globally visible 580 This applies especially to globally visible functions and inline
595 functions in public header files. It might b 581 functions in public header files. It might be overkill to use kernel-doc
596 format for every (static) function which nee 582 format for every (static) function which needs a tiny explanation. The
597 usage of descriptive function names often re 583 usage of descriptive function names often replaces these tiny comments.
598 Apply common sense as always. 584 Apply common sense as always.
599 585
600 586
601 Documenting locking requirements 587 Documenting locking requirements
602 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 588 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
603 Documenting locking requirements is a good t 589 Documenting locking requirements is a good thing, but comments are not
604 necessarily the best choice. Instead of writ 590 necessarily the best choice. Instead of writing::
605 591
606 /* Caller must hold foo->lock */ 592 /* Caller must hold foo->lock */
607 void func(struct foo *foo) 593 void func(struct foo *foo)
608 { 594 {
609 ... 595 ...
610 } 596 }
611 597
612 Please use:: 598 Please use::
613 599
614 void func(struct foo *foo) 600 void func(struct foo *foo)
615 { 601 {
616 lockdep_assert_held(&foo->lock 602 lockdep_assert_held(&foo->lock);
617 ... 603 ...
618 } 604 }
619 605
620 In PROVE_LOCKING kernels, lockdep_assert_hel 606 In PROVE_LOCKING kernels, lockdep_assert_held() emits a warning
621 if the caller doesn't hold the lock. Commen 607 if the caller doesn't hold the lock. Comments can't do that.
622 608
623 Bracket rules 609 Bracket rules
624 ^^^^^^^^^^^^^ 610 ^^^^^^^^^^^^^
625 611
626 Brackets should be omitted only if the stateme 612 Brackets should be omitted only if the statement which follows 'if', 'for',
627 'while' etc. is truly a single line:: 613 'while' etc. is truly a single line::
628 614
629 if (foo) 615 if (foo)
630 do_something(); 616 do_something();
631 617
632 The following is not considered to be a single 618 The following is not considered to be a single line statement even
633 though C does not require brackets:: 619 though C does not require brackets::
634 620
635 for (i = 0; i < end; i++) 621 for (i = 0; i < end; i++)
636 if (foo[i]) 622 if (foo[i])
637 do_something(foo[i]); 623 do_something(foo[i]);
638 624
639 Adding brackets around the outer loop enhances 625 Adding brackets around the outer loop enhances the reading flow::
640 626
641 for (i = 0; i < end; i++) { 627 for (i = 0; i < end; i++) {
642 if (foo[i]) 628 if (foo[i])
643 do_something(foo[i]); 629 do_something(foo[i]);
644 } 630 }
645 631
646 632
647 Variable declarations 633 Variable declarations
648 ^^^^^^^^^^^^^^^^^^^^^ 634 ^^^^^^^^^^^^^^^^^^^^^
649 635
650 The preferred ordering of variable declaration 636 The preferred ordering of variable declarations at the beginning of a
651 function is reverse fir tree order:: 637 function is reverse fir tree order::
652 638
653 struct long_struct_name *descriptive_n 639 struct long_struct_name *descriptive_name;
654 unsigned long foo, bar; 640 unsigned long foo, bar;
655 unsigned int tmp; 641 unsigned int tmp;
656 int ret; 642 int ret;
657 643
658 The above is faster to parse than the reverse 644 The above is faster to parse than the reverse ordering::
659 645
660 int ret; 646 int ret;
661 unsigned int tmp; 647 unsigned int tmp;
662 unsigned long foo, bar; 648 unsigned long foo, bar;
663 struct long_struct_name *descriptive_n 649 struct long_struct_name *descriptive_name;
664 650
665 And even more so than random ordering:: 651 And even more so than random ordering::
666 652
667 unsigned long foo, bar; 653 unsigned long foo, bar;
668 int ret; 654 int ret;
669 struct long_struct_name *descriptive_n 655 struct long_struct_name *descriptive_name;
670 unsigned int tmp; 656 unsigned int tmp;
671 657
672 Also please try to aggregate variables of the 658 Also please try to aggregate variables of the same type into a single
673 line. There is no point in wasting screen spac 659 line. There is no point in wasting screen space::
674 660
675 unsigned long a; 661 unsigned long a;
676 unsigned long b; 662 unsigned long b;
677 unsigned long c; 663 unsigned long c;
678 unsigned long d; 664 unsigned long d;
679 665
680 It's really sufficient to do:: 666 It's really sufficient to do::
681 667
682 unsigned long a, b, c, d; 668 unsigned long a, b, c, d;
683 669
684 Please also refrain from introducing line spli 670 Please also refrain from introducing line splits in variable declarations::
685 671
686 struct long_struct_name *descriptive_n 672 struct long_struct_name *descriptive_name = container_of(bar,
687 673 struct long_struct_name,
688 674 member);
689 struct foobar foo; 675 struct foobar foo;
690 676
691 It's way better to move the initialization to 677 It's way better to move the initialization to a separate line after the
692 declarations:: 678 declarations::
693 679
694 struct long_struct_name *descriptive_n 680 struct long_struct_name *descriptive_name;
695 struct foobar foo; 681 struct foobar foo;
696 682
697 descriptive_name = container_of(bar, s 683 descriptive_name = container_of(bar, struct long_struct_name, member);
698 684
699 685
700 Variable types 686 Variable types
701 ^^^^^^^^^^^^^^ 687 ^^^^^^^^^^^^^^
702 688
703 Please use the proper u8, u16, u32, u64 types 689 Please use the proper u8, u16, u32, u64 types for variables which are meant
704 to describe hardware or are used as arguments 690 to describe hardware or are used as arguments for functions which access
705 hardware. These types are clearly defining the 691 hardware. These types are clearly defining the bit width and avoid
706 truncation, expansion and 32/64-bit confusion. 692 truncation, expansion and 32/64-bit confusion.
707 693
708 u64 is also recommended in code which would be 694 u64 is also recommended in code which would become ambiguous for 32-bit
709 kernels when 'unsigned long' would be used ins 695 kernels when 'unsigned long' would be used instead. While in such
710 situations 'unsigned long long' could be used 696 situations 'unsigned long long' could be used as well, u64 is shorter
711 and also clearly shows that the operation is r 697 and also clearly shows that the operation is required to be 64 bits wide
712 independent of the target CPU. 698 independent of the target CPU.
713 699
714 Please use 'unsigned int' instead of 'unsigned 700 Please use 'unsigned int' instead of 'unsigned'.
715 701
716 702
717 Constants 703 Constants
718 ^^^^^^^^^ 704 ^^^^^^^^^
719 705
720 Please do not use literal (hexa)decimal number 706 Please do not use literal (hexa)decimal numbers in code or initializers.
721 Either use proper defines which have descripti 707 Either use proper defines which have descriptive names or consider using
722 an enum. 708 an enum.
723 709
724 710
725 Struct declarations and initializers 711 Struct declarations and initializers
726 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 712 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
727 713
728 Struct declarations should align the struct me 714 Struct declarations should align the struct member names in a tabular
729 fashion:: 715 fashion::
730 716
731 struct bar_order { 717 struct bar_order {
732 unsigned int guest_id; 718 unsigned int guest_id;
733 int ordered_item; 719 int ordered_item;
734 struct menu *menu; 720 struct menu *menu;
735 }; 721 };
736 722
737 Please avoid documenting struct members within 723 Please avoid documenting struct members within the declaration, because
738 this often results in strangely formatted comm 724 this often results in strangely formatted comments and the struct members
739 become obfuscated:: 725 become obfuscated::
740 726
741 struct bar_order { 727 struct bar_order {
742 unsigned int guest_id; /* U 728 unsigned int guest_id; /* Unique guest id */
743 int ordered_item; 729 int ordered_item;
744 /* Pointer to a menu instance 730 /* Pointer to a menu instance which contains all the drinks */
745 struct menu *menu; 731 struct menu *menu;
746 }; 732 };
747 733
748 Instead, please consider using the kernel-doc 734 Instead, please consider using the kernel-doc format in a comment preceding
749 the struct declaration, which is easier to rea 735 the struct declaration, which is easier to read and has the added advantage
750 of including the information in the kernel doc 736 of including the information in the kernel documentation, for example, as
751 follows:: 737 follows::
752 738
753 739
754 /** 740 /**
755 * struct bar_order - Description of a 741 * struct bar_order - Description of a bar order
756 * @guest_id: Unique guest i 742 * @guest_id: Unique guest id
757 * @ordered_item: The item numbe 743 * @ordered_item: The item number from the menu
758 * @menu: Pointer to the 744 * @menu: Pointer to the menu from which the item
759 * was ordered 745 * was ordered
760 * 746 *
761 * Supplementary information for using 747 * Supplementary information for using the struct.
762 * 748 *
763 * Note, that the struct member descri 749 * Note, that the struct member descriptors above are arranged
764 * in a tabular fashion. 750 * in a tabular fashion.
765 */ 751 */
766 struct bar_order { 752 struct bar_order {
767 unsigned int guest_id; 753 unsigned int guest_id;
768 int ordered_item; 754 int ordered_item;
769 struct menu *menu; 755 struct menu *menu;
770 }; 756 };
771 757
772 Static struct initializers must use C99 initia 758 Static struct initializers must use C99 initializers and should also be
773 aligned in a tabular fashion:: 759 aligned in a tabular fashion::
774 760
775 static struct foo statfoo = { 761 static struct foo statfoo = {
776 .a = 0, 762 .a = 0,
777 .plain_integer = CONSTANT_DEF 763 .plain_integer = CONSTANT_DEFINE_OR_ENUM,
778 .bar = &statbar, 764 .bar = &statbar,
779 }; 765 };
780 766
781 Note that while C99 syntax allows the omission 767 Note that while C99 syntax allows the omission of the final comma,
782 we recommend the use of a comma on the last li 768 we recommend the use of a comma on the last line because it makes
783 reordering and addition of new lines easier, a 769 reordering and addition of new lines easier, and makes such future
784 patches slightly easier to read as well. 770 patches slightly easier to read as well.
785 771
786 Line breaks 772 Line breaks
787 ^^^^^^^^^^^ 773 ^^^^^^^^^^^
788 774
789 Restricting line length to 80 characters makes 775 Restricting line length to 80 characters makes deeply indented code hard to
790 read. Consider breaking out code into helper 776 read. Consider breaking out code into helper functions to avoid excessive
791 line breaking. 777 line breaking.
792 778
793 The 80 character rule is not a strict rule, so 779 The 80 character rule is not a strict rule, so please use common sense when
794 breaking lines. Especially format strings shou 780 breaking lines. Especially format strings should never be broken up.
795 781
796 When splitting function declarations or functi 782 When splitting function declarations or function calls, then please align
797 the first argument in the second line with the 783 the first argument in the second line with the first argument in the first
798 line:: 784 line::
799 785
800 static int long_function_name(struct foobar 786 static int long_function_name(struct foobar *barfoo, unsigned int id,
801 unsigned int o 787 unsigned int offset)
802 { 788 {
803 789
804 if (!id) { 790 if (!id) {
805 ret = longer_function_name(bar 791 ret = longer_function_name(barfoo, DEFAULT_BARFOO_ID,
806 off 792 offset);
807 ... 793 ...
808 794
809 Namespaces 795 Namespaces
810 ^^^^^^^^^^ 796 ^^^^^^^^^^
811 797
812 Function/variable namespaces improve readabili 798 Function/variable namespaces improve readability and allow easy
813 grepping. These namespaces are string prefixes 799 grepping. These namespaces are string prefixes for globally visible
814 function and variable names, including inlines 800 function and variable names, including inlines. These prefixes should
815 combine the subsystem and the component name s 801 combine the subsystem and the component name such as 'x86_comp\_',
816 'sched\_', 'irq\_', and 'mutex\_'. 802 'sched\_', 'irq\_', and 'mutex\_'.
817 803
818 This also includes static file scope functions 804 This also includes static file scope functions that are immediately put
819 into globally visible driver templates - it's 805 into globally visible driver templates - it's useful for those symbols
820 to carry a good prefix as well, for backtrace 806 to carry a good prefix as well, for backtrace readability.
821 807
822 Namespace prefixes may be omitted for local st 808 Namespace prefixes may be omitted for local static functions and
823 variables. Truly local functions, only called 809 variables. Truly local functions, only called by other local functions,
824 can have shorter descriptive names - our prima 810 can have shorter descriptive names - our primary concern is greppability
825 and backtrace readability. 811 and backtrace readability.
826 812
827 Please note that 'xxx_vendor\_' and 'vendor_xx 813 Please note that 'xxx_vendor\_' and 'vendor_xxx_` prefixes are not
828 helpful for static functions in vendor-specifi 814 helpful for static functions in vendor-specific files. After all, it
829 is already clear that the code is vendor-speci 815 is already clear that the code is vendor-specific. In addition, vendor
830 names should only be for truly vendor-specific 816 names should only be for truly vendor-specific functionality.
831 817
832 As always apply common sense and aim for consi 818 As always apply common sense and aim for consistency and readability.
833 819
834 820
835 Commit notifications 821 Commit notifications
836 -------------------- 822 --------------------
837 823
838 The tip tree is monitored by a bot for new com 824 The tip tree is monitored by a bot for new commits. The bot sends an email
839 for each new commit to a dedicated mailing lis 825 for each new commit to a dedicated mailing list
840 (``linux-tip-commits@vger.kernel.org``) and Cc 826 (``linux-tip-commits@vger.kernel.org``) and Cc's all people who are
841 mentioned in one of the commit tags. It uses t 827 mentioned in one of the commit tags. It uses the email message ID from the
842 Link tag at the end of the tag list to set the 828 Link tag at the end of the tag list to set the In-Reply-To email header so
843 the message is properly threaded with the patc 829 the message is properly threaded with the patch submission email.
844 830
845 The tip maintainers and submaintainers try to 831 The tip maintainers and submaintainers try to reply to the submitter
846 when merging a patch, but they sometimes forge 832 when merging a patch, but they sometimes forget or it does not fit the
847 workflow of the moment. While the bot message 833 workflow of the moment. While the bot message is purely mechanical, it
848 also implies a 'Thank you! Applied.'. 834 also implies a 'Thank you! Applied.'.
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.