176f650f0SMauro Carvalho ChehabUSB hotplugging 276f650f0SMauro Carvalho Chehab~~~~~~~~~~~~~~~ 376f650f0SMauro Carvalho Chehab 476f650f0SMauro Carvalho ChehabLinux Hotplugging 576f650f0SMauro Carvalho Chehab================= 676f650f0SMauro Carvalho Chehab 776f650f0SMauro Carvalho Chehab 876f650f0SMauro Carvalho ChehabIn hotpluggable busses like USB (and Cardbus PCI), end-users plug devices 976f650f0SMauro Carvalho Chehabinto the bus with power on. In most cases, users expect the devices to become 1076f650f0SMauro Carvalho Chehabimmediately usable. That means the system must do many things, including: 1176f650f0SMauro Carvalho Chehab 1276f650f0SMauro Carvalho Chehab - Find a driver that can handle the device. That may involve 1376f650f0SMauro Carvalho Chehab loading a kernel module; newer drivers can use module-init-tools 1476f650f0SMauro Carvalho Chehab to publish their device (and class) support to user utilities. 1576f650f0SMauro Carvalho Chehab 1676f650f0SMauro Carvalho Chehab - Bind a driver to that device. Bus frameworks do that using a 1776f650f0SMauro Carvalho Chehab device driver's probe() routine. 1876f650f0SMauro Carvalho Chehab 1976f650f0SMauro Carvalho Chehab - Tell other subsystems to configure the new device. Print 2076f650f0SMauro Carvalho Chehab queues may need to be enabled, networks brought up, disk 2176f650f0SMauro Carvalho Chehab partitions mounted, and so on. In some cases these will 2276f650f0SMauro Carvalho Chehab be driver-specific actions. 2376f650f0SMauro Carvalho Chehab 2476f650f0SMauro Carvalho ChehabThis involves a mix of kernel mode and user mode actions. Making devices 2576f650f0SMauro Carvalho Chehabbe immediately usable means that any user mode actions can't wait for an 2676f650f0SMauro Carvalho Chehabadministrator to do them: the kernel must trigger them, either passively 2776f650f0SMauro Carvalho Chehab(triggering some monitoring daemon to invoke a helper program) or 2876f650f0SMauro Carvalho Chehabactively (calling such a user mode helper program directly). 2976f650f0SMauro Carvalho Chehab 3076f650f0SMauro Carvalho ChehabThose triggered actions must support a system's administrative policies; 3176f650f0SMauro Carvalho Chehabsuch programs are called "policy agents" here. Typically they involve 3276f650f0SMauro Carvalho Chehabshell scripts that dispatch to more familiar administration tools. 3376f650f0SMauro Carvalho Chehab 3476f650f0SMauro Carvalho ChehabBecause some of those actions rely on information about drivers (metadata) 3576f650f0SMauro Carvalho Chehabthat is currently available only when the drivers are dynamically linked, 3676f650f0SMauro Carvalho Chehabyou get the best hotplugging when you configure a highly modular system. 3776f650f0SMauro Carvalho Chehab 3876f650f0SMauro Carvalho ChehabKernel Hotplug Helper (``/sbin/hotplug``) 3976f650f0SMauro Carvalho Chehab========================================= 4076f650f0SMauro Carvalho Chehab 4176f650f0SMauro Carvalho ChehabThere is a kernel parameter: ``/proc/sys/kernel/hotplug``, which normally 4276f650f0SMauro Carvalho Chehabholds the pathname ``/sbin/hotplug``. That parameter names a program 4376f650f0SMauro Carvalho Chehabwhich the kernel may invoke at various times. 4476f650f0SMauro Carvalho Chehab 4576f650f0SMauro Carvalho ChehabThe /sbin/hotplug program can be invoked by any subsystem as part of its 4676f650f0SMauro Carvalho Chehabreaction to a configuration change, from a thread in that subsystem. 4776f650f0SMauro Carvalho ChehabOnly one parameter is required: the name of a subsystem being notified of 4876f650f0SMauro Carvalho Chehabsome kernel event. That name is used as the first key for further event 4976f650f0SMauro Carvalho Chehabdispatch; any other argument and environment parameters are specified by 5076f650f0SMauro Carvalho Chehabthe subsystem making that invocation. 5176f650f0SMauro Carvalho Chehab 5276f650f0SMauro Carvalho ChehabHotplug software and other resources is available at: 5376f650f0SMauro Carvalho Chehab 5476f650f0SMauro Carvalho Chehab http://linux-hotplug.sourceforge.net 5576f650f0SMauro Carvalho Chehab 5676f650f0SMauro Carvalho ChehabMailing list information is also available at that site. 5776f650f0SMauro Carvalho Chehab 5876f650f0SMauro Carvalho Chehab 5976f650f0SMauro Carvalho ChehabUSB Policy Agent 6076f650f0SMauro Carvalho Chehab================ 6176f650f0SMauro Carvalho Chehab 6276f650f0SMauro Carvalho ChehabThe USB subsystem currently invokes ``/sbin/hotplug`` when USB devices 6376f650f0SMauro Carvalho Chehabare added or removed from system. The invocation is done by the kernel 6476f650f0SMauro Carvalho Chehabhub workqueue [hub_wq], or else as part of root hub initialization 6576f650f0SMauro Carvalho Chehab(done by init, modprobe, kapmd, etc). Its single command line parameter 6676f650f0SMauro Carvalho Chehabis the string "usb", and it passes these environment variables: 6776f650f0SMauro Carvalho Chehab 6876f650f0SMauro Carvalho Chehab========== ============================================ 6976f650f0SMauro Carvalho ChehabACTION ``add``, ``remove`` 7076f650f0SMauro Carvalho ChehabPRODUCT USB vendor, product, and version codes (hex) 7176f650f0SMauro Carvalho ChehabTYPE device class codes (decimal) 7276f650f0SMauro Carvalho ChehabINTERFACE interface 0 class codes (decimal) 7376f650f0SMauro Carvalho Chehab========== ============================================ 7476f650f0SMauro Carvalho Chehab 7576f650f0SMauro Carvalho ChehabIf "usbdevfs" is configured, DEVICE and DEVFS are also passed. DEVICE is 7676f650f0SMauro Carvalho Chehabthe pathname of the device, and is useful for devices with multiple and/or 7776f650f0SMauro Carvalho Chehabalternate interfaces that complicate driver selection. By design, USB 7876f650f0SMauro Carvalho Chehabhotplugging is independent of ``usbdevfs``: you can do most essential parts 7976f650f0SMauro Carvalho Chehabof USB device setup without using that filesystem, and without running a 8076f650f0SMauro Carvalho Chehabuser mode daemon to detect changes in system configuration. 8176f650f0SMauro Carvalho Chehab 8276f650f0SMauro Carvalho ChehabCurrently available policy agent implementations can load drivers for 8376f650f0SMauro Carvalho Chehabmodules, and can invoke driver-specific setup scripts. The newest ones 8476f650f0SMauro Carvalho Chehableverage USB module-init-tools support. Later agents might unload drivers. 8576f650f0SMauro Carvalho Chehab 8676f650f0SMauro Carvalho Chehab 8776f650f0SMauro Carvalho ChehabUSB Modutils Support 8876f650f0SMauro Carvalho Chehab==================== 8976f650f0SMauro Carvalho Chehab 9076f650f0SMauro Carvalho ChehabCurrent versions of module-init-tools will create a ``modules.usbmap`` file 9176f650f0SMauro Carvalho Chehabwhich contains the entries from each driver's ``MODULE_DEVICE_TABLE``. Such 9276f650f0SMauro Carvalho Chehabfiles can be used by various user mode policy agents to make sure all the 9376f650f0SMauro Carvalho Chehabright driver modules get loaded, either at boot time or later. 9476f650f0SMauro Carvalho Chehab 9576f650f0SMauro Carvalho ChehabSee ``linux/usb.h`` for full information about such table entries; or look 9676f650f0SMauro Carvalho Chehabat existing drivers. Each table entry describes one or more criteria to 9776f650f0SMauro Carvalho Chehabbe used when matching a driver to a device or class of devices. The 9876f650f0SMauro Carvalho Chehabspecific criteria are identified by bits set in "match_flags", paired 9976f650f0SMauro Carvalho Chehabwith field values. You can construct the criteria directly, or with 10076f650f0SMauro Carvalho Chehabmacros such as these, and use driver_info to store more information:: 10176f650f0SMauro Carvalho Chehab 10276f650f0SMauro Carvalho Chehab USB_DEVICE (vendorId, productId) 10376f650f0SMauro Carvalho Chehab ... matching devices with specified vendor and product ids 10476f650f0SMauro Carvalho Chehab USB_DEVICE_VER (vendorId, productId, lo, hi) 10576f650f0SMauro Carvalho Chehab ... like USB_DEVICE with lo <= productversion <= hi 10676f650f0SMauro Carvalho Chehab USB_INTERFACE_INFO (class, subclass, protocol) 10776f650f0SMauro Carvalho Chehab ... matching specified interface class info 10876f650f0SMauro Carvalho Chehab USB_DEVICE_INFO (class, subclass, protocol) 10976f650f0SMauro Carvalho Chehab ... matching specified device class info 11076f650f0SMauro Carvalho Chehab 11176f650f0SMauro Carvalho ChehabA short example, for a driver that supports several specific USB devices 11276f650f0SMauro Carvalho Chehaband their quirks, might have a MODULE_DEVICE_TABLE like this:: 11376f650f0SMauro Carvalho Chehab 11476f650f0SMauro Carvalho Chehab static const struct usb_device_id mydriver_id_table[] = { 11576f650f0SMauro Carvalho Chehab { USB_DEVICE (0x9999, 0xaaaa), driver_info: QUIRK_X }, 11676f650f0SMauro Carvalho Chehab { USB_DEVICE (0xbbbb, 0x8888), driver_info: QUIRK_Y|QUIRK_Z }, 11776f650f0SMauro Carvalho Chehab ... 11876f650f0SMauro Carvalho Chehab { } /* end with an all-zeroes entry */ 11976f650f0SMauro Carvalho Chehab }; 12076f650f0SMauro Carvalho Chehab MODULE_DEVICE_TABLE(usb, mydriver_id_table); 12176f650f0SMauro Carvalho Chehab 12276f650f0SMauro Carvalho ChehabMost USB device drivers should pass these tables to the USB subsystem as 12376f650f0SMauro Carvalho Chehabwell as to the module management subsystem. Not all, though: some driver 12476f650f0SMauro Carvalho Chehabframeworks connect using interfaces layered over USB, and so they won't 1259303c9d5SMauro Carvalho Chehabneed such a struct usb_driver. 12676f650f0SMauro Carvalho Chehab 12776f650f0SMauro Carvalho ChehabDrivers that connect directly to the USB subsystem should be declared 12876f650f0SMauro Carvalho Chehabsomething like this:: 12976f650f0SMauro Carvalho Chehab 13076f650f0SMauro Carvalho Chehab static struct usb_driver mydriver = { 13176f650f0SMauro Carvalho Chehab .name = "mydriver", 13276f650f0SMauro Carvalho Chehab .id_table = mydriver_id_table, 13376f650f0SMauro Carvalho Chehab .probe = my_probe, 13476f650f0SMauro Carvalho Chehab .disconnect = my_disconnect, 13576f650f0SMauro Carvalho Chehab 13676f650f0SMauro Carvalho Chehab /* 13776f650f0SMauro Carvalho Chehab if using the usb chardev framework: 13876f650f0SMauro Carvalho Chehab .minor = MY_USB_MINOR_START, 13976f650f0SMauro Carvalho Chehab .fops = my_file_ops, 14076f650f0SMauro Carvalho Chehab if exposing any operations through usbdevfs: 14176f650f0SMauro Carvalho Chehab .ioctl = my_ioctl, 14276f650f0SMauro Carvalho Chehab */ 14376f650f0SMauro Carvalho Chehab }; 14476f650f0SMauro Carvalho Chehab 14576f650f0SMauro Carvalho ChehabWhen the USB subsystem knows about a driver's device ID table, it's used when 14676f650f0SMauro Carvalho Chehabchoosing drivers to probe(). The thread doing new device processing checks 14776f650f0SMauro Carvalho Chehabdrivers' device ID entries from the ``MODULE_DEVICE_TABLE`` against interface 14876f650f0SMauro Carvalho Chehaband device descriptors for the device. It will only call ``probe()`` if there 14976f650f0SMauro Carvalho Chehabis a match, and the third argument to ``probe()`` will be the entry that 15076f650f0SMauro Carvalho Chehabmatched. 15176f650f0SMauro Carvalho Chehab 15276f650f0SMauro Carvalho ChehabIf you don't provide an ``id_table`` for your driver, then your driver may get 15376f650f0SMauro Carvalho Chehabprobed for each new device; the third parameter to ``probe()`` will be 15476f650f0SMauro Carvalho Chehab``NULL``. 155