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