chapter08/kernel.xml

   1 <?xml version="1.0" encoding="ISO-8859-1"?>
   2 <!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
   3   "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
   4   <!ENTITY % general-entities SYSTEM "../general.ent">
   5   %general-entities;
   6 ]>
   7
   8 <sect1 id="ch-bootable-kernel" role="wrap">
   9   <?dbhtml filename="kernel.html"?>
  10
  11   <sect1info condition="script">
  12     <productname>linux</productname>
  13     <productnumber>&linux-version;</productnumber>
  14     <address>&linux-url;</address>
  15   </sect1info>
  16
  17   <title>Linux-&linux-version;</title>
  18
  19   <indexterm zone="ch-bootable-kernel">
  20     <primary sortas="a-Linux">Linux</primary>
  21   </indexterm>
  22
  23   <sect2 role="package">
  24     <title/>
  25
  26     <para>The Linux package contains the Linux kernel.</para>
  27
  28     <segmentedlist>
  29       <segtitle>&buildtime;</segtitle>
  30       <segtitle>&diskspace;</segtitle>
  31
  32       <seglistitem>
  33         <seg>&linux-ch8-sbu;</seg>
  34         <seg>&linux-ch8-du;</seg>
  35       </seglistitem>
  36     </segmentedlist>
  37
  38   </sect2>
  39
  40   <sect2 role="installation">
  41     <title>Installation of the kernel</title>
  42
  43     <para>Building the kernel involves a few steps&mdash;configuration,
  44     compilation, and installation. Read the <filename>README</filename> file
  45     in the kernel source tree for alternative methods to the way this book
  46     configures the kernel.</para>
  47
  48     <para>Prepare for compilation by running the following command:</para>
  49
  50 <screen><userinput remap="pre">make mrproper</userinput></screen>
  51
  52     <para>This ensures that the kernel tree is absolutely clean. The
  53     kernel team recommends that this command be issued prior to each
  54     kernel compilation. Do not rely on the source tree being clean after
  55     un-tarring.</para>
  56
  57     <!-- Support for compiling a keymap into the kernel is deliberately removed -->
  58
  59     <para>Configure the kernel via a menu-driven interface. For general
  60     information on kernel configuration see <ulink
  61     url="&hints-root;kernel-configuration.txt"/>.  BLFS has some information
  62     regarding particular kernel configuration requirements of packages outside
  63     of LFS at <ulink
  64     url="&blfs-book;longindex.html#kernel-config-index"/>.  Additional
  65     information about configuring and building the kernel can be found at
  66     <ulink url="http://www.kroah.com/lkn/"/> </para>
  67
  68     <note>
  69
  70       <para>A good starting place for setting up the kernel configuration is to
  71       run <command>make defconfig</command>. This will set the base
  72       configuration to a good state that takes your current system architecture
  73       into account.</para>
  74
  75       <para>Be sure to enable or disable following features or the system might
  76       not work correctly or boot at all:</para>
  77
  78       <screen role="nodump" revision="sysv">
  79 Device Drivers  ---&gt;
  80   Generic Driver Options  ---&gt;
  81    [ ] Support for uevent helper [CONFIG_UEVENT_HELPER]
  82    [*] Maintain a devtmpfs filesystem to mount at /dev [CONFIG_DEVTMPFS]</screen>
  83
  84       <screen role="nodump" revision="systemd">
  85 General setup -->
  86    [ ] Enable deprecated sysfs features to support old userspace tools [CONFIG_SYSFS_DEPRECATED]
  87    [ ] Enable deprecated sysfs features by default [CONFIG_SYSFS_DEPRECATED_V2]
  88    [*] open by fhandle syscalls [CONFIG_FHANDLE]
  89    [ ] Auditing support [CONFIG_AUDIT]
  90    [*] Control Group support [CONFIG_CGROUPS]
  91 Processor type and features  ---&gt;
  92    [*] Enable seccomp to safely compute untrusted bytecode [CONFIG_SECCOMP]
  93 Networking support  ---&gt;
  94   Networking options  ---&gt;
  95    &lt;*&gt; The IPv6 protocol [CONFIG_IPV6]
  96 Device Drivers  ---&gt;
  97   Generic Driver Options  ---&gt;
  98    [ ] Support for uevent helper [CONFIG_UEVENT_HELPER]
  99    [*] Maintain a devtmpfs filesystem to mount at /dev [CONFIG_DEVTMPFS]
 100    [ ] Fallback user-helper invocation for firmware loading [CONFIG_FW_LOADER_USER_HELPER]
 101 Firmware Drivers  ---&gt;
 102    [*] Export DMI identification via sysfs to userspace [CONFIG_DMIID]
 103 File systems  ---&gt;
 104    [*] Inotify support for userspace [CONFIG_INOTIFY_USER]
 105    &lt;*&gt; Kernel automounter version 4 support (also supports v3) [CONFIG_AUTOFS4_FS]
 106   Pseudo filesystems  ---&gt;
 107    [*] Tmpfs POSIX Access Control Lists [CONFIG_TMPFS_POSIX_ACL]
 108    [*] Tmpfs extended attributes [CONFIG_TMPFS_XATTR]</screen>
 109
 110     </note>
 111
 112     <note revision="systemd">
 113       <para>While "The IPv6 Protocol" is not strictly
 114       required, it is highly recommended by the systemd developers.</para>
 115     </note>
 116
 117     <para revision="sysv">There are several other options that may be desired
 118     depending on the requirements for the system. For a list of options needed
 119     for BLFS packages, see the <ulink
 120     url="&lfs-root;blfs/view/&short-version;/longindex.html#kernel-config-index">BLFS
 121     Index of Kernel Settings</ulink>
 122     (&lfs-root;blfs/view/&short-version;/longindex.html#kernel-config-index).</para>
 123
 124     <variablelist>
 125       <title>The rationale for the above configuration items:</title>
 126
 127       <varlistentry>
 128         <term><parameter>Support for uevent helper</parameter></term>
 129         <listitem>
 130           <para>Having this option set may interfere with device
 131           management when using Udev/Eudev. </para>
 132         </listitem>
 133       </varlistentry>
 134
 135       <varlistentry>
 136         <term><parameter>Maintain a devtmpfs</parameter></term>
 137         <listitem>
 138           <para>This will create automated device nodes which are populated by the
 139           kernel, even without Udev running.  Udev then runs on top of this,
 140           managing permissions and adding symlinks.  This configuration
 141           item is required for all users of Udev/Eudev.</para>
 142         </listitem>
 143       </varlistentry>
 144
 145     </variablelist>
 146
 147 <screen role="nodump"><userinput>make menuconfig</userinput></screen>
 148
 149     <variablelist>
 150       <title>The meaning of optional make environment variables:</title>
 151
 152       <varlistentry>
 153         <term><parameter>LANG=&lt;host_LANG_value&gt; LC_ALL=</parameter></term>
 154         <listitem>
 155           <para>This establishes the locale setting to the one used on the
 156           host.  This may be needed for a proper menuconfig ncurses interface
 157           line drawing on a UTF-8 linux text console.</para>
 158
 159           <para>If used, be sure to replace
 160           <replaceable>&lt;host_LANG_value&gt;</replaceable> by the value of
 161           the <envar>$LANG</envar> variable from your host.  You can
 162           alternatively use instead the host's value of <envar>$LC_ALL</envar>
 163           or <envar>$LC_CTYPE</envar>.</para>
 164         </listitem>
 165       </varlistentry>
 166
 167     </variablelist>
 168
 169     <para>Alternatively, <command>make oldconfig</command> may be more
 170     appropriate in some situations. See the <filename>README</filename>
 171     file for more information.</para>
 172
 173     <para>If desired, skip kernel configuration by copying the kernel
 174     config file, <filename>.config</filename>, from the host system
 175     (assuming it is available) to the unpacked <filename
 176     class="directory">linux-&linux-version;</filename> directory. However,
 177     we do not recommend this option. It is often better to explore all the
 178     configuration menus and create the kernel configuration from
 179     scratch.</para>
 180
 181     <para>Compile the kernel image and modules:</para>
 182
 183 <screen><userinput remap="make">make</userinput></screen>
 184
 185     <para>If using kernel modules, module configuration in <filename
 186     class="directory">/etc/modprobe.d</filename> may be required.
 187     Information pertaining to modules and kernel configuration is
 188     located in <xref linkend="ch-scripts-udev"/> and in the kernel
 189     documentation in the <filename
 190     class="directory">linux-&linux-version;/Documentation</filename> directory.
 191     Also, <filename>modprobe.d(5)</filename> may be of interest.</para>
 192
 193     <para>Install the modules, if the kernel configuration uses them:</para>
 194
 195 <screen><userinput remap="install">make modules_install</userinput></screen>
 196
 197     <para>After kernel compilation is complete, additional steps are
 198     required to complete the installation. Some files need to be copied to
 199     the <filename class="directory">/boot</filename> directory.</para>
 200
 201     <caution>
 202       <para>If the host system has a separate /boot partition, the
 203       files copied below should go there. The easiest way to do that
 204       is to bind /boot on the host to /mnt/lfs/boot before proceeding:</para>
 205
 206 <screen role="nodump"><userinput>mount --bind /boot /mnt/lfs/boot</userinput></screen>
 207     </caution>
 208
 209     <para>The path to the kernel image may vary depending on the platform being
 210     used. The filename below can be changed to suit your taste, but the stem of
 211     the filename should be <emphasis>vmlinuz</emphasis> to be compatible with
 212     the automatic setup of the boot process described in the next section.  The
 213     following command assumes an x86 architecture:</para>
 214
 215 <screen revision="sysv"><userinput remap="install">cp -v arch/x86/boot/bzImage /boot/vmlinuz-&linux-version;-lfs-&version;</userinput></screen>
 216
 217 <screen revision="systemd"><userinput remap="install">cp -v arch/x86/boot/bzImage /boot/vmlinuz-&linux-version;-lfs-&versiond;</userinput></screen>
 218
 219     <para><filename>System.map</filename> is a symbol file for the kernel.
 220     It maps the function entry points of every function in the kernel API,
 221     as well as the addresses of the kernel data structures for the running
 222     kernel.  It is used as a resource when investigating kernel problems.
 223     Issue the following command to install the map file:</para>
 224
 225 <screen><userinput remap="install">cp -v System.map /boot/System.map-&linux-version;</userinput></screen>
 226
 227     <para>The kernel configuration file <filename>.config</filename>
 228     produced by the <command>make menuconfig</command> step
 229     above contains all the configuration selections for the kernel
 230     that was just compiled. It is a good idea to keep this file for future
 231     reference:</para>
 232
 233 <screen><userinput remap="install">cp -v .config /boot/config-&linux-version;</userinput></screen>
 234
 235     <para>Install the documentation for the Linux kernel:</para>
 236
 237 <screen><userinput remap="install">install -d /usr/share/doc/linux-&linux-version;
 238 cp -r Documentation/* /usr/share/doc/linux-&linux-version;</userinput></screen>
 239
 240     <para>It is important to note that the files in the kernel source
 241     directory are not owned by <emphasis>root</emphasis>. Whenever a
 242     package is unpacked as user <emphasis>root</emphasis> (like we did
 243     inside chroot), the files have the user and group IDs of whatever
 244     they were on the packager's computer. This is usually not a problem
 245     for any other package to be installed because the source tree is
 246     removed after the installation. However, the Linux source tree is
 247     often retained for a long time.  Because of this, there is a chance
 248     that whatever user ID the packager used will be assigned to somebody
 249     on the machine. That person would then have write access to the kernel
 250     source.</para>
 251
 252     <note>
 253       <para>In many cases, the configuration of the kernel will need to be
 254       updated for packages that will be installed later in BLFS.  Unlike
 255       other packages, it is not necessary to remove the kernel source tree
 256       after the newly built kernel is installed.</para>
 257
 258       <para>If the kernel source tree is going to be retained, run
 259       <command>chown -R 0:0</command> on the <filename
 260       class="directory">linux-&linux-version;</filename> directory to ensure
 261       all files are owned by user <emphasis>root</emphasis>.</para>
 262     </note>
 263
 264     <warning>
 265       <para>Some kernel documentation recommends creating a symlink from
 266       <filename class="symlink">/usr/src/linux</filename> pointing to the kernel
 267       source directory.  This is specific to kernels prior to the 2.6 series and
 268       <emphasis>must not</emphasis> be created on an LFS system as it can cause
 269       problems for packages you may wish to build once your base LFS system is
 270       complete.</para>
 271     </warning>
 272
 273     <warning>
 274       <para>The headers in the system's <filename
 275       class="directory">include</filename> directory (<filename
 276       class="directory">/usr/include</filename>) should
 277       <emphasis>always</emphasis> be the ones against which Glibc was compiled,
 278       that is, the sanitised headers installed in <xref
 279       linkend="ch-system-linux-headers"/>.  Therefore, they should
 280       <emphasis>never</emphasis> be replaced by either the raw kernel headers
 281       or any other kernel sanitized headers.</para>
 282     </warning>
 283
 284   </sect2>
 285
 286   <sect2 id="conf-modprobe" role="configuration">
 287     <title>Configuring Linux Module Load Order</title>
 288
 289     <indexterm zone="conf-modprobe">
 290       <primary sortas="e-/etc/modprobe.d/usb.conf">/etc/modprobe.d/usb.conf</primary>
 291     </indexterm>
 292
 293     <para>Most of the time Linux modules are loaded automatically, but
 294     sometimes it needs some specific direction.  The program that loads
 295     modules, <command>modprobe</command> or <command>insmod</command>, uses
 296     <filename>/etc/modprobe.d/usb.conf</filename> for this purpose.  This file
 297     needs to be created so that if the USB drivers (ehci_hcd, ohci_hcd and
 298     uhci_hcd) have been built as modules, they will be loaded in the correct
 299     order; ehci_hcd needs to be loaded prior to ohci_hcd and uhci_hcd in order
 300     to avoid a warning being output at boot time.</para>
 301
 302     <para>Create a new file <filename>/etc/modprobe.d/usb.conf</filename> by running
 303     the following:</para>
 304
 305 <screen><userinput>install -v -m755 -d /etc/modprobe.d
 306 cat &gt; /etc/modprobe.d/usb.conf &lt;&lt; "EOF"
 307 <literal># Begin /etc/modprobe.d/usb.conf
 308
 309 install ohci_hcd /sbin/modprobe ehci_hcd ; /sbin/modprobe -i ohci_hcd ; true
 310 install uhci_hcd /sbin/modprobe ehci_hcd ; /sbin/modprobe -i uhci_hcd ; true
 311
 312 # End /etc/modprobe.d/usb.conf</literal>
 313 EOF</userinput></screen>
 314
 315   </sect2>
 316
 317   <sect2 id="contents-kernel" role="content">
 318     <title>Contents of Linux</title>
 319
 320     <segmentedlist>
 321       <segtitle>Installed files</segtitle>
 322       <segtitle>Installed directories</segtitle>
 323
 324       <seglistitem>
 325         <seg>config-&linux-version;,
 326         <phrase revision="sysv">vmlinuz-&linux-version;-lfs-&version;,</phrase>
 327         <phrase revision="systemd">vmlinuz-&linux-version;-lfs-&versiond;,</phrase>
 328         and System.map-&linux-version;</seg>
 329         <seg>/lib/modules, /usr/share/doc/linux-&linux-version;</seg>
 330       </seglistitem>
 331     </segmentedlist>
 332
 333     <variablelist>
 334       <bridgehead renderas="sect3">Short Descriptions</bridgehead>
 335       <?dbfo list-presentation="list"?>
 336       <?dbhtml list-presentation="table"?>
 337
 338       <varlistentry id="config">
 339         <term><filename>config-&linux-version;</filename></term>
 340         <listitem>
 341           <para>Contains all the configuration selections for the kernel</para>
 342           <indexterm zone="ch-bootable-kernel config">
 343             <primary sortas="e-/boot/config">/boot/config-&linux-version;</primary>
 344           </indexterm>
 345         </listitem>
 346       </varlistentry>
 347
 348       <varlistentry id="lfskernel">
 349         <term revision="sysv"><filename>vmlinuz-&linux-version;-lfs-&version;</filename></term>
 350         <term revision="systemd"><filename>vmlinuz-&linux-version;-lfs-&versiond;</filename></term>
 351         <listitem>
 352           <para>The engine of the Linux system. When turning on the computer,
 353           the kernel is the first part of the operating system that gets loaded.
 354           It detects and initializes all components of the computer's hardware,
 355           then makes these components available as a tree of files to the
 356           software and turns a single CPU into a multitasking machine capable
 357           of running scores of programs seemingly at the same time</para>
 358           <indexterm zone="ch-bootable-kernel lfskernel">
 359             <primary sortas="b-lfskernel">lfskernel-&linux-version;</primary>
 360           </indexterm>
 361         </listitem>
 362       </varlistentry>
 363
 364       <varlistentry id="System.map">
 365         <term><filename>System.map-&linux-version;</filename></term>
 366         <listitem>
 367           <para>A list of addresses and symbols; it maps the entry points and
 368           addresses of all the functions and data structures in the
 369           kernel</para>
 370           <indexterm zone="ch-bootable-kernel System.map">
 371             <primary sortas="e-/boot/System.map">/boot/System.map-&linux-version;</primary>
 372           </indexterm>
 373         </listitem>
 374       </varlistentry>
 375
 376     </variablelist>
 377
 378   </sect2>
 379
 380 </sect1>