[src/trunk]: src/share/man/man9 document usbd_open_pipe*(). fix some minor e...

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

details:   https://anonhg.NetBSD.org/src/rev/a3697cbec8de
branches:  trunk
changeset: 779558:a3697cbec8de
user:      mrg <mrg%NetBSD.org@localhost>
date:      Sat Jun 02 23:33:16 2012 +0000

description:
document usbd_open_pipe*().  fix some minor errors.

prepare to re-structure a lot of stuff.

diffstat:

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

diffs (74 lines):

diff -r 175bc750a2f8 -r a3697cbec8de share/man/man9/usbdi.9
--- a/share/man/man9/usbdi.9    Sat Jun 02 23:10:12 2012 +0000
+++ b/share/man/man9/usbdi.9    Sat Jun 02 23:33:16 2012 +0000
@@ -1,4 +1,4 @@
-.\"    $NetBSD: usbdi.9,v 1.17 2012/06/02 23:10:12 mrg Exp $
+.\"    $NetBSD: usbdi.9,v 1.18 2012/06/02 23:33:16 mrg Exp $
 .\"
 .\" Copyright (c) 2012 Matthew R. Green
 .\" All rights reserved.
@@ -131,7 +131,7 @@
 .Fn usbd_open_pipe_intr "usbd_interface_handle iface" "uint8_t address" \
  "uint8_t flags" "usbd_pipe_handle *pipe" \
  "usbd_private_handle priv" "void *buffer" \
- "uint32_t length" "usbd_callback"
+ "uint32_t length" "usbd_callback callback" "int interval"
 .Ft usbd_status
 .Fn usbd_do_request "usbd_device_handle dev" "usb_device_request_t *req" \
  "void *data"
@@ -285,23 +285,49 @@
 A transfer describes a communication with a USB device.
 A transfer is an abstract concept that can result in several
 physical packets being transferred to or from a device.
-.Pp
+A transfer is described by the
+.Va usbd_xfer_handle 
+cookie.
 A pipe is a logical connection to a USB device.
 It is described by the
 .Va usbd_pipe_handle
 cookie.
+.Pp
 Pipes are created and destroyed by using the
 .Fn usbd_open_pipe ,
 .Fn usbd_open_pipe_intr
 and
 .Fn usbd_close_pipe
 functions.
-.\" XXX document args to usbd_open_pipe*()
+The open functions take the interface handle
+.Fa iface ,
+the
+.Fa address
+of this pipe and
+.Fa flags
+for this pipe which currently may be 0 or
+.Dv USBD_EXCLUSIVE_USE ,
+to enable exclusive access to this interface and address.
+The
+.Fn usbd_open_pipe_intr
+takes additional arguments
+.Fa priv
+to set the default private handle.
+.Fa buffer
+and
+.Fa len
+to describe the buffer to be used,
+.Fa callback
+for the function to call at interrupt time, and finally the
+.Fa interval
+for interrupts to be delivered in milliseconds.
+The
+.Fa interval
+may be set to
+.Dv USBD_DEFAULT_INTERVAL
+use the default interval, specified by the ep. description.
 It is common to have more than one pipe per device.
-.Pp
-A transfer is described by the
-.Va usbd_xfer_handle 
-cookie.
+
 .Pp
 Transfers are allocated and deallocated with
 .Fn usbd_alloc_xfer