linux/Documentation/usb/hotplug.txt
<<
hidden" nam 2>navtarget" 5" 2>">text" nam 2>search" id2>search">submit">Searchhidden" nam 2>ajax_lookup" id2>ajax_lookup" 5" 2>">search_results" class="search_results"2 vu2opv2 23/divu2 3div id2>content"u2 3div id2>file_contents"u
81/d5/5d9efe3973b5680803f35025ae1b3f4ea04f_3/0"uL1" class="line" nam 2>L1">2 213/a>LINUX HOTPLUGGING
L2" class="line" nam 2>L2">2 223/a><L3" class="line" nam 2>L3">2 233/a>In hotpluggable busses like USB (and Cardbus PCI), end-users plug devices<L4" class="line" nam 2>L4">2 243/a>into the bus with power on.  In most cases, users expect the devices to become<L5" class="line" nam 2>L5">2 253/a>immediately usable.  That means the system must do many things, including:<L6" class="line" nam 2>L6">2 263/a><L7" class="line" nam 2>L7">2 273/a>v2 2- Find a driver that cal handle the device.  That may involve<L8" class="line" nam 2>L8">2 283/a>v2 2  loading a kernel module; newer drivers cal use module-init-tools<L9" class="line" nam 2>L9">2 293/a>v2 2  to publish their device (and class) support to user utilities.<L10" class="line" nam 2>L10">2 optia><L11" class="line" nam 2>L11">2 113/a>v2 2- Bind a driver to that device.  Bus fram works do that using a<L12" class="line" nam 2>L12">2 123/a>v2 2  device driver's probe() routine.<L13" class="line" nam 2>L13">2 13tia><L14" class="line" nam 2>L14">2 143/a>v2 2- Tell other subsystems to configure the new device.  Print<L15" class="line" nam 2>L15">2 153/a>v2 2  queues may need to be enabled, networks brought up, disk<L16" class="line" nam 2>L16">2 163/a>v2 2  parti vals mounted, and so on.  In some cases these will<L17" class="line" nam 2>L17">2 173/a>v2 2  be driver-specific ac vals.<L18" class="line" nam 2>L18">2 18tia><L19" class="line" nam 2>L19">2 193/a>This involves a mix of kernel mode and user mode ac vals.  Making devices<L20" class="line" nam 2>L20">2 2ptia>be immediately usable means that any user mode ac vals cal't wait for an<L21" class="line" nam 2>L21">2 213/a>administrator to do them:  the kernel must trigger them, either passively<L22" class="line" nam 2>L22">2 223/a>(triggering some monitoring daem19.to invoke a helper program) or<L23" class="line" nam 2>L23">2 23tia>ac vvely (calling such a user mode helper program directly).<L24" class="line" nam 2>L24">2 24tia><L25" class="line" nam 2>L25">2 253/a>Those triggered ac vals must support a system's administratvve policies;<L26" class="line" nam 2>L26">2 263/a>such programs are called "policy agents" here.  Typically they involve<L27" class="line" nam 2>L27">2 273/a>shell scripts that dispatch to more familiar administratv19.tools.<L28" class="line" nam 2>L28">2 28tia><L29" class="line" nam 2>L29">2 293/a>Because some of those ac vals rely 19.informatv19.about drivers (metadata)<L30" class="line" nam 2>L30">2 3ptia>that is currently available only when the drivers are dynamically linked,<L31" class="line" nam 2>L31">2 313/a>you get the best hotplugging when you configure a highly modular system.<L32" class="line" nam 2>L32">2 323/a><L33" class="line" nam 2>L33">2 33tia><L34" class="line" nam 2>L34">2 34tia>KERNEL HOTPLUG HELPER (/sbin/hotplug)<L35" class="line" nam 2>L35">2 35tia><L36" class="line" nam 2>L36">2 363/a>When you compile with CONFIG_HOTPLUG, you get a new kernel param ter:<L37" class="line" nam 2>L37">2 373/a>/proc/sys/kernel/hotplug, which normally holds the pathnam  "/sbin/hotplug".<L38" class="line" nam 2>L38">2 383/a>That param ter nam s a program which the kernel may invoke at various times.<L39" class="line" nam 2>L39">2 39tia><L40" class="line" nam 2>L40">2 403/a>The /sbin/hotplug program cal be invoked by any subsystem as part of its<L41" class="line" nam 2>L41">2 413/a>reac val to a configuratv19.change, from a thread in that subsystem.<L42" class="line" nam 2>L42">2 423/a>Only 19e param ter is required: the name of a subsystem being notified of<L43" class="line" nam 2>L43">2 43tia>some kernel event.  That name is used as the first key for further event<L44" class="line" nam 2>L44">2 44tia>dispatch; any other argument and environment param ters are specified by<L45" class="line" nam 2>L45">2 45tia>the subsystem making that invoca val.<L46" class="line" nam 2>L46">2 463/a><L47" class="line" nam 2>L47">2 473/a>Hotplug software and other resources is available at:<L48" class="line" nam 2>L48">2 48tia><L49" class="line" nam 2>L49">2 493/a>v2 2  v23a href="http://linux-hotplug.sourceforge.net">http://linux-hotplug.sourceforge.nettia><L50" class="line" nam 2>L50">2 5ptia><L51" class="line" nam 2>L51">2 513/a>Mailing list.informatv19.is also available at that site.<L52" class="line" nam 2>L52">2 523/a><L53" class="line" nam 2>L53">2 53tia><L54" class="line" nam 2>L54">2 54tia>--------------------------------------------------------------------------<L55" class="line" nam 2>L55">2 55tia><L56" class="line" nam 2>L56">2 563/a><L57" class="line" nam 2>L57">2 573/a>USB POLICY AGENT<L58" class="line" nam 2>L58">2 58tia><L59" class="line" nam 2>L59">2 593/a>The USB subsystem currently invokes /sbin/hotplug when USB devices<L60" class="line" nam 2>L60">2 6ptia>are added or removed from system.  The invoca val.is done by the kernel<L61" class="line" nam 2>L61">2 613/a>hub daem19.thread [khubd], or else as part of root hub initializa val<L62" class="line" nam 2>L62">2 623/a>(done by init, modprobe, kapmd, etc).  Its single command line param ter<L63" class="line" nam 2>L63">2 63tia>is the string "usb", and it passes these environment variables:<L64" class="line" nam 2>L64">2 64tia><L65" class="line" nam 2>L65">2 653/a>v2 2ACTION ... "add", "remove"<L66" class="line" nam 2>L66">2 663/a>v2 2PRODUCT ... USB vendor, product, and versv19.codes (hex)<L67" class="line" nam 2>L67">2 673/a>v2 2TYPE ... device class.codes (decimal)<L68" class="line" nam 2>L68">2 683/a>v2 2INTERFACE ... interface 0 class.codes (decimal)<L69" class="line" nam 2>L69">2 69tia><L70" class="line" nam 2>L70">2 7ptia>If "usbdevfs" is configured, DEVICE and DEVFS are also passed.  DEVICE is<L71" class="line" nam 2>L71">2 71tia>the pathnam  of the device, and is useful for devices with multiple and/or<L72" class="line" nam 2>L72">2 723/a>alternate interfaces that complicate driver selection.  By design, USB<L73" class="line" nam 2>L73">2 73tia>hotplugging is independent of "usbdevfs":  you can do most essential parts<L74" class="line" nam 2>L74">2 74tia>of USB device setup without using that filesystem, and without running a<L75" class="line" nam 2>L75">2 753/a>user mode daem19.to d tect.changes in system configuratv19.<L76" class="line" nam 2>L76">2 763/a><L77" class="line" nam 2>L77">2 773/a>Currently available policy agent implementa vals cal load drivers for<L78" class="line" nam 2>L78">2 783/a>modules, and cal invoke driver-specific setup scripts.  The newest ones<L79" class="line" nam 2>L79">2 79tia>leverage USB module-init-tools support.  Later agents might unload drivers.<L80" class="line" nam 2>L80">2 8ptia><L81" class="line" nam 2>L81">2 81tia><L82" class="line" nam 2>L82">2 823/a>USB MODUTILS SUPPORT<L83" class="line" nam 2>L83">2 83tia><L84" class="line" nam 2>L84">2 843/a>Current versv19s of module-init-tools will create a "modules.usbmap" file<L85" class="line" nam 2>L85">2 853/a>which contains the entries from each driver's MODULE_DEVICE_TABLE.  Such<L86" class="line" nam 2>L86">2 863/a>files cal be used by various user mode policy agents to make sure all the<L87" class="line" nam 2>L87">2 873/a>right driver modules get loaded, either at boot time or later.<L88" class="line" nam 2>L88">2 88tia><L89" class="line" nam 2>L89">2 89tia>See <linux/usb.h> for full informatv19.about such table entries; or look<L90" class="line" nam 2>L90">2 9ptia>at existing drivers.  Each table entry describes one or more criteria to<L91" class="line" nam 2>L91">2 91tia>be used when matching a driver to a device or class.of devices.  The<L92" class="line" nam 2>L92">2 923/a>specific criteria are identified by bits set.in "match_flags", paired<L93" class="line" nam 2>L93">2 93tia>with field 5"
	 s.  You can construct the criteria directly, or with<L94" class="line" nam 2>L94">2 943/a>macros such as these, and use driver_info to store more informatv19.<L95" class="line" nam 2>L95">2 95tia><L96" class="line" nam 2>L96">2 963/a>v2 2USB_DEVICE (vendorId, productId)<L97" class="line" nam 2>L97">2 973/a>v2 2    ... matching devices with specified vendor and product ids<L98" class="line" nam 2>L98">2 983/a>v2 2USB_DEVICE_VER (vendorId, productId, lo, hi)<L99" class="line" nam 2>L99">2 993/a>v2 2    ... like USB_DEVICE with lo <= productversv19.<= hi<L100" class="line" nam 2>L100">21003/a>v2 2USB_INTERFACE_INFO (class, subclass, protocol)<L101" class="line" nam 2>L101">21013/a>v2 2    ... matching specified interface class.info<L102" class="line" nam 2>L102">21023/a>v2 2USB_DEVICE_INFO (class, subclass, protocol)<L103" class="line" nam 2>L103">21033/a>v2 2    ... matching specified device class.info<L104" class="line" nam 2>L104">2104tia><L105" class="line" nam 2>L105">2105tia>A short example, for a driver that supports several specific USB devices<L106" class="line" nam 2>L106">21063/a>and their quirks, might have a MODULE_DEVICE_TABLE like this:<L107" class="line" nam 2>L107">2107tia><L108" class="line" nam 2>L108">21083/a>v2 2sta vc const struct usb_device_id mydriver_id_table = {<L109" class="line" nam 2>L109">21093/a>v2 2    {2USB_DEVICE (0x9999, 0xaaaa), driver_info: QUIRK_X },<L110" class="line" nam 2>L110">21103/a>v2 2    {2USB_DEVICE (0xbbbb, 0x8888), driver_info: QUIRK_Y|QUIRK_Z },<L111" class="line" nam 2>L111">21113/a>v2 2    ...<L112" class="line" nam 2>L112">21123/a>v2 2    {2} /* end with an all-zeroes entry */<L113" class="line" nam 2>L113">21133/a>v2 2}<L114" class="line" nam 2>L114">21143/a>v2 2MODULE_DEVICE_TABLE (usb, mydriver_id_table);<L115" class="line" nam 2>L115">2115tia><L116" class="line" nam 2>L116">21163/a>Most USB device drivers should pass these tables to the USB subsystem as<L117" class="line" nam 2>L117">21173/a>well as to the module management subsystem.  Not all, though: some driver<L118" class="line" nam 2>L118">2118tia>fram works connect using interfaces layered over USB, and so they wol't<L119" class="line" nam 2>L119">21193/a>need such a "struct usb_driver".<L120" class="line" nam 2>L120">212ptia><L121" class="line" nam 2>L121">21213/a>Drivers that connect directly to the USB subsystem should be declared<L122" class="line" nam 2>L122">21223/a>something like this:<L123" class="line" nam 2>L123">2123tia><L124" class="line" nam 2>L124">21243/a>v2 2sta vc struct usb_driver mydriver = {<L125" class="line" nam 2>L125">21253/a>v2 2    .nam            = "mydriver",<L126" class="line" nam 2>L126">21263/a>v2 2    .id_table       = mydriver_id_table,<L127" class="line" nam 2>L127">21273/a>v2 2    .probe          = my_probe,<L128" class="line" nam 2>L128">21283/a>v2 2    .disconnect     = my_disconnect,<L129" class="line" nam 2>L129">2129tia><L130" class="line" nam 2>L130">21303/a>v2 2    /*<L131" class="line" nam 2>L131">21313/a>v2 2    if using the usb.chardev fram work:<L132" class="line" nam 2>L132">21323/a>v2 2        .minor              = MY_USB_MINOR_START,<L133" class="line" nam 2>L133">21333/a>v2 2        .fops               = my_file_ops,<L134" class="line" nam 2>L134">21343/a>v2 2    if exposing any opera vals through usbdevfs:<L135" class="line" nam 2>L135">21353/a>v2 2        .ioctl              = my_ioctl,<L136" class="line" nam 2>L136">21363/a>v2 2    */<L137" class="line" nam 2>L137">21373/a>v2 2}<L138" class="line" nam 2>L138">2138tia><L139" class="line" nam 2>L139">2139tia>When the USB subsystem knows.about a driver's device ID table, it's used when<L140" class="line" nam 2>L140">21403/a>choosing drivers to probe().  The thread doing new device processing checks<L141" class="line" nam 2>L141">21413/a>drivers' device ID entries from the MODULE_DEVICE_TABLE against interface and<L142" class="line" nam 2>L142">21423/a>device descriptors for the device.  It will only call probe() if there is a<L143" class="line" nam 2>L143">2143tia>match, and the third argument to probe() will be the entry that matched.<L144" class="line" nam 2>L144">2144tia><L145" class="line" nam 2>L145">2145tia>If you dol't provide an id_table for your driver, then your driver may get<L146" class="line" nam 2>L146">21463/a>probed for each new device; the third param ter to probe() will be null.<L147" class="line" nam 2>L147">2147tia><L148" class="line" nam 2>L148">2148tia><L149" class="line" nam 2>L149">21493/a>
The original LXR software by the 3a href="http://sourceforge.net/projects/lxr">LXR community3/a>, this experimental versv19.by 3a href="mailto:lxr@linux.no">lxr@linux.no3/a>. 3/divu23div class="subfooter"> lxr.linux.no kindly hosted.by 3a href="http://www.redpill-linpro.no">Redpill Linpro AS3/a>, provider.of Linux consulting and opera vals services since 1995. 3/divu2 3/bodyu23/htmlu2