^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1) USB hotplugging
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2) ~~~~~~~~~~~~~~~
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4) Linux Hotplugging
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 5) =================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 6)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 7)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 8) In hotpluggable busses like USB (and Cardbus PCI), end-users plug devices
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 9) into the bus with power on. In most cases, users expect the devices to become
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 10) immediately usable. That means the system must do many things, including:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 11)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 12) - Find a driver that can handle the device. That may involve
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 13) loading a kernel module; newer drivers can use module-init-tools
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 14) to publish their device (and class) support to user utilities.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 15)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 16) - Bind a driver to that device. Bus frameworks do that using a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 17) device driver's probe() routine.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 18)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 19) - Tell other subsystems to configure the new device. Print
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 20) queues may need to be enabled, networks brought up, disk
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 21) partitions mounted, and so on. In some cases these will
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 22) be driver-specific actions.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 23)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 24) This involves a mix of kernel mode and user mode actions. Making devices
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 25) be immediately usable means that any user mode actions can't wait for an
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 26) administrator to do them: the kernel must trigger them, either passively
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 27) (triggering some monitoring daemon to invoke a helper program) or
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 28) actively (calling such a user mode helper program directly).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 29)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 30) Those triggered actions must support a system's administrative policies;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 31) such programs are called "policy agents" here. Typically they involve
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 32) shell scripts that dispatch to more familiar administration tools.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 33)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 34) Because some of those actions rely on information about drivers (metadata)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 35) that is currently available only when the drivers are dynamically linked,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 36) you get the best hotplugging when you configure a highly modular system.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 37)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 38) Kernel Hotplug Helper (``/sbin/hotplug``)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 39) =========================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 40)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 41) There is a kernel parameter: ``/proc/sys/kernel/hotplug``, which normally
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 42) holds the pathname ``/sbin/hotplug``. That parameter names a program
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 43) which the kernel may invoke at various times.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 44)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 45) The /sbin/hotplug program can be invoked by any subsystem as part of its
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 46) reaction to a configuration change, from a thread in that subsystem.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 47) Only one parameter is required: the name of a subsystem being notified of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 48) some kernel event. That name is used as the first key for further event
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 49) dispatch; any other argument and environment parameters are specified by
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 50) the subsystem making that invocation.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 51)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 52) Hotplug software and other resources is available at:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 53)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 54) http://linux-hotplug.sourceforge.net
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 55)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 56) Mailing list information is also available at that site.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 57)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 58)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 59) USB Policy Agent
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 60) ================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 61)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 62) The USB subsystem currently invokes ``/sbin/hotplug`` when USB devices
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 63) are added or removed from system. The invocation is done by the kernel
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 64) hub workqueue [hub_wq], or else as part of root hub initialization
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 65) (done by init, modprobe, kapmd, etc). Its single command line parameter
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 66) is the string "usb", and it passes these environment variables:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 67)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 68) ========== ============================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 69) ACTION ``add``, ``remove``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 70) PRODUCT USB vendor, product, and version codes (hex)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 71) TYPE device class codes (decimal)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 72) INTERFACE interface 0 class codes (decimal)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 73) ========== ============================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 74)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 75) If "usbdevfs" is configured, DEVICE and DEVFS are also passed. DEVICE is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 76) the pathname of the device, and is useful for devices with multiple and/or
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 77) alternate interfaces that complicate driver selection. By design, USB
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 78) hotplugging is independent of ``usbdevfs``: you can do most essential parts
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 79) of USB device setup without using that filesystem, and without running a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 80) user mode daemon to detect changes in system configuration.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 81)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 82) Currently available policy agent implementations can load drivers for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 83) modules, and can invoke driver-specific setup scripts. The newest ones
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 84) leverage USB module-init-tools support. Later agents might unload drivers.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 85)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 86)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 87) USB Modutils Support
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 88) ====================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 89)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 90) Current versions of module-init-tools will create a ``modules.usbmap`` file
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 91) which contains the entries from each driver's ``MODULE_DEVICE_TABLE``. Such
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 92) files can be used by various user mode policy agents to make sure all the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 93) right driver modules get loaded, either at boot time or later.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 94)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 95) See ``linux/usb.h`` for full information about such table entries; or look
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 96) at existing drivers. Each table entry describes one or more criteria to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 97) be used when matching a driver to a device or class of devices. The
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 98) specific criteria are identified by bits set in "match_flags", paired
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 99) with field values. You can construct the criteria directly, or with
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 100) macros such as these, and use driver_info to store more information::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 101)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 102) USB_DEVICE (vendorId, productId)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 103) ... matching devices with specified vendor and product ids
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 104) USB_DEVICE_VER (vendorId, productId, lo, hi)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 105) ... like USB_DEVICE with lo <= productversion <= hi
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 106) USB_INTERFACE_INFO (class, subclass, protocol)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 107) ... matching specified interface class info
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 108) USB_DEVICE_INFO (class, subclass, protocol)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 109) ... matching specified device class info
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 110)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 111) A short example, for a driver that supports several specific USB devices
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 112) and their quirks, might have a MODULE_DEVICE_TABLE like this::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 113)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 114) static const struct usb_device_id mydriver_id_table[] = {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 115) { USB_DEVICE (0x9999, 0xaaaa), driver_info: QUIRK_X },
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 116) { USB_DEVICE (0xbbbb, 0x8888), driver_info: QUIRK_Y|QUIRK_Z },
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 117) ...
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 118) { } /* end with an all-zeroes entry */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 119) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 120) MODULE_DEVICE_TABLE(usb, mydriver_id_table);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 121)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 122) Most USB device drivers should pass these tables to the USB subsystem as
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 123) well as to the module management subsystem. Not all, though: some driver
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 124) frameworks connect using interfaces layered over USB, and so they won't
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 125) need such a struct usb_driver.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 126)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 127) Drivers that connect directly to the USB subsystem should be declared
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 128) something like this::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 129)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 130) static struct usb_driver mydriver = {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 131) .name = "mydriver",
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 132) .id_table = mydriver_id_table,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 133) .probe = my_probe,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 134) .disconnect = my_disconnect,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 135)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 136) /*
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 137) if using the usb chardev framework:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 138) .minor = MY_USB_MINOR_START,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 139) .fops = my_file_ops,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 140) if exposing any operations through usbdevfs:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 141) .ioctl = my_ioctl,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 142) */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 143) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 144)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 145) When the USB subsystem knows about a driver's device ID table, it's used when
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 146) choosing drivers to probe(). The thread doing new device processing checks
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 147) drivers' device ID entries from the ``MODULE_DEVICE_TABLE`` against interface
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 148) and device descriptors for the device. It will only call ``probe()`` if there
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 149) is a match, and the third argument to ``probe()`` will be the entry that
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 150) matched.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 151)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 152) If you don't provide an ``id_table`` for your driver, then your driver may get
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 153) probed for each new device; the third parameter to ``probe()`` will be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 154) ``NULL``.
Orange Pi5 kernel
Deprecated Linux kernel 5.10.110 for OrangePi 5/5B/5+ boards
3 Commits
0 Branches
0 Tags