1 |
62 |
marcus.erl |
|
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 .
|
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@vger.kernel.org. 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 .
|
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@vger.kernel.org.
|
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 |
|
|
|
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@kernel.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:
|
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 |
|
|
|
224 |
|
|
WARNING: Some mailers like Mozilla send your messages with
|
225 |
|
|
---- message header ----
|
226 |
|
|
Content-Type: text/plain; charset=us-ascii; format=flowed
|
227 |
|
|
---- message header ----
|
228 |
|
|
The problem is that "format=flowed" makes some of the mailers
|
229 |
|
|
on receiving side to replace TABs with spaces and do similar
|
230 |
|
|
changes. Thus the patches from you can look corrupted.
|
231 |
|
|
|
232 |
|
|
To fix this just make your mozilla defaults/pref/mailnews.js file to look like:
|
233 |
|
|
pref("mailnews.send_plaintext_flowed", false); // RFC 2646=======
|
234 |
|
|
pref("mailnews.display.disable_format_flowed_support", true);
|
235 |
|
|
|
236 |
|
|
|
237 |
|
|
|
238 |
|
|
8) E-mail size.
|
239 |
|
|
|
240 |
|
|
When sending patches to Linus, always follow step #7.
|
241 |
|
|
|
242 |
|
|
Large changes are not appropriate for mailing lists, and some
|
243 |
|
|
maintainers. If your patch, uncompressed, exceeds 40 kB in size,
|
244 |
|
|
it is preferred that you store your patch on an Internet-accessible
|
245 |
|
|
server, and provide instead a URL (link) pointing to your patch.
|
246 |
|
|
|
247 |
|
|
|
248 |
|
|
|
249 |
|
|
9) Name your kernel version.
|
250 |
|
|
|
251 |
|
|
It is important to note, either in the subject line or in the patch
|
252 |
|
|
description, the kernel version to which this patch applies.
|
253 |
|
|
|
254 |
|
|
If the patch does not apply cleanly to the latest kernel version,
|
255 |
|
|
Linus will not apply it.
|
256 |
|
|
|
257 |
|
|
|
258 |
|
|
|
259 |
|
|
10) Don't get discouraged. Re-submit.
|
260 |
|
|
|
261 |
|
|
After you have submitted your change, be patient and wait. If Linus
|
262 |
|
|
likes your change and applies it, it will appear in the next version
|
263 |
|
|
of the kernel that he releases.
|
264 |
|
|
|
265 |
|
|
However, if your change doesn't appear in the next version of the
|
266 |
|
|
kernel, there could be any number of reasons. It's YOUR job to
|
267 |
|
|
narrow down those reasons, correct what was wrong, and submit your
|
268 |
|
|
updated change.
|
269 |
|
|
|
270 |
|
|
It is quite common for Linus to "drop" your patch without comment.
|
271 |
|
|
That's the nature of the system. If he drops your patch, it could be
|
272 |
|
|
due to
|
273 |
|
|
* Your patch did not apply cleanly to the latest kernel version.
|
274 |
|
|
* Your patch was not sufficiently discussed on linux-kernel.
|
275 |
|
|
* A style issue (see section 2).
|
276 |
|
|
* An e-mail formatting issue (re-read this section).
|
277 |
|
|
* A technical problem with your change.
|
278 |
|
|
* He gets tons of e-mail, and yours got lost in the shuffle.
|
279 |
|
|
* You are being annoying.
|
280 |
|
|
|
281 |
|
|
When in doubt, solicit comments on linux-kernel mailing list.
|
282 |
|
|
|
283 |
|
|
|
284 |
|
|
|
285 |
|
|
11) Include PATCH in the subject
|
286 |
|
|
|
287 |
|
|
Due to high e-mail traffic to Linus, and to linux-kernel, it is common
|
288 |
|
|
convention to prefix your subject line with [PATCH]. This lets Linus
|
289 |
|
|
and other kernel developers more easily distinguish patches from other
|
290 |
|
|
e-mail discussions.
|
291 |
|
|
|
292 |
|
|
|
293 |
|
|
|
294 |
|
|
12) Sign your work
|
295 |
|
|
|
296 |
|
|
To improve tracking of who did what, especially with patches that can
|
297 |
|
|
percolate to their final resting place in the kernel through several
|
298 |
|
|
layers of maintainers, we've introduced a "sign-off" procedure on
|
299 |
|
|
patches that are being emailed around.
|
300 |
|
|
|
301 |
|
|
The sign-off is a simple line at the end of the explanation for the
|
302 |
|
|
patch, which certifies that you wrote it or otherwise have the right to
|
303 |
|
|
pass it on as a open-source patch. The rules are pretty simple: if you
|
304 |
|
|
can certify the below:
|
305 |
|
|
|
306 |
|
|
Developer's Certificate of Origin 1.1
|
307 |
|
|
|
308 |
|
|
By making a contribution to this project, I certify that:
|
309 |
|
|
|
310 |
|
|
(a) The contribution was created in whole or in part by me and I
|
311 |
|
|
have the right to submit it under the open source license
|
312 |
|
|
indicated in the file; or
|
313 |
|
|
|
314 |
|
|
(b) The contribution is based upon previous work that, to the best
|
315 |
|
|
of my knowledge, is covered under an appropriate open source
|
316 |
|
|
license and I have the right under that license to submit that
|
317 |
|
|
work with modifications, whether created in whole or in part
|
318 |
|
|
by me, under the same open source license (unless I am
|
319 |
|
|
permitted to submit under a different license), as indicated
|
320 |
|
|
in the file; or
|
321 |
|
|
|
322 |
|
|
(c) The contribution was provided directly to me by some other
|
323 |
|
|
person who certified (a), (b) or (c) and I have not modified
|
324 |
|
|
it.
|
325 |
|
|
|
326 |
|
|
(d) I understand and agree that this project and the contribution
|
327 |
|
|
are public and that a record of the contribution (including all
|
328 |
|
|
personal information I submit with it, including my sign-off) is
|
329 |
|
|
maintained indefinitely and may be redistributed consistent with
|
330 |
|
|
this project or the open source license(s) involved.
|
331 |
|
|
|
332 |
|
|
then you just add a line saying
|
333 |
|
|
|
334 |
|
|
Signed-off-by: Random J Developer
|
335 |
|
|
|
336 |
|
|
using your real name (sorry, no pseudonyms or anonymous contributions.)
|
337 |
|
|
|
338 |
|
|
Some people also put extra tags at the end. They'll just be ignored for
|
339 |
|
|
now, but you can do this to mark internal company procedures or just
|
340 |
|
|
point out some special detail about the sign-off.
|
341 |
|
|
|
342 |
|
|
|
343 |
|
|
13) When to use Acked-by:
|
344 |
|
|
|
345 |
|
|
The Signed-off-by: tag indicates that the signer was involved in the
|
346 |
|
|
development of the patch, or that he/she was in the patch's delivery path.
|
347 |
|
|
|
348 |
|
|
If a person was not directly involved in the preparation or handling of a
|
349 |
|
|
patch but wishes to signify and record their approval of it then they can
|
350 |
|
|
arrange to have an Acked-by: line added to the patch's changelog.
|
351 |
|
|
|
352 |
|
|
Acked-by: is often used by the maintainer of the affected code when that
|
353 |
|
|
maintainer neither contributed to nor forwarded the patch.
|
354 |
|
|
|
355 |
|
|
Acked-by: is not as formal as Signed-off-by:. It is a record that the acker
|
356 |
|
|
has at least reviewed the patch and has indicated acceptance. Hence patch
|
357 |
|
|
mergers will sometimes manually convert an acker's "yep, looks good to me"
|
358 |
|
|
into an Acked-by:.
|
359 |
|
|
|
360 |
|
|
Acked-by: does not necessarily indicate acknowledgement of the entire patch.
|
361 |
|
|
For example, if a patch affects multiple subsystems and has an Acked-by: from
|
362 |
|
|
one subsystem maintainer then this usually indicates acknowledgement of just
|
363 |
|
|
the part which affects that maintainer's code. Judgement should be used here.
|
364 |
|
|
When in doubt people should refer to the original discussion in the mailing
|
365 |
|
|
list archives.
|
366 |
|
|
|
367 |
|
|
|
368 |
|
|
14) The canonical patch format
|
369 |
|
|
|
370 |
|
|
The canonical patch subject line is:
|
371 |
|
|
|
372 |
|
|
Subject: [PATCH 001/123] subsystem: summary phrase
|
373 |
|
|
|
374 |
|
|
The canonical patch message body contains the following:
|
375 |
|
|
|
376 |
|
|
- A "from" line specifying the patch author.
|
377 |
|
|
|
378 |
|
|
- An empty line.
|
379 |
|
|
|
380 |
|
|
- The body of the explanation, which will be copied to the
|
381 |
|
|
permanent changelog to describe this patch.
|
382 |
|
|
|
383 |
|
|
- The "Signed-off-by:" lines, described above, which will
|
384 |
|
|
also go in the changelog.
|
385 |
|
|
|
386 |
|
|
- A marker line containing simply "---".
|
387 |
|
|
|
388 |
|
|
- Any additional comments not suitable for the changelog.
|
389 |
|
|
|
390 |
|
|
- The actual patch (diff output).
|
391 |
|
|
|
392 |
|
|
The Subject line format makes it very easy to sort the emails
|
393 |
|
|
alphabetically by subject line - pretty much any email reader will
|
394 |
|
|
support that - since because the sequence number is zero-padded,
|
395 |
|
|
the numerical and alphabetic sort is the same.
|
396 |
|
|
|
397 |
|
|
The "subsystem" in the email's Subject should identify which
|
398 |
|
|
area or subsystem of the kernel is being patched.
|
399 |
|
|
|
400 |
|
|
The "summary phrase" in the email's Subject should concisely
|
401 |
|
|
describe the patch which that email contains. The "summary
|
402 |
|
|
phrase" should not be a filename. Do not use the same "summary
|
403 |
|
|
phrase" for every patch in a whole patch series (where a "patch
|
404 |
|
|
series" is an ordered sequence of multiple, related patches).
|
405 |
|
|
|
406 |
|
|
Bear in mind that the "summary phrase" of your email becomes
|
407 |
|
|
a globally-unique identifier for that patch. It propagates
|
408 |
|
|
all the way into the git changelog. The "summary phrase" may
|
409 |
|
|
later be used in developer discussions which refer to the patch.
|
410 |
|
|
People will want to google for the "summary phrase" to read
|
411 |
|
|
discussion regarding that patch.
|
412 |
|
|
|
413 |
|
|
A couple of example Subjects:
|
414 |
|
|
|
415 |
|
|
Subject: [patch 2/5] ext2: improve scalability of bitmap searching
|
416 |
|
|
Subject: [PATCHv2 001/207] x86: fix eflags tracking
|
417 |
|
|
|
418 |
|
|
The "from" line must be the very first line in the message body,
|
419 |
|
|
and has the form:
|
420 |
|
|
|
421 |
|
|
From: Original Author
|
422 |
|
|
|
423 |
|
|
The "from" line specifies who will be credited as the author of the
|
424 |
|
|
patch in the permanent changelog. If the "from" line is missing,
|
425 |
|
|
then the "From:" line from the email header will be used to determine
|
426 |
|
|
the patch author in the changelog.
|
427 |
|
|
|
428 |
|
|
The explanation body will be committed to the permanent source
|
429 |
|
|
changelog, so should make sense to a competent reader who has long
|
430 |
|
|
since forgotten the immediate details of the discussion that might
|
431 |
|
|
have led to this patch.
|
432 |
|
|
|
433 |
|
|
The "---" marker line serves the essential purpose of marking for patch
|
434 |
|
|
handling tools where the changelog message ends.
|
435 |
|
|
|
436 |
|
|
One good use for the additional comments after the "---" marker is for
|
437 |
|
|
a diffstat, to show what files have changed, and the number of inserted
|
438 |
|
|
and deleted lines per file. A diffstat is especially useful on bigger
|
439 |
|
|
patches. Other comments relevant only to the moment or the maintainer,
|
440 |
|
|
not suitable for the permanent changelog, should also go here.
|
441 |
|
|
Use diffstat options "-p 1 -w 70" so that filenames are listed from the
|
442 |
|
|
top of the kernel source tree and don't use too much horizontal space
|
443 |
|
|
(easily fit in 80 columns, maybe with some indentation).
|
444 |
|
|
|
445 |
|
|
See more details on the proper patch format in the following
|
446 |
|
|
references.
|
447 |
|
|
|
448 |
|
|
|
449 |
|
|
|
450 |
|
|
|
451 |
|
|
-----------------------------------
|
452 |
|
|
SECTION 2 - HINTS, TIPS, AND TRICKS
|
453 |
|
|
-----------------------------------
|
454 |
|
|
|
455 |
|
|
This section lists many of the common "rules" associated with code
|
456 |
|
|
submitted to the kernel. There are always exceptions... but you must
|
457 |
|
|
have a really good reason for doing so. You could probably call this
|
458 |
|
|
section Linus Computer Science 101.
|
459 |
|
|
|
460 |
|
|
|
461 |
|
|
|
462 |
|
|
1) Read Documentation/CodingStyle
|
463 |
|
|
|
464 |
|
|
Nuff said. If your code deviates too much from this, it is likely
|
465 |
|
|
to be rejected without further review, and without comment.
|
466 |
|
|
|
467 |
|
|
One significant exception is when moving code from one file to
|
468 |
|
|
another -- in this case you should not modify the moved code at all in
|
469 |
|
|
the same patch which moves it. This clearly delineates the act of
|
470 |
|
|
moving the code and your changes. This greatly aids review of the
|
471 |
|
|
actual differences and allows tools to better track the history of
|
472 |
|
|
the code itself.
|
473 |
|
|
|
474 |
|
|
Check your patches with the patch style checker prior to submission
|
475 |
|
|
(scripts/checkpatch.pl). The style checker should be viewed as
|
476 |
|
|
a guide not as the final word. If your code looks better with
|
477 |
|
|
a violation then its probably best left alone.
|
478 |
|
|
|
479 |
|
|
The checker reports at three levels:
|
480 |
|
|
- ERROR: things that are very likely to be wrong
|
481 |
|
|
- WARNING: things requiring careful review
|
482 |
|
|
- CHECK: things requiring thought
|
483 |
|
|
|
484 |
|
|
You should be able to justify all violations that remain in your
|
485 |
|
|
patch.
|
486 |
|
|
|
487 |
|
|
|
488 |
|
|
|
489 |
|
|
2) #ifdefs are ugly
|
490 |
|
|
|
491 |
|
|
Code cluttered with ifdefs is difficult to read and maintain. Don't do
|
492 |
|
|
it. Instead, put your ifdefs in a header, and conditionally define
|
493 |
|
|
'static inline' functions, or macros, which are used in the code.
|
494 |
|
|
Let the compiler optimize away the "no-op" case.
|
495 |
|
|
|
496 |
|
|
Simple example, of poor code:
|
497 |
|
|
|
498 |
|
|
dev = alloc_etherdev (sizeof(struct funky_private));
|
499 |
|
|
if (!dev)
|
500 |
|
|
return -ENODEV;
|
501 |
|
|
#ifdef CONFIG_NET_FUNKINESS
|
502 |
|
|
init_funky_net(dev);
|
503 |
|
|
#endif
|
504 |
|
|
|
505 |
|
|
Cleaned-up example:
|
506 |
|
|
|
507 |
|
|
(in header)
|
508 |
|
|
#ifndef CONFIG_NET_FUNKINESS
|
509 |
|
|
static inline void init_funky_net (struct net_device *d) {}
|
510 |
|
|
#endif
|
511 |
|
|
|
512 |
|
|
(in the code itself)
|
513 |
|
|
dev = alloc_etherdev (sizeof(struct funky_private));
|
514 |
|
|
if (!dev)
|
515 |
|
|
return -ENODEV;
|
516 |
|
|
init_funky_net(dev);
|
517 |
|
|
|
518 |
|
|
|
519 |
|
|
|
520 |
|
|
3) 'static inline' is better than a macro
|
521 |
|
|
|
522 |
|
|
Static inline functions are greatly preferred over macros.
|
523 |
|
|
They provide type safety, have no length limitations, no formatting
|
524 |
|
|
limitations, and under gcc they are as cheap as macros.
|
525 |
|
|
|
526 |
|
|
Macros should only be used for cases where a static inline is clearly
|
527 |
|
|
suboptimal [there a few, isolated cases of this in fast paths],
|
528 |
|
|
or where it is impossible to use a static inline function [such as
|
529 |
|
|
string-izing].
|
530 |
|
|
|
531 |
|
|
'static inline' is preferred over 'static __inline__', 'extern inline',
|
532 |
|
|
and 'extern __inline__'.
|
533 |
|
|
|
534 |
|
|
|
535 |
|
|
|
536 |
|
|
4) Don't over-design.
|
537 |
|
|
|
538 |
|
|
Don't try to anticipate nebulous future cases which may or may not
|
539 |
|
|
be useful: "Make it as simple as you can, and no simpler."
|
540 |
|
|
|
541 |
|
|
|
542 |
|
|
|
543 |
|
|
----------------------
|
544 |
|
|
SECTION 3 - REFERENCES
|
545 |
|
|
----------------------
|
546 |
|
|
|
547 |
|
|
Andrew Morton, "The perfect patch" (tpp).
|
548 |
|
|
|
549 |
|
|
|
550 |
|
|
Jeff Garzik, "Linux kernel patch submission format".
|
551 |
|
|
|
552 |
|
|
|
553 |
|
|
Greg Kroah-Hartman, "How to piss off a kernel subsystem maintainer".
|
554 |
|
|
|
555 |
|
|
|
556 |
|
|
|
557 |
|
|
|
558 |
|
|
|
559 |
|
|
NO!!!! No more huge patch bombs to linux-kernel@vger.kernel.org people!
|
560 |
|
|
|
561 |
|
|
|
562 |
|
|
Kernel Documentation/CodingStyle:
|
563 |
|
|
|
564 |
|
|
|
565 |
|
|
Linus Torvalds's mail on the canonical patch format:
|
566 |
|
|
|
567 |
|
|
--
|