0001 USB hotplugging
0002 ~~~~~~~~~~~~~~~
0003
0004 Linux Hotplugging
0005 =================
0006
0007
0008 In hotpluggable busses like USB (and Cardbus PCI), end-users plug devices
0009 into the bus with power on. In most cases, users expect the devices to become
0010 immediately usable. That means the system must do many things, including:
0011
0012 - Find a driver that can handle the device. That may involve
0013 loading a kernel module; newer drivers can use module-init-tools
0014 to publish their device (and class) support to user utilities.
0015
0016 - Bind a driver to that device. Bus frameworks do that using a
0017 device driver's probe() routine.
0018
0019 - Tell other subsystems to configure the new device. Print
0020 queues may need to be enabled, networks brought up, disk
0021 partitions mounted, and so on. In some cases these will
0022 be driver-specific actions.
0023
0024 This involves a mix of kernel mode and user mode actions. Making devices
0025 be immediately usable means that any user mode actions can't wait for an
0026 administrator to do them: the kernel must trigger them, either passively
0027 (triggering some monitoring daemon to invoke a helper program) or
0028 actively (calling such a user mode helper program directly).
0029
0030 Those triggered actions must support a system's administrative policies;
0031 such programs are called "policy agents" here. Typically they involve
0032 shell scripts that dispatch to more familiar administration tools.
0033
0034 Because some of those actions rely on information about drivers (metadata)
0035 that is currently available only when the drivers are dynamically linked,
0036 you get the best hotplugging when you configure a highly modular system.
0037
0038 Kernel Hotplug Helper (``/sbin/hotplug``)
0039 =========================================
0040
0041 There is a kernel parameter: ``/proc/sys/kernel/hotplug``, which normally
0042 holds the pathname ``/sbin/hotplug``. That parameter names a program
0043 which the kernel may invoke at various times.
0044
0045 The /sbin/hotplug program can be invoked by any subsystem as part of its
0046 reaction to a configuration change, from a thread in that subsystem.
0047 Only one parameter is required: the name of a subsystem being notified of
0048 some kernel event. That name is used as the first key for further event
0049 dispatch; any other argument and environment parameters are specified by
0050 the subsystem making that invocation.
0051
0052 Hotplug software and other resources is available at:
0053
0054 http://linux-hotplug.sourceforge.net
0055
0056 Mailing list information is also available at that site.
0057
0058
0059 USB Policy Agent
0060 ================
0061
0062 The USB subsystem currently invokes ``/sbin/hotplug`` when USB devices
0063 are added or removed from system. The invocation is done by the kernel
0064 hub workqueue [hub_wq], or else as part of root hub initialization
0065 (done by init, modprobe, kapmd, etc). Its single command line parameter
0066 is the string "usb", and it passes these environment variables:
0067
0068 ========== ============================================
0069 ACTION ``add``, ``remove``
0070 PRODUCT USB vendor, product, and version codes (hex)
0071 TYPE device class codes (decimal)
0072 INTERFACE interface 0 class codes (decimal)
0073 ========== ============================================
0074
0075 If "usbdevfs" is configured, DEVICE and DEVFS are also passed. DEVICE is
0076 the pathname of the device, and is useful for devices with multiple and/or
0077 alternate interfaces that complicate driver selection. By design, USB
0078 hotplugging is independent of ``usbdevfs``: you can do most essential parts
0079 of USB device setup without using that filesystem, and without running a
0080 user mode daemon to detect changes in system configuration.
0081
0082 Currently available policy agent implementations can load drivers for
0083 modules, and can invoke driver-specific setup scripts. The newest ones
0084 leverage USB module-init-tools support. Later agents might unload drivers.
0085
0086
0087 USB Modutils Support
0088 ====================
0089
0090 Current versions of module-init-tools will create a ``modules.usbmap`` file
0091 which contains the entries from each driver's ``MODULE_DEVICE_TABLE``. Such
0092 files can be used by various user mode policy agents to make sure all the
0093 right driver modules get loaded, either at boot time or later.
0094
0095 See ``linux/usb.h`` for full information about such table entries; or look
0096 at existing drivers. Each table entry describes one or more criteria to
0097 be used when matching a driver to a device or class of devices. The
0098 specific criteria are identified by bits set in "match_flags", paired
0099 with field values. You can construct the criteria directly, or with
0100 macros such as these, and use driver_info to store more information::
0101
0102 USB_DEVICE (vendorId, productId)
0103 ... matching devices with specified vendor and product ids
0104 USB_DEVICE_VER (vendorId, productId, lo, hi)
0105 ... like USB_DEVICE with lo <= productversion <= hi
0106 USB_INTERFACE_INFO (class, subclass, protocol)
0107 ... matching specified interface class info
0108 USB_DEVICE_INFO (class, subclass, protocol)
0109 ... matching specified device class info
0110
0111 A short example, for a driver that supports several specific USB devices
0112 and their quirks, might have a MODULE_DEVICE_TABLE like this::
0113
0114 static const struct usb_device_id mydriver_id_table[] = {
0115 { USB_DEVICE (0x9999, 0xaaaa), driver_info: QUIRK_X },
0116 { USB_DEVICE (0xbbbb, 0x8888), driver_info: QUIRK_Y|QUIRK_Z },
0117 ...
0118 { } /* end with an all-zeroes entry */
0119 };
0120 MODULE_DEVICE_TABLE(usb, mydriver_id_table);
0121
0122 Most USB device drivers should pass these tables to the USB subsystem as
0123 well as to the module management subsystem. Not all, though: some driver
0124 frameworks connect using interfaces layered over USB, and so they won't
0125 need such a struct usb_driver.
0126
0127 Drivers that connect directly to the USB subsystem should be declared
0128 something like this::
0129
0130 static struct usb_driver mydriver = {
0131 .name = "mydriver",
0132 .id_table = mydriver_id_table,
0133 .probe = my_probe,
0134 .disconnect = my_disconnect,
0135
0136 /*
0137 if using the usb chardev framework:
0138 .minor = MY_USB_MINOR_START,
0139 .fops = my_file_ops,
0140 if exposing any operations through usbdevfs:
0141 .ioctl = my_ioctl,
0142 */
0143 };
0144
0145 When the USB subsystem knows about a driver's device ID table, it's used when
0146 choosing drivers to probe(). The thread doing new device processing checks
0147 drivers' device ID entries from the ``MODULE_DEVICE_TABLE`` against interface
0148 and device descriptors for the device. It will only call ``probe()`` if there
0149 is a match, and the third argument to ``probe()`` will be the entry that
0150 matched.
0151
0152 If you don't provide an ``id_table`` for your driver, then your driver may get
0153 probed for each new device; the third parameter to ``probe()`` will be
0154 ``NULL``.
