From 0ca6adfed9603e63bd42f9af9d1a73bd661a36da Mon Sep 17 00:00:00 2001 From: Daniel Drake Date: Mon, 9 May 2005 23:44:27 +0100 Subject: [PATCH] Writing udev rules docs update Here's a long overdue update to the udev rules docs, based on lots of user feedback from the last few months. Mostly updates to keep up with the new udev features, some clarifications and wording improvements. I added a section on rules for palm pilots due to the excessive amount of mail I get about them. I removed the nvidia stuff because it's out of date. Added another section about debugging using logs and udevtest. Removed the thanks list because I haven't been updating it and there are too many people to name now, sorry..! --- docs/writing_udev_rules/index.html | 153 +++++++++++++++++++++---------------- 1 file changed, 89 insertions(+), 64 deletions(-) (limited to 'docs/writing_udev_rules/index.html') diff --git a/docs/writing_udev_rules/index.html b/docs/writing_udev_rules/index.html index 9396184366..1ba43678c0 100644 --- a/docs/writing_udev_rules/index.html +++ b/docs/writing_udev_rules/index.html @@ -8,7 +8,7 @@

Writing udev rules

by Daniel Drake (dsd)
-Version 0.55

+Version 0.6

The most recent version of this document can always be found at:
http://www.reactivated.net/udevrules.php @@ -27,6 +27,8 @@ The most recent version of this document can always be found at:
  • Key-writing basics
  • Identifying devices through basic keys
  • Identifying devices through SYSFS files
    • +
  • Using multiple SYMLINK style rules
    • +
  • Controlling ownership and permissions
  • Example: Writing a rule for my USB printer
  • Example: Writing a rule for my USB-Storage digital camera
    • @@ -34,8 +36,7 @@ The most recent version of this document can always be found at:
  • Example: Writing convenience rules for my CD drives
  • Example: Writing a rule to name my network interface
  • Tips for finding the appropriate places in SYSFS
    • -
  • Using multiple SYMLINK style rules
    • -
  • udev vs Nvidia's graphics drivers
    • +
  • Debugging your rules
  • Author and credits
    • @@ -53,6 +54,7 @@ This document assumes that you have udev/hotplug installed and running OK with d

    History

    +May 9th 2005 v0.6: Misc updates, including information about udevinfo, groups and permissions, logging, and udevtest.

    June 20th 2004 v0.55: Added info on multiple symlinks, and some minor changes/updates.

    April 26th 2004 v0.54: Added some Debian info. Minor corrections. Re-reverted information about what to call your rule file. Added info about naming network interfaces.

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

    @@ -66,9 +68,8 @@ February 15th 2004 v0.1: Initial publication.

    Software versions used at time of writing

    -Linux Kernel 2.6.7
    -udev 027
    -hotplug 20040401

    +Linux Kernel 2.6.11
    +udev 056

    Terminology: devfs, sysfs, nodes, etc.

    @@ -97,6 +98,8 @@ However, if my HP laser printer got named lp_hp (as well as lpX) and my other pr For external mass-storage devices (e.g. usb hard disks), persistent naming is very helpful in that it allows you to hardcode accurate device paths into your /etc/fstab.

    +It is important to understand that writing rules is simply a means of customizing udev behaviour. Writing rules is not a workaround for the problem where no device nodes for your particular device exist. If no matching rules exist, udev will create the node anyway, using the name that was supplied by the kernel.

    +

    The basics of writing rules

    @@ -104,31 +107,32 @@ When populating /dev, udev decides which nodes to include, and how to nam Default udev rules are stored in /etc/udev/rules.d/50-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.

    -Files in /etc/udev/rules.d/ are parsed in lexical order. udev will stop processing rules as soon as it finds a matching rule in a file for the new item of hardware that has been detected. It is important that your own rules get processed before the udev defaults, otherwise your own naming schemes will not take effect! I suggest that you keep your own rules in a file at /etc/udev/rules.d/10-local.rules (this doesn't exist by default - create it). As 10 comes before 50, you know that your rules will be looked at first.

    +Files in /etc/udev/rules.d/ are parsed in lexical order. udev will stop processing rules as soon as it finds a matching rule in a file for the new item of hardware that has been detected. It is important that your own rules get processed before the udev defaults, otherwise your own naming schemes will not take effect! I suggest that you keep your own rules in a file at /etc/udev/rules.d/10-local.rules (this doesn't exist by default - create it). As 10 comes before 50, you know that your rules will be looked at first. It is important that the filenames of your rule files end with the .rules suffix, otherwise they will not be used.

    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.

    In rule files, lines starting with a "#" are treated as comments. Every uncommented line in the file corresponds to a rule.

    -The basic form for a rule is: -
    key,[key,...] name [, symlink]
    +Rules are composed of keys. Keys are seperated by commas. Some keys are used for reading and matching information, others are used for assigning information and performing actions.
      -
    1. At least one key must be specified. Keys are used to identify which devices the rule matches.
      2. -
    2. The name parameter is required. It tells udev what that device should be named as in the /dev tree. It is written in the format NAME="X", where X is what the node will be named. You can specify multiple symlinks here, seperate them with a space.
      3. -
    3. The symlink parameter (optional) allows for you to specify additional places where this node will be linked.
      4. +
    4. At least one identification key should be provided, which will match the rule to any number of devices in the system. These are listed in the later section: Identifying devices through basic keys.
      5. +
    5. At least one assignment key should be provided, to control how the resultant device node is created. These include NAME, SYMLINK, OWNER, GROUP and MODE, all of which are described in this document.
    -Remember that udev will only create one node for one device. If you want it to be accessible through multiple nodes, then you have to specify the other nodes in the SYMLINK parameter.

    +Common rules will use basic identification keys to determine the device to name, and then have a NAME assignement key to define the device node name. udev will only create one node for one device, so if you want it to be accessible through multiple nodes, then you have to specify the other nodes in the SYMLINK assignment key.

    I'll take a slightly modified udev example rule to illustrate this: 
    BUS="usb", SYSFS{serial}="HXOLL0012202323480", NAME="lp_epson", SYMLINK="printers/epson_stylus"
    -The keys here are the BUS and SYSFS{serial} parameters. udev will match this rule against a device that is connected through the USB bus and with a serial number of HXOLL0012202323480. Note that all (as opposed to any) specified keys must be matched for udev to use the rule to name a device.
    +The identification keys here are BUS and SYSFS{serial}. The assignment keys here are NAME and SYMLINK. udev will match this rule against a device that is connected through the USB bus and with a serial number of HXOLL0012202323480. Note that all (as opposed to any) specified keys must be matched for udev to use the rule to name a device.
    udev will name this node lp_epson, and it will be located at /dev/lp_epson.
    udev will also create a symlink to /dev/lp_epson, located at /dev/printers/epson_stylus (the printers directory will be automatically created). You can now print to your Epson printer by sending data to /dev/printers/epson_stylus or /dev/lp_epson.

    +Any rules that you have added or modified will not take effect until you notify udev of this. Make sure you remember to run the following every time you modify any rule files: +
    # udevstart
    +

    Additional automated customisation for NAME and SYMLINK parameters

    @@ -187,6 +191,8 @@ You may be wondering, "How do I find the serial number of my printer? What is th The valid keys are: - -

    Using multiple SYMLINK style rules

    -Another recent feature is the ability to write rules that do not specify a NAME, but instead they simply specify SYMLINK keys. This allows you to avoid the issue where your own rules effectively mask the udev defaults.

    - -Take the rule:
    -
    KERNEL="hdc", SYMLINK="dvd"
    - -When udev finds this rule, it will take a mental note of it. Upon finding another rule matching the same device which also includes a NAME parameter, udev will create the node as specified by the NAME parameter, plus symbolic links as specified by the SYMLINK parameters of both rules.
    -To put it into practical terms, when udev is naming nodes for my hdc device, it will use the default rules for block devices as usual, with the addition of my personal symlink "dvd".

    + +

    Debugging your rules

    -Similarly to normal rules, rules of this type will only take effect if udev is able to find them before it finds a rule specifying a NAME parameter.

    - - -

    udev vs Nvidia's graphics drivers

    +If you have written rules and remembered to run udevstart but they do not appear to be taking effect, there are a couple of ways you can debug them.

    -This section isn't really relevant to the purpose of this document, but judging from the hits I get from google, this is a hot topic. I will leave it here for now.

    +The file /etc/udev/udev.conf contains a udev_log option. Setting this option to yes will cause udev to log some useful information about which rules are being applied to which nodes into the system logger. The logs will be included in /var/log/messages for most users.

    -Nvidia's graphics drivers (the closed-source ones, not the ones that come with XFree) do not work with a default installation of udev - you are unable to start X. This is because the nvidia module is loaded by X, but the /dev/nvidia* nodes are not created quick enough, so X bails out.

    +Additionally, if you know the path in sysfs for the node you want to create, you can use udevtest to see a rundown on what udev would do with the node. For example: -The solution to this problem is to autoload the nvidia module on bootup. Yes - you are *supposed* to do this - the NVidia FAQ confirms this! On devfs-based systems, devfs did this automatically at bootup anyway. Your linux distribution will have created a file which you can list modules to be loaded on bootup (e.g. /etc/modules.autoload.d/kernel-2.6 for Gentoo, /etc/modules for Debian).

    +
    # udevtest /sys/class/sound/dsp/
+version 056
+looking at '/class/sound/dsp/'
+opened class_dev->name='dsp'
+configured rule in '/etc/udev/rules.d/50-udev.rules[132]' applied, added symlink '%k'
+configured rule in '/etc/udev/rules.d/50-udev.rules[132]' applied, 'dsp' becomes 'sound/%k'
+creating device node '/dev/sound/dsp', major = '14', minor = '3', mode = '0660', uid = '0', gid = '18'
    -This isn't all - you will also need to patch the nvidia kernel interface to export some basic info to SYSFS so that udev will create the devices. Martin Schlemmer has written a patch against the 1.0.5336 version of the nvidia drivers, which can be found here. The Gentoo package nvidia-kernel-1.0.5336-r4 contains this patch.

    - -Another solution is to simply create the nvidia specific nodes on bootup. X will then load the module when required, and as the nodes are already in existance, you will not run into the problem described above. Place these commands in a file that is automatically executed on bootup (e.g. /etc/conf.d/local.start for Gentoo): -
    -mknod /dev/nvidia0 c 195 0
-mknod /dev/nvidiactl c 195 255
-
    - -You should now be able to get into X with no problems.

    +udevtest is only a debugging/testing tool - it does not actually create the device node, even though it says it doing so!

    Author and Credits

    This document is written by Daniel Drake <dan@reactivated.net>
    Please do not hesitate to send feedback!

    -Additional thanks to: - - -

    Copyright (C) 2003-2004 Daniel Drake
    +Copyright (C) 2003-2005 Daniel Drake
    This document is licensed under the GNU General Public License, Version 2. -- cgit v1.2.3-54-g00ecf