1 files changed, 94 insertions, 0 deletions
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.