Kernel/Gentoo Kernel Configuration Guide

From Gentoo Wiki
Revision as of 19:05, 19 April 2014 by SwifT (Talk | contribs)

Jump to: navigation, search
Other languages:English 100% • ‎español 100% • ‎français 100% • ‎日本語 10% • ‎русский 100%

This document aims to introduce the concepts of manual kernel configuration, and to detail some of the most common configuration pitfalls.


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.

Configuration Concepts

The basics

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 (N), 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 it.

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!).

Hardware support

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.

Kernel features

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 type.

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.

CodeConfiguration 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
    Select your chipset from the choices listed below the above option

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 being used.

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.

root # 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.

Kernel configurationConfiguration 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
  Select your chipset from the choices listed below the above option

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 than 1.5mbit/sec?

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:

root # 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])
Kernel configurationConfiguration 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
  Select the HCDs present on your system, or all 3 if you are unsure.

In Linux kernel 3.12.13 and later, OHCI support for PCI-bus USB controllers (CONFIG_USB_OHCI_HCD_PCI) has to be enabled if the USB controller is OHCI and a USB keyboard or mouse is used.

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 logical processors.
  • Most Intel/AMD CPUs actually consist of multiple physical processors inside a single package, these are known as multi-core processors.
  • 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.

Kernel configurationConfiguration for multi-processing

Processor type and features  --->
 [*] Symmetric multi-processing support
 Select the above option if you are on a multi-processor system (of any type)
 [*]   SMT (Hyperthreading) scheduler support
 Select the above option if you are on an Intel Hyper-Threading CPU
 [*]   Multi-core scheduler support (NEW)
 Select the above option if your CPU is multi-core
Power management and ACPI options  --->
 [*] ACPI (Advanced Configuration and Power Interface) Support
 The above option not only enables power management features, but might
 also be a requirement for making all CPUs available to your system

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 required.

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!

Kernel configurationEnabling high memory support on x86

Processor type and features  --->
 High Memory Support  --->
  (X) 4GB
  ( ) 64GB
  Choose the 4GB option, unless your system has more than 4GB of RAM.

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.

Kernel configurationResult 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.

Entry Description
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]).
Type: boolean 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.
Location: ... This is the location in the make menuconfig structure where you can find the setting. Remember, the setting you are looking for is Tmpfs extended attributes.
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

  1. need to enable the settings described in the Depends on field
  2. navigate where Location: points you towards
  3. 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 article 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 article details the options you need in order to use bluetooth devices on your system.
  • The IPv6 router guide describes how to configure your kernel for routing using the next generation network addressing scheme.
  • 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 kernel configuration.
  • 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 effect!

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 /usr/src/linux:

root # uname -v
#4 SMP PREEMPT Sat Jul 15 08:49:26 BST 2006

The above command displays the date and time that the kernel you are currently booted from was compiled.

root # 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

The above command displays the date and time that the kernel image on your hard disk was last compiled.

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.


We would like to thank the following authors and editors for their contributions to this guide:

  • Daniel Drake
  • Curtis Napier
  • Justin Robinson
  • Łukasz Damentko
  • Jonathan Smith
  • nightmorph