[src/trunk]: src/share/man/man9 greatly expand the discussion on transfers an...

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

details:   https://anonhg.NetBSD.org/src/rev/175bc750a2f8
branches:  trunk
changeset: 779557:175bc750a2f8
user:      mrg <mrg%NetBSD.org@localhost>
date:      Sat Jun 02 23:10:12 2012 +0000

description:
greatly expand the discussion on transfers and provide most of the details
needed to alloc, setup, transfer and obtain the status of them.
this takes care of:
  - usbd_close_pipe
  - usbd_alloc_xfer
  - usbd_free_xfer
  - usbd_setup{,_default,_isoc}_xfer
  - usbd_transfer
  - usbd_{bulk,intr}_transfer
  - usbd_transfer_sync{,_sig}
  - usbd_get_xfer_status
as well as callback and request information.

update the list of functions missing real descriptions.  there are about
30 usbdi.h and 35 usbdi_util.h functions remaining.

diffstat:

 share/man/man9/usbdi.9 |  129 +++++++++++++++++++++++++++++++++++++++---------
 1 files changed, 103 insertions(+), 26 deletions(-)

diffs (203 lines):

diff -r d95fc41dcde8 -r 175bc750a2f8 share/man/man9/usbdi.9
--- a/share/man/man9/usbdi.9    Sat Jun 02 22:54:52 2012 +0000
+++ b/share/man/man9/usbdi.9    Sat Jun 02 23:10:12 2012 +0000
@@ -1,4 +1,4 @@
-.\"    $NetBSD: usbdi.9,v 1.16 2012/06/01 00:16:28 mrg Exp $
+.\"    $NetBSD: usbdi.9,v 1.17 2012/06/02 23:10:12 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 31, 2012
+.Dd June 2, 2012
 .Dt USBDI 9
 .Os
 .Sh NAME
@@ -287,21 +287,28 @@
 physical packets being transferred to or from a device.
 .Pp
 A pipe is a logical connection to a USB device.
+It is described by the
+.Va usbd_pipe_handle
+cookie.
 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*()
 It is common to have more than one pipe per device.
 .Pp
-A transfer is described by a
-.Va usbd_xfer_handle ,
-a largely opaque cookie.
-Allocated and deallocate are performed with
+A transfer is described by the
+.Va usbd_xfer_handle 
+cookie.
+.Pp
+Transfers are allocated and deallocated with
 .Fn usbd_alloc_xfer
 and
-.Fn usbd_free_xfer .
+.Fn usbd_free_xfer ,
+respectively, and are associated with a pipe at their creation time.
+.Pp
 The data describing the transfer is filled by either
 .Fn usbd_setup_default_xfer
 for control pipe transfers, by
@@ -309,9 +316,73 @@
 for bulk and interrupt transfers, and by
 .Fn usbd_setup_isoc_xfer
 for isochronous transfers.
-.\" XXX describe args to usbd_setup*xfer
+Private data may be passed between setup and completion or status
+calls using the
+.Ft usbd_private_handle priv
+argument, which must be an integral type.
+.Pp
+Arguments to the setup functions include the newly allocated
+.Fa xfer ,
+the
+.Fa pipe
+to associate this transfer with,
+the private data
+.Fa priv ,
+the
+.Fa timeout
+in milliseconds,
+for control, bulk and interrupt transfers
+.Fa buffer
+the data to transfer and its
+.Fa length
+and for isochronous transfers the the frame length
+.Fa frlengths
+and number of frames
+.Fa nframes ,
+and for default transfers a usb request structure
+.Fa req
+must be presented (see below.)
+.Pp
+The transfer specific
+.Fa flags
+that can be set are:
+.Bl -tag -width 10n
+.It Dv USBD_NO_COPY
+Do not copy data to DMA buffer
+.It Dv USBD_SYNCHRONOUS
+Wait for completion
+.It Dv USBD_SYNCHRONOUS_SIG
+When waiting for completion, allow signals to trigger wake up.
+.It Dv USBD_SHORT_XFER_OK
+Short reads are not an error
+.It Dv USBD_FORCE_SHORT_XFER
+Force last short packet on write
+.El
+.Pp
+Upon completion the
+.Fa callback
+function is called, which takes the completed
+.Fa xfer ,
+the private data
+.Fa priv
+originally assocated with this transfer, and
+.Fa status
+the status of this transfer.
+.Pp
 Transfers are initiated by calling
-.Fn usbd_transfer .
+.Fn usbd_transfer ,
+and their results made be later obtained by calling
+.Fa usbd_get_xfer_status ,
+which fills in the private data
+.Fa priv ,
+original buffer location
+.Fa buffer ,
+the length
+.Fa length ,
+and the
+.Fa status
+of this request.
+.Pp
 The
 .Fn usbd_bulk_transfer
 and
@@ -323,12 +394,31 @@
 and
 .Fn usbd_get_xfer_status ,
 as well as associated error handling.
-.\" XXX describe args to usbd_get_xfer_status
-Transfers are associated with a pipe at their creation time.
+The
+.Fa lbl
+option is deprecated and will be removed.
+The
+.Fn usbd_sync_transfer
+is identical to
+.Fn usbd_transfer
+with the
+.Dv USBD_SYNCHRONOUS
+flag set.
+The
+.Fn usbd_sync_transfer_sig
+is identical to
+.Fn usbd_transfer
+with the
+.Dv USBD_SYNCHRONOUS
+and
+.Dv USBD_SYNCHRONOUS_SIG
+flags set.
+.Pp
 Transfers are aborted via this pipe with
 .Fn usbd_abort_pipe
 and
 .Fn usbd_abort_default_pipe .
+.Pp
 The
 .Fn usbd_clear_endpoint_stall
 and
@@ -369,6 +459,7 @@
 .Ft usbd_device_handle
 pointer for interface
 .Fa iface .
+.\" usbd_pipe2device_handle is unused; remove from usbdi?
 .It Fn usbd_pipe2device_handle pipe
 Returns the
 .Ft usbd_device_handle
@@ -381,6 +472,7 @@
 .Fa iface
 at address
 .Fa address .
+.\" XXX describe what a .Ft usb_endpoint_descriptor_t is.
 .It Fn usbd_endpoint_count dev count
 .It Fn usbd_interface_count dev count
 Fills in
@@ -437,24 +529,9 @@
 .\"
 .\" XXX functions missing descriptions in usbdi.h XXX
 .\"
-.\" .Fn usbd_open_pipe "usbd_interface_handle iface" "uint8_t address" \
-.\"  "uint8_t flags" "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" \
-.\"  "uint32_t length" "usbd_callback"
-.\"
-.\" .Fn usbd_interface2endpoint_descriptor "usbd_interface_handle iface" \
-.\"  "uint8_t address"
-.\" .Fn usbd_endpoint_count "usbd_interface_handle dev" "uint8_t *count"
-.\" .Fn usbd_interface_count "usbd_device_handle dev" "uint8_t *count"
-.\" .Fn usbd_interface2device_handle "usbd_interface_handle iface" "usbd_device_handle *dev"
-.\" .Fn usbd_device2interface_handle "usbd_device_handle dev" "uint8_t ifaceno" "usbd_interface_handle *iface"
-.\"
 .\" .Fn usbd_alloc_buffer "usbd_xfer_handle req" "uint32_t size"
 .\" .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" \