r2189 - / branches/clfs-2.0/BOOK/bootscripts branches/clfs-2.0/BOOK/bootscripts/common

jim at linuxfromscratch.org jim at linuxfromscratch.org
Mon Aug 7 12:47:28 PDT 2006


Author: jim
Date: 2006-08-07 13:47:26 -0600 (Mon, 07 Aug 2006)
New Revision: 2189

Added:
   branches/clfs-2.0/BOOK/bootscripts/common/symlinks.xml
Modified:
   /
   branches/clfs-2.0/BOOK/bootscripts/arm-chapter.xml
   branches/clfs-2.0/BOOK/bootscripts/common/network.xml
   branches/clfs-2.0/BOOK/bootscripts/common/setclock.xml
   branches/clfs-2.0/BOOK/bootscripts/common/udev.xml
   branches/clfs-2.0/BOOK/bootscripts/x86-chapter.xml
Log:
 r5021 at server (orig r2314):  jciccone | 2006-08-07 09:25:33 -0700
 Text Updates.



Property changes on: 
___________________________________________________________________
Name: svk:merge
   - b6734a72-470d-0410-b049-f317dca95413:/:2313
   + b6734a72-470d-0410-b049-f317dca95413:/:2314

Modified: branches/clfs-2.0/BOOK/bootscripts/arm-chapter.xml
===================================================================
--- branches/clfs-2.0/BOOK/bootscripts/arm-chapter.xml	2006-08-07 19:47:13 UTC (rev 2188)
+++ branches/clfs-2.0/BOOK/bootscripts/arm-chapter.xml	2006-08-07 19:47:26 UTC (rev 2189)
@@ -23,6 +23,7 @@
   <xi:include xmlns:xi="http://www.w3.org/2003/XInclude" href="common/profile.xml"/>
   <xi:include xmlns:xi="http://www.w3.org/2003/XInclude" href="common/hostname.xml"/>
   <xi:include xmlns:xi="http://www.w3.org/2003/XInclude" href="common/hosts.xml"/>
+  <xi:include xmlns:xi="http://www.w3.org/2003/XInclude" href="common/symlinks.xml"/>
   <xi:include xmlns:xi="http://www.w3.org/2003/XInclude" href="common/network.xml"/>
 
 </chapter>

Modified: branches/clfs-2.0/BOOK/bootscripts/common/network.xml
===================================================================
--- branches/clfs-2.0/BOOK/bootscripts/common/network.xml	2006-08-07 19:47:13 UTC (rev 2188)
+++ branches/clfs-2.0/BOOK/bootscripts/common/network.xml	2006-08-07 19:47:26 UTC (rev 2189)
@@ -24,6 +24,92 @@
   class="directory">/etc/rc.d/rc*.d</filename>).</para>
 
   <sect2>
+    <title>Creating stable names for network interfaces</title>
+
+    <para>Instructions in this section are optional if you have only one
+    network card.</para>
+
+    <para>With Udev and modular network drivers, the network interface numbering
+    is not persistent across reboots by default, because the drivers are loaded
+    in parallel and, thus, in random order. For example, on a computer having
+    two network cards made by Intel and Realtek, the network card manufactured
+    by Intel may become <filename class="devicefile">eth0</filename> and the
+    Realtek card becomes  <filename class="devicefile">eth1</filename>. In some
+    cases, after a reboot the cards get renumbered the other way around. To
+    avoid this, create Udev rules that assign stable names to network cards
+    based on their MAC addresses or bus positions.</para>
+
+    <para>If you are going to use MAC addresses to identify your network
+    cards, find the addresses with the following command:</para>
+
+<screen role="nodump"><userinput>grep -H . /sys/class/net/*/address</userinput></screen>
+
+    <para>For each network card (but not for the loopback interface),
+    invent a descriptive name, such as <quote>realtek</quote>, and create
+    Udev rules similar to the following:</para>
+
+<screen role="nodump"><userinput>cat > /etc/udev/rules.d/26-network.rules << EOF
+<literal>ACTION=="add", SUBSYSTEM=="net", SYSFS{address}=="<replaceable>00:e0:4c:12:34:56</replaceable>", \
+    NAME="<replaceable>realtek</replaceable>"
+ACTION=="add", SUBSYSTEM=="net", SYSFS{address}=="<replaceable>00:a0:c9:78:9a:bc</replaceable>", \
+    NAME="<replaceable>intel</replaceable>"</literal>
+EOF</userinput></screen>
+
+<!-- Yes, I know that VLANs are beyond BLFS. This is not the reason to get them
+     incorrect by default when every distro does this right. -->
+
+    <note>
+      <para>Although the examples in this book work properly, be aware
+      that Udev does not recognize the backslash for line continuation.
+      If modifying Udev rules with an editor, be sure to leave each rule
+      on one physical line.</para>
+    </note>
+
+    <para>If you are going to use the bus position as a key, create
+    Udev rules similar to the following:</para>
+
+<screen role="nodump"><userinput>cat > /etc/udev/rules.d/26-network.rules << EOF
+<literal>ACTION=="add", SUBSYSTEM=="net", BUS=="<replaceable>pci</replaceable>", ID=="<replaceable>0000:00:0c.0</replaceable>", \
+    NAME="<replaceable>realtek</replaceable>"
+ACTION=="add", SUBSYSTEM=="net", BUS=="<replaceable>pci</replaceable>", ID=="<replaceable>0000:00:0d.0</replaceable>", \
+    NAME="<replaceable>intel</replaceable>"</literal>
+EOF</userinput></screen>
+
+    <para>These rules will always rename the network cards to
+    <quote>realtek</quote> and <quote>intel</quote>, independently
+    of the original numbering provided by the kernel (i.e.: the original
+    <quote>eth0</quote> and <quote>eth1</quote> interfaces will no longer
+    exist, unless you put such <quote>descriptive</quote> names in the NAME
+    key). Use the descriptive names from the Udev rules instead
+    of <quote>eth0</quote> in the network interface configuration files
+    below.</para>
+
+    <para>Note that the rules above don't work for every setup. For example,
+    MAC-based rules break when bridges or VLANs are used, because bridges and
+    VLANs have the same MAC address as the network card. One wants to rename
+    only the network card interface, not the bridge or VLAN interface, but the
+    example rule matches both. If you use such virtual interfaces, you have two
+    potential solutions. One is to add the DRIVER=="?*" key after
+    SUBSYSTEM=="net" in MAC-based rules which will stop matching the virtual
+    interfaces.  This is known to fail with some older Ethernet cards because
+    they don't have the DRIVER variable in the uevent and thus the rule does
+    not match with such cards. Another solution is to switch to rules that use
+    the bus position as a key.</para>
+
+    <para>The second known non-working case is with wireless cards using the
+    MadWifi or HostAP drivers, because they create at least two interfaces with
+    the same MAC address and bus position. For example, the Madwifi driver
+    creates both an athX and a wifiX interface where X is a digit.  To
+    differentiate these interfaces, add an appropriate KERNEL parameter such as
+    KERNEL=="ath*" after SUBSYSTEM=="net".</para>
+
+    <para>There may be other cases where the rules above don't work. Currently,
+    bugs on this topic are still being reported to Linux distributions, and no
+    solution that covers every case is available.</para>
+
+  </sect2>
+
+  <sect2>
     <title>Creating Network Interface Configuration Files</title>
 
     <para>Which interfaces are brought up and down by the network script
@@ -32,14 +118,14 @@
     This directory should contain a sub-directory for each interface to be
     configured, such as <filename>ifconfig.xyz</filename>, where
     <quote>xyz</quote> is a network interface name. Inside this directory
-    would be files defining the attributes to this interface, such as its
-    IP address(es), subnet masks, and so forth.</para>
+    would be files defining the attributes to this interface, such as its IP
+    address(es), subnet masks, and so forth.</para>
 
     <para>The following command creates a sample <filename>ipv4</filename>
-    file for the <filename class="devicefile">eth0</filename> device:</para>
+    file for the <emphasis>eth0</emphasis> device:</para>
 
-<screen><userinput>cd ${CLFS}/etc/sysconfig/network-devices &&
-mkdir ifconfig.eth0 &&
+<screen><userinput>cd /etc/sysconfig/network-devices &&
+mkdir -v ifconfig.eth0 &&
 cat > ifconfig.eth0/ipv4 << "EOF"
 <literal>ONBOOT=yes
 SERVICE=ipv4-static
@@ -49,34 +135,33 @@
 BROADCAST=192.168.1.255</literal>
 EOF</userinput></screen>
 
-    <para>The values of these variables must be changed in every file to
-    match the proper setup. If the <envar>ONBOOT</envar> variable is
-    set to <quote>yes</quote> the network script will bring up the
-    Network Interface Card (NIC) during booting of the system. If set
-    to anything but <quote>yes</quote> the NIC will be ignored by the
-    network script and not brought up.</para>
+    <para>The values of these variables must be changed in every file to match
+    the proper setup. If the <envar>ONBOOT</envar> variable is set to
+    <quote>yes</quote> the network script will bring up the Network Interface
+    Card (NIC) during booting of the system. If set to anything but
+    <quote>yes</quote> the NIC will be ignored by the network script and not
+    be brought up.</para>
 
     <para>The <envar>SERVICE</envar> variable defines the method used for
     obtaining the IP address. The CLFS-Bootscripts package has a modular IP
     assignment format, and creating additional files in the <filename
     class="directory">/etc/sysconfig/network-devices/services</filename>
-    directory allows other IP assignment methods. This is commonly used
-    for Dynamic Host Configuration Protocol (DHCP), which is addressed in
-    the BLFS book.</para>
+    directory allows other IP assignment methods. This is commonly used for
+    Dynamic Host Configuration Protocol (DHCP), which is addressed in the
+    BLFS book.</para>
 
     <para>The <envar>GATEWAY</envar> variable should contain the default
     gateway IP address, if one is present. If not, then comment out the
     variable entirely.</para>
 
-    <para>The <envar>PREFIX</envar> variable needs to contain the number
-    of bits used in the subnet. Each octet in an IP address is 8 bits.
-    If the subnet's netmask is 255.255.255.0, then it is using the first
-    three octets (24 bits) to specify the network number. If the netmask
-    is 255.255.255.240, it would be using the first 28 bits. Prefixes
-    longer than 24 bits are commonly used by DSL and cable-based Internet
-    Service Providers (ISPs). In this example (PREFIX=24), the netmask is
-    255.255.255.0. Adjust the <envar>PREFIX</envar> variable according to
-    your specific subnet.</para>
+    <para>The <envar>PREFIX</envar> variable needs to contain the number of
+    bits used in the subnet. Each octet in an IP address is 8 bits. If the
+    subnet's netmask is 255.255.255.0, then it is using the first three octets
+    (24 bits) to specify the network number. If the netmask is 255.255.255.240,
+    it would be using the first 28 bits.  Prefixes longer than 24 bits are
+    commonly used by DSL and cable-based Internet Service Providers (ISPs).
+    In this example (PREFIX=24), the netmask is 255.255.255.0. Adjust the
+    <envar>PREFIX</envar> variable according to your specific subnet.</para>
 
   </sect2>
 
@@ -88,13 +173,14 @@
     </indexterm>
 
     <para>If the system is going to be connected to the Internet, it will
-    need some means of Domain Name Service (DNS) name resolution to resolve
-    Internet domain names to IP addresses, and vice versa. This is best
-    achieved by placing the IP address of the DNS server, available from
-    the ISP or network administrator, into <filename>/etc/resolv.conf</filename>.
-    Create the file by running the following:</para>
+    need some means of Domain Name Service (DNS) name resolution to
+    resolve Internet domain names to IP addresses, and vice versa. This is
+    best achieved by placing the IP address of the DNS server, available
+    from the ISP or network administrator, into
+    <filename>/etc/resolv.conf</filename>. Create the file by running the
+    following:</para>
 
-<screen><userinput>cat > ${CLFS}/etc/resolv.conf << "EOF"
+<screen><userinput>cat > /etc/resolv.conf << "EOF"
 <literal># Begin /etc/resolv.conf
 
 domain {<replaceable>[Your Domain Name]</replaceable>}

Modified: branches/clfs-2.0/BOOK/bootscripts/common/setclock.xml
===================================================================
--- branches/clfs-2.0/BOOK/bootscripts/common/setclock.xml	2006-08-07 19:47:13 UTC (rev 2188)
+++ branches/clfs-2.0/BOOK/bootscripts/common/setclock.xml	2006-08-07 19:47:26 UTC (rev 2189)
@@ -38,7 +38,7 @@
   to a value of <option>0</option> (zero) if the hardware clock
   is <emphasis>not</emphasis> set to UTC time.</para>
 
-  <para os="d">Create a new file <filename>/etc/sysconfig/clock</filename> by running
+  <para os="d">Create a new file <filename>${CLFS}/etc/sysconfig/clock</filename> by running
   the following:</para>
 
 <screen><userinput>cat > ${CLFS}/etc/sysconfig/clock << "EOF"

Added: branches/clfs-2.0/BOOK/bootscripts/common/symlinks.xml
===================================================================
--- branches/clfs-2.0/BOOK/bootscripts/common/symlinks.xml	                        (rev 0)
+++ branches/clfs-2.0/BOOK/bootscripts/common/symlinks.xml	2006-08-07 19:47:26 UTC (rev 2189)
@@ -0,0 +1,141 @@
+<?xml version="1.0" encoding="ISO-8859-1"?>
+<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
+  "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
+  <!ENTITY % general-entities SYSTEM "../../general.ent">
+  %general-entities;
+]>
+
+<sect1 id="ch-scripts-symlinks">
+  <?dbhtml filename="symlinks.html"?>
+
+  <title>Creating custom symlinks to devices</title>
+
+  <sect2>
+
+    <title>CD-ROM symlinks</title>
+
+    <para>Some software that you may want to install later (e.g., various
+    media players) expect the /dev/cdrom and /dev/dvd symlinks to exist.
+    Also, it may be convenient to put references to those symlinks into
+    <filename>/etc/fstab</filename>. For each of your CD-ROM devices,
+    find the corresponding directory under
+    <filename class="directory">/sys</filename> (e.g., this can be
+    <filename class="directory">/sys/block/hdd</filename>) and
+    run a command similar to the following:</para>
+
+<screen role="nodump"><userinput>udevtest /block/hdd</userinput></screen>
+
+    <para>Look at the lines containing the output of various *_id programs.</para>
+
+    <para>There are two approaches to creating symlinks. The first one is to
+    use the model name and the serial number, the second one is based on the
+    location of the device on the bus. If you are going to use the first
+    approach, create a file similar to the following:</para>
+
+<screen role="nodump"><userinput>cat > ${CLFS}/etc/udev/rules.d/82-cdrom.rules << EOF
+<literal>
+# Custom CD-ROM symlinks
+SUBSYSTEM=="block", ENV{ID_MODEL}=="SAMSUNG_CD-ROM_SC-148F", \
+    ENV{ID_REVISION}=="PS05", SYMLINK+="cdrom"
+SUBSYSTEM=="block", ENV{ID_MODEL}=="PHILIPS_CDD5301", \
+    ENV{ID_SERIAL}=="5VO1306DM00190", SYMLINK+="cdrom1 dvd"
+</literal>
+EOF</userinput></screen>
+
+    <note>
+      <para>Although the examples in this book work properly, be aware
+      that Udev does not recognize the backslash for line continuation.
+      If modifying Udev rules with an editor, be sure to leave each rule
+      on one physical line.</para>
+    </note>
+
+    <para>This way, the symlinks will stay correct even if you move the drives
+    to different positions on the IDE bus, but the
+    <filename>/dev/cdrom</filename> symlink won't be created if you replace
+    the old SAMSUNG CD-ROM with a new drive.</para>
+<!-- The symlinks in the first approach survive even the transition
+     to libata for IDE drives, but that is not for the book. -->
+
+    <para>The SUBSYSTEM=="block" key is needed in order to avoid
+    matching SCSI generic devices. Without it, in the case with SCSI
+    CD-ROMs, the symlinks will sometimes point to the correct
+    <filename>/dev/srX</filename> devices, and sometimes to
+    <filename>/dev/sgX</filename>, which is wrong.</para>
+
+    <para>The second approach yields:</para>
+
+<screen role="nodump"><userinput>cat > ${CLFS}/etc/udev/rules.d/82-cdrom.rules << EOF
+<literal>
+# Custom CD-ROM symlinks
+SUBSYSTEM=="block", ENV{ID_TYPE}=="cd", \
+    ENV{ID_PATH}=="pci-0000:00:07.1-ide-0:1", SYMLINK+="cdrom"
+SUBSYSTEM=="block", ENV{ID_TYPE}=="cd", \
+    ENV{ID_PATH}=="pci-0000:00:07.1-ide-1:1", SYMLINK+="cdrom1 dvd"
+</literal>
+EOF</userinput></screen>
+
+    <para>This way, the symlinks will stay correct even if you replace drives
+    with different models, but place them to the old positions on the IDE
+    bus. The ENV{ID_TYPE}=="cd" key makes sure that the symlink
+    disappears if you put something other than a CD-ROM in that position on
+    the bus.</para>
+
+    <para>Of course, it is possible to mix the two approaches.</para>
+
+  </sect2>
+
+  <sect2>
+
+    <title>Dealing with duplicate devices</title>
+
+    <para>As explained in <xref linkend="ch-scripts-udev"/>, the order in
+    which devices with the same function appear in
+    <filename class="directory">/dev</filename> is essentially random.
+    E.g., if you have a USB web camera and a TV tuner, sometimes
+    <filename>/dev/video0</filename> refers to the camera and
+    <filename>/dev/video1</filename> refers to the tuner, and sometimes
+    after a reboot the order changes to the opposite one.
+    For all classes of hardware except sound cards and network cards, this is
+    fixable by creating udev rules for custom persistent symlinks.
+    The case of network cards is covered separately in
+    <xref linkend="ch-scripts-network"/>, and sound card configuration can
+    be found in <ulink url="&blfs-root;">BLFS</ulink>.</para>
+
+    <para>For each of your devices that is likely to have this problem
+    (even if the problem doesn't exist in your current Linux distribution),
+    find the corresponding directory under
+    <filename class="directory">/sys/class</filename> or
+    <filename class="directory">/sys/block</filename>.
+    For video devices, this may be
+    <filename
+    class="directory">/sys/class/video4linux/video<replaceable>X</replaceable></filename>.
+    Figure out the attributes that identify the device uniquely (usually,
+    vendor and product IDs and/or serial numbers work):</para>
+
+<screen role="nodump"><userinput>udevinfo -a -p /sys/class/video4linux/video0</userinput></screen>
+
+    <para>Then write rules that create the symlinks, e.g.:</para>
+
+<screen role="nodump"><userinput>cat > ${CLFS}/etc/udev/rules.d/83-duplicate_devs.rules << EOF
+<literal>
+# Persistent symlinks for webcam and tuner
+KERNEL=="video*", SYSFS{idProduct}=="1910", SYSFS{idVendor}=="0d81", \
+    SYMLINK+="webcam"
+KERNEL=="video*", SYSFS{device}=="0x036f", SYSFS{vendor}=="0x109e", \
+    SYMLINK+="tvtuner"
+</literal>
+EOF</userinput></screen>
+
+    <para>The result is that <filename>/dev/video0</filename> and
+    <filename>/dev/video1</filename> devices still refer randomly to the tuner
+    and the web camera (and thus should never be used directly), but there are
+    symlinks <filename>/dev/tvtuner</filename> and
+    <filename>/dev/webcam</filename> that always point to the correct
+    device.</para>
+
+    <para>More information on writing Udev rules can be found in
+    <filename>/usr/share/doc/udev-&udev-version;/index.html</filename>.</para>
+
+ </sect2>
+
+</sect1>

Modified: branches/clfs-2.0/BOOK/bootscripts/common/udev.xml
===================================================================
--- branches/clfs-2.0/BOOK/bootscripts/common/udev.xml	2006-08-07 19:47:13 UTC (rev 2188)
+++ branches/clfs-2.0/BOOK/bootscripts/common/udev.xml	2006-08-07 19:47:26 UTC (rev 2189)
@@ -8,202 +8,318 @@
 <sect1 id="ch-scripts-udev">
   <?dbhtml filename="udev.html"?>
 
-  <title>Device and Module Handling on an CLFS System</title>
+  <title>Device and Module Handling on a CLFS System</title>
 
   <indexterm zone="ch-scripts-udev">
     <primary sortas="a-Udev">Udev</primary>
-  <secondary>usage</secondary></indexterm>
+    <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>
+  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. 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">tmpfs</systemitem> (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>
+  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">tmpfs</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>
+    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> 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 has also been marked
-    as deprecated due to a lack of recent maintenance.</para>
+    conditions that are inherent in its design and cannot be fixed without a
+    substantial revision to the kernel. It has also been marked as deprecated
+    due to a lack of recent maintenance.</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>
+    <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>
 
-    <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>udev</command> for
-    device node creation.</para>
+    <sect3>
+      <title>Sysfs</title>
 
-    <para>The <command>S10udev</command> initscript takes care of creating
-    these device nodes when Linux is booted. This script starts by registering
-    <command>/sbin/udevsend</command> as a hotplug event handler. Hotplug
-    events (discussed below) are not usually generated during this stage,
-    but <command>udev</command> is registered just in case they do occur.
-    The <command>udevstart</command> program then walks through the
-    <systemitem class="filesystem">/sys</systemitem> filesystem and creates
-    devices under <filename class="directory">/dev</filename> that match the
-    descriptions. For example, <filename>/sys/class/tty/vcs/dev</filename>
-    contains the string <quote>7:0</quote> This string is used by
-    <command>udevstart</command> to create <filename>/dev/vcs</filename>
-    with major number <emphasis>7</emphasis> and minor <emphasis>0</emphasis>.
-    The names and permissions of the nodes created under the <filename
-    class="directory">/dev</filename> directory are configured according to
-    the rules specified in the files within the <filename
-    class="directory">/etc/udev/rules.d/</filename> directory. These are
-    numbered in a similar fashion to the CLFS-Bootscripts package. If
-    <command>udev</command> can't find a rule for the device it is creating,
-    it will default permissions to <emphasis>660</emphasis> and ownership to
-    <emphasis>root:root</emphasis>.</para>
+      <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 device
+      node creation.</para>
 
-    <para>Once the above stage is complete, all devices that were already
-    present and have compiled-in drivers will be available for use. This
-    leads us to the devices that have modular drivers.</para>
+    </sect3>
 
-    <para>Earlier, we mentioned the concept of a <quote>hotplug event
-    handler.</quote> When a new device connection is detected by the kernel,
-    the kernel will generate a hotplug event and look at the file
-    <filename>/proc/sys/kernel/hotplug</filename> to determine the userspace
-    program that handles the device's connection. The <command>udev</command>
-    bootscript registered <command>udevsend</command> as this handler. When
-    these hotplug events are generated, the kernel will tell
-    <command>udev</command> to check the <filename
-    class="directory">/sys</filename> filesystem for the information
-    pertaining to this new device and create the <filename
-    class="directory">/dev</filename> entry for it.</para>
+    <sect3>
+      <title>Udev Bootscript</title>
 
-    <para>This brings us to one problem that exists with
-    <command>udev</command>, and likewise with <systemitem
-    class="filesystem">devfs</systemitem> before it. It is commonly
-    referred to as the <quote>chicken and egg</quote> problem. Most
-    Linux distributions handle loading modules via entries in
-    <filename>/etc/modules.conf</filename>. Access to a device node causes
-    the appropriate kernel module to load. With <command>udev</command>,
-    this method will not work because the device node does not exist until
-    the module is loaded. To solve this, the <command>S05modules</command>
-    bootscript was added to the CLFS-Bootscripts package, along with the
-    <filename>/etc/sysconfig/modules</filename> file. By adding module
-    names to the <filename>modules</filename> file, these modules will be
-    loaded when the computer starts up. This allows <command>udev</command>
-    to detect the devices and create the appropriate device nodes.</para>
+      <para>The <command>S10udev</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.
+      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>Note that on slower machines or for drivers that create a lot
-    of device nodes, the process of creating devices may take a few
-    seconds to complete. This means that some device nodes may not be
-    immediately accessible.</para>
+    </sect3>
 
-  </sect2>
+    <sect3>
+      <title>Device Node Creation</title>
 
-  <sect2>
-    <title>Handling Hotpluggable/Dynamic Devices</title>
+      <para>To obtain the right major and minor number for a device, Udev relies
+      on the information provided by <systemitem
+      class="filesystem">sysfs</systemitem> in <filename
+      class="directory">/sys</filename>.  For example,
+      <filename>/sys/class/tty/vcs/dev</filename> contains the string
+      <quote>7:0</quote>. This string is used by <command>udevd</command>
+      to create a device node with major number <emphasis>7</emphasis> and minor
+      <emphasis>0</emphasis>. The names and permissions of the nodes created
+      under the <filename class="directory">/dev</filename> directory are
+      determined by rules specified in the files within the <filename
+      class="directory">/etc/udev/rules.d/</filename> directory. These are
+      numbered in a similar fashion to the CLFS-Bootscripts package. If
+      <command>udevd</command> can't find a rule for the device it is creating,
+      it will default permissions to <emphasis>660</emphasis> and ownership to
+      <emphasis>root:root</emphasis>. Documentation on the syntax of the Udev
+      rules configuration files are available in
+      <filename>/usr/share/doc/udev-&udev-version;/index.html</filename></para>
 
-    <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 hotplug event. If the driver is already loaded (either
-    because it was compiled into the kernel or because it was loaded via
-    the <command>S05modules</command> bootscript), <command>udev</command>
-    will be called upon to create the relevant device node(s) according to
-    the <systemitem class="filesystem">sysfs</systemitem> data available in
-    <filename class="directory">/sys</filename>.</para>
+    </sect3>
 
-    <para>If the driver for the just plugged in device is available as a
-    module but currently unloaded, the Hotplug package will load the
-    appropriate module and make this device available by creating the
-    device node(s) for it.</para>
+    <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 rules that CLFS installs will cause <command>udevd</command> to call
+      out to <command>/sbin/modprobe</command> with the contents of the
+      <envar>MODALIAS</envar> uevent environment variable (that 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 Creating Devices</title>
+    <title>Problems with Loading Modules and Creating Devices</title>
 
-    <para>There are a few known problems when it comes to automatically
-    creating device nodes:</para>
+    <para>There are a few possible problems when it comes to automatically
+    creating device nodes.</para>
 
-    <para>1) A kernel driver may not export its data to <systemitem
-    class="filesystem">sysfs</systemitem>.</para>
+    <sect3>
+      <title>A kernel module is not loaded automatically</title>
 
-    <para>This is most common with third party drivers from outside the
-    kernel tree. Udev will be unable to automatically create device nodes
-    for such drivers. Use the <filename>/etc/sysconfig/createfiles</filename>
-    configuration file to manually create the devices. Consult the
-    <filename>devices.txt</filename> file inside the kernel documentation
-    or the documentation for that driver to find the proper major/minor
-    numbers.</para>
+      <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>2) A non-hardware device is required. This is most common with
-    the Advanced Linux Sound Architecture (ALSA) project's Open Sound
-    System (OSS) compatibility module. These types of devices can be
-    handled in one of two ways:</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>
 
-    <itemizedlist>
-      <listitem>
-        <para>Adding the module names to
-        <filename>/etc/sysconfig/modules</filename></para>
-      </listitem>
-      <listitem>
-        <para>Using an <quote>install</quote> line in
-        <filename>/etc/modprobe.conf</filename>. This tells the
-        <command>modprobe</command> command <quote>when loading this
-        module, also load this other module, at the same time.</quote>
-        For example:</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>
 
-<screen><userinput>install snd-pcm modprobe -i snd-pcm ; modprobe \
-    snd-pcm-oss ; true</userinput></screen>
+      <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>This will cause the system to load both the
-        <emphasis>snd-pcm</emphasis> and <emphasis>snd-pcm-oss</emphasis>
-        modules when any request is made to load the driver
-        <emphasis>snd-pcm</emphasis>.</para>
-      </listitem>
-    </itemizedlist>
+      <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 an <quote>install</quote> line in
+      <filename>/etc/modprobe.conf</filename>. For example:</para>
+
+<screen role="nodump"><literal>install snd-pcm /sbin/modprobe -i snd-pcm ; \
+    /sbin/modprobe snd-pcm-oss ; true</literal></screen>
+
+      <para>If the module in question is not a wrapper and is useful by itself,
+      configure the <command>S05modules</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
+      <filename>/etc/modprobe.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.</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. Please notify the CLFS 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>S10udev</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>
@@ -213,18 +329,22 @@
     sites:</para>
 
     <itemizedlist>
+
       <listitem>
         <para remap="verbatim">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 remap="verbatim">udev FAQ
         <ulink url="http://www.kernel.org/pub/linux/utils/kernel/hotplug/udev-FAQ"/></para>
       </listitem>
+
       <listitem>
-        <para remap="verbatim">The Linux Kernel Driver Model
-        <ulink url="http://public.planetmirror.com/pub/lca/2003/proceedings/papers/Patrick_Mochel/Patrick_Mochel.pdf"/></para>
+        <para remap="verbatim">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>
+
     </itemizedlist>
 
   </sect2>

Modified: branches/clfs-2.0/BOOK/bootscripts/x86-chapter.xml
===================================================================
--- branches/clfs-2.0/BOOK/bootscripts/x86-chapter.xml	2006-08-07 19:47:13 UTC (rev 2188)
+++ branches/clfs-2.0/BOOK/bootscripts/x86-chapter.xml	2006-08-07 19:47:26 UTC (rev 2189)
@@ -23,6 +23,7 @@
   <xi:include xmlns:xi="http://www.w3.org/2003/XInclude" href="common/profile.xml"/>
   <xi:include xmlns:xi="http://www.w3.org/2003/XInclude" href="common/hostname.xml"/>
   <xi:include xmlns:xi="http://www.w3.org/2003/XInclude" href="common/hosts.xml"/>
+  <xi:include xmlns:xi="http://www.w3.org/2003/XInclude" href="common/symlinks.xml"/>
   <xi:include xmlns:xi="http://www.w3.org/2003/XInclude" href="common/network.xml"/>
 
 </chapter>




More information about the cross-lfs mailing list