Gentoo Linux Kernel Configuration Guide
Gentoo provides two ways for you to handle kernel installation and upgrade:
automatic (genkernel), and manual. Although the automatic method
can be regarded as easier for the user, there are a number of reasons
why a large proportion of Gentoo users choose to configure their kernel
manually: greater flexibility, smaller kernel, shorter compilation time,
learning experience, severe boredom, etc.
This guide does not cover the automatic method (genkernel). If you'd prefer to
use genkernel to compile and install your kernel, head over to the Genkernel documentation.
This guide does not attempt to document the manual configuration process from
start to finish -- the configuration process relies upon a large degree of
common sense, and a relatively high level of technical knowledge about your
system. Instead, this document will introduce the concepts of manual
configuration and detail the most common pitfalls which users face.
This document is written with recent kernels in mind, for the most common
computer architectures. Some details may differ for older kernels or more
exotic architectures, but much of the content will still be relevant.
At this point, you are assumed to have Linux kernel sources unpacked on your
hard disk (usually somewhere under /usr/src), and you are expected to
know how to enter the menuconfig configuration utility and move through
the menu system. If you are not already at this stage, we do have other
documentation available to help you.
The Kernel Guide lists the
various kernel source packages we have available
The Kernel Upgrade Guide
explains how to upgrade your kernel or switch from one to another.
The Gentoo Handbook covers
some aspects of kernel installation too.
The general process is actually rather simple: you are presented with a series
of options, categorised into individual menus and sub-menus, and you select the
hardware support and kernel features relevant for your system.
The kernel includes a default configuration, which is presented to you
the first time you run menuconfig on a particular set of sources. The defaults
are generally broad and sensible, which means that the majority of users will
only have to make a small number of changes to the base config. If you decide
to disable an option that was enabled by default, make sure you have a
relatively good understanding of exactly what that option does, and the
consequences of disabling it.
If this is your first time configuring a Linux kernel, you should probably aim
to be conservative: don't be too adventurous, and aim to make as few
modifications to the default settings as possible. At the same time, keep in
mind that there are certain parts of the configuration which you absolutely
must customise to your system setup to actually allow it to boot!
Built-in vs modular
Most configuration options are tristate: they can be either not built at
all, built directly into your kernel (Y), or built as a module (M). Modules are
stored externally on the filesystem, whereas built-in items are built directly
into the kernel image itself.
There is an important difference between built-in and modular: with a few
exceptions, the kernel makes no attempt whatsoever to load any external modules
when you might need them (it is left up to the user). While certain other parts
of the system may have load-on-demand facilities, and there are some automatic
module loading utilities available, it is recommended that you build hardware
support and kernel features directly into the kernel. The kernel can then
ensure the functionality and hardware support is available whenever it needs
Of course, for some parts of the configuration, built-in is an absolute
requirement. For example, if your root partition was an ext2 filesystem,
your system would not boot if ext2 was built as a module (the system would have
to look on the root partition to find the ext2 module, but it cannot look on
the root partition unless it already has ext2 support loaded!).
Beyond detecting the architecture type of your system, the configuration
utility makes no attempt to identify which hardware is actually present in your
system. While there are default settings for some hardware support, you almost
certainly need to find and select the configuration options relevant to your
system's hardware configuration.
This simply requires knowledge of the components inside and connected to your
computer, or for you to identify these components. For most internal
components, you need to identify the chipset used on each one, rather
than the retail product name.
There are some utilities available that will help you. lspci (part of
the sys-apps/pciutils package) will identify your PCI-based and
AGP-based hardware, and this includes components built onto the motherboard
itself. lsusb (from the sys-apps/usbutils package) will identify
devices connected to USB ports.
The situation is somewhat confused by varying degrees of standardisation in the
hardware world. Unless you really deviate from the defaults, your IDE hard
disks will "just work", as will your PS/2 or USB keyboard and mouse. You'll get
basic VGA display support. However, some devices such as ethernet adapters are
barely standardised at all, so you'll have to identify the ethernet chipset and
select the appropriate hardware support for your specific card to get any
network access at all.
In addition, while some things just-about-work with the default settings, you
may need to select more specialised options to get the full potential from your
system. For example, if you do not enable the support for the appropriate IDE
chipset, your IDE hard disks will run very slowly.
As well as hardware support, you also need to think in terms of the software
features you require in your kernel. One important example of such a feature is
filesystem support: you need to select support for the filesystems in use on
your hard disk, as well as any filesystems you might be using on external
storage (e.g. VFAT on USB flash disks).
Another common example is advanced network functionality. If you want to do
some kind of routing or firewalling, you need to ensure the relevant
configuration items are included in your kernel config.
Now that we've introduced the concepts, you should be able to start identifying
your hardware and browsing through the configuration menus, selecting the
required kernel options for your system.
The rest of this page aims to clear up common areas of confusion, and provide
advice for how to avoid common problems which users often run into. Good luck!
Common problems and areas of confusion
SATA disks are SCSI
Most modern desktop systems ship with storage devices (hard disk and CD/DVD
drives) on a Serial ATA
bus, rather than the older IDE (ribbon cable) bus
SATA support in Linux is implemented in a layer referred to as libata,
which sits below the SCSI subsystem. For this reason, SATA drivers are found in
the SCSI driver section of the configuration. Additionally, your storage
devices will be treated as SCSI devices, which means SCSI disk/cdrom support is
required too. Your SATA hard disk will be named as (e.g.) /dev/sda and
your SATA CD/DVD drive will be named as (e.g.) /dev/sr0.
Although the majority of these drivers are for SATA controllers, libata was not
designed to be SATA-specific. All common IDE drivers will also be ported to
libata in the near future, and at this point, the above considerations will
also apply for IDE users.
Code Listing 3.1: Configuration options for libata
Device Drivers --->
SCSI device support --->
<*> SCSI device support
<*> SCSI disk support
<*> SCSI CDROM support
SCSI low-level drivers --->
<*> Serial ATA (SATA) support
IDE chipsets and DMA
Despite the introduction of SATA, IDE devices are still very common and
depended upon by many. IDE is a fairly generic technology, and as such, Linux
supports almost all IDE controllers out-of-the-box without any
controller-specific options selected.
However, IDE is an old technology, and in it's original Programmed
Input/Output incarnation, it is unable to provide the transfer rates
required for speedy access to modern storage devices. The generic IDE driver is
limited to these PIO transfer modes, which result in slow data transfer rates,
and significantly high CPU usage while data is being transferred to/from disk.
Unless you're dealing with a pre-1995 system, your IDE controller will also
support an alternative transfer mode, known as Direct Memory Access
(DMA). DMA is much much faster, and CPU utilisation is barely affected while
data transfers are taking place. If you are suffering from really poor general
system performance and you are using an IDE disk, chances are that DMA is not
As mentioned earlier, libata is available even for IDE drives. If you're using
libata, then all your drives, including your IDE drives, will be using DMA.
There's no need to do any further checking or configuration.
If you're not using libata for your IDE disks, then you'll need to check for DMA
usage and enable it.
Code Listing 3.2: Checking if DMA is enabled on your IDE disk
# hdparm -d /dev/hda
using_dma = 0 (off)
To enable DMA on your IDE devices, you simply need to enable the configuration
option for your IDE controller.
Code Listing 3.3: Configuration options for IDE controllers
Device Drivers --->
ATA/ATAPI/MFM/RLL support --->
<*> ATA/ATAPI/MFM/RLL support
<*> Enhanced IDE/MFM/RLL disk/cdrom/tape/floppy support
[*] PCI IDE chipset support
USB Host Controllers
USB is a widely adopted bus
for connecting external peripherals to your computer. One of the reasons behind
the success of USB is that it is a standardised protocol, however the USB
host controller devices (HCDs) implemented on the host computer do vary
a little. There are 3 main types:
UHCI is the Universal Host Controller Interface. It supports USB
1.1, and is usually found on motherboards based on a VIA or Intel chipset.
OHCI is the Open Host Controller Interface. It supports USB 1.1 and
is usually found on motherboards based on an Nvidia or SiS chipset.
EHCI is the Extended Host Controller Interface. It is the only
common host controller to support USB 2.0, and can typically be found on
any computer that supports USB 2.0.
Most systems will come with two of the above interface types: EHCI (USB 2.0),
plus either UHCI or OHCI (USB 1.1). It is important that you select both types
present on your system. While all USB 2.0 devices are backwards compatible with
USB 1.1, a large proportion of USB devices (even the ones being manufactured
today) are based on the USB 1.1 interface - why would a USB mouse need more
If you do not select the relevant options corresponding to the USB HCD types
present on your system, you may experience 'dead' USB ports: you plug a device
in, but it does not get power or respond in any way.
A neat lspci trick (from the sys-apps/pciutils package) makes it
relatively easy to detect which HCDs are present in your system. Ignoring the
FireWire controller which was also matched, it is easy to spot that my system
requires OHCI and EHCI support:
Code Listing 3.4: Using lspci to detect HCD type
# lspci -v | grep HCI
00:02.0 USB Controller: nVidia Corporation CK804 USB Controller (rev a2) (prog-if 10 [OHCI])
00:02.1 USB Controller: nVidia Corporation CK804 USB Controller (rev a3) (prog-if 20 [EHCI])
01:0b.0 FireWire (IEEE 1394): Agere Systems FW323 (rev 61) (prog-if 10 [OHCI])
Code Listing 3.5: Configuration for USB HCDs
Device Drivers --->
USB support --->
<*> Support for Host-side USB
--- USB Host Controller Drivers
<*> EHCI HCD (USB 2.0) support
<*> OHCI HCD support
<*> UHCI HCD (most Intel and VIA) support
Multiprocessor, Hyper-Threading and Multi-Core systems
Many computer systems are based on multiple processors, but not always in
immediately obvious ways.
Many of Intel's CPUs support a technology which they call hyper-threading,
which is where the CPU is actually viewed by the system as two
Most Intel/AMD CPUs actually consist of multiple physical processors
inside a single package, these are known as multi-core
Some high-end computer systems actually have multiple physical processors
installed on specialised motherboards to provide a significant performance
increase over a uniprocessor system. You'll probably know if you
have such a system, since they aren't cheap.
In all of these cases, you need to select the appropriate kernel options to
obtain optimum performance from these setups.
Code Listing 3.6: Configuration for multi-processing
Processor type and features --->
[*] Symmetric multi-processing support
[*] SMT (Hyperthreading) scheduler support
[*] Multi-core scheduler support (NEW)
Power management and ACPI options --->
[*] ACPI (Advanced Configuration and Power Interface) Support
x86 High Memory support
Due to limitations in the 32-bit address space of the x86 architecture, a
kernel with default configuration can only support up to 896mb RAM. If your
system has more memory, only the first 896mb will be visible, unless you enable
high memory support.
This limitation is specific to the x86 (IA32) architecture. Other architectures
naturally support large amounts of memory, with no configuration tweaks
High memory support is not enabled by default, because it introduces a small
system overhead. Do not be distracted by this, the overhead is insignificant
when compared to the performance increase of having more memory available!
Code Listing 3.7: Enabling high memory support on x86
Processor type and features --->
High Memory Support --->
( ) 64GB
Kernel configuration shorthand notation
When you read about kernel configurations, you will often see that settings are
described as CONFIG_<something>. This short-hand notation is what
the kernel configuration actually uses internally, and is what you will find in
the kernel configuration file (be it /usr/src/linux/.config or in
the auto-generated /proc/config.gz file). Of course, using
short-hand notation wouldn't do much good if you cannot translate this to the
real location in the kernel configuration. Luckily, the make menuconfig
tool allows you to do just that.
Translating CONFIG_FOO to the real configuration location
Suppose you need to enable CONFIG_TMPFS_XATTR, launch the kernel
configuration menu (make menuconfig) and type in /. This will open
the search box. In this search box, type CONFIG_TMPFS_XATTR (you can even
drop the CONFIG_). The next code listing shows the result of this search.
Code Listing 4.1: Result of looking for CONFIG_TMPFS_XATTR
Symbol: TMPFS_XATTR [=n]
Type : boolean
Prompt: Tmpfs extended attributes
Defined at fs/Kconfig:138
Depends on: TMPFS [=y]
-> File systems
-> Pseudo filesystems
-> Virtual memory file system support (former shm fs) (TMPFS [=y])
Selected by: TMPFS_POSIX_ACL [=n] && TMPFS [=y]
This output yields lots of interesting information.
|Symbol: TMPFS_XATTR [=n]
This identifies the kernel configuration entry you are looking for. It also
already tells you that the setting is currently not enabled ([=n]).
The setting you looked for is a boolean (which means you can enable or
disable it). Some settings are numbers or strings.
|Prompt: Tmpfs extended attributes
This is the text you will find in make menuconfig and as such, is the
entry that you are looking for in a more human readable format.
|Depends on: TMPFS [=y]
Before you can even see this entry, you need to have CONFIG_TMPFS
enabled. In this case, this is done (hence the [=y]) but if this is not the
case, you will first need to look (and enable) CONFIG_TMPFS.
This is the location in the make menuconfig structure where you can
find the setting. Remember, the setting you are looking for is Tmpfs
|Selected by: TMPFS_POSIX_ACL [=n] && TMPFS [=y]
If the settings described here are both enabled (in our case, the first one
isn't), then CONFIG_TMPFS_XATTR will be automatically enabled as well
and you will not be able to disable it.
With this information, you should be able to translate any CONFIG_*
requirements tossed at you easily. In short, it means you
- need to enable the settings described in the Depends on field
- navigate where Location: points you towards
- toggle the value referred to by Prompt:
Other kernel configuration documentation
So far, we have only discussed general concepts and specific problems related
to kernel configuration, without going into any precise details (such details
are for you to discover!). However, other parts of the Gentoo documentation
collection provide specialised details for the topics at hand.
You may find these documents helpful while configuring those specific areas,
but if you are new to kernel configuration, don't be too adventurous. Start by
getting a basic system up and running, you can always come back later to add
support for your audio, printing, etc.
The ALSA Guide details the
configuration options required for sound card support. Note that ALSA is
one exception to the suggested scheme of not building things as modules:
ALSA is actually much easier to configure when the components are modular.
The Bluetooth wiki
article details the options you need in order to use bluetooth devices on
The IPv6 Router Guide describes how to
configure your kernel for routing using the next generation network
If you will be using the closed-source nVidia graphics drivers for improved
3D graphics performance, the nVidia
Guide lists the options that should and should not be selected on
such a system.
Amongst other things, the Power Management Guide
explains how to configure your kernel for CPU frequency scaling, and for
suspend and hibernate functionality.
If you are running a PowerPC system, the PPC FAQ has a few sections about
The Printing HOWTO lists the
kernel options needed to support printing in Linux.
The USB Guide details the
configuration required to use common USB devices such as keyboards/mice,
storage devices, and printers.
Configuration changes do not take effect
It is very common for users to make a configuration change, but then make a
small mistake in the process following on from that point. They reboot into a
kernel image that is not the one they just reconfigured, observe that whatever
problem they were trying to solve is still present, and conclude that the
configuration change does not solve the problem.
The process of compiling and installing kernels is outside the scope of this
document, you should refer to the Kernel
Upgrade Guide for general guidance. In short, the process is: configure,
compile, mount /boot (if not already mounted), copy new kernel image over,
reboot. If you miss out any of those final stages, your changes will not take
It is possible to verify if the kernel you are booted from matches the kernel
compiled on your hard disk by examining the date and time of compilation.
Assuming your architecture is x86 and your kernel sources are installed at
Code Listing 6.1: Verifying you are booted from your modified kernel
# uname -v
#4 SMP PREEMPT Sat Jul 15 08:49:26 BST 2006
# ls -l /usr/src/linux/arch/i386/boot/bzImage
-rw-r--r-- 1 dsd users 1504118 Jul 15 08:49 /usr/src/linux/arch/i386/boot/bzImage
If the two times from the above commands differ by more than 2 minutes, it
indicates that you have made a mistake during kernel reinstallation and you are
not booted from the kernel image that you thought you were!
Modules do not get loaded automatically
As mentioned earlier in this document, the kernel configuration system hides a
large behavioural change when selecting a kernel component as a module (M)
rather than built-in (Y). It is worth repeating this again because so many
users fall into this trap.
When you select a component as built-in, the code is built into the kernel
image (bzImage). When the kernel needs to use that component, it can initialise
and load it automatically, without any user intervention.
When you select a component as a module, the code is built into a kernel module
file and installed on your filesystem. In general, when the kernel needs to use
that component, it can't! With some exceptions, the kernel makes no effort to
actually load these modules - this task is left up to the user.
So, if you build support for your network card as a module, and you then find
that you cannot access your network, it is probably because the module is not
loaded - you must either do this manually or configure your system to autoload
it at boot time.
Unless you have reasons to do otherwise, save yourself some time by building
these components directly into the kernel image, so that the kernel can
automatically set these things up for you.
The contents of this document, unless otherwise expressly stated, are licensed under the CC-BY-SA-2.5 license. The Gentoo Name and Logo Usage Guidelines apply.