[1/2] usb: gadget: udc: core: update usb_ep_queue() documentation

[Felipe Balbi <felipe.balbi@linux.intel.com>]

Hi,

Alan Stern <stern@rowland.harvard.edu> writes:
> On Mon, 26 Mar 2018, Felipe Balbi wrote:
>
>> Mention that ->complete() should never be called from within
>> usb_ep_queue().
>> 
>> Signed-off-by: Felipe Balbi <felipe.balbi@linux.intel.com>
>> ---
>>  drivers/usb/gadget/udc/core.c | 3 +++
>>  1 file changed, 3 insertions(+)
>> 
>> diff --git a/drivers/usb/gadget/udc/core.c b/drivers/usb/gadget/udc/core.c
>> index 50988b21a21b..842814bc0e4f 100644
>> --- a/drivers/usb/gadget/udc/core.c
>> +++ b/drivers/usb/gadget/udc/core.c
>> @@ -238,6 +238,9 @@ EXPORT_SYMBOL_GPL(usb_ep_free_request);
>>   * arranges to poll once per interval, and the gadget driver usually will
>>   * have queued some data to transfer at that time.
>>   *
>> + * Note that @req's ->complete() callback must never be called from
>> + * within usb_ep_queue() as that can create deadlock situations.
>> + *
>
> I think this is highly questionable.  Certainly it was not David 
> Brownell's original intention; his dummy-hcd driver will sometimes 
> give back a request from within usb_ep_queue() -- and I believe he 
> wrote it that way in order to emulate a feature of his net2280 driver.
>
> In this particular case, the problem is that a driver acquires a 
> spinlock in its complete() routine, but then it holds that same 
> spinlock while submitting a request.  This is a bug; it should be fixed 
> in the driver.  The spinlock should be dropped while the request is 
> submitted.  I'm sure there are examples whether other drivers do this.

usb_ep_queue() can be called from atomic, there's no explicit
requirement that locks should be released. Either one case or the other
should be made explicit.