usb: gadget: udc: core: Document the relation between usb_ep_queue() and completion...

Improve the kerneldoc for usb_ep_queue() to note explicitly that the
request's completion routine will be called if and only if the return
value is 0.  The corresponding fact about usb_submit_urb() for the
host-side API has long been documented, and this has always been the
intention for the gadget API.  But until now, documentation seems to
have been lacking.

Signed-off-by: Alan Stern <stern@rowland.harvard.edu>
Signed-off-by: Felipe Balbi <felipe.balbi@linux.intel.com>

diff --git a/drivers/usb/gadget/udc/core.c b/drivers/usb/gadget/udc/core.c
index 842814bc0e4f9c4b0bf1b0521be16ffad040a923..cab5e4f099240e4a4024734a0b3ec37947301282 100644 (file)
--- a/drivers/usb/gadget/udc/core.c
+++ b/drivers/usb/gadget/udc/core.c
@@ -244,6 +244,12 @@ EXPORT_SYMBOL_GPL(usb_ep_free_request);
  * Returns zero, or a negative error code.  Endpoints that are not enabled
  * report errors; errors will also be
  * reported when the usb peripheral is disconnected.
+ *
+ * If and only if @req is successfully queued (the return value is zero),
+ * @req->complete() will be called exactly once, when the Gadget core and
+ * UDC are finished with the request.  When the completion function is called,
+ * control of the request is returned to the device driver which submitted it.
+ * The completion handler may then immediately free or reuse @req.
  */
 int usb_ep_queue(struct usb_ep *ep,
                               struct usb_request *req, gfp_t gfp_flags)