Root/
Source at commit fbf123cd4cc0c097fe9a99c90109ebb2a5e94a50 created 10 years 3 months ago. By Lars-Peter Clausen, dma: jz4740: Dequeue descriptor from active list before completing it | |
---|---|
1 | |
2 | Applying Patches To The Linux Kernel |
3 | ------------------------------------ |
4 | |
5 | Original by: Jesper Juhl, August 2005 |
6 | Last update: 2006-01-05 |
7 | |
8 | |
9 | A frequently asked question on the Linux Kernel Mailing List is how to apply |
10 | a patch to the kernel or, more specifically, what base kernel a patch for |
11 | one of the many trees/branches should be applied to. Hopefully this document |
12 | will explain this to you. |
13 | |
14 | In addition to explaining how to apply and revert patches, a brief |
15 | description of the different kernel trees (and examples of how to apply |
16 | their specific patches) is also provided. |
17 | |
18 | |
19 | What is a patch? |
20 | --- |
21 | A patch is a small text document containing a delta of changes between two |
22 | different versions of a source tree. Patches are created with the `diff' |
23 | program. |
24 | To correctly apply a patch you need to know what base it was generated from |
25 | and what new version the patch will change the source tree into. These |
26 | should both be present in the patch file metadata or be possible to deduce |
27 | from the filename. |
28 | |
29 | |
30 | How do I apply or revert a patch? |
31 | --- |
32 | You apply a patch with the `patch' program. The patch program reads a diff |
33 | (or patch) file and makes the changes to the source tree described in it. |
34 | |
35 | Patches for the Linux kernel are generated relative to the parent directory |
36 | holding the kernel source dir. |
37 | |
38 | This means that paths to files inside the patch file contain the name of the |
39 | kernel source directories it was generated against (or some other directory |
40 | names like "a/" and "b/"). |
41 | Since this is unlikely to match the name of the kernel source dir on your |
42 | local machine (but is often useful info to see what version an otherwise |
43 | unlabeled patch was generated against) you should change into your kernel |
44 | source directory and then strip the first element of the path from filenames |
45 | in the patch file when applying it (the -p1 argument to `patch' does this). |
46 | |
47 | To revert a previously applied patch, use the -R argument to patch. |
48 | So, if you applied a patch like this: |
49 | patch -p1 < ../patch-x.y.z |
50 | |
51 | You can revert (undo) it like this: |
52 | patch -R -p1 < ../patch-x.y.z |
53 | |
54 | |
55 | How do I feed a patch/diff file to `patch'? |
56 | --- |
57 | This (as usual with Linux and other UNIX like operating systems) can be |
58 | done in several different ways. |
59 | In all the examples below I feed the file (in uncompressed form) to patch |
60 | via stdin using the following syntax: |
61 | patch -p1 < path/to/patch-x.y.z |
62 | |
63 | If you just want to be able to follow the examples below and don't want to |
64 | know of more than one way to use patch, then you can stop reading this |
65 | section here. |
66 | |
67 | Patch can also get the name of the file to use via the -i argument, like |
68 | this: |
69 | patch -p1 -i path/to/patch-x.y.z |
70 | |
71 | If your patch file is compressed with gzip or bzip2 and you don't want to |
72 | uncompress it before applying it, then you can feed it to patch like this |
73 | instead: |
74 | zcat path/to/patch-x.y.z.gz | patch -p1 |
75 | bzcat path/to/patch-x.y.z.bz2 | patch -p1 |
76 | |
77 | If you wish to uncompress the patch file by hand first before applying it |
78 | (what I assume you've done in the examples below), then you simply run |
79 | gunzip or bunzip2 on the file -- like this: |
80 | gunzip patch-x.y.z.gz |
81 | bunzip2 patch-x.y.z.bz2 |
82 | |
83 | Which will leave you with a plain text patch-x.y.z file that you can feed to |
84 | patch via stdin or the -i argument, as you prefer. |
85 | |
86 | A few other nice arguments for patch are -s which causes patch to be silent |
87 | except for errors which is nice to prevent errors from scrolling out of the |
88 | screen too fast, and --dry-run which causes patch to just print a listing of |
89 | what would happen, but doesn't actually make any changes. Finally --verbose |
90 | tells patch to print more information about the work being done. |
91 | |
92 | |
93 | Common errors when patching |
94 | --- |
95 | When patch applies a patch file it attempts to verify the sanity of the |
96 | file in different ways. |
97 | Checking that the file looks like a valid patch file & checking the code |
98 | around the bits being modified matches the context provided in the patch are |
99 | just two of the basic sanity checks patch does. |
100 | |
101 | If patch encounters something that doesn't look quite right it has two |
102 | options. It can either refuse to apply the changes and abort or it can try |
103 | to find a way to make the patch apply with a few minor changes. |
104 | |
105 | One example of something that's not 'quite right' that patch will attempt to |
106 | fix up is if all the context matches, the lines being changed match, but the |
107 | line numbers are different. This can happen, for example, if the patch makes |
108 | a change in the middle of the file but for some reasons a few lines have |
109 | been added or removed near the beginning of the file. In that case |
110 | everything looks good it has just moved up or down a bit, and patch will |
111 | usually adjust the line numbers and apply the patch. |
112 | |
113 | Whenever patch applies a patch that it had to modify a bit to make it fit |
114 | it'll tell you about it by saying the patch applied with 'fuzz'. |
115 | You should be wary of such changes since even though patch probably got it |
116 | right it doesn't /always/ get it right, and the result will sometimes be |
117 | wrong. |
118 | |
119 | When patch encounters a change that it can't fix up with fuzz it rejects it |
120 | outright and leaves a file with a .rej extension (a reject file). You can |
121 | read this file to see exactly what change couldn't be applied, so you can |
122 | go fix it up by hand if you wish. |
123 | |
124 | If you don't have any third-party patches applied to your kernel source, but |
125 | only patches from kernel.org and you apply the patches in the correct order, |
126 | and have made no modifications yourself to the source files, then you should |
127 | never see a fuzz or reject message from patch. If you do see such messages |
128 | anyway, then there's a high risk that either your local source tree or the |
129 | patch file is corrupted in some way. In that case you should probably try |
130 | re-downloading the patch and if things are still not OK then you'd be advised |
131 | to start with a fresh tree downloaded in full from kernel.org. |
132 | |
133 | Let's look a bit more at some of the messages patch can produce. |
134 | |
135 | If patch stops and presents a "File to patch:" prompt, then patch could not |
136 | find a file to be patched. Most likely you forgot to specify -p1 or you are |
137 | in the wrong directory. Less often, you'll find patches that need to be |
138 | applied with -p0 instead of -p1 (reading the patch file should reveal if |
139 | this is the case -- if so, then this is an error by the person who created |
140 | the patch but is not fatal). |
141 | |
142 | If you get "Hunk #2 succeeded at 1887 with fuzz 2 (offset 7 lines)." or a |
143 | message similar to that, then it means that patch had to adjust the location |
144 | of the change (in this example it needed to move 7 lines from where it |
145 | expected to make the change to make it fit). |
146 | The resulting file may or may not be OK, depending on the reason the file |
147 | was different than expected. |
148 | This often happens if you try to apply a patch that was generated against a |
149 | different kernel version than the one you are trying to patch. |
150 | |
151 | If you get a message like "Hunk #3 FAILED at 2387.", then it means that the |
152 | patch could not be applied correctly and the patch program was unable to |
153 | fuzz its way through. This will generate a .rej file with the change that |
154 | caused the patch to fail and also a .orig file showing you the original |
155 | content that couldn't be changed. |
156 | |
157 | If you get "Reversed (or previously applied) patch detected! Assume -R? [n]" |
158 | then patch detected that the change contained in the patch seems to have |
159 | already been made. |
160 | If you actually did apply this patch previously and you just re-applied it |
161 | in error, then just say [n]o and abort this patch. If you applied this patch |
162 | previously and actually intended to revert it, but forgot to specify -R, |
163 | then you can say [y]es here to make patch revert it for you. |
164 | This can also happen if the creator of the patch reversed the source and |
165 | destination directories when creating the patch, and in that case reverting |
166 | the patch will in fact apply it. |
167 | |
168 | A message similar to "patch: **** unexpected end of file in patch" or "patch |
169 | unexpectedly ends in middle of line" means that patch could make no sense of |
170 | the file you fed to it. Either your download is broken, you tried to feed |
171 | patch a compressed patch file without uncompressing it first, or the patch |
172 | file that you are using has been mangled by a mail client or mail transfer |
173 | agent along the way somewhere, e.g., by splitting a long line into two lines. |
174 | Often these warnings can easily be fixed by joining (concatenating) the |
175 | two lines that had been split. |
176 | |
177 | As I already mentioned above, these errors should never happen if you apply |
178 | a patch from kernel.org to the correct version of an unmodified source tree. |
179 | So if you get these errors with kernel.org patches then you should probably |
180 | assume that either your patch file or your tree is broken and I'd advise you |
181 | to start over with a fresh download of a full kernel tree and the patch you |
182 | wish to apply. |
183 | |
184 | |
185 | Are there any alternatives to `patch'? |
186 | --- |
187 | Yes there are alternatives. |
188 | |
189 | You can use the `interdiff' program (http://cyberelk.net/tim/patchutils/) to |
190 | generate a patch representing the differences between two patches and then |
191 | apply the result. |
192 | This will let you move from something like 2.6.12.2 to 2.6.12.3 in a single |
193 | step. The -z flag to interdiff will even let you feed it patches in gzip or |
194 | bzip2 compressed form directly without the use of zcat or bzcat or manual |
195 | decompression. |
196 | |
197 | Here's how you'd go from 2.6.12.2 to 2.6.12.3 in a single step: |
198 | interdiff -z ../patch-2.6.12.2.bz2 ../patch-2.6.12.3.gz | patch -p1 |
199 | |
200 | Although interdiff may save you a step or two you are generally advised to |
201 | do the additional steps since interdiff can get things wrong in some cases. |
202 | |
203 | Another alternative is `ketchup', which is a python script for automatic |
204 | downloading and applying of patches (http://www.selenic.com/ketchup/). |
205 | |
206 | Other nice tools are diffstat, which shows a summary of changes made by a |
207 | patch; lsdiff, which displays a short listing of affected files in a patch |
208 | file, along with (optionally) the line numbers of the start of each patch; |
209 | and grepdiff, which displays a list of the files modified by a patch where |
210 | the patch contains a given regular expression. |
211 | |
212 | |
213 | Where can I download the patches? |
214 | --- |
215 | The patches are available at http://kernel.org/ |
216 | Most recent patches are linked from the front page, but they also have |
217 | specific homes. |
218 | |
219 | The 2.6.x.y (-stable) and 2.6.x patches live at |
220 | ftp://ftp.kernel.org/pub/linux/kernel/v2.6/ |
221 | |
222 | The -rc patches live at |
223 | ftp://ftp.kernel.org/pub/linux/kernel/v2.6/testing/ |
224 | |
225 | The -git patches live at |
226 | ftp://ftp.kernel.org/pub/linux/kernel/v2.6/snapshots/ |
227 | |
228 | The -mm kernels live at |
229 | ftp://ftp.kernel.org/pub/linux/kernel/people/akpm/patches/2.6/ |
230 | |
231 | In place of ftp.kernel.org you can use ftp.cc.kernel.org, where cc is a |
232 | country code. This way you'll be downloading from a mirror site that's most |
233 | likely geographically closer to you, resulting in faster downloads for you, |
234 | less bandwidth used globally and less load on the main kernel.org servers -- |
235 | these are good things, so do use mirrors when possible. |
236 | |
237 | |
238 | The 2.6.x kernels |
239 | --- |
240 | These are the base stable releases released by Linus. The highest numbered |
241 | release is the most recent. |
242 | |
243 | If regressions or other serious flaws are found, then a -stable fix patch |
244 | will be released (see below) on top of this base. Once a new 2.6.x base |
245 | kernel is released, a patch is made available that is a delta between the |
246 | previous 2.6.x kernel and the new one. |
247 | |
248 | To apply a patch moving from 2.6.11 to 2.6.12, you'd do the following (note |
249 | that such patches do *NOT* apply on top of 2.6.x.y kernels but on top of the |
250 | base 2.6.x kernel -- if you need to move from 2.6.x.y to 2.6.x+1 you need to |
251 | first revert the 2.6.x.y patch). |
252 | |
253 | Here are some examples: |
254 | |
255 | # moving from 2.6.11 to 2.6.12 |
256 | $ cd ~/linux-2.6.11 # change to kernel source dir |
257 | $ patch -p1 < ../patch-2.6.12 # apply the 2.6.12 patch |
258 | $ cd .. |
259 | $ mv linux-2.6.11 linux-2.6.12 # rename source dir |
260 | |
261 | # moving from 2.6.11.1 to 2.6.12 |
262 | $ cd ~/linux-2.6.11.1 # change to kernel source dir |
263 | $ patch -p1 -R < ../patch-2.6.11.1 # revert the 2.6.11.1 patch |
264 | # source dir is now 2.6.11 |
265 | $ patch -p1 < ../patch-2.6.12 # apply new 2.6.12 patch |
266 | $ cd .. |
267 | $ mv linux-2.6.11.1 linux-2.6.12 # rename source dir |
268 | |
269 | |
270 | The 2.6.x.y kernels |
271 | --- |
272 | Kernels with 4-digit versions are -stable kernels. They contain small(ish) |
273 | critical fixes for security problems or significant regressions discovered |
274 | in a given 2.6.x kernel. |
275 | |
276 | This is the recommended branch for users who want the most recent stable |
277 | kernel and are not interested in helping test development/experimental |
278 | versions. |
279 | |
280 | If no 2.6.x.y kernel is available, then the highest numbered 2.6.x kernel is |
281 | the current stable kernel. |
282 | |
283 | note: the -stable team usually do make incremental patches available as well |
284 | as patches against the latest mainline release, but I only cover the |
285 | non-incremental ones below. The incremental ones can be found at |
286 | ftp://ftp.kernel.org/pub/linux/kernel/v2.6/incr/ |
287 | |
288 | These patches are not incremental, meaning that for example the 2.6.12.3 |
289 | patch does not apply on top of the 2.6.12.2 kernel source, but rather on top |
290 | of the base 2.6.12 kernel source . |
291 | So, in order to apply the 2.6.12.3 patch to your existing 2.6.12.2 kernel |
292 | source you have to first back out the 2.6.12.2 patch (so you are left with a |
293 | base 2.6.12 kernel source) and then apply the new 2.6.12.3 patch. |
294 | |
295 | Here's a small example: |
296 | |
297 | $ cd ~/linux-2.6.12.2 # change into the kernel source dir |
298 | $ patch -p1 -R < ../patch-2.6.12.2 # revert the 2.6.12.2 patch |
299 | $ patch -p1 < ../patch-2.6.12.3 # apply the new 2.6.12.3 patch |
300 | $ cd .. |
301 | $ mv linux-2.6.12.2 linux-2.6.12.3 # rename the kernel source dir |
302 | |
303 | |
304 | The -rc kernels |
305 | --- |
306 | These are release-candidate kernels. These are development kernels released |
307 | by Linus whenever he deems the current git (the kernel's source management |
308 | tool) tree to be in a reasonably sane state adequate for testing. |
309 | |
310 | These kernels are not stable and you should expect occasional breakage if |
311 | you intend to run them. This is however the most stable of the main |
312 | development branches and is also what will eventually turn into the next |
313 | stable kernel, so it is important that it be tested by as many people as |
314 | possible. |
315 | |
316 | This is a good branch to run for people who want to help out testing |
317 | development kernels but do not want to run some of the really experimental |
318 | stuff (such people should see the sections about -git and -mm kernels below). |
319 | |
320 | The -rc patches are not incremental, they apply to a base 2.6.x kernel, just |
321 | like the 2.6.x.y patches described above. The kernel version before the -rcN |
322 | suffix denotes the version of the kernel that this -rc kernel will eventually |
323 | turn into. |
324 | So, 2.6.13-rc5 means that this is the fifth release candidate for the 2.6.13 |
325 | kernel and the patch should be applied on top of the 2.6.12 kernel source. |
326 | |
327 | Here are 3 examples of how to apply these patches: |
328 | |
329 | # first an example of moving from 2.6.12 to 2.6.13-rc3 |
330 | $ cd ~/linux-2.6.12 # change into the 2.6.12 source dir |
331 | $ patch -p1 < ../patch-2.6.13-rc3 # apply the 2.6.13-rc3 patch |
332 | $ cd .. |
333 | $ mv linux-2.6.12 linux-2.6.13-rc3 # rename the source dir |
334 | |
335 | # now let's move from 2.6.13-rc3 to 2.6.13-rc5 |
336 | $ cd ~/linux-2.6.13-rc3 # change into the 2.6.13-rc3 dir |
337 | $ patch -p1 -R < ../patch-2.6.13-rc3 # revert the 2.6.13-rc3 patch |
338 | $ patch -p1 < ../patch-2.6.13-rc5 # apply the new 2.6.13-rc5 patch |
339 | $ cd .. |
340 | $ mv linux-2.6.13-rc3 linux-2.6.13-rc5 # rename the source dir |
341 | |
342 | # finally let's try and move from 2.6.12.3 to 2.6.13-rc5 |
343 | $ cd ~/linux-2.6.12.3 # change to the kernel source dir |
344 | $ patch -p1 -R < ../patch-2.6.12.3 # revert the 2.6.12.3 patch |
345 | $ patch -p1 < ../patch-2.6.13-rc5 # apply new 2.6.13-rc5 patch |
346 | $ cd .. |
347 | $ mv linux-2.6.12.3 linux-2.6.13-rc5 # rename the kernel source dir |
348 | |
349 | |
350 | The -git kernels |
351 | --- |
352 | These are daily snapshots of Linus' kernel tree (managed in a git |
353 | repository, hence the name). |
354 | |
355 | These patches are usually released daily and represent the current state of |
356 | Linus's tree. They are more experimental than -rc kernels since they are |
357 | generated automatically without even a cursory glance to see if they are |
358 | sane. |
359 | |
360 | -git patches are not incremental and apply either to a base 2.6.x kernel or |
361 | a base 2.6.x-rc kernel -- you can see which from their name. |
362 | A patch named 2.6.12-git1 applies to the 2.6.12 kernel source and a patch |
363 | named 2.6.13-rc3-git2 applies to the source of the 2.6.13-rc3 kernel. |
364 | |
365 | Here are some examples of how to apply these patches: |
366 | |
367 | # moving from 2.6.12 to 2.6.12-git1 |
368 | $ cd ~/linux-2.6.12 # change to the kernel source dir |
369 | $ patch -p1 < ../patch-2.6.12-git1 # apply the 2.6.12-git1 patch |
370 | $ cd .. |
371 | $ mv linux-2.6.12 linux-2.6.12-git1 # rename the kernel source dir |
372 | |
373 | # moving from 2.6.12-git1 to 2.6.13-rc2-git3 |
374 | $ cd ~/linux-2.6.12-git1 # change to the kernel source dir |
375 | $ patch -p1 -R < ../patch-2.6.12-git1 # revert the 2.6.12-git1 patch |
376 | # we now have a 2.6.12 kernel |
377 | $ patch -p1 < ../patch-2.6.13-rc2 # apply the 2.6.13-rc2 patch |
378 | # the kernel is now 2.6.13-rc2 |
379 | $ patch -p1 < ../patch-2.6.13-rc2-git3 # apply the 2.6.13-rc2-git3 patch |
380 | # the kernel is now 2.6.13-rc2-git3 |
381 | $ cd .. |
382 | $ mv linux-2.6.12-git1 linux-2.6.13-rc2-git3 # rename source dir |
383 | |
384 | |
385 | The -mm kernels |
386 | --- |
387 | These are experimental kernels released by Andrew Morton. |
388 | |
389 | The -mm tree serves as a sort of proving ground for new features and other |
390 | experimental patches. |
391 | Once a patch has proved its worth in -mm for a while Andrew pushes it on to |
392 | Linus for inclusion in mainline. |
393 | |
394 | Although it's encouraged that patches flow to Linus via the -mm tree, this |
395 | is not always enforced. |
396 | Subsystem maintainers (or individuals) sometimes push their patches directly |
397 | to Linus, even though (or after) they have been merged and tested in -mm (or |
398 | sometimes even without prior testing in -mm). |
399 | |
400 | You should generally strive to get your patches into mainline via -mm to |
401 | ensure maximum testing. |
402 | |
403 | This branch is in constant flux and contains many experimental features, a |
404 | lot of debugging patches not appropriate for mainline etc., and is the most |
405 | experimental of the branches described in this document. |
406 | |
407 | These kernels are not appropriate for use on systems that are supposed to be |
408 | stable and they are more risky to run than any of the other branches (make |
409 | sure you have up-to-date backups -- that goes for any experimental kernel but |
410 | even more so for -mm kernels). |
411 | |
412 | These kernels in addition to all the other experimental patches they contain |
413 | usually also contain any changes in the mainline -git kernels available at |
414 | the time of release. |
415 | |
416 | Testing of -mm kernels is greatly appreciated since the whole point of the |
417 | tree is to weed out regressions, crashes, data corruption bugs, build |
418 | breakage (and any other bug in general) before changes are merged into the |
419 | more stable mainline Linus tree. |
420 | But testers of -mm should be aware that breakage in this tree is more common |
421 | than in any other tree. |
422 | |
423 | The -mm kernels are not released on a fixed schedule, but usually a few -mm |
424 | kernels are released in between each -rc kernel (1 to 3 is common). |
425 | The -mm kernels apply to either a base 2.6.x kernel (when no -rc kernels |
426 | have been released yet) or to a Linus -rc kernel. |
427 | |
428 | Here are some examples of applying the -mm patches: |
429 | |
430 | # moving from 2.6.12 to 2.6.12-mm1 |
431 | $ cd ~/linux-2.6.12 # change to the 2.6.12 source dir |
432 | $ patch -p1 < ../2.6.12-mm1 # apply the 2.6.12-mm1 patch |
433 | $ cd .. |
434 | $ mv linux-2.6.12 linux-2.6.12-mm1 # rename the source appropriately |
435 | |
436 | # moving from 2.6.12-mm1 to 2.6.13-rc3-mm3 |
437 | $ cd ~/linux-2.6.12-mm1 |
438 | $ patch -p1 -R < ../2.6.12-mm1 # revert the 2.6.12-mm1 patch |
439 | # we now have a 2.6.12 source |
440 | $ patch -p1 < ../patch-2.6.13-rc3 # apply the 2.6.13-rc3 patch |
441 | # we now have a 2.6.13-rc3 source |
442 | $ patch -p1 < ../2.6.13-rc3-mm3 # apply the 2.6.13-rc3-mm3 patch |
443 | $ cd .. |
444 | $ mv linux-2.6.12-mm1 linux-2.6.13-rc3-mm3 # rename the source dir |
445 | |
446 | |
447 | This concludes this list of explanations of the various kernel trees. |
448 | I hope you are now clear on how to apply the various patches and help testing |
449 | the kernel. |
450 | |
451 | Thank you's to Randy Dunlap, Rolf Eike Beer, Linus Torvalds, Bodo Eggert, |
452 | Johannes Stezenbach, Grant Coady, Pavel Machek and others that I may have |
453 | forgotten for their reviews and contributions to this document. |
454 | |
455 |
Branches:
ben-wpan
ben-wpan-stefan
javiroman/ks7010
jz-2.6.34
jz-2.6.34-rc5
jz-2.6.34-rc6
jz-2.6.34-rc7
jz-2.6.35
jz-2.6.36
jz-2.6.37
jz-2.6.38
jz-2.6.39
jz-3.0
jz-3.1
jz-3.11
jz-3.12
jz-3.13
jz-3.15
jz-3.16
jz-3.18-dt
jz-3.2
jz-3.3
jz-3.4
jz-3.5
jz-3.6
jz-3.6-rc2-pwm
jz-3.9
jz-3.9-clk
jz-3.9-rc8
jz47xx
jz47xx-2.6.38
master
Tags:
od-2011-09-04
od-2011-09-18
v2.6.34-rc5
v2.6.34-rc6
v2.6.34-rc7
v3.9