Kernel/Gentoo Kernel Configuration Guide

This page contains changes which are not marked for translation.

Other languages:

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 users to handle kernel configuration, installation, and upgrades: automatic (genkernel) and manual. Although the automatic method can be regarded as easier for most users, there are a number of reasons why a large proportion of Gentoo users choose to configure their kernels manually:

Greater flexibility
Smaller (kernel) sizes
Shorter compilation times
The learning experience
Severe boredom
Absolute knowledge of kernel configuration, and/or
Complete control

This guide does not cover the automatic method (genkernel). If genkernel is the preferred method of handling matters related to the kernel head over to the Genkernel article for details.

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 the system being used. Instead it will introduce the concepts of manual configuration and detail the most common pitfalls which users face.

Note
This guide is written with recent kernels in mind for common computer architectures. Some details may differ for older kernels or more exotic architectures; however much of the content will still be relevant.

At this point, the user is presumed to have Linux kernel sources unpacked on the hard disk (usually somewhere under /usr/src), and is expected to know how to enter the menuconfig configuration utility with knowledge to navigate through the ncursers-based menu system. If the user is not at this stage, other documentation is available to help. Read the following articles, then return to this guide:

The Kernel sources overview article contains information on the various kernel source packages available in the Portage tree.
The Kernel upgrade article explains how to upgrade a kernel or switch from one kernel to another.
The Gentoo Handbook's kernel configuration section covers some aspects of kernel installation. Select the appropriate architecture, then navigate to section titled "Configuring the Linux kernel".

Configuration concepts

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 the first time menuconfig is run 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 configuration. When deciding to disable an option that was enabled from kernel's default configuration, make sure a good understanding has been obtained of exactly what that option does, and the consequences of disabling it.

During a first time Linux kernel configuring, aim to be conservative; do not be too adventurous, and try to make as few modifications to the default settings as possible. At the same time, keep in mind that there are certain parts to a system's setup that must be customized to actually allow for the system to boot.

Built-in vs modular

Most configuration options are tristate: they can be either not built at all (N), built directly into the 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 the system might need them; it is left up to the user to decide when, or when to not, load a module. 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 to build hardware support and kernel features directly into the kernel. The kernel can then ensure the functionality and hardware support is available whenever needed. This is done by setting each kernel feature to (Y). For this setup to be coherent it is also necessary to include firmware support in the kernel. For details see the Linux firmware article.

For other parts of the configuration, built-in is an absolute requirement. For example, if the root partition is a btrfs filesystem the system can't 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.

See the article on kernel Modules for more information, and the instructions on using menuconfig to configure the kernel.

Hardware support

Beyond detecting the architecture type of the system, the configuration utility makes no attempt to identify what hardware is actually present in the system. While there are default settings for some hardware support, users almost certainly need to find and select the configuration options relevant to each system's hardware configuration.

Selecting the proper configuration options requires a knowledge of the components inside and connected to the computer. Most of the time these components can be identified without taking the lid off the system. For most internal components, users need to identify the chipset used on each device, rather than the retailed product name. Many expansion cards are retailed with a certain brand name, but use another manufacturer's chipset.

There are some utilities available to help users determine what kernel configuration options to use. lspci (part of the sys-apps/pciutils package) will identify PCI-based and AGP-based hardware, this includes components built onto the motherboard itself. lsusb (from the sys-apps/usbutils package) will identify various devices connected to the system's USB ports.

The situation is somewhat confused by varying degrees of standardization in the hardware world. Unless the user selects extreme deviation from the default configuration settings, the IDE hard disks should "just work", as will the PS/2 or USB keyboard and mouse. Basic VGA display support is also included. However, some devices such as Ethernet adapters are hardly standardized at all; for these devices users will have to identify the Ethernet chipset and select the appropriate hardware support for the specific card to get network access.

In addition, while some things just-about-work with the default settings, more specialized options may need to be selected to get the full potential from the system. For example, if support for the appropriate IDE chipset has not been enabled, the IDE hard disks will run very slowly.

It is recommended for drivers that require firmware to be configured as modules to more easily load the firmware from disk. Common groups that should be included here are GPU and networking drivers (when not using an NFS, or similar networked based, rootfs).

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 software feature example is advanced network functionality. In order to do some kind of routing or firewalling the relevant configuration items must be included in the kernel configuration.

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 guide should clear up common areas of confusion, and provide advice for how to avoid common problems which users often run into. Best wishes!

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, the system's storage devices will be treated as SCSI devices, which means SCSI disk/cdrom support will also be required. The first SATA hard disk will be named /dev/sda and the first SATA CD/DVD drive will be named /dev/sr0.

Although the majority of these drivers are for SATA controllers, libata was not designed to be SATA-specific. All common IDE drivers were also ported to libata, and at this point, the above considerations will also apply for IDE users.

KERNEL Configuration options for libata

Device Drivers  --->
   SCSI device support  --->
      <*> SCSI device support
      <*> SCSI disk support
      <*> SCSI CDROM support
 
      [ ] SCSI low-level drivers  --->
 
   <*> Serial ATA and Parallel ATA drivers (libata)  --->

Note
Non-standard chipset(s) are listed under SCSI low-level drivers in the Serial ATA and Parallel ATA drivers (libata) kernel box above.

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 4 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.
XHCI is the eXtensible Host Controller Interface. It is the host controller for USB 3.0 and is compatible with USB 1.0, 1.1, 2.0, 3.0 and future speeds. Enable this feature when the board supports USB 3.0.

Most systems come with two of the above interface types: XHCI (USB 3.0) and EHCI (USB 2.0). To use USB devices, it is no longer necessary to select both options since XHCI is compatible with slower USB-controllers. Users can also enable EHCI to be "extra" safe; it does no harm if USB 2.0 controllers are unavailable.

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 lspci trick (from the sys-apps/pciutils package) makes it relatively easy to detect which HCDs are present on system. Ignoring the SATA controller which was also matched, it is easy to spot that this system requires EHCI and XHCI support:

root #lspci -v | grep HCI

00:14.0 USB controller: Intel Corporation 8 Series/C220 Series Chipset Family USB xHCI (rev 04) (prog-if 30 [XHCI])
00:1a.0 USB controller: Intel Corporation 8 Series/C220 Series Chipset Family USB EHCI #2 (rev 04) (prog-if 20 [EHCI])
00:1d.0 USB controller: Intel Corporation 8 Series/C220 Series Chipset Family USB EHCI #1 (rev 04) (prog-if 20 [EHCI])
00:1f.2 SATA controller: Intel Corporation 8 Series/C220 Series Chipset Family 6-port SATA Controller 1 [AHCI mode] (rev 04) (prog-if 01 [AHCI 1.0])

Select the HCDs present on the system. In general select all three options for maximum support, or if the correct option is uncertain:

KERNEL Configuration for USB HCDs

Device Drivers  --->
   USB support  --->
      <*> Support for Host-side USB
      ---   USB Host Controller Drivers
      <*>   xHCI HCD (USB 3.0) support
      <*>   EHCI HCD (USB 2.0) support
      < >   OHCI HCD  (USB 1.1) support
      < >   UHCI HCD (most Intel and VIA) support

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

Nearly every recent Intel/AMD/IBM CPU supports the simultaneous multithreading (SMT) technology which is also known as hyper-threading. This technology enables a single CPU to be viewed by the system as two or more logical processors.
Most recent CPUs actually consist of multiple physical processors inside a single package, these processors are known as multi-core processors.
Some high-end computer systems actually have multiple physical processors installed on specialized motherboards to provide a significant performance increase over a uniprocessor system. System users will probably know if they have such a system, since they are not cheap.

In all of these cases, the appropriate kernel options must be selected to obtain optimum performance from these setups:

KERNEL Configuration for multi-processing support

Processor type and features  --->
 [*] Symmetric multi-processing support
 [*]   SMT (Hyperthreading) aware nice priority and policy support
 [*]   Multi-core scheduler support (NEW)

The next option not only enables power management features, but might also be a requirement for making all CPUs available to the system:

KERNEL Power management for multi-processor systems

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 896 MB RAM. If a system has more memory, only the first 896 MB will be visible, unless high memory support has been enabled.

Note
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!

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

KERNEL Enabling high memory support on x86

Processor type and features  --->
 High Memory Support  --->
  (X) 4GB
  ( ) 64GB

Compressed kernel modules

From kernel version 3.18.x (and up) compression of kernel modules has been possible. It is important to emerge sys-apps/kmod with the proper USE flags before compiling a kernel with compressed modules:

FILE /etc/portage/package.use/kmodEnabling compression support for kmod

sys-apps/kmod lzma zlib

Re-emerge sys-apps/kmod:

root #emerge --ask --oneshot --changed-use sys-apps/kmod

Enable module compression and select a preferred compression method:

KERNEL Enable module compression

[*] Enable loadable module support Search for <code>CONFIG_MODULES</code> to find this item. --->
  Module compression mode () --->
    ( ) None
    (X) GZIP
    ( ) XZ
    ( ) ZSTD

Usually make modules_install runs depmod. If sys-apps/kmod did not have the proper USE flags set (see the package.use 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:

root #

depmod -a

root #

modprobe <module_name>

Kernel configuration shorthand notation

Introduction

When reading about kernel configuration, often times settings are described as CONFIG_<something>. This short-hand notation is what the kernel configuration actually uses internally, and is what will be found 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 would not do much good if this cannot translate this to the real location in the kernel configuration. The make menuconfig tool makes this possible.

Translating CONFIG_FOO to the real configuration location

Suppose the CONFIG_TMPFS_XATTR feature needs to be enabled. Launch the kernel configuration menu (make menuconfig) and press the / key. This will open a search box. In the search box, type CONFIG_TMPFS_XATTR.

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

KERNEL Result of searching menuconfig for "CONFIG_TMPFS_XATTR"

Symbol: TMPFS_XATTR [=n]
Type  : boolean
Prompt: Tmpfs extended attributes
  Defined at fs/Kconfig:138
  Depends on: TMPFS [=y]
  Location:
    -> File systems
      -> Pseudo filesystems
(1)     -> 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 being searched for. It also shows that this setting is currently not enabled ([=n]).
Type: boolean	The setting searched for is a boolean (which means it can be one of two options: enabled or disabled). Some settings are numbers or strings.
Prompt: Tmpfs extended attributes	This is the text found in the make menuconfig entry that controls the variable (`TMPFS_XATTR`) in the .config file. It is essentially the variable name in a more human readable format.
Depends on: TMPFS [=y]	Before this entry can be seen `CONFIG_TMPFS` must be enabled. In this case it is already done (hence the [=y]) but if this is not the case, first look for (and enable) `CONFIG_TMPFS`.
Location: ...	This is the location in the make menuconfig structure where the setting can be found. Remember, the setting to look for is Tmpfs extended attributes.
Selected by: TMPFS_POSIX_ACL [=n] && TMPFS [=y]	If the settings described here are both enabled (in this case the first one is not), then `CONFIG_TMPFS_XATTR` will be automatically enabled and will not be possible to be disabled until one of these settings is de-selected.

With this information, it should be possible to translate any CONFIG_* requirements fairly easily. In short, it means a user must:

Enable the settings described in the Depends on field
Navigate where Location: points
Toggle the value referred to by Prompt:

Tip
Notice the number in parenthesis; users can jump to that option, or as close as possible for enabled menus, by pressing the number while in the search. In the above example, pressing 1 on the keyboard will jump to or near that option.

Troubleshooting

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 of actually booting to their newly configured kernel. 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:

configure
compile
mount /boot (if not already mounted)
copy new kernel image to /boot
make sure the bootloader will reference the new kernel
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 /usr/src/linux, the following command can be used:

root #uname -v

#4 SMP PREEMPT Sat Jul 15 08:49:26 BST 2006

The above command will display the date and time the currently booted kernel 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 the 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 behavioral 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 selecting a component as built-in, the code is built into the kernel image (bzImage). When the kernel needs to use that component, it can initialize and load it automatically, without any user intervention.

When selecting a component as a module, the code is built into a kernel module file and installed on the filesystem. In general, when the kernel needs to use that component, it will not be able to find it. With some exceptions, the kernel makes no effort to actually load these modules — this task is left up to the user.

If building support for a network card as a module, and it is discovered the network is not accessible, it is probably because the module is not loaded — either this must be done manually or the system must be configured to autoload the module at boot time.

Unless a user has reason to do otherwise, some time can be saved by building these components directly into the kernel image, so that the kernel can automatically configure these small settings by itself.

Kernel/Gentoo Kernel Configuration Guide

Contents

Introduction

Configuration concepts

The basics

Built-in vs modular

Hardware support

Kernel features

Ready?

Common problems and areas of confusion

SATA disks are SCSI

USB host controllers

Multiprocessor, hyper-threading, and multi-core systems

x86 high memory support

Compressed kernel modules

Kernel configuration shorthand notation

Introduction

Translating CONFIG_FOO to the real configuration location

Other kernel configuration documentation

Troubleshooting

Configuration changes do not take effect

Modules do not get loaded automatically

See also