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     <note>
 125       <para>If your host hardware is using UEFI, then the 'make defconfig'
 126       above should automatically add in some EFI-related kernel options.</para>
 127
 128       <para>In order to allow your LFS kernel to be booted from within your
 129       host's UEFI boot environment, your kernel must have this option
 130       selected:</para>
 131
 132 <screen role="nodump">Processor type and features  ---&gt;
 133    [*]   EFI stub support  [CONFIG_EFI_STUB]</screen>
 134
 135       <para>A fuller description of managing UEFI environments from within LFS
 136       is covered by the lfs-uefi.txt hint at
 137       <ulink
 138         url="http://www.linuxfromscratch.org/hints/downloads/files/lfs-uefi.txt"/>.
 139       </para>
 140     </note>
 141
 142     <variablelist>
 143       <title>The rationale for the above configuration items:</title>
 144
 145       <varlistentry>
 146         <term><parameter>Support for uevent helper</parameter></term>
 147         <listitem>
 148           <para>Having this option set may interfere with device
 149           management when using Udev/Eudev. </para>
 150         </listitem>
 151       </varlistentry>
 152
 153       <varlistentry>
 154         <term><parameter>Maintain a devtmpfs</parameter></term>
 155         <listitem>
 156           <para>This will create automated device nodes which are populated by the
 157           kernel, even without Udev running.  Udev then runs on top of this,
 158           managing permissions and adding symlinks.  This configuration
 159           item is required for all users of Udev/Eudev.</para>
 160         </listitem>
 161       </varlistentry>
 162
 163     </variablelist>
 164
 165 <screen role="nodump"><userinput>make menuconfig</userinput></screen>
 166
 167     <variablelist>
 168       <title>The meaning of optional make environment variables:</title>
 169
 170       <varlistentry>
 171         <term><parameter>LANG=&lt;host_LANG_value&gt; LC_ALL=</parameter></term>
 172         <listitem>
 173           <para>This establishes the locale setting to the one used on the
 174           host.  This may be needed for a proper menuconfig ncurses interface
 175           line drawing on a UTF-8 linux text console.</para>
 176
 177           <para>If used, be sure to replace
 178           <replaceable>&lt;host_LANG_value&gt;</replaceable> by the value of
 179           the <envar>$LANG</envar> variable from your host.  You can
 180           alternatively use instead the host's value of <envar>$LC_ALL</envar>
 181           or <envar>$LC_CTYPE</envar>.</para>
 182         </listitem>
 183       </varlistentry>
 184
 185     </variablelist>
 186
 187     <para>Alternatively, <command>make oldconfig</command> may be more
 188     appropriate in some situations. See the <filename>README</filename>
 189     file for more information.</para>
 190
 191     <para>If desired, skip kernel configuration by copying the kernel
 192     config file, <filename>.config</filename>, from the host system
 193     (assuming it is available) to the unpacked <filename
 194     class="directory">linux-&linux-version;</filename> directory. However,
 195     we do not recommend this option. It is often better to explore all the
 196     configuration menus and create the kernel configuration from
 197     scratch.</para>
 198
 199     <!-- Remove at 4.8.13 -->
 200     <para>Fix an out of memory issue that affects recent kernels:</para>
 201
 202 <screen><userinput remap="pre">sed -e '/sk_sndbuf/s/u32/int/' \
 203     -e '/sk_rcvbuf/s/u32/int/' \
 204     -i.bak net/core/sock.c</userinput></screen>
 205
 206     <para>Compile the kernel image and modules:</para>
 207
 208 <screen><userinput remap="make">make</userinput></screen>
 209
 210     <para>If using kernel modules, module configuration in <filename
 211     class="directory">/etc/modprobe.d</filename> may be required.
 212     Information pertaining to modules and kernel configuration is
 213     located in <xref linkend="ch-scripts-udev"/> and in the kernel
 214     documentation in the <filename
 215     class="directory">linux-&linux-version;/Documentation</filename> directory.
 216     Also, <filename>modprobe.d(5)</filename> may be of interest.</para>
 217
 218     <para>Install the modules, if the kernel configuration uses them:</para>
 219
 220 <screen><userinput remap="install">make modules_install</userinput></screen>
 221
 222     <para>After kernel compilation is complete, additional steps are
 223     required to complete the installation. Some files need to be copied to
 224     the <filename class="directory">/boot</filename> directory.</para>
 225
 226     <caution>
 227       <para>If the host system has a separate /boot partition, the
 228       files copied below should go there. The easiest way to do that
 229       is to bind /boot on the host to /mnt/lfs/boot before proceeding.
 230       As the root user in the <emphasis>host system</emphasis>:</para>
 231
 232 <screen role="nodump"><userinput>mount --bind /boot /mnt/lfs/boot</userinput></screen>
 233     </caution>
 234
 235     <para>The path to the kernel image may vary depending on the platform being
 236     used. The filename below can be changed to suit your taste, but the stem of
 237     the filename should be <emphasis>vmlinuz</emphasis> to be compatible with
 238     the automatic setup of the boot process described in the next section.  The
 239     following command assumes an x86 architecture:</para>
 240
 241 <screen revision="sysv"><userinput remap="install">cp -v arch/x86/boot/bzImage /boot/vmlinuz-&linux-version;-lfs-&version;</userinput></screen>
 242
 243 <screen revision="systemd"><userinput remap="install">cp -v arch/x86/boot/bzImage /boot/vmlinuz-&linux-version;-lfs-&versiond;</userinput></screen>
 244
 245     <para><filename>System.map</filename> is a symbol file for the kernel.
 246     It maps the function entry points of every function in the kernel API,
 247     as well as the addresses of the kernel data structures for the running
 248     kernel.  It is used as a resource when investigating kernel problems.
 249     Issue the following command to install the map file:</para>
 250
 251 <screen><userinput remap="install">cp -v System.map /boot/System.map-&linux-version;</userinput></screen>
 252
 253     <para>The kernel configuration file <filename>.config</filename>
 254     produced by the <command>make menuconfig</command> step
 255     above contains all the configuration selections for the kernel
 256     that was just compiled. It is a good idea to keep this file for future
 257     reference:</para>
 258
 259 <screen><userinput remap="install">cp -v .config /boot/config-&linux-version;</userinput></screen>
 260
 261     <para>Install the documentation for the Linux kernel:</para>
 262
 263 <screen><userinput remap="install">install -d /usr/share/doc/linux-&linux-version;
 264 cp -r Documentation/* /usr/share/doc/linux-&linux-version;</userinput></screen>
 265
 266     <para>It is important to note that the files in the kernel source
 267     directory are not owned by <emphasis>root</emphasis>. Whenever a
 268     package is unpacked as user <emphasis>root</emphasis> (like we did
 269     inside chroot), the files have the user and group IDs of whatever
 270     they were on the packager's computer. This is usually not a problem
 271     for any other package to be installed because the source tree is
 272     removed after the installation. However, the Linux source tree is
 273     often retained for a long time.  Because of this, there is a chance
 274     that whatever user ID the packager used will be assigned to somebody
 275     on the machine. That person would then have write access to the kernel
 276     source.</para>
 277
 278     <note>
 279       <para>In many cases, the configuration of the kernel will need to be
 280       updated for packages that will be installed later in BLFS.  Unlike
 281       other packages, it is not necessary to remove the kernel source tree
 282       after the newly built kernel is installed.</para>
 283
 284       <para>If the kernel source tree is going to be retained, run
 285       <command>chown -R 0:0</command> on the <filename
 286       class="directory">linux-&linux-version;</filename> directory to ensure
 287       all files are owned by user <emphasis>root</emphasis>.</para>
 288     </note>
 289
 290     <warning>
 291       <para>Some kernel documentation recommends creating a symlink from
 292       <filename class="symlink">/usr/src/linux</filename> pointing to the kernel
 293       source directory.  This is specific to kernels prior to the 2.6 series and
 294       <emphasis>must not</emphasis> be created on an LFS system as it can cause
 295       problems for packages you may wish to build once your base LFS system is
 296       complete.</para>
 297     </warning>
 298
 299     <warning>
 300       <para>The headers in the system's <filename
 301       class="directory">include</filename> directory (<filename
 302       class="directory">/usr/include</filename>) should
 303       <emphasis>always</emphasis> be the ones against which Glibc was compiled,
 304       that is, the sanitised headers installed in <xref
 305       linkend="ch-system-linux-headers"/>.  Therefore, they should
 306       <emphasis>never</emphasis> be replaced by either the raw kernel headers
 307       or any other kernel sanitized headers.</para>
 308     </warning>
 309
 310   </sect2>
 311
 312   <sect2 id="conf-modprobe" role="configuration">
 313     <title>Configuring Linux Module Load Order</title>
 314
 315     <indexterm zone="conf-modprobe">
 316       <primary sortas="e-/etc/modprobe.d/usb.conf">/etc/modprobe.d/usb.conf</primary>
 317     </indexterm>
 318
 319     <para>Most of the time Linux modules are loaded automatically, but
 320     sometimes it needs some specific direction.  The program that loads
 321     modules, <command>modprobe</command> or <command>insmod</command>, uses
 322     <filename>/etc/modprobe.d/usb.conf</filename> for this purpose.  This file
 323     needs to be created so that if the USB drivers (ehci_hcd, ohci_hcd and
 324     uhci_hcd) have been built as modules, they will be loaded in the correct
 325     order; ehci_hcd needs to be loaded prior to ohci_hcd and uhci_hcd in order
 326     to avoid a warning being output at boot time.</para>
 327
 328     <para>Create a new file <filename>/etc/modprobe.d/usb.conf</filename> by running
 329     the following:</para>
 330
 331 <screen><userinput>install -v -m755 -d /etc/modprobe.d
 332 cat &gt; /etc/modprobe.d/usb.conf &lt;&lt; "EOF"
 333 <literal># Begin /etc/modprobe.d/usb.conf
 334
 335 install ohci_hcd /sbin/modprobe ehci_hcd ; /sbin/modprobe -i ohci_hcd ; true
 336 install uhci_hcd /sbin/modprobe ehci_hcd ; /sbin/modprobe -i uhci_hcd ; true
 337
 338 # End /etc/modprobe.d/usb.conf</literal>
 339 EOF</userinput></screen>
 340
 341   </sect2>
 342
 343   <sect2 id="contents-kernel" role="content">
 344     <title>Contents of Linux</title>
 345
 346     <segmentedlist>
 347       <segtitle>Installed files</segtitle>
 348       <segtitle>Installed directories</segtitle>
 349
 350       <seglistitem>
 351         <seg>config-&linux-version;,
 352         <phrase revision="sysv">vmlinuz-&linux-version;-lfs-&version;,</phrase>
 353         <phrase revision="systemd">vmlinuz-&linux-version;-lfs-&versiond;,</phrase>
 354         and System.map-&linux-version;</seg>
 355         <seg>/lib/modules, /usr/share/doc/linux-&linux-version;</seg>
 356       </seglistitem>
 357     </segmentedlist>
 358
 359     <variablelist>
 360       <bridgehead renderas="sect3">Short Descriptions</bridgehead>
 361       <?dbfo list-presentation="list"?>
 362       <?dbhtml list-presentation="table"?>
 363
 364       <varlistentry id="config">
 365         <term><filename>config-&linux-version;</filename></term>
 366         <listitem>
 367           <para>Contains all the configuration selections for the kernel</para>
 368           <indexterm zone="ch-bootable-kernel config">
 369             <primary sortas="e-/boot/config">/boot/config-&linux-version;</primary>
 370           </indexterm>
 371         </listitem>
 372       </varlistentry>
 373
 374       <varlistentry id="lfskernel">
 375         <term revision="sysv"><filename>vmlinuz-&linux-version;-lfs-&version;</filename></term>
 376         <term revision="systemd"><filename>vmlinuz-&linux-version;-lfs-&versiond;</filename></term>
 377         <listitem>
 378           <para>The engine of the Linux system. When turning on the computer,
 379           the kernel is the first part of the operating system that gets loaded.
 380           It detects and initializes all components of the computer's hardware,
 381           then makes these components available as a tree of files to the
 382           software and turns a single CPU into a multitasking machine capable
 383           of running scores of programs seemingly at the same time</para>
 384           <indexterm zone="ch-bootable-kernel lfskernel">
 385             <primary sortas="b-lfskernel">lfskernel-&linux-version;</primary>
 386           </indexterm>
 387         </listitem>
 388       </varlistentry>
 389
 390       <varlistentry id="System.map">
 391         <term><filename>System.map-&linux-version;</filename></term>
 392         <listitem>
 393           <para>A list of addresses and symbols; it maps the entry points and
 394           addresses of all the functions and data structures in the
 395           kernel</para>
 396           <indexterm zone="ch-bootable-kernel System.map">
 397             <primary sortas="e-/boot/System.map">/boot/System.map-&linux-version;</primary>
 398           </indexterm>
 399         </listitem>
 400       </varlistentry>
 401
 402     </variablelist>
 403
 404   </sect2>
 405
 406 </sect1>