[src/trunk]: src/share/man/man9 - remove some comments about only being relev...

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

details:   https://anonhg.NetBSD.org/src/rev/1b57bf207758
branches:  trunk
changeset: 780319:1b57bf207758
user:      mrg <mrg%NetBSD.org@localhost>
date:      Fri Jul 20 07:55:44 2012 +0000

description:
- remove some comments about only being relevant for usbmp.
- add documentation for usb_rem_task(), and clean up the task doc in
  general.  be clear about SMP issues for tasks
- bump date

diffstat:

 share/man/man9/usbdi.9 |  34 ++++++++++++++++++++++++----------
 1 files changed, 24 insertions(+), 10 deletions(-)

diffs (84 lines):

diff -r a6b66bfb9a8a -r 1b57bf207758 share/man/man9/usbdi.9
--- a/share/man/man9/usbdi.9    Fri Jul 20 07:31:14 2012 +0000
+++ b/share/man/man9/usbdi.9    Fri Jul 20 07:55:44 2012 +0000
@@ -1,4 +1,4 @@
-.\"    $NetBSD: usbdi.9,v 1.23 2012/06/10 06:40:08 mrg Exp $
+.\"    $NetBSD: usbdi.9,v 1.24 2012/07/20 07:55:44 mrg Exp $
 .\"
 .\" Copyright (c) 2012 Matthew R. Green
 .\" All rights reserved.
@@ -54,7 +54,7 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 .\" POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd June 2, 2012
+.Dd July 20, 2012
 .Dt USBDI 9
 .Os
 .Sh NAME
@@ -642,7 +642,6 @@
 and
 .Dv USBD_SYNCHRONOUS_SIG
 flags set.
-This function is only available with the USB SMP code.
 .Pp
 Transfers are aborted via this pipe with
 .Fn usbd_abort_pipe
@@ -900,8 +899,6 @@
 that is being waited on with
 .Fn usb_detach_wait .
 .Pp
-These functions are only available with the USB SMP code.
-.Pp
 The are another pair of functions with similar functionality that do not
 use a condition variable or mutex and should be avoided in new code.
 The
@@ -917,7 +914,9 @@
 The USB stack provides a task management framework to execute tasks
 in a thread context at the soonest opportunity.
 Typically this is used by network drivers to handle periodic updates
-or status change requests.
+or status change requests, or other operations that need to run in
+a normal context.
+.Pp
 The
 .Fn usb_init_task
 function takes a pointer to a
@@ -927,18 +926,33 @@
 and the argument to pass to
 .Fa func ,
 .Fa arg .
-To schedule the task to be run the
+.Pp
+To invoke the task callback the
 .Fn usb_add_task
 function should be called with the
 .Fa iface
-associated with this device, the task queue to invoke
+associated with this device, the task structure
 .Fa task ,
 and the
 .Fa queue
 to run against, either
 .Dv USB_TASKQ_HC
-or
-.Dv USB_TASKQ_DRIVER .
+for operations initiated by host controllers or
+.Dv USB_TASKQ_DRIVER
+for operations initiated by USB drivers.
+.Pp
+To deschedule a potentially running task the
+.Fn usb_rem_task
+function should be called.
+.Pp
+The driver using these facilities is expected to provide the
+necessary serialisation between
+.Fn usb_init_task ,
+.Fn usb_add_task
+and
+.Fn usb_rem_task
+for each specific
+.Ft struct usb_task .
 .Sh SEE ALSO
 .Xr usb 4 ,
 .Xr usbd_status 9