Merge branch 'for-linus' of git://git.kernel.org/pub/scm/linux/kernel/git/viro/vfs
[linux/fpc-iii.git] / drivers / usb / core / message.c
blobf829a1aad1c383e71d06ca26914ecff715fa598d
1 /*
2 * message.c - synchronous message handling
3 */
5 #include <linux/pci.h> /* for scatterlist macros */
6 #include <linux/usb.h>
7 #include <linux/module.h>
8 #include <linux/slab.h>
9 #include <linux/mm.h>
10 #include <linux/timer.h>
11 #include <linux/ctype.h>
12 #include <linux/nls.h>
13 #include <linux/device.h>
14 #include <linux/scatterlist.h>
15 #include <linux/usb/quirks.h>
16 #include <linux/usb/hcd.h> /* for usbcore internals */
17 #include <asm/byteorder.h>
19 #include "usb.h"
21 static void cancel_async_set_config(struct usb_device *udev);
23 struct api_context {
24 struct completion done;
25 int status;
28 static void usb_api_blocking_completion(struct urb *urb)
30 struct api_context *ctx = urb->context;
32 ctx->status = urb->status;
33 complete(&ctx->done);
38 * Starts urb and waits for completion or timeout. Note that this call
39 * is NOT interruptible. Many device driver i/o requests should be
40 * interruptible and therefore these drivers should implement their
41 * own interruptible routines.
43 static int usb_start_wait_urb(struct urb *urb, int timeout, int *actual_length)
45 struct api_context ctx;
46 unsigned long expire;
47 int retval;
49 init_completion(&ctx.done);
50 urb->context = &ctx;
51 urb->actual_length = 0;
52 retval = usb_submit_urb(urb, GFP_NOIO);
53 if (unlikely(retval))
54 goto out;
56 expire = timeout ? msecs_to_jiffies(timeout) : MAX_SCHEDULE_TIMEOUT;
57 if (!wait_for_completion_timeout(&ctx.done, expire)) {
58 usb_kill_urb(urb);
59 retval = (ctx.status == -ENOENT ? -ETIMEDOUT : ctx.status);
61 dev_dbg(&urb->dev->dev,
62 "%s timed out on ep%d%s len=%u/%u\n",
63 current->comm,
64 usb_endpoint_num(&urb->ep->desc),
65 usb_urb_dir_in(urb) ? "in" : "out",
66 urb->actual_length,
67 urb->transfer_buffer_length);
68 } else
69 retval = ctx.status;
70 out:
71 if (actual_length)
72 *actual_length = urb->actual_length;
74 usb_free_urb(urb);
75 return retval;
78 /*-------------------------------------------------------------------*/
79 /* returns status (negative) or length (positive) */
80 static int usb_internal_control_msg(struct usb_device *usb_dev,
81 unsigned int pipe,
82 struct usb_ctrlrequest *cmd,
83 void *data, int len, int timeout)
85 struct urb *urb;
86 int retv;
87 int length;
89 urb = usb_alloc_urb(0, GFP_NOIO);
90 if (!urb)
91 return -ENOMEM;
93 usb_fill_control_urb(urb, usb_dev, pipe, (unsigned char *)cmd, data,
94 len, usb_api_blocking_completion, NULL);
96 retv = usb_start_wait_urb(urb, timeout, &length);
97 if (retv < 0)
98 return retv;
99 else
100 return length;
104 * usb_control_msg - Builds a control urb, sends it off and waits for completion
105 * @dev: pointer to the usb device to send the message to
106 * @pipe: endpoint "pipe" to send the message to
107 * @request: USB message request value
108 * @requesttype: USB message request type value
109 * @value: USB message value
110 * @index: USB message index value
111 * @data: pointer to the data to send
112 * @size: length in bytes of the data to send
113 * @timeout: time in msecs to wait for the message to complete before timing
114 * out (if 0 the wait is forever)
116 * Context: !in_interrupt ()
118 * This function sends a simple control message to a specified endpoint and
119 * waits for the message to complete, or timeout.
121 * Don't use this function from within an interrupt context, like a bottom half
122 * handler. If you need an asynchronous message, or need to send a message
123 * from within interrupt context, use usb_submit_urb().
124 * If a thread in your driver uses this call, make sure your disconnect()
125 * method can wait for it to complete. Since you don't have a handle on the
126 * URB used, you can't cancel the request.
128 * Return: If successful, the number of bytes transferred. Otherwise, a negative
129 * error number.
131 int usb_control_msg(struct usb_device *dev, unsigned int pipe, __u8 request,
132 __u8 requesttype, __u16 value, __u16 index, void *data,
133 __u16 size, int timeout)
135 struct usb_ctrlrequest *dr;
136 int ret;
138 dr = kmalloc(sizeof(struct usb_ctrlrequest), GFP_NOIO);
139 if (!dr)
140 return -ENOMEM;
142 dr->bRequestType = requesttype;
143 dr->bRequest = request;
144 dr->wValue = cpu_to_le16(value);
145 dr->wIndex = cpu_to_le16(index);
146 dr->wLength = cpu_to_le16(size);
148 ret = usb_internal_control_msg(dev, pipe, dr, data, size, timeout);
150 kfree(dr);
152 return ret;
154 EXPORT_SYMBOL_GPL(usb_control_msg);
157 * usb_interrupt_msg - Builds an interrupt urb, sends it off and waits for completion
158 * @usb_dev: pointer to the usb device to send the message to
159 * @pipe: endpoint "pipe" to send the message to
160 * @data: pointer to the data to send
161 * @len: length in bytes of the data to send
162 * @actual_length: pointer to a location to put the actual length transferred
163 * in bytes
164 * @timeout: time in msecs to wait for the message to complete before
165 * timing out (if 0 the wait is forever)
167 * Context: !in_interrupt ()
169 * This function sends a simple interrupt message to a specified endpoint and
170 * waits for the message to complete, or timeout.
172 * Don't use this function from within an interrupt context, like a bottom half
173 * handler. If you need an asynchronous message, or need to send a message
174 * from within interrupt context, use usb_submit_urb() If a thread in your
175 * driver uses this call, make sure your disconnect() method can wait for it to
176 * complete. Since you don't have a handle on the URB used, you can't cancel
177 * the request.
179 * Return:
180 * If successful, 0. Otherwise a negative error number. The number of actual
181 * bytes transferred will be stored in the @actual_length paramater.
183 int usb_interrupt_msg(struct usb_device *usb_dev, unsigned int pipe,
184 void *data, int len, int *actual_length, int timeout)
186 return usb_bulk_msg(usb_dev, pipe, data, len, actual_length, timeout);
188 EXPORT_SYMBOL_GPL(usb_interrupt_msg);
191 * usb_bulk_msg - Builds a bulk urb, sends it off and waits for completion
192 * @usb_dev: pointer to the usb device to send the message to
193 * @pipe: endpoint "pipe" to send the message to
194 * @data: pointer to the data to send
195 * @len: length in bytes of the data to send
196 * @actual_length: pointer to a location to put the actual length transferred
197 * in bytes
198 * @timeout: time in msecs to wait for the message to complete before
199 * timing out (if 0 the wait is forever)
201 * Context: !in_interrupt ()
203 * This function sends a simple bulk message to a specified endpoint
204 * and waits for the message to complete, or timeout.
206 * Don't use this function from within an interrupt context, like a bottom half
207 * handler. If you need an asynchronous message, or need to send a message
208 * from within interrupt context, use usb_submit_urb() If a thread in your
209 * driver uses this call, make sure your disconnect() method can wait for it to
210 * complete. Since you don't have a handle on the URB used, you can't cancel
211 * the request.
213 * Because there is no usb_interrupt_msg() and no USBDEVFS_INTERRUPT ioctl,
214 * users are forced to abuse this routine by using it to submit URBs for
215 * interrupt endpoints. We will take the liberty of creating an interrupt URB
216 * (with the default interval) if the target is an interrupt endpoint.
218 * Return:
219 * If successful, 0. Otherwise a negative error number. The number of actual
220 * bytes transferred will be stored in the @actual_length parameter.
223 int usb_bulk_msg(struct usb_device *usb_dev, unsigned int pipe,
224 void *data, int len, int *actual_length, int timeout)
226 struct urb *urb;
227 struct usb_host_endpoint *ep;
229 ep = usb_pipe_endpoint(usb_dev, pipe);
230 if (!ep || len < 0)
231 return -EINVAL;
233 urb = usb_alloc_urb(0, GFP_KERNEL);
234 if (!urb)
235 return -ENOMEM;
237 if ((ep->desc.bmAttributes & USB_ENDPOINT_XFERTYPE_MASK) ==
238 USB_ENDPOINT_XFER_INT) {
239 pipe = (pipe & ~(3 << 30)) | (PIPE_INTERRUPT << 30);
240 usb_fill_int_urb(urb, usb_dev, pipe, data, len,
241 usb_api_blocking_completion, NULL,
242 ep->desc.bInterval);
243 } else
244 usb_fill_bulk_urb(urb, usb_dev, pipe, data, len,
245 usb_api_blocking_completion, NULL);
247 return usb_start_wait_urb(urb, timeout, actual_length);
249 EXPORT_SYMBOL_GPL(usb_bulk_msg);
251 /*-------------------------------------------------------------------*/
253 static void sg_clean(struct usb_sg_request *io)
255 if (io->urbs) {
256 while (io->entries--)
257 usb_free_urb(io->urbs[io->entries]);
258 kfree(io->urbs);
259 io->urbs = NULL;
261 io->dev = NULL;
264 static void sg_complete(struct urb *urb)
266 struct usb_sg_request *io = urb->context;
267 int status = urb->status;
269 spin_lock(&io->lock);
271 /* In 2.5 we require hcds' endpoint queues not to progress after fault
272 * reports, until the completion callback (this!) returns. That lets
273 * device driver code (like this routine) unlink queued urbs first,
274 * if it needs to, since the HC won't work on them at all. So it's
275 * not possible for page N+1 to overwrite page N, and so on.
277 * That's only for "hard" faults; "soft" faults (unlinks) sometimes
278 * complete before the HCD can get requests away from hardware,
279 * though never during cleanup after a hard fault.
281 if (io->status
282 && (io->status != -ECONNRESET
283 || status != -ECONNRESET)
284 && urb->actual_length) {
285 dev_err(io->dev->bus->controller,
286 "dev %s ep%d%s scatterlist error %d/%d\n",
287 io->dev->devpath,
288 usb_endpoint_num(&urb->ep->desc),
289 usb_urb_dir_in(urb) ? "in" : "out",
290 status, io->status);
291 /* BUG (); */
294 if (io->status == 0 && status && status != -ECONNRESET) {
295 int i, found, retval;
297 io->status = status;
299 /* the previous urbs, and this one, completed already.
300 * unlink pending urbs so they won't rx/tx bad data.
301 * careful: unlink can sometimes be synchronous...
303 spin_unlock(&io->lock);
304 for (i = 0, found = 0; i < io->entries; i++) {
305 if (!io->urbs[i] || !io->urbs[i]->dev)
306 continue;
307 if (found) {
308 retval = usb_unlink_urb(io->urbs[i]);
309 if (retval != -EINPROGRESS &&
310 retval != -ENODEV &&
311 retval != -EBUSY &&
312 retval != -EIDRM)
313 dev_err(&io->dev->dev,
314 "%s, unlink --> %d\n",
315 __func__, retval);
316 } else if (urb == io->urbs[i])
317 found = 1;
319 spin_lock(&io->lock);
322 /* on the last completion, signal usb_sg_wait() */
323 io->bytes += urb->actual_length;
324 io->count--;
325 if (!io->count)
326 complete(&io->complete);
328 spin_unlock(&io->lock);
333 * usb_sg_init - initializes scatterlist-based bulk/interrupt I/O request
334 * @io: request block being initialized. until usb_sg_wait() returns,
335 * treat this as a pointer to an opaque block of memory,
336 * @dev: the usb device that will send or receive the data
337 * @pipe: endpoint "pipe" used to transfer the data
338 * @period: polling rate for interrupt endpoints, in frames or
339 * (for high speed endpoints) microframes; ignored for bulk
340 * @sg: scatterlist entries
341 * @nents: how many entries in the scatterlist
342 * @length: how many bytes to send from the scatterlist, or zero to
343 * send every byte identified in the list.
344 * @mem_flags: SLAB_* flags affecting memory allocations in this call
346 * This initializes a scatter/gather request, allocating resources such as
347 * I/O mappings and urb memory (except maybe memory used by USB controller
348 * drivers).
350 * The request must be issued using usb_sg_wait(), which waits for the I/O to
351 * complete (or to be canceled) and then cleans up all resources allocated by
352 * usb_sg_init().
354 * The request may be canceled with usb_sg_cancel(), either before or after
355 * usb_sg_wait() is called.
357 * Return: Zero for success, else a negative errno value.
359 int usb_sg_init(struct usb_sg_request *io, struct usb_device *dev,
360 unsigned pipe, unsigned period, struct scatterlist *sg,
361 int nents, size_t length, gfp_t mem_flags)
363 int i;
364 int urb_flags;
365 int use_sg;
367 if (!io || !dev || !sg
368 || usb_pipecontrol(pipe)
369 || usb_pipeisoc(pipe)
370 || nents <= 0)
371 return -EINVAL;
373 spin_lock_init(&io->lock);
374 io->dev = dev;
375 io->pipe = pipe;
377 if (dev->bus->sg_tablesize > 0) {
378 use_sg = true;
379 io->entries = 1;
380 } else {
381 use_sg = false;
382 io->entries = nents;
385 /* initialize all the urbs we'll use */
386 io->urbs = kmalloc(io->entries * sizeof(*io->urbs), mem_flags);
387 if (!io->urbs)
388 goto nomem;
390 urb_flags = URB_NO_INTERRUPT;
391 if (usb_pipein(pipe))
392 urb_flags |= URB_SHORT_NOT_OK;
394 for_each_sg(sg, sg, io->entries, i) {
395 struct urb *urb;
396 unsigned len;
398 urb = usb_alloc_urb(0, mem_flags);
399 if (!urb) {
400 io->entries = i;
401 goto nomem;
403 io->urbs[i] = urb;
405 urb->dev = NULL;
406 urb->pipe = pipe;
407 urb->interval = period;
408 urb->transfer_flags = urb_flags;
409 urb->complete = sg_complete;
410 urb->context = io;
411 urb->sg = sg;
413 if (use_sg) {
414 /* There is no single transfer buffer */
415 urb->transfer_buffer = NULL;
416 urb->num_sgs = nents;
418 /* A length of zero means transfer the whole sg list */
419 len = length;
420 if (len == 0) {
421 struct scatterlist *sg2;
422 int j;
424 for_each_sg(sg, sg2, nents, j)
425 len += sg2->length;
427 } else {
429 * Some systems can't use DMA; they use PIO instead.
430 * For their sakes, transfer_buffer is set whenever
431 * possible.
433 if (!PageHighMem(sg_page(sg)))
434 urb->transfer_buffer = sg_virt(sg);
435 else
436 urb->transfer_buffer = NULL;
438 len = sg->length;
439 if (length) {
440 len = min_t(size_t, len, length);
441 length -= len;
442 if (length == 0)
443 io->entries = i + 1;
446 urb->transfer_buffer_length = len;
448 io->urbs[--i]->transfer_flags &= ~URB_NO_INTERRUPT;
450 /* transaction state */
451 io->count = io->entries;
452 io->status = 0;
453 io->bytes = 0;
454 init_completion(&io->complete);
455 return 0;
457 nomem:
458 sg_clean(io);
459 return -ENOMEM;
461 EXPORT_SYMBOL_GPL(usb_sg_init);
464 * usb_sg_wait - synchronously execute scatter/gather request
465 * @io: request block handle, as initialized with usb_sg_init().
466 * some fields become accessible when this call returns.
467 * Context: !in_interrupt ()
469 * This function blocks until the specified I/O operation completes. It
470 * leverages the grouping of the related I/O requests to get good transfer
471 * rates, by queueing the requests. At higher speeds, such queuing can
472 * significantly improve USB throughput.
474 * There are three kinds of completion for this function.
475 * (1) success, where io->status is zero. The number of io->bytes
476 * transferred is as requested.
477 * (2) error, where io->status is a negative errno value. The number
478 * of io->bytes transferred before the error is usually less
479 * than requested, and can be nonzero.
480 * (3) cancellation, a type of error with status -ECONNRESET that
481 * is initiated by usb_sg_cancel().
483 * When this function returns, all memory allocated through usb_sg_init() or
484 * this call will have been freed. The request block parameter may still be
485 * passed to usb_sg_cancel(), or it may be freed. It could also be
486 * reinitialized and then reused.
488 * Data Transfer Rates:
490 * Bulk transfers are valid for full or high speed endpoints.
491 * The best full speed data rate is 19 packets of 64 bytes each
492 * per frame, or 1216 bytes per millisecond.
493 * The best high speed data rate is 13 packets of 512 bytes each
494 * per microframe, or 52 KBytes per millisecond.
496 * The reason to use interrupt transfers through this API would most likely
497 * be to reserve high speed bandwidth, where up to 24 KBytes per millisecond
498 * could be transferred. That capability is less useful for low or full
499 * speed interrupt endpoints, which allow at most one packet per millisecond,
500 * of at most 8 or 64 bytes (respectively).
502 * It is not necessary to call this function to reserve bandwidth for devices
503 * under an xHCI host controller, as the bandwidth is reserved when the
504 * configuration or interface alt setting is selected.
506 void usb_sg_wait(struct usb_sg_request *io)
508 int i;
509 int entries = io->entries;
511 /* queue the urbs. */
512 spin_lock_irq(&io->lock);
513 i = 0;
514 while (i < entries && !io->status) {
515 int retval;
517 io->urbs[i]->dev = io->dev;
518 retval = usb_submit_urb(io->urbs[i], GFP_ATOMIC);
520 /* after we submit, let completions or cancellations fire;
521 * we handshake using io->status.
523 spin_unlock_irq(&io->lock);
524 switch (retval) {
525 /* maybe we retrying will recover */
526 case -ENXIO: /* hc didn't queue this one */
527 case -EAGAIN:
528 case -ENOMEM:
529 retval = 0;
530 yield();
531 break;
533 /* no error? continue immediately.
535 * NOTE: to work better with UHCI (4K I/O buffer may
536 * need 3K of TDs) it may be good to limit how many
537 * URBs are queued at once; N milliseconds?
539 case 0:
540 ++i;
541 cpu_relax();
542 break;
544 /* fail any uncompleted urbs */
545 default:
546 io->urbs[i]->status = retval;
547 dev_dbg(&io->dev->dev, "%s, submit --> %d\n",
548 __func__, retval);
549 usb_sg_cancel(io);
551 spin_lock_irq(&io->lock);
552 if (retval && (io->status == 0 || io->status == -ECONNRESET))
553 io->status = retval;
555 io->count -= entries - i;
556 if (io->count == 0)
557 complete(&io->complete);
558 spin_unlock_irq(&io->lock);
560 /* OK, yes, this could be packaged as non-blocking.
561 * So could the submit loop above ... but it's easier to
562 * solve neither problem than to solve both!
564 wait_for_completion(&io->complete);
566 sg_clean(io);
568 EXPORT_SYMBOL_GPL(usb_sg_wait);
571 * usb_sg_cancel - stop scatter/gather i/o issued by usb_sg_wait()
572 * @io: request block, initialized with usb_sg_init()
574 * This stops a request after it has been started by usb_sg_wait().
575 * It can also prevents one initialized by usb_sg_init() from starting,
576 * so that call just frees resources allocated to the request.
578 void usb_sg_cancel(struct usb_sg_request *io)
580 unsigned long flags;
582 spin_lock_irqsave(&io->lock, flags);
584 /* shut everything down, if it didn't already */
585 if (!io->status) {
586 int i;
588 io->status = -ECONNRESET;
589 spin_unlock(&io->lock);
590 for (i = 0; i < io->entries; i++) {
591 int retval;
593 if (!io->urbs[i]->dev)
594 continue;
595 retval = usb_unlink_urb(io->urbs[i]);
596 if (retval != -EINPROGRESS
597 && retval != -ENODEV
598 && retval != -EBUSY
599 && retval != -EIDRM)
600 dev_warn(&io->dev->dev, "%s, unlink --> %d\n",
601 __func__, retval);
603 spin_lock(&io->lock);
605 spin_unlock_irqrestore(&io->lock, flags);
607 EXPORT_SYMBOL_GPL(usb_sg_cancel);
609 /*-------------------------------------------------------------------*/
612 * usb_get_descriptor - issues a generic GET_DESCRIPTOR request
613 * @dev: the device whose descriptor is being retrieved
614 * @type: the descriptor type (USB_DT_*)
615 * @index: the number of the descriptor
616 * @buf: where to put the descriptor
617 * @size: how big is "buf"?
618 * Context: !in_interrupt ()
620 * Gets a USB descriptor. Convenience functions exist to simplify
621 * getting some types of descriptors. Use
622 * usb_get_string() or usb_string() for USB_DT_STRING.
623 * Device (USB_DT_DEVICE) and configuration descriptors (USB_DT_CONFIG)
624 * are part of the device structure.
625 * In addition to a number of USB-standard descriptors, some
626 * devices also use class-specific or vendor-specific descriptors.
628 * This call is synchronous, and may not be used in an interrupt context.
630 * Return: The number of bytes received on success, or else the status code
631 * returned by the underlying usb_control_msg() call.
633 int usb_get_descriptor(struct usb_device *dev, unsigned char type,
634 unsigned char index, void *buf, int size)
636 int i;
637 int result;
639 memset(buf, 0, size); /* Make sure we parse really received data */
641 for (i = 0; i < 3; ++i) {
642 /* retry on length 0 or error; some devices are flakey */
643 result = usb_control_msg(dev, usb_rcvctrlpipe(dev, 0),
644 USB_REQ_GET_DESCRIPTOR, USB_DIR_IN,
645 (type << 8) + index, 0, buf, size,
646 USB_CTRL_GET_TIMEOUT);
647 if (result <= 0 && result != -ETIMEDOUT)
648 continue;
649 if (result > 1 && ((u8 *)buf)[1] != type) {
650 result = -ENODATA;
651 continue;
653 break;
655 return result;
657 EXPORT_SYMBOL_GPL(usb_get_descriptor);
660 * usb_get_string - gets a string descriptor
661 * @dev: the device whose string descriptor is being retrieved
662 * @langid: code for language chosen (from string descriptor zero)
663 * @index: the number of the descriptor
664 * @buf: where to put the string
665 * @size: how big is "buf"?
666 * Context: !in_interrupt ()
668 * Retrieves a string, encoded using UTF-16LE (Unicode, 16 bits per character,
669 * in little-endian byte order).
670 * The usb_string() function will often be a convenient way to turn
671 * these strings into kernel-printable form.
673 * Strings may be referenced in device, configuration, interface, or other
674 * descriptors, and could also be used in vendor-specific ways.
676 * This call is synchronous, and may not be used in an interrupt context.
678 * Return: The number of bytes received on success, or else the status code
679 * returned by the underlying usb_control_msg() call.
681 static int usb_get_string(struct usb_device *dev, unsigned short langid,
682 unsigned char index, void *buf, int size)
684 int i;
685 int result;
687 for (i = 0; i < 3; ++i) {
688 /* retry on length 0 or stall; some devices are flakey */
689 result = usb_control_msg(dev, usb_rcvctrlpipe(dev, 0),
690 USB_REQ_GET_DESCRIPTOR, USB_DIR_IN,
691 (USB_DT_STRING << 8) + index, langid, buf, size,
692 USB_CTRL_GET_TIMEOUT);
693 if (result == 0 || result == -EPIPE)
694 continue;
695 if (result > 1 && ((u8 *) buf)[1] != USB_DT_STRING) {
696 result = -ENODATA;
697 continue;
699 break;
701 return result;
704 static void usb_try_string_workarounds(unsigned char *buf, int *length)
706 int newlength, oldlength = *length;
708 for (newlength = 2; newlength + 1 < oldlength; newlength += 2)
709 if (!isprint(buf[newlength]) || buf[newlength + 1])
710 break;
712 if (newlength > 2) {
713 buf[0] = newlength;
714 *length = newlength;
718 static int usb_string_sub(struct usb_device *dev, unsigned int langid,
719 unsigned int index, unsigned char *buf)
721 int rc;
723 /* Try to read the string descriptor by asking for the maximum
724 * possible number of bytes */
725 if (dev->quirks & USB_QUIRK_STRING_FETCH_255)
726 rc = -EIO;
727 else
728 rc = usb_get_string(dev, langid, index, buf, 255);
730 /* If that failed try to read the descriptor length, then
731 * ask for just that many bytes */
732 if (rc < 2) {
733 rc = usb_get_string(dev, langid, index, buf, 2);
734 if (rc == 2)
735 rc = usb_get_string(dev, langid, index, buf, buf[0]);
738 if (rc >= 2) {
739 if (!buf[0] && !buf[1])
740 usb_try_string_workarounds(buf, &rc);
742 /* There might be extra junk at the end of the descriptor */
743 if (buf[0] < rc)
744 rc = buf[0];
746 rc = rc - (rc & 1); /* force a multiple of two */
749 if (rc < 2)
750 rc = (rc < 0 ? rc : -EINVAL);
752 return rc;
755 static int usb_get_langid(struct usb_device *dev, unsigned char *tbuf)
757 int err;
759 if (dev->have_langid)
760 return 0;
762 if (dev->string_langid < 0)
763 return -EPIPE;
765 err = usb_string_sub(dev, 0, 0, tbuf);
767 /* If the string was reported but is malformed, default to english
768 * (0x0409) */
769 if (err == -ENODATA || (err > 0 && err < 4)) {
770 dev->string_langid = 0x0409;
771 dev->have_langid = 1;
772 dev_err(&dev->dev,
773 "string descriptor 0 malformed (err = %d), "
774 "defaulting to 0x%04x\n",
775 err, dev->string_langid);
776 return 0;
779 /* In case of all other errors, we assume the device is not able to
780 * deal with strings at all. Set string_langid to -1 in order to
781 * prevent any string to be retrieved from the device */
782 if (err < 0) {
783 dev_err(&dev->dev, "string descriptor 0 read error: %d\n",
784 err);
785 dev->string_langid = -1;
786 return -EPIPE;
789 /* always use the first langid listed */
790 dev->string_langid = tbuf[2] | (tbuf[3] << 8);
791 dev->have_langid = 1;
792 dev_dbg(&dev->dev, "default language 0x%04x\n",
793 dev->string_langid);
794 return 0;
798 * usb_string - returns UTF-8 version of a string descriptor
799 * @dev: the device whose string descriptor is being retrieved
800 * @index: the number of the descriptor
801 * @buf: where to put the string
802 * @size: how big is "buf"?
803 * Context: !in_interrupt ()
805 * This converts the UTF-16LE encoded strings returned by devices, from
806 * usb_get_string_descriptor(), to null-terminated UTF-8 encoded ones
807 * that are more usable in most kernel contexts. Note that this function
808 * chooses strings in the first language supported by the device.
810 * This call is synchronous, and may not be used in an interrupt context.
812 * Return: length of the string (>= 0) or usb_control_msg status (< 0).
814 int usb_string(struct usb_device *dev, int index, char *buf, size_t size)
816 unsigned char *tbuf;
817 int err;
819 if (dev->state == USB_STATE_SUSPENDED)
820 return -EHOSTUNREACH;
821 if (size <= 0 || !buf || !index)
822 return -EINVAL;
823 buf[0] = 0;
824 tbuf = kmalloc(256, GFP_NOIO);
825 if (!tbuf)
826 return -ENOMEM;
828 err = usb_get_langid(dev, tbuf);
829 if (err < 0)
830 goto errout;
832 err = usb_string_sub(dev, dev->string_langid, index, tbuf);
833 if (err < 0)
834 goto errout;
836 size--; /* leave room for trailing NULL char in output buffer */
837 err = utf16s_to_utf8s((wchar_t *) &tbuf[2], (err - 2) / 2,
838 UTF16_LITTLE_ENDIAN, buf, size);
839 buf[err] = 0;
841 if (tbuf[1] != USB_DT_STRING)
842 dev_dbg(&dev->dev,
843 "wrong descriptor type %02x for string %d (\"%s\")\n",
844 tbuf[1], index, buf);
846 errout:
847 kfree(tbuf);
848 return err;
850 EXPORT_SYMBOL_GPL(usb_string);
852 /* one UTF-8-encoded 16-bit character has at most three bytes */
853 #define MAX_USB_STRING_SIZE (127 * 3 + 1)
856 * usb_cache_string - read a string descriptor and cache it for later use
857 * @udev: the device whose string descriptor is being read
858 * @index: the descriptor index
860 * Return: A pointer to a kmalloc'ed buffer containing the descriptor string,
861 * or %NULL if the index is 0 or the string could not be read.
863 char *usb_cache_string(struct usb_device *udev, int index)
865 char *buf;
866 char *smallbuf = NULL;
867 int len;
869 if (index <= 0)
870 return NULL;
872 buf = kmalloc(MAX_USB_STRING_SIZE, GFP_NOIO);
873 if (buf) {
874 len = usb_string(udev, index, buf, MAX_USB_STRING_SIZE);
875 if (len > 0) {
876 smallbuf = kmalloc(++len, GFP_NOIO);
877 if (!smallbuf)
878 return buf;
879 memcpy(smallbuf, buf, len);
881 kfree(buf);
883 return smallbuf;
887 * usb_get_device_descriptor - (re)reads the device descriptor (usbcore)
888 * @dev: the device whose device descriptor is being updated
889 * @size: how much of the descriptor to read
890 * Context: !in_interrupt ()
892 * Updates the copy of the device descriptor stored in the device structure,
893 * which dedicates space for this purpose.
895 * Not exported, only for use by the core. If drivers really want to read
896 * the device descriptor directly, they can call usb_get_descriptor() with
897 * type = USB_DT_DEVICE and index = 0.
899 * This call is synchronous, and may not be used in an interrupt context.
901 * Return: The number of bytes received on success, or else the status code
902 * returned by the underlying usb_control_msg() call.
904 int usb_get_device_descriptor(struct usb_device *dev, unsigned int size)
906 struct usb_device_descriptor *desc;
907 int ret;
909 if (size > sizeof(*desc))
910 return -EINVAL;
911 desc = kmalloc(sizeof(*desc), GFP_NOIO);
912 if (!desc)
913 return -ENOMEM;
915 ret = usb_get_descriptor(dev, USB_DT_DEVICE, 0, desc, size);
916 if (ret >= 0)
917 memcpy(&dev->descriptor, desc, size);
918 kfree(desc);
919 return ret;
923 * usb_get_status - issues a GET_STATUS call
924 * @dev: the device whose status is being checked
925 * @type: USB_RECIP_*; for device, interface, or endpoint
926 * @target: zero (for device), else interface or endpoint number
927 * @data: pointer to two bytes of bitmap data
928 * Context: !in_interrupt ()
930 * Returns device, interface, or endpoint status. Normally only of
931 * interest to see if the device is self powered, or has enabled the
932 * remote wakeup facility; or whether a bulk or interrupt endpoint
933 * is halted ("stalled").
935 * Bits in these status bitmaps are set using the SET_FEATURE request,
936 * and cleared using the CLEAR_FEATURE request. The usb_clear_halt()
937 * function should be used to clear halt ("stall") status.
939 * This call is synchronous, and may not be used in an interrupt context.
941 * Returns 0 and the status value in *@data (in host byte order) on success,
942 * or else the status code from the underlying usb_control_msg() call.
944 int usb_get_status(struct usb_device *dev, int type, int target, void *data)
946 int ret;
947 __le16 *status = kmalloc(sizeof(*status), GFP_KERNEL);
949 if (!status)
950 return -ENOMEM;
952 ret = usb_control_msg(dev, usb_rcvctrlpipe(dev, 0),
953 USB_REQ_GET_STATUS, USB_DIR_IN | type, 0, target, status,
954 sizeof(*status), USB_CTRL_GET_TIMEOUT);
956 if (ret == 2) {
957 *(u16 *) data = le16_to_cpu(*status);
958 ret = 0;
959 } else if (ret >= 0) {
960 ret = -EIO;
962 kfree(status);
963 return ret;
965 EXPORT_SYMBOL_GPL(usb_get_status);
968 * usb_clear_halt - tells device to clear endpoint halt/stall condition
969 * @dev: device whose endpoint is halted
970 * @pipe: endpoint "pipe" being cleared
971 * Context: !in_interrupt ()
973 * This is used to clear halt conditions for bulk and interrupt endpoints,
974 * as reported by URB completion status. Endpoints that are halted are
975 * sometimes referred to as being "stalled". Such endpoints are unable
976 * to transmit or receive data until the halt status is cleared. Any URBs
977 * queued for such an endpoint should normally be unlinked by the driver
978 * before clearing the halt condition, as described in sections 5.7.5
979 * and 5.8.5 of the USB 2.0 spec.
981 * Note that control and isochronous endpoints don't halt, although control
982 * endpoints report "protocol stall" (for unsupported requests) using the
983 * same status code used to report a true stall.
985 * This call is synchronous, and may not be used in an interrupt context.
987 * Return: Zero on success, or else the status code returned by the
988 * underlying usb_control_msg() call.
990 int usb_clear_halt(struct usb_device *dev, int pipe)
992 int result;
993 int endp = usb_pipeendpoint(pipe);
995 if (usb_pipein(pipe))
996 endp |= USB_DIR_IN;
998 /* we don't care if it wasn't halted first. in fact some devices
999 * (like some ibmcam model 1 units) seem to expect hosts to make
1000 * this request for iso endpoints, which can't halt!
1002 result = usb_control_msg(dev, usb_sndctrlpipe(dev, 0),
1003 USB_REQ_CLEAR_FEATURE, USB_RECIP_ENDPOINT,
1004 USB_ENDPOINT_HALT, endp, NULL, 0,
1005 USB_CTRL_SET_TIMEOUT);
1007 /* don't un-halt or force to DATA0 except on success */
1008 if (result < 0)
1009 return result;
1011 /* NOTE: seems like Microsoft and Apple don't bother verifying
1012 * the clear "took", so some devices could lock up if you check...
1013 * such as the Hagiwara FlashGate DUAL. So we won't bother.
1015 * NOTE: make sure the logic here doesn't diverge much from
1016 * the copy in usb-storage, for as long as we need two copies.
1019 usb_reset_endpoint(dev, endp);
1021 return 0;
1023 EXPORT_SYMBOL_GPL(usb_clear_halt);
1025 static int create_intf_ep_devs(struct usb_interface *intf)
1027 struct usb_device *udev = interface_to_usbdev(intf);
1028 struct usb_host_interface *alt = intf->cur_altsetting;
1029 int i;
1031 if (intf->ep_devs_created || intf->unregistering)
1032 return 0;
1034 for (i = 0; i < alt->desc.bNumEndpoints; ++i)
1035 (void) usb_create_ep_devs(&intf->dev, &alt->endpoint[i], udev);
1036 intf->ep_devs_created = 1;
1037 return 0;
1040 static void remove_intf_ep_devs(struct usb_interface *intf)
1042 struct usb_host_interface *alt = intf->cur_altsetting;
1043 int i;
1045 if (!intf->ep_devs_created)
1046 return;
1048 for (i = 0; i < alt->desc.bNumEndpoints; ++i)
1049 usb_remove_ep_devs(&alt->endpoint[i]);
1050 intf->ep_devs_created = 0;
1054 * usb_disable_endpoint -- Disable an endpoint by address
1055 * @dev: the device whose endpoint is being disabled
1056 * @epaddr: the endpoint's address. Endpoint number for output,
1057 * endpoint number + USB_DIR_IN for input
1058 * @reset_hardware: flag to erase any endpoint state stored in the
1059 * controller hardware
1061 * Disables the endpoint for URB submission and nukes all pending URBs.
1062 * If @reset_hardware is set then also deallocates hcd/hardware state
1063 * for the endpoint.
1065 void usb_disable_endpoint(struct usb_device *dev, unsigned int epaddr,
1066 bool reset_hardware)
1068 unsigned int epnum = epaddr & USB_ENDPOINT_NUMBER_MASK;
1069 struct usb_host_endpoint *ep;
1071 if (!dev)
1072 return;
1074 if (usb_endpoint_out(epaddr)) {
1075 ep = dev->ep_out[epnum];
1076 if (reset_hardware)
1077 dev->ep_out[epnum] = NULL;
1078 } else {
1079 ep = dev->ep_in[epnum];
1080 if (reset_hardware)
1081 dev->ep_in[epnum] = NULL;
1083 if (ep) {
1084 ep->enabled = 0;
1085 usb_hcd_flush_endpoint(dev, ep);
1086 if (reset_hardware)
1087 usb_hcd_disable_endpoint(dev, ep);
1092 * usb_reset_endpoint - Reset an endpoint's state.
1093 * @dev: the device whose endpoint is to be reset
1094 * @epaddr: the endpoint's address. Endpoint number for output,
1095 * endpoint number + USB_DIR_IN for input
1097 * Resets any host-side endpoint state such as the toggle bit,
1098 * sequence number or current window.
1100 void usb_reset_endpoint(struct usb_device *dev, unsigned int epaddr)
1102 unsigned int epnum = epaddr & USB_ENDPOINT_NUMBER_MASK;
1103 struct usb_host_endpoint *ep;
1105 if (usb_endpoint_out(epaddr))
1106 ep = dev->ep_out[epnum];
1107 else
1108 ep = dev->ep_in[epnum];
1109 if (ep)
1110 usb_hcd_reset_endpoint(dev, ep);
1112 EXPORT_SYMBOL_GPL(usb_reset_endpoint);
1116 * usb_disable_interface -- Disable all endpoints for an interface
1117 * @dev: the device whose interface is being disabled
1118 * @intf: pointer to the interface descriptor
1119 * @reset_hardware: flag to erase any endpoint state stored in the
1120 * controller hardware
1122 * Disables all the endpoints for the interface's current altsetting.
1124 void usb_disable_interface(struct usb_device *dev, struct usb_interface *intf,
1125 bool reset_hardware)
1127 struct usb_host_interface *alt = intf->cur_altsetting;
1128 int i;
1130 for (i = 0; i < alt->desc.bNumEndpoints; ++i) {
1131 usb_disable_endpoint(dev,
1132 alt->endpoint[i].desc.bEndpointAddress,
1133 reset_hardware);
1138 * usb_disable_device - Disable all the endpoints for a USB device
1139 * @dev: the device whose endpoints are being disabled
1140 * @skip_ep0: 0 to disable endpoint 0, 1 to skip it.
1142 * Disables all the device's endpoints, potentially including endpoint 0.
1143 * Deallocates hcd/hardware state for the endpoints (nuking all or most
1144 * pending urbs) and usbcore state for the interfaces, so that usbcore
1145 * must usb_set_configuration() before any interfaces could be used.
1147 void usb_disable_device(struct usb_device *dev, int skip_ep0)
1149 int i;
1150 struct usb_hcd *hcd = bus_to_hcd(dev->bus);
1152 /* getting rid of interfaces will disconnect
1153 * any drivers bound to them (a key side effect)
1155 if (dev->actconfig) {
1157 * FIXME: In order to avoid self-deadlock involving the
1158 * bandwidth_mutex, we have to mark all the interfaces
1159 * before unregistering any of them.
1161 for (i = 0; i < dev->actconfig->desc.bNumInterfaces; i++)
1162 dev->actconfig->interface[i]->unregistering = 1;
1164 for (i = 0; i < dev->actconfig->desc.bNumInterfaces; i++) {
1165 struct usb_interface *interface;
1167 /* remove this interface if it has been registered */
1168 interface = dev->actconfig->interface[i];
1169 if (!device_is_registered(&interface->dev))
1170 continue;
1171 dev_dbg(&dev->dev, "unregistering interface %s\n",
1172 dev_name(&interface->dev));
1173 remove_intf_ep_devs(interface);
1174 device_del(&interface->dev);
1177 /* Now that the interfaces are unbound, nobody should
1178 * try to access them.
1180 for (i = 0; i < dev->actconfig->desc.bNumInterfaces; i++) {
1181 put_device(&dev->actconfig->interface[i]->dev);
1182 dev->actconfig->interface[i] = NULL;
1185 if (dev->usb2_hw_lpm_enabled == 1)
1186 usb_set_usb2_hardware_lpm(dev, 0);
1187 usb_unlocked_disable_lpm(dev);
1188 usb_disable_ltm(dev);
1190 dev->actconfig = NULL;
1191 if (dev->state == USB_STATE_CONFIGURED)
1192 usb_set_device_state(dev, USB_STATE_ADDRESS);
1195 dev_dbg(&dev->dev, "%s nuking %s URBs\n", __func__,
1196 skip_ep0 ? "non-ep0" : "all");
1197 if (hcd->driver->check_bandwidth) {
1198 /* First pass: Cancel URBs, leave endpoint pointers intact. */
1199 for (i = skip_ep0; i < 16; ++i) {
1200 usb_disable_endpoint(dev, i, false);
1201 usb_disable_endpoint(dev, i + USB_DIR_IN, false);
1203 /* Remove endpoints from the host controller internal state */
1204 mutex_lock(hcd->bandwidth_mutex);
1205 usb_hcd_alloc_bandwidth(dev, NULL, NULL, NULL);
1206 mutex_unlock(hcd->bandwidth_mutex);
1207 /* Second pass: remove endpoint pointers */
1209 for (i = skip_ep0; i < 16; ++i) {
1210 usb_disable_endpoint(dev, i, true);
1211 usb_disable_endpoint(dev, i + USB_DIR_IN, true);
1216 * usb_enable_endpoint - Enable an endpoint for USB communications
1217 * @dev: the device whose interface is being enabled
1218 * @ep: the endpoint
1219 * @reset_ep: flag to reset the endpoint state
1221 * Resets the endpoint state if asked, and sets dev->ep_{in,out} pointers.
1222 * For control endpoints, both the input and output sides are handled.
1224 void usb_enable_endpoint(struct usb_device *dev, struct usb_host_endpoint *ep,
1225 bool reset_ep)
1227 int epnum = usb_endpoint_num(&ep->desc);
1228 int is_out = usb_endpoint_dir_out(&ep->desc);
1229 int is_control = usb_endpoint_xfer_control(&ep->desc);
1231 if (reset_ep)
1232 usb_hcd_reset_endpoint(dev, ep);
1233 if (is_out || is_control)
1234 dev->ep_out[epnum] = ep;
1235 if (!is_out || is_control)
1236 dev->ep_in[epnum] = ep;
1237 ep->enabled = 1;
1241 * usb_enable_interface - Enable all the endpoints for an interface
1242 * @dev: the device whose interface is being enabled
1243 * @intf: pointer to the interface descriptor
1244 * @reset_eps: flag to reset the endpoints' state
1246 * Enables all the endpoints for the interface's current altsetting.
1248 void usb_enable_interface(struct usb_device *dev,
1249 struct usb_interface *intf, bool reset_eps)
1251 struct usb_host_interface *alt = intf->cur_altsetting;
1252 int i;
1254 for (i = 0; i < alt->desc.bNumEndpoints; ++i)
1255 usb_enable_endpoint(dev, &alt->endpoint[i], reset_eps);
1259 * usb_set_interface - Makes a particular alternate setting be current
1260 * @dev: the device whose interface is being updated
1261 * @interface: the interface being updated
1262 * @alternate: the setting being chosen.
1263 * Context: !in_interrupt ()
1265 * This is used to enable data transfers on interfaces that may not
1266 * be enabled by default. Not all devices support such configurability.
1267 * Only the driver bound to an interface may change its setting.
1269 * Within any given configuration, each interface may have several
1270 * alternative settings. These are often used to control levels of
1271 * bandwidth consumption. For example, the default setting for a high
1272 * speed interrupt endpoint may not send more than 64 bytes per microframe,
1273 * while interrupt transfers of up to 3KBytes per microframe are legal.
1274 * Also, isochronous endpoints may never be part of an
1275 * interface's default setting. To access such bandwidth, alternate
1276 * interface settings must be made current.
1278 * Note that in the Linux USB subsystem, bandwidth associated with
1279 * an endpoint in a given alternate setting is not reserved until an URB
1280 * is submitted that needs that bandwidth. Some other operating systems
1281 * allocate bandwidth early, when a configuration is chosen.
1283 * This call is synchronous, and may not be used in an interrupt context.
1284 * Also, drivers must not change altsettings while urbs are scheduled for
1285 * endpoints in that interface; all such urbs must first be completed
1286 * (perhaps forced by unlinking).
1288 * Return: Zero on success, or else the status code returned by the
1289 * underlying usb_control_msg() call.
1291 int usb_set_interface(struct usb_device *dev, int interface, int alternate)
1293 struct usb_interface *iface;
1294 struct usb_host_interface *alt;
1295 struct usb_hcd *hcd = bus_to_hcd(dev->bus);
1296 int ret;
1297 int manual = 0;
1298 unsigned int epaddr;
1299 unsigned int pipe;
1301 if (dev->state == USB_STATE_SUSPENDED)
1302 return -EHOSTUNREACH;
1304 iface = usb_ifnum_to_if(dev, interface);
1305 if (!iface) {
1306 dev_dbg(&dev->dev, "selecting invalid interface %d\n",
1307 interface);
1308 return -EINVAL;
1310 if (iface->unregistering)
1311 return -ENODEV;
1313 alt = usb_altnum_to_altsetting(iface, alternate);
1314 if (!alt) {
1315 dev_warn(&dev->dev, "selecting invalid altsetting %d\n",
1316 alternate);
1317 return -EINVAL;
1320 /* Make sure we have enough bandwidth for this alternate interface.
1321 * Remove the current alt setting and add the new alt setting.
1323 mutex_lock(hcd->bandwidth_mutex);
1324 /* Disable LPM, and re-enable it once the new alt setting is installed,
1325 * so that the xHCI driver can recalculate the U1/U2 timeouts.
1327 if (usb_disable_lpm(dev)) {
1328 dev_err(&iface->dev, "%s Failed to disable LPM\n.", __func__);
1329 mutex_unlock(hcd->bandwidth_mutex);
1330 return -ENOMEM;
1332 ret = usb_hcd_alloc_bandwidth(dev, NULL, iface->cur_altsetting, alt);
1333 if (ret < 0) {
1334 dev_info(&dev->dev, "Not enough bandwidth for altsetting %d\n",
1335 alternate);
1336 usb_enable_lpm(dev);
1337 mutex_unlock(hcd->bandwidth_mutex);
1338 return ret;
1341 if (dev->quirks & USB_QUIRK_NO_SET_INTF)
1342 ret = -EPIPE;
1343 else
1344 ret = usb_control_msg(dev, usb_sndctrlpipe(dev, 0),
1345 USB_REQ_SET_INTERFACE, USB_RECIP_INTERFACE,
1346 alternate, interface, NULL, 0, 5000);
1348 /* 9.4.10 says devices don't need this and are free to STALL the
1349 * request if the interface only has one alternate setting.
1351 if (ret == -EPIPE && iface->num_altsetting == 1) {
1352 dev_dbg(&dev->dev,
1353 "manual set_interface for iface %d, alt %d\n",
1354 interface, alternate);
1355 manual = 1;
1356 } else if (ret < 0) {
1357 /* Re-instate the old alt setting */
1358 usb_hcd_alloc_bandwidth(dev, NULL, alt, iface->cur_altsetting);
1359 usb_enable_lpm(dev);
1360 mutex_unlock(hcd->bandwidth_mutex);
1361 return ret;
1363 mutex_unlock(hcd->bandwidth_mutex);
1365 /* FIXME drivers shouldn't need to replicate/bugfix the logic here
1366 * when they implement async or easily-killable versions of this or
1367 * other "should-be-internal" functions (like clear_halt).
1368 * should hcd+usbcore postprocess control requests?
1371 /* prevent submissions using previous endpoint settings */
1372 if (iface->cur_altsetting != alt) {
1373 remove_intf_ep_devs(iface);
1374 usb_remove_sysfs_intf_files(iface);
1376 usb_disable_interface(dev, iface, true);
1378 iface->cur_altsetting = alt;
1380 /* Now that the interface is installed, re-enable LPM. */
1381 usb_unlocked_enable_lpm(dev);
1383 /* If the interface only has one altsetting and the device didn't
1384 * accept the request, we attempt to carry out the equivalent action
1385 * by manually clearing the HALT feature for each endpoint in the
1386 * new altsetting.
1388 if (manual) {
1389 int i;
1391 for (i = 0; i < alt->desc.bNumEndpoints; i++) {
1392 epaddr = alt->endpoint[i].desc.bEndpointAddress;
1393 pipe = __create_pipe(dev,
1394 USB_ENDPOINT_NUMBER_MASK & epaddr) |
1395 (usb_endpoint_out(epaddr) ?
1396 USB_DIR_OUT : USB_DIR_IN);
1398 usb_clear_halt(dev, pipe);
1402 /* 9.1.1.5: reset toggles for all endpoints in the new altsetting
1404 * Note:
1405 * Despite EP0 is always present in all interfaces/AS, the list of
1406 * endpoints from the descriptor does not contain EP0. Due to its
1407 * omnipresence one might expect EP0 being considered "affected" by
1408 * any SetInterface request and hence assume toggles need to be reset.
1409 * However, EP0 toggles are re-synced for every individual transfer
1410 * during the SETUP stage - hence EP0 toggles are "don't care" here.
1411 * (Likewise, EP0 never "halts" on well designed devices.)
1413 usb_enable_interface(dev, iface, true);
1414 if (device_is_registered(&iface->dev)) {
1415 usb_create_sysfs_intf_files(iface);
1416 create_intf_ep_devs(iface);
1418 return 0;
1420 EXPORT_SYMBOL_GPL(usb_set_interface);
1423 * usb_reset_configuration - lightweight device reset
1424 * @dev: the device whose configuration is being reset
1426 * This issues a standard SET_CONFIGURATION request to the device using
1427 * the current configuration. The effect is to reset most USB-related
1428 * state in the device, including interface altsettings (reset to zero),
1429 * endpoint halts (cleared), and endpoint state (only for bulk and interrupt
1430 * endpoints). Other usbcore state is unchanged, including bindings of
1431 * usb device drivers to interfaces.
1433 * Because this affects multiple interfaces, avoid using this with composite
1434 * (multi-interface) devices. Instead, the driver for each interface may
1435 * use usb_set_interface() on the interfaces it claims. Be careful though;
1436 * some devices don't support the SET_INTERFACE request, and others won't
1437 * reset all the interface state (notably endpoint state). Resetting the whole
1438 * configuration would affect other drivers' interfaces.
1440 * The caller must own the device lock.
1442 * Return: Zero on success, else a negative error code.
1444 int usb_reset_configuration(struct usb_device *dev)
1446 int i, retval;
1447 struct usb_host_config *config;
1448 struct usb_hcd *hcd = bus_to_hcd(dev->bus);
1450 if (dev->state == USB_STATE_SUSPENDED)
1451 return -EHOSTUNREACH;
1453 /* caller must have locked the device and must own
1454 * the usb bus readlock (so driver bindings are stable);
1455 * calls during probe() are fine
1458 for (i = 1; i < 16; ++i) {
1459 usb_disable_endpoint(dev, i, true);
1460 usb_disable_endpoint(dev, i + USB_DIR_IN, true);
1463 config = dev->actconfig;
1464 retval = 0;
1465 mutex_lock(hcd->bandwidth_mutex);
1466 /* Disable LPM, and re-enable it once the configuration is reset, so
1467 * that the xHCI driver can recalculate the U1/U2 timeouts.
1469 if (usb_disable_lpm(dev)) {
1470 dev_err(&dev->dev, "%s Failed to disable LPM\n.", __func__);
1471 mutex_unlock(hcd->bandwidth_mutex);
1472 return -ENOMEM;
1474 /* Make sure we have enough bandwidth for each alternate setting 0 */
1475 for (i = 0; i < config->desc.bNumInterfaces; i++) {
1476 struct usb_interface *intf = config->interface[i];
1477 struct usb_host_interface *alt;
1479 alt = usb_altnum_to_altsetting(intf, 0);
1480 if (!alt)
1481 alt = &intf->altsetting[0];
1482 if (alt != intf->cur_altsetting)
1483 retval = usb_hcd_alloc_bandwidth(dev, NULL,
1484 intf->cur_altsetting, alt);
1485 if (retval < 0)
1486 break;
1488 /* If not, reinstate the old alternate settings */
1489 if (retval < 0) {
1490 reset_old_alts:
1491 for (i--; i >= 0; i--) {
1492 struct usb_interface *intf = config->interface[i];
1493 struct usb_host_interface *alt;
1495 alt = usb_altnum_to_altsetting(intf, 0);
1496 if (!alt)
1497 alt = &intf->altsetting[0];
1498 if (alt != intf->cur_altsetting)
1499 usb_hcd_alloc_bandwidth(dev, NULL,
1500 alt, intf->cur_altsetting);
1502 usb_enable_lpm(dev);
1503 mutex_unlock(hcd->bandwidth_mutex);
1504 return retval;
1506 retval = usb_control_msg(dev, usb_sndctrlpipe(dev, 0),
1507 USB_REQ_SET_CONFIGURATION, 0,
1508 config->desc.bConfigurationValue, 0,
1509 NULL, 0, USB_CTRL_SET_TIMEOUT);
1510 if (retval < 0)
1511 goto reset_old_alts;
1512 mutex_unlock(hcd->bandwidth_mutex);
1514 /* re-init hc/hcd interface/endpoint state */
1515 for (i = 0; i < config->desc.bNumInterfaces; i++) {
1516 struct usb_interface *intf = config->interface[i];
1517 struct usb_host_interface *alt;
1519 alt = usb_altnum_to_altsetting(intf, 0);
1521 /* No altsetting 0? We'll assume the first altsetting.
1522 * We could use a GetInterface call, but if a device is
1523 * so non-compliant that it doesn't have altsetting 0
1524 * then I wouldn't trust its reply anyway.
1526 if (!alt)
1527 alt = &intf->altsetting[0];
1529 if (alt != intf->cur_altsetting) {
1530 remove_intf_ep_devs(intf);
1531 usb_remove_sysfs_intf_files(intf);
1533 intf->cur_altsetting = alt;
1534 usb_enable_interface(dev, intf, true);
1535 if (device_is_registered(&intf->dev)) {
1536 usb_create_sysfs_intf_files(intf);
1537 create_intf_ep_devs(intf);
1540 /* Now that the interfaces are installed, re-enable LPM. */
1541 usb_unlocked_enable_lpm(dev);
1542 return 0;
1544 EXPORT_SYMBOL_GPL(usb_reset_configuration);
1546 static void usb_release_interface(struct device *dev)
1548 struct usb_interface *intf = to_usb_interface(dev);
1549 struct usb_interface_cache *intfc =
1550 altsetting_to_usb_interface_cache(intf->altsetting);
1552 kref_put(&intfc->ref, usb_release_interface_cache);
1553 kfree(intf);
1556 static int usb_if_uevent(struct device *dev, struct kobj_uevent_env *env)
1558 struct usb_device *usb_dev;
1559 struct usb_interface *intf;
1560 struct usb_host_interface *alt;
1562 intf = to_usb_interface(dev);
1563 usb_dev = interface_to_usbdev(intf);
1564 alt = intf->cur_altsetting;
1566 if (add_uevent_var(env, "INTERFACE=%d/%d/%d",
1567 alt->desc.bInterfaceClass,
1568 alt->desc.bInterfaceSubClass,
1569 alt->desc.bInterfaceProtocol))
1570 return -ENOMEM;
1572 if (add_uevent_var(env,
1573 "MODALIAS=usb:"
1574 "v%04Xp%04Xd%04Xdc%02Xdsc%02Xdp%02Xic%02Xisc%02Xip%02Xin%02X",
1575 le16_to_cpu(usb_dev->descriptor.idVendor),
1576 le16_to_cpu(usb_dev->descriptor.idProduct),
1577 le16_to_cpu(usb_dev->descriptor.bcdDevice),
1578 usb_dev->descriptor.bDeviceClass,
1579 usb_dev->descriptor.bDeviceSubClass,
1580 usb_dev->descriptor.bDeviceProtocol,
1581 alt->desc.bInterfaceClass,
1582 alt->desc.bInterfaceSubClass,
1583 alt->desc.bInterfaceProtocol,
1584 alt->desc.bInterfaceNumber))
1585 return -ENOMEM;
1587 return 0;
1590 struct device_type usb_if_device_type = {
1591 .name = "usb_interface",
1592 .release = usb_release_interface,
1593 .uevent = usb_if_uevent,
1596 static struct usb_interface_assoc_descriptor *find_iad(struct usb_device *dev,
1597 struct usb_host_config *config,
1598 u8 inum)
1600 struct usb_interface_assoc_descriptor *retval = NULL;
1601 struct usb_interface_assoc_descriptor *intf_assoc;
1602 int first_intf;
1603 int last_intf;
1604 int i;
1606 for (i = 0; (i < USB_MAXIADS && config->intf_assoc[i]); i++) {
1607 intf_assoc = config->intf_assoc[i];
1608 if (intf_assoc->bInterfaceCount == 0)
1609 continue;
1611 first_intf = intf_assoc->bFirstInterface;
1612 last_intf = first_intf + (intf_assoc->bInterfaceCount - 1);
1613 if (inum >= first_intf && inum <= last_intf) {
1614 if (!retval)
1615 retval = intf_assoc;
1616 else
1617 dev_err(&dev->dev, "Interface #%d referenced"
1618 " by multiple IADs\n", inum);
1622 return retval;
1627 * Internal function to queue a device reset
1629 * This is initialized into the workstruct in 'struct
1630 * usb_device->reset_ws' that is launched by
1631 * message.c:usb_set_configuration() when initializing each 'struct
1632 * usb_interface'.
1634 * It is safe to get the USB device without reference counts because
1635 * the life cycle of @iface is bound to the life cycle of @udev. Then,
1636 * this function will be ran only if @iface is alive (and before
1637 * freeing it any scheduled instances of it will have been cancelled).
1639 * We need to set a flag (usb_dev->reset_running) because when we call
1640 * the reset, the interfaces might be unbound. The current interface
1641 * cannot try to remove the queued work as it would cause a deadlock
1642 * (you cannot remove your work from within your executing
1643 * workqueue). This flag lets it know, so that
1644 * usb_cancel_queued_reset() doesn't try to do it.
1646 * See usb_queue_reset_device() for more details
1648 static void __usb_queue_reset_device(struct work_struct *ws)
1650 int rc;
1651 struct usb_interface *iface =
1652 container_of(ws, struct usb_interface, reset_ws);
1653 struct usb_device *udev = interface_to_usbdev(iface);
1655 rc = usb_lock_device_for_reset(udev, iface);
1656 if (rc >= 0) {
1657 iface->reset_running = 1;
1658 usb_reset_device(udev);
1659 iface->reset_running = 0;
1660 usb_unlock_device(udev);
1666 * usb_set_configuration - Makes a particular device setting be current
1667 * @dev: the device whose configuration is being updated
1668 * @configuration: the configuration being chosen.
1669 * Context: !in_interrupt(), caller owns the device lock
1671 * This is used to enable non-default device modes. Not all devices
1672 * use this kind of configurability; many devices only have one
1673 * configuration.
1675 * @configuration is the value of the configuration to be installed.
1676 * According to the USB spec (e.g. section 9.1.1.5), configuration values
1677 * must be non-zero; a value of zero indicates that the device in
1678 * unconfigured. However some devices erroneously use 0 as one of their
1679 * configuration values. To help manage such devices, this routine will
1680 * accept @configuration = -1 as indicating the device should be put in
1681 * an unconfigured state.
1683 * USB device configurations may affect Linux interoperability,
1684 * power consumption and the functionality available. For example,
1685 * the default configuration is limited to using 100mA of bus power,
1686 * so that when certain device functionality requires more power,
1687 * and the device is bus powered, that functionality should be in some
1688 * non-default device configuration. Other device modes may also be
1689 * reflected as configuration options, such as whether two ISDN
1690 * channels are available independently; and choosing between open
1691 * standard device protocols (like CDC) or proprietary ones.
1693 * Note that a non-authorized device (dev->authorized == 0) will only
1694 * be put in unconfigured mode.
1696 * Note that USB has an additional level of device configurability,
1697 * associated with interfaces. That configurability is accessed using
1698 * usb_set_interface().
1700 * This call is synchronous. The calling context must be able to sleep,
1701 * must own the device lock, and must not hold the driver model's USB
1702 * bus mutex; usb interface driver probe() methods cannot use this routine.
1704 * Returns zero on success, or else the status code returned by the
1705 * underlying call that failed. On successful completion, each interface
1706 * in the original device configuration has been destroyed, and each one
1707 * in the new configuration has been probed by all relevant usb device
1708 * drivers currently known to the kernel.
1710 int usb_set_configuration(struct usb_device *dev, int configuration)
1712 int i, ret;
1713 struct usb_host_config *cp = NULL;
1714 struct usb_interface **new_interfaces = NULL;
1715 struct usb_hcd *hcd = bus_to_hcd(dev->bus);
1716 int n, nintf;
1718 if (dev->authorized == 0 || configuration == -1)
1719 configuration = 0;
1720 else {
1721 for (i = 0; i < dev->descriptor.bNumConfigurations; i++) {
1722 if (dev->config[i].desc.bConfigurationValue ==
1723 configuration) {
1724 cp = &dev->config[i];
1725 break;
1729 if ((!cp && configuration != 0))
1730 return -EINVAL;
1732 /* The USB spec says configuration 0 means unconfigured.
1733 * But if a device includes a configuration numbered 0,
1734 * we will accept it as a correctly configured state.
1735 * Use -1 if you really want to unconfigure the device.
1737 if (cp && configuration == 0)
1738 dev_warn(&dev->dev, "config 0 descriptor??\n");
1740 /* Allocate memory for new interfaces before doing anything else,
1741 * so that if we run out then nothing will have changed. */
1742 n = nintf = 0;
1743 if (cp) {
1744 nintf = cp->desc.bNumInterfaces;
1745 new_interfaces = kmalloc(nintf * sizeof(*new_interfaces),
1746 GFP_NOIO);
1747 if (!new_interfaces) {
1748 dev_err(&dev->dev, "Out of memory\n");
1749 return -ENOMEM;
1752 for (; n < nintf; ++n) {
1753 new_interfaces[n] = kzalloc(
1754 sizeof(struct usb_interface),
1755 GFP_NOIO);
1756 if (!new_interfaces[n]) {
1757 dev_err(&dev->dev, "Out of memory\n");
1758 ret = -ENOMEM;
1759 free_interfaces:
1760 while (--n >= 0)
1761 kfree(new_interfaces[n]);
1762 kfree(new_interfaces);
1763 return ret;
1767 i = dev->bus_mA - usb_get_max_power(dev, cp);
1768 if (i < 0)
1769 dev_warn(&dev->dev, "new config #%d exceeds power "
1770 "limit by %dmA\n",
1771 configuration, -i);
1774 /* Wake up the device so we can send it the Set-Config request */
1775 ret = usb_autoresume_device(dev);
1776 if (ret)
1777 goto free_interfaces;
1779 /* if it's already configured, clear out old state first.
1780 * getting rid of old interfaces means unbinding their drivers.
1782 if (dev->state != USB_STATE_ADDRESS)
1783 usb_disable_device(dev, 1); /* Skip ep0 */
1785 /* Get rid of pending async Set-Config requests for this device */
1786 cancel_async_set_config(dev);
1788 /* Make sure we have bandwidth (and available HCD resources) for this
1789 * configuration. Remove endpoints from the schedule if we're dropping
1790 * this configuration to set configuration 0. After this point, the
1791 * host controller will not allow submissions to dropped endpoints. If
1792 * this call fails, the device state is unchanged.
1794 mutex_lock(hcd->bandwidth_mutex);
1795 /* Disable LPM, and re-enable it once the new configuration is
1796 * installed, so that the xHCI driver can recalculate the U1/U2
1797 * timeouts.
1799 if (dev->actconfig && usb_disable_lpm(dev)) {
1800 dev_err(&dev->dev, "%s Failed to disable LPM\n.", __func__);
1801 mutex_unlock(hcd->bandwidth_mutex);
1802 ret = -ENOMEM;
1803 goto free_interfaces;
1805 ret = usb_hcd_alloc_bandwidth(dev, cp, NULL, NULL);
1806 if (ret < 0) {
1807 if (dev->actconfig)
1808 usb_enable_lpm(dev);
1809 mutex_unlock(hcd->bandwidth_mutex);
1810 usb_autosuspend_device(dev);
1811 goto free_interfaces;
1815 * Initialize the new interface structures and the
1816 * hc/hcd/usbcore interface/endpoint state.
1818 for (i = 0; i < nintf; ++i) {
1819 struct usb_interface_cache *intfc;
1820 struct usb_interface *intf;
1821 struct usb_host_interface *alt;
1823 cp->interface[i] = intf = new_interfaces[i];
1824 intfc = cp->intf_cache[i];
1825 intf->altsetting = intfc->altsetting;
1826 intf->num_altsetting = intfc->num_altsetting;
1827 kref_get(&intfc->ref);
1829 alt = usb_altnum_to_altsetting(intf, 0);
1831 /* No altsetting 0? We'll assume the first altsetting.
1832 * We could use a GetInterface call, but if a device is
1833 * so non-compliant that it doesn't have altsetting 0
1834 * then I wouldn't trust its reply anyway.
1836 if (!alt)
1837 alt = &intf->altsetting[0];
1839 intf->intf_assoc =
1840 find_iad(dev, cp, alt->desc.bInterfaceNumber);
1841 intf->cur_altsetting = alt;
1842 usb_enable_interface(dev, intf, true);
1843 intf->dev.parent = &dev->dev;
1844 intf->dev.driver = NULL;
1845 intf->dev.bus = &usb_bus_type;
1846 intf->dev.type = &usb_if_device_type;
1847 intf->dev.groups = usb_interface_groups;
1848 intf->dev.dma_mask = dev->dev.dma_mask;
1849 INIT_WORK(&intf->reset_ws, __usb_queue_reset_device);
1850 intf->minor = -1;
1851 device_initialize(&intf->dev);
1852 pm_runtime_no_callbacks(&intf->dev);
1853 dev_set_name(&intf->dev, "%d-%s:%d.%d",
1854 dev->bus->busnum, dev->devpath,
1855 configuration, alt->desc.bInterfaceNumber);
1857 kfree(new_interfaces);
1859 ret = usb_control_msg(dev, usb_sndctrlpipe(dev, 0),
1860 USB_REQ_SET_CONFIGURATION, 0, configuration, 0,
1861 NULL, 0, USB_CTRL_SET_TIMEOUT);
1862 if (ret < 0 && cp) {
1864 * All the old state is gone, so what else can we do?
1865 * The device is probably useless now anyway.
1867 usb_hcd_alloc_bandwidth(dev, NULL, NULL, NULL);
1868 for (i = 0; i < nintf; ++i) {
1869 usb_disable_interface(dev, cp->interface[i], true);
1870 put_device(&cp->interface[i]->dev);
1871 cp->interface[i] = NULL;
1873 cp = NULL;
1876 dev->actconfig = cp;
1877 mutex_unlock(hcd->bandwidth_mutex);
1879 if (!cp) {
1880 usb_set_device_state(dev, USB_STATE_ADDRESS);
1882 /* Leave LPM disabled while the device is unconfigured. */
1883 usb_autosuspend_device(dev);
1884 return ret;
1886 usb_set_device_state(dev, USB_STATE_CONFIGURED);
1888 if (cp->string == NULL &&
1889 !(dev->quirks & USB_QUIRK_CONFIG_INTF_STRINGS))
1890 cp->string = usb_cache_string(dev, cp->desc.iConfiguration);
1892 /* Now that the interfaces are installed, re-enable LPM. */
1893 usb_unlocked_enable_lpm(dev);
1894 /* Enable LTM if it was turned off by usb_disable_device. */
1895 usb_enable_ltm(dev);
1897 /* Now that all the interfaces are set up, register them
1898 * to trigger binding of drivers to interfaces. probe()
1899 * routines may install different altsettings and may
1900 * claim() any interfaces not yet bound. Many class drivers
1901 * need that: CDC, audio, video, etc.
1903 for (i = 0; i < nintf; ++i) {
1904 struct usb_interface *intf = cp->interface[i];
1906 dev_dbg(&dev->dev,
1907 "adding %s (config #%d, interface %d)\n",
1908 dev_name(&intf->dev), configuration,
1909 intf->cur_altsetting->desc.bInterfaceNumber);
1910 device_enable_async_suspend(&intf->dev);
1911 ret = device_add(&intf->dev);
1912 if (ret != 0) {
1913 dev_err(&dev->dev, "device_add(%s) --> %d\n",
1914 dev_name(&intf->dev), ret);
1915 continue;
1917 create_intf_ep_devs(intf);
1920 usb_autosuspend_device(dev);
1921 return 0;
1924 static LIST_HEAD(set_config_list);
1925 static DEFINE_SPINLOCK(set_config_lock);
1927 struct set_config_request {
1928 struct usb_device *udev;
1929 int config;
1930 struct work_struct work;
1931 struct list_head node;
1934 /* Worker routine for usb_driver_set_configuration() */
1935 static void driver_set_config_work(struct work_struct *work)
1937 struct set_config_request *req =
1938 container_of(work, struct set_config_request, work);
1939 struct usb_device *udev = req->udev;
1941 usb_lock_device(udev);
1942 spin_lock(&set_config_lock);
1943 list_del(&req->node);
1944 spin_unlock(&set_config_lock);
1946 if (req->config >= -1) /* Is req still valid? */
1947 usb_set_configuration(udev, req->config);
1948 usb_unlock_device(udev);
1949 usb_put_dev(udev);
1950 kfree(req);
1953 /* Cancel pending Set-Config requests for a device whose configuration
1954 * was just changed
1956 static void cancel_async_set_config(struct usb_device *udev)
1958 struct set_config_request *req;
1960 spin_lock(&set_config_lock);
1961 list_for_each_entry(req, &set_config_list, node) {
1962 if (req->udev == udev)
1963 req->config = -999; /* Mark as cancelled */
1965 spin_unlock(&set_config_lock);
1969 * usb_driver_set_configuration - Provide a way for drivers to change device configurations
1970 * @udev: the device whose configuration is being updated
1971 * @config: the configuration being chosen.
1972 * Context: In process context, must be able to sleep
1974 * Device interface drivers are not allowed to change device configurations.
1975 * This is because changing configurations will destroy the interface the
1976 * driver is bound to and create new ones; it would be like a floppy-disk
1977 * driver telling the computer to replace the floppy-disk drive with a
1978 * tape drive!
1980 * Still, in certain specialized circumstances the need may arise. This
1981 * routine gets around the normal restrictions by using a work thread to
1982 * submit the change-config request.
1984 * Return: 0 if the request was successfully queued, error code otherwise.
1985 * The caller has no way to know whether the queued request will eventually
1986 * succeed.
1988 int usb_driver_set_configuration(struct usb_device *udev, int config)
1990 struct set_config_request *req;
1992 req = kmalloc(sizeof(*req), GFP_KERNEL);
1993 if (!req)
1994 return -ENOMEM;
1995 req->udev = udev;
1996 req->config = config;
1997 INIT_WORK(&req->work, driver_set_config_work);
1999 spin_lock(&set_config_lock);
2000 list_add(&req->node, &set_config_list);
2001 spin_unlock(&set_config_lock);
2003 usb_get_dev(udev);
2004 schedule_work(&req->work);
2005 return 0;
2007 EXPORT_SYMBOL_GPL(usb_driver_set_configuration);