The existing kerneldoc documentation for URB completion callbacks is
incorrect about the context in which the callbacks occur; it is not
always in_interrupt.  State explicitly that a callback may occur in
any context with no guarantees, and likewise for the status of
CPU-local interrupts.

Documentation update only; no code changes.

Signed-off-by: Alan Stern <stern@rowland.harvard.edu>

---

 drivers/usb/core/urb.c |    8 ++++++++
 include/linux/usb.h    |    7 ++++++-
 2 files changed, 14 insertions(+), 1 deletion(-)

Index: usb-devel/drivers/usb/core/urb.c
===================================================================
--- usb-devel.orig/drivers/usb/core/urb.c
+++ usb-devel/drivers/usb/core/urb.c
@@ -254,6 +254,14 @@ EXPORT_SYMBOL_GPL(usb_urb_ep_type_check)
  * request.  The completion handler may then immediately free or reuse that
  * URB.
  *
+ * The USB core makes no guarantees at all about the context in which
+ * the complete() callback is invoked.  It may be in process context,
+ * interrupt context, BH context, or anything else.  Also, local interrupts
+ * may be enabled or disabled.  To deal with this, the callback routine
+ * must always use the _irqsave and _irqrestore variants of things like
+ * spin_lock(), and it must always use GFP_ATOMIC for its memory
+ * allocation flags.
+ *
  * With few exceptions, USB device drivers should never access URB fields
  * provided by usbcore or the HCD until its complete() is called.
  * The exceptions relate to periodic transfer scheduling.  For both
Index: usb-devel/include/linux/usb.h
===================================================================
--- usb-devel.orig/include/linux/usb.h
+++ usb-devel/include/linux/usb.h
@@ -1605,7 +1605,12 @@ typedef void (*usb_complete_t)(struct ur
  *
  * Completion Callbacks:
  *
- * The completion callback is made in_interrupt(), and one of the first
+ * The completion callback can occur in any context: process, interrupt,
+ * BH, or anything else.  Also, interrupts may or may not be disabled on
+ * the local CPU when the callback runs.  A completion handler routine
+ * must not depend on any particular properties of its environment.
+ *
+ * One of the first
  * things that a completion handler should do is check the status field.
  * The status field is provided for all URBs.  It is used to report
  * unlinked URBs, and status for all non-ISO transfers.  It should not

On 2026-10-15 12:00:46 [-0400], Alan Stern wrote:
> The existing kerneldoc documentation for URB completion callbacks is
> incorrect about the context in which the callbacks occur; it is not
> always in_interrupt.  State explicitly that a callback may occur in
> any context with no guarantees, and likewise for the status of
> CPU-local interrupts.
> 
> Documentation update only; no code changes.
> 
> Signed-off-by: Alan Stern <stern@rowland.harvard.edu>

Reviewed-by: Sebastian Andrzej Siewior <bigeasy@linutronix.de>

usb_hcd_giveback_urb() kernel doc says: 

|  * Context: atomic. The completion callback is invoked either in a work queue
|  * (BH) context or in the caller's context, depending on whether the HCD_BH
|  * flag is set in the @hcd structure, except that URBs submitted to the
|  * root hub always complete in BH context.

Do you think this deserves an update?

Sebastian

On Thu, Oct 15, 2026 at 08:26:43PM +0200, Sebastian Andrzej Siewior wrote:
> On 2026-10-15 12:00:46 [-0400], Alan Stern wrote:
> > The existing kerneldoc documentation for URB completion callbacks is
> > incorrect about the context in which the callbacks occur; it is not
> > always in_interrupt.  State explicitly that a callback may occur in
> > any context with no guarantees, and likewise for the status of
> > CPU-local interrupts.
> > 
> > Documentation update only; no code changes.
> > 
> > Signed-off-by: Alan Stern <stern@rowland.harvard.edu>
> 
> Reviewed-by: Sebastian Andrzej Siewior <bigeasy@linutronix.de>
> 
> usb_hcd_giveback_urb() kernel doc says: 
> 
> |  * Context: atomic. The completion callback is invoked either in a work queue
> |  * (BH) context or in the caller's context, depending on whether the HCD_BH
> |  * flag is set in the @hcd structure, except that URBs submitted to the
> |  * root hub always complete in BH context.
> 
> Do you think this deserves an update?

I think that's okay as is.  It describes the current implementation 
pretty well, even though it doesn't mention the lack of guarantees.  If 
you feel it should be changed, let me know.

Alan Stern

On 2026-10-15 14:35:56 [-0400], Alan Stern wrote:
> On Thu, Oct 15, 2026 at 08:26:43PM +0200, Sebastian Andrzej Siewior wrote:
> > On 2026-10-15 12:00:46 [-0400], Alan Stern wrote:
> > > The existing kerneldoc documentation for URB completion callbacks is
> > > incorrect about the context in which the callbacks occur; it is not
> > > always in_interrupt.  State explicitly that a callback may occur in
> > > any context with no guarantees, and likewise for the status of
> > > CPU-local interrupts.
> > > 
> > > Documentation update only; no code changes.
> > > 
> > > Signed-off-by: Alan Stern <stern@rowland.harvard.edu>
> > 
> > Reviewed-by: Sebastian Andrzej Siewior <bigeasy@linutronix.de>
> > 
> > usb_hcd_giveback_urb() kernel doc says: 
> > 
> > |  * Context: atomic. The completion callback is invoked either in a work queue
> > |  * (BH) context or in the caller's context, depending on whether the HCD_BH
> > |  * flag is set in the @hcd structure, except that URBs submitted to the
> > |  * root hub always complete in BH context.
> > 
> > Do you think this deserves an update?
> 
> I think that's okay as is.  It describes the current implementation 
> pretty well, even though it doesn't mention the lack of guarantees.  If 
> you feel it should be changed, let me know.

It reads as it is always atomic. Maybe removing parts of the description
and adding a pointer to your initial documentation would be better.

> Alan Stern

Sebastian