2 * drivers/usb/driver.c - most of the driver model stuff for usb
4 * (C) Copyright 2005 Greg Kroah-Hartman <gregkh@suse.de>
6 * based on drivers/usb/usb.c which had the following copyrights:
7 * (C) Copyright Linus Torvalds 1999
8 * (C) Copyright Johannes Erdfelt 1999-2001
9 * (C) Copyright Andreas Gal 1999
10 * (C) Copyright Gregory P. Smith 1999
11 * (C) Copyright Deti Fliegl 1999 (new USB architecture)
12 * (C) Copyright Randy Dunlap 2000
13 * (C) Copyright David Brownell 2000-2004
14 * (C) Copyright Yggdrasil Computing, Inc. 2000
15 * (usb_device_id matching changes by Adam J. Richter)
16 * (C) Copyright Greg Kroah-Hartman 2002-2003
18 * NOTE! This is not actually a driver at all, rather this is
19 * just a collection of helper routines that implement the
20 * matching, probing, releasing, suspending and resuming for
25 #include <linux/device.h>
26 #include <linux/usb.h>
30 static int usb_match_one_id(struct usb_interface
*interface
,
31 const struct usb_device_id
*id
);
34 struct list_head node
;
35 struct usb_device_id id
;
41 * Adds a new dynamic USBdevice ID to this driver,
42 * and cause the driver to probe for all devices again.
44 static ssize_t
store_new_id(struct device_driver
*driver
,
45 const char *buf
, size_t count
)
47 struct usb_driver
*usb_drv
= to_usb_driver(driver
);
48 struct usb_dynid
*dynid
;
53 fields
= sscanf(buf
, "%x %x", &idVendor
, &idProduct
);
57 dynid
= kzalloc(sizeof(*dynid
), GFP_KERNEL
);
61 INIT_LIST_HEAD(&dynid
->node
);
62 dynid
->id
.idVendor
= idVendor
;
63 dynid
->id
.idProduct
= idProduct
;
64 dynid
->id
.match_flags
= USB_DEVICE_ID_MATCH_DEVICE
;
66 spin_lock(&usb_drv
->dynids
.lock
);
67 list_add_tail(&usb_drv
->dynids
.list
, &dynid
->node
);
68 spin_unlock(&usb_drv
->dynids
.lock
);
70 if (get_driver(driver
)) {
71 driver_attach(driver
);
77 static DRIVER_ATTR(new_id
, S_IWUSR
, NULL
, store_new_id
);
79 static int usb_create_newid_file(struct usb_driver
*usb_drv
)
83 if (usb_drv
->no_dynamic_id
)
86 if (usb_drv
->probe
!= NULL
)
87 error
= sysfs_create_file(&usb_drv
->driver
.kobj
,
88 &driver_attr_new_id
.attr
);
93 static void usb_remove_newid_file(struct usb_driver
*usb_drv
)
95 if (usb_drv
->no_dynamic_id
)
98 if (usb_drv
->probe
!= NULL
)
99 sysfs_remove_file(&usb_drv
->driver
.kobj
,
100 &driver_attr_new_id
.attr
);
103 static void usb_free_dynids(struct usb_driver
*usb_drv
)
105 struct usb_dynid
*dynid
, *n
;
107 spin_lock(&usb_drv
->dynids
.lock
);
108 list_for_each_entry_safe(dynid
, n
, &usb_drv
->dynids
.list
, node
) {
109 list_del(&dynid
->node
);
112 spin_unlock(&usb_drv
->dynids
.lock
);
115 static inline int usb_create_newid_file(struct usb_driver
*usb_drv
)
120 static void usb_remove_newid_file(struct usb_driver
*usb_drv
)
124 static inline void usb_free_dynids(struct usb_driver
*usb_drv
)
129 static const struct usb_device_id
*usb_match_dynamic_id(struct usb_interface
*intf
,
130 struct usb_driver
*drv
)
132 struct usb_dynid
*dynid
;
134 spin_lock(&drv
->dynids
.lock
);
135 list_for_each_entry(dynid
, &drv
->dynids
.list
, node
) {
136 if (usb_match_one_id(intf
, &dynid
->id
)) {
137 spin_unlock(&drv
->dynids
.lock
);
141 spin_unlock(&drv
->dynids
.lock
);
146 /* called from driver core with usb_bus_type.subsys writelock */
147 static int usb_probe_interface(struct device
*dev
)
149 struct usb_interface
* intf
= to_usb_interface(dev
);
150 struct usb_driver
* driver
= to_usb_driver(dev
->driver
);
151 const struct usb_device_id
*id
;
154 dev_dbg(dev
, "%s\n", __FUNCTION__
);
158 /* FIXME we'd much prefer to just resume it ... */
159 if (interface_to_usbdev(intf
)->state
== USB_STATE_SUSPENDED
)
160 return -EHOSTUNREACH
;
162 id
= usb_match_id(intf
, driver
->id_table
);
164 id
= usb_match_dynamic_id(intf
, driver
);
166 dev_dbg(dev
, "%s - got id\n", __FUNCTION__
);
168 /* Interface "power state" doesn't correspond to any hardware
169 * state whatsoever. We use it to record when it's bound to
170 * a driver that may start I/0: it's not frozen/quiesced.
173 intf
->condition
= USB_INTERFACE_BINDING
;
174 error
= driver
->probe(intf
, id
);
177 intf
->condition
= USB_INTERFACE_UNBOUND
;
179 intf
->condition
= USB_INTERFACE_BOUND
;
185 /* called from driver core with usb_bus_type.subsys writelock */
186 static int usb_unbind_interface(struct device
*dev
)
188 struct usb_interface
*intf
= to_usb_interface(dev
);
189 struct usb_driver
*driver
= to_usb_driver(intf
->dev
.driver
);
191 intf
->condition
= USB_INTERFACE_UNBINDING
;
193 /* release all urbs for this interface */
194 usb_disable_interface(interface_to_usbdev(intf
), intf
);
196 if (driver
&& driver
->disconnect
)
197 driver
->disconnect(intf
);
199 /* reset other interface state */
200 usb_set_interface(interface_to_usbdev(intf
),
201 intf
->altsetting
[0].desc
.bInterfaceNumber
,
203 usb_set_intfdata(intf
, NULL
);
204 intf
->condition
= USB_INTERFACE_UNBOUND
;
211 * usb_driver_claim_interface - bind a driver to an interface
212 * @driver: the driver to be bound
213 * @iface: the interface to which it will be bound; must be in the
214 * usb device's active configuration
215 * @priv: driver data associated with that interface
217 * This is used by usb device drivers that need to claim more than one
218 * interface on a device when probing (audio and acm are current examples).
219 * No device driver should directly modify internal usb_interface or
220 * usb_device structure members.
222 * Few drivers should need to use this routine, since the most natural
223 * way to bind to an interface is to return the private data from
224 * the driver's probe() method.
226 * Callers must own the device lock and the driver model's usb_bus_type.subsys
227 * writelock. So driver probe() entries don't need extra locking,
228 * but other call contexts may need to explicitly claim those locks.
230 int usb_driver_claim_interface(struct usb_driver
*driver
,
231 struct usb_interface
*iface
, void* priv
)
233 struct device
*dev
= &iface
->dev
;
238 dev
->driver
= &driver
->driver
;
239 usb_set_intfdata(iface
, priv
);
240 iface
->condition
= USB_INTERFACE_BOUND
;
243 /* if interface was already added, bind now; else let
244 * the future device_add() bind it, bypassing probe()
246 if (device_is_registered(dev
))
247 device_bind_driver(dev
);
251 EXPORT_SYMBOL(usb_driver_claim_interface
);
254 * usb_driver_release_interface - unbind a driver from an interface
255 * @driver: the driver to be unbound
256 * @iface: the interface from which it will be unbound
258 * This can be used by drivers to release an interface without waiting
259 * for their disconnect() methods to be called. In typical cases this
260 * also causes the driver disconnect() method to be called.
262 * This call is synchronous, and may not be used in an interrupt context.
263 * Callers must own the device lock and the driver model's usb_bus_type.subsys
264 * writelock. So driver disconnect() entries don't need extra locking,
265 * but other call contexts may need to explicitly claim those locks.
267 void usb_driver_release_interface(struct usb_driver
*driver
,
268 struct usb_interface
*iface
)
270 struct device
*dev
= &iface
->dev
;
272 /* this should never happen, don't release something that's not ours */
273 if (!dev
->driver
|| dev
->driver
!= &driver
->driver
)
276 /* don't release from within disconnect() */
277 if (iface
->condition
!= USB_INTERFACE_BOUND
)
280 /* don't release if the interface hasn't been added yet */
281 if (device_is_registered(dev
)) {
282 iface
->condition
= USB_INTERFACE_UNBINDING
;
283 device_release_driver(dev
);
287 usb_set_intfdata(iface
, NULL
);
288 iface
->condition
= USB_INTERFACE_UNBOUND
;
289 mark_quiesced(iface
);
291 EXPORT_SYMBOL(usb_driver_release_interface
);
293 /* returns 0 if no match, 1 if match */
294 static int usb_match_one_id(struct usb_interface
*interface
,
295 const struct usb_device_id
*id
)
297 struct usb_host_interface
*intf
;
298 struct usb_device
*dev
;
300 /* proc_connectinfo in devio.c may call us with id == NULL. */
304 intf
= interface
->cur_altsetting
;
305 dev
= interface_to_usbdev(interface
);
307 if ((id
->match_flags
& USB_DEVICE_ID_MATCH_VENDOR
) &&
308 id
->idVendor
!= le16_to_cpu(dev
->descriptor
.idVendor
))
311 if ((id
->match_flags
& USB_DEVICE_ID_MATCH_PRODUCT
) &&
312 id
->idProduct
!= le16_to_cpu(dev
->descriptor
.idProduct
))
315 /* No need to test id->bcdDevice_lo != 0, since 0 is never
316 greater than any unsigned number. */
317 if ((id
->match_flags
& USB_DEVICE_ID_MATCH_DEV_LO
) &&
318 (id
->bcdDevice_lo
> le16_to_cpu(dev
->descriptor
.bcdDevice
)))
321 if ((id
->match_flags
& USB_DEVICE_ID_MATCH_DEV_HI
) &&
322 (id
->bcdDevice_hi
< le16_to_cpu(dev
->descriptor
.bcdDevice
)))
325 if ((id
->match_flags
& USB_DEVICE_ID_MATCH_DEV_CLASS
) &&
326 (id
->bDeviceClass
!= dev
->descriptor
.bDeviceClass
))
329 if ((id
->match_flags
& USB_DEVICE_ID_MATCH_DEV_SUBCLASS
) &&
330 (id
->bDeviceSubClass
!= dev
->descriptor
.bDeviceSubClass
))
333 if ((id
->match_flags
& USB_DEVICE_ID_MATCH_DEV_PROTOCOL
) &&
334 (id
->bDeviceProtocol
!= dev
->descriptor
.bDeviceProtocol
))
337 if ((id
->match_flags
& USB_DEVICE_ID_MATCH_INT_CLASS
) &&
338 (id
->bInterfaceClass
!= intf
->desc
.bInterfaceClass
))
341 if ((id
->match_flags
& USB_DEVICE_ID_MATCH_INT_SUBCLASS
) &&
342 (id
->bInterfaceSubClass
!= intf
->desc
.bInterfaceSubClass
))
345 if ((id
->match_flags
& USB_DEVICE_ID_MATCH_INT_PROTOCOL
) &&
346 (id
->bInterfaceProtocol
!= intf
->desc
.bInterfaceProtocol
))
352 * usb_match_id - find first usb_device_id matching device or interface
353 * @interface: the interface of interest
354 * @id: array of usb_device_id structures, terminated by zero entry
356 * usb_match_id searches an array of usb_device_id's and returns
357 * the first one matching the device or interface, or null.
358 * This is used when binding (or rebinding) a driver to an interface.
359 * Most USB device drivers will use this indirectly, through the usb core,
360 * but some layered driver frameworks use it directly.
361 * These device tables are exported with MODULE_DEVICE_TABLE, through
362 * modutils, to support the driver loading functionality of USB hotplugging.
366 * The "match_flags" element in a usb_device_id controls which
367 * members are used. If the corresponding bit is set, the
368 * value in the device_id must match its corresponding member
369 * in the device or interface descriptor, or else the device_id
372 * "driver_info" is normally used only by device drivers,
373 * but you can create a wildcard "matches anything" usb_device_id
374 * as a driver's "modules.usbmap" entry if you provide an id with
375 * only a nonzero "driver_info" field. If you do this, the USB device
376 * driver's probe() routine should use additional intelligence to
377 * decide whether to bind to the specified interface.
379 * What Makes Good usb_device_id Tables:
381 * The match algorithm is very simple, so that intelligence in
382 * driver selection must come from smart driver id records.
383 * Unless you have good reasons to use another selection policy,
384 * provide match elements only in related groups, and order match
385 * specifiers from specific to general. Use the macros provided
386 * for that purpose if you can.
388 * The most specific match specifiers use device descriptor
389 * data. These are commonly used with product-specific matches;
390 * the USB_DEVICE macro lets you provide vendor and product IDs,
391 * and you can also match against ranges of product revisions.
392 * These are widely used for devices with application or vendor
393 * specific bDeviceClass values.
395 * Matches based on device class/subclass/protocol specifications
396 * are slightly more general; use the USB_DEVICE_INFO macro, or
397 * its siblings. These are used with single-function devices
398 * where bDeviceClass doesn't specify that each interface has
401 * Matches based on interface class/subclass/protocol are the
402 * most general; they let drivers bind to any interface on a
403 * multiple-function device. Use the USB_INTERFACE_INFO
404 * macro, or its siblings, to match class-per-interface style
405 * devices (as recorded in bDeviceClass).
407 * Within those groups, remember that not all combinations are
408 * meaningful. For example, don't give a product version range
409 * without vendor and product IDs; or specify a protocol without
410 * its associated class and subclass.
412 const struct usb_device_id
*usb_match_id(struct usb_interface
*interface
,
413 const struct usb_device_id
*id
)
415 /* proc_connectinfo in devio.c may call us with id == NULL. */
419 /* It is important to check that id->driver_info is nonzero,
420 since an entry that is all zeroes except for a nonzero
421 id->driver_info is the way to create an entry that
422 indicates that the driver want to examine every
423 device and interface. */
424 for (; id
->idVendor
|| id
->bDeviceClass
|| id
->bInterfaceClass
||
425 id
->driver_info
; id
++) {
426 if (usb_match_one_id(interface
, id
))
432 EXPORT_SYMBOL_GPL_FUTURE(usb_match_id
);
434 int usb_device_match(struct device
*dev
, struct device_driver
*drv
)
436 struct usb_interface
*intf
;
437 struct usb_driver
*usb_drv
;
438 const struct usb_device_id
*id
;
440 /* check for generic driver, which we don't match any device with */
441 if (drv
== &usb_generic_driver
)
444 intf
= to_usb_interface(dev
);
445 usb_drv
= to_usb_driver(drv
);
447 id
= usb_match_id(intf
, usb_drv
->id_table
);
451 id
= usb_match_dynamic_id(intf
, usb_drv
);
457 #ifdef CONFIG_HOTPLUG
460 * This sends an uevent to userspace, typically helping to load driver
461 * or other modules, configure the device, and more. Drivers can provide
462 * a MODULE_DEVICE_TABLE to help with module loading subtasks.
464 * We're called either from khubd (the typical case) or from root hub
465 * (init, kapmd, modprobe, rmmod, etc), but the agents need to handle
466 * delays in event delivery. Use sysfs (and DEVPATH) to make sure the
467 * device (and this configuration!) are still present.
469 static int usb_uevent(struct device
*dev
, char **envp
, int num_envp
,
470 char *buffer
, int buffer_size
)
472 struct usb_interface
*intf
;
473 struct usb_device
*usb_dev
;
474 struct usb_host_interface
*alt
;
481 /* driver is often null here; dev_dbg() would oops */
482 pr_debug ("usb %s: uevent\n", dev
->bus_id
);
484 /* Must check driver_data here, as on remove driver is always NULL */
485 if ((dev
->driver
== &usb_generic_driver
) ||
486 (dev
->driver_data
== &usb_generic_driver_data
))
489 intf
= to_usb_interface(dev
);
490 usb_dev
= interface_to_usbdev (intf
);
491 alt
= intf
->cur_altsetting
;
493 if (usb_dev
->devnum
< 0) {
494 pr_debug ("usb %s: already deleted?\n", dev
->bus_id
);
498 pr_debug ("usb %s: bus removed?\n", dev
->bus_id
);
502 #ifdef CONFIG_USB_DEVICEFS
503 /* If this is available, userspace programs can directly read
504 * all the device descriptors we don't tell them about. Or
505 * even act as usermode drivers.
507 * FIXME reduce hardwired intelligence here
509 if (add_uevent_var(envp
, num_envp
, &i
,
510 buffer
, buffer_size
, &length
,
511 "DEVICE=/proc/bus/usb/%03d/%03d",
512 usb_dev
->bus
->busnum
, usb_dev
->devnum
))
516 /* per-device configurations are common */
517 if (add_uevent_var(envp
, num_envp
, &i
,
518 buffer
, buffer_size
, &length
,
520 le16_to_cpu(usb_dev
->descriptor
.idVendor
),
521 le16_to_cpu(usb_dev
->descriptor
.idProduct
),
522 le16_to_cpu(usb_dev
->descriptor
.bcdDevice
)))
525 /* class-based driver binding models */
526 if (add_uevent_var(envp
, num_envp
, &i
,
527 buffer
, buffer_size
, &length
,
529 usb_dev
->descriptor
.bDeviceClass
,
530 usb_dev
->descriptor
.bDeviceSubClass
,
531 usb_dev
->descriptor
.bDeviceProtocol
))
534 if (add_uevent_var(envp
, num_envp
, &i
,
535 buffer
, buffer_size
, &length
,
536 "INTERFACE=%d/%d/%d",
537 alt
->desc
.bInterfaceClass
,
538 alt
->desc
.bInterfaceSubClass
,
539 alt
->desc
.bInterfaceProtocol
))
542 if (add_uevent_var(envp
, num_envp
, &i
,
543 buffer
, buffer_size
, &length
,
544 "MODALIAS=usb:v%04Xp%04Xd%04Xdc%02Xdsc%02Xdp%02Xic%02Xisc%02Xip%02X",
545 le16_to_cpu(usb_dev
->descriptor
.idVendor
),
546 le16_to_cpu(usb_dev
->descriptor
.idProduct
),
547 le16_to_cpu(usb_dev
->descriptor
.bcdDevice
),
548 usb_dev
->descriptor
.bDeviceClass
,
549 usb_dev
->descriptor
.bDeviceSubClass
,
550 usb_dev
->descriptor
.bDeviceProtocol
,
551 alt
->desc
.bInterfaceClass
,
552 alt
->desc
.bInterfaceSubClass
,
553 alt
->desc
.bInterfaceProtocol
))
563 static int usb_uevent(struct device
*dev
, char **envp
,
564 int num_envp
, char *buffer
, int buffer_size
)
569 #endif /* CONFIG_HOTPLUG */
572 * usb_register_driver - register a USB driver
573 * @new_driver: USB operations for the driver
574 * @owner: module owner of this driver.
576 * Registers a USB driver with the USB core. The list of unattached
577 * interfaces will be rescanned whenever a new driver is added, allowing
578 * the new driver to attach to any recognized devices.
579 * Returns a negative error code on failure and 0 on success.
581 * NOTE: if you want your driver to use the USB major number, you must call
582 * usb_register_dev() to enable that functionality. This function no longer
583 * takes care of that.
585 int usb_register_driver(struct usb_driver
*new_driver
, struct module
*owner
)
592 new_driver
->driver
.name
= (char *)new_driver
->name
;
593 new_driver
->driver
.bus
= &usb_bus_type
;
594 new_driver
->driver
.probe
= usb_probe_interface
;
595 new_driver
->driver
.remove
= usb_unbind_interface
;
596 new_driver
->driver
.owner
= owner
;
597 spin_lock_init(&new_driver
->dynids
.lock
);
598 INIT_LIST_HEAD(&new_driver
->dynids
.list
);
600 retval
= driver_register(&new_driver
->driver
);
603 pr_info("%s: registered new driver %s\n",
604 usbcore_name
, new_driver
->name
);
605 usbfs_update_special();
606 usb_create_newid_file(new_driver
);
608 printk(KERN_ERR
"%s: error %d registering driver %s\n",
609 usbcore_name
, retval
, new_driver
->name
);
614 EXPORT_SYMBOL_GPL_FUTURE(usb_register_driver
);
617 * usb_deregister - unregister a USB driver
618 * @driver: USB operations of the driver to unregister
619 * Context: must be able to sleep
621 * Unlinks the specified driver from the internal USB driver list.
623 * NOTE: If you called usb_register_dev(), you still need to call
624 * usb_deregister_dev() to clean up your driver's allocated minor numbers,
625 * this * call will no longer do it for you.
627 void usb_deregister(struct usb_driver
*driver
)
629 pr_info("%s: deregistering driver %s\n", usbcore_name
, driver
->name
);
631 usb_remove_newid_file(driver
);
632 usb_free_dynids(driver
);
633 driver_unregister(&driver
->driver
);
635 usbfs_update_special();
637 EXPORT_SYMBOL_GPL_FUTURE(usb_deregister
);
641 static int verify_suspended(struct device
*dev
, void *unused
)
643 if (dev
->driver
== NULL
)
645 return (dev
->power
.power_state
.event
== PM_EVENT_ON
) ? -EBUSY
: 0;
648 static int usb_generic_suspend(struct device
*dev
, pm_message_t message
)
650 struct usb_interface
*intf
;
651 struct usb_driver
*driver
;
654 /* USB devices enter SUSPEND state through their hubs, but can be
655 * marked for FREEZE as soon as their children are already idled.
656 * But those semantics are useless, so we equate the two (sigh).
658 if (dev
->driver
== &usb_generic_driver
) {
659 if (dev
->power
.power_state
.event
== message
.event
)
661 /* we need to rule out bogus requests through sysfs */
662 status
= device_for_each_child(dev
, NULL
, verify_suspended
);
665 return usb_port_suspend(to_usb_device(dev
));
668 if ((dev
->driver
== NULL
) ||
669 (dev
->driver_data
== &usb_generic_driver_data
))
672 intf
= to_usb_interface(dev
);
673 driver
= to_usb_driver(dev
->driver
);
675 /* with no hardware, USB interfaces only use FREEZE and ON states */
676 if (!is_active(intf
))
679 if (driver
->suspend
&& driver
->resume
) {
680 status
= driver
->suspend(intf
, message
);
682 dev_err(dev
, "%s error %d\n", "suspend", status
);
686 // FIXME else if there's no suspend method, disconnect...
687 dev_warn(dev
, "no suspend for driver %s?\n", driver
->name
);
694 static int usb_generic_resume(struct device
*dev
)
696 struct usb_interface
*intf
;
697 struct usb_driver
*driver
;
698 struct usb_device
*udev
;
701 if (dev
->power
.power_state
.event
== PM_EVENT_ON
)
704 /* mark things as "on" immediately, no matter what errors crop up */
705 dev
->power
.power_state
.event
= PM_EVENT_ON
;
707 /* devices resume through their hubs */
708 if (dev
->driver
== &usb_generic_driver
) {
709 udev
= to_usb_device(dev
);
710 if (udev
->state
== USB_STATE_NOTATTACHED
)
712 return usb_port_resume(udev
);
715 if ((dev
->driver
== NULL
) ||
716 (dev
->driver_data
== &usb_generic_driver_data
)) {
717 dev
->power
.power_state
.event
= PM_EVENT_FREEZE
;
721 intf
= to_usb_interface(dev
);
722 driver
= to_usb_driver(dev
->driver
);
724 udev
= interface_to_usbdev(intf
);
725 if (udev
->state
== USB_STATE_NOTATTACHED
)
728 /* if driver was suspended, it has a resume method;
729 * however, sysfs can wrongly mark things as suspended
730 * (on the "no suspend method" FIXME path above)
732 if (driver
->resume
) {
733 status
= driver
->resume(intf
);
735 dev_err(dev
, "%s error %d\n", "resume", status
);
739 dev_warn(dev
, "no resume for driver %s?\n", driver
->name
);
743 #endif /* CONFIG_PM */
745 struct bus_type usb_bus_type
= {
747 .match
= usb_device_match
,
748 .uevent
= usb_uevent
,
750 .suspend
= usb_generic_suspend
,
751 .resume
= usb_generic_resume
,