8 files changed, 417 insertions, 0 deletions
diff --git a/udev-config/doc/05-udev-early.txt b/udev-config/doc/05-udev-early.txt
new file mode 100644
index 000000000..9c0fb4fb8
--- /dev/null
+++ b/udev-config/doc/05-udev-early.txt
@@ -0,0 +1,33 @@
+Purpose of rules file:
+
+The kernel does not always fully populate a given kobject's attributes before
+sending the uevent for that kobject.  This means that a given sysfs directory
+may not have all the required files in it (each directory corresponds to a
+kobject, and each file corresponds to an attribute).
+
+Therefore, we must sometimes wait for attributes to show up when devices are
+discovered.  This is accomplished by udev's WAIT_FOR_SYSFS rule types.
+
+
+Description of rules:
+
+All rules in this file match ACTION="add", because none of them apply when
+devices are being removed.
+
+SUBSYSTEM is the kernel subsystem that the device uses.  Current kernels have
+some issues with SCSI device attributes being created too late.  For any device
+with a SUBSYSTEM of scsi, we must wait for the ioerr_cnt attribute.  (This is
+the last attribute created for SCSI devices, so when this attribute appears,
+the kobject is fully populated.)
+
+It is also possible to use SUBSYSTEMS in Udev rules.  Using SUBSYSTEMS would
+cause Udev to search up the device tree for a matching SUBSYSTEM value.  (Note
+that "the device tree" is not necessarily the same as the path under /sys (the
+DEVPATH).  Rather, "up the device tree" is the path followed by udevinfo when
+it is given the argument "-a".)
+
+We do not use SUBSYSTEMS in this rule, because we only care about the SUBSYSTEM
+of the kobject in question.  We don't care about devices that are children of
+SCSI devices, only the SCSI device itself.  We will use SUBSYSTEMS in later
+rules, though.
+
diff --git a/udev-config/doc/55-lfs.txt b/udev-config/doc/55-lfs.txt
new file mode 100644
index 000000000..7b09c79a0
--- /dev/null
+++ b/udev-config/doc/55-lfs.txt
@@ -0,0 +1,94 @@
+Purpose of rules file:
+
+This is the core rules file for Udev on LFS.  If these rules were not included,
+most devices would either only work for root, or would not work at all.
+
+
+Description of rules:
+
+By default, Udev creates device nodes with UID 0, GID 0, and permissions 0660,
+and in one flat directory structure with all nodes in /dev.  This does not
+always work well.
+
+KERNEL=="ptmx"
+
+Any uevent generated by the kernel with a name matching "ptmx" will match this
+rule.  Note that the matching done by Udev is shell-style; these are not regex
+matches.  For the ptmx device, we first change the permisions, by assigning to
+the MODE value:
+
+KERNEL=="ptmx", MODE="0666"
+
+We also assign a different GID to /dev/ptmx (also all other TTY devices), by
+assigning to the GROUP value:
+
+KERNEL=="ptmx", MODE="0666", "GROUP="tty"
+
+
+There are also devices that should not be in /dev, because historically they
+have been created in subdirectories instead.  For instance, all Alsa devices
+have traditionally been put into the /dev/snd subdirectory:
+
+KERNEL=="controlC[0-9]*", <...>, NAME="snd/%k"
+
+"%k" expands into "the original value of KERNEL" (note: not the pattern that was
+matched against).  This type of rule puts any matching device into the snd/
+subdirectory.
+
+Sometimes we need to move devices based on more than just their name.  For
+example, USB printer devices need to be moved to /dev/usb/lpX, but we can't
+match only "lp[0-9]*", because that would also match parallel port printers.
+So we match both KERNEL and SUBSYSTEMS in this case, to move USB printers only.
+
+
+Some devices also commonly have symlinks pointing to them -- for example,
+/dev/mouse is usually a symlink to /dev/input/mice.  We acheive this by
+assigning to the SYMLINK value.  But note that SYMLINK can store multiple values
+(because each device node could have multiple symlinks pointing to it), so we
+need to add to the list of symlinks, not overwrite the whole list:
+
+KERNEL=="mice", <...>, SYMLINK+="mouse"
+
+If we needed to add multiple symlinks, they would be space-separated inside the
+double quotes.
+
+Of course, symlinks, permissions, and device names can all be combined in a
+rule if needed.  But note that if you combine permissions and symlinks, or if
+you combine GROUP and symlinks, the permissions of the symlink will not be
+modified, only those of the target device.  (This is because the kernel does
+not pay any attention to the permissions on symlinks, only the permissions on
+their targets, and there's no reason to change something that won't be used.)
+
+
+Finally, we have this rule:
+
+SUBSYSTEM=="usb_device", PROGRAM="/bin/sh -c 'X=%k; X=$${X#usbdev}; B=$${X%%%%.*} D=$${X#*.}; echo bus/usb/$$B/$$D'", NAME="%c"
+
+This rule matches any device under the SUBSYSTEM of usb_device.  (All devices
+that were traditionally created under /proc/bus/usb/ use this subsystem.)  We
+tell Udev to run the specified PROGRAM; Udev will save the output of this
+program (it will be available under %c later).
+
+The program itself is a shell that starts by setting the variable X to the
+original kernel name (which is "usbdevB.D" for these devices, where B and D are
+the bus and device numbers of the USB device).  Then, the rule re-sets X to the
+value of X with the string "usbdev" removed from the start.  So now, X has the
+value "B.D".  Then, the rule sets B to the value of X after a period, and all
+characters following it, have been removed from the end; this sets B to just
+the string "B" (just the bus number of the USB device).  Then, the rule sets D
+to the value of X after a period, and all characters before it, have been
+removed from the beginning; this sets D to just the string "D" (just the device
+number).
+
+Then, the rule echoes "bus/usb/$B/$D" (bus/usb/bus-number/device-number), so
+Udev will capture that value.  The rule sets NAME="%c" to put the device node
+at /dev/bus/usb/bus-number/device-number.  (This is the same layout that the
+/proc/bus/usb/ devices used.)
+
+Most of the doubled characters in this rule are doubled so that Udev does not
+interpret them.  The rule looks all the more confusing because of this method
+of escaping special characters.
+
+
+A final word of caution: Any particular rule must be written on one line, and a
+comma must separate each part of the rule.
diff --git a/udev-config/doc/60-persistent-input.txt b/udev-config/doc/60-persistent-input.txt
new file mode 100644
index 000000000..45030723f
--- /dev/null
+++ b/udev-config/doc/60-persistent-input.txt
@@ -0,0 +1,86 @@
+Purpose of rules file:
+
+This rules file provides nonvolatile, unique names (in the form of symlinks)
+for input devices that cooperate.
+
+
+Description of rules:
+
+This file starts off with a few rules that make Udev skip the entire file if
+the current uevent is not input related.  If ACTION is not "add", or SUBSYSTEM
+is not "input", or KERNEL (the device node) matches "input[0-9]*", then Udev
+will GOTO the LABEL named "persistent_input_end", which is the last rule in
+this file.  (input[0-9]* uevents are skipped because they do not create device
+nodes.)
+
+This type of "skip this list of rules if X" operation is done in both the
+persistent input and persistent storage rules files.  The reason is efficiency
+-- if Udev had to go run the usb_id and/or path_id programs for non-input and
+non-storage rules, those rules would take much longer to process for no good
+reason.
+
+
+First in this file is a set of rules for by-ID style symlinks.  These attempt
+to uniquely identify a device based on its serial number, but there are some
+issues with this.  Many USB manufacturers do not provide a unique serial number
+for each device -- for instance, my Microsoft Intellimouse Optical has a USB
+serial number of "Microsoft_Microsoft_IntelliMouse_Optical".  This kind of
+nonsensical "serial number" means that if you plug in two Intellimouse Optical
+devices, they will both get the same by-id symlink, and the device that the
+symlink points to will be random.  This defeats the purpose of by-ID symlinks.
+(However, I believe this behavior is technically valid according to the USB
+standard.  I believe it is not recommended, though.)
+
+Anyway, first in the by-ID rules, we have a rule that runs for any (input)
+device hanging anywhere off a USB bus.  It uses the IMPORT{program} option to
+run the "/lib/udev/usb_id -x" program.  usb_id looks at the environment to find
+out which device to look at, generates a list of environment-variable VAR=value
+pairs, and prints them.  Udev stores this output away while the process is
+running.  After the process exits, Udev modifies the current environment to
+include the VARs that usb_id printed.  (It assigns the "value"s that usb_id
+printed to each of those VARs.)  Specifically, usb_id prints ID_VENDOR,
+ID_MODEL, ID_REVISION, ID_SERIAL, ID_TYPE, and ID_BUS (at least in the case of
+the aforementioned USB optical mouse).  These variable names will all be set in
+the environment.
+
+Then, we have a set of rules to set ID_CLASS for various types of devices.  The
+rules first check for a "usb"-bus device that has a "bInterfaceClass" of 03 and
+a "bInterfaceProtocol" of 01.  If the interface class is 03, this is an HID
+device.  If the protocol is 01, it's a keyboard device.  So we set ID_CLASS to
+"kbd".  The next rule checks whether the interface protocol is 02, and if so,
+sets ID_CLASS to "mouse" (HID devices with a protocol of 02 are mice).
+
+Any input device that the "pcspkr" driver claims must be a speaker.  Any input
+device that the "atkbd" driver claims must be a keyboard.  Any input device
+that the "psmouse" driver claims must be a mouse.  If there's a sysfs attribute
+named "name", whose contents contain "dvb", "DVB", or " IR ", then we set
+ID_CLASS to "ir".
+
+Then, we have a rule to search the tree and find the first parent that has a
+modalias.  If that modalias matches the big long ugly string in the rules file,
+we assume this is a joystick device, and set ID_CLASS appropriately.  (This
+parent should be the kobject for the joystick device itself.  The reason we
+search the tree is that the current uevent is for a device node, not the
+physical joystick device.)
+
+Once the ID_CLASS variable is set properly, we have one more modification to
+perform: if the ID_SERIAL variable was not set at all by the usb_id program, we
+set it to "noserial".
+
+Now that all the environment variables are set up properly, we start generating
+the by-ID symlinks in /dev/input/by-id/.  If the current device node's name
+starts with "event", we add "event" into the symlink name.  Otherwise, we don't
+add anything for mice.  (Other device types don't get a persistent by-ID
+symlink.)
+
+
+Next, we create by-path symlinks.  The /lib/udev/path_id program takes the path
+of the device as an argument, and prints out "ID_PATH=string", where "string"
+is the "shortest physical path" to the device.  We import this value into the
+environment.
+
+If the path is non-empty, and the device node name starts with "mouse" or
+"event", we add a by-path symlink based on the path and the device class (and
+we also add "event" if it's an event device).  This symlink should be stable as
+long as the device never moves to a different port.
+
diff --git a/udev-config/doc/60-persistent-storage.txt b/udev-config/doc/60-persistent-storage.txt
new file mode 100644
index 000000000..32062c559
--- /dev/null
+++ b/udev-config/doc/60-persistent-storage.txt
@@ -0,0 +1,95 @@
+Purpose of rules file:
+
+This rules file provides nonvolatile, unique names (in the form of symlinks)
+for various types of storage devices -- both IDE/ATA and SCSI.
+
+
+Description of rules:
+
+First, similar to the 60-persistent-input.rules file, we skip the entire file
+for uevents that this rules file should not apply to, as an optimization.  The
+file does not apply to removal uevents or non-block devices.  It does not apply
+to ramdisks, loopback-mount devices, floppy disks, netblock devices, or device-
+mapper devices.  It also should not apply to removable devices (that is, non-
+partition devices with attributes named "removable" with the value "1", or
+partition devices whose parents have "removable" set to "1" -- partition
+kobjects don't have the "removable" attribute, only whole-disk kobjects do).
+
+For partition devices, we use the IMPORT{parent} option to pull in all the
+environment variables that get set for the parent device.  (The parent of a
+partition device is the containing whole-disk device.)  The IMPORT{parent}
+option is documented in the udev(7) manpage, but basically the value that we
+assign is used as a filter of environment variable names to import.
+
+Now, we start with rules to create by-ID symlinks (similar to the by-ID links
+created for input devices).  For hd* whole-disk devices (they're IDE/ATA, since 
+they start with hd), we run the ata_id program in --export mode.  The ata_id
+program requires a device node to be passed, so we also use the $tempnode Udev
+variable -- this causes Udev to create a temporary device node somewhere and
+substitute its name where $tempnode appears in the program command line.
+
+The ata_id program, in --export mode, prints several ID_* values.  If we're
+looking at a whole-disk device, and if ID_SERIAL is among those, we add a
+symlink containing the device's ID_MODEL and ID_SERIAL values.  If we're
+looking at a partition device, we create an ID_MODEL- and ID_SERIAL-based
+symlink also, but we add -partX to the end of the link name (where X is the
+partition number).
+
+For SCSI devices, we first make some modifications to the environment.  If the
+device's kobject has a parent with a non-empty "ieee1394_id" attribute, then
+the device is Firewire, so we set the ID_SERIAL environment variable to the
+value of that attribute, and we set ID_BUS to "ieee1394".  Now, if ID_SERIAL is
+not set, we run usb_id, which (if this is a USB storage device) will print
+various values.  If ID_SERIAL is still unset, we run scsi_id with a set of
+parameters designed to get an ID_SERIAL by querying the device itself.  If that
+still fails, we try running scsi_id in a mode that prints the information even
+if the disk doesn't support so-called "vital product data" pages.  If the
+uevent is for a DASD device, we run dasd_id.
+
+If one of these *_id programs gave us an ID_SERIAL, then for whole-disk devices
+we create a by-ID symlink using the ID_BUS and ID_SERIAL.  For partition
+devices, we create a by-ID symlink that has the same form except we add -partX
+to the end (just like for IDE/ATA devices).
+
+
+Now we have some rules to create by-path persistent symlinks.  We start by
+running the path_id program on the DEVPATH (%p) value.  For whole-disk devices
+and SCSI ROM type devices, we create a symlink directly, using the environment
+variable ID_PATH, under the /dev/disk/by-path directory.  But for SCSI tape
+devices, we create a by-path symlink in the /dev/tape/by-path directory (we
+base the symlink on the same information, though: the ID_PATH value printed by
+path_id).  Now, for both SCSI ROM and SCSI tape devices, we skip everything
+that's left in the rules file (this is another optimization: neither SCSI ROM
+nor SCSI tape devices have UUIDs, labels, or EDD information).
+
+For partition devices, we now create a by-path symlink of the same form as the
+other partition device persistent symlinks (that is, with the same name as the
+parent device, but with -partX added).  We know that ID_PATH is set whenever it
+applies, because we ran the path_id program on the parent device, and we did an
+IMPORT{parent} on ID_* earlier in the rules file.
+
+Now we create by-label and by-uuid symlinks.  These use properties of various
+filesystems to generate a persistent name for a partition.  For instance, if
+you use the ext2 filesystem, you can use e2label to assign a label, and mke2fs
+assigns a UUID when the filesystem is created.  MS-DOS compatible filesystems
+also assign a "UUID" (actually it's just a serial number, created based on the
+date and time the partition was formatted, so it is not unique), which these
+rules will also use.  But for removable partitions, we skip the rules (for the
+same reason as we skipped them above for removable disks).
+
+We run the vol_id program to get ID_FS_USAGE, ID_FS_UUID, and ID_FS_LABEL_SAFE
+values.  (vol_id supports other values as well, but we do not use them here.)
+ID_FS_USAGE corresponds to the way the filesystem is supposed to be used; if it
+gets set to "filesystem", "other", or "crypto", we create a symlink.  If
+ID_FS_UUID is set, we use it in a by-uuid symlink.  If ID_FS_LABEL_SAFE is set,
+we use it in a by-label symlink.
+
+Finally, we create EDD-based symlinks in the by-id directory.  For whole-disk
+devices, we run edd_id to get the EDD-generated ID string.  (For partition
+devices, we import this string from the parent.)  If edd_id yields an ID_EDD
+value, we use it in a symlink, for both whole disks and partitions.
+
+
+The last rule in the file is merely a LABEL that various other rules use to
+bypass the file (or the rest of the file) when needed.
+
diff --git a/udev-config/doc/61-cdrom.txt b/udev-config/doc/61-cdrom.txt
new file mode 100644
index 000000000..ff7887fe3
--- /dev/null
+++ b/udev-config/doc/61-cdrom.txt
@@ -0,0 +1,16 @@
+Purpose of rules file:
+
+This file re-assigns CD-ROM type devices to the "cdrom" group.
+
+
+Description of rules:
+
+There is only one rule here.  It depends on the 60-persistent-storage file,
+though, because it requires the ID_TYPE environment variable to be set properly
+for CD devices.  Normally the rules in the 60-persistent-storage.rules file
+will run the correct *_id programs to do this properly.
+
+If ID_TYPE is "cd", and this is a block device, and it's an add event, then we
+assign the device to the "cdrom" group.  Simple, once the *_id programs have
+all been run.
+
diff --git a/udev-config/doc/80-drivers.txt b/udev-config/doc/80-drivers.txt
new file mode 100644
index 000000000..e5cfcefb3
--- /dev/null
+++ b/udev-config/doc/80-drivers.txt
@@ -0,0 +1,69 @@
+Purpose of rules file:
+
+The rules in this file allow Udev to fully replace the old /sbin/hotplug
+script.  They automatically load kernel modules as devices are discovered.
+
+
+Description of rules:
+
+All rules in this file match ACTION=="add", so they only run when devices are
+being added.
+
+ENV{MODALIAS} is the value of the environment variable named MODALIAS.  This
+environment variable is sent by the kernel when it sends a uevent for any
+device that has a modalias.  Modaliases are strings that can be used to load
+the appropriate kernel module driver.
+
+Generally a modalias will contain information like vendor ID, device ID, and
+possibly other IDs depending on the bus the device is connected to.  (USB, for
+instance, has the concept of a "device class" and a "device interface", which
+are basically just ways to standardize the USB protocol for various types of
+devices.  This is what allows a single kernel module such as hid.ko to drive
+many different vendors' USB input devices: all devices that support the USB
+HID interface expose the HID interface number in their modalias, and so the
+hid.ko driver can be loaded for each device.  When it loads, hid.ko attaches
+to the HID interface and does whatever is needed to work with each device.)
+
+Kernel modules that drive hardware expose a list of modaliases.  These
+modaliases are matched against the device modalias by /sbin/modprobe (after
+shell-style expansion), with the help of /sbin/depmod's modules.alias file.
+The upshot of all this is, you can tell Udev to run "/sbin/modprobe modalias",
+and it will load the module that claims it can drive the "modalias" device.
+
+The rule that does this inspects ENV{MODALIAS} to ensure it is not empty.  It
+does this by comparing it to "?*" -- inside a match, "*" would match *any*
+string, including the empty string, so to ensure MODALIAS is not empty, we need
+to match against "?*" instead.  ("?" matches any one character.)
+
+The Udev RUN+="" option adds a program to run when the rule matches.  In this
+case, we tell Udev to run "/sbin/modprobe $env{MODALIAS}".  Note that Udev does
+not do path searches; if the executable is not specified with a fully-qualified
+path, it *must* be located under the /lib/udev directory.  If it is not, you
+*must* specify a fully-qualified path, as we do here.  Also, "$env{string}" is
+replaced by the value of the environment variable "string" when the command
+runs, so this adds the modalias to the modprobe command.  The modprobe program
+will do the rest.  Finally, the {ignore_error} option is added to the RUN key;
+this prevents Udev from failing the uevent if the modprobe command fails.  (The
+modprobe command will fail when run during cold-plugging, if the driver was
+configured into the kernel instead of as a module, for instance.)
+
+There is still one feature of the old hotplug shell-script system that Udev
+cannot provide: blacklisting modules from being auto-loaded.  To accomplish
+this, we must use module-init-tools.  In /etc/modprobe.conf, if you use the
+"blacklist <module-name>" syntax, modprobe will not load <module-name> under
+any name except its real module name.  Any modaliases exposed by that module
+will not be honored.
+
+
+There are also rules in this file for various other types of driver loading.
+PNP-BIOS devices, for instance, expose a list of PNP IDs in their sysfs "id"
+attribute, instead of exposing a single MODALIAS, so one rule loops through
+each ID and tries to load the appropriate module.  Several other types of
+devices require an extra module before they will work properly; one example
+of this is IDE tapes, which require the ide-scsi module.  Finally, whenever
+any SCSI device is found, the file uses the TEST key to check whether the
+/sys/module/sg directory exists.  If not, then the "sg" module -- the SCSI
+generic driver -- is loaded.  (That driver creates the module/sg directory,
+so the module/sg test is just to see whether the driver has already been
+loaded.)
+
diff --git a/udev-config/doc/95-udev-late.txt b/udev-config/doc/95-udev-late.txt
new file mode 100644
index 000000000..00ea17c61
--- /dev/null
+++ b/udev-config/doc/95-udev-late.txt
@@ -0,0 +1,18 @@
+Purpose of rules file:
+
+Sends all uevents to a Unix-domain socket, where they can be monitored by other
+programs.
+
+
+Description of rules:
+
+There is only one rule, which matches all uevents.  It uses Udev's RUN key to
+specify a socket to send each uevent to.  Normally RUN is used to start up a
+process, but if the pathname starts with "socket:", Udev instead interprets
+the rest of the name as a Unix-domain socket to send the uevent to.  In this
+case, we send send the uevent to the socket named /org/kernel/udev/monitor,
+which is created by the udevmonitor program.  Udevmonitor is used to watch
+uevents as they come to Udev.  Its only purpose is for debugging, but sending
+the uevent to a socket that doesn't exist is a very cheap operation, so we
+enable this rule for all uevents.
+
diff --git a/udev-config/doc/README b/udev-config/doc/README
new file mode 100644
index 000000000..01216694c
--- /dev/null
+++ b/udev-config/doc/README
@@ -0,0 +1,6 @@
+This directory contains documentation for each rule file used in LFS.
+
+Each .rules file should contain a corresponding .txt file in this directory,
+which explains both the overall purpose of the rules file, and each type of
+rule contained therein.
+