rane 06/07/16 22:34:47 Added: kernel-config.xml Log: #94955, now we have kernel configuration documentation
Revision Changes Path 1.1 xml/htdocs/doc/en/kernel-config.xml file : http://www.gentoo.org/cgi-bin/viewcvs.cgi/xml/htdocs/doc/en/kernel-config.xml?rev=1.1&content-type=text/x-cvsweb-markup&cvsroot=gentoo plain: http://www.gentoo.org/cgi-bin/viewcvs.cgi/xml/htdocs/doc/en/kernel-config.xml?rev=1.1&content-type=text/plain&cvsroot=gentoo Index: kernel-config.xml =================================================================== <?xml version="1.0" encoding="UTF-8"?> <!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/kernel-config.xml,v 1.1 2006/07/16 22:34:46 rane Exp $ --> <!DOCTYPE guide SYSTEM "/dtd/guide.dtd"> <guide link="/doc/en/kernel-config.xml"> <title>Gentoo Linux Kernel Configuration Guide</title> <author title="Author"> <mail link="[EMAIL PROTECTED]">Daniel Drake</mail> </author> <author title="Contributor"> <mail link="[EMAIL PROTECTED]">Curtis Napier</mail> </author> <author title="Contributor"> <mail link="[EMAIL PROTECTED]">Justin Robinson</mail> </author> <author title="Contributor"> <mail link="[EMAIL PROTECTED]">Åukasz Damentko</mail> </author> <author title="Editor"> <mail link="[EMAIL PROTECTED]">Jonathan Smith</mail> </author> <abstract> This document aims to introduce the concepts of manual kernel configuration, and to detail some of the most common configuration pitfalls. </abstract> <!-- The content of this document is licensed under the CC-BY-SA license --> <!-- See http://creativecommons.org/licenses/by-sa/2.5 --> <license/> <version>1.0</version> <date>2006-07-16</date> <chapter> <title>Introduction</title> <section> <body> <p> Gentoo provides two ways for you to handle kernel installation and upgrade: <e>automatic</e> (genkernel), and <e>manual</e>. Although the automatic method can be regarded as <e>easier</e> 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. </p> <p> 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 <uri link="/doc/en/genkernel.xml">Genkernel documentation</uri>. </p> <p> 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. </p> <p> 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. </p> <p> At this point, you are assumed to have Linux kernel sources unpacked on your hard disk (usually somewhere under <c>/usr/src</c>), and you are expected to know how to enter the <c>menuconfig</c> 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. </p> <ul> <li> The <uri link="/doc/en/gentoo-kernel.xml">Kernel Guide</uri> lists the various kernel source packages we have available </li> <li> The <uri link="/doc/en/kernel-upgrade.xml">Kernel Upgrade Guide</uri> explains how to upgrade your kernel or switch from one to another. </li> <li> The <uri link="/doc/en/handbook/index.xml">Gentoo Handbook</uri> covers some aspects of kernel installation too. </li> </ul> </body> </section> </chapter> <chapter> <title>Configuration Concepts</title> <section> <title>The basics</title> <body> <p> 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. </p> <p> The kernel includes a <e>default configuration</e>, 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. </p> <p> 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! </p> </body> </section> <section> <title>Built-in vs modular</title> <body> <p> Most configuration options are <e>tristate</e>: 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. </p> <p> 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. </p> <p> Of course, for some parts of the configuration, built-in is an absolute requirement. For example, if your root partition was an <c>ext2</c> 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!). </p> </body> </section> <section> <title>Hardware support</title> <body> <p> Beyond detecting the <e>architecture type</e> 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. </p> <p> 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 <e>chipset</e> used on each one, rather than the retail product name. </p> <p> There are some utilities available that will help you. <c>lspci</c> (part of the <c>sys-apps/pciutils</c> package) will identify your PCI-based and AGP-based hardware, and this includes components built onto the motherboard itself. <c>lsusb</c> (from the <c>sys-apps/usbutils</c>) package will identify devices connected to USB ports. </p> <p> 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. </p> <p> 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 <e>very</e> slowly. </p> </body> </section> <section> <title>Kernel features</title> <body> <p> 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). </p> <p> 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. </p> </body> </section> <section> <title>Ready?</title> <body> <p> 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. </p> <p> 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! </p> </body> </section> </chapter> <chapter> <title>Common problems and areas of confusion</title> <section> <title>SATA disks are SCSI</title> <body> <p> Most modern desktop systems ship with storage devices (hard disk and CD/DVD drives) on a <uri link="http://en.wikipedia.org/wiki/SATA";>Serial ATA</uri> bus, rather than the older <uri link="http://en.wikipedia.org/wiki/Parallel_ATA";>IDE</uri> (ribbon cable) bus type. </p> <p> SATA support in Linux is implemented in a layer referred to as <e>libata</e>, 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.) <c>/dev/sda</c> and your SATA CD/DVD drive will be named as (e.g.) <c>/dev/sr0</c>. </p> <p> 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. </p> <pre caption="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 <comment>Select your chipset from the choices listed below the above option</comment> </pre> </body> </section> <section> <title>IDE chipsets and DMA</title> <body> <p> 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. </p> <p> However, IDE is an old technology, and in it's original <e>Programmed Input/Output</e> 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. </p> <p> Unless you're dealing with a pre-1995 system, your IDE controller will also support an alternative transfer mode, known as <e>Direct Memory Access</e> (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. </p> <pre caption="Checking if DMA is enabled on your IDE disk"> # <i>hdparm -d /dev/hda</i> /dev/hda: using_dma = 0 (off) </pre> <p> To enable DMA on your IDE devices, you simply need to enable the configuration option for your IDE controller. </p> <pre caption="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 [*] Generic PCI bus-master DMA support [*] Use PCI DMA by default when available <comment>Select your chipset from the choices listed below the above option</comment> </pre> </body> </section> <section> <title>USB Host Controllers</title> <body> <p> <uri link="http://en.wikipedia.org/wiki/USB";>USB</uri> 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 <e>host controller devices</e> (HCDs) implemented on the host computer do vary a little. There are 3 main types: </p> <ul> <li> <c>UHCI</c> is the Universal Host Controller Interface. It supports USB 1.1, and is usually found on motherboards based on a VIA or Intel chipset. </li> <li> <c>OHCI</c> is the Open Host Controller Interface. It supports USB 1.1 and is usually found on motherboards based on an Nvidia or SiS chipset. </li> <li> <c>EHCI</c> 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. </li> </ul> <p> 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? </p> <p> 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. </p> <p> A neat <c>lspci</c> trick (from the <c>sys-apps/pciutils</c> 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: </p> <pre caption="Using lspci to detect HCD type"> # <i>lspci -v | grep HCI</i> 00:02.0 USB Controller: nVidia Corporation CK804 USB Controller (rev a2) (prog-if 10 <i>[OHCI]</i>) 00:02.1 USB Controller: nVidia Corporation CK804 USB Controller (rev a3) (prog-if 20 <i>[EHCI]</i>) 01:0b.0 FireWire (IEEE 1394): Agere Systems FW323 (rev 61) (prog-if 10 [OHCI]) </pre> <pre caption="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 <comment>Select the HCDs present on your system, or all 3 if you are unsure.</comment> </pre> </body> </section> <section> <title>Multiprocessor, Hyper-Threading and Dual Core systems</title> <body> <p> Many computer systems are based on multiple processors, but not always in immediately obvious ways. </p> <ul> <li> Many of Intel's CPUs support a technology which they call <uri link="http://en.wikipedia.org/wiki/Hyperthreading";>hyper-threading</uri>, which is where the CPU is actually viewed by the system as two <e>logical</e> processors. </li> <li> Some of the most recent Intel/AMD CPUs actually consist of multiple physical processors inside a single package, these are known as <uri link="http://en.wikipedia.org/wiki/Dual_core";>dual core</uri> processors. </li> <li> Some high-end computer systems actually have multiple physical processors installed on specialised motherboards to provide a significant performance increase over a <e>uniprocessor</e> system. You'll probably know if you have such a system, since they aren't cheap. </li> </ul> <p> In all of these cases, you need to select the appropriate kernel options to obtain optimum performance from these setups. </p> <pre caption="Configuration for multi-processing"> Processor type and features ---> [*] Symmetric multi-processing support <comment>Select the above option if you are on a multi-processor system (of any type)</comment> [*] SMT (Hyperthreading) scheduler support <comment>Select the above option if you are on an Intel Hyper-Threading CPU</comment> [*] Multi-core scheduler support (NEW) <comment>Select the above option if your CPU is dual core</comment> </pre> </body> </section> <section> <title>x86 High Memory support</title> <body> <p> 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. </p> <note> This limitation is specific to the x86 (IA32) architecture. Other architectures naturally support large amounts of memory, with no configuration tweaks required. </note> <p> 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! </p> <pre caption="Enabling high memory support on x86"> Processor type and features ---> High Memory Support ---> (X) 4GB ( ) 64GB <comment>Choose the 4GB option, unless your system has more than 4GB of RAM.</comment> </pre> </body> </section> </chapter> <chapter> <title>Other kernel configuration documentation</title> <section> <body> <p> 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. </p> <p> 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. </p> <ul> <li> The <uri link="/doc/en/alsa-guide.xml">ALSA Guide</uri> 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. </li> <li> The <uri link="/doc/en/bluetooth-guide.xml">Bluetooth Guide</uri> details the options you need in order to use bluetooth devices on your system. </li> <li> The <uri link="/doc/en/ipv6.xml">IPv6 Router Guide</uri> describes how to configure your kernel for routing using the next generation network addressing scheme. </li> <li> If you will be using the closed-source nVidia graphics drivers for improved 3D graphics performance, the <uri link="/doc/en/nvidia-guide.xml">nVidia Guide</uri> lists the options that should and should not be selected on such a system. </li> <li> Amongst other things, the <uri link="/doc/en/power-management-guide.xml">Power Management Guide</uri> explains how to configure your kernel for CPU frequency scaling, and for suspend and hibernate functionality. </li> <li> If you are running a PowerPC system, the <uri link="/doc/en/gentoo-ppc-faq.xml">PPC FAQ</uri> has a few sections about kernel configuration. </li> <li> The <uri link="/doc/en/printing-howto.xml">Printing HOWTO</uri> lists the kernel options needed to support printing in Linux. </li> <li> The <uri link="/doc/en/usb-guide.xml">USB Guide</uri> details the configuration required to use common USB devices such as keyboards/mice, storage devices, and printers. </li> </ul> </body> </section> </chapter> <chapter> <title>Troubleshooting</title> <section> <title>Configuration changes do not take effect</title> <body> <p> 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. </p> <p> The process of compiling and installing kernels is outside the scope of this document, you should refer to the <uri link="/doc/en/kernel-upgrade.xml">Kernel Upgrade Guide</uri> 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! </p> <p> It is possible to verify if 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: </p> <pre caption="Verifying you are booted from your modified kernel"> # <i>uname -v</i> #4 SMP PREEMPT Sat Jul 15 08:49:26 BST 2006 <comment>The above command displays the date and time that the kernel you are currently booted from was compiled.</comment> # <i>ls -l /usr/src/linux/arch/i386/boot/bzImage</i> -rw-r--r-- 1 dsd users 1504118 Jul 15 08:49 /usr/src/linux/arch/i386/boot/bzImage <comment>The above command displays the date and time that the kernel image on your hard disk was last compiled.</comment> </pre> <p> 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! </p> </body> </section> <section> <title>Modules do not get loaded automatically</title> <body> <p> 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. </p> <p> 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. </p> <p> 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. </p> <p> 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. </p> <p> 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. </p> </body> </section> </chapter> </guide> -- [email protected] mailing list
