source: chapter07/udev.xml@ f896e21c

<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
  "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
  <!ENTITY % general-entities SYSTEM "../general.ent">
  %general-entities;
]>

<sect1 id="ch-scripts-udev">
  <?dbhtml filename="udev.html"?>

  <title>Device and Module Handling on an LFS System</title>

  <indexterm zone="ch-scripts-udev">
    <primary sortas="a-Udev">Udev</primary>
    <secondary>usage</secondary>
  </indexterm>

  <para>In <xref linkend="chapter-building-system"/>, we installed the Udev
  package. Before we go into the details regarding how this works,
  a brief history of previous methods of handling devices is in
  order.</para>

  <para>Linux systems in general traditionally use a static device creation
  method, whereby a great many device nodes are created under <filename
  class="directory">/dev</filename> (sometimes literally thousands of nodes),
  regardless of whether the corresponding hardware devices actually exist. This
  is typically done via a <command>MAKEDEV</command> script, which contains a
  number of calls to the <command>mknod</command> program with the relevant
  major and minor device numbers for every possible device that might exist in
  the world.</para>

  <para>Using the Udev method, only those devices which are detected by the
  kernel get device nodes created for them. Because these device nodes will be
  created each time the system boots, they will be stored on a <systemitem
  class="filesystem">devtmpfs</systemitem> file system (a virtual file system
  that resides entirely in system memory). Device nodes do not require much
  space, so the memory that is used is negligible.</para>

  <sect2>
    <title>History</title>

    <para>In February 2000, a new filesystem called <systemitem
    class="filesystem">devfs</systemitem> was merged into the 2.3.46 kernel
    and was made available during the 2.4 series of stable kernels. Although
    it was present in the kernel source itself, this method of creating devices
    dynamically never received overwhelming support from the core kernel
    developers.</para>

    <para>The main problem with the approach adopted by <systemitem
    class="filesystem">devfs</systemitem> was the way it handled device
    detection, creation, and naming. The latter issue, that of device node
    naming, was perhaps the most critical. It is generally accepted that if
    device names are allowed to be configurable, then the device naming policy
    should be up to a system administrator, not imposed on them by any
    particular developer(s). The <systemitem
    class="filesystem">devfs</systemitem> file system also suffers from race
    conditions that are inherent in its design and cannot be fixed without a
    substantial revision to the kernel. It was marked as deprecated for a long
    period &ndash; due to a lack of maintenance &ndash; and was finally removed
    from the kernel in June, 2006.</para>

    <para>With the development of the unstable 2.5 kernel tree, later released
    as the 2.6 series of stable kernels, a new virtual filesystem called
    <systemitem class="filesystem">sysfs</systemitem> came to be. The job of
    <systemitem class="filesystem">sysfs</systemitem> is to export a view of
    the system's hardware configuration to userspace processes. With this
    userspace-visible representation, the possibility of seeing a userspace
    replacement for <systemitem class="filesystem">devfs</systemitem> became
    much more realistic.</para>

  </sect2>

  <sect2>
    <title>Udev Implementation</title>

    <sect3>
      <title>Sysfs</title>

      <para>The <systemitem class="filesystem">sysfs</systemitem> filesystem was
      mentioned briefly above. One may wonder how <systemitem
      class="filesystem">sysfs</systemitem> knows about the devices present on
      a system and what device numbers should be used for them. Drivers that
      have been compiled into the kernel directly register their objects with
      <systemitem class="filesystem">sysfs</systemitem> as they are detected by
      the kernel. For drivers compiled as modules, this registration will happen
      when the module is loaded. Once the <systemitem
      class="filesystem">sysfs</systemitem> filesystem is mounted (on <filename
      class="directory">/sys</filename>), data which the built-in drivers
      registered with <systemitem class="filesystem">sysfs</systemitem> are
      available to userspace processes and to <command>udevd</command> for
      processing (including modifications to device nodes).</para>

    </sect3>

    <sect3>
      <title>Udev Bootscripts</title>

      <para>The <command>/etc/rc.d/init.d/udev</command> initscript takes care
      of creating device nodes when Linux is booted. The script unsets the
      uevent handler from the default of <command>/sbin/hotplug</command>.
      This is done because the kernel no longer needs to call out to an
      external binary.  Instead <command>udevd</command> will listen on a
      netlink socket for uevents that the kernel raises. Next, the bootscript
      copies any static device nodes that exist in <filename
      class="directory">/lib/udev/devices</filename> to <filename
      class="directory">/dev</filename>. This is necessary because some
      devices, directories, and symlinks are needed before the dynamic device
      handling processes are available during the early stages of booting a
      system, or are required by <command>udevd</command> itself.  Creating
      static device nodes in <filename
      class="directory">/lib/udev/devices</filename> also provides an easy
      workaround for devices that are not supported by the dynamic device
      handling infrastructure. The bootscript then starts the Udev daemon,
      <command>udevd</command>, which will act on any uevents it receives.
      Finally, the bootscript forces the kernel to replay uevents for any
      devices that have already been registered and then waits for
      <command>udevd</command> to handle them.</para>

      <para>The <command>/etc/rc.d/init.d/udev_retry</command> initscript takes
      care of re-triggering events for subsystems whose rules may rely on
      filesystems that are not mounted until the <command>mountfs</command>
      script is run (in particular, /usr and /var may cause this).  This script
      runs after the <command>mountfs</command> script, so those rules (if
      re-triggered) should succeed the second time around.  It is configured
      from the <filename>/etc/sysconfig/udev_retry</filename> file; any words
      in this file other than comments are considered subsystem names to
      trigger at retry time.  (To find the subsystem of a device, use
      <command>udevadm info --attribute-walk</command>.)</para>

    </sect3>

    <sect3>
      <title>Device Node Creation</title>

      <para>In recent version of udev, <command>udevd</command> no longer
      creates device files in <filename class="directory">/dev</filename>.
      Instead, this must be handled in the kernel, by the <systemitem
      class="filesystem">devtmpfs</systemitem> filesystem.  Any driver that
      wishes to register a device node will go through <systemitem
      class="filesystem">devtmpfs</systemitem> (via the driver core) to do it.
      When a <systemitem class="filesystem">devtmpfs</systemitem> instance is
      mounted on <filename class="directory">/dev</filename>, the device node
      will initially be created with a fixed name, permissions, and owner.</para>

      <para>A short time later, the kernel will send a uevent to <command>
      udevd</command>.  Based on the rules specified in the files within the
      <filename class="directory">/etc/udev/rules.d</filename>, <filename
      class="directory">/lib/udev/rules.d</filename>, and <filename
      class="directory">/run/udev/rules.d</filename> directories, <command>
      udevd</command> will create additional symlinks to the device node,
      or change its permissions, owner, or group, or modify the internal
      <command>udevd</command> database entry for that object.</para>

      <para>The rules in these three directories are numbered in a similar
      fashion to the LFS-Bootscripts package, and all three directories are
      merged together. If <command>udevd</command> can't find a rule for the
      device it is creating, it will leave the permissions and ownership at
      whatever <systemitem class="filesystem">devtmpfs</systemitem> used
      initially.</para>

    </sect3>

    <sect3>
      <title>Module Loading</title>

      <para>Device drivers compiled as modules may have aliases built into them.
      Aliases are visible in the output of the <command>modinfo</command>
      program and are usually related to the bus-specific identifiers of devices
      supported by a module. For example, the <emphasis>snd-fm801</emphasis>
      driver supports PCI devices with vendor ID 0x1319 and device ID 0x0801,
      and has an alias of <quote>pci:v00001319d00000801sv*sd*bc04sc01i*</quote>.
      For most devices, the bus driver exports the alias of the driver that
      would handle the device via <systemitem
      class="filesystem">sysfs</systemitem>. E.g., the
      <filename>/sys/bus/pci/devices/0000:00:0d.0/modalias</filename> file
      might contain the string
      <quote>pci:v00001319d00000801sv00001319sd00001319bc04sc01i00</quote>.
      The default rules provided with Udev will cause <command>udevd</command>
      to call out to <command>/sbin/modprobe</command> with the contents of the
      <envar>MODALIAS</envar> uevent environment variable (which should be the
      same as the contents of the <filename>modalias</filename> file in sysfs),
      thus loading all modules whose aliases match this string after wildcard
      expansion.</para>

      <para>In this example, this means that, in addition to
      <emphasis>snd-fm801</emphasis>, the obsolete (and unwanted)
      <emphasis>forte</emphasis> driver will be loaded if it is
      available. See below for ways in which the loading of unwanted drivers can
      be prevented.</para>

      <para>The kernel itself is also able to load modules for network
      protocols, filesystems and NLS support on demand.</para>

    </sect3>

    <sect3>
      <title>Handling Hotpluggable/Dynamic Devices</title>

      <para>When you plug in a device, such as a Universal Serial Bus (USB) MP3
      player, the kernel recognizes that the device is now connected and
      generates a uevent. This uevent is then handled by
      <command>udevd</command> as described above.</para>

    </sect3>

  </sect2>

  <sect2>
    <title>Problems with Loading Modules and Creating Devices</title>

    <para>There are a few possible problems when it comes to automatically
    creating device nodes.</para>

    <sect3>
      <title>A kernel module is not loaded automatically</title>

      <para>Udev will only load a module if it has a bus-specific alias and the
      bus driver properly exports the necessary aliases to <systemitem
      class="filesystem">sysfs</systemitem>. In other cases, one should
      arrange module loading by other means. With Linux-&linux-version;, Udev is
      known to load properly-written drivers for INPUT, IDE, PCI, USB, SCSI,
      SERIO, and FireWire devices.</para>

      <para>To determine if the device driver you require has the necessary
      support for Udev, run <command>modinfo</command> with the module name as
      the argument.  Now try locating the device directory under
      <filename class="directory">/sys/bus</filename> and check whether there is
      a <filename>modalias</filename> file there.</para>

      <para>If the <filename>modalias</filename> file exists in <systemitem
      class="filesystem">sysfs</systemitem>, the driver supports the device and
      can talk to it directly, but doesn't have the alias, it is a bug in the
      driver. Load the driver without the help from Udev and expect the issue
      to be fixed later.</para>

      <para>If there is no <filename>modalias</filename> file in the relevant
      directory under <filename class="directory">/sys/bus</filename>, this
      means that the kernel developers have not yet added modalias support to
      this bus type. With Linux-&linux-version;, this is the case with ISA
      busses. Expect this issue to be fixed in later kernel versions.</para>

      <para>Udev is not intended to load <quote>wrapper</quote> drivers such as
      <emphasis>snd-pcm-oss</emphasis> and non-hardware drivers such as
      <emphasis>loop</emphasis> at all.</para>

    </sect3>

    <sect3>
      <title>A kernel module is not loaded automatically, and Udev is not
      intended to load it</title>

      <para>If the <quote>wrapper</quote> module only enhances the functionality
      provided by some other module (e.g., <emphasis>snd-pcm-oss</emphasis>
      enhances the functionality of <emphasis>snd-pcm</emphasis> by making the
      sound cards available to OSS applications), configure
      <command>modprobe</command> to load the wrapper after Udev loads the
      wrapped module. To do this, add a <quote>softdep</quote> line in any
      <filename>/etc/modprobe.d/<replaceable>&lt;filename&gt;</replaceable>.conf</filename>
      file. For example:</para>

<screen role="nodump"><literal>softdep snd-pcm post: snd-pcm-oss</literal></screen>

      <para>Note that the <quote>softdep</quote> command also allows
      <literal>pre:</literal> dependencies, or a mixture of both
      <literal>pre:</literal> and <literal>post:</literal>.  See the
      <filename>modprobe.d(5)</filename> manual page for more information
      on <quote>softdep</quote> syntax and capabilities.</para>

      <para>If the module in question is not a wrapper and is useful by itself,
      configure the <command>modules</command> bootscript to load this
      module on system boot. To do this, add the module name to the
      <filename>/etc/sysconfig/modules</filename> file on a separate line.
      This works for wrapper modules too, but is suboptimal in that case.</para>

    </sect3>

    <sect3>
      <title>Udev loads some unwanted module</title>

      <para>Either don't build the module, or blacklist it in a
      <filename>/etc/modprobe.d/blacklist.conf</filename> file as done with the
      <emphasis>forte</emphasis> module in the example below:</para>

<screen role="nodump"><literal>blacklist forte</literal></screen>

      <para>Blacklisted modules can still be loaded manually with the
      explicit <command>modprobe</command> command.</para>

    </sect3>

    <sect3>
      <title>Udev creates a device incorrectly, or makes a wrong symlink</title>

      <para>This usually happens if a rule unexpectedly matches a device. For
      example, a poorly-writen rule can match both a SCSI disk (as desired)
      and the corresponding SCSI generic device (incorrectly) by vendor.
      Find the offending rule and make it more specific, with the help of the
      <command>udevadm info</command> command.</para>

    </sect3>

    <sect3>
      <title>Udev rule works unreliably</title>

      <para>This may be another manifestation of the previous problem. If not,
      and your rule uses <systemitem class="filesystem">sysfs</systemitem>
      attributes, it may be a kernel timing issue, to be fixed in later kernels.
      For now, you can work around it by creating a rule that waits for the used
      <systemitem class="filesystem">sysfs</systemitem> attribute and appending
      it to the <filename>/etc/udev/rules.d/10-wait_for_sysfs.rules</filename>
      file (create this file if it does not exist). Please notify the LFS
      Development list if you do so and it helps.</para>

    </sect3>

    <sect3>
      <title>Udev does not create a device</title>

      <para>Further text assumes that the driver is built statically into the
      kernel or already loaded as a module, and that you have already checked
      that Udev doesn't create a misnamed device.</para>

      <para>Udev has no information needed to create a device node if a kernel
      driver does not export its data to <systemitem
      class="filesystem">sysfs</systemitem>.
      This is most common with third party drivers from outside the kernel
      tree. Create a static device node in
      <filename>/lib/udev/devices</filename> with the appropriate major/minor
      numbers (see the file <filename>devices.txt</filename> inside the kernel
      documentation or the documentation provided by the third party driver
      vendor). The static device node will be copied to
      <filename class="directory">/dev</filename> by the
      <command>udev</command> bootscript.</para>

    </sect3>

    <sect3>
      <title>Device naming order changes randomly after rebooting</title>

      <para>This is due to the fact that Udev, by design, handles uevents and
      loads modules in parallel, and thus in an unpredictable order. This will
      never be <quote>fixed</quote>. You should not rely upon the kernel device
      names being stable. Instead, create your own rules that make symlinks with
      stable names based on some stable attributes of the device, such as a
      serial number or the output of various *_id utilities installed by Udev.
      See <xref linkend="ch-scripts-symlinks"/> and
      <xref linkend="ch-scripts-network"/> for examples.</para>

    </sect3>

  </sect2>

  <sect2>
    <title>Useful Reading</title>

    <para>Additional helpful documentation is available at the following
    sites:</para>

    <itemizedlist>

      <listitem>
        <para>A Userspace Implementation of <systemitem class="filesystem">devfs</systemitem>
        <ulink url="http://www.kroah.com/linux/talks/ols_2003_udev_paper/Reprint-Kroah-Hartman-OLS2003.pdf"/></para>
      </listitem>

      <listitem>
        <para>The <systemitem class="filesystem">sysfs</systemitem> Filesystem
        <ulink url="http://www.kernel.org/pub/linux/kernel/people/mochel/doc/papers/ols-2005/mochel.pdf"/></para>
      </listitem>

      <listitem>
        <para>Pointers to further reading
        <ulink url="http://www.kernel.org/pub/linux/utils/kernel/hotplug/udev.html"/>
        </para>
      </listitem>

    </itemizedlist>

  </sect2>

</sect1>