From f2bd44417bf2c6c99037b430f3f97cfd65a21f76 Mon Sep 17 00:00:00 2001 From: "dan@reactivated.net" Date: Fri, 16 Apr 2004 23:58:08 -0700 Subject: [PATCH 1/1] [PATCH] Update writing udev rules docs Here's an update for the writing udev rules document. - Minor corrections/clarifications - Added info about using NAME{all_partitions} - Added more info about udevinfo, simplifying the rule-writing process You can ignore the diff I sent you yesterday - according to the 20040415 bk snapshot on codemonkey.org, you haven't applied it yet. This patch incorporates that update, and some other changes I just made. --- docs/writing_udev_rules/index.html | 69 ++++++++++++++++++++---------- 1 file changed, 46 insertions(+), 23 deletions(-) diff --git a/docs/writing_udev_rules/index.html b/docs/writing_udev_rules/index.html index 0e4d54cfa..1a2702aea 100644 --- a/docs/writing_udev_rules/index.html +++ b/docs/writing_udev_rules/index.html @@ -1,6 +1,6 @@ -Writing udev rules [reactivated.net] +Writing udev rules @@ -8,7 +8,7 @@

Writing udev rules

by Daniel Drake (dsd)
-Version 0.51

+Version 0.53

The most recent version of this document can always be found at:
http://www.reactivated.net/udevrules.php @@ -23,7 +23,7 @@ The most recent version of this document can always be found at:
  • Why? (The purpose of this document)
  • The basics of writing rules
  • Additional automated customisation for NAME and SYMLINK parameters
    • -
  • Using regular expressions and wildcards in keys
    • +
  • Using shell-style pattern matching in keys
  • Key-writing basics
  • Identifying devices through basic keys
  • Identifying devices through SYSFS files
    • @@ -51,8 +51,9 @@ This document assumes that you have udev/hotplug installed and running OK with d

    History

    +April 15th 2004: Minor corrections. Added info about NAME{all_partitions}. Added info about other udevinfo tricks.

    +April 14th 2004: Reverted to suggesting using "udev.rules" until the udev defaults allow for other files. Minor work.

    April 6th 2004: I now write suggest users to use their own "local.rules" file rather than prepending "udev.rules".

    - April 3rd 2004: Minor cleanups and preparations for possible inclusion in the udev distribution.

    February 15th 2004: Initial publication.

    February 18th 2004: Fixed a small omission in an example. Updated section on identifying mass-storage devices. Updated section on nvidia.

    @@ -96,11 +97,13 @@ For external mass-storage devices (e.g. usb hard disks), persistant naming is ve

    The basics of writing rules

    -When populating /dev, udev decides which nodes to include, and how to name them, by reading a rules file. The default rules file includes some examples, and defaults to giving a devfs-style layout. The examples may safely be removed, but it is generally sensible to keep the devfs rules and simply make your own amendments and modifications.

    +When populating /dev, udev decides which nodes to include, and how to name them, by reading a rules file. This rules file is processed from top to bottom, and udev will stop processing rules for a device once it finds one that matches.

    + +Default udev rules are stored in /etc/udev/udev.rules. The default file includes some examples, and defaults to giving a devfs-style layout. The examples may safely be removed, but it is generally sensible to keep the devfs rules and simply make your own amendments and modifications. You should write your rules in this file, above the examples and default devfs-style rules.

    -Default udev rules are stored in /etc/udev/udev.rules. You may find it interesting to look over this file - it includes a few examples, and then some default rules proving a devfs-style /dev layout. However, you should not write rules into this file directly, to reduce hassle while updating your udev installation in the future.

    + As your own rules will effectively mask out the udev defaults which create the base /dev layout, it is recommended that you also specify devfs-style names/symlinks for the rules you write, so that you get the sensible defaults plus your own names.

    @@ -141,9 +144,9 @@ Another common operator is %k. This represents what the kernel would name A full list of operators, with explanations, can be found in the udev man page.

    -

    Using regular expressions and wildcards in keys

    +

    Using shell-style pattern matching in keys

    -You can use wildcards and basic regular-expression style matching to provide even more flexibility when writing keys. Taking a default udev rule: +You can use shell style pattern matching to provide even more flexibility when writing keys. Taking a default udev rule: 
    KERNEL="ts*", NAME="input/%k"
    @@ -164,7 +167,7 @@ This rule says:
    Match a device identified by a KERNEL name starting with the letters "fd", followed by any single digit, optionally followed by anything at all. Name the device with the kernel number of the device (%n) under the floppy directory.
    -You can use these wildcards/regular-expression matches in any type of key, including both basic keys and sysfs-based identification (see below for explanations of these key types).

    +You can use these wildcards/pattern matches in any type of key, including both basic keys and sysfs-based identification (see below for explanations of these key types).

    I have purposely left out some information on this topic (particularly the flexibility of using [ ] operators) that is out of the scope of basic rule-writing documentation. More information on this topic can be found in the udev man page.

    @@ -209,7 +212,18 @@ The first thing you need to do is find a directory somewhere in /sys that corres Once you have found a directory of this type, you can use the following command to assist you in the creation of writing keys for udev rules: 
    # udevinfo -a -p /sys/path/to/hardware/info
    -Some snipped output of the results of my "udevinfo -a -p /sys/block/sda" command is shown below, with colour added.
    +You may find that finding the correct place in /sys to run udevinfo on is not obvious. Chances are the device you just plugged in has already careted a device node (e.g. /dev/sda), in which case, udevinfo can be helpful! Taking the example of my /dev/sda node, running the following command will point you to the appropriate area of sysfs: +
    +# udevinfo -q path -n /dev/sda
+
+/block/sda
+
    + +The output of the command (shown above) is telling me that the sysfs path to start at is /sys/block/sda. I would now run "udevinfo -a -p /sys/block/sda". These two commands can be stringed together, like so: + +
    # udevinfo -a -p `udevinfo -q path -n /dev/sda`
    + +Moving on to rule-writing, some snipped output of the results of my "udevinfo -a -p /sys/block/sda" command is shown below, with colour added.
    
 follow the class device's "device"
@@ -262,14 +276,10 @@ I will show three examples of this rule writing based on udevinfo output
 
 
    Example: Writing a rule for my USB printer
    
 
-After plugging in my printer, I started looking around some /sys directories for a relevant place to start. I didn't get anywhere, but I noticed that my printer had been given device node /dev/lp0. I used this command sequence to find an answer:
+After plugging in my printer, I started looking around some /sys directories for a relevant place to start. I didn't get anywhere, but I noticed that my printer had been given device node /dev/lp0. udevinfo was able to provide me with a useful path:
 
    -# cd /sys
-# find | grep lp0
-./class/usb/lp0
-./class/usb/lp0/dev
-./class/usb/lp0/driver
-./class/usb/lp0/device
+# udevinfo -q path -n /dev/lp0
+/class/usb/lp0
 
    
 
 Running "udevinfo -a -p /sys/class/usb/lp0" provided me with a heap of info, as usual. I picked out the relevant bits for unique device identification:
@@ -326,14 +336,23 @@ Carl's rule is:
 
 This rule creates symlinks such as:
 
      
-
    • /dev/usbhdd - The fdiskable node
      • 
-
    • /dev/usbhdd1 - The first partition (mountable)
      • 
-
    • /dev/usbhdd2 - The second partition (mountable)
      • 
+
    • /dev/usbhd - The fdiskable node
      • 
+
    • /dev/usbhd1 - The first partition (mountable)
      • 
+
    • /dev/usbhd2 - The second partition (mountable)
      • 
 
 
    
 
 We agreed that depending on the situation and device in question, there are reasons for both wanting and not wanting the non-mountable /dev/sda node. Use whichever setup suits you best.

    
 
+Another difficult situation is having a multiple-slot USB-storage card reader. These types of device generally do not inform the host when new cards are plugged in or out, so plugging a card into an unused slot while the reader is plugged in will not create the extra device node needed for mounting!
    
+This problem also applies to other USB disks - e.g. if you create a new partition, the new partition node will not appear until you re-plug the device.

    
+
+udev provides a solution here - it is able to create nodes for all partitions of a block device. For every rule that you specify, the block device will have all 16 partition nodes created. To achieve this, you can simply modify the NAME key, as shown below:
    
+
+
    BUS="usb", SYSFS{product}="USB 2.0 Storage Device", NAME{all_partitions}="usbhd%n"
    
+
+You will now have nodes named: usbhd, usbhd1, usbhd2, usbhd3, ..., usbhd15.

    
+
 
 
    Example: Writing convenience rules for my CD drives
    
 I have two CD drives in my PC - a DVD reader, and a CD rewriter. My DVD is hdc and my CDRW is hdd. I would not expect this to change, unless I manually changed the cabling of my system.

    
@@ -346,13 +365,14 @@ BUS="ide", KERNEL="hdc", NAME="%k", SYMLINK="dvd cdroms/cdrom%n"
 BUS="ide", KERNEL="hdd", NAME="%k", SYMLINK="cdrw cdroms/cdrom%n"
    -You may have noticed that the default udev.rules file contains a rule which runs a script to produces names for block devices. Do not be confused by this - as usual, because your own rules in local.rules are processed before the default rules, the default rules will not be used when naming the hardware you have written rules for.

    +You may have noticed that the default udev.rules file contains a rule which runs a script to produces names for block devices. Do not be confused by this - as usual, because your own rules are located at the top of the rules file, they are processed before the default rules, so the default rules will not be used when naming the hardware you have written rules for.

    Tips for finding the appropriate places in SYSFS

    I'm looking for some more device specific tips here. Please contact me with any you can provide.