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: [EMAIL PROTECTED] (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> -- http://linuxfromscratch.org/mailman/listinfo/cross-lfs FAQ: http://www.linuxfromscratch.org/faq/ Unsubscribe: See the above information page
