USB: gadget: Improve kerneldoc for usb_ep_dequeue()

USB: gadget: Improve kerneldoc for usb_ep_dequeue()

[Alan Stern]

Commit bf594c1070f5 ("USB: gadget: Document that certain ep operations
can be called in interrupt context") documented that usb_ep_dequeue()
may be called in a non-process context.  It follows that the routine
must not sleep or wait for events.

However, the routine's existing kerneldoc seems to imply that it will
wait until the request being cancelled has fully completed.  This is
not so, and thus the comment needs to be improved.  Misunderstanding
this point may very well have been responsible for a bug recently
uncovered in the f_fs function.

The updated comment explicitly says that the routine may return before
the request's completion handler is called.

Signed-off-by: Alan Stern <stern@rowland.harvard.edu>
CC: John Stultz <john.stultz@linaro.org>
---


[as1883]


 drivers/usb/gadget/udc/core.c |    8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

Index: usb-4.x/drivers/usb/gadget/udc/core.c
===================================================================
--- usb-4.x.orig/drivers/usb/gadget/udc/core.c
+++ usb-4.x/drivers/usb/gadget/udc/core.c
@@ -281,10 +281,10 @@ EXPORT_SYMBOL_GPL(usb_ep_queue);
  * @ep:the endpoint associated with the request
  * @req:the request being canceled
  *
- * If the request is still active on the endpoint, it is dequeued and its
- * completion routine is called (with status -ECONNRESET); else a negative
- * error code is returned. This is guaranteed to happen before the call to
- * usb_ep_dequeue() returns.
+ * If the request is still active on the endpoint, it is dequeued and
+ * eventually its completion routine is called (with status -ECONNRESET);
+ * else a negative error code is returned.  This routine is asynchronous,
+ * that is, it may return before the completion routine runs.
  *
  * Note that some hardware can't clear out write fifos (to unlink the request
  * at the head of the queue) except as part of disconnecting from usb. Such