The migration processes described in this document are not minor changes. This document is in early stages and may be missing some details but hopefully the main things have been covered. If you do try a migration, please report any problem you might encounter so that we can refine this guide.

We are planning on making Linux 2.6 the default kernel for when 2005.0 is released (for some arch's). At the same time, we will encourage all existing users of those arch's to upgrade to Linux 2.6, as many will still be running 2.4. Your feedback on this document is much appreciated, so that when this time comes, the document can be in good shape for the mass-migration.

That is no easy question to answer. Linux 2.6 is the result of over 2 years of rapid development and stabilisation of new features, and is architectually quite different from its 2.4 counterpart. Some of the more major changes are listed below:

• Scheduler/Interactivity improvements: Linux feels very smooth on desktop systems and copes much better than 2.4 while under load
• Scalability: Linux now scales much better at both ends - on small embedded devices and also systems with many processors
• Performance: Throughput from common applications is much improved
• Hardware support: Linux now supports many more architectures and hardware devices out-of-the-box than any other operating system.

Joseph Pranevich has written a very detailed document, The Wonderful World Of Linux 2.6 which you may be interested to glance over. If you are interested in the more technical details, you can refer to The post-halloween document - but bear in mind that this is somewhat outdated now.

In the past, Gentoo has instructed users to use devfs for managing the /dev directory, which contains a series of device interfaces to allow system applications to communicate with hardware (through the kernel).

devfs, whilst a good concept, has some internal problems, and has been marked obselete in Linux 2.6.

udev is the new way of managing device nodes. It addresses issues with previous device managers, and also attempts to solve some other problems.

The above may not mean much to you, but fear not, the hard working Gentoo developers have put effort into making the migration from devfs very easy.

With Linux 2.4, chances are that you used OSS (open sound system) drivers to power your sound card. OSS has been replaced by a newer and better set of sound drivers: ALSA.

ALSA, the Advanced Linux Sound Architecture, is a new set of sound drivers with a new and improved API, present in the Linux 2.6 kernel. It is backwards compatible with OSS applications, provided that you select the right kernel configuration options!

Some of the changes brought in with Linux 2.6 also required some changes in the base system applications. Before continuing, you should ensure that your system is relatively up-to-date, and to be perfectly sure, you should update all world and system packages where updates are available.

In particular, make sure you have the latest stable versions of the following packages:

• sys-apps/baselayout
• sys-apps/util-linux
• sys-kernel/genkernel (only if you wish to use genkernel as opposed to manual configuration)

# emerge sync
# emerge -ua world

sys-apps/modutils is the package that provides tools such as modprobe, rmmod and insmod for Linux 2.4.

Linux 2.6 introduces a new module format, and therefore requires new tools for handling modules. These are bundled up into the sys-apps/module-init-tools package.

You should now remove modutils and install module-init-tools:

# emerge unmerge sys-apps/modutils
# emerge module-init-tools

There is no configuration involved here. Simply use emerge to install udev:

# emerge -a udev

When the system boots up, the system requires some essential device nodes. As udev is not included in the kernel, it is not activated immediately. To work around this, you must ensure that you have some essential device nodes on your disk.

Our installation stage files will have created the required devices during the initial installation. However, some users have reported that this is not the case. We will use this opportunity to check that the device files exist, and create them if they do not.

As your existing device manager will be mounted at /dev, we cannot access it directly. So we will bind-mount your root partition to another location and access the /dev directory from there.

# mkdir -p /mnt/temp
# mount -o bind / /mnt/temp
# cd /mnt/temp/dev
# ls -l console null

If the above ls command reported that either console or null do not exist, then you must create them yourself, as shown below.

# mknod -m 660 console c 5 1
# mknod -m 660 null c 1 3

You should now unmount your bind-mounted root partition, even if you did not have to create those devices:

# umount /mnt/temp
# rmdir /mnt/temp

ALSA requires you to have some packages installed, so that applications can use the ALSA API. These packages will also allow you to control the mixer and volume levels. Install the required utilities as follows:

# emerge -a alsa-lib alsa-utils alsa-tools alsa-headers alsa-oss

The first thing you need to do is install sources of a 2.6 kernel of your choice. The two Gentoo-supported 2.6 kernels are currently gentoo-dev-sources (for desktops) and hardened-dev-sources (for servers). There are others available, see the Gentoo Linux Kernel Guide for more choices.

In this guide, we'll use gentoo-dev-sources as an example. Install your chosen set of kernel sources using the emerge utility:

# emerge -a gentoo-dev-sources
These are the packages that I would merge, in order:
Calculating dependencies ...done!
[ebuild  N    ] sys-kernel/gentoo-dev-sources-2.6.9-r2

Do you want me to merge these packages? [Yes/No] y

Various components of the Gentoo utilities rely on /usr/src/linux being a symbolic link to the kernel sources that you are running (or wish to compile against).

We will now update our /usr/src/linux link to point at the kernel sources we just installed. Continuing our example:

# cd /usr/src
# ln -sfn linux-2.6.9-gentoo-r2 linux

Before we get stuck into configuring the kernel, I'll attempt to detail the most common errors that people make when migrating to Linux 2.6, as some of these points will influence the way you configure the new kernel.

You'll be asked many many questions, since there have been a large amount of changes. Many people who do try a make oldconfig from a 2.4 config end up creating an unworkable kernel (e.g. no output on-screen, no input from keyboard, etc). Please save yourself the trouble, and use the traditional menuconfig configuration method just this once.

In Linux 2.4, the only way to achieve good CD/DVD writing results was to enable the (rather ugly) ide-scsi emulation. Thankfully, the IDE layer in Linux 2.6 has been extended to support CD/DVD writers much better.

You don't need to enable any extra options to support CD writing. Just be sure not to enable ide-scsi as you used to.

You won't get your normal console beeps (or any response from the PC speaker at all) unless you specifically enable the new PC speaker option (CONFIG_INPUT_PCSPKR):

Device Drivers  --->
 Input device support  --->
  [*] Misc
   <*>   PC Speaker support

Very recently, a new USB storage device driver has been added to the kernel. At the time of writing, this driver ("ub") is still in its early stages and some users find it to be unreliable. If you have problems accessing your USB hard disk, USB flash disk, USB card reader, or USB digital camera, then you could try reverting to the older SCSI-style driver:

Device Drivers  --->
 Block devices  --->
  < > Low Performance USB Block driver

If you have edited your /etc/fstab file to customise the way that the USB device filesystem gets mounted, you may have to modify the filesystem type from usbdevfs to usbfs.

If you are a desktop 2.4 user, you may have hacked your system into running X at a higher priority, as in some cases it seems to provide better desktop performance.

There have been many scheduler changes in 2.6 which change this behaviour. If you continue to run X at a higher priority, it will do exactly what it is supposed to (run the display server at a very high priority) and you will notice consequences such as sound stuttering and slow application load times because your CPU is spending too long serving X and only X.

In Linux 2.6, you no longer need to renice desktop applications to get good interactivity. Please remove your "niceness" hacks!

One of the changes that a default udev configuration introduces is different organisation of the mouse device nodes. Previously, you would have had nodes such as /dev/psaux and /dev/mouse. You will now have nodes such as /dev/input/mouse0, /dev/input/mouse1, and a collective /dev/input/mice node which combines movements from all mice.

Since the old X configurations typically reference /dev/mouse or /dev/psaux then you may get an error similar to the one shown below when you attempt to start X11:

(EE) xf86OpenSerial: Cannot open device /dev/mouse
	No such file or directory.
(EE) Mouse0: cannot open input device
(EE) PreInit failed for input device "Mouse0"
No core pointer

To correct this, open your X11 config in a text editor, and update the mouse InputDevice section to use the /dev/input/mice device. An example is shown below:

# nano -w /etc/X11/xorg.conf

Section "InputDevice"
	Identifier  "Mouse0"
	Driver      "mouse"
	Option      "Protocol" "auto"
	Option      "Device" "/dev/input/mice"
EndSection

As with Linux 2.4, you have two options for managing your new kernel build.

1. The default method is to configure your kernel manually. This may seem daunting but is the preferred way as long as you know your system. If you wish to configure your new kernel manually, please continue on to the next chapter.
2. The alternative option is to use our genkernel utility to automatically configure, compile, and install a kernel for you. If you wish to use genkernel then skip over the next chapter and proceed with using genkernel.

We'll now get on with configuring the kernel. Open menuconfig in the usual way:

# cd /usr/src/linux
# make menuconfig

You will probably be familiar with using menuconfig from configuring 2.4 kernels. Fortunately, the front end has barely changed at all, but you will observe much better organisation of kernel options, plus many new options that weren't present in 2.4.

Be sure to enable the following important kernel options:

File systems --->
  Pseudo Filesystems --->
    [*] /proc file system support
    [*] Virtual memory file system support (former shm fs)
    
(the following are required for udev):
General setup  --->
 [*] Support for hot-pluggable devices

Device Drivers  --->
 Block devices  --->
  <*> RAM disk support
  
(the following are required for ALSA):
Device Drivers  --->
 Sound  --->
  <*> Sound card support
  Advanced Linux Sound Architecture  --->
   <M> Advanced Linux Sound Architecture
   <M> Sequencer support
   <M> OSS Mixer API
   [*] OSS Sequencer API
   (and dont forget to select your soundcard from the submenus!)

Also, remember to enable support for the filesystems that you use, and the hardware present in your system. Be sure to enable support for the IDE controller on your motherboard if you wish to benefit from fast DMA disk access. Refer to the Configuring the Kernel section of the Gentoo Handbook for additional guidance here.

Now that we have configured the kernel, we can start the compilation process:

# make && make modules_install

Wait for the kernel compilation to complete (and observe the much more readable compilation output).

The next step is mounting your /boot partition and copying the kernel image over. You must then update your bootloader config manually.

# mount /boot
# cp arch/i386/boot/bzImage /boot/bzImage-2.6.9-gentoo-r2
# cp System.map /boot/System.map-2.6.9-gentoo-r2

Note that the above instructions are examples only, you should follow your usual procedure of updating kernels by following the instructions in the Gentoo Handbook (see the Configuring the Kernel chapter).

When updating your bootloader config, do not remove the old entry pointing at your 2.4 kernel. This way, you will easily be able to switch between the two if something is not working.

Now continue onto the Module Configuration section.

If you prefer to use genkernel instead of manually configuring your kernel, you will be happy to hear that using genkernel to produce 2.6 kernels is very similar to the process you performed when producing your previous 2.4 kernel.

You should invoke genkernel as shown below:

# genkernel --udev --menuconfig --bootloader=grub all

In the above example, we also take advantage of genkernel features to open menuconfig to allow you to customise the kernel configuration (if you wish), and to update the grub bootloader configuration after compilation.

You should choose genkernel arguments that suit you, but do not forget to include the --udev argument! Refer to the Gentoo Linux Genkernel Guide and the Configuring the Kernel chapter of the Gentoo Handbook for additional information.

Many users will additionally rely on kernel modules that are built outside of the kernel tree. Common examples are the binary ATI and Nvidia graphics drivers. You now need to install those modules, which will compile against the 2.6 sources found at /usr/src/linux. This is the usual case of emerge packagename for all the external modules you are used to using with 2.4.

Refer again to the Configuring the Kernel chapter of the Gentoo Handbook for more info.

You may have decided to compile some kernel components as modules (as opposed to compiled directly into the kernel) and would like to have them autoloaded on bootup like you did with 2.4. Also, if you installed any external modules from the portage tree (as described above) you will probably want to autoload them too.

You can achieve this similarly as to how you did with 2.4. Simply open up the file /etc/modules.autoload.d/kernel-2.6 in a text editor and list the names of the modules you would like autoloaded.

# nano -w /etc/modules.autoload.d/kernel-2.6

# /etc/modules.autoload.d/kernel-2.6:  kernel modules to load when system boots.
#
# Note that this file is for 2.6 kernels.
#
# Add the names of modules that you'd like to load when the system
# starts into this file, one per line.  Comments begin with # and
# are ignored.  Read man modules.autoload for additional details.

3c59x
nvidia

You will have noticed that we chose to compile ALSA as modules. We can now configure ALSA's behaviour easily. However, we also need to configure which modules are to be loaded. Open up /etc/modules.d/alsa in your text editor:

# nano -w /etc/modules.d/alsa

Now look for the section marked as IMPORTANT. In most cases, you just need to uncomment and modify the snd-card-0 and snd-slot-0 aliases.

## IMPORTANT:
## You need to customise this section for your specific sound card(s)
## and then run `update-modules' command.
## Read alsa-driver's INSTALL file in /usr/share/doc for more info.
##
##  ALSA portion

#   My laptop uses the snd-maestro3 driver
alias snd-card-0 snd-maestro3

##  OSS/Free portion

# Generally all you need to do is uncomment this line:
alias sound-slot-0 snd-card-0

For more info on which driver name to use, consult the Gentoo Linux ALSA Guide. Remember to prefix it with snd- in this file.

Finally, set the alsasound init script to be executed on bootup:

# rc-update add alsasound boot

It's now time to boot into Linux 2.6. Close all applications and reboot:

# modules-update
# umount /boot
# reboot

When you reboot, if you followed this document correctly so far, you will have the option of either loading Linux 2.4 or Linux 2.6 from your bootloader. Choose Linux 2.6.

Once the system has booted, check that things are working. If you made a mistake in the kernel configuration, don't worry, you can skip back to the Configuring, building, and installing the kernel section, make your change, recompile and install new kernel image, reboot, and try again!

By default, ALSA channels are muted, so you won't hear anything when you go to play a sound. You need to unmute them now. Run the alsamixer program from a console and use the arrow keys to move around and adjust volumes, and the M key to mute and unmute. Read the Gentoo Linux ALSA Guide for more complete documentation and other ways to do this.

By now you are running Linux 2.6 and hopefully have all issues ironed out. You should now update your Linux kernel header files and re-merge glibc so that userspace applications can take advantage of new Linux 2.6 features.

# emerge unmerge linux-headers
# emerge linux26-headers

After updating your headers package, you should generally re-merge glibc. There is a new feature here that you may be interested in - NPTL. NPTL is a new threading model present in Linux 2.6, which features much quicker thread create and destroy times. This won't make much of a difference to most systems, but you may wish to enable it during this migration process! To enable NPTL, edit /etc/make.conf, adding nptl to your USE variable.

Now re-merge glibc (you should do this even if you did not choose to enable NPTL).

# emerge -a glibc

If you enabled NPTL, existing binaries will not use it until they are recompiled. However, any binaries compiled from this point onwards will use NPTL. You may wish to recompile all binaries now, e.g.:

# emerge -e world

Alternatively, you can just let your system "naturally" convert itself to NPTL as you update to newer versions of packages when they are released.

With the incredible amount of work that went into Linux 2.6, it is sometimes inevitable that things which used to work fine, no longer function as expected.

If you have any problems with your 2.6 kernel, and you can confirm that this problem does not exist with Linux 2.4, then please open a bug with us on our Bugzilla. We will investigate the issue, and if we find that it is a problem in the mainline kernel, we may then ask you to file a report at the central kernel bugzilla.

Hopefully you have just completed a smooth migration and you are enjoying the benefits which Linux 2.6 brings over 2.4. As I mentioned at the start, we are looking for feedback on this document - even if your migration went perfectly smoothly. Please mail me your feedback so that we can get this document in perfect shape for when 2005.0 comes around. Thanks!