[src/trunk]: src/share/man/man9 - add some comments for post-usbmp

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

details:   https://anonhg.NetBSD.org/src/rev/aa6605adcadd
branches:  trunk
changeset: 779515:aa6605adcadd
user:      mrg <mrg%NetBSD.org@localhost>
date:      Fri Jun 01 00:16:28 2012 +0000

description:
- add some comments for post-usbmp
- basic documentation for:
    usbd_clear_endpoint_toggle()
    usbd_device2interface_handle()
    usbd_interface2device_handle()
    usbd_pipe2device_handle()
    usbd_interface2endpoint_descriptor()
    usbd_endpoint_count()
- usbd_close_pipe() has documentation already
- bump date

diffstat:

 share/man/man9/usbdi.9 |  64 ++++++++++++++++++++++++++++++++++++++++---------
 1 files changed, 52 insertions(+), 12 deletions(-)

diffs (133 lines):

diff -r fe1c1ee6bef4 -r aa6605adcadd share/man/man9/usbdi.9
--- a/share/man/man9/usbdi.9    Thu May 31 23:11:35 2012 +0000
+++ b/share/man/man9/usbdi.9    Fri Jun 01 00:16:28 2012 +0000
@@ -1,4 +1,4 @@
-.\"    $NetBSD: usbdi.9,v 1.15 2012/05/17 07:28:29 wiz Exp $
+.\"    $NetBSD: usbdi.9,v 1.16 2012/06/01 00:16:28 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 May 16, 2012
+.Dd May 31, 2012
 .Dt USBDI 9
 .Os
 .Sh NAME
@@ -124,6 +124,9 @@
 .Fn usbd_get_buffer "usbd_xfer_handle xfer"
 .Ft usbd_status
 .Fn usbd_sync_transfer "usbd_xfer_handle req"
+.\" only in usbmp
+.\" .Ft usbd_status
+.\" .Fn usbd_sync_transfer_sig "usbd_xfer_handle req"
 .Ft usbd_status
 .Fn usbd_open_pipe_intr "usbd_interface_handle iface" "uint8_t address" \
  "uint8_t flags" "usbd_pipe_handle *pipe" \
@@ -332,12 +335,8 @@
 .Fn usbd_clear_endpoint_stall_async
 functions are used to clear endpoint halt in either a synchronous
 or asynchronous fashion.
-.\" XXX something about
-.\" .Fn usbd_clear_endpoint_toggle .
-To obtain the
-.Ft usbd_device_handle
-associated with a pipe the
-.Fn usbd_pipe2device_handle
+To clear the toggle state of an endpoint the
+.Fn usbd_clear_endpoint_toggle
 function should be used.
 .Pp
 A request is described by a
@@ -351,13 +350,53 @@
 .Sx INITIALISING USB REQUESTS
 section for more details.
 .Pp
+There are a number of functions to obtain a handle, descriptor
+of resource count:
+.Bl -tag -width 10n
+.It Fn usbd_device2interface_handle dev ifaceno iface
+Fills in
+.Fa iface
+with the
+.Ft usbd_interface_handle
+for the USB device
+.Fa dev
+on interface number
+.Fa ifaceno .
+.It Fn usbd_interface2device_handle iface dev
+Fills in
+.Fa dev
+with the
+.Ft usbd_device_handle
+pointer for interface
+.Fa iface .
+.It Fn usbd_pipe2device_handle pipe
+Returns the
+.Ft usbd_device_handle
+associated with
+.Fa pipe .
+.It Fn usbd_interface2endpoint_descriptor iface address
+Returns the
+.Ft usb_endpoint_descriptor_t *
+for the particular interface
+.Fa iface
+at address
+.Fa address .
+.It Fn usbd_endpoint_count dev count
+.It Fn usbd_interface_count dev count
+Fills in
+.Fa count
+with the number of endpoint or interfaces the USB device
+.Fa dev
+has.
+.El
+.Pp
 Error handling and other return values are described in
 .Xr usbd_status 9 .
 .Pp
 Additional comments on particular functions:
 .Bl -tag -width 10n
 .It Fn usbd_errstr err
-Return the string associated with
+Returns the string associated with
 .Fa err .
 .It Fn usbd_add_dev_event type iface
 The
@@ -400,7 +439,6 @@
 .\"
 .\" .Fn usbd_open_pipe "usbd_interface_handle iface" "uint8_t address" \
 .\"  "uint8_t flags" "usbd_pipe_handle *pipe"
-.\" .Fn usbd_close_pipe "usbd_pipe_handle pipe"
 .\" .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" \
@@ -417,6 +455,8 @@
 .\" .Fn usbd_free_buffer "usbd_xfer_handle req"
 .\" .Fn usbd_get_buffer "usbd_xfer_handle xfer"
 .\" .Fn usbd_sync_transfer "usbd_xfer_handle req"
+.\" only in usbmp
+.\" .Fn usbd_sync_transfer_sig "usbd_xfer_handle req"
 .\" .Fn usbd_do_request "usbd_device_handle dev" "usb_device_request_t *req" \
 .\"  "void *data"
 .\" .Fn usbd_do_request_flags "usbd_device_handle dev" \
@@ -640,7 +680,7 @@
 .Vt uWord wStatus ;
 .El
 .Pp
-For device status requests, the
+For device status requests the
 .Fa wStatus
 member may have either of these bit flags set:
 .Bl -tag -width UDS_REMOTE_WAKEUPXX -offset offset -compact
@@ -648,7 +688,7 @@
 .It Dv UDS_REMOTE_WAKEUP
 .El
 .Pp
-For endpoint status requests, the
+For endpoint status requests the
 .Fa wStatus
 member may have this bit flag set:
 .Bl -tag -width UES_HALTXX -offset offset -compact