1
2 How to Get Your Change Into the Linux Kernel
3 or
4 Care And Operation Of Your Linus Torvalds
5
6
7
8 For a person or company who wishes to submit a change to the Linux
9 kernel, the process can sometimes be daunting if you're not familiar
10 with "the system." This text is a collection of suggestions which
11 can greatly increase the chances of your change being accepted.
12
13 If you are submitting a driver, also read Documentation/SubmittingDrivers.
14
15
16
17 --------------------------------------------
18 SECTION 1 - CREATING AND SENDING YOUR CHANGE
19 --------------------------------------------
20
21
22
23 1) "diff -u"
24 ------------
25
26 Use "diff -u" or "diff -urN" to create patches.
27
28 All changes to the Linux kernel occur in the form of patches, as
29 generated by diff(1). When creating your patch, make sure to create it
30 in "unified diff" format, as supplied by the '-u' argument to diff(1).
31 Patches should be based in the root kernel source directory, not in
32 any lower subdirectory.
33
34 To create a patch for a single file, it is often sufficient to do:
35
36 SRCTREE= /devel/linux-2.4
37 MYFILE= drivers/net/mydriver.c
38
39 cd $SRCTREE
40 cp $MYFILE $MYFILE.orig
41 vi $MYFILE # make your change
42 diff -u $MYFILE.orig $MYFILE > /tmp/patch
43
44 To create a patch for multiple files, you should unpack a "vanilla",
45 or unmodified kernel source tree, and generate a diff against your
46 own source tree. For example:
47
48 MYSRC= /devel/linux-2.4
49
50 tar xvfz linux-2.4.0-test11.tar.gz
51 mv linux linux-vanilla
52 wget http://www.moses.uklinux.net/patches/dontdiff
53 diff -urN -X dontdiff linux-vanilla $MYSRC > /tmp/patch
54 rm -f dontdiff
55
56 "dontdiff" is a list of files which are generated by the kernel during
57 the build process, and should be ignored in any diff(1)-generated
58 patch. dontdiff is maintained by Tigran Aivazian <tigran@veritas.com>
59
60 Make sure your patch does not include any extra files which do not
61 belong in a patch submission. Make sure to review your patch -after-
62 generated it with diff(1), to ensure accuracy.
63
64
65 2) Describe your changes.
66
67 Describe the technical detail of the change(s) your patch includes.
68
69 Be as specific as possible. The WORST descriptions possible include
70 things like "update driver X", "bug fix for driver X", or "this patch
71 includes updates for subsystem X. Please apply."
72
73 If your description starts to get long, that's a sign that you probably
74 need to split up your patch. See #3, next.
75
76
77
78 3) Separate your changes.
79
80 Separate each logical change into its own patch.
81
82 For example, if your changes include both bug fixes and performance
83 enhancements for a single driver, separate those changes into two
84 or more patches. If your changes include an API update, and a new
85 driver which uses that new API, separate those into two patches.
86
87 On the other hand, if you make a single change to numerous files,
88 group those changes into a single patch. Thus a single logical change
89 is contained within a single patch.
90
91 If one patch depends on another patch in order for a change to be
92 complete, that is OK. Simply note "this patch depends on patch X"
93 in your patch description.
94
95
96 4) Select e-mail destination.
97
98 Look through the MAINTAINERS file and the source code, and determine
99 if your change applies to a specific subsystem of the kernel, with
100 an assigned maintainer. If so, e-mail that person.
101
102 If no maintainer is listed, or the maintainer does not respond, send
103 your patch to the primary Linux kernel developer's mailing list,
104 linux-kernel@vger.kernel.org. Most kernel developers monitor this
105 e-mail list, and can comment on your changes.
106
107 Linus Torvalds is the final arbiter of all changes accepted into the
108 Linux kernel. His e-mail address is torvalds@transmeta.com. He gets
109 a lot of e-mail, so typically you should do your best to -avoid- sending
110 him e-mail.
111
112 Patches which are bug fixes, are "obvious" changes, or similarly
113 require little discussion should be sent or CC'd to Linus. Patches
114 which require discussion or do not have a clear advantage should
115 usually be sent first to linux-kernel. Only after the patch is
116 discussed should the patch then be submitted to Linus.
117
118
119
120 5) Select your CC (e-mail carbon copy) list.
121
122 Unless you have a reason NOT to do so, CC linux-kernel@vger.kernel.org.
123
124 Other kernel developers besides Linus need to be aware of your change,
125 so that they may comment on it and offer code review and suggestions.
126 linux-kernel is the primary Linux kernel developer mailing list.
127 Other mailing lists are available for specific subsystems, such as
128 USB, framebuffer devices, the VFS, the SCSI subsystem, etc. See the
129 MAINTAINERS file for a mailing list that relates specifically to
130 your change.
131
132 Even if the maintainer did not respond in step #4, make sure to ALWAYS
133 copy the maintainer when you change their code.
134
135
136
137 6) No MIME, no links, no compression, no attachments. Just plain text.
138
139 Linus and other kernel developers need to be able to read and comment
140 on the changes you are submitting. It is important for a kernel
141 developer to be able to "quote" your changes, using standard e-mail
142 tools, so that they may comment on specific portions of your code.
143
144 For this reason, all patches should be submitting e-mail "inline".
145 WARNING: Be wary of your editor's word-wrap corrupting your patch,
146 if you choose to cut-n-paste your patch.
147
148 Do not attach the patch as a MIME attachment, compressed or not.
149 Many popular e-mail applications will not always transmit a MIME
150 attachment as plain text, making it impossible to comment on your
151 code. A MIME attachment also takes Linus a bit more time to process,
152 decreasing the likelihood of your MIME-attached change being accepted.
153
154 Exception: If your mailer is mangling patches then someone may ask
155 you to re-send them using MIME.
156
157
158
159 7) E-mail size.
160
161 When sending patches to Linus, always follow step #6.
162
163 Large changes are not appropriate for mailing lists, and some
164 maintainers. If your patch, uncompressed, exceeds 40Kb in size,
165 it is preferred that you store your patch on an Internet-accessible
166 server, and provide instead a URL (link) pointing to your patch.
167
168
169
170 8) Name your kernel version.
171
172 It is important to note, either in the subject line or in the patch
173 description, the kernel version to which this patch applies.
174
175 If the patch does not apply cleanly to the latest kernel version,
176 Linus will not apply it.
177
178
179
180 9) Don't get discouraged. Re-submit.
181
182 After you have submitted your change, be patient and wait. If Linus
183 likes your change and applies it, it will appear in the next version
184 of the kernel that he releases.
185
186 However, if your change doesn't appear in the next version of the
187 kernel, there could be any number of reasons. It's YOUR job to
188 narrow down those reasons, correct what was wrong, and submit your
189 updated change.
190
191 It is quite common for Linus to "drop" your patch without comment.
192 That's the nature of the system. If he drops your patch, it could be
193 due to
194 * Your patch did not apply cleanly to the latest kernel version
195 * Your patch was not sufficiently discussed on linux-kernel.
196 * A style issue (see section 2),
197 * An e-mail formatting issue (re-read this section)
198 * A technical problem with your change
199 * He gets tons of e-mail, and yours got lost in the shuffle
200 * You are being annoying (See Figure 1)
201
202 When in doubt, solicit comments on linux-kernel mailing list.
203
204
205
206 10) Include PATCH in the subject
207
208 Due to high e-mail traffic to Linus, and to linux-kernel, it is common
209 convention to prefix your subject line with [PATCH]. This lets Linus
210 and other kernel developers more easily distinguish patches from other
211 e-mail discussions.
212
213
214
215 -----------------------------------
216 SECTION 2 - HINTS, TIPS, AND TRICKS
217 -----------------------------------
218
219 This section lists many of the common "rules" associated with code
220 submitted to the kernel. There are always exceptions... but you must
221 have a really good reason for doing so. You could probably call this
222 section Linus Computer Science 101.
223
224
225
226 1) Read Documentation/CodingStyle
227
228 Nuff said. If your code deviates too much from this, it is likely
229 to be rejected without further review, and without comment.
230
231
232
233 2) #ifdefs are ugly
234
235 Code cluttered with ifdefs is difficult to read and maintain. Don't do
236 it. Instead, put your ifdefs in a header, and conditionally define
237 'static inline' functions, or macros, which are used in the code.
238 Let the compiler optimize away the "no-op" case.
239
240 Simple example, of poor code:
241
242 dev = init_etherdev (NULL, 0);
243 if (!dev)
244 return -ENODEV;
245 #ifdef CONFIG_NET_FUNKINESS
246 init_funky_net(dev);
247 #endif
248
249 Cleaned-up example:
250
251 (in header)
252 #ifndef CONFIG_NET_FUNKINESS
253 static inline void init_funky_net (struct net_device *d) {}
254 #endif
255
256 (in the code itself)
257 dev = init_etherdev (NULL, 0);
258 if (!dev)
259 return -ENODEV;
260 init_funky_net(dev);
261
262
263
264 3) 'static inline' is better than a macro
265
266 Static inline functions are greatly preferred over macros.
267 They provide type safety, have no length limitations, no formatting
268 limitations, and under gcc they are as cheap as macros.
269
270 Macros should only be used for cases where a static inline is clearly
271 suboptimal [there a few, isolated cases of this in fast paths],
272 or where it is impossible to use a static inline function [such as
273 string-izing].
274
275 'static inline' is preferred over 'static __inline__', 'extern inline',
276 and 'extern __inline__'.
277
278
279
280 4) Don't over-design.
281
282 Don't try to anticipate nebulous future cases which may or may not
283 be useful: "Make it as simple as you can, and no simpler"
284
285
286
This page was automatically generated by the
LXR engine.
Visit the LXR main site for more
information.