Kernel/Gentoo Kernel Configuration Guide/en

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

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


 * 1) greater flexibility,
 * 2) smaller (kernel) sizes,
 * 3) shorter compilation times,
 * 4) the learning experience,
 * 5) severe boredom,
 * 6) absolute knowledge of kernel configuration, and/or
 * 7) complete control.

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 ), and you are expected to know how to enter the  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 basics
The general process is actually rather simple: a series of options, categorized into individual menus and sub-menus, are presented and the desired hardware support and kernel features relevant to the system are selected.

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.

For other parts of the configuration, built-in is an absolute requirement. For example, if the root partition was an btrfs filesystem the system would not boot if btrfs was built as a module. The system would have to look on the root partition to find the btrfs module (since modules are stored in the root partition), but it cannot look on the root partition unless it already has btrfs support loaded! If btrfs has not been built-in then the init process will fail to find the root device.

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. (part of the package) will identify your PCI-based and AGP-based hardware, and this includes components built onto the motherboard itself. (from the 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
In addition to hardware support, users need to consider the software features that will be required in the kernel. One important example of such a feature is filesystem support: users must select support for the filesystems in use on their hard disks, as well as any filesystems they might use on external storage devices (e.g. VFAT on USB drives).

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.

Ready?
Now that the concepts have been introduced, it should be easy to start identifying the system hardware, browsing through the menuconfig interface, and selecting the required kernel options for the 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!

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.) and your SATA CD/DVD drive will be named as (e.g.).

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.

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.

If you're not using libata for your IDE disks, then you'll need to check for DMA usage and enable it.

To enable DMA on your IDE devices, you simply need to enable the configuration option for your IDE controller.

USB Host Controllers
USB is a widely adopted bus for connecting external peripherals to a computer. One of the reasons behind the success of USB is that it is a standardized protocol, however the USB host controller devices (HCDs) implemented on the host computer do vary a little. There are 3 main types:


 * is the Universal Host Controller Interface. It supports USB 1.1, and is usually found on motherboards based on a VIA or Intel chipset.
 * is the Open Host Controller Interface. It supports USB 1.1 and is usually found on motherboards based on an Nvidia or SiS chipset.
 * 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.5Mb/s?

If the relevant options corresponding to the USB HCD types present on the system are not selected, then 'dead' USB ports may be experienced. This case can be determined if a working USB device is plugged in, but it does not get power or respond in any way.

A neat  trick (from the  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:

In Linux kernel 3.12.13 and later, OHCI support for PCI-bus USB controllers 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.

The next option not only enables power management features, but might also be a requirement for making all CPUs available to the 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.

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!

Choose the 4GB option, unless your system has more than 4GB of RAM:

Compressed kernel modules
From kernel version 3.18.x (and up) compression of kernel modules has been possible. gzip and xz compression are available. It is important to emerge with the proper USE flags before compiling a kernel with compressed modules:

Re-emerge :

Enable module compression and select a preferred compression method:

Usually make modules_install runs depmod. If did not have the proper USE flags set (see the  step above) the first time it was run, then the dependency list will be empty. The system will therefore be unable to load any modules that were built compressed.

After kmod has been recompiled, re-run depmod as a solution to this problem:

Introduction
When you read about kernel configurations, you will often see that settings are described as. 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 or in the auto-generated  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  tool allows you to do just that.

Translating CONFIG_FOO to the real configuration location
Suppose you need to enable, launch the kernel configuration menu  and type in. This will open the search box. In this search box, type  (you can even drop the  ). The next code listing shows the result of this search.

The following is an output of the result of this search:

This output yields lots of interesting information.

With this information, you should be able to translate any  requirements tossed at you easily. In short, it means you


 * 1) Enable the settings described in the Depends on field;
 * 2) Navigate where Location: points;
 * 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.

Getting the basics of a kernel operational will help users in later configuration steps because the user will know what is breaking their system and what is not. It is always wise to save the base (working) kernel configuration in a folder other than the kernel's sources folder before attempting to add new features or hardware.


 * 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 needed in order to use bluetooth devices.


 * 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 running a PowerPC system, the PPC FAQ has a few sections about PPC 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; refer to the Kernel Upgrade Guide for general guidance. In short, the process to get a modified kernel is the following: 1) configure, 2) compile, 3) mount (if not already mounted), 4) copy new kernel image to, 5) Make sure the bootloader will reference the new kernel, 6) reboot. If one of those final stages has been missed, then the changes will not properly take effect.

It is possible to verify if the kernel that has booted matches the newly kernel compiled on the hard disk. This is performed by examining the date and time of the kernel's compilation. Assuming the system architecture is x86 and the kernel sources are installed at, the following command can be used:

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

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

If the time stamps from the above commands differ by more than 2 minutes, it indicates a mistake was made during kernel reinstallation and the system has not booted from the newly modified kernel image.

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.