USB: documentation update for usb_unlink_urb (beafef07) · Commits · e / devices / android_kernel_oneplus_sm7250

drivers/usb/core/urb.c

+45 −43

Original line number	Diff line number	Diff line
		@@ -440,55 +440,57 @@ int usb_submit_urb(struct urb *urb, gfp_t mem_flags)
		* @urb: pointer to urb describing a previously submitted request,
		* may be NULL
		*
		* This routine cancels an in-progress request. URBs complete only
		* once per submission, and may be canceled only once per submission.
		* Successful cancellation means the requests's completion handler will
		* be called with a status code indicating that the request has been
		* canceled (rather than any other code) and will quickly be removed
		* from host controller data structures.
		*
		* This request is always asynchronous.
		* Success is indicated by returning -EINPROGRESS,
		* at which time the URB will normally have been unlinked but not yet
		* given back to the device driver. When it is called, the completion
		* function will see urb->status == -ECONNRESET. Failure is indicated
		* by any other return value. Unlinking will fail when the URB is not
		* currently "linked" (i.e., it was never submitted, or it was unlinked
		* before, or the hardware is already finished with it), even if the
		* completion handler has not yet run.
		* This routine cancels an in-progress request. URBs complete only once
		* per submission, and may be canceled only once per submission.
		* Successful cancellation means termination of @urb will be expedited
		* and the completion handler will be called with a status code
		* indicating that the request has been canceled (rather than any other
		* code).
		*
		* This request is always asynchronous. Success is indicated by
		* returning -EINPROGRESS, at which time the URB will probably not yet
		* have been given back to the device driver. When it is eventually
		* called, the completion function will see @urb->status == -ECONNRESET.
		* Failure is indicated by usb_unlink_urb() returning any other value.
		* Unlinking will fail when @urb is not currently "linked" (i.e., it was
		* never submitted, or it was unlinked before, or the hardware is already
		* finished with it), even if the completion handler has not yet run.
		*
		* Unlinking and Endpoint Queues:
		*
		* [The behaviors and guarantees described below do not apply to virtual
		* root hubs but only to endpoint queues for physical USB devices.]
		*
		* Host Controller Drivers (HCDs) place all the URBs for a particular
		* endpoint in a queue. Normally the queue advances as the controller
		* hardware processes each request. But when an URB terminates with an
		* error its queue stops, at least until that URB's completion routine
		* returns. It is guaranteed that the queue will not restart until all
		* its unlinked URBs have been fully retired, with their completion
		* routines run, even if that's not until some time after the original
		* completion handler returns. Normally the same behavior and guarantees
		* apply when an URB terminates because it was unlinked; however if an
		* URB is unlinked before the hardware has started to execute it, then
		* its queue is not guaranteed to stop until all the preceding URBs have
		* completed.
		*
		* This means that USB device drivers can safely build deep queues for
		* large or complex transfers, and clean them up reliably after any sort
		* of aborted transfer by unlinking all pending URBs at the first fault.
		*
		* Note that an URB terminating early because a short packet was received
		* will count as an error if and only if the URB_SHORT_NOT_OK flag is set.
		* Also, that all unlinks performed in any URB completion handler must
		* be asynchronous.
		*
		* Queues for isochronous endpoints are treated differently, because they
		* advance at fixed rates. Such queues do not stop when an URB is unlinked.
		* An unlinked URB may leave a gap in the stream of packets. It is undefined
		* whether such gaps can be filled in.
		*
		* When a control URB terminates with an error, it is likely that the
		* status stage of the transfer will not take place, even if it is merely
		* a soft error resulting from a short-packet with URB_SHORT_NOT_OK set.
		* error its queue generally stops (see below), at least until that URB's
		* completion routine returns. It is guaranteed that a stopped queue
		* will not restart until all its unlinked URBs have been fully retired,
		* with their completion routines run, even if that's not until some time
		* after the original completion handler returns. The same behavior and
		* guarantee apply when an URB terminates because it was unlinked.
		*
		* Bulk and interrupt endpoint queues are guaranteed to stop whenever an
		* URB terminates with any sort of error, including -ECONNRESET, -ENOENT,
		* and -EREMOTEIO. Control endpoint queues behave the same way except
		* that they are not guaranteed to stop for -EREMOTEIO errors. Queues
		* for isochronous endpoints are treated differently, because they must
		* advance at fixed rates. Such queues do not stop when an URB
		* encounters an error or is unlinked. An unlinked isochronous URB may
		* leave a gap in the stream of packets; it is undefined whether such
		* gaps can be filled in.
		*
		* Note that early termination of an URB because a short packet was
		* received will generate a -EREMOTEIO error if and only if the
		* URB_SHORT_NOT_OK flag is set. By setting this flag, USB device
		* drivers can build deep queues for large or complex bulk transfers
		* and clean them up reliably after any sort of aborted transfer by
		* unlinking all pending URBs at the first fault.
		*
		* When a control URB terminates with an error other than -EREMOTEIO, it
		* is quite likely that the status stage of the transfer will not take
		* place.
		*/
		int usb_unlink_urb(struct urb *urb)
		{