On Thu, 21 Aug 2014, Paul Zimmerman wrote: > > From: Alan Stern [mailto:stern@xxxxxxxxxxxxxxxxxxx] > > Sent: Thursday, August 21, 2014 12:16 PM > > > > On Thu, 21 Aug 2014, Paul Zimmerman wrote: > > > > > AFAIK, it has always been a requirement that usb_ep_dequeue() release > > > the data buffer and call the urb's completion routine before it returns. > > > > Hmmm. I don't know if that really has been a requirement, but it does > > seem to be true in the UDC drivers I'm familiar with. > > > > > Quite a few of the function drivers depend on that, after the call to > > > usb_ep_dequeue() they immediately free the data buffer. So if it's not > > > explicitly documented like that, it should be. > > > > Okay, would you like to write a documentation patch? > > Something like this? I didn't find any references to usp_ep_dequeue() > under Documentation/, so I guess the only place is the kerneldoc in the > header. Yes, that's where it is. > I also fixed up some strange capitalization in the existing > text while I was there. If this looks OK to you I will send a proper > patch submission to Felipe. > > [PATCH] usb: gadget: document a usb_ep_dequeue() requirement > > Document the requirement that the request be dequeued and its > completion routine called before usb_ep_dequeue() returns. > > diff --git a/include/linux/usb/gadget.h b/include/linux/usb/gadget.h > index c3a6185..c540557 100644 > --- a/include/linux/usb/gadget.h > +++ b/include/linux/usb/gadget.h > @@ -345,12 +345,13 @@ static inline int usb_ep_queue(struct usb_ep *ep, > * @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 > + * 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. > + * error code is returned. This is guaranteed to happen before the call to > + * usb_ep_dequeue() returns. > * > - * 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 > + * 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 > * restrictions prevent drivers from supporting configuration changes, > * even to configuration zero (a "chapter 9" requirement). > */ Looks good to me. Acked-by: Alan Stern <stern@xxxxxxxxxxxxxxxxxxx> Alan Stern -- To unsubscribe from this list: send the line "unsubscribe linux-usb" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
