[src/trunk]: src document a large chunk of the USB interface. some of this i...

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

details:   https://anonhg.NetBSD.org/src/rev/2ef6ec4b08c0
branches:  trunk
changeset: 779244:2ef6ec4b08c0
user:      mrg <mrg%NetBSD.org@localhost>
date:      Sun May 13 09:00:51 2012 +0000

description:
document a large chunk of the USB interface.  some of this is kind of
generic and depends upon understanding USB itself (and since i don't
really that well, i might have gotten some wrong.)

diffstat:

 distrib/sets/lists/comp/mi   |    5 +-
 share/man/man9/Makefile      |    4 +-
 share/man/man9/usbd_status.9 |  110 +++++++++++++++
 share/man/man9/usbdi.9       |  302 ++++++++++++++++++++++++++++++++++++++++--
 4 files changed, 398 insertions(+), 23 deletions(-)

diffs (truncated from 521 to 300 lines):

diff -r 788655c64763 -r 2ef6ec4b08c0 distrib/sets/lists/comp/mi
--- a/distrib/sets/lists/comp/mi        Sun May 13 07:34:02 2012 +0000
+++ b/distrib/sets/lists/comp/mi        Sun May 13 09:00:51 2012 +0000
@@ -1,4 +1,4 @@
-#      $NetBSD: mi,v 1.1757 2012/05/09 22:04:05 christos Exp $
+#      $NetBSD: mi,v 1.1758 2012/05/13 09:00:51 mrg Exp $
 #
 # Note: don't delete entries from here - mark them as "obsolete" instead.
 #
@@ -10783,6 +10783,7 @@
 ./usr/share/man/cat9/ungetnewvnode.0           comp-sys-catman         .cat
 ./usr/share/man/cat9/untimeout.0               comp-sys-catman         .cat
 ./usr/share/man/cat9/uprintf.0                 comp-sys-catman         .cat
+./usr/share/man/cat9/usbd_status.0             comp-sys-catman         .cat
 ./usr/share/man/cat9/usbdi.0                   comp-sys-catman         .cat
 ./usr/share/man/cat9/useracc.0                 comp-obsolete           obsolete
 ./usr/share/man/cat9/userret.0                 comp-sys-catman         .cat
@@ -16943,6 +16944,7 @@
 ./usr/share/man/html9/ungetnewvnode.html       comp-sys-htmlman        html
 ./usr/share/man/html9/untimeout.html           comp-sys-htmlman        html
 ./usr/share/man/html9/uprintf.html             comp-sys-htmlman        html
+./usr/share/man/html9/usbd_status.html         comp-sys-htmlman        html
 ./usr/share/man/html9/usbdi.html               comp-sys-htmlman        html
 ./usr/share/man/html9/userret.html             comp-sys-htmlman        html
 ./usr/share/man/html9/uvm.html                 comp-sys-htmlman        html
@@ -23316,6 +23318,7 @@
 ./usr/share/man/man9/ungetnewvnode.9           comp-sys-man            .man
 ./usr/share/man/man9/untimeout.9               comp-sys-man            .man
 ./usr/share/man/man9/uprintf.9                 comp-sys-man            .man
+./usr/share/man/man9/usbd_status.9             comp-sys-man            .man
 ./usr/share/man/man9/usbdi.9                   comp-sys-man            .man
 ./usr/share/man/man9/useracc.9                 comp-obsolete           obsolete
 ./usr/share/man/man9/userret.9                 comp-sys-man            .man
diff -r 788655c64763 -r 2ef6ec4b08c0 share/man/man9/Makefile
--- a/share/man/man9/Makefile   Sun May 13 07:34:02 2012 +0000
+++ b/share/man/man9/Makefile   Sun May 13 09:00:51 2012 +0000
@@ -1,4 +1,4 @@
-#       $NetBSD: Makefile,v 1.364 2012/03/13 18:40:26 elad Exp $
+#       $NetBSD: Makefile,v 1.365 2012/05/13 09:00:52 mrg Exp $
 
 #      Makefile for section 9 (kernel function and variable) manual pages.
 
@@ -56,7 +56,7 @@
        vattr.9 veriexec.9 vcons.9 vfs.9 vfs_hooks.9 vfsops.9 vfssubr.9 \
        video.9 vme.9 \
        vnfileops.9 vnode.9 vnodeops.9 vnsubr.9 \
-       ubc.9 usbdi.9 uvm.9 uvm_km.9 uvm_map.9 vmem.9 \
+       ubc.9 usbd_status.9 usbdi.9 uvm.9 uvm_km.9 uvm_map.9 vmem.9 \
        wdc.9 workqueue.9 \
        wscons.9 wsdisplay.9 wsfont.9 wskbd.9 wsmouse.9 \
        xcall.9
diff -r 788655c64763 -r 2ef6ec4b08c0 share/man/man9/usbd_status.9
--- /dev/null   Thu Jan 01 00:00:00 1970 +0000
+++ b/share/man/man9/usbd_status.9      Sun May 13 09:00:51 2012 +0000
@@ -0,0 +1,110 @@
+.\"    $NetBSD: usbd_status.9,v 1.1 2012/05/13 09:00:52 mrg Exp $
+.\"
+.\" Copyright (c) 2012 Matthew R. Green
+.\" All rights reserved.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\" 3. The name of the author may not be used to endorse or promote products
+.\"    derived from this software without specific prior written permission.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
+.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
+.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
+.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
+.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
+.\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
+.\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+.\" SUCH DAMAGE.
+.\"
+.Dd May 12, 2012
+.Dt USBD_STATUS 9
+.Os
+.Sh NAME
+.Nm usbd_status
+.Nd USB device drivers interface return status values
+.Sh SYNOPSIS
+.In dev/usb/usbdi.h
+.Sh DESCRIPTION
+This documents the full list of return values used by the generic USB code.
+Interface-specific definitions will be given with interface.
+.Pp
+.Sh RETURN VALUES
+Return values are split into two main groups: expected values
+and error values.
+.Pp
+There are only two expected values:
+.Bl -tag -width indent
+.It Dv USBD_NORMAL_COMPLETION
+The operation completed successfully.
+.It Dv USBD_IN_PROGRESS
+The operation was successfully submitted, usually part of
+an asynchronous operation.
+.El
+.Pp
+These are the error values:
+.Bl -tag -width indent
+.It Dv USBD_PENDING_REQUESTS
+The requested operation could not be completed due to pending
+requests, usually from a pipe close operation.
+.It Dv USBD_NOT_STARTED
+The initial status of a USB transfer.
+See
+.Xr usbdi 9
+for more details about USB transfers.
+.It Dv USBD_INVAL
+Invalid arguments were supplied for the requested operation.
+.It Dv USBD_NOMEM
+No memory could be allocated.
+.It Dv USBD_CANCELLED
+The USB transfer has been cancelled, and not completed.
+.It Dv USBD_BAD_ADDRESS
+The requested USB pipe could not be found.
+See
+.Xr usbdi 9
+for more details about USB pipes.
+.It Dv USBD_IN_USE
+The requested operation could not be performed due to the device
+having active connections, such as USB audio device currently playing.
+.It Dv USBD_NO_ADDR
+USB bus has reached it maximum limit of devices.
+.It Dv USBD_SET_ADDR_FAILED
+Call to
+.Fn usbd_set_address
+failed during new USB device discovery.
+.It Dv USBD_NO_POWER
+New device has requested more power than is available.
+.It Dv USBD_TOO_DEEP
+.\" XXXMRG why do we do this?  it's only 5 right now.
+New USB Hub too deep from the root.
+.It Dv USBD_IOERROR
+Non-specific error happened during IO.
+.It Dv USBD_NOT_CONFIGURED
+USB device is not configured; it has no configuration descriptor.
+.It Dv USBD_TIMEOUT
+Operation timed out.
+.It Dv USBD_SHORT_XFER
+USB transfer succeeded but not all requested data was returned.
+.It Dv USBD_STALLED
+USB controller has stalled (controller specific.)
+.It Dv USBD_INTERRUPTED
+Process was interrupted by external means (such as a signal) while
+waiting for a transfer to complete.
+.El
+.Sh SEE ALSO
+.Xr usb 4 ,
+.Xr usbdi 9
+.Sh HISTORY
+This
+.Nm
+interface first appeared in
+.Nx 1.4 .
diff -r 788655c64763 -r 2ef6ec4b08c0 share/man/man9/usbdi.9
--- a/share/man/man9/usbdi.9    Sun May 13 07:34:02 2012 +0000
+++ b/share/man/man9/usbdi.9    Sun May 13 09:00:51 2012 +0000
@@ -1,4 +1,31 @@
-.\"    $NetBSD: usbdi.9,v 1.8 2011/10/20 12:14:12 njoly Exp $
+.\"    $NetBSD: usbdi.9,v 1.9 2012/05/13 09:00:52 mrg Exp $
+.\"
+.\" Copyright (c) 2012 Matthew R. Green
+.\" All rights reserved.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\" 3. The name of the author may not be used to endorse or promote products
+.\"    derived from this software without specific prior written permission.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
+.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
+.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
+.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
+.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
+.\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
+.\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+.\" SUCH DAMAGE.
+.\"
 .\"
 .\" Copyright (c) 1999 The NetBSD Foundation, Inc.
 .\" All rights reserved.
@@ -27,7 +54,7 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 .\" POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd December 3, 1999
+.Dd May 12, 2012
 .Dt USBDI 9
 .Os
 .Sh NAME
@@ -36,31 +63,69 @@
 .Sh SYNOPSIS
 .In dev/usb/usb.h
 .In dev/usb/usbdi.h
+.In dev/usb/usbdi_util.h
 .Sh DESCRIPTION
 Device driver access to the USB bus centers around transfers.
 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 a
-.Va usbd_xfer_handle .
-It is allocated by
-.Va usbd_alloc_xfer
-and the data describing the transfer is filled by
-.Va usbd_setup_default_xfer
+.Va usbd_xfer_handle ,
+a largely opaque cookie.
+Allocated and deallocate are performed with
+.Fn usbd_alloc_xfer
+and
+.Fn usbd_free_xfer .
+The data describing the transfer is filled by either
+.Fn usbd_setup_default_xfer
 for control pipe transfers, by
-.Va usbd_setup_xfer
+.Fn usbd_setup_xfer
 for bulk and interrupt transfers, and by
-.Va usbd_setup_isoc_xfer
+.Fn usbd_setup_isoc_xfer
 for isochronous transfers.
 .Pp
-describe
-.Va usbd_do_request
+A pipe is a logical connection to a USB device.
+Pipes are created and destroyed by using the
+.Fn usbd_open_pipe ,
+.Fn usbd_open_pipe_intr 
+and
+.Fn usbd_close_pipe
+functions.
+It is common to have more than one pipe per device.
+Pipes are used to allocate 
+.Va usbd_xfer_handle
+is required to 
+Transfers are aborted via their parent pipe with
+.Fn usbd_abort_pipe .
+The
+.Fn usbd_clear_endpoint_stall
+and
+.Fn usbd_clear_endpoint_stall_async
+functions are used to clear endpoint halt in either a synchronous
+or asynchronous fashion.
+The
+.Fn usbd_bulk_transfer
+and
+.Fn usbd_intr_transfer
+functions are used to transfer data in either an interrupt or
+bulk fashion.
 .Pp
-describe pipes
+A request is described by a
+.Va usb_device_request_t
+which must be initialised as necessary before calling either
+.Fn usbd_do_request
+or
+.Fn usbd_do_request_flags
+to submit the request.
+See the
+.Sx INITIALISING USB REQUESTS
+section for more details.
 .Pp
-describe
-usbd_status
-.Ss Functions offered by usbdi
+Error handling and other return values are described in
+.Xr usbd_status 9 .
+.Sh FUNCTIONS
+.Ss Functions offered by usbdi.h
 .Bl -tag -width indent
 .It Dv usbd_status usbd_open_pipe(usbd_interface_handle iface, uint8_t address,
     uint8_t flags,
@@ -102,7 +167,6 @@
      usbd_private_handle priv, void *buffer,
      uint32_t length, usbd_callback)
 .It Dv usbd_status usbd_do_request(usbd_device_handle pipe, usb_device_request_t *req, void *data)
-.It Dv usbd_status usbd_do_request_async(usbd_device_handle pipe, usb_device_request_t *req, void *data)
 .It Dv usbd_status usbd_do_request_flags(usbd_device_handle pipe, usb_device_request_t *req,
      void *data, uint16_t flags, int *)