udev rules need documented

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.

KERNEL=="mice"

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.

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.

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 http://www.reactivated.net/writing_udev_rules.html is really useful, but documenting a reaonably full example configuration supplements it wonderfully.

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

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.

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

Beginning work on this.

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.