1// SPDX-License-Identifier: GPL-2.0
2/*
3 * Released under the GPLv2 only.
4 */
5
6#include <linux/module.h>
7#include <linux/string.h>
8#include <linux/bitops.h>
9#include <linux/slab.h>
10#include <linux/log2.h>
11#include <linux/kmsan.h>
12#include <linux/usb.h>
13#include <linux/wait.h>
14#include <linux/usb/hcd.h>
15#include <linux/scatterlist.h>
16
17#define to_urb(d) container_of(d, struct urb, kref)
18
19
20static void urb_destroy(struct kref *kref)
21{
22 struct urb *urb = to_urb(kref);
23
24 if (urb->transfer_flags & URB_FREE_BUFFER)
25 kfree(objp: urb->transfer_buffer);
26
27 kfree(objp: urb);
28}
29
30/**
31 * usb_init_urb - initializes a urb so that it can be used by a USB driver
32 * @urb: pointer to the urb to initialize
33 *
34 * Initializes a urb so that the USB subsystem can use it properly.
35 *
36 * If a urb is created with a call to usb_alloc_urb() it is not
37 * necessary to call this function. Only use this if you allocate the
38 * space for a struct urb on your own. If you call this function, be
39 * careful when freeing the memory for your urb that it is no longer in
40 * use by the USB core.
41 *
42 * Only use this function if you _really_ understand what you are doing.
43 */
44void usb_init_urb(struct urb *urb)
45{
46 if (urb) {
47 memset(s: urb, c: 0, n: sizeof(*urb));
48 kref_init(kref: &urb->kref);
49 INIT_LIST_HEAD(list: &urb->urb_list);
50 INIT_LIST_HEAD(list: &urb->anchor_list);
51 }
52}
53EXPORT_SYMBOL_GPL(usb_init_urb);
54
55/**
56 * usb_alloc_urb - creates a new urb for a USB driver to use
57 * @iso_packets: number of iso packets for this urb
58 * @mem_flags: the type of memory to allocate, see kmalloc() for a list of
59 * valid options for this.
60 *
61 * Creates an urb for the USB driver to use, initializes a few internal
62 * structures, increments the usage counter, and returns a pointer to it.
63 *
64 * If the driver want to use this urb for interrupt, control, or bulk
65 * endpoints, pass '0' as the number of iso packets.
66 *
67 * The driver must call usb_free_urb() when it is finished with the urb.
68 *
69 * Return: A pointer to the new urb, or %NULL if no memory is available.
70 */
71struct urb *usb_alloc_urb(int iso_packets, gfp_t mem_flags)
72{
73 struct urb *urb;
74
75 urb = kmalloc(struct_size(urb, iso_frame_desc, iso_packets),
76 mem_flags);
77 if (!urb)
78 return NULL;
79 usb_init_urb(urb);
80 return urb;
81}
82EXPORT_SYMBOL_GPL(usb_alloc_urb);
83
84/**
85 * usb_free_urb - frees the memory used by a urb when all users of it are finished
86 * @urb: pointer to the urb to free, may be NULL
87 *
88 * Must be called when a user of a urb is finished with it. When the last user
89 * of the urb calls this function, the memory of the urb is freed.
90 *
91 * Note: The transfer buffer associated with the urb is not freed unless the
92 * URB_FREE_BUFFER transfer flag is set.
93 */
94void usb_free_urb(struct urb *urb)
95{
96 if (urb)
97 kref_put(kref: &urb->kref, release: urb_destroy);
98}
99EXPORT_SYMBOL_GPL(usb_free_urb);
100
101/**
102 * usb_get_urb - increments the reference count of the urb
103 * @urb: pointer to the urb to modify, may be NULL
104 *
105 * This must be called whenever a urb is transferred from a device driver to a
106 * host controller driver. This allows proper reference counting to happen
107 * for urbs.
108 *
109 * Return: A pointer to the urb with the incremented reference counter.
110 */
111struct urb *usb_get_urb(struct urb *urb)
112{
113 if (urb)
114 kref_get(kref: &urb->kref);
115 return urb;
116}
117EXPORT_SYMBOL_GPL(usb_get_urb);
118
119/**
120 * usb_anchor_urb - anchors an URB while it is processed
121 * @urb: pointer to the urb to anchor
122 * @anchor: pointer to the anchor
123 *
124 * This can be called to have access to URBs which are to be executed
125 * without bothering to track them
126 */
127void usb_anchor_urb(struct urb *urb, struct usb_anchor *anchor)
128{
129 unsigned long flags;
130
131 spin_lock_irqsave(&anchor->lock, flags);
132 usb_get_urb(urb);
133 list_add_tail(new: &urb->anchor_list, head: &anchor->urb_list);
134 urb->anchor = anchor;
135
136 if (unlikely(anchor->poisoned))
137 atomic_inc(v: &urb->reject);
138
139 spin_unlock_irqrestore(lock: &anchor->lock, flags);
140}
141EXPORT_SYMBOL_GPL(usb_anchor_urb);
142
143static int usb_anchor_check_wakeup(struct usb_anchor *anchor)
144{
145 return atomic_read(v: &anchor->suspend_wakeups) == 0 &&
146 list_empty(head: &anchor->urb_list);
147}
148
149/* Callers must hold anchor->lock */
150static void __usb_unanchor_urb(struct urb *urb, struct usb_anchor *anchor)
151{
152 urb->anchor = NULL;
153 list_del(entry: &urb->anchor_list);
154 usb_put_urb(urb);
155 if (usb_anchor_check_wakeup(anchor))
156 wake_up(&anchor->wait);
157}
158
159/**
160 * usb_unanchor_urb - unanchors an URB
161 * @urb: pointer to the urb to anchor
162 *
163 * Call this to stop the system keeping track of this URB
164 */
165void usb_unanchor_urb(struct urb *urb)
166{
167 unsigned long flags;
168 struct usb_anchor *anchor;
169
170 if (!urb)
171 return;
172
173 anchor = urb->anchor;
174 if (!anchor)
175 return;
176
177 spin_lock_irqsave(&anchor->lock, flags);
178 /*
179 * At this point, we could be competing with another thread which
180 * has the same intention. To protect the urb from being unanchored
181 * twice, only the winner of the race gets the job.
182 */
183 if (likely(anchor == urb->anchor))
184 __usb_unanchor_urb(urb, anchor);
185 spin_unlock_irqrestore(lock: &anchor->lock, flags);
186}
187EXPORT_SYMBOL_GPL(usb_unanchor_urb);
188
189/*-------------------------------------------------------------------*/
190
191static const int pipetypes[4] = {
192 PIPE_CONTROL, PIPE_ISOCHRONOUS, PIPE_BULK, PIPE_INTERRUPT
193};
194
195/**
196 * usb_pipe_type_check - sanity check of a specific pipe for a usb device
197 * @dev: struct usb_device to be checked
198 * @pipe: pipe to check
199 *
200 * This performs a light-weight sanity check for the endpoint in the
201 * given usb device. It returns 0 if the pipe is valid for the specific usb
202 * device, otherwise a negative error code.
203 */
204int usb_pipe_type_check(struct usb_device *dev, unsigned int pipe)
205{
206 const struct usb_host_endpoint *ep;
207
208 ep = usb_pipe_endpoint(dev, pipe);
209 if (!ep)
210 return -EINVAL;
211 if (usb_pipetype(pipe) != pipetypes[usb_endpoint_type(epd: &ep->desc)])
212 return -EINVAL;
213 return 0;
214}
215EXPORT_SYMBOL_GPL(usb_pipe_type_check);
216
217/**
218 * usb_urb_ep_type_check - sanity check of endpoint in the given urb
219 * @urb: urb to be checked
220 *
221 * This performs a light-weight sanity check for the endpoint in the
222 * given urb. It returns 0 if the urb contains a valid endpoint, otherwise
223 * a negative error code.
224 */
225int usb_urb_ep_type_check(const struct urb *urb)
226{
227 return usb_pipe_type_check(urb->dev, urb->pipe);
228}
229EXPORT_SYMBOL_GPL(usb_urb_ep_type_check);
230
231/**
232 * usb_submit_urb - issue an asynchronous transfer request for an endpoint
233 * @urb: pointer to the urb describing the request
234 * @mem_flags: the type of memory to allocate, see kmalloc() for a list
235 * of valid options for this.
236 *
237 * This submits a transfer request, and transfers control of the URB
238 * describing that request to the USB subsystem. Request completion will
239 * be indicated later, asynchronously, by calling the completion handler.
240 * The three types of completion are success, error, and unlink
241 * (a software-induced fault, also called "request cancellation").
242 *
243 * URBs may be submitted in interrupt context.
244 *
245 * The caller must have correctly initialized the URB before submitting
246 * it. Functions such as usb_fill_bulk_urb() and usb_fill_control_urb() are
247 * available to ensure that most fields are correctly initialized, for
248 * the particular kind of transfer, although they will not initialize
249 * any transfer flags.
250 *
251 * If the submission is successful, the complete() callback from the URB
252 * will be called exactly once, when the USB core and Host Controller Driver
253 * (HCD) are finished with the URB. When the completion function is called,
254 * control of the URB is returned to the device driver which issued the
255 * request. The completion handler may then immediately free or reuse that
256 * URB.
257 *
258 * With few exceptions, USB device drivers should never access URB fields
259 * provided by usbcore or the HCD until its complete() is called.
260 * The exceptions relate to periodic transfer scheduling. For both
261 * interrupt and isochronous urbs, as part of successful URB submission
262 * urb->interval is modified to reflect the actual transfer period used
263 * (normally some power of two units). And for isochronous urbs,
264 * urb->start_frame is modified to reflect when the URB's transfers were
265 * scheduled to start.
266 *
267 * Not all isochronous transfer scheduling policies will work, but most
268 * host controller drivers should easily handle ISO queues going from now
269 * until 10-200 msec into the future. Drivers should try to keep at
270 * least one or two msec of data in the queue; many controllers require
271 * that new transfers start at least 1 msec in the future when they are
272 * added. If the driver is unable to keep up and the queue empties out,
273 * the behavior for new submissions is governed by the URB_ISO_ASAP flag.
274 * If the flag is set, or if the queue is idle, then the URB is always
275 * assigned to the first available (and not yet expired) slot in the
276 * endpoint's schedule. If the flag is not set and the queue is active
277 * then the URB is always assigned to the next slot in the schedule
278 * following the end of the endpoint's previous URB, even if that slot is
279 * in the past. When a packet is assigned in this way to a slot that has
280 * already expired, the packet is not transmitted and the corresponding
281 * usb_iso_packet_descriptor's status field will return -EXDEV. If this
282 * would happen to all the packets in the URB, submission fails with a
283 * -EXDEV error code.
284 *
285 * For control endpoints, the synchronous usb_control_msg() call is
286 * often used (in non-interrupt context) instead of this call.
287 * That is often used through convenience wrappers, for the requests
288 * that are standardized in the USB 2.0 specification. For bulk
289 * endpoints, a synchronous usb_bulk_msg() call is available.
290 *
291 * Return:
292 * 0 on successful submissions. A negative error number otherwise.
293 *
294 * Request Queuing:
295 *
296 * URBs may be submitted to endpoints before previous ones complete, to
297 * minimize the impact of interrupt latencies and system overhead on data
298 * throughput. With that queuing policy, an endpoint's queue would never
299 * be empty. This is required for continuous isochronous data streams,
300 * and may also be required for some kinds of interrupt transfers. Such
301 * queuing also maximizes bandwidth utilization by letting USB controllers
302 * start work on later requests before driver software has finished the
303 * completion processing for earlier (successful) requests.
304 *
305 * As of Linux 2.6, all USB endpoint transfer queues support depths greater
306 * than one. This was previously a HCD-specific behavior, except for ISO
307 * transfers. Non-isochronous endpoint queues are inactive during cleanup
308 * after faults (transfer errors or cancellation).
309 *
310 * Reserved Bandwidth Transfers:
311 *
312 * Periodic transfers (interrupt or isochronous) are performed repeatedly,
313 * using the interval specified in the urb. Submitting the first urb to
314 * the endpoint reserves the bandwidth necessary to make those transfers.
315 * If the USB subsystem can't allocate sufficient bandwidth to perform
316 * the periodic request, submitting such a periodic request should fail.
317 *
318 * For devices under xHCI, the bandwidth is reserved at configuration time, or
319 * when the alt setting is selected. If there is not enough bus bandwidth, the
320 * configuration/alt setting request will fail. Therefore, submissions to
321 * periodic endpoints on devices under xHCI should never fail due to bandwidth
322 * constraints.
323 *
324 * Device drivers must explicitly request that repetition, by ensuring that
325 * some URB is always on the endpoint's queue (except possibly for short
326 * periods during completion callbacks). When there is no longer an urb
327 * queued, the endpoint's bandwidth reservation is canceled. This means
328 * drivers can use their completion handlers to ensure they keep bandwidth
329 * they need, by reinitializing and resubmitting the just-completed urb
330 * until the driver longer needs that periodic bandwidth.
331 *
332 * Memory Flags:
333 *
334 * The general rules for how to decide which mem_flags to use
335 * are the same as for kmalloc. There are four
336 * different possible values; GFP_KERNEL, GFP_NOFS, GFP_NOIO and
337 * GFP_ATOMIC.
338 *
339 * GFP_NOFS is not ever used, as it has not been implemented yet.
340 *
341 * GFP_ATOMIC is used when
342 * (a) you are inside a completion handler, an interrupt, bottom half,
343 * tasklet or timer, or
344 * (b) you are holding a spinlock or rwlock (does not apply to
345 * semaphores), or
346 * (c) current->state != TASK_RUNNING, this is the case only after
347 * you've changed it.
348 *
349 * GFP_NOIO is used in the block io path and error handling of storage
350 * devices.
351 *
352 * All other situations use GFP_KERNEL.
353 *
354 * Some more specific rules for mem_flags can be inferred, such as
355 * (1) start_xmit, timeout, and receive methods of network drivers must
356 * use GFP_ATOMIC (they are called with a spinlock held);
357 * (2) queuecommand methods of scsi drivers must use GFP_ATOMIC (also
358 * called with a spinlock held);
359 * (3) If you use a kernel thread with a network driver you must use
360 * GFP_NOIO, unless (b) or (c) apply;
361 * (4) after you have done a down() you can use GFP_KERNEL, unless (b) or (c)
362 * apply or your are in a storage driver's block io path;
363 * (5) USB probe and disconnect can use GFP_KERNEL unless (b) or (c) apply; and
364 * (6) changing firmware on a running storage or net device uses
365 * GFP_NOIO, unless b) or c) apply
366 *
367 */
368int usb_submit_urb(struct urb *urb, gfp_t mem_flags)
369{
370 int xfertype, max;
371 struct usb_device *dev;
372 struct usb_host_endpoint *ep;
373 int is_out;
374 unsigned int allowed;
375 bool is_eusb2_isoch_double;
376
377 if (!urb || !urb->complete)
378 return -EINVAL;
379 if (urb->hcpriv) {
380 WARN_ONCE(1, "URB %p submitted while active\n", urb);
381 return -EBUSY;
382 }
383
384 dev = urb->dev;
385 if ((!dev) || (dev->state < USB_STATE_UNAUTHENTICATED))
386 return -ENODEV;
387
388 /* For now, get the endpoint from the pipe. Eventually drivers
389 * will be required to set urb->ep directly and we will eliminate
390 * urb->pipe.
391 */
392 ep = usb_pipe_endpoint(dev, pipe: urb->pipe);
393 if (!ep)
394 return -ENOENT;
395
396 urb->ep = ep;
397 urb->status = -EINPROGRESS;
398 urb->actual_length = 0;
399
400 /* Lots of sanity checks, so HCDs can rely on clean data
401 * and don't need to duplicate tests
402 */
403 xfertype = usb_endpoint_type(epd: &ep->desc);
404 if (xfertype == USB_ENDPOINT_XFER_CONTROL) {
405 struct usb_ctrlrequest *setup =
406 (struct usb_ctrlrequest *) urb->setup_packet;
407
408 if (!setup)
409 return -ENOEXEC;
410 is_out = !(setup->bRequestType & USB_DIR_IN) ||
411 !setup->wLength;
412 dev_WARN_ONCE(&dev->dev, (usb_pipeout(urb->pipe) != is_out),
413 "BOGUS control dir, pipe %x doesn't match bRequestType %x\n",
414 urb->pipe, setup->bRequestType);
415 if (le16_to_cpu(setup->wLength) != urb->transfer_buffer_length) {
416 dev_dbg(&dev->dev, "BOGUS control len %d doesn't match transfer length %d\n",
417 le16_to_cpu(setup->wLength),
418 urb->transfer_buffer_length);
419 return -EBADR;
420 }
421 } else {
422 is_out = usb_endpoint_dir_out(epd: &ep->desc);
423 }
424
425 /* Clear the internal flags and cache the direction for later use */
426 urb->transfer_flags &= ~(URB_DIR_MASK | URB_DMA_MAP_SINGLE |
427 URB_DMA_MAP_PAGE | URB_DMA_MAP_SG | URB_MAP_LOCAL |
428 URB_SETUP_MAP_SINGLE | URB_SETUP_MAP_LOCAL |
429 URB_DMA_SG_COMBINED);
430 urb->transfer_flags |= (is_out ? URB_DIR_OUT : URB_DIR_IN);
431 kmsan_handle_urb(urb, is_out);
432
433 if (xfertype != USB_ENDPOINT_XFER_CONTROL &&
434 dev->state < USB_STATE_CONFIGURED)
435 return -ENODEV;
436
437 max = usb_endpoint_maxp(epd: &ep->desc);
438 is_eusb2_isoch_double = usb_endpoint_is_hs_isoc_double(udev: dev, ep);
439 if (!max && !is_eusb2_isoch_double) {
440 dev_dbg(&dev->dev,
441 "bogus endpoint ep%d%s in %s (bad maxpacket %d)\n",
442 usb_endpoint_num(&ep->desc), is_out ? "out" : "in",
443 __func__, max);
444 return -EMSGSIZE;
445 }
446
447 /* periodic transfers limit size per frame/uframe,
448 * but drivers only control those sizes for ISO.
449 * while we're checking, initialize return status.
450 */
451 if (xfertype == USB_ENDPOINT_XFER_ISOC) {
452 int n, len;
453
454 /* SuperSpeed isoc endpoints have up to 16 bursts of up to
455 * 3 packets each
456 */
457 if (dev->speed >= USB_SPEED_SUPER) {
458 int burst = 1 + ep->ss_ep_comp.bMaxBurst;
459 int mult = USB_SS_MULT(ep->ss_ep_comp.bmAttributes);
460 max *= burst;
461 max *= mult;
462 }
463
464 if (dev->speed == USB_SPEED_SUPER_PLUS &&
465 USB_SS_SSP_ISOC_COMP(ep->ss_ep_comp.bmAttributes)) {
466 struct usb_ssp_isoc_ep_comp_descriptor *isoc_ep_comp;
467
468 isoc_ep_comp = &ep->ssp_isoc_ep_comp;
469 max = le32_to_cpu(isoc_ep_comp->dwBytesPerInterval);
470 }
471
472 /* High speed, 1-3 packets/uframe, max 6 for eUSB2 double bw */
473 if (dev->speed == USB_SPEED_HIGH) {
474 if (is_eusb2_isoch_double)
475 max = le32_to_cpu(ep->eusb2_isoc_ep_comp.dwBytesPerInterval);
476 else
477 max *= usb_endpoint_maxp_mult(epd: &ep->desc);
478 }
479
480 if (urb->number_of_packets <= 0)
481 return -EINVAL;
482 for (n = 0; n < urb->number_of_packets; n++) {
483 len = urb->iso_frame_desc[n].length;
484 if (len < 0 || len > max)
485 return -EMSGSIZE;
486 urb->iso_frame_desc[n].status = -EXDEV;
487 urb->iso_frame_desc[n].actual_length = 0;
488 }
489 } else if (urb->num_sgs && !urb->dev->bus->no_sg_constraint) {
490 struct scatterlist *sg;
491 int i;
492
493 for_each_sg(urb->sg, sg, urb->num_sgs - 1, i)
494 if (sg->length % max)
495 return -EINVAL;
496 }
497
498 /* the I/O buffer must be mapped/unmapped, except when length=0 */
499 if (urb->transfer_buffer_length > INT_MAX)
500 return -EMSGSIZE;
501
502 /*
503 * stuff that drivers shouldn't do, but which shouldn't
504 * cause problems in HCDs if they get it wrong.
505 */
506
507 /* Check that the pipe's type matches the endpoint's type */
508 if (usb_pipe_type_check(urb->dev, urb->pipe))
509 dev_warn_once(&dev->dev, "BOGUS urb xfer, pipe %x != type %x\n",
510 usb_pipetype(urb->pipe), pipetypes[xfertype]);
511
512 /* Check against a simple/standard policy */
513 allowed = (URB_NO_TRANSFER_DMA_MAP | URB_NO_INTERRUPT | URB_DIR_MASK |
514 URB_FREE_BUFFER);
515 switch (xfertype) {
516 case USB_ENDPOINT_XFER_BULK:
517 case USB_ENDPOINT_XFER_INT:
518 if (is_out)
519 allowed |= URB_ZERO_PACKET;
520 fallthrough;
521 default: /* all non-iso endpoints */
522 if (!is_out)
523 allowed |= URB_SHORT_NOT_OK;
524 break;
525 case USB_ENDPOINT_XFER_ISOC:
526 allowed |= URB_ISO_ASAP;
527 break;
528 }
529 allowed &= urb->transfer_flags;
530
531 /* warn if submitter gave bogus flags */
532 if (allowed != urb->transfer_flags)
533 dev_WARN(&dev->dev, "BOGUS urb flags, %x --> %x\n",
534 urb->transfer_flags, allowed);
535
536 /*
537 * Force periodic transfer intervals to be legal values that are
538 * a power of two (so HCDs don't need to).
539 *
540 * FIXME want bus->{intr,iso}_sched_horizon values here. Each HC
541 * supports different values... this uses EHCI/UHCI defaults (and
542 * EHCI can use smaller non-default values).
543 */
544 switch (xfertype) {
545 case USB_ENDPOINT_XFER_ISOC:
546 case USB_ENDPOINT_XFER_INT:
547 /* too small? */
548 if (urb->interval <= 0)
549 return -EINVAL;
550
551 /* too big? */
552 switch (dev->speed) {
553 case USB_SPEED_SUPER_PLUS:
554 case USB_SPEED_SUPER: /* units are 125us */
555 /* Handle up to 2^(16-1) microframes */
556 if (urb->interval > (1 << 15))
557 return -EINVAL;
558 max = 1 << 15;
559 break;
560 case USB_SPEED_HIGH: /* units are microframes */
561 /* NOTE usb handles 2^15 */
562 if (urb->interval > (1024 * 8))
563 urb->interval = 1024 * 8;
564 max = 1024 * 8;
565 break;
566 case USB_SPEED_FULL: /* units are frames/msec */
567 case USB_SPEED_LOW:
568 if (xfertype == USB_ENDPOINT_XFER_INT) {
569 if (urb->interval > 255)
570 return -EINVAL;
571 /* NOTE ohci only handles up to 32 */
572 max = 128;
573 } else {
574 if (urb->interval > 1024)
575 urb->interval = 1024;
576 /* NOTE usb and ohci handle up to 2^15 */
577 max = 1024;
578 }
579 break;
580 default:
581 return -EINVAL;
582 }
583 /* Round down to a power of 2, no more than max */
584 urb->interval = min(max, 1 << ilog2(urb->interval));
585 }
586
587 return usb_hcd_submit_urb(urb, mem_flags);
588}
589EXPORT_SYMBOL_GPL(usb_submit_urb);
590
591/*-------------------------------------------------------------------*/
592
593/**
594 * usb_unlink_urb - abort/cancel a transfer request for an endpoint
595 * @urb: pointer to urb describing a previously submitted request,
596 * may be NULL
597 *
598 * This routine cancels an in-progress request. URBs complete only once
599 * per submission, and may be canceled only once per submission.
600 * Successful cancellation means termination of @urb will be expedited
601 * and the completion handler will be called with a status code
602 * indicating that the request has been canceled (rather than any other
603 * code).
604 *
605 * Drivers should not call this routine or related routines, such as
606 * usb_kill_urb(), after their disconnect method has returned. The
607 * disconnect function should synchronize with a driver's I/O routines
608 * to insure that all URB-related activity has completed before it returns.
609 *
610 * This request is asynchronous, however the HCD might call the ->complete()
611 * callback during unlink. Therefore when drivers call usb_unlink_urb(), they
612 * must not hold any locks that may be taken by the completion function.
613 * Success is indicated by returning -EINPROGRESS, at which time the URB will
614 * probably not yet have been given back to the device driver. When it is
615 * eventually called, the completion function will see @urb->status ==
616 * -ECONNRESET.
617 * Failure is indicated by usb_unlink_urb() returning any other value.
618 * Unlinking will fail when @urb is not currently "linked" (i.e., it was
619 * never submitted, or it was unlinked before, or the hardware is already
620 * finished with it), even if the completion handler has not yet run.
621 *
622 * The URB must not be deallocated while this routine is running. In
623 * particular, when a driver calls this routine, it must insure that the
624 * completion handler cannot deallocate the URB.
625 *
626 * Return: -EINPROGRESS on success. See description for other values on
627 * failure.
628 *
629 * Unlinking and Endpoint Queues:
630 *
631 * [The behaviors and guarantees described below do not apply to virtual
632 * root hubs but only to endpoint queues for physical USB devices.]
633 *
634 * Host Controller Drivers (HCDs) place all the URBs for a particular
635 * endpoint in a queue. Normally the queue advances as the controller
636 * hardware processes each request. But when an URB terminates with an
637 * error its queue generally stops (see below), at least until that URB's
638 * completion routine returns. It is guaranteed that a stopped queue
639 * will not restart until all its unlinked URBs have been fully retired,
640 * with their completion routines run, even if that's not until some time
641 * after the original completion handler returns. The same behavior and
642 * guarantee apply when an URB terminates because it was unlinked.
643 *
644 * Bulk and interrupt endpoint queues are guaranteed to stop whenever an
645 * URB terminates with any sort of error, including -ECONNRESET, -ENOENT,
646 * and -EREMOTEIO. Control endpoint queues behave the same way except
647 * that they are not guaranteed to stop for -EREMOTEIO errors. Queues
648 * for isochronous endpoints are treated differently, because they must
649 * advance at fixed rates. Such queues do not stop when an URB
650 * encounters an error or is unlinked. An unlinked isochronous URB may
651 * leave a gap in the stream of packets; it is undefined whether such
652 * gaps can be filled in.
653 *
654 * Note that early termination of an URB because a short packet was
655 * received will generate a -EREMOTEIO error if and only if the
656 * URB_SHORT_NOT_OK flag is set. By setting this flag, USB device
657 * drivers can build deep queues for large or complex bulk transfers
658 * and clean them up reliably after any sort of aborted transfer by
659 * unlinking all pending URBs at the first fault.
660 *
661 * When a control URB terminates with an error other than -EREMOTEIO, it
662 * is quite likely that the status stage of the transfer will not take
663 * place.
664 */
665int usb_unlink_urb(struct urb *urb)
666{
667 if (!urb)
668 return -EINVAL;
669 if (!urb->dev)
670 return -ENODEV;
671 if (!urb->ep)
672 return -EIDRM;
673 return usb_hcd_unlink_urb(urb, status: -ECONNRESET);
674}
675EXPORT_SYMBOL_GPL(usb_unlink_urb);
676
677/**
678 * usb_kill_urb - cancel a transfer request and wait for it to finish
679 * @urb: pointer to URB describing a previously submitted request,
680 * may be NULL
681 *
682 * This routine cancels an in-progress request. It is guaranteed that
683 * upon return all completion handlers will have finished and the URB
684 * will be totally idle and available for reuse. These features make
685 * this an ideal way to stop I/O in a disconnect() callback or close()
686 * function. If the request has not already finished or been unlinked
687 * the completion handler will see urb->status == -ENOENT.
688 *
689 * While the routine is running, attempts to resubmit the URB will fail
690 * with error -EPERM. Thus even if the URB's completion handler always
691 * tries to resubmit, it will not succeed and the URB will become idle.
692 *
693 * The URB must not be deallocated while this routine is running. In
694 * particular, when a driver calls this routine, it must insure that the
695 * completion handler cannot deallocate the URB.
696 *
697 * This routine may not be used in an interrupt context (such as a bottom
698 * half or a completion handler), or when holding a spinlock, or in other
699 * situations where the caller can't schedule().
700 *
701 * This routine should not be called by a driver after its disconnect
702 * method has returned.
703 */
704void usb_kill_urb(struct urb *urb)
705{
706 might_sleep();
707 if (!(urb && urb->dev && urb->ep))
708 return;
709 atomic_inc(v: &urb->reject);
710 /*
711 * Order the write of urb->reject above before the read
712 * of urb->use_count below. Pairs with the barriers in
713 * __usb_hcd_giveback_urb() and usb_hcd_submit_urb().
714 */
715 smp_mb__after_atomic();
716
717 usb_hcd_unlink_urb(urb, status: -ENOENT);
718 wait_event(usb_kill_urb_queue, atomic_read(&urb->use_count) == 0);
719
720 atomic_dec(v: &urb->reject);
721}
722EXPORT_SYMBOL_GPL(usb_kill_urb);
723
724/**
725 * usb_poison_urb - reliably kill a transfer and prevent further use of an URB
726 * @urb: pointer to URB describing a previously submitted request,
727 * may be NULL
728 *
729 * This routine cancels an in-progress request. It is guaranteed that
730 * upon return all completion handlers will have finished and the URB
731 * will be totally idle and cannot be reused. These features make
732 * this an ideal way to stop I/O in a disconnect() callback.
733 * If the request has not already finished or been unlinked
734 * the completion handler will see urb->status == -ENOENT.
735 *
736 * After and while the routine runs, attempts to resubmit the URB will fail
737 * with error -EPERM. Thus even if the URB's completion handler always
738 * tries to resubmit, it will not succeed and the URB will become idle.
739 *
740 * The URB must not be deallocated while this routine is running. In
741 * particular, when a driver calls this routine, it must insure that the
742 * completion handler cannot deallocate the URB.
743 *
744 * This routine may not be used in an interrupt context (such as a bottom
745 * half or a completion handler), or when holding a spinlock, or in other
746 * situations where the caller can't schedule().
747 *
748 * This routine should not be called by a driver after its disconnect
749 * method has returned.
750 */
751void usb_poison_urb(struct urb *urb)
752{
753 might_sleep();
754 if (!urb)
755 return;
756 atomic_inc(v: &urb->reject);
757 /*
758 * Order the write of urb->reject above before the read
759 * of urb->use_count below. Pairs with the barriers in
760 * __usb_hcd_giveback_urb() and usb_hcd_submit_urb().
761 */
762 smp_mb__after_atomic();
763
764 if (!urb->dev || !urb->ep)
765 return;
766
767 usb_hcd_unlink_urb(urb, status: -ENOENT);
768 wait_event(usb_kill_urb_queue, atomic_read(&urb->use_count) == 0);
769}
770EXPORT_SYMBOL_GPL(usb_poison_urb);
771
772void usb_unpoison_urb(struct urb *urb)
773{
774 if (!urb)
775 return;
776
777 atomic_dec(v: &urb->reject);
778}
779EXPORT_SYMBOL_GPL(usb_unpoison_urb);
780
781/**
782 * usb_block_urb - reliably prevent further use of an URB
783 * @urb: pointer to URB to be blocked, may be NULL
784 *
785 * After the routine has run, attempts to resubmit the URB will fail
786 * with error -EPERM. Thus even if the URB's completion handler always
787 * tries to resubmit, it will not succeed and the URB will become idle.
788 *
789 * The URB must not be deallocated while this routine is running. In
790 * particular, when a driver calls this routine, it must insure that the
791 * completion handler cannot deallocate the URB.
792 */
793void usb_block_urb(struct urb *urb)
794{
795 if (!urb)
796 return;
797
798 atomic_inc(v: &urb->reject);
799}
800EXPORT_SYMBOL_GPL(usb_block_urb);
801
802/**
803 * usb_kill_anchored_urbs - kill all URBs associated with an anchor
804 * @anchor: anchor the requests are bound to
805 *
806 * This kills all outstanding URBs starting from the back of the queue,
807 * with guarantee that no completer callbacks will take place from the
808 * anchor after this function returns.
809 *
810 * This routine should not be called by a driver after its disconnect
811 * method has returned.
812 */
813void usb_kill_anchored_urbs(struct usb_anchor *anchor)
814{
815 struct urb *victim;
816 int surely_empty;
817
818 do {
819 spin_lock_irq(lock: &anchor->lock);
820 while (!list_empty(head: &anchor->urb_list)) {
821 victim = list_entry(anchor->urb_list.prev,
822 struct urb, anchor_list);
823 /* make sure the URB isn't freed before we kill it */
824 usb_get_urb(victim);
825 spin_unlock_irq(lock: &anchor->lock);
826 /* this will unanchor the URB */
827 usb_kill_urb(victim);
828 usb_put_urb(victim);
829 spin_lock_irq(lock: &anchor->lock);
830 }
831 surely_empty = usb_anchor_check_wakeup(anchor);
832
833 spin_unlock_irq(lock: &anchor->lock);
834 cpu_relax();
835 } while (!surely_empty);
836}
837EXPORT_SYMBOL_GPL(usb_kill_anchored_urbs);
838
839
840/**
841 * usb_poison_anchored_urbs - cease all traffic from an anchor
842 * @anchor: anchor the requests are bound to
843 *
844 * this allows all outstanding URBs to be poisoned starting
845 * from the back of the queue. Newly added URBs will also be
846 * poisoned
847 *
848 * This routine should not be called by a driver after its disconnect
849 * method has returned.
850 */
851void usb_poison_anchored_urbs(struct usb_anchor *anchor)
852{
853 struct urb *victim;
854 int surely_empty;
855
856 do {
857 spin_lock_irq(lock: &anchor->lock);
858 anchor->poisoned = 1;
859 while (!list_empty(head: &anchor->urb_list)) {
860 victim = list_entry(anchor->urb_list.prev,
861 struct urb, anchor_list);
862 /* make sure the URB isn't freed before we kill it */
863 usb_get_urb(victim);
864 spin_unlock_irq(lock: &anchor->lock);
865 /* this will unanchor the URB */
866 usb_poison_urb(victim);
867 usb_put_urb(victim);
868 spin_lock_irq(lock: &anchor->lock);
869 }
870 surely_empty = usb_anchor_check_wakeup(anchor);
871
872 spin_unlock_irq(lock: &anchor->lock);
873 cpu_relax();
874 } while (!surely_empty);
875}
876EXPORT_SYMBOL_GPL(usb_poison_anchored_urbs);
877
878/**
879 * usb_unpoison_anchored_urbs - let an anchor be used successfully again
880 * @anchor: anchor the requests are bound to
881 *
882 * Reverses the effect of usb_poison_anchored_urbs
883 * the anchor can be used normally after it returns
884 */
885void usb_unpoison_anchored_urbs(struct usb_anchor *anchor)
886{
887 unsigned long flags;
888 struct urb *lazarus;
889
890 spin_lock_irqsave(&anchor->lock, flags);
891 list_for_each_entry(lazarus, &anchor->urb_list, anchor_list) {
892 usb_unpoison_urb(lazarus);
893 }
894 anchor->poisoned = 0;
895 spin_unlock_irqrestore(lock: &anchor->lock, flags);
896}
897EXPORT_SYMBOL_GPL(usb_unpoison_anchored_urbs);
898
899/**
900 * usb_anchor_suspend_wakeups
901 * @anchor: the anchor you want to suspend wakeups on
902 *
903 * Call this to stop the last urb being unanchored from waking up any
904 * usb_wait_anchor_empty_timeout waiters. This is used in the hcd urb give-
905 * back path to delay waking up until after the completion handler has run.
906 */
907void usb_anchor_suspend_wakeups(struct usb_anchor *anchor)
908{
909 if (anchor)
910 atomic_inc(v: &anchor->suspend_wakeups);
911}
912EXPORT_SYMBOL_GPL(usb_anchor_suspend_wakeups);
913
914/**
915 * usb_anchor_resume_wakeups
916 * @anchor: the anchor you want to resume wakeups on
917 *
918 * Allow usb_wait_anchor_empty_timeout waiters to be woken up again, and
919 * wake up any current waiters if the anchor is empty.
920 */
921void usb_anchor_resume_wakeups(struct usb_anchor *anchor)
922{
923 if (!anchor)
924 return;
925
926 atomic_dec(v: &anchor->suspend_wakeups);
927 if (usb_anchor_check_wakeup(anchor))
928 wake_up(&anchor->wait);
929}
930EXPORT_SYMBOL_GPL(usb_anchor_resume_wakeups);
931
932/**
933 * usb_wait_anchor_empty_timeout - wait for an anchor to be unused
934 * @anchor: the anchor you want to become unused
935 * @timeout: how long you are willing to wait in milliseconds
936 *
937 * Call this is you want to be sure all an anchor's
938 * URBs have finished
939 *
940 * Return: Non-zero if the anchor became unused. Zero on timeout.
941 */
942int usb_wait_anchor_empty_timeout(struct usb_anchor *anchor,
943 unsigned int timeout)
944{
945 return wait_event_timeout(anchor->wait,
946 usb_anchor_check_wakeup(anchor),
947 msecs_to_jiffies(timeout));
948}
949EXPORT_SYMBOL_GPL(usb_wait_anchor_empty_timeout);
950
951/**
952 * usb_get_from_anchor - get an anchor's oldest urb
953 * @anchor: the anchor whose urb you want
954 *
955 * This will take the oldest urb from an anchor,
956 * unanchor and return it
957 *
958 * Return: The oldest urb from @anchor, or %NULL if @anchor has no
959 * urbs associated with it.
960 */
961struct urb *usb_get_from_anchor(struct usb_anchor *anchor)
962{
963 struct urb *victim;
964 unsigned long flags;
965
966 spin_lock_irqsave(&anchor->lock, flags);
967 if (!list_empty(head: &anchor->urb_list)) {
968 victim = list_entry(anchor->urb_list.next, struct urb,
969 anchor_list);
970 usb_get_urb(victim);
971 __usb_unanchor_urb(urb: victim, anchor);
972 } else {
973 victim = NULL;
974 }
975 spin_unlock_irqrestore(lock: &anchor->lock, flags);
976
977 return victim;
978}
979
980EXPORT_SYMBOL_GPL(usb_get_from_anchor);
981
982/**
983 * usb_scuttle_anchored_urbs - unanchor all an anchor's urbs
984 * @anchor: the anchor whose urbs you want to unanchor
985 *
986 * use this to get rid of all an anchor's urbs
987 */
988void usb_scuttle_anchored_urbs(struct usb_anchor *anchor)
989{
990 struct urb *victim;
991 unsigned long flags;
992 int surely_empty;
993
994 do {
995 spin_lock_irqsave(&anchor->lock, flags);
996 while (!list_empty(head: &anchor->urb_list)) {
997 victim = list_entry(anchor->urb_list.prev,
998 struct urb, anchor_list);
999 __usb_unanchor_urb(urb: victim, anchor);
1000 }
1001 surely_empty = usb_anchor_check_wakeup(anchor);
1002
1003 spin_unlock_irqrestore(lock: &anchor->lock, flags);
1004 cpu_relax();
1005 } while (!surely_empty);
1006}
1007
1008EXPORT_SYMBOL_GPL(usb_scuttle_anchored_urbs);
1009
1010/**
1011 * usb_anchor_empty - is an anchor empty
1012 * @anchor: the anchor you want to query
1013 *
1014 * Return: 1 if the anchor has no urbs associated with it.
1015 */
1016int usb_anchor_empty(struct usb_anchor *anchor)
1017{
1018 return list_empty(head: &anchor->urb_list);
1019}
1020
1021EXPORT_SYMBOL_GPL(usb_anchor_empty);
1022
1023