KC11 - kernel compiling for the beginner

[wynn]

Navigation: [Kernel Compilation] [Table of Contents]

Changes:
6-12 Jun 2003 [topic=58787]Original FAQ[/topic] by [profile=12769]wilburpan[/profile]
10-21 Feb 2007 Updated and new material added
26 Feb 2007 Added kernel configuration slideshow to Resources (thanks d2_racing)
11 Mar 2007 Reduced repetitions by moving sections to "Hints & Tips" and replacing by references (thanks jmbsvicetto), normalized titles, proofread
30 Mar 2007 Incorporated suggestions and corrections from EarthWings, many thanks

KC11: Kernel compiling for the beginner

Table of contents

1. General principles to keep in mind
2. Preparing to compile a kernel
   1. During an installation
      • Mounting the partitions and chroot
   2. From a Gentoo installation
   3. Configuring the kernel
      • Using menuconfig with genkernel
      • Using menuconfig
      • Creating a kernel configuration from scratch
      • Slimming down a genkernel default configuration
      • Configuring the kernel to support a new item of hardware
3. Compiling and installing the kernel
   1. Compiling
   2. Installing
   3. Updating grub.conf
4. Recovering from a new kernel which doesn't boot
   1. Booting from a saved version of the kernel
   2. Booting from a previous version of the kernel
5. Collected Hints and Tips
   1. Enabling an IDE driver in the kernel
   2. Enabling a SATA driver in the kernel
   3. Enabling the driver for a wired network in the kernel
   4. Framebuffer support
   5. Find the modules (drivers) in use
   6. Finding a module (driver) from the output of lspci
6. Resources

Note: the terms "built in" and "module" in connection with hardware drivers will appear frequently in the following

• A built in driver is one which has been selected in the kernel configuration by typing "y" and will appear as "<*>" or in brackets.
• A driver which is a module is selected by typing "m" and will appear as "<M>".
• A built in driver is part of the kernel image and will be available immediately the kernel is running.
• A driver which is a module is separate from the kernel image and is stored in a directory under /lib/modules: it will not be available until the root filesystem is mounted.

Note: the book by Greg Kroah-Hartman "Linux Kernel in a Nutshell" (see Resources) will be referenced, quoted and paraphrased frequently in this section. It will be referred to as "gkh-lkn".

1) General principles to keep in mind

1. It is much more important to have a working kernel than an optimized kernel at first. You can always try to optimize and recompile later. (see Keeping Backup Kernels though).
2. Keep it simple to start with; the essentials to get the kernel and Gentoo going are: a system that has built in support for the hard drive (SATA or IDE) your root filesystem is on, built in support for your root filesystem, support for other hard drives or optical drives (again IDE or SATA) as modules, support for the filesystems on any other hard drive partitions as modules, support for your network card either built in or as a module.
3. As it may be difficult in the beginning to decide which hard drive support and which filesystem support is required to be built in, you can make them all built in.
4. When (at last) you have a booting kernel, make sure it is never overwritten by later kernels by giving each kernel - even recompilations of the same kernel - a different name. Both LILO and GRUB have ways of making a simple menu so that you can have multiple kernels and pick which of your kernels you want to boot. For instance

   Code: Select all

   ls /boot
   /boot/kernel-2.6.17-gentoo-r7.old
   /boot/kernel-2.6.17-gentoo-r7
   /boot/kernel-2.6.18-gentoo-r3
   /boot/kernel-2.6.19-gentoo-r5
   /boot/kernel-2.6.19-gentoo-r5-100hz
   /boot/kernel-2.6.19-gentoo-r5-100hz-dl
   /boot/kernel-2.6.19-gentoo-r5-100hz-dl-idedma_auto
   /boot/kernel-2.6.20-gentoo

   There is an old (but working) 2.6.17 kernel, 2.6.18 and 4 variations on 2.6.19 which used different configuration options. Note that none of the kernels have the generic "bzImage" name. It is a very good idea to have a quick and easy way of seeing which version of the kernel each file was compiled from.
5. Keeping Backup Kernels: when you recompile your first working kernel, if it is the same kernel version, before copying the new kernel to /boot, you should rename the old, working, image by adding ".old" to its name (and, if you are using genkernel, to the initramfs file name as well). If your new kernel won't boot, this will allow you to boot your old working one instead. When you compile a new version of the kernel, you can leave the old, working, version as your backup - and you will have an entry in your GRUB menu to boot it.

2) Preparing to compile a kernel

Important Warning: The kernel developers advise against uncompressing the kernel source code, configuring or building the kernel as root. It should be done as an ordinary user. Only the one or two commands needed to install the kernel and the modules should be run as root. There have been bugs in the build process in the past which have caused files in /dev to be deleted when run as root and uncompressing the kernel archive as root can lead to some files getting the wrong permissions. gkh-lkn: "None of the primary kernel developers build kernels as root"

This FAQ will consider two possible scenarios for a first or the first series of kernel compilations: using genkernel with the "--menuconfig" argument or running "make menuconfig" from the top of the kernel source tree.

Using just "genkernel all" may give you a kernel which boots but, later on, you may want to remove the modules you don't need and, at that point, this is the FAQ for you.

There are two possible settings for a kernel compilation, during installation while chroot'ed to your root filesystem and within a running Gentoo installation.

There are instructions on chroot'ing in the Handbook and the QuickInstall Guide but it seems worthwhile giving a potted version here to make it less likely that something isn't forgotten in going backwards and forwards.

During an Installation

Mounting the partitions and chroot

As in the Handbook and QuickInstall Guide, the following disk layout is used for this example: you will have to replace sda by hda if your root filesystem is on an IDE drive rather than a SATA one. If you don't have a /boot partition you should leave out the commands to mount and unmount it

Code: Select all

livecd ~ # mount /dev/sda3 /mnt/gentoo
livecd ~ # mount /dev/sda1 /mnt/gentoo/boot
livecd ~ # cd /
livecd / # mount -t proc proc /mnt/gentoo/proc
livecd / # chroot /mnt/gentoo /bin/bash
livecd / # env-update && source /etc/profile

Now follow the instructions below to configure your kernel

When you have configured it, compiled it, installed the modules, copied the kernel image to /boot (or had genkernel do it for you) and added a new section to GRUB for it unless it is replacing an existing version (make the old version a backup copy if you need to), you can exit from the chroot, unmount the partitions and reboot

Code: Select all

livecd / # exit
livecd / # umount /mnt/gentoo/proc /mnt/gentoo/boot /mnt/gentoo
livecd / # reboot

(Don't forget to remove the CD)

From a Gentoo Installation

If you already have a kernel which boots and you wish to reconfigure it or compile a new kernel, you just need to run menuconfig or run genkernel with the argument "--menuconfig": see "Configuring the Kernel".

Configuring the Kernel

There are many different ways to configure a kernel, menuconfig is widely used and people you ask for help are more likely to be familiar with it.

It will be used in this FAQ.

Using menuconfig with genkernel

To modify a kernel configuration (the .config file) while running genkernel, enter

Code: Select all

genkernel --menuconfig --no-mrproper --no-clean all

You may want to add "--no-bootsplash" and "--no-gensplash" to the arguments as they may interfere with booting. When you have a working kernel, you may like to try one or the other.

With the "--menuconfig" argument, genkernel will pause to allow you to change the starting configuration - "--no-mrproper" prevents genkernel from removing it.

"--no-clean" stops genkernel from trying to clean the kernel source tree which, as it hasn't been used yet, is already clean.

The default configuration file for genkernel itself, /etc/genkernel.conf, will set it up to save the final .config file to /etc/kernels. If you are compiling linux-2.6.19-gentoo-r5 for example, the .config will be saved as /etc/kernels/kernel-config-x86-2.6.19-gentoo-r5 - of course, the "x86" will be replaced by your arch: x86_64, ppc, sparc and so on.

Using menuconfig

You can also run menuconfig on its own, compiling and installing the resulting kernel by hand. To do this, navigate to the kernel source directory ("cd /usr/src/linux") and enter

Code: Select all

make menuconfig

The screen you see is split into three parts, the upper part tells you how to navigate around the menus and make selections and the middle shows the first part of the initial menu list and at the bottom of the screen you have

Code: Select all

 <Select>    < Exit >    < Help >

The navigation instructions are

Code: Select all

 Arrow keys navigate the menu.  <Enter> selects submenus --->.
 Highlighted letters are hotkeys.  Pressing <Y> includes, <N> excludes,
 <M> modularizes features.  Press <Esc><Esc> to exit, <?> for Help, </>
 for Search.  Legend: [*] built-in  [ ] excluded  <M> module  < >

The left and right arrow keys move the Select highlight around the Select/Exit/Help group ar the bottom of the screen - it wraps around so pressing left arrow while on Help will move the highlight to Select.

The up and down arrows move the menu highlight from item to item: if "v(+)" is showing on the left of the bottom line, there is more to come and you can use PageDown to see it. Use PageUp to go back up the screen.

Another useful feature, though you may not need it just yet, is "/" for Search: to find out where a particular configuration option is you can press "/" and type in all or part of the name.

See gkh-lkn Chapter 4 "Console Configuration Method" for more details.

Creating a kernel configuration from scratch

First check that the symbolic link "/usr/src/linux" is pointing to the right place

Code: Select all

readlink /usr/src/linux
linux-2.6.19-gentoo-r5

If it isn't then, to correct it, run

Code: Select all

cd /usr/src
rm linux; ln -s linux-2.6.19-gentoo-r5 linux

and

Code: Select all

cd /usr/src/linux

to get to the top of the kernel tree.

To get a good starting configuration, run

Code: Select all

make defconfig

This will create a basic .config file in your kernel source tree which you can then modify to suit your hardware - [gkh-lkn "Every kernel version comes with a "default" kernel configuration. This configuration is loosely based on the defaults that the kernel maintainer of that architecture feels are the best options to be used. In some cases, it is merely the configuration that is used by the kernel maintainer himself for his personal machines. This is true for the i386 architecture, where the default kernel configuration matches closely what Linus Torvalds uses for his main development machine."]

The full initial menu is

Code: Select all

Code maturity level options  --->
General setup  --->
Loadable module support  --->
Block layer  --->
Processor type and features  --->
Power management options (ACPI, APM)  --->
Bus options (PCI, PCMCIA, EISA, MCA, ISA)  --->
Executable file formats  --->
Networking  --->
Device Drivers  --->
File systems  --->
Instrumentation Support  --->
Kernel hacking  --->
Security options  --->
Cryptographic options  --->
Library routines  --->
---
Load an Alternate Configuration File
Save an Alternate Configuration File

There is only one entry in "Code maturity level options" which is set to allow you to choose drivers which are still in development. A number of working (for most people) drivers are marked as "development" so selecting this option gives you the choice instead of hiding them away.

To get to this option, move the menu highlight on to "Code maturity level options" with the up/down arrows and then move the select highlight at the bottom of the screen to "Select" with the left/right arrows: when you are there, press Enter and you should see

Code: Select all

 [*] Prompt for development and/or incomplete code/drivers

The "[ ]" means that it can only be selected or not and the "*" shows it has been selected. Other selections may have "< >" instead showing that they can be selected as a module (press "m" and it becomes "<M>") or selected to be built in to the kernel, press "y" and it becomes "<*>". If the option shows "[*]", "<*>" or "<M>" it can be deselected by pressing "n".

To get back to the main menu, press Esc twice in succession (Esc-Esc) or move the Select highlight to "Exit" with the left/right arrow keys and press Enter.

"General setup" is a group of miscellaneous settings and defconfig has already made sensible choices for you.

"Loadable module support" has to do with loading modules and removing them: again there is no need to change the defconfig choice.

"Block layer" has settings for block devices: hard drives, optical drives, USB mass storage &c. It also allows you to select your favourite IO scheduler (defconfig likes the "Deadline" scheduler) and decide whether you want support for Single Large Files, those over 2 terabytes. You probably don't want to change anything here.

The next section, "Processor type and features", you should at least glance at. Most of the settings will be fine as they are and if you have an Intel Pentium 4/Pentium 4 based Celeron or Pentium 4 M CPU you should not need to change anything. If you have an AMD Athlon or Duron CPU or an Intel Pentium III or other CPU you should enter this option by moving the menu highlight on to it, moving the Select highlight to "Select" and pressing Enter.

The subsection "Subarchitecture Type" will be set to "(PC-compatible)" - if you have a standard PC this is the correct setting.

Now have a look at "Processor family", this will be set to "(Pentium-4/Celeron(P4-based)/Pentium-4 M/Xeon)": if this does not match the CPU you have then select the option to change it. You will see six choices with "Pentium 4/..." at the bottom of the window - there are more

Code: Select all

( ) 386
( ) 486
( ) 586/K5/5x86/6x86/6x86MX
( ) Pentium-Classic
( ) Pentium-MMX
( ) Pentium-Pro
( ) Pentium-II/Celeron(pre-Coppermine)
( ) Pentium-III/Celeron(Coppermine)/Pentium-III Xeon
( ) Pentium M
(X) Pentium-4/Celeron(P4-based)/Pentium-4 M/Xeon
( ) K6/K6-II/K6-III
( ) Athlon/Duron/K7
( ) Opteron/Athlon64/Hammer/K8
( ) Crusoe
( ) Efficeon
( ) Winchip-C6
( ) Winchip-2
( ) Winchip-2A/Winchip-3
( ) GeodeGX1
( ) Geode GX/LX
( ) CyrixIII/VIA-C3
( ) VIA C3-2 (Nehemiah)

Move the menu highlight to the one which matches your CPU (pressing "?" as necessary to get Help) and then move the Select highlight to Select and press Enter. The text at the end of "Processor family" should have changed to match your choice. If it hasn't, try again.

If you have a 64-bit CPU then "Processor family" will be set to "(Generic-x86-64)", selecting this option to change it you will see

Code: Select all

( ) AMD-Opteron/Athlon64
( ) Intel EM64T
(X) Generic-x86-64

If you have an Intel EM64T CPU or an AMD Opteron or Athlon64, move the menu highlight to the appropriate line, move the Select highlight to Select and press Enter.

The other options in "Processor type and features" have reasonable settings, they shouldn't need changing.

[Note: The discussion of the section "Processor type and features" above assumes you have a 32-bit x86 CPU or a 64-bit x86_64 CPU: somebody who (a) thinks beginners may have a non-x86 arch and (b) has the resources to write a discussion similar to the above for it, may like to step in]

The next section "Power management options (ACPI, APM)" has reasonable settings so you may like to leave it for now. However, if you are configuring a kernel for a laptop, it would be worthwhile checking the Power Management Guide.

"Bus options (PCI, PCMCIA, EISA, MCA, ISA)" should also be OK unless you have a PCMCIA/CardBus device you need right away. If you do, navigate in to the section and then again into the "PCCARD (PCMCIA/CardBus) support --->" which shows

Code: Select all

< > PCCard (PCMCIA/CardBus) support

you can make it a module or builtin to your kernel. Pressing "m" then reveals more options

Code: Select all

<M> PCCard (PCMCIA/CardBus) support
[ ]   Enable PCCARD debugging (NEW)
<M>   16-bit PCMCIA support (NEW)
[*]     Load CIS updates from userspace (EXPERIMENTAL) (NEW)
[*]     PCMCIA control ioctl (obsolete) (NEW)
[*]   32-bit CardBus support (NEW)
---   PC-card bridges
< >   CardBus yenta-compatible bridge support (NEW)
< >   Cirrus PD6729 compatible bridge support (NEW)
< >   i82092 compatible bridge support (NEW)

headed by the original option, now selected as a module.

If the information you have on your device doesn't make the choice clear, you can look at the help for each of the last three settings (the other settings you can leave as they are). To get help for "CardBus yenta-compatible bridge support" move the menu highlight down to it and then press "?", you will see

Code: Select all

                    CardBus yenta-compatible bridge support
CONFIG_YENTA:

This option enables support for CardBus host bridges.  Virtually
all modern PCMCIA bridges are CardBus compatible.  A "bridge" is
the hardware inside your computer that PCMCIA cards are plugged
into.

To compile this driver as modules, choose M here: the
module will be called yenta_socket.

If unsure, say Y.

Symbol: YENTA [=n]
Prompt: CardBus yenta-compatible bridge support
  Defined at drivers/pcmcia/Kconfig:103
  Depends on: PCCARD && PCI

There is a percentage in the righthand corner, 69%, which means that all the help is not in the window, pressing PageDown reveals

Code: Select all

  Location:
    -> Bus options (PCI, PCMCIA, EISA, MCA, ISA)
      -> PCCARD (PCMCIA/CardBus) support
        -> PCCard (PCMCIA/CardBus) support (PCCARD [=m])
  Selects: CARDBUS && PCCARD_NONSTATIC

This is the sort of information you will want later on when you want to set a configuration option but you don't know where it is. At present, you can just take note that it is there.

The help which may be useful to you, depending on how much you can find out about your device, is in the first few lines up to the "Symbol: YENTA [=n]".

If, after viewing the help for all three options, you can't decide which one is the driver for your device, select them all as modules and let the kernel decide when you plug it in.

The next section, "Executable file formats", in the main menu (exit from where you were by Esc-Esc until you get back again) doesn't need any changes.

"Networking" can be left as it is unless you are dependent on a Wifi card for your network connection. Unfortunately, setting up a wireless card is a subject for a FAQ, or many FAQs, in itself and can't be dealt with here. There is a chapter Wireless Networking in the Handbook and many, many threads in these Forums on the various wireless cards: searching for "wireless cards" or "wireless drivers" on the Forum may well show the one that discusses your device. You may be able to find the information you need to get your card working from the thread or you could join the thread and ask.

"Device Drivers" you certainly can't pass up: this section contains all the selections you need to get your hardware working - except, usually, video cards, as the drivers for these will be in the X Window System (Xorg) or installed separately. Entering this section you will see

Code: Select all

Generic Driver Options  --->
Connector - unified userspace <-> kernelspace linker  --->
Memory Technology Devices (MTD)  --->
Parallel port support  --->
Plug and Play support  --->
Block devices  --->
Misc devices  --->
ATA/ATAPI/MFM/RLL support  --->
SCSI device support  --->
Serial ATA (prod) and Parallel ATA (experimental) drivers  --
Multi-device support (RAID and LVM)  --->
Fusion MPT device support  --->
IEEE 1394 (FireWire) support  --->
I2O device support  --->
Network device support  --->
ISDN subsystem  --->
Telephony Support  --->
Input device support  --->
Character devices  --->
I2C support  --->
SPI support  --->
Dallas's 1-wire bus  --->
Hardware Monitoring support  --->
Multimedia devices  --->
Graphics support  --->
Speakup console speech  --->
Sound  --->
USB support  --->
MMC/SD Card support  --->
LED devices  --->
Graphics support  --->
Speakup console speech  --->
Sound  --->
USB support  --->
MMC/SD Card support  --->
LED devices  --->
InfiniBand support  --->
EDAC - error detection and reporting (RAS) (EXPERIMENTAL)  --
Real Time Clock  --->
DMA Engine support  --->

The only ones you need to bother about at present are "Parallel port support", "ATA/ATAPI/MFM/RLL support", "Serial ATA (prod) and Parallel ATA (experimental) drivers" and "Network device support".

"Input device support" (only if you have an unusual keyboard, not the standard AT one), "Character devices" (with settings useful when installing Xorg) and "Graphics support" (which sets up framebuffer support), you can leave for the moment.

Parallel port support: this option is already selected; if you have a parallel port printer you need to make two more selections. On entering this option you will see

Code: Select all

<*> Parallel port support
< >   PC-style hardware (NEW)
< > AX88796 Parallel Port (NEW)
[ ] IEEE 1284 transfer modes (NEW)

You need to select "PC-style hardware" and "IEEE 1284 transfer modes" - move the menu highlight to the item and press "y". Exit back to "Device Drivers" with Esc-Esc.

ATA/ATAPI/MFM/RLL support: ATA here means IDE (aka PATA => parallel ATA to distinguish it from serial ATA, SATA), ATAPI is the designation for an optical drive, that is, a CD reader or writer, or a DVD reader or writer. If you have either, or both, these devices then you may need to make some changes in this section. On entering it you will see

Code: Select all

<*> ATA/ATAPI/MFM/RLL support
<*>   Enhanced IDE/MFM/RLL disk/cdrom/tape/floppy support
---     Please see Documentation/ide.txt for help/info on IDE dri
[ ]     Support for SATA (deprecated; conflicts with libata SATA
[ ]     Use old disk-only driver on primary interface
<*>     Include IDE/ATA-2 DISK support
[*]     Use multi-mode by default
<*>     Include IDE/ATAPI CDROM support
< >     Include IDE/ATAPI TAPE support (EXPERIMENTAL)
< >     Include IDE/ATAPI FLOPPY support

and there is a lot more. The following general options are set by default

Code: Select all

<*> ATA/ATAPI/MFM/RLL support
<*>   Enhanced IDE/MFM/RLL disk/cdrom/tape/floppy support
<*>     Include IDE/ATA-2 DISK support
[*]     Use multi-mode by default
<*>     Include IDE/ATAPI CDROM support
<*>     generic/default IDE chipset support
[*]     PCI IDE chipset support
[*]       Generic PCI bus-master DMA support
[*]         Use PCI DMA by default when available

you don't need to change these and

Code: Select all

[ ]           Enable DMA only for disks

which is the next one in the list and all the others above it which are not set should be left unset.

Following this there is a long list of IDE chipsets of which

Code: Select all

<*>         AMD and nVidia IDE support
<*>         Intel PIIXn chipsets support

are set.

Which do you need?

First of all run

Code: Select all

ls -d /sys/block/hd*
/sys/block/hda  /sys/block/hdb

which shows you have two IDE devices /dev/hda and /dev/hdb. You will find an example showing how the chipset driver for /dev/hda can be found in "Collected Hints and Tips" at the end of this FAQ: repeat it for every IDE device to make sure you select all the drivers you need.

Serial ATA (prod) and Parallel ATA (experimental) drivers: the SCSI settings required for SATA are already selected in the default configuration - as are a number of SATA chipset drivers. To find out how many SATA devices you have, run

Code: Select all

ls -d /sys/block/s[dr]*
/sys/block/sda  /sys/block/sdb

which shows you have two devices. You will find an example showing how to find the chipset driver for your device in "Collected Hints and Tips" at the end of this FAQ.

Now repeat this procedure for all the other /dev/sdX devices you have. Note that, if the experimental PATA drivers work for your hardware, PATA devices will be named /dev/sdX and the chipset driver will be "pata_xxx". These new PATA drivers also need SCSI disk support. If you have SATA optical drives or use the new PATA drivers for them, you will need SCSI CD-ROM support: they will be named /dev/srN as in /dev/sr0, /dev/sr1 and you should use the same procedure to determine their drivers.

Network device support: the procedure for selecting the driver (or drivers) is given in "Collected Hints and Tips", "Enabling the driver for a wired network in the kernel".

There are a number of other Ethernet devices which are enabled in the default configuration, if you wish, you can go through "Ethernet (10 or 100Mbit)" and "Ethernet (1000 Mbit)" and disable them.

To continue now with the remaining entries in the main menu which follow "Device Drivers".

The next is "File systems": if the file systems on your partitions are ext2, ext3 or reiserfs, then you do not need to change anything in this section - all three are selected. If you are using JFS or XFS then you will need to enable them. The three filesystems enabled are builtin to the kernel so the root partition can be formatted as any one of them. If your root partition uses JFS or XFS, then you will have to make it builtin as well, if another partition uses JFS or XFS then it can be enabled as a module instead.

"Instrumentation Support": no changes are needed but if you are unlikely to use OProfile or kprobes then you can go in to the section and disable them.

"Kernel hacking": there are a number of things enabled in this section, it doesn't seem necessary to make any changes.

"Security options": there are no selections made in this section but gkh-lkn recommends selecting

Code: Select all

[*] Enable different security models
<*>   Default Linux Capabilities

"unless you really want to run an insecure kernel for some reason".

"Cryptographic options": if you go into this section and read the Help for "[ ] Cryptographic API", you will see that the last line mentions "IEEE80211". If you are likely to use a WiFi card then you might like to enable this now. To use encryption with a WiFi card, you will need to enable more of the cipher algorithms, you could make them all modules and have done with it.

"Library routines": the help for "< > CRC-CCITT functions" says

This option is provided for the case where no in-kernel-tree modules require CRC-CCITT functions, but a module built outside the kernel tree does. Such modules that use library CRC-CCITT functions require M here.

You might like to make them all modules to avoid nasty surprises later on.

Now, having configured your kernel, leave menuconfig taking the option to save your new configuration. Copy it somewhere (/etc/kernels perhaps or /boot) as

Code: Select all

config-2.6.19-gentoo-r5-scratch

or a different name of your choice - the point is to make sure it isn't overwritten by a later configuration file so, if things go wrong, you can always come back to this one and start again.

Now continue with "Compiling and installing the kernel".

Slimming down a genkernel default configuration

First you need to find out what modules your hardware is actually using: running lsmod while booted into the LiveCD will give a list of around 40 modules as the LiveCD tries to cover all eventualities - and this doesn't include the IDE modules or the filesystem modules as these are builtin to the kernel.

To find out which of these modules is used, you can run this script from gkh-lkn(Chapter 7, "Let the kernel tell us what we need")

Code: Select all

#!/bin/bash
#
# find_all_modules.sh
#
for i in `find /sys/ -name modalias -exec cat {} \;`; do
    /sbin/modprobe --config /dev/null --show-depends $i ;
done | rev | cut -f 1 -d '/' | rev | sort -u

Run on an Athlon XP/VIA machine it gave

Code: Select all

FATAL: Module input:b0011v0001p... not found
...
FATAL: Module ide:m_cdrom not found.
FATAL: Module ide:m_disk not found.
...
3c59x.ko
crc-ccitt.ko
ehci-hcd.ko
libata.ko
mii.ko
sata_via.ko
uhci-hcd.ko
usbcore.ko
usbhid.ko
via-velocity.ko

There will probably be several lines beginning "FATAL: Module input:" or "FATAL: Module pci:", gkh-lkn (Chapter 7) says "Which means that it could not find a module that can control that device. Do not be concerned about this, as some devices do not have kernel drivers that will work for them."

The modules ide:m_cdrom and ide:m_disk are the IDE drivers supporting IDE disks and IDE (ATAPI) CD-ROMs, they are not found as they are builtin to the kernel.

To configure the high level IDE drivers and the IDE chipset driver, you can go back to the previous section, "Creating a kernel configuration from scratch", and use the instructions given.

The SATA chipset module is already clear, they all begin "sata_" and there is only one in the above list - sata_via.ko.

You can find out the driver that SATA needs (if it isn't clear) and how to enable it in the kernel from "Enabling a SATA driver in the kernel" in "Collected Hints and Tips" at the end of this FAQ.

To make sure you continue to have networking, you need to find out the driver that eth0 uses: this is also in "Collected Hints and Tips" under "Enabling the driver for a wired network in the kernel". You will see crc-ccitt and mii in the original list of modules, these are helper modules for the driver and are selected automatically.

You can then go through the rest of "Ethernet (10 or 100Mbit)", "Ethernet (1000 Mbit)" and "Ethernet (10000 Mbit)" removing any other devices which are enabled.

After all that, the remaining modules unaccounted for are: ehci-hcd, uhci-hcd, usbcore and usbhid all of which, surprisingly enough, are to do with USB. EHCI is USB 2.0 and UHCI is one flavour of USB 1.0 (the other is OHCI) and uhci-hcd is in use because that is the flavour chosen by your motherboard. You can go into Device Drivers -> USB support and remove unnecessary entries if you like: leave "EHCI HCD (USB 2.0) support" and leave one of "OHCI HCD support" or "UHCI HCD (most Intel and VIA) support" depending on which is favoured by your mainboard. You may want to enable "USB Printer support", you should keep "USB Mass Storage support" for cameras, MP3 players, flash disks and so on; unless you have one of the devices which are listed next ("Datafab Compact Flash Reader" to "Olympus MAUSB-10/Fuji DPC-R1") you can deselect them; you can deselect the group starting with "ATI / X10 USB RF remote control"; and you can deselect the entries in "USB DSL modem support" unless you have one of those USB DSL modems and you are using the USB connection.

You can now leave menuconfig, saving your new configuration and continue with compiling and installing the kernel.

Configuring the kernel to support a new item of hardware

[gkh-lkn Chapter 7: Finding which module is needed - there are more details and background to be found there]

First run lspci to get the hardware information. To demonstrate the procedure it will be used to find the driver for a SATA chipset and for an Ethernet card.

For the first example, the SATA controller had the following PCI information

Code: Select all

00:1f.2 SATA controller: Intel Corporation SATA Controller AHCI (rev 02)

Next the Vendor Id and the Device Id are needed, for this, run

Code: Select all

lspci -n | grep '^00:1f.2'

and you will see

Code: Select all

00:1f.2 0106: 8086:2821 (rev 02)

you need the last two numbers separated by a colon, "8086:2821", the first is the Vendor Id and the second the Device Id.

Searching the list of vendor id's in the kernel to find what "8086" is coded as

Code: Select all

grep -i 0x8086 /usr/src/linux-2.6.20-gentoo/include/linux/pci_ids.h
#define PCI_VENDOR_ID_INTEL             0x8086

("grep -i" is used even though this is all digits as the hexadecimal digits a-f may appear as A-F) now to find the device id

Code: Select all

find /usr/src/linux-2.6.20-gentoo -name \*.c | xargs grep -l INTEL

which yields 121 files but, as the file we are interested in must be under "drivers/ata", it reduces to

Code: Select all

/usr/src/linux-2.6.20-gentoo/drivers/ata/ahci.c
/usr/src/linux-2.6.20-gentoo/drivers/ata/ata_piix.c
/usr/src/linux-2.6.20-gentoo/drivers/ata/pata_mpiix.c
/usr/src/linux-2.6.20-gentoo/drivers/ata/pata_oldpiix.c
/usr/src/linux-2.6.20-gentoo/drivers/ata/pata_pdc202xx_old.c
/usr/src/linux-2.6.20-gentoo/drivers/ata/sata_sil24.c
/usr/src/linux-2.6.20-gentoo/drivers/ata/sata_vsc.c

We are looking for a line in a table which is headed

Code: Select all

static const struct pci_device_id

ahci.c has

Code: Select all

        { PCI_VDEVICE(INTEL, 0x2821), board_ahci_pi }, /* ICH8 */

ata_piix.c hasn't got it but, as this is older code, it doesn't have INTEL in the table but 0x8086; pata_mpiix.c, pata_oldpiix.c, pata_pdc202xx_old.c (only has Promise devices), sata_sil24.c and sata_sil24.c don't have it either. So the driver for this chipset is ahci.c.

The next step is to find the kernel configuration variable which causes this module to be compiled and this is described in "Collected Hints and Tips", "Enabling a SATA driver in the kernel".

Turning now to to the Ethernet controller, the output from lspci was

Code: Select all

03:00.0 Ethernet controller: Marvell Technology Group Ltd. 88E8053 PCI-E Gigabit Ethernet Controller (rev 22)
03:00.0 0200: 11ab:4362 (rev 22)

The entry in the kernel PCI Ids table is

Code: Select all

#define PCI_VENDOR_ID_MARVELL           0x11ab

Five files were found containing "MARVELL": /usr/src/linux-2.6.20-gentoo/drivers/net/{forcedeth,sk98lin/skge,skge,sky2,via-velocity}.c and the matching device id was found in /usr/src/linux-2.6.20-gentoo/drivers/net/sky2.c

Code: Select all

        { PCI_DEVICE(PCI_VENDOR_ID_MARVELL, 0x4362) }, /* 88E8053 */

To find the kernel configuration variable which causes this module to be compiled see "Collected Hints and Tips", "Enabling the driver for a wired network in the kernel".

There is a similar method for finding the driver for a USB device described in gkh-lkn Chapter 7 "USB Devices".

3) Compiling and installing the kernel

Compiling

Before starting compilation, save your .config: you can save it to /etc/kernels (which is where genkernel saves .configs) or to /boot. Give it a name like "config-2.6.19-gentoo-r5" and, if you already have a file by this name, add something on the end to remind you what you have changed in the new version. If, later on, you find the kernel doesn't work, you will then be able to go back to a working configuration and start again.

Note: the kernel developers warn that you should not configure or compile your kernel as root. In the past gkh-lkn says (Chapter 1 "Using This Book") that there have been bugs in the build process which caused files in the /dev tree to be deleted if run as root. Also unpacking the kernel source code as root can lead to some files having the wrong permissions.

If a kernel has been compiled in this source tree already then, if the new .config makes changes to the kernel itself - adds or removes a setting, makes a driver which was builtin a module or vice versa - you should at least run

Code: Select all

make clean

before recompiling. You could also run

Code: Select all

make mrproper

which does all that "make clean" does

remove most generated files but keep the config and enough build support to build external modules

but

removes all generated files + config + various backup files

After "make mrproper" you will have to copy your saved .config back again (as .config, of course).

Now just run

Code: Select all

make && make modules

Some posters say that if you are only adding a new module (which wasn't builtin to the kernel before) or removing a module (which is not being made a kernel builtin) then you can just run

Code: Select all

make modules

Installing

Installation has to be done as root.

First run

Code: Select all

make modules_install

to copy the compiled modules into /lib/modules under the kernel version: if the kernel source tree is /usr/src/linux-2.6.19-gentoo-r5 then the modules will be installed into directories under /lib/modules/2.6.19-gentoo-r5.

Your kernel, however, is usually installed into /boot: like the config file, give it a name which will remind you of the change to its configuration that you made. Your first kernel of a particular version can be named using the release string - kernel-2.6.19-gentoo-r5, for instance. If you already have a working kernel with this name, rename the working one kernel-2.6.19-gentoo-r5.wkg first before saving the new one.

To save the new kernel to /boot/kernel-2.6.19-gentoo-r5, first make sure (if you have a /boot partition) that /boot is mounted, then run

Code: Select all

cp -pv arch/i386/boot/bzimage /boot/kernel-2.6.19-gentoo-r5

If you do not have an x86 (i386) arch, replace "i386" with your arch: x86_64 &c.

Updating grub.conf

If you are recompiling a working kernel, then you will already have a section in your /boot/grub/grub.conf (or /boot/grub/menu.lst) to boot it and you shouldn't need to change it.

If it is a new kernel then you will have to create a new section: you can copy an existing section and modify the "title" and the kernel filename.

4) Recovering from a new kernel which doesn't boot

Booting from a saved version of the kernel

If it is a different configuration of an existing, working, kernel and you save the working version as (for instance) kernel-2.6.19-gentoo-r5.wkg, then boot and, as the GRUB menu appears, press 'e' to edit the kernel line. GRUB will display the section and you can move the highlight to the kernel line and press 'e' again. Now you can move along the line to the end of the kernel filename and add .wkg. Press Enter to leave editing mode and then press 'b' to boot the modified section.

You should now have your Gentoo installation back again to repair your kernel configuration.

Booting from a previous version of the kernel

This is simpler, when the GRUB menu appears, move the highlight to the line for the previous kernel and press Enter.

5) Collected Hints and Tips

Enabling an IDE driver in the kernel

To find the drivers for /dev/hda, run

Code: Select all

udevinfo -a -p /sys/block/hda | grep DRIVERS
    DRIVERS=="ide-disk"
    DRIVERS==""
    DRIVERS=="VIA_IDE"
    DRIVERS==""

which shows that /dev/hda depends on two drivers, the high level "ide-disk" which is enabled in the selections made under "<*> ATA/ATAPI/MFM/RLL support" shown above, and the IDE chipset driver "VIA_IDE". These chipset drivers are named after an older scheme and it requires a bit of digging in the files in drivers/ide/pci to find the file name for a particular module name. The following table shows the link between the module name and the prompt to get the driver compiled

Code: Select all

"AEC62xx_IDE",  AEC62XX chipset support
"ALI15x3_IDE",  ALI M15x3 chipset support
"AMD_IDE",      AMD and nVidia IDE support
"ATIIXP_IDE",   ATI IXP chipset IDE support
"CMD64x_IDE",   CMD64{3|6|8|9} chipset support
"TRIFLEX_IDE",  Compaq Triflex IDE support
"Cypress_IDE",  CY82C693 chipset support
"Cyrix_IDE",    Cyrix CS5510/20 MediaGX chipset support (VERY EXPERIMENTAL)
"CS5530 IDE",   Cyrix/National Semiconductor CS5530 MediaGX chipset support
"CS5535_IDE",   AMD CS5535 chipset support
"HPT34x_IDE",   HPT34X chipset support
"HPT366_IDE",   HPT36X/37X chipset support
"JMicron IDE",  JMicron JMB36x support
"SC1200_IDE",   National SCx200 chipset support
"PIIX_IDE",     Intel PIIXn chipsets support
"ITE821x IDE",  IT821X IDE support
"NS87415_IDE",  NS87415 chipset support
"Promise_Old_IDE",  PROMISE PDC202{46|62|65|67} support
"Promise_IDE",  PROMISE PDC202{68|69|70|71|75|76|77} support
"Serverworks_IDE",  ServerWorks OSB4/CSB5/CSB6 chipsets support
"SiI_IDE",      Silicon Image chipset support
"SIS_IDE",      SiS5513 chipset support
"SLC90e66_IDE",  SLC90E66 chipset support
"TRM290_IDE",   Tekram TRM290 chipset support
"VIA_IDE",      VIA82CXXX chipset support

For example, suppose that, as above, udevinfo shows your chipset driver to be "VIA_IDE", then you need to find the prompt "< > VIA82CXXX chipset support" and select it. Note that if your root filesystem is on this device, the driver must be builtin (select with "y"). If the IDE port has an optical drive attached, the high level driver will be "ide-cdrom" no matter whether it is a reader or a writer, DVD or CD.

Enabling a SATA driver in the kernel

The SCSI settings you need are

Code: Select all

   Device Drivers  --->
   SCSI device support  --->
<*> SCSI disk support
<M> SCSI CDROM support

To find the chipset driver (or drivers) for /dev/sda, run

Code: Select all

udevinfo -a -p /sys/block/sda | grep DRIVERS
    DRIVERS=="sd"
    DRIVERS==""
    DRIVERS==""
    DRIVERS=="ahci"
    DRIVERS==""

which shows that /dev/sda depends on two drivers, the high level "sd" (SCSI Disk support) which has already been enabled in "SCSI device support", and "ahci". To find out how to select the "ahci" driver, run

Code: Select all

cd /usr/src/linux-2.6.19-gentoo-r5
find -name Makefile | xargs grep ahci
./drivers/ata/Makefile:obj-$(CONFIG_SATA_AHCI)          += ahci.o

which shows that setting the configuration variable CONFIG_SATA_AHCI causes this driver to be built. Now use the Search facility in menuconfig to find the prompt and where it is: searching for "SATA_AHCI" yields

Code: Select all

Symbol: SATA_AHCI [=y]
Prompt: AHCI SATA support
  Defined at drivers/ata/Kconfig:26
  Depends on: ATA && PCI
  Location:
    -> Device Drivers
      -> Serial ATA (prod) and Parallel ATA (experimental) drivers
        -> ATA device support (ATA [=y])

so under "Serial ATA (prod) and Parallel ATA (experimental) drivers", you will find "ATA device support", if this has been enabled ("y") then you will see a long list of SATA and PATA chipsets, find the prompt shown above, "AHCI SATA support", and select it - if your root filesystem is on this device you must make it builtin ("y").

SATA hard drives (and PATA hard drives using the new drivers) need SCSI disk support as well as chipset support.

Optical drives using the new PATA drivers and, of course, SATA optical drives need SCSI CD-ROM support as well as chipset support.

Enabling the driver for a wired network in the kernel

First find out how many Ethernet controllers you have

Code: Select all

lspci | grep Ethernet

on the example machine this gave

Code: Select all

00:0a.0 Ethernet controller: 3Com Corporation 3c905C-TX/TX-M [Tornado] (rev 74)
00:0e.0 Ethernet controller: VIA Technologies, Inc. VT6120/VT6121/VT6122 Gigabit Ethernet Adapter (rev 11)

Now running

Code: Select all

ifconfig -a

shows eth0 and eth1. To find the driver that eth0 uses, run

Code: Select all

# udevinfo -a -p /sys/class/net/eth0
    DRIVERS==""
    DRIVERS=="3c59x"
    DRIVERS==""
    DRIVERS==""

Using the method shown above to find the configuration variable to enable this driver

Code: Select all

find /usr/src/linux-2.6.20-gentoo -name Makefile | xargs grep 3c59x
/usr/src/linux-2.6.20-gentoo/drivers/net/Makefile:obj-$(CONFIG_VORTEX) += 3c59x.o

Searching for "VORTEX" using menuconfig gives

Code: Select all

Symbol: VORTEX [=n]
Prompt: 3c590/3c900 series (592/595/597) "Vortex/Boomerang" support
  Defined at drivers/net/Kconfig:705
  Depends on: NET && NETDEVICES && !UML && NET_VENDOR_3COM && (PCI || E
  Location:
    -> Device Drivers
      -> Network device support
        -> Network device support (NETDEVICES [=y])
          -> Ethernet (10 or 100Mbit)
            -> 3COM cards (NET_VENDOR_3COM [=n])
  Selects: MII

You can then navigate to "3COM cards" and make it builtin instead of a module if you wish. Note that if "[ ] 3COM cards" is not selected, you will not see any of the options that depend on it. Select it ("y") to see them.

If you have more than one Ethernet controller, you can use the same procedure to find the driver for it as well.

The thing to note in VORTEX above is the last line: in VORTEX "Selects: MII" and in other cases "Selects: CRC32 && CRC_CCITT && MII" - these are helper modules for these drivers They are selected automatically whenever the driver is selected so you do not have to do anything.

Framebuffer support

After you have got your kernel working, you may like to add framebuffer support. To do this, go to "Device Drivers" and "Graphics support": in this section, you should enable

Code: Select all

< > Support for frame buffer devices

and, when the dependent options appear

Code: Select all

< >   VESA VGA graphics support

The default VESA driver type is "vesafb-tng" the default mode is "640x480@60": you can adjust this according to the capabilities of your graphics card and monitor. Support for particular chipsets is best avoided, at least for the moment, as some of them can interfere with Xorg. Under "Console display driver support" you should enable

Code: Select all

< > Framebuffer Console support

but the dependent options, "Framebuffer Console Rotation" and "Select compiled-in fonts" can be left disabled. You may wish to enable "Logo configuration" too - the dependent selections have already been made for you.

Find the modules (drivers) in use

A script (gkh-lkn) for finding the modules in use from a list of loaded modules (as on a LiveCD)

Code: Select all

#!/bin/bash
#
# find_all_modules.sh
#
for i in `find /sys/ -name modalias -exec cat {} \;`; do
    /sbin/modprobe --config /dev/null --show-depends $i ;
done | rev | cut -f 1 -d '/' | rev | sort -u

Given a module name, find the configuration option to enable it (gkh-lkn): for example, the module "cciss"

Code: Select all

cd /usr/src/linux
find -name Makefile | xargs grep cciss

One of the lines of output should look like

Code: Select all

./drivers/block/Makefile:obj-$(CONFIG_BLK_CPQ_CISS_DA)  += cciss.o

and you can the use Search in menuconfig to find "BLK_CPQ_CISS_DA" (leave off "CONFIG_" for Search) which will show you the option title ("Prompt:") and where it is to be found ("Location:").

Finding a module (driver) from the output of lspci

Finding the correct module given the "lspci" and "lspci -n" output is dealt with in "Configuring the kernel to support a new item of hardware"

6) Resources
Linux Kernel in a Nutshell

Chapter 7 tells how to find the driver and kernel config options for devices. This book is in portage as app-doc/linux-kernel-in-a-nutshell

The book is current as of the 2.6.18 kernel release, newer kernel versions will cause some of the configuration items to move around and new configuration options will be added.

Kernel configuration slideshow

[Earthwings]

Thanks very much for all the work with this FAQ, wynn.

Moved from Documentation, Tips & Tricks to Frequently Asked Questions. Please direct comments to the FAQ at [topic=69487][FAQF] KC11: Kernel compiling for the beginner.[/topic]