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>kernel</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/disable/set the 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]
  83
  84 Kernel hacking  ---&gt;
  85        Choose kernel unwinder (Frame pointer unwinder)  ---&gt; [CONFIG_UNWINDER_FRAME_POINTER]</screen>
  86
  87       <screen role="nodump" revision="systemd">
  88 General setup -->
  89    [ ] Enable deprecated sysfs features to support old userspace tools [CONFIG_SYSFS_DEPRECATED]
  90    [*] Configure standard kernel features (expert users) [CONFIG_EXPERT] ---&gt;
  91       [*] open by fhandle syscalls [CONFIG_FHANDLE]
  92    [ ] Auditing support [CONFIG_AUDIT]
  93    [*] Control Group support [CONFIG_CGROUPS]
  94 Processor type and features  ---&gt;
  95    [*] Enable seccomp to safely compute untrusted bytecode [CONFIG_SECCOMP]
  96 Firmware Drivers  ---&gt;
  97    [*] Export DMI identification via sysfs to userspace [CONFIG_DMIID]
  98 Networking support  ---&gt;
  99   Networking options  ---&gt;
 100    &lt;*&gt; The IPv6 protocol [CONFIG_IPV6]
 101 Device Drivers  ---&gt;
 102   Generic Driver Options  ---&gt;
 103    [ ] Support for uevent helper [CONFIG_UEVENT_HELPER]
 104    [*] Maintain a devtmpfs filesystem to mount at /dev [CONFIG_DEVTMPFS]
 105    Firmware Loader ---&gt;
 106       [ ] Enable the firmware sysfs fallback mechanism [CONFIG_FW_LOADER_USER_HELPER]
 107 File systems  ---&gt;
 108    [*] Inotify support for userspace [CONFIG_INOTIFY_USER]
 109    &lt;*&gt; Kernel automounter support (supports v3, v4, and v5) [CONFIG_AUTOFS_FS]
 110   Pseudo filesystems  ---&gt;
 111    [*] Tmpfs POSIX Access Control Lists [CONFIG_TMPFS_POSIX_ACL]
 112    [*] Tmpfs extended attributes [CONFIG_TMPFS_XATTR]
 113 Kernel hacking  ---&gt;
 114    x86 Debugging ---&gt;
 115        Choose kernel unwinder (Frame pointer unwinder)  ---&gt; [CONFIG_UNWINDER_FRAME_POINTER]</screen>
 116     </note>
 117
 118     <note revision="systemd">
 119       <para>While "The IPv6 Protocol" is not strictly
 120       required, it is highly recommended by the systemd developers.</para>
 121     </note>
 122
 123     <para revision="sysv">There are several other options that may be desired
 124     depending on the requirements for the system. For a list of options needed
 125     for BLFS packages, see the <ulink
 126     url="&lfs-root;blfs/view/&short-version;/longindex.html#kernel-config-index">BLFS
 127     Index of Kernel Settings</ulink>
 128     (&lfs-root;blfs/view/&short-version;/longindex.html#kernel-config-index).</para>
 129
 130     <note>
 131       <para>If your host hardware is using UEFI, then the 'make defconfig'
 132       above should automatically add in some EFI-related kernel options.</para>
 133
 134       <para>In order to allow your LFS kernel to be booted from within your
 135       host's UEFI boot environment, your kernel must have this option
 136       selected:</para>
 137
 138 <screen role="nodump">Processor type and features  ---&gt;
 139    [*]   EFI stub support  [CONFIG_EFI_STUB]</screen>
 140
 141       <para>A fuller description of managing UEFI environments from within LFS
 142       is covered by the lfs-uefi.txt hint at
 143       <ulink
 144         url="http://www.linuxfromscratch.org/hints/downloads/files/lfs-uefi.txt"/>.
 145       </para>
 146     </note>
 147
 148     <variablelist>
 149       <title>The rationale for the above configuration items:</title>
 150
 151       <varlistentry>
 152         <term><parameter>Support for uevent helper</parameter></term>
 153         <listitem>
 154           <para>Having this option set may interfere with device
 155           management when using Udev/Eudev. </para>
 156         </listitem>
 157       </varlistentry>
 158
 159       <varlistentry>
 160         <term><parameter>Maintain a devtmpfs</parameter></term>
 161         <listitem>
 162           <para>This will create automated device nodes which are populated by the
 163           kernel, even without Udev running.  Udev then runs on top of this,
 164           managing permissions and adding symlinks.  This configuration
 165           item is required for all users of Udev/Eudev.</para>
 166         </listitem>
 167       </varlistentry>
 168
 169     </variablelist>
 170
 171 <screen role="nodump"><userinput>make menuconfig</userinput></screen>
 172
 173     <variablelist>
 174       <title>The meaning of optional make environment variables:</title>
 175
 176       <varlistentry>
 177         <term><parameter>LANG=&lt;host_LANG_value&gt; LC_ALL=</parameter></term>
 178         <listitem>
 179           <para>This establishes the locale setting to the one used on the
 180           host.  This may be needed for a proper menuconfig ncurses interface
 181           line drawing on a UTF-8 linux text console.</para>
 182
 183           <para>If used, be sure to replace
 184           <replaceable>&lt;host_LANG_value&gt;</replaceable> by the value of
 185           the <envar>$LANG</envar> variable from your host.  You can
 186           alternatively use instead the host's value of <envar>$LC_ALL</envar>
 187           or <envar>$LC_CTYPE</envar>.</para>
 188         </listitem>
 189       </varlistentry>
 190
 191     </variablelist>
 192
 193     <para>Alternatively, <command>make oldconfig</command> may be more
 194     appropriate in some situations. See the <filename>README</filename>
 195     file for more information.</para>
 196
 197     <para>If desired, skip kernel configuration by copying the kernel
 198     config file, <filename>.config</filename>, from the host system
 199     (assuming it is available) to the unpacked <filename
 200     class="directory">linux-&linux-version;</filename> directory. However,
 201     we do not recommend this option. It is often better to explore all the
 202     configuration menus and create the kernel configuration from
 203     scratch.</para>
 204
 205     <para>Compile the kernel image and modules:</para>
 206
 207 <screen><userinput remap="make">make</userinput></screen>
 208
 209     <para>If using kernel modules, module configuration in <filename
 210     class="directory">/etc/modprobe.d</filename> may be required.
 211     Information pertaining to modules and kernel configuration is
 212     located in <xref linkend="ch-config-udev"/> and in the kernel
 213     documentation in the <filename
 214     class="directory">linux-&linux-version;/Documentation</filename> directory.
 215     Also, <filename>modprobe.d(5)</filename> may be of interest.</para>
 216
 217     <para>Unless module support has been disabled in the kernel configuration,
 218     install the modules with:</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 files copied
 228       below should go there. The easiest way to do that is to bind /boot on the
 229       host (outside chroot) to /mnt/lfs/boot before proceeding.  As the root
 230       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 -iv arch/x86/boot/bzImage /boot/vmlinuz-&linux-version;-lfs-&version;</userinput></screen>
 242
 243 <screen revision="systemd"><userinput remap="install">cp -iv 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 -iv 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 -iv .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>