Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit 371f3b49 authored by Sebastian Andrzej Siewior's avatar Sebastian Andrzej Siewior Committed by Greg Kroah-Hartman
Browse files

usb/core: remove "always" from usb_unlink_urb() kernel doc entry 



The kernel doc entry for usb_unlink_urb() contains the phrase "This
request is always asynchronous.". The "always" leads to the assumption
that the ->complete() callback is not called from within
usb_unlink_urb(). This is not true. The HCD is allowed to call the
->complete() from within ->urb_dequeue() if it is appropriate for the
hardware.
This patch updates the kernel doc so usb-device driver authors make sure
to drop all locks (and make sure it is okay to drop them) which are
acquired by the complete callback before calling usb_unlink_urb().

Signed-off-by: default avatarSebastian Andrzej Siewior <bigeasy@linutronix.de>
Signed-off-by: default avatarGreg Kroah-Hartman <gregkh@linuxfoundation.org>
parent 2a5be878

drivers/usb/core/urb.c

+7 −4
Original line number Diff line number Diff line
@@ -527,10 +527,13 @@ EXPORT_SYMBOL_GPL(usb_submit_urb); 
 * a driver's I/O routines to insure that all URB-related activity has

 * completed before it returns.

 *

 * 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.

 * This request is asynchronous, however the HCD might call the ->complete()

 * callback during unlink. Therefore when drivers call usb_unlink_urb(), they

 * must not hold any locks that may be taken by the completion function.

 * 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