doc/en/kernel-upgrade.xml

<?xml version="1.0" encoding="UTF-8"?>
<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/kernel-upgrade.xml,v 1.23 2013/02/23 17:53:47 swift Exp $ -->

<!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
<guide>
<title>Gentoo Linux Kernel Upgrade Guide</title>
<author title="Author">
  <mail link="dsd@gentoo.org">Daniel Drake</mail>
</author>

<abstract>
This document describes the process of upgrading your kernel from one release
to another.
</abstract>

<!-- The content of this document is licensed under the CC-BY-SA license -->
<!-- See http://creativecommons.org/licenses/by-sa/2.5 -->
<license/>

<version>5</version>
<date>2013-06-02</date>

<chapter>
<title>Introduction</title>
<section>
<body>

<p>
The kernel is one of the few package classes in portage that requires some
manual intervention to complete the upgrade. Portage will download and
install the kernel source for you, but then it is up to you to step in and
compile the new kernel before any changes will take effect.
</p>

<p>
Although this guide is targeted at users upgrading from one kernel release
to another, it will also be useful for users migrating from one kernel
package to another.
</p>

<p>
<c>gentoo-sources</c> is used as an example in this document, however, the
instructions here also apply to the other packages present in our tree.
</p>

</body>
</section>
</chapter>

<chapter>
<title>Why upgrade the kernel?</title>
<section>
<body>

<p>
Generally, upgrading from one minor kernel release to the next won't bring any
major differences. There are several reasons to upgrade the kernel. One is to
take advantage of a specific new feature or driver; another is to be protected
against a security vulnerability, or just to maintain an up-to-date and healthy
system.
</p>

<p>
Even if you choose not to update to every new kernel revision, it is
recommended that you at least upgrade from time to time. It is strongly
recommended that you immediately upgrade to a new kernel if that new release
solves a security problem.
</p>

</body>
</section>
</chapter>

<chapter>
<title>Obtaining the newer sources through Portage</title>
<section>
<body>

<p>
You upgrade the kernel sources like you would upgrade any other package -
using the <c>emerge</c> utility. It will probably be the case that you want to
upgrade your kernel when you see the upgrade appearing on your world updates
list. For example:
</p>

<pre caption="New kernel sources appearing on update list">
# <i>emerge -Dup world</i>
Calculating dependencies ...done!
[ebuild    NS ] sys-kernel/gentoo-sources-2.6.39-r3 [2.6.38-r6]
</pre>

<note>
The "NS" label in the above output means that the new kernel will be installed
in a New Slot, i.e. the sources of your old kernel will be kept around, until
you manually remove them.
</note>

<p>
You can then go ahead and install the update, e.g.:
</p>

<pre caption="Upgrading your kernel sources">
# <i>emerge -u gentoo-sources</i>
</pre>

<p>
The kernel sources will then be installed into a subdirectory of
<path>/usr/src</path>. In the above example, the new kernel sources will be
installed at <path>/usr/src/linux-2.6.39-gentoo-r3</path>.
</p>

</body>
</section>
</chapter>

<chapter>
<title>Updating the /usr/src/linux symbolic link</title>
<section>
<body>

<p>
Gentoo requires that the <path>/usr/src/linux</path> symbolic link points to
the sources of the kernel you are running.
</p>

<p>
Portage can update the symlink automatically when you emerge new kernel
sources. All you have to do is add the <c>symlink</c> flag to the USE variable
in <path>/etc/portage/make.conf</path>.
</p>

<pre caption="Example of USE variable in /etc/portage/make.conf">
<comment>(Add the symlink keyword)</comment>
USE="<i>symlink</i> x86 3dnow 3dnowex X aac aalib adns alsa apache2"
</pre>

<p>
Alternatively, you could use <c>app-admin/eselect</c> to modify the symlink.
</p>

<pre caption="Using eselect to symlink">
<comment>(Install eselect if you don't have it)</comment>
# <i>emerge eselect</i>
<comment>(See the list of available kernels)</comment>
# <i>eselect kernel list</i>
Available kernel symlink targets:
  [1]   linux-2.6.39-gentoo-r3
  [2]   linux-2.6.38-gentoo-r6 *
<comment>(Select the correct kernel)</comment>
# <i>eselect kernel set 1</i>
<comment>(Verify the kernel was symlinked)</comment>
# <i>eselect kernel list</i>
  [1]   linux-2.6.39-gentoo-r3 *
  [2]   linux-2.6.38-gentoo-r6
</pre>

<p>
If you really want to do it yourself, the following example shows you how to
make the link point to <path>linux-2.6.39-gentoo-r3</path>:
</p>

<pre caption="Updating the /usr/src/linux softlink manually">
# <i>cd /usr/src</i>
# <i>ln -sfn linux-2.6.39-gentoo-r3 linux</i>
</pre>

</body>
</section>
</chapter>

<chapter id="install">
<title>Configuring, compiling and installing the new kernel</title>
<section>
<body>

<p>
For either of these options, you should refer to the instructions given in the
<uri link="/doc/en/handbook/">Gentoo Handbook</uri> relating to <e>Configuring
the Kernel</e> and <e>Configuring the Bootloader</e>. Below is an outline of
the required actions:
</p>

</body>
</section>
<section>
<title>Option 1: Automatic kernel setup with Genkernel</title>
<body>

<p>
If you are a genkernel user, you just need to repeat the stages you went
through when installing your kernel for the first time.
</p>

<p>
Simply run genkernel in the normal way:
</p>

<pre caption="Invoking genkernel">
# <i>genkernel all</i>
</pre>

<p>
You can also use extra parameters for other genkernel functionality. For
example, if you wish to configure some extra kernel options using
<c>menuconfig</c> and you wish genkernel to automatically update your grub boot
loader configuration, then invoke genkernel as follows:
</p>

<pre caption="Invoking genkernel with some common arguments">
# <i>genkernel --menuconfig --bootloader=grub all</i>
</pre>

<p>
For more info, follow the <uri link="/doc/en/genkernel.xml">Gentoo Linux
Genkernel Guide</uri>, or refer to the <uri link="/doc/en/handbook/">Gentoo
Handbook</uri>. Many of the options can be set in the configuration file for
<c>genkernel</c>, <path>/etc/genkernel.conf</path>. Also take a look at the <uri
link="/doc/en/initramfs-guide.xml">Gentoo Linux Initial RAM file system
guide</uri>.
</p>

</body>
</section>
<section>
<title>Option 2: Manual configuration</title>
<body>

<p>
To begin, open the <c>menuconfig</c> utility in the kernel source tree:
</p>

<pre caption="Invoking menuconfig">
# <i>cd /usr/src/linux</i>
# <i>make menuconfig</i>
</pre>

<p>
Select the options required for your hardware and operating environment. For
additional information on kernel configuration, refer to the chapter entitled
<e>Configuring the Kernel</e> of the <uri
link="/doc/en/handbook/index.xml">Gentoo Handbook</uri>.
</p>

<p>
Next, compile your kernel and copy it over to your boot partition. Again,
follow the <uri link="/doc/en/handbook/index.xml">Gentoo Handbook</uri>
instructions outlined in the chapter on <e>Configuring the Bootloader</e>. If
<path>/boot</path> is a separate partition, ensure it is mounted before copying
the compiled kernel to this directory! Failing to do so would keep you from
booting the system with your new kernel.
</p>

<pre caption="Compiling and installing the new kernel">
# <i>make &amp;&amp; make modules_install</i>
# <i>mount /boot</i>
# <i>cp arch/i386/boot/bzImage /boot/bzImage-2.6.39-gentoo-r3</i>
</pre>

<p>
Finally, you should update your boot loader configuration, adding an entry for
the new kernel (don't delete the old one just yet!) and unmount the
<path>/boot</path> partition. Again, refer to the
<uri link="/doc/en/handbook/index.xml">Gentoo Handbook</uri>
for detailed instructions on this procedure.
</p>

</body>
</section>
</chapter>

<chapter>
<title>Reinstalling external modules</title>
<section>
<body>

<p>
If you use any kernel modules that are not included in the kernel source tree
but are provided elsewhere in Portage (e.g. ALSA drivers and NVIDIA or ATI
graphics drivers), then you must reinstall these after upgrading the kernel.
This is as simple as re-merging the packages involved. For more information,
refer to the chapter on <e>Configuring the Kernel</e> in the <uri
link="/doc/en/handbook/">Gentoo Handbook</uri>.
</p>

<p>
We provide you with a built-in Portage set (<c>@module-rebuild</c>) which
rebuilds all the kernel modules you have installed using separate ebuilds (such
as <c>app-laptop/tp_smapi</c>) for the kernel at <path>/usr/src/linux</path>.
Once you have finished upgrading or recompiling your kernel, run <c>emerge
@module-rebuild</c> to rebuild the drivers for your new kernel.
</p>

</body>
</section>
</chapter>

<chapter>
<title>Updating your module configuration</title>
<section>
<body>

<p>
If you have put specific module configuration entries in
<path>/etc/conf.d/modules</path>, then you might need to update the entries
accordingly.
</p>

<pre caption="Sample /etc/conf.d/modules file">
<comment># The following will only auto-load the ieee1394 module in 2.6.38-gentoo-r6 kernels</comment>
modules_2_6_38_gentoo_r6="ieee1394"

<comment># To support auto-loading on all possible versions, drop any reference to versions:</comment>
modules="ohci1394"
</pre>

</body>
</section>
</chapter>

<chapter>
<title>Rebooting into the new kernel</title>
<section>
<body>

<p>
Next, close all applications and reboot your system. If you followed the above
instructions correctly, the boot loader menu should include an entry for the
new kernel. Select the new kernel and let the system boot.
</p>

<p>
Hopefully, your system successfully boots with the new kernel, and you can log
in to resume whatever you were doing. If this is the case, then the upgrade is
complete.
</p>

<p>
If you made a mistake and the system fails to boot with the new kernel, reboot
the system and select the entry from the boot loader that corresponds to the
last known working kernel. You can then restart from the <uri link="#install">
Configuring, compiling, and installing the new kernel</uri> stage -- making
the appropriate changes to correct your mistake. In some cases, you might not
even need to reboot to do this (e.g. you missed a driver for an audio device,
Ethernet adapter, etc.)
</p>

</body>
</section>
</chapter>

<chapter>
<title>Running multiple kernels</title>
<section>
<body>

<p>
You may have noticed, that when installing the sources for your newer kernel,
the sources for your existing kernel were not removed. This is by design -- it
allows you to easily switch between running different kernels.
</p>

<p>
Switching between multiple kernels is as simple as leaving the kernel sources
under <path>/usr/src/</path> and leaving the <path>bzImage</path> binaries on
your <path>/boot</path> partition (referenced by entries in your boot loader
configuration). Every time you boot up, you will be presented with a choice of
which kernel to boot into.
</p>

</body>
</section>
</chapter>

<chapter>
<title>Removing older kernels</title>
<section>
<body>

<p>
Continuing on from the last section, you may be happy with your new kernel and
not have any need to keep older kernel versions around. To easily remove all
sources for a particular kernel except for the newest one, you can take
advantage of the <e>prune</e> option available through <c>emerge</c>. Continuing
the example using <c>gentoo-sources</c>:
</p>

<pre caption="Pruning old versions">
# <i>emerge -P gentoo-sources</i>
</pre>

<p>
In most cases, temporary files used during compilation will still remain under
the appropriate source directory under <path>/usr/src</path>. It is safe to
remove these using <c>rm</c>.
</p>

<p>
You can also safely delete any modules that were used by this kernel. This can
be done by removing the appropriate directories under <path>/lib/modules/</path>
that relate to the kernel versions you are removing. Be careful not to delete
modules belonging to kernels that you still use!
</p>

<p>
Finally, you can mount your <path>/boot</path> partition and remove the
<path>bzImage</path> file(s) for the kernel(s) you are pruning. You should also
edit your boot loader configuration so that it no longer references such
kernel(s).
</p>

</body>
</section>
</chapter>

<chapter>
<title>Advanced: Using your old kernel .config to configure a new one</title>
<section>
<body>

<p>
It is sometimes possible to save time by re-using the configuration file from
your old kernel when configuring the new one. Note that this is generally
unsafe -- too many changes between every kernel release for this to be a
reliable upgrade path.
</p>

<p>
The only situation where this is appropriate is when upgrading from one Gentoo
kernel revision to another. For example, the changes made between
<c>gentoo-sources-2.6.9-r1</c> and <c>gentoo-sources-2.6.9-r2</c> will be very
small, so it is usually OK to use the following method. However, it is not
appropriate to use it in the example used throughout this document: upgrading
from 2.6.8 to 2.6.9. Too many changes between the official releases, and the
method described below does not display enough context to the user, often
resulting in the user running into problems because they disabled options that
they really didn't want to.
</p>

<p>
To reuse your old <path>.config</path>, you simply need to copy it over and
then run <c>make oldconfig</c>. In the following example, we take the
configuration from <c>gentoo-sources-2.6.9-r1</c> and import it into
<c>gentoo-sources-2.6.9-r2</c>.
</p>

<pre caption="Reusing your old config">
# <i>cd /usr/src/linux-2.6.9-gentoo-r2</i>
# <i>cp ../linux-2.6.9-gentoo-r1/.config .</i>
# <i>make oldconfig</i>
</pre>

<pre caption="Reusing your old config with genkernel">
# <i>cd /etc/kernels</i>
# <i>cp kernel-config-x86-2.6.9-gentoo-r1 kernel-config-x86-2.6.9-gentoo-r2</i>
# <i>genkernel all</i>
</pre>

<p>
At this point, you may be asked to produce answers for configuration options
which have changed between the two versions. Once you have done that, you can
compile and install your kernel as normal, without having to go through the
<c>menuconfig</c> configuration process.
</p>

<p>
A much safer upgrading method is to copy your config as previously shown, and
then simply run <c>make menuconfig</c>. This avoids the problems of <c>make
oldconfig</c> mentioned previously, as <c>make menuconfig</c> will load up your
previous configuration as much as possible into the menu. Now all you have to
do is go through each option and look for new sections, removals, and so on. By
using <c>menuconfig</c>, you gain context for all the new changes, and can
easily view the new choices and review help screens much easier. You can even
use this for upgrades such as 2.6.8 to 2.6.9; just make sure you read through
the options carefully. Once you've finished, compile and install your kernel as
normal.
</p>

</body>
</section>
</chapter>

<chapter>
<title>Problems after a kernel upgrade?</title>
<section>
<body>

<p>
With the rapid development of the Linux kernel, it is inevitable that some
changes made from one kernel release to another may cause some problems. If you
have any issues with the latest versions of <uri
link="/doc/en/gentoo-kernel.xml#doc_chap2"> Gentoo-supported kernels</uri> then
please do report the issues to us.
</p>

</body>
</section>
</chapter>

</guide>
1	swift	1.1	<?xml version="1.0" encoding="UTF-8"?>
2	nightmorph	1.24	<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/kernel-upgrade.xml,v 1.23 2013/02/23 17:53:47 swift Exp $ -->
3	swift	1.1
4			<!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
5	swift	1.21	<guide>
6	swift	1.1	<title>Gentoo Linux Kernel Upgrade Guide</title>
7			<author title="Author">
8	neysx	1.12	<mail link="dsd@gentoo.org">Daniel Drake</mail>
9	swift	1.1	</author>
10
11			<abstract>
12			This document describes the process of upgrading your kernel from one release
13			to another.
14			</abstract>
15
16			<!-- The content of this document is licensed under the CC-BY-SA license -->
17	jkt	1.9	<!-- See http://creativecommons.org/licenses/by-sa/2.5 -->
18	swift	1.1	<license/>
19
20	nightmorph	1.24	<version>5</version>
21			<date>2013-06-02</date>
22	swift	1.1
23			<chapter>
24			<title>Introduction</title>
25			<section>
26			<body>
27
28			<p>
29			The kernel is one of the few package classes in portage that requires some
30			manual intervention to complete the upgrade. Portage will download and
31			install the kernel source for you, but then it is up to you to step in and
32			compile the new kernel before any changes will take effect.
33			</p>
34
35			<p>
36	swift	1.4	Although this guide is targeted at users upgrading from one kernel release
37	swift	1.1	to another, it will also be useful for users migrating from one kernel
38			package to another.
39			</p>
40
41			<p>
42	neysx	1.3	<c>gentoo-sources</c> is used as an example in this document, however, the
43	swift	1.1	instructions here also apply to the other packages present in our tree.
44			</p>
45
46			</body>
47			</section>
48			</chapter>
49
50			<chapter>
51	swift	1.4	<title>Why upgrade the kernel?</title>
52	swift	1.1	<section>
53			<body>
54
55			<p>
56			Generally, upgrading from one minor kernel release to the next won't bring any
57	swift	1.4	major differences. There are several reasons to upgrade the kernel. One is to
58	swift	1.18	take advantage of a specific new feature or driver; another is to be protected
59			against a security vulnerability, or just to maintain an up-to-date and healthy
60	swift	1.4	system.
61	swift	1.1	</p>
62
63			<p>
64			Even if you choose not to update to every new kernel revision, it is
65			recommended that you at least upgrade from time to time. It is strongly
66			recommended that you immediately upgrade to a new kernel if that new release
67			solves a security problem.
68			</p>
69
70			</body>
71			</section>
72			</chapter>
73
74			<chapter>
75			<title>Obtaining the newer sources through Portage</title>
76			<section>
77			<body>
78
79			<p>
80			You upgrade the kernel sources like you would upgrade any other package -
81			using the <c>emerge</c> utility. It will probably be the case that you want to
82			upgrade your kernel when you see the upgrade appearing on your world updates
83			list. For example:
84			</p>
85
86			<pre caption="New kernel sources appearing on update list">
87			# <i>emerge -Dup world</i>
88			Calculating dependencies ...done!
89	swift	1.20	[ebuild NS ] sys-kernel/gentoo-sources-2.6.39-r3 [2.6.38-r6]
90	swift	1.1	</pre>
91
92	neysx	1.3	<note>
93			The "NS" label in the above output means that the new kernel will be installed
94			in a New Slot, i.e. the sources of your old kernel will be kept around, until
95			you manually remove them.
96			</note>
97
98	swift	1.1	<p>
99			You can then go ahead and install the update, e.g.:
100			</p>
101
102			<pre caption="Upgrading your kernel sources">
103	neysx	1.3	# <i>emerge -u gentoo-sources</i>
104	swift	1.1	</pre>
105
106			<p>
107	swift	1.18	The kernel sources will then be installed into a subdirectory of
108			<path>/usr/src</path>. In the above example, the new kernel sources will be
109	swift	1.20	installed at <path>/usr/src/linux-2.6.39-gentoo-r3</path>.
110	swift	1.1	</p>
111
112			</body>
113			</section>
114			</chapter>
115
116			<chapter>
117			<title>Updating the /usr/src/linux symbolic link</title>
118			<section>
119			<body>
120
121			<p>
122	neysx	1.8	Gentoo requires that the <path>/usr/src/linux</path> symbolic link points to
123			the sources of the kernel you are running.
124	swift	1.1	</p>
125
126			<p>
127	neysx	1.8	Portage can update the symlink automatically when you emerge new kernel
128			sources. All you have to do is add the <c>symlink</c> flag to the USE variable
129	swift	1.22	in <path>/etc/portage/make.conf</path>.
130	swift	1.1	</p>
131
132	swift	1.22	<pre caption="Example of USE variable in /etc/portage/make.conf">
133	neysx	1.8	<comment>(Add the symlink keyword)</comment>
134			USE="<i>symlink</i> x86 3dnow 3dnowex X aac aalib adns alsa apache2"
135			</pre>
136
137			<p>
138	fox2mike	1.15	Alternatively, you could use <c>app-admin/eselect</c> to modify the symlink.
139			</p>
140
141			<pre caption="Using eselect to symlink">
142			<comment>(Install eselect if you don't have it)</comment>
143			# <i>emerge eselect</i>
144			<comment>(See the list of available kernels)</comment>
145			# <i>eselect kernel list</i>
146			Available kernel symlink targets:
147	swift	1.20	[1] linux-2.6.39-gentoo-r3
148			[2] linux-2.6.38-gentoo-r6 *
149	fox2mike	1.15	<comment>(Select the correct kernel)</comment>
150			# <i>eselect kernel set 1</i>
151	nightmorph	1.19	<comment>(Verify the kernel was symlinked)</comment>
152			# <i>eselect kernel list</i>
153	swift	1.20	[1] linux-2.6.39-gentoo-r3 *
154			[2] linux-2.6.38-gentoo-r6
155	fox2mike	1.15	</pre>
156
157			<p>
158	neysx	1.8	If you really want to do it yourself, the following example shows you how to
159	swift	1.20	make the link point to <path>linux-2.6.39-gentoo-r3</path>:
160	neysx	1.8	</p>
161
162			<pre caption="Updating the /usr/src/linux softlink manually">
163	swift	1.1	# <i>cd /usr/src</i>
164	swift	1.20	# <i>ln -sfn linux-2.6.39-gentoo-r3 linux</i>
165	swift	1.1	</pre>
166
167			</body>
168			</section>
169			</chapter>
170
171			<chapter id="install">
172			<title>Configuring, compiling and installing the new kernel</title>
173			<section>
174			<body>
175
176			<p>
177			For either of these options, you should refer to the instructions given in the
178	neysx	1.16	<uri link="/doc/en/handbook/">Gentoo Handbook</uri> relating to <e>Configuring
179			the Kernel</e> and <e>Configuring the Bootloader</e>. Below is an outline of
180			the required actions:
181	swift	1.1	</p>
182
183			</body>
184			</section>
185			<section>
186			<title>Option 1: Automatic kernel setup with Genkernel</title>
187			<body>
188
189			<p>
190			If you are a genkernel user, you just need to repeat the stages you went
191			through when installing your kernel for the first time.
192			</p>
193
194			<p>
195			Simply run genkernel in the normal way:
196			</p>
197
198			<pre caption="Invoking genkernel">
199			# <i>genkernel all</i>
200			</pre>
201
202			<p>
203			You can also use extra parameters for other genkernel functionality. For
204			example, if you wish to configure some extra kernel options using
205	neysx	1.16	<c>menuconfig</c> and you wish genkernel to automatically update your grub boot
206			loader configuration, then invoke genkernel as follows:
207	swift	1.1	</p>
208
209			<pre caption="Invoking genkernel with some common arguments">
210			# <i>genkernel --menuconfig --bootloader=grub all</i>
211			</pre>
212
213			<p>
214	neysx	1.16	For more info, follow the <uri link="/doc/en/genkernel.xml">Gentoo Linux
215			Genkernel Guide</uri>, or refer to the <uri link="/doc/en/handbook/">Gentoo
216	swift	1.4	Handbook</uri>. Many of the options can be set in the configuration file for
217	swift	1.23	<c>genkernel</c>, <path>/etc/genkernel.conf</path>. Also take a look at the <uri
218			link="/doc/en/initramfs-guide.xml">Gentoo Linux Initial RAM file system
219			guide</uri>.
220	swift	1.1	</p>
221
222			</body>
223			</section>
224			<section>
225			<title>Option 2: Manual configuration</title>
226			<body>
227
228			<p>
229			To begin, open the <c>menuconfig</c> utility in the kernel source tree:
230			</p>
231
232			<pre caption="Invoking menuconfig">
233			# <i>cd /usr/src/linux</i>
234			# <i>make menuconfig</i>
235			</pre>
236
237			<p>
238	swift	1.4	Select the options required for your hardware and operating environment. For
239			additional information on kernel configuration, refer to the chapter entitled
240			<e>Configuring the Kernel</e> of the <uri
241			link="/doc/en/handbook/index.xml">Gentoo Handbook</uri>.
242	swift	1.1	</p>
243
244			<p>
245			Next, compile your kernel and copy it over to your boot partition. Again,
246	swift	1.4	follow the <uri link="/doc/en/handbook/index.xml">Gentoo Handbook</uri>
247			instructions outlined in the chapter on <e>Configuring the Bootloader</e>. If
248			<path>/boot</path> is a separate partition, ensure it is mounted before copying
249			the compiled kernel to this directory! Failing to do so would keep you from
250			booting the system with your new kernel.
251	swift	1.1	</p>
252
253			<pre caption="Compiling and installing the new kernel">
254			# <i>make && make modules_install</i>
255			# <i>mount /boot</i>
256	swift	1.20	# <i>cp arch/i386/boot/bzImage /boot/bzImage-2.6.39-gentoo-r3</i>
257	swift	1.1	</pre>
258
259			<p>
260	swift	1.18	Finally, you should update your boot loader configuration, adding an entry for
261	swift	1.5	the new kernel (don't delete the old one just yet!) and unmount the
262	swift	1.18	<path>/boot</path> partition. Again, refer to the
263	swift	1.4	<uri link="/doc/en/handbook/index.xml">Gentoo Handbook</uri>
264			for detailed instructions on this procedure.
265	swift	1.1	</p>
266
267			</body>
268			</section>
269			</chapter>
270
271			<chapter>
272			<title>Reinstalling external modules</title>
273			<section>
274			<body>
275
276			<p>
277			If you use any kernel modules that are not included in the kernel source tree
278	neysx	1.13	but are provided elsewhere in Portage (e.g. ALSA drivers and NVIDIA or ATI
279			graphics drivers), then you must reinstall these after upgrading the kernel.
280			This is as simple as re-merging the packages involved. For more information,
281			refer to the chapter on <e>Configuring the Kernel</e> in the <uri
282	nightmorph	1.14	link="/doc/en/handbook/">Gentoo Handbook</uri>.
283	swift	1.1	</p>
284
285	swift	1.11	<p>
286	nightmorph	1.24	We provide you with a built-in Portage set (<c>@module-rebuild</c>) which
287			rebuilds all the kernel modules you have installed using separate ebuilds (such
288			as <c>app-laptop/tp_smapi</c>) for the kernel at <path>/usr/src/linux</path>.
289			Once you have finished upgrading or recompiling your kernel, run <c>emerge
290			@module-rebuild</c> to rebuild the drivers for your new kernel.
291	swift	1.11	</p>
292
293	swift	1.1	</body>
294			</section>
295			</chapter>
296
297			<chapter>
298	swift	1.20	<title>Updating your module configuration</title>
299			<section>
300			<body>
301
302			<p>
303			If you have put specific module configuration entries in
304			<path>/etc/conf.d/modules</path>, then you might need to update the entries
305			accordingly.
306			</p>
307
308			<pre caption="Sample /etc/conf.d/modules file">
309			<comment># The following will only auto-load the ieee1394 module in 2.6.38-gentoo-r6 kernels</comment>
310			modules_2_6_38_gentoo_r6="ieee1394"
311
312			<comment># To support auto-loading on all possible versions, drop any reference to versions:</comment>
313			modules="ohci1394"
314			</pre>
315
316			</body>
317			</section>
318			</chapter>
319
320			<chapter>
321	swift	1.1	<title>Rebooting into the new kernel</title>
322			<section>
323			<body>
324
325			<p>
326			Next, close all applications and reboot your system. If you followed the above
327	swift	1.5	instructions correctly, the boot loader menu should include an entry for the
328	swift	1.4	new kernel. Select the new kernel and let the system boot.
329	swift	1.1	</p>
330
331			<p>
332	swift	1.4	Hopefully, your system successfully boots with the new kernel, and you can log
333			in to resume whatever you were doing. If this is the case, then the upgrade is
334			complete.
335	swift	1.1	</p>
336	neysx	1.13
337	swift	1.1	<p>
338	swift	1.18	If you made a mistake and the system fails to boot with the new kernel, reboot
339			the system and select the entry from the boot loader that corresponds to the
340	swift	1.4	last known working kernel. You can then restart from the <uri link="#install">
341	swift	1.18	Configuring, compiling, and installing the new kernel</uri> stage -- making
342			the appropriate changes to correct your mistake. In some cases, you might not
343			even need to reboot to do this (e.g. you missed a driver for an audio device,
344	swift	1.5	Ethernet adapter, etc.)
345	swift	1.1	</p>
346
347			</body>
348			</section>
349			</chapter>
350
351			<chapter>
352			<title>Running multiple kernels</title>
353			<section>
354			<body>
355
356			<p>
357			You may have noticed, that when installing the sources for your newer kernel,
358	swift	1.4	the sources for your existing kernel were not removed. This is by design -- it
359	swift	1.1	allows you to easily switch between running different kernels.
360			</p>
361
362			<p>
363			Switching between multiple kernels is as simple as leaving the kernel sources
364	swift	1.18	under <path>/usr/src/</path> and leaving the <path>bzImage</path> binaries on
365			your <path>/boot</path> partition (referenced by entries in your boot loader
366			configuration). Every time you boot up, you will be presented with a choice of
367	swift	1.5	which kernel to boot into.
368	swift	1.1	</p>
369
370			</body>
371			</section>
372			</chapter>
373
374			<chapter>
375			<title>Removing older kernels</title>
376			<section>
377			<body>
378
379			<p>
380			Continuing on from the last section, you may be happy with your new kernel and
381			not have any need to keep older kernel versions around. To easily remove all
382			sources for a particular kernel except for the newest one, you can take
383	swift	1.4	advantage of the <e>prune</e> option available through <c>emerge</c>. Continuing
384			the example using <c>gentoo-sources</c>:
385	swift	1.1	</p>
386
387			<pre caption="Pruning old versions">
388	neysx	1.3	# <i>emerge -P gentoo-sources</i>
389	swift	1.1	</pre>
390
391			<p>
392			In most cases, temporary files used during compilation will still remain under
393	swift	1.18	the appropriate source directory under <path>/usr/src</path>. It is safe to
394	swift	1.1	remove these using <c>rm</c>.
395			</p>
396
397			<p>
398			You can also safely delete any modules that were used by this kernel. This can
399			be done by removing the appropriate directories under <path>/lib/modules/</path>
400			that relate to the kernel versions you are removing. Be careful not to delete
401			modules belonging to kernels that you still use!
402			</p>
403
404			<p>
405	swift	1.18	Finally, you can mount your <path>/boot</path> partition and remove the
406	jkt	1.10	<path>bzImage</path> file(s) for the kernel(s) you are pruning. You should also
407			edit your boot loader configuration so that it no longer references such
408			kernel(s).
409	swift	1.1	</p>
410
411			</body>
412			</section>
413			</chapter>
414
415			<chapter>
416	neysx	1.3	<title>Advanced: Using your old kernel .config to configure a new one</title>
417			<section>
418			<body>
419
420			<p>
421			It is sometimes possible to save time by re-using the configuration file from
422			your old kernel when configuring the new one. Note that this is generally
423	swift	1.4	unsafe -- too many changes between every kernel release for this to be a
424	neysx	1.3	reliable upgrade path.
425			</p>
426
427			<p>
428			The only situation where this is appropriate is when upgrading from one Gentoo
429			kernel revision to another. For example, the changes made between
430			<c>gentoo-sources-2.6.9-r1</c> and <c>gentoo-sources-2.6.9-r2</c> will be very
431			small, so it is usually OK to use the following method. However, it is not
432			appropriate to use it in the example used throughout this document: upgrading
433			from 2.6.8 to 2.6.9. Too many changes between the official releases, and the
434			method described below does not display enough context to the user, often
435			resulting in the user running into problems because they disabled options that
436			they really didn't want to.
437			</p>
438
439			<p>
440	neysx	1.16	To reuse your old <path>.config</path>, you simply need to copy it over and
441			then run <c>make oldconfig</c>. In the following example, we take the
442			configuration from <c>gentoo-sources-2.6.9-r1</c> and import it into
443	neysx	1.3	<c>gentoo-sources-2.6.9-r2</c>.
444			</p>
445
446			<pre caption="Reusing your old config">
447			# <i>cd /usr/src/linux-2.6.9-gentoo-r2</i>
448			# <i>cp ../linux-2.6.9-gentoo-r1/.config .</i>
449			# <i>make oldconfig</i>
450			</pre>
451
452	neysx	1.16	<pre caption="Reusing your old config with genkernel">
453			# <i>cd /etc/kernels</i>
454			# <i>cp kernel-config-x86-2.6.9-gentoo-r1 kernel-config-x86-2.6.9-gentoo-r2</i>
455			# <i>genkernel all</i>
456			</pre>
457
458	neysx	1.3	<p>
459			At this point, you may be asked to produce answers for configuration options
460			which have changed between the two versions. Once you have done that, you can
461			compile and install your kernel as normal, without having to go through the
462			<c>menuconfig</c> configuration process.
463			</p>
464
465	nightmorph	1.17	<p>
466			A much safer upgrading method is to copy your config as previously shown, and
467			then simply run <c>make menuconfig</c>. This avoids the problems of <c>make
468			oldconfig</c> mentioned previously, as <c>make menuconfig</c> will load up your
469			previous configuration as much as possible into the menu. Now all you have to
470			do is go through each option and look for new sections, removals, and so on. By
471			using <c>menuconfig</c>, you gain context for all the new changes, and can
472			easily view the new choices and review help screens much easier. You can even
473			use this for upgrades such as 2.6.8 to 2.6.9; just make sure you read through
474			the options carefully. Once you've finished, compile and install your kernel as
475			normal.
476			</p>
477
478	neysx	1.3	</body>
479			</section>
480			</chapter>
481
482			<chapter>
483	swift	1.1	<title>Problems after a kernel upgrade?</title>
484			<section>
485			<body>
486
487			<p>
488			With the rapid development of the Linux kernel, it is inevitable that some
489	neysx	1.3	changes made from one kernel release to another may cause some problems. If you
490			have any issues with the latest versions of <uri
491			link="/doc/en/gentoo-kernel.xml#doc_chap2"> Gentoo-supported kernels</uri> then
492			please do report the issues to us.
493	swift	1.1	</p>
494
495			</body>
496			</section>
497			</chapter>
498
499			</guide>