Opened 17 years ago

Closed 17 years ago

#1790 closed task (fixed)

udev rules need documented

Reported by: archaic@… Owned by:
Priority: normal Milestone: Future
Component: Book Version: SVN
Severity: normal Keywords:


Placeholder ticket to briefly describe each type of rule used in LFS.

Change History (9)

comment:1 by archaic@…, 17 years ago

Okay, here's round one. Please help correct this for accuracy, grammar, and readability. I don't know how pedantic and technical I should be for the book.

All discussion of devices below refers to devices which can be properly exported by the kernel via sysfs (as discussed on xref="the page that dicusses this").

Uevent: An event generated by the kernel whenever a device is added or removed. In this context, added doesn't necessarily mean the device was just plugged in. It means the kernel now recognizes it. All devices are "added" when the kernel is first booting up.

ACTION=="add", DEVPATH=="/devices/*", ENV{PHYSDEVBUS}=="?*", WAIT_FOR_SYSFS="bus"

The files, directories, and symlinks in /sys do not all appear at once. They appear as the kernel identifies and enumerates them. However, the uevent will be generated as soon as the device is known to the kernel. For some devices, it may take the kernel an extra few milliseconds to export all the information to /sys/devices while Udev may already be processing the uevent. To avoid race conditions, this rule matches those devices (which have an ACTION of add, DEVPATH of /devices/*, and a non-empty environment variable named PHYSDEVBUS) and causes Udev to wait until the kernel has created the needed "bus" file (in this case it will be a symlink) for that particular device before it attempts to match any other rule. This gives the kernel time to enumerate the various devices and export them via sysfs.

ACTION=="add", SUBSYSTEM=="scsi", WAIT_FOR_SYSFS="ioerr_cnt"

Very similar to the previous rule, any uevent for devices handled by the kernel's SCSI subsystem where the ACTION to take is "add" the device, Udev will wait for the existence of the file /sys/bus/scsi/devices/<device number>/ioerr_cnt.


The majority of rules exist to create device nodes. In the above example any uevent generated by the kernel with the name "mice" will cause a device node to be created at /dev/mice with a default ownership of root:root and default permissions of 0660. To change the permissions or ownership, one would fine-tune the above rule as such:

KERNEL=="mice", MODE="0644", GROUP="some group"

Further additions to the rule allow modifying the location where the device node is created. For example, /dev/mice is not the standard location for the mice device node, /dev/input/mice is. We can acheive this with:

KERNEL=="mice", MODE="0644", GROUP="some group", NAME="input/%k"

Finally, if this device commonly has a symlink associated with it -- for example, /dev/mouse often is a symlink to /dev/input/mice -- you can acheive this with the following:

KERNEL=="mice", MODE="0644", GROUP="some group", NAME="input/%k", SYMLINK="mouse"

A final word of caution: Any particular rule must be written on one line and a comma must separate each part of the rule.

comment:2 by archaic@…, 17 years ago

This is a full page of text and it isn't even complete. We don't spend this kind of time on any other set of config files (though we don't use such complex config files anywhere else). I'm wondering how much of this is overkill.

comment:3 by bdubbs@…, 17 years ago

It is really useful from an educational point of view. udev is still pretty new and not understood by a lot of people.

I think that is really useful, but documenting a reaonably full example configuration supplements it wonderfully.

comment:4 by archaic@…, 17 years ago

Owner: changed from lfs-book@… to archaic@…
Status: newassigned

I'm going to start putting a lot of this inside the different rules files as comments. Then reference them in the book.

comment:5 by archaic@…, 17 years ago

Owner: changed from archaic@… to lfs-book@…
Status: assignednew

comment:6 by dnicholson@…, 17 years ago

I personally feel like this is not realistic for 6.2. There is a lot of work to document all the udev rules.

Alexander and I talked about creating a doc/ directory in the udev-config tarball. This would be more realistic than trying to put all this information in the book. However, this work would still need to be done. Archaic's work is a start, but there's still a long way to go.

Requesting this be moved to Future.

comment:7 by bdubbs@…, 17 years ago

Milestone: 6.2Future

Moving to future. We can take forever explaining this complex subject, but we need to concentrate on other areas right now.

comment:8 by, 17 years ago

Owner: changed from lfs-book@… to
Status: newassigned

Beginning work on this.

comment:9 by, 17 years ago

Resolution: fixed
Status: assignedclosed

And done, in a bunch of different SVN revs. (Specifically, r7801, r7803, r7804, r7805, and r7806.)

Feel free to open tickets if the explanations could use some changes -- for example, if they're too detailed or outright incorrect. (Either could happen: I don't use all the areas of the rules files.)

It may also be that the explanations don't exactly match the rules files: I believe a couple rules could still be cleaned up before they make any sense. But they come from upstream, so I'll be asking them.

Note: See TracTickets for help on using tickets.