[src/trunk]: src/sys/dev/usb usb: Clarify contract of usbd_xfer_trycomplete.

[riastradh <riastradh%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/4efd7b257055
branches:  trunk
changeset: 363464:4efd7b257055
user:      riastradh <riastradh%NetBSD.org@localhost>
date:      Sun Mar 13 11:29:01 2022 +0000

description:
usb: Clarify contract of usbd_xfer_trycomplete.

No functional change.  This rule has always been in place since
usbd_xfer_trycomplete was created, just wasn't clearly articulated
anywhere.

diffstat:

 sys/dev/usb/usbdi.c |  10 +++++++---
 1 files changed, 7 insertions(+), 3 deletions(-)

diffs (31 lines):

diff -r 97cd7553346d -r 4efd7b257055 sys/dev/usb/usbdi.c
--- a/sys/dev/usb/usbdi.c       Sun Mar 13 11:28:52 2022 +0000
+++ b/sys/dev/usb/usbdi.c       Sun Mar 13 11:29:01 2022 +0000
@@ -1,4 +1,4 @@
-/*     $NetBSD: usbdi.c,v 1.235 2022/03/13 11:28:42 riastradh Exp $    */
+/*     $NetBSD: usbdi.c,v 1.236 2022/03/13 11:29:01 riastradh Exp $    */
 
 /*
  * Copyright (c) 1998, 2012, 2015 The NetBSD Foundation, Inc.
@@ -32,7 +32,7 @@
  */
 
 #include <sys/cdefs.h>
-__KERNEL_RCSID(0, "$NetBSD: usbdi.c,v 1.235 2022/03/13 11:28:42 riastradh Exp $");
+__KERNEL_RCSID(0, "$NetBSD: usbdi.c,v 1.236 2022/03/13 11:29:01 riastradh Exp $");
 
 #ifdef _KERNEL_OPT
 #include "opt_usb.h"
@@ -1506,7 +1506,11 @@
  *     in a host controller interrupt handler.
  *
  *     Caller must either hold the bus lock or have the bus in polling
- *     mode.
+ *     mode.  If this succeeds, caller must proceed to call
+ *     usb_complete_transfer under the bus lock or with polling
+ *     enabled -- must not release and reacquire the bus lock in the
+ *     meantime.  Failing to heed this rule may lead to catastrophe
+ *     with abort or timeout.
  */
 bool
 usbd_xfer_trycomplete(struct usbd_xfer *xfer)