Gentoo Archives: gentoo-doc-cvs

From: Lukasz Damentko <rane@×××××××××××.org>
To: gentoo-doc-cvs@l.g.o
Subject: [gentoo-doc-cvs] cvs commit: kernel-config.xml
Date: Sun, 16 Jul 2006 22:35:10
1 rane 06/07/16 22:34:47
3 Added: kernel-config.xml
4 Log:
5 #94955, now we have kernel configuration documentation
7 Revision Changes Path
8 1.1 xml/htdocs/doc/en/kernel-config.xml
10 file :
11 plain:
13 Index: kernel-config.xml
14 ===================================================================
15 <?xml version="1.0" encoding="UTF-8"?>
16 <!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/kernel-config.xml,v 1.1 2006/07/16 22:34:46 rane Exp $ -->
17 <!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
19 <guide link="/doc/en/kernel-config.xml">
20 <title>Gentoo Linux Kernel Configuration Guide</title>
22 <author title="Author">
23 <mail link="dsd@g.o">Daniel Drake</mail>
24 </author>
25 <author title="Contributor">
26 <mail link="curtis119@g.o">Curtis Napier</mail>
27 </author>
28 <author title="Contributor">
29 <mail link="jdr@××××××.net">Justin Robinson</mail>
30 </author>
31 <author title="Contributor">
32 <mail link="rane@g.o">Łukasz Damentko</mail>
33 </author>
34 <author title="Editor">
35 <mail link="smithj@g.o">Jonathan Smith</mail>
36 </author>
38 <abstract>
39 This document aims to introduce the concepts of manual kernel configuration,
40 and to detail some of the most common configuration pitfalls.
41 </abstract>
43 <!-- The content of this document is licensed under the CC-BY-SA license -->
44 <!-- See -->
45 <license/>
47 <version>1.0</version>
48 <date>2006-07-16</date>
50 <chapter>
51 <title>Introduction</title>
52 <section>
53 <body>
55 <p>
56 Gentoo provides two ways for you to handle kernel installation and upgrade:
57 <e>automatic</e> (genkernel), and <e>manual</e>. Although the automatic method
58 can be regarded as <e>easier</e> for the user, there are a number of reasons
59 why a large proportion of Gentoo users choose to configure their kernel
60 manually: greater flexibility, smaller kernel, shorter compilation time,
61 learning experience, severe boredom, etc.
62 </p>
64 <p>
65 This guide does not cover the automatic method (genkernel). If you'd prefer to
66 use genkernel to compile and install your kernel, head over to the <uri
67 link="/doc/en/genkernel.xml">Genkernel documentation</uri>.
68 </p>
70 <p>
71 This guide does not attempt to document the manual configuration process from
72 start to finish -- the configuration process relies upon a large degree of
73 common sense, and a relatively high level of technical knowledge about your
74 system. Instead, this document will introduce the concepts of manual
75 configuration and detail the most common pitfalls which users face.
76 </p>
78 <p>
79 This document is written with recent kernels in mind, for the most common
80 computer architectures. Some details may differ for older kernels or more
81 exotic architectures, but much of the content will still be relevant.
82 </p>
84 <p>
85 At this point, you are assumed to have Linux kernel sources unpacked on your
86 hard disk (usually somewhere under <c>/usr/src</c>), and you are expected to
87 know how to enter the <c>menuconfig</c> configuration utility and move through
88 the menu system. If you are not already at this stage, we do have other
89 documentation available to help you.
90 </p>
92 <ul>
93 <li>
94 The <uri link="/doc/en/gentoo-kernel.xml">Kernel Guide</uri> lists the
95 various kernel source packages we have available
96 </li>
97 <li>
98 The <uri link="/doc/en/kernel-upgrade.xml">Kernel Upgrade Guide</uri>
99 explains how to upgrade your kernel or switch from one to another.
100 </li>
101 <li>
102 The <uri link="/doc/en/handbook/index.xml">Gentoo Handbook</uri> covers
103 some aspects of kernel installation too.
104 </li>
105 </ul>
107 </body>
108 </section>
109 </chapter>
111 <chapter>
112 <title>Configuration Concepts</title>
113 <section>
114 <title>The basics</title>
115 <body>
117 <p>
118 The general process is actually rather simple: you are presented with a series
119 of options, categorised into individual menus and sub-menus, and you select the
120 hardware support and kernel features relevant for your system.
121 </p>
123 <p>
124 The kernel includes a <e>default configuration</e>, which is presented to you
125 the first time you run menuconfig on a particular set of sources. The defaults
126 are generally broad and sensible, which means that the majority of users will
127 only have to make a small number of changes to the base config. If you decide
128 to disable an option that was enabled by default, make sure you have a
129 relatively good understanding of exactly what that option does, and the
130 consequences of disabling it.
131 </p>
133 <p>
134 If this is your first time configuring a Linux kernel, you should probably aim
135 to be conservative: don't be too adventurous, and aim to make as few
136 modifications to the default settings as possible. At the same time, keep in
137 mind that there are certain parts of the configuration which you absolutely
138 must customise to your system setup to actually allow it to boot!
139 </p>
141 </body>
142 </section>
143 <section>
144 <title>Built-in vs modular</title>
145 <body>
147 <p>
148 Most configuration options are <e>tristate</e>: they can be either not built at
149 all, built directly into your kernel (Y), or built as a module (M). Modules are
150 stored externally on the filesystem, whereas built-in items are built directly
151 into the kernel image itself.
152 </p>
154 <p>
155 There is an important difference between built-in and modular: with a few
156 exceptions, the kernel makes no attempt whatsoever to load any external modules
157 when you might need them (it is left up to the user). While certain other parts
158 of the system may have load-on-demand facilities, and there are some automatic
159 module loading utilities available, it is recommended that you build hardware
160 support and kernel features directly into the kernel. The kernel can then
161 ensure the functionality and hardware support is available whenever it needs
162 it.
163 </p>
165 <p>
166 Of course, for some parts of the configuration, built-in is an absolute
167 requirement. For example, if your root partition was an <c>ext2</c> filesystem,
168 your system would not boot if ext2 was built as a module (the system would have
169 to look on the root partition to find the ext2 module, but it cannot look on
170 the root partition unless it already has ext2 support loaded!).
171 </p>
173 </body>
174 </section>
175 <section>
176 <title>Hardware support</title>
177 <body>
179 <p>
180 Beyond detecting the <e>architecture type</e> of your system, the configuration
181 utility makes no attempt to identify which hardware is actually present in your
182 system. While there are default settings for some hardware support, you almost
183 certainly need to find and select the configuration options relevant to your
184 system's hardware configuration.
185 </p>
187 <p>
188 This simply requires knowledge of the components inside and connected to your
189 computer, or for you to identify these components. For most internal
190 components, you need to identify the <e>chipset</e> used on each one, rather
191 than the retail product name.
192 </p>
194 <p>
195 There are some utilities available that will help you. <c>lspci</c> (part of
196 the <c>sys-apps/pciutils</c> package) will identify your PCI-based and
197 AGP-based hardware, and this includes components built onto the motherboard
198 itself. <c>lsusb</c> (from the <c>sys-apps/usbutils</c>) package will identify
199 devices connected to USB ports.
200 </p>
202 <p>
203 The situation is somewhat confused by varying degrees of standardisation in the
204 hardware world. Unless you really deviate from the defaults, your IDE hard
205 disks will "just work", as will your PS/2 or USB keyboard and mouse. You'll get
206 basic VGA display support. However, some devices such as ethernet adapters are
207 barely standardised at all, so you'll have to identify the ethernet chipset and
208 select the appropriate hardware support for your specific card to get any
209 network access at all.
210 </p>
212 <p>
213 In addition, while some things just-about-work with the default settings, you
214 may need to select more specialised options to get the full potential from your
215 system. For example, if you do not enable the support for the appropriate IDE
216 chipset, your IDE hard disks will run <e>very</e> slowly.
217 </p>
219 </body>
220 </section>
221 <section>
222 <title>Kernel features</title>
223 <body>
225 <p>
226 As well as hardware support, you also need to think in terms of the software
227 features you require in your kernel. One important example of such a feature is
228 filesystem support: you need to select support for the filesystems in use on
229 your hard disk, as well as any filesystems you might be using on external
230 storage (e.g. VFAT on USB flash disks).
231 </p>
233 <p>
234 Another common example is advanced network functionality. If you want to do
235 some kind of routing or firewalling, you need to ensure the relevant
236 configuration items are included in your kernel config.
237 </p>
239 </body>
240 </section>
241 <section>
242 <title>Ready?</title>
243 <body>
245 <p>
246 Now that we've introduced the concepts, you should be able to start identifying
247 your hardware and browsing through the configuration menus, selecting the
248 required kernel options for your system.
249 </p>
251 <p>
252 The rest of this page aims to clear up common areas of confusion, and provide
253 advice for how to avoid common problems which users often run into. Good luck!
254 </p>
256 </body>
257 </section>
258 </chapter>
260 <chapter>
261 <title>Common problems and areas of confusion</title>
263 <section>
264 <title>SATA disks are SCSI</title>
265 <body>
267 <p>
268 Most modern desktop systems ship with storage devices (hard disk and CD/DVD
269 drives) on a <uri link="">Serial ATA</uri>
270 bus, rather than the older <uri
271 link="">IDE</uri> (ribbon cable) bus
272 type.
273 </p>
275 <p>
276 SATA support in Linux is implemented in a layer referred to as <e>libata</e>,
277 which sits below the SCSI subsystem. For this reason, SATA drivers are found in
278 the SCSI driver section of the configuration. Additionally, your storage
279 devices will be treated as SCSI devices, which means SCSI disk/cdrom support is
280 required too. Your SATA hard disk will be named as (e.g.) <c>/dev/sda</c> and
281 your SATA CD/DVD drive will be named as (e.g.) <c>/dev/sr0</c>.
282 </p>
284 <p>
285 Although the majority of these drivers are for SATA controllers, libata was not
286 designed to be SATA-specific. All common IDE drivers will also be ported to
287 libata in the near future, and at this point, the above considerations will
288 also apply for IDE users.
289 </p>
291 <pre caption="Configuration options for libata">
292 Device Drivers ---&gt;
293 SCSI device support ---&gt;
294 &lt;*&gt; SCSI device support
295 &lt;*&gt; SCSI disk support
296 &lt;*&gt; SCSI CDROM support
298 SCSI low-level drivers ---&gt;
299 &lt;*&gt; Serial ATA (SATA) support
300 <comment>Select your chipset from the choices listed below the above option</comment>
301 </pre>
303 </body>
304 </section>
305 <section>
306 <title>IDE chipsets and DMA</title>
307 <body>
309 <p>
310 Despite the introduction of SATA, IDE devices are still very common and
311 depended upon by many. IDE is a fairly generic technology, and as such, Linux
312 supports almost all IDE controllers out-of-the-box without any
313 controller-specific options selected.
314 </p>
316 <p>
317 However, IDE is an old technology, and in it's original <e>Programmed
318 Input/Output</e> incarnation, it is unable to provide the transfer rates
319 required for speedy access to modern storage devices. The generic IDE driver is
320 limited to these PIO transfer modes, which result in slow data transfer rates,
321 and significantly high CPU usage while data is being transferred to/from disk.
322 </p>
324 <p>
325 Unless you're dealing with a pre-1995 system, your IDE controller will also
326 support an alternative transfer mode, known as <e>Direct Memory Access</e>
327 (DMA). DMA is much much faster, and CPU utilisation is barely affected while
328 data transfers are taking place. If you are suffering from really poor general
329 system performance and you are using an IDE disk, chances are that DMA is not
330 being used.
331 </p>
333 <pre caption="Checking if DMA is enabled on your IDE disk">
334 # <i>hdparm -d /dev/hda</i>
336 /dev/hda:
337 using_dma = 0 (off)
338 </pre>
340 <p>
341 To enable DMA on your IDE devices, you simply need to enable the configuration
342 option for your IDE controller.
343 </p>
345 <pre caption="Configuration options for IDE controllers">
346 Device Drivers ---&gt;
347 ATA/ATAPI/MFM/RLL support ---&gt;
348 &lt;*&gt; ATA/ATAPI/MFM/RLL support
349 &lt;*&gt; Enhanced IDE/MFM/RLL disk/cdrom/tape/floppy support
350 [*] PCI IDE chipset support
351 [*] Generic PCI bus-master DMA support
352 [*] Use PCI DMA by default when available
353 <comment>Select your chipset from the choices listed below the above option</comment>
354 </pre>
356 </body>
357 </section>
358 <section>
359 <title>USB Host Controllers</title>
360 <body>
362 <p>
363 <uri link="">USB</uri> is a widely adopted bus
364 for connecting external peripherals to your computer. One of the reasons behind
365 the success of USB is that it is a standardised protocol, however the USB
366 <e>host controller devices</e> (HCDs) implemented on the host computer do vary
367 a little. There are 3 main types:
368 </p>
370 <ul>
371 <li>
372 <c>UHCI</c> is the Universal Host Controller Interface. It supports USB
373 1.1, and is usually found on motherboards based on a VIA or Intel chipset.
374 </li>
375 <li>
376 <c>OHCI</c> is the Open Host Controller Interface. It supports USB 1.1 and
377 is usually found on motherboards based on an Nvidia or SiS chipset.
378 </li>
379 <li>
380 <c>EHCI</c> is the Extended Host Controller Interface. It is the only
381 common host controller to support USB 2.0, and can typically be found on
382 any computer that supports USB 2.0.
383 </li>
384 </ul>
386 <p>
387 Most systems will come with two of the above interface types: EHCI (USB 2.0),
388 plus either UHCI or OHCI (USB 1.1). It is important that you select both types
389 present on your system. While all USB 2.0 devices are backwards compatible with
390 USB 1.1, a large proportion of USB devices (even the ones being manufactured
391 today) are based on the USB 1.1 interface - why would a USB mouse need more
392 than 1.5mbit/sec?
393 </p>
395 <p>
396 If you do not select the relevant options corresponding to the USB HCD types
397 present on your system, you may experience 'dead' USB ports: you plug a device
398 in, but it does not get power or respond in any way.
399 </p>
401 <p>
402 A neat <c>lspci</c> trick (from the <c>sys-apps/pciutils</c> package) makes it
403 relatively easy to detect which HCDs are present in your system. Ignoring the
404 FireWire controller which was also matched, it is easy to spot that my system
405 requires OHCI and EHCI support:
406 </p>
408 <pre caption="Using lspci to detect HCD type">
409 # <i>lspci -v | grep HCI</i>
410 00:02.0 USB Controller: nVidia Corporation CK804 USB Controller (rev a2) (prog-if 10 <i>[OHCI]</i>)
411 00:02.1 USB Controller: nVidia Corporation CK804 USB Controller (rev a3) (prog-if 20 <i>[EHCI]</i>)
412 01:0b.0 FireWire (IEEE 1394): Agere Systems FW323 (rev 61) (prog-if 10 [OHCI])
413 </pre>
415 <pre caption="Configuration for USB HCDs">
416 Device Drivers ---&gt;
417 USB support ---&gt;
418 &lt;*&gt; Support for Host-side USB
419 --- USB Host Controller Drivers
420 &lt;*&gt; EHCI HCD (USB 2.0) support
421 &lt;*&gt; OHCI HCD support
422 &lt;*&gt; UHCI HCD (most Intel and VIA) support
423 <comment>Select the HCDs present on your system, or all 3 if you are unsure.</comment>
424 </pre>
426 </body>
427 </section>
428 <section>
429 <title>Multiprocessor, Hyper-Threading and Dual Core systems</title>
430 <body>
432 <p>
433 Many computer systems are based on multiple processors, but not always in
434 immediately obvious ways.
435 </p>
437 <ul>
438 <li>
439 Many of Intel's CPUs support a technology which they call <uri
440 link="">hyper-threading</uri>,
441 which is where the CPU is actually viewed by the system as two
442 <e>logical</e> processors.
443 </li>
444 <li>
445 Some of the most recent Intel/AMD CPUs actually consist of multiple
446 physical processors inside a single package, these are known as <uri
447 link="">dual core</uri> processors.
448 </li>
449 <li>
450 Some high-end computer systems actually have multiple physical processors
451 installed on specialised motherboards to provide a significant performance
452 increase over a <e>uniprocessor</e> system. You'll probably know if you
453 have such a system, since they aren't cheap.
454 </li>
455 </ul>
457 <p>
458 In all of these cases, you need to select the appropriate kernel options to
459 obtain optimum performance from these setups.
460 </p>
462 <pre caption="Configuration for multi-processing">
463 Processor type and features ---&gt;
464 [*] Symmetric multi-processing support
465 <comment>Select the above option if you are on a multi-processor system (of any type)</comment>
466 [*] SMT (Hyperthreading) scheduler support
467 <comment>Select the above option if you are on an Intel Hyper-Threading CPU</comment>
468 [*] Multi-core scheduler support (NEW)
469 <comment>Select the above option if your CPU is dual core</comment>
470 </pre>
472 </body>
473 </section>
474 <section>
475 <title>x86 High Memory support</title>
476 <body>
478 <p>
479 Due to limitations in the 32-bit address space of the x86 architecture, a
480 kernel with default configuration can only support up to 896mb RAM. If your
481 system has more memory, only the first 896mb will be visible, unless you enable
482 high memory support.
483 </p>
485 <note>
486 This limitation is specific to the x86 (IA32) architecture. Other architectures
487 naturally support large amounts of memory, with no configuration tweaks
488 required.
489 </note>
491 <p>
492 High memory support is not enabled by default, because it introduces a small
493 system overhead. Do not be distracted by this, the overhead is insignificant
494 when compared to the performance increase of having more memory available!
495 </p>
497 <pre caption="Enabling high memory support on x86">
498 Processor type and features ---&gt;
499 High Memory Support ---&gt;
500 (X) 4GB
501 ( ) 64GB
502 <comment>Choose the 4GB option, unless your system has more than 4GB of RAM.</comment>
503 </pre>
505 </body>
506 </section>
507 </chapter>
509 <chapter>
510 <title>Other kernel configuration documentation</title>
511 <section>
512 <body>
514 <p>
515 So far, we have only discussed general concepts and specific problems related
516 to kernel configuration, without going into any precise details (such details
517 are for you to discover!). However, other parts of the Gentoo documentation
518 collection provide specialised details for the topics at hand.
519 </p>
521 <p>
522 You may find these documents helpful while configuring those specific areas,
523 but if you are new to kernel configuration, don't be too adventurous. Start by
524 getting a basic system up and running, you can always come back later to add
525 support for your audio, printing, etc.
526 </p>
528 <ul>
529 <li>
530 The <uri link="/doc/en/alsa-guide.xml">ALSA Guide</uri> details the
531 configuration options required for sound card support. Note that ALSA is
532 one exception to the suggested scheme of not building things as modules:
533 ALSA is actually much easier to configure when the components are modular.
534 </li>
535 <li>
536 The <uri link="/doc/en/bluetooth-guide.xml">Bluetooth Guide</uri> details
537 the options you need in order to use bluetooth devices on your system.
538 </li>
539 <li>
540 The <uri link="/doc/en/ipv6.xml">IPv6 Router Guide</uri> describes how to
541 configure your kernel for routing using the next generation network
542 addressing scheme.
543 </li>
544 <li>
545 If you will be using the closed-source nVidia graphics drivers for improved
546 3D graphics performance, the <uri link="/doc/en/nvidia-guide.xml">nVidia
547 Guide</uri> lists the options that should and should not be selected on
548 such a system.
549 </li>
550 <li>
551 Amongst other things, the <uri
552 link="/doc/en/power-management-guide.xml">Power Management Guide</uri>
553 explains how to configure your kernel for CPU frequency scaling, and for
554 suspend and hibernate functionality.
555 </li>
556 <li>
557 If you are running a PowerPC system, the <uri
558 link="/doc/en/gentoo-ppc-faq.xml">PPC FAQ</uri> has a few sections about
559 kernel configuration.
560 </li>
561 <li>
562 The <uri link="/doc/en/printing-howto.xml">Printing HOWTO</uri> lists the
563 kernel options needed to support printing in Linux.
564 </li>
565 <li>
566 The <uri link="/doc/en/usb-guide.xml">USB Guide</uri> details the
567 configuration required to use common USB devices such as keyboards/mice,
568 storage devices, and printers.
569 </li>
570 </ul>
572 </body>
573 </section>
574 </chapter>
576 <chapter>
577 <title>Troubleshooting</title>
578 <section>
579 <title>Configuration changes do not take effect</title>
580 <body>
582 <p>
583 It is very common for users to make a configuration change, but then make a
584 small mistake in the process following on from that point. They reboot into a
585 kernel image that is not the one they just reconfigured, observe that whatever
586 problem they were trying to solve is still present, and conclude that the
587 configuration change does not solve the problem.
588 </p>
590 <p>
591 The process of compiling and installing kernels is outside the scope of this
592 document, you should refer to the <uri link="/doc/en/kernel-upgrade.xml">Kernel
593 Upgrade Guide</uri> for general guidance. In short, the process is: configure,
594 compile, mount /boot (if not already mounted), copy new kernel image over,
595 reboot. If you miss out any of those final stages, your changes will not take
596 effect!
597 </p>
599 <p>
600 It is possible to verify if you are booted from matches the kernel compiled on
601 your hard disk by examining the date and time of compilation. Assuming your
602 architecture is x86 and your kernel sources are installed at /usr/src/linux:
603 </p>
605 <pre caption="Verifying you are booted from your modified kernel">
606 # <i>uname -v</i>
607 #4 SMP PREEMPT Sat Jul 15 08:49:26 BST 2006
608 <comment>The above command displays the date and time that the kernel you are currently booted from was compiled.</comment>
610 # <i>ls -l /usr/src/linux/arch/i386/boot/bzImage</i>
611 -rw-r--r-- 1 dsd users 1504118 Jul 15 08:49 /usr/src/linux/arch/i386/boot/bzImage
612 <comment>The above command displays the date and time that the kernel image on your hard disk was last compiled.</comment>
613 </pre>
615 <p>
616 If the two times from the above commands differ by more than 2 minutes, it
617 indicates that you have made a mistake during kernel reinstallation and you are
618 not booted from the kernel image that you thought you were!
619 </p>
621 </body>
622 </section>
623 <section>
624 <title>Modules do not get loaded automatically</title>
625 <body>
627 <p>
628 As mentioned earlier in this document, the kernel configuration system hides a
629 large behavioural change when selecting a kernel component as a module (M)
630 rather than built-in (Y). It is worth repeating this again because so many
631 users fall into this trap.
632 </p>
634 <p>
635 When you select a component as built-in, the code is built into the kernel
636 image (bzImage). When the kernel needs to use that component, it can initialise
637 and load it automatically, without any user intervention.
638 </p>
640 <p>
641 When you select a component as a module, the code is built into a kernel module
642 file and installed on your filesystem. In general, when the kernel needs to use
643 that component, it can't! With some exceptions, the kernel makes no effort to
644 actually load these modules - this task is left up to the user.
645 </p>
647 <p>
648 So, if you build support for your network card as a module, and you then find
649 that you cannot access your network, it is probably because the module is not
650 loaded - you must either do this manually or configure your system to autoload
651 it at boot time.
652 </p>
654 <p>
655 Unless you have reasons to do otherwise, save yourself some time by building
656 these components directly into the kernel image, so that the kernel can
657 automatically set these things up for you.
658 </p>
660 </body>
661 </section>
662 </chapter>
663 </guide>
667 --
668 gentoo-doc-cvs@g.o mailing list