Merge branch 'master' into upstream
[linux-2.6] / drivers / usb / core / usb.c
1 /*
2  * drivers/usb/usb.c
3  *
4  * (C) Copyright Linus Torvalds 1999
5  * (C) Copyright Johannes Erdfelt 1999-2001
6  * (C) Copyright Andreas Gal 1999
7  * (C) Copyright Gregory P. Smith 1999
8  * (C) Copyright Deti Fliegl 1999 (new USB architecture)
9  * (C) Copyright Randy Dunlap 2000
10  * (C) Copyright David Brownell 2000-2004
11  * (C) Copyright Yggdrasil Computing, Inc. 2000
12  *     (usb_device_id matching changes by Adam J. Richter)
13  * (C) Copyright Greg Kroah-Hartman 2002-2003
14  *
15  * NOTE! This is not actually a driver at all, rather this is
16  * just a collection of helper routines that implement the
17  * generic USB things that the real drivers can use..
18  *
19  * Think of this as a "USB library" rather than anything else.
20  * It should be considered a slave, with no callbacks. Callbacks
21  * are evil.
22  */
23
24 #include <linux/module.h>
25 #include <linux/string.h>
26 #include <linux/bitops.h>
27 #include <linux/slab.h>
28 #include <linux/interrupt.h>  /* for in_interrupt() */
29 #include <linux/kmod.h>
30 #include <linux/init.h>
31 #include <linux/spinlock.h>
32 #include <linux/errno.h>
33 #include <linux/smp_lock.h>
34 #include <linux/usb.h>
35 #include <linux/mutex.h>
36 #include <linux/workqueue.h>
37
38 #include <asm/io.h>
39 #include <asm/scatterlist.h>
40 #include <linux/mm.h>
41 #include <linux/dma-mapping.h>
42
43 #include "hcd.h"
44 #include "usb.h"
45
46
47 const char *usbcore_name = "usbcore";
48
49 static int nousb;       /* Disable USB when built into kernel image */
50
51 struct workqueue_struct *ksuspend_usb_wq;       /* For autosuspend */
52
53
54 /**
55  * usb_ifnum_to_if - get the interface object with a given interface number
56  * @dev: the device whose current configuration is considered
57  * @ifnum: the desired interface
58  *
59  * This walks the device descriptor for the currently active configuration
60  * and returns a pointer to the interface with that particular interface
61  * number, or null.
62  *
63  * Note that configuration descriptors are not required to assign interface
64  * numbers sequentially, so that it would be incorrect to assume that
65  * the first interface in that descriptor corresponds to interface zero.
66  * This routine helps device drivers avoid such mistakes.
67  * However, you should make sure that you do the right thing with any
68  * alternate settings available for this interfaces.
69  *
70  * Don't call this function unless you are bound to one of the interfaces
71  * on this device or you have locked the device!
72  */
73 struct usb_interface *usb_ifnum_to_if(const struct usb_device *dev,
74                                       unsigned ifnum)
75 {
76         struct usb_host_config *config = dev->actconfig;
77         int i;
78
79         if (!config)
80                 return NULL;
81         for (i = 0; i < config->desc.bNumInterfaces; i++)
82                 if (config->interface[i]->altsetting[0]
83                                 .desc.bInterfaceNumber == ifnum)
84                         return config->interface[i];
85
86         return NULL;
87 }
88
89 /**
90  * usb_altnum_to_altsetting - get the altsetting structure with a given
91  *      alternate setting number.
92  * @intf: the interface containing the altsetting in question
93  * @altnum: the desired alternate setting number
94  *
95  * This searches the altsetting array of the specified interface for
96  * an entry with the correct bAlternateSetting value and returns a pointer
97  * to that entry, or null.
98  *
99  * Note that altsettings need not be stored sequentially by number, so
100  * it would be incorrect to assume that the first altsetting entry in
101  * the array corresponds to altsetting zero.  This routine helps device
102  * drivers avoid such mistakes.
103  *
104  * Don't call this function unless you are bound to the intf interface
105  * or you have locked the device!
106  */
107 struct usb_host_interface *usb_altnum_to_altsetting(const struct usb_interface *intf,
108                                                     unsigned int altnum)
109 {
110         int i;
111
112         for (i = 0; i < intf->num_altsetting; i++) {
113                 if (intf->altsetting[i].desc.bAlternateSetting == altnum)
114                         return &intf->altsetting[i];
115         }
116         return NULL;
117 }
118
119 struct find_interface_arg {
120         int minor;
121         struct usb_interface *interface;
122 };
123
124 static int __find_interface(struct device * dev, void * data)
125 {
126         struct find_interface_arg *arg = data;
127         struct usb_interface *intf;
128
129         /* can't look at usb devices, only interfaces */
130         if (is_usb_device(dev))
131                 return 0;
132
133         intf = to_usb_interface(dev);
134         if (intf->minor != -1 && intf->minor == arg->minor) {
135                 arg->interface = intf;
136                 return 1;
137         }
138         return 0;
139 }
140
141 /**
142  * usb_find_interface - find usb_interface pointer for driver and device
143  * @drv: the driver whose current configuration is considered
144  * @minor: the minor number of the desired device
145  *
146  * This walks the driver device list and returns a pointer to the interface 
147  * with the matching minor.  Note, this only works for devices that share the
148  * USB major number.
149  */
150 struct usb_interface *usb_find_interface(struct usb_driver *drv, int minor)
151 {
152         struct find_interface_arg argb;
153         int retval;
154
155         argb.minor = minor;
156         argb.interface = NULL;
157         /* eat the error, it will be in argb.interface */
158         retval = driver_for_each_device(&drv->drvwrap.driver, NULL, &argb,
159                                         __find_interface);
160         return argb.interface;
161 }
162
163 /**
164  * usb_release_dev - free a usb device structure when all users of it are finished.
165  * @dev: device that's been disconnected
166  *
167  * Will be called only by the device core when all users of this usb device are
168  * done.
169  */
170 static void usb_release_dev(struct device *dev)
171 {
172         struct usb_device *udev;
173
174         udev = to_usb_device(dev);
175
176 #ifdef  CONFIG_USB_SUSPEND
177         cancel_delayed_work(&udev->autosuspend);
178         flush_workqueue(ksuspend_usb_wq);
179 #endif
180         usb_destroy_configuration(udev);
181         usb_put_hcd(bus_to_hcd(udev->bus));
182         kfree(udev->product);
183         kfree(udev->manufacturer);
184         kfree(udev->serial);
185         kfree(udev);
186 }
187
188 #ifdef  CONFIG_PM
189
190 static int ksuspend_usb_init(void)
191 {
192         ksuspend_usb_wq = create_singlethread_workqueue("ksuspend_usbd");
193         if (!ksuspend_usb_wq)
194                 return -ENOMEM;
195         return 0;
196 }
197
198 static void ksuspend_usb_cleanup(void)
199 {
200         destroy_workqueue(ksuspend_usb_wq);
201 }
202
203 #else
204
205 #define ksuspend_usb_init()     0
206 #define ksuspend_usb_cleanup()  do {} while (0)
207
208 #endif
209
210 #ifdef  CONFIG_USB_SUSPEND
211
212 /* usb_autosuspend_work - callback routine to autosuspend a USB device */
213 static void usb_autosuspend_work(void *_udev)
214 {
215         struct usb_device       *udev = _udev;
216
217         usb_pm_lock(udev);
218         udev->auto_pm = 1;
219         usb_suspend_both(udev, PMSG_SUSPEND);
220         usb_pm_unlock(udev);
221 }
222
223 #else
224
225 static void usb_autosuspend_work(void *_udev)
226 {}
227
228 #endif
229
230 /**
231  * usb_alloc_dev - usb device constructor (usbcore-internal)
232  * @parent: hub to which device is connected; null to allocate a root hub
233  * @bus: bus used to access the device
234  * @port1: one-based index of port; ignored for root hubs
235  * Context: !in_interrupt ()
236  *
237  * Only hub drivers (including virtual root hub drivers for host
238  * controllers) should ever call this.
239  *
240  * This call may not be used in a non-sleeping context.
241  */
242 struct usb_device *
243 usb_alloc_dev(struct usb_device *parent, struct usb_bus *bus, unsigned port1)
244 {
245         struct usb_device *dev;
246
247         dev = kzalloc(sizeof(*dev), GFP_KERNEL);
248         if (!dev)
249                 return NULL;
250
251         if (!usb_get_hcd(bus_to_hcd(bus))) {
252                 kfree(dev);
253                 return NULL;
254         }
255
256         device_initialize(&dev->dev);
257         dev->dev.bus = &usb_bus_type;
258         dev->dev.dma_mask = bus->controller->dma_mask;
259         dev->dev.release = usb_release_dev;
260         dev->state = USB_STATE_ATTACHED;
261
262         /* This magic assignment distinguishes devices from interfaces */
263         dev->dev.platform_data = &usb_generic_driver;
264
265         INIT_LIST_HEAD(&dev->ep0.urb_list);
266         dev->ep0.desc.bLength = USB_DT_ENDPOINT_SIZE;
267         dev->ep0.desc.bDescriptorType = USB_DT_ENDPOINT;
268         /* ep0 maxpacket comes later, from device descriptor */
269         dev->ep_in[0] = dev->ep_out[0] = &dev->ep0;
270
271         /* Save readable and stable topology id, distinguishing devices
272          * by location for diagnostics, tools, driver model, etc.  The
273          * string is a path along hub ports, from the root.  Each device's
274          * dev->devpath will be stable until USB is re-cabled, and hubs
275          * are often labeled with these port numbers.  The bus_id isn't
276          * as stable:  bus->busnum changes easily from modprobe order,
277          * cardbus or pci hotplugging, and so on.
278          */
279         if (unlikely (!parent)) {
280                 dev->devpath [0] = '0';
281
282                 dev->dev.parent = bus->controller;
283                 sprintf (&dev->dev.bus_id[0], "usb%d", bus->busnum);
284         } else {
285                 /* match any labeling on the hubs; it's one-based */
286                 if (parent->devpath [0] == '0')
287                         snprintf (dev->devpath, sizeof dev->devpath,
288                                 "%d", port1);
289                 else
290                         snprintf (dev->devpath, sizeof dev->devpath,
291                                 "%s.%d", parent->devpath, port1);
292
293                 dev->dev.parent = &parent->dev;
294                 sprintf (&dev->dev.bus_id[0], "%d-%s",
295                         bus->busnum, dev->devpath);
296
297                 /* hub driver sets up TT records */
298         }
299
300         dev->portnum = port1;
301         dev->bus = bus;
302         dev->parent = parent;
303         INIT_LIST_HEAD(&dev->filelist);
304
305 #ifdef  CONFIG_PM
306         mutex_init(&dev->pm_mutex);
307         INIT_WORK(&dev->autosuspend, usb_autosuspend_work, dev);
308 #endif
309         return dev;
310 }
311
312 /**
313  * usb_get_dev - increments the reference count of the usb device structure
314  * @dev: the device being referenced
315  *
316  * Each live reference to a device should be refcounted.
317  *
318  * Drivers for USB interfaces should normally record such references in
319  * their probe() methods, when they bind to an interface, and release
320  * them by calling usb_put_dev(), in their disconnect() methods.
321  *
322  * A pointer to the device with the incremented reference counter is returned.
323  */
324 struct usb_device *usb_get_dev(struct usb_device *dev)
325 {
326         if (dev)
327                 get_device(&dev->dev);
328         return dev;
329 }
330
331 /**
332  * usb_put_dev - release a use of the usb device structure
333  * @dev: device that's been disconnected
334  *
335  * Must be called when a user of a device is finished with it.  When the last
336  * user of the device calls this function, the memory of the device is freed.
337  */
338 void usb_put_dev(struct usb_device *dev)
339 {
340         if (dev)
341                 put_device(&dev->dev);
342 }
343
344 /**
345  * usb_get_intf - increments the reference count of the usb interface structure
346  * @intf: the interface being referenced
347  *
348  * Each live reference to a interface must be refcounted.
349  *
350  * Drivers for USB interfaces should normally record such references in
351  * their probe() methods, when they bind to an interface, and release
352  * them by calling usb_put_intf(), in their disconnect() methods.
353  *
354  * A pointer to the interface with the incremented reference counter is
355  * returned.
356  */
357 struct usb_interface *usb_get_intf(struct usb_interface *intf)
358 {
359         if (intf)
360                 get_device(&intf->dev);
361         return intf;
362 }
363
364 /**
365  * usb_put_intf - release a use of the usb interface structure
366  * @intf: interface that's been decremented
367  *
368  * Must be called when a user of an interface is finished with it.  When the
369  * last user of the interface calls this function, the memory of the interface
370  * is freed.
371  */
372 void usb_put_intf(struct usb_interface *intf)
373 {
374         if (intf)
375                 put_device(&intf->dev);
376 }
377
378
379 /*                      USB device locking
380  *
381  * USB devices and interfaces are locked using the semaphore in their
382  * embedded struct device.  The hub driver guarantees that whenever a
383  * device is connected or disconnected, drivers are called with the
384  * USB device locked as well as their particular interface.
385  *
386  * Complications arise when several devices are to be locked at the same
387  * time.  Only hub-aware drivers that are part of usbcore ever have to
388  * do this; nobody else needs to worry about it.  The rule for locking
389  * is simple:
390  *
391  *      When locking both a device and its parent, always lock the
392  *      the parent first.
393  */
394
395 /**
396  * usb_lock_device_for_reset - cautiously acquire the lock for a
397  *      usb device structure
398  * @udev: device that's being locked
399  * @iface: interface bound to the driver making the request (optional)
400  *
401  * Attempts to acquire the device lock, but fails if the device is
402  * NOTATTACHED or SUSPENDED, or if iface is specified and the interface
403  * is neither BINDING nor BOUND.  Rather than sleeping to wait for the
404  * lock, the routine polls repeatedly.  This is to prevent deadlock with
405  * disconnect; in some drivers (such as usb-storage) the disconnect()
406  * or suspend() method will block waiting for a device reset to complete.
407  *
408  * Returns a negative error code for failure, otherwise 1 or 0 to indicate
409  * that the device will or will not have to be unlocked.  (0 can be
410  * returned when an interface is given and is BINDING, because in that
411  * case the driver already owns the device lock.)
412  */
413 int usb_lock_device_for_reset(struct usb_device *udev,
414                               const struct usb_interface *iface)
415 {
416         unsigned long jiffies_expire = jiffies + HZ;
417
418         if (udev->state == USB_STATE_NOTATTACHED)
419                 return -ENODEV;
420         if (udev->state == USB_STATE_SUSPENDED)
421                 return -EHOSTUNREACH;
422         if (iface) {
423                 switch (iface->condition) {
424                   case USB_INTERFACE_BINDING:
425                         return 0;
426                   case USB_INTERFACE_BOUND:
427                         break;
428                   default:
429                         return -EINTR;
430                 }
431         }
432
433         while (usb_trylock_device(udev) != 0) {
434
435                 /* If we can't acquire the lock after waiting one second,
436                  * we're probably deadlocked */
437                 if (time_after(jiffies, jiffies_expire))
438                         return -EBUSY;
439
440                 msleep(15);
441                 if (udev->state == USB_STATE_NOTATTACHED)
442                         return -ENODEV;
443                 if (udev->state == USB_STATE_SUSPENDED)
444                         return -EHOSTUNREACH;
445                 if (iface && iface->condition != USB_INTERFACE_BOUND)
446                         return -EINTR;
447         }
448         return 1;
449 }
450
451
452 static struct usb_device *match_device(struct usb_device *dev,
453                                        u16 vendor_id, u16 product_id)
454 {
455         struct usb_device *ret_dev = NULL;
456         int child;
457
458         dev_dbg(&dev->dev, "check for vendor %04x, product %04x ...\n",
459             le16_to_cpu(dev->descriptor.idVendor),
460             le16_to_cpu(dev->descriptor.idProduct));
461
462         /* see if this device matches */
463         if ((vendor_id == le16_to_cpu(dev->descriptor.idVendor)) &&
464             (product_id == le16_to_cpu(dev->descriptor.idProduct))) {
465                 dev_dbg (&dev->dev, "matched this device!\n");
466                 ret_dev = usb_get_dev(dev);
467                 goto exit;
468         }
469
470         /* look through all of the children of this device */
471         for (child = 0; child < dev->maxchild; ++child) {
472                 if (dev->children[child]) {
473                         usb_lock_device(dev->children[child]);
474                         ret_dev = match_device(dev->children[child],
475                                                vendor_id, product_id);
476                         usb_unlock_device(dev->children[child]);
477                         if (ret_dev)
478                                 goto exit;
479                 }
480         }
481 exit:
482         return ret_dev;
483 }
484
485 /**
486  * usb_find_device - find a specific usb device in the system
487  * @vendor_id: the vendor id of the device to find
488  * @product_id: the product id of the device to find
489  *
490  * Returns a pointer to a struct usb_device if such a specified usb
491  * device is present in the system currently.  The usage count of the
492  * device will be incremented if a device is found.  Make sure to call
493  * usb_put_dev() when the caller is finished with the device.
494  *
495  * If a device with the specified vendor and product id is not found,
496  * NULL is returned.
497  */
498 struct usb_device *usb_find_device(u16 vendor_id, u16 product_id)
499 {
500         struct list_head *buslist;
501         struct usb_bus *bus;
502         struct usb_device *dev = NULL;
503         
504         mutex_lock(&usb_bus_list_lock);
505         for (buslist = usb_bus_list.next;
506              buslist != &usb_bus_list; 
507              buslist = buslist->next) {
508                 bus = container_of(buslist, struct usb_bus, bus_list);
509                 if (!bus->root_hub)
510                         continue;
511                 usb_lock_device(bus->root_hub);
512                 dev = match_device(bus->root_hub, vendor_id, product_id);
513                 usb_unlock_device(bus->root_hub);
514                 if (dev)
515                         goto exit;
516         }
517 exit:
518         mutex_unlock(&usb_bus_list_lock);
519         return dev;
520 }
521
522 /**
523  * usb_get_current_frame_number - return current bus frame number
524  * @dev: the device whose bus is being queried
525  *
526  * Returns the current frame number for the USB host controller
527  * used with the given USB device.  This can be used when scheduling
528  * isochronous requests.
529  *
530  * Note that different kinds of host controller have different
531  * "scheduling horizons".  While one type might support scheduling only
532  * 32 frames into the future, others could support scheduling up to
533  * 1024 frames into the future.
534  */
535 int usb_get_current_frame_number(struct usb_device *dev)
536 {
537         return usb_hcd_get_frame_number (dev);
538 }
539
540 /**
541  * usb_endpoint_dir_in - check if the endpoint has IN direction
542  * @epd: endpoint to be checked
543  *
544  * Returns true if the endpoint is of type IN, otherwise it returns false.
545  */
546 int usb_endpoint_dir_in(const struct usb_endpoint_descriptor *epd)
547 {
548         return ((epd->bEndpointAddress & USB_ENDPOINT_DIR_MASK) == USB_DIR_IN);
549 }
550
551 /**
552  * usb_endpoint_dir_out - check if the endpoint has OUT direction
553  * @epd: endpoint to be checked
554  *
555  * Returns true if the endpoint is of type OUT, otherwise it returns false.
556  */
557 int usb_endpoint_dir_out(const struct usb_endpoint_descriptor *epd)
558 {
559         return ((epd->bEndpointAddress & USB_ENDPOINT_DIR_MASK) == USB_DIR_OUT);
560 }
561
562 /**
563  * usb_endpoint_xfer_bulk - check if the endpoint has bulk transfer type
564  * @epd: endpoint to be checked
565  *
566  * Returns true if the endpoint is of type bulk, otherwise it returns false.
567  */
568 int usb_endpoint_xfer_bulk(const struct usb_endpoint_descriptor *epd)
569 {
570         return ((epd->bmAttributes & USB_ENDPOINT_XFERTYPE_MASK) ==
571                 USB_ENDPOINT_XFER_BULK);
572 }
573
574 /**
575  * usb_endpoint_xfer_int - check if the endpoint has interrupt transfer type
576  * @epd: endpoint to be checked
577  *
578  * Returns true if the endpoint is of type interrupt, otherwise it returns
579  * false.
580  */
581 int usb_endpoint_xfer_int(const struct usb_endpoint_descriptor *epd)
582 {
583         return ((epd->bmAttributes & USB_ENDPOINT_XFERTYPE_MASK) ==
584                 USB_ENDPOINT_XFER_INT);
585 }
586
587 /**
588  * usb_endpoint_xfer_isoc - check if the endpoint has isochronous transfer type
589  * @epd: endpoint to be checked
590  *
591  * Returns true if the endpoint is of type isochronous, otherwise it returns
592  * false.
593  */
594 int usb_endpoint_xfer_isoc(const struct usb_endpoint_descriptor *epd)
595 {
596         return ((epd->bmAttributes & USB_ENDPOINT_XFERTYPE_MASK) ==
597                 USB_ENDPOINT_XFER_ISOC);
598 }
599
600 /**
601  * usb_endpoint_is_bulk_in - check if the endpoint is bulk IN
602  * @epd: endpoint to be checked
603  *
604  * Returns true if the endpoint has bulk transfer type and IN direction,
605  * otherwise it returns false.
606  */
607 int usb_endpoint_is_bulk_in(const struct usb_endpoint_descriptor *epd)
608 {
609         return (usb_endpoint_xfer_bulk(epd) && usb_endpoint_dir_in(epd));
610 }
611
612 /**
613  * usb_endpoint_is_bulk_out - check if the endpoint is bulk OUT
614  * @epd: endpoint to be checked
615  *
616  * Returns true if the endpoint has bulk transfer type and OUT direction,
617  * otherwise it returns false.
618  */
619 int usb_endpoint_is_bulk_out(const struct usb_endpoint_descriptor *epd)
620 {
621         return (usb_endpoint_xfer_bulk(epd) && usb_endpoint_dir_out(epd));
622 }
623
624 /**
625  * usb_endpoint_is_int_in - check if the endpoint is interrupt IN
626  * @epd: endpoint to be checked
627  *
628  * Returns true if the endpoint has interrupt transfer type and IN direction,
629  * otherwise it returns false.
630  */
631 int usb_endpoint_is_int_in(const struct usb_endpoint_descriptor *epd)
632 {
633         return (usb_endpoint_xfer_int(epd) && usb_endpoint_dir_in(epd));
634 }
635
636 /**
637  * usb_endpoint_is_int_out - check if the endpoint is interrupt OUT
638  * @epd: endpoint to be checked
639  *
640  * Returns true if the endpoint has interrupt transfer type and OUT direction,
641  * otherwise it returns false.
642  */
643 int usb_endpoint_is_int_out(const struct usb_endpoint_descriptor *epd)
644 {
645         return (usb_endpoint_xfer_int(epd) && usb_endpoint_dir_out(epd));
646 }
647
648 /**
649  * usb_endpoint_is_isoc_in - check if the endpoint is isochronous IN
650  * @epd: endpoint to be checked
651  *
652  * Returns true if the endpoint has isochronous transfer type and IN direction,
653  * otherwise it returns false.
654  */
655 int usb_endpoint_is_isoc_in(const struct usb_endpoint_descriptor *epd)
656 {
657         return (usb_endpoint_xfer_isoc(epd) && usb_endpoint_dir_in(epd));
658 }
659
660 /**
661  * usb_endpoint_is_isoc_out - check if the endpoint is isochronous OUT
662  * @epd: endpoint to be checked
663  *
664  * Returns true if the endpoint has isochronous transfer type and OUT direction,
665  * otherwise it returns false.
666  */
667 int usb_endpoint_is_isoc_out(const struct usb_endpoint_descriptor *epd)
668 {
669         return (usb_endpoint_xfer_isoc(epd) && usb_endpoint_dir_out(epd));
670 }
671
672 /*-------------------------------------------------------------------*/
673 /*
674  * __usb_get_extra_descriptor() finds a descriptor of specific type in the
675  * extra field of the interface and endpoint descriptor structs.
676  */
677
678 int __usb_get_extra_descriptor(char *buffer, unsigned size,
679         unsigned char type, void **ptr)
680 {
681         struct usb_descriptor_header *header;
682
683         while (size >= sizeof(struct usb_descriptor_header)) {
684                 header = (struct usb_descriptor_header *)buffer;
685
686                 if (header->bLength < 2) {
687                         printk(KERN_ERR
688                                 "%s: bogus descriptor, type %d length %d\n",
689                                 usbcore_name,
690                                 header->bDescriptorType, 
691                                 header->bLength);
692                         return -1;
693                 }
694
695                 if (header->bDescriptorType == type) {
696                         *ptr = header;
697                         return 0;
698                 }
699
700                 buffer += header->bLength;
701                 size -= header->bLength;
702         }
703         return -1;
704 }
705
706 /**
707  * usb_buffer_alloc - allocate dma-consistent buffer for URB_NO_xxx_DMA_MAP
708  * @dev: device the buffer will be used with
709  * @size: requested buffer size
710  * @mem_flags: affect whether allocation may block
711  * @dma: used to return DMA address of buffer
712  *
713  * Return value is either null (indicating no buffer could be allocated), or
714  * the cpu-space pointer to a buffer that may be used to perform DMA to the
715  * specified device.  Such cpu-space buffers are returned along with the DMA
716  * address (through the pointer provided).
717  *
718  * These buffers are used with URB_NO_xxx_DMA_MAP set in urb->transfer_flags
719  * to avoid behaviors like using "DMA bounce buffers", or tying down I/O
720  * mapping hardware for long idle periods.  The implementation varies between
721  * platforms, depending on details of how DMA will work to this device.
722  * Using these buffers also helps prevent cacheline sharing problems on
723  * architectures where CPU caches are not DMA-coherent.
724  *
725  * When the buffer is no longer used, free it with usb_buffer_free().
726  */
727 void *usb_buffer_alloc (
728         struct usb_device *dev,
729         size_t size,
730         gfp_t mem_flags,
731         dma_addr_t *dma
732 )
733 {
734         if (!dev || !dev->bus)
735                 return NULL;
736         return hcd_buffer_alloc (dev->bus, size, mem_flags, dma);
737 }
738
739 /**
740  * usb_buffer_free - free memory allocated with usb_buffer_alloc()
741  * @dev: device the buffer was used with
742  * @size: requested buffer size
743  * @addr: CPU address of buffer
744  * @dma: DMA address of buffer
745  *
746  * This reclaims an I/O buffer, letting it be reused.  The memory must have
747  * been allocated using usb_buffer_alloc(), and the parameters must match
748  * those provided in that allocation request. 
749  */
750 void usb_buffer_free (
751         struct usb_device *dev,
752         size_t size,
753         void *addr,
754         dma_addr_t dma
755 )
756 {
757         if (!dev || !dev->bus)
758                 return;
759         if (!addr)
760                 return;
761         hcd_buffer_free (dev->bus, size, addr, dma);
762 }
763
764 /**
765  * usb_buffer_map - create DMA mapping(s) for an urb
766  * @urb: urb whose transfer_buffer/setup_packet will be mapped
767  *
768  * Return value is either null (indicating no buffer could be mapped), or
769  * the parameter.  URB_NO_TRANSFER_DMA_MAP and URB_NO_SETUP_DMA_MAP are
770  * added to urb->transfer_flags if the operation succeeds.  If the device
771  * is connected to this system through a non-DMA controller, this operation
772  * always succeeds.
773  *
774  * This call would normally be used for an urb which is reused, perhaps
775  * as the target of a large periodic transfer, with usb_buffer_dmasync()
776  * calls to synchronize memory and dma state.
777  *
778  * Reverse the effect of this call with usb_buffer_unmap().
779  */
780 #if 0
781 struct urb *usb_buffer_map (struct urb *urb)
782 {
783         struct usb_bus          *bus;
784         struct device           *controller;
785
786         if (!urb
787                         || !urb->dev
788                         || !(bus = urb->dev->bus)
789                         || !(controller = bus->controller))
790                 return NULL;
791
792         if (controller->dma_mask) {
793                 urb->transfer_dma = dma_map_single (controller,
794                         urb->transfer_buffer, urb->transfer_buffer_length,
795                         usb_pipein (urb->pipe)
796                                 ? DMA_FROM_DEVICE : DMA_TO_DEVICE);
797                 if (usb_pipecontrol (urb->pipe))
798                         urb->setup_dma = dma_map_single (controller,
799                                         urb->setup_packet,
800                                         sizeof (struct usb_ctrlrequest),
801                                         DMA_TO_DEVICE);
802         // FIXME generic api broken like pci, can't report errors
803         // if (urb->transfer_dma == DMA_ADDR_INVALID) return 0;
804         } else
805                 urb->transfer_dma = ~0;
806         urb->transfer_flags |= (URB_NO_TRANSFER_DMA_MAP
807                                 | URB_NO_SETUP_DMA_MAP);
808         return urb;
809 }
810 #endif  /*  0  */
811
812 /* XXX DISABLED, no users currently.  If you wish to re-enable this
813  * XXX please determine whether the sync is to transfer ownership of
814  * XXX the buffer from device to cpu or vice verse, and thusly use the
815  * XXX appropriate _for_{cpu,device}() method.  -DaveM
816  */
817 #if 0
818
819 /**
820  * usb_buffer_dmasync - synchronize DMA and CPU view of buffer(s)
821  * @urb: urb whose transfer_buffer/setup_packet will be synchronized
822  */
823 void usb_buffer_dmasync (struct urb *urb)
824 {
825         struct usb_bus          *bus;
826         struct device           *controller;
827
828         if (!urb
829                         || !(urb->transfer_flags & URB_NO_TRANSFER_DMA_MAP)
830                         || !urb->dev
831                         || !(bus = urb->dev->bus)
832                         || !(controller = bus->controller))
833                 return;
834
835         if (controller->dma_mask) {
836                 dma_sync_single (controller,
837                         urb->transfer_dma, urb->transfer_buffer_length,
838                         usb_pipein (urb->pipe)
839                                 ? DMA_FROM_DEVICE : DMA_TO_DEVICE);
840                 if (usb_pipecontrol (urb->pipe))
841                         dma_sync_single (controller,
842                                         urb->setup_dma,
843                                         sizeof (struct usb_ctrlrequest),
844                                         DMA_TO_DEVICE);
845         }
846 }
847 #endif
848
849 /**
850  * usb_buffer_unmap - free DMA mapping(s) for an urb
851  * @urb: urb whose transfer_buffer will be unmapped
852  *
853  * Reverses the effect of usb_buffer_map().
854  */
855 #if 0
856 void usb_buffer_unmap (struct urb *urb)
857 {
858         struct usb_bus          *bus;
859         struct device           *controller;
860
861         if (!urb
862                         || !(urb->transfer_flags & URB_NO_TRANSFER_DMA_MAP)
863                         || !urb->dev
864                         || !(bus = urb->dev->bus)
865                         || !(controller = bus->controller))
866                 return;
867
868         if (controller->dma_mask) {
869                 dma_unmap_single (controller,
870                         urb->transfer_dma, urb->transfer_buffer_length,
871                         usb_pipein (urb->pipe)
872                                 ? DMA_FROM_DEVICE : DMA_TO_DEVICE);
873                 if (usb_pipecontrol (urb->pipe))
874                         dma_unmap_single (controller,
875                                         urb->setup_dma,
876                                         sizeof (struct usb_ctrlrequest),
877                                         DMA_TO_DEVICE);
878         }
879         urb->transfer_flags &= ~(URB_NO_TRANSFER_DMA_MAP
880                                 | URB_NO_SETUP_DMA_MAP);
881 }
882 #endif  /*  0  */
883
884 /**
885  * usb_buffer_map_sg - create scatterlist DMA mapping(s) for an endpoint
886  * @dev: device to which the scatterlist will be mapped
887  * @pipe: endpoint defining the mapping direction
888  * @sg: the scatterlist to map
889  * @nents: the number of entries in the scatterlist
890  *
891  * Return value is either < 0 (indicating no buffers could be mapped), or
892  * the number of DMA mapping array entries in the scatterlist.
893  *
894  * The caller is responsible for placing the resulting DMA addresses from
895  * the scatterlist into URB transfer buffer pointers, and for setting the
896  * URB_NO_TRANSFER_DMA_MAP transfer flag in each of those URBs.
897  *
898  * Top I/O rates come from queuing URBs, instead of waiting for each one
899  * to complete before starting the next I/O.   This is particularly easy
900  * to do with scatterlists.  Just allocate and submit one URB for each DMA
901  * mapping entry returned, stopping on the first error or when all succeed.
902  * Better yet, use the usb_sg_*() calls, which do that (and more) for you.
903  *
904  * This call would normally be used when translating scatterlist requests,
905  * rather than usb_buffer_map(), since on some hardware (with IOMMUs) it
906  * may be able to coalesce mappings for improved I/O efficiency.
907  *
908  * Reverse the effect of this call with usb_buffer_unmap_sg().
909  */
910 int usb_buffer_map_sg(const struct usb_device *dev, unsigned pipe,
911                       struct scatterlist *sg, int nents)
912 {
913         struct usb_bus          *bus;
914         struct device           *controller;
915
916         if (!dev
917                         || usb_pipecontrol (pipe)
918                         || !(bus = dev->bus)
919                         || !(controller = bus->controller)
920                         || !controller->dma_mask)
921                 return -1;
922
923         // FIXME generic api broken like pci, can't report errors
924         return dma_map_sg (controller, sg, nents,
925                         usb_pipein (pipe) ? DMA_FROM_DEVICE : DMA_TO_DEVICE);
926 }
927
928 /* XXX DISABLED, no users currently.  If you wish to re-enable this
929  * XXX please determine whether the sync is to transfer ownership of
930  * XXX the buffer from device to cpu or vice verse, and thusly use the
931  * XXX appropriate _for_{cpu,device}() method.  -DaveM
932  */
933 #if 0
934
935 /**
936  * usb_buffer_dmasync_sg - synchronize DMA and CPU view of scatterlist buffer(s)
937  * @dev: device to which the scatterlist will be mapped
938  * @pipe: endpoint defining the mapping direction
939  * @sg: the scatterlist to synchronize
940  * @n_hw_ents: the positive return value from usb_buffer_map_sg
941  *
942  * Use this when you are re-using a scatterlist's data buffers for
943  * another USB request.
944  */
945 void usb_buffer_dmasync_sg(const struct usb_device *dev, unsigned pipe,
946                            struct scatterlist *sg, int n_hw_ents)
947 {
948         struct usb_bus          *bus;
949         struct device           *controller;
950
951         if (!dev
952                         || !(bus = dev->bus)
953                         || !(controller = bus->controller)
954                         || !controller->dma_mask)
955                 return;
956
957         dma_sync_sg (controller, sg, n_hw_ents,
958                         usb_pipein (pipe) ? DMA_FROM_DEVICE : DMA_TO_DEVICE);
959 }
960 #endif
961
962 /**
963  * usb_buffer_unmap_sg - free DMA mapping(s) for a scatterlist
964  * @dev: device to which the scatterlist will be mapped
965  * @pipe: endpoint defining the mapping direction
966  * @sg: the scatterlist to unmap
967  * @n_hw_ents: the positive return value from usb_buffer_map_sg
968  *
969  * Reverses the effect of usb_buffer_map_sg().
970  */
971 void usb_buffer_unmap_sg(const struct usb_device *dev, unsigned pipe,
972                          struct scatterlist *sg, int n_hw_ents)
973 {
974         struct usb_bus          *bus;
975         struct device           *controller;
976
977         if (!dev
978                         || !(bus = dev->bus)
979                         || !(controller = bus->controller)
980                         || !controller->dma_mask)
981                 return;
982
983         dma_unmap_sg (controller, sg, n_hw_ents,
984                         usb_pipein (pipe) ? DMA_FROM_DEVICE : DMA_TO_DEVICE);
985 }
986
987 /* format to disable USB on kernel command line is: nousb */
988 __module_param_call("", nousb, param_set_bool, param_get_bool, &nousb, 0444);
989
990 /*
991  * for external read access to <nousb>
992  */
993 int usb_disabled(void)
994 {
995         return nousb;
996 }
997
998 /*
999  * Init
1000  */
1001 static int __init usb_init(void)
1002 {
1003         int retval;
1004         if (nousb) {
1005                 pr_info ("%s: USB support disabled\n", usbcore_name);
1006                 return 0;
1007         }
1008
1009         retval = ksuspend_usb_init();
1010         if (retval)
1011                 goto out;
1012         retval = bus_register(&usb_bus_type);
1013         if (retval) 
1014                 goto bus_register_failed;
1015         retval = usb_host_init();
1016         if (retval)
1017                 goto host_init_failed;
1018         retval = usb_major_init();
1019         if (retval)
1020                 goto major_init_failed;
1021         retval = usb_register(&usbfs_driver);
1022         if (retval)
1023                 goto driver_register_failed;
1024         retval = usbdev_init();
1025         if (retval)
1026                 goto usbdevice_init_failed;
1027         retval = usbfs_init();
1028         if (retval)
1029                 goto fs_init_failed;
1030         retval = usb_hub_init();
1031         if (retval)
1032                 goto hub_init_failed;
1033         retval = usb_register_device_driver(&usb_generic_driver, THIS_MODULE);
1034         if (!retval)
1035                 goto out;
1036
1037         usb_hub_cleanup();
1038 hub_init_failed:
1039         usbfs_cleanup();
1040 fs_init_failed:
1041         usbdev_cleanup();
1042 usbdevice_init_failed:
1043         usb_deregister(&usbfs_driver);
1044 driver_register_failed:
1045         usb_major_cleanup();
1046 major_init_failed:
1047         usb_host_cleanup();
1048 host_init_failed:
1049         bus_unregister(&usb_bus_type);
1050 bus_register_failed:
1051         ksuspend_usb_cleanup();
1052 out:
1053         return retval;
1054 }
1055
1056 /*
1057  * Cleanup
1058  */
1059 static void __exit usb_exit(void)
1060 {
1061         /* This will matter if shutdown/reboot does exitcalls. */
1062         if (nousb)
1063                 return;
1064
1065         usb_deregister_device_driver(&usb_generic_driver);
1066         usb_major_cleanup();
1067         usbfs_cleanup();
1068         usb_deregister(&usbfs_driver);
1069         usbdev_cleanup();
1070         usb_hub_cleanup();
1071         usb_host_cleanup();
1072         bus_unregister(&usb_bus_type);
1073         ksuspend_usb_cleanup();
1074 }
1075
1076 subsys_initcall(usb_init);
1077 module_exit(usb_exit);
1078
1079 /*
1080  * USB may be built into the kernel or be built as modules.
1081  * These symbols are exported for device (or host controller)
1082  * driver modules to use.
1083  */
1084
1085 EXPORT_SYMBOL(usb_disabled);
1086
1087 EXPORT_SYMBOL_GPL(usb_get_intf);
1088 EXPORT_SYMBOL_GPL(usb_put_intf);
1089
1090 EXPORT_SYMBOL(usb_put_dev);
1091 EXPORT_SYMBOL(usb_get_dev);
1092 EXPORT_SYMBOL(usb_hub_tt_clear_buffer);
1093
1094 EXPORT_SYMBOL(usb_lock_device_for_reset);
1095
1096 EXPORT_SYMBOL(usb_find_interface);
1097 EXPORT_SYMBOL(usb_ifnum_to_if);
1098 EXPORT_SYMBOL(usb_altnum_to_altsetting);
1099
1100 EXPORT_SYMBOL(__usb_get_extra_descriptor);
1101
1102 EXPORT_SYMBOL(usb_find_device);
1103 EXPORT_SYMBOL(usb_get_current_frame_number);
1104
1105 EXPORT_SYMBOL_GPL(usb_endpoint_dir_in);
1106 EXPORT_SYMBOL_GPL(usb_endpoint_dir_out);
1107 EXPORT_SYMBOL_GPL(usb_endpoint_xfer_bulk);
1108 EXPORT_SYMBOL_GPL(usb_endpoint_xfer_int);
1109 EXPORT_SYMBOL_GPL(usb_endpoint_xfer_isoc);
1110 EXPORT_SYMBOL_GPL(usb_endpoint_is_bulk_in);
1111 EXPORT_SYMBOL_GPL(usb_endpoint_is_bulk_out);
1112 EXPORT_SYMBOL_GPL(usb_endpoint_is_int_in);
1113 EXPORT_SYMBOL_GPL(usb_endpoint_is_int_out);
1114 EXPORT_SYMBOL_GPL(usb_endpoint_is_isoc_in);
1115 EXPORT_SYMBOL_GPL(usb_endpoint_is_isoc_out);
1116
1117 EXPORT_SYMBOL (usb_buffer_alloc);
1118 EXPORT_SYMBOL (usb_buffer_free);
1119
1120 #if 0
1121 EXPORT_SYMBOL (usb_buffer_map);
1122 EXPORT_SYMBOL (usb_buffer_dmasync);
1123 EXPORT_SYMBOL (usb_buffer_unmap);
1124 #endif
1125
1126 EXPORT_SYMBOL (usb_buffer_map_sg);
1127 #if 0
1128 EXPORT_SYMBOL (usb_buffer_dmasync_sg);
1129 #endif
1130 EXPORT_SYMBOL (usb_buffer_unmap_sg);
1131
1132 MODULE_LICENSE("GPL");