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