Module Name: src
Committed By: mrg
Date: Sun May 13 09:00:52 UTC 2012
Modified Files:
src/distrib/sets/lists/comp: mi
src/share/man/man9: Makefile usbdi.9
Added Files:
src/share/man/man9: usbd_status.9
Log Message:
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.)
To generate a diff of this commit:
cvs rdiff -u -r1.1757 -r1.1758 src/distrib/sets/lists/comp/mi
cvs rdiff -u -r1.364 -r1.365 src/share/man/man9/Makefile
cvs rdiff -u -r0 -r1.1 src/share/man/man9/usbd_status.9
cvs rdiff -u -r1.8 -r1.9 src/share/man/man9/usbdi.9
Please note that diffs are not public domain; they are subject to the
copyright notices on the relevant files.
Modified files:
Index: src/distrib/sets/lists/comp/mi
diff -u src/distrib/sets/lists/comp/mi:1.1757 src/distrib/sets/lists/comp/mi:1.1758
--- src/distrib/sets/lists/comp/mi:1.1757 Wed May 9 22:04:05 2012
+++ src/distrib/sets/lists/comp/mi Sun May 13 09:00:51 2012
@@ -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
Index: src/share/man/man9/Makefile
diff -u src/share/man/man9/Makefile:1.364 src/share/man/man9/Makefile:1.365
--- src/share/man/man9/Makefile:1.364 Tue Mar 13 18:40:26 2012
+++ src/share/man/man9/Makefile Sun May 13 09:00:52 2012
@@ -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 @@ MAN= accept_filter.9 accf_data.9 accf_ht
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
Index: src/share/man/man9/usbdi.9
diff -u src/share/man/man9/usbdi.9:1.8 src/share/man/man9/usbdi.9:1.9
--- src/share/man/man9/usbdi.9:1.8 Thu Oct 20 12:14:12 2011
+++ src/share/man/man9/usbdi.9 Sun May 13 09:00:52 2012
@@ -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_status
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 *)
.It Dv usb_interface_descriptor_t *usbd_get_interface_descriptor(usbd_interface_handle iface)
@@ -171,11 +235,207 @@ through
.It Dv usbd_status usbd_bulk_transfer
(usbd_xfer_handle xfer, usbd_pipe_handle pipe, uint16_t flags,
uint32_t timeout, void *buf, uint32_t *size, char *lbl)
-.It Dv void usb_detach_wait(device_ptr_t)
-.It Dv void usb_detach_wakeup(device_ptr_t)
+.It Dv usbd_status usbd_intr_transfer
+(usbd_xfer_handle xfer, usbd_pipe_handle pipe, uint16_t flags,
+ uint32_t timeout, void *buf, uint32_t *size, char *lbl)
+.\" these are very different in usbmp
+.It Dv void usb_detach_waitold(device_t)
+.It Dv void usb_detach_wakeupold(device_t)
+.\" .It Dv void usb_detach_wait(device_t dv, kcondvar_t *cv, kmutex_t *lk)
+.\" .It Dv void usb_detach_broadcast(device_t dv, kcondvar_t *cv)
+.El
+.Sh INITIALISING USB REQUESTS
+There are 5 members of a
+.Va usb_device_request_t
+that must be initialised:
+.Pp
+.Bl -item -offset offset -compact
+.It
+.Vt uByte bmRequestType ;
+.It
+.Vt uByte bRequest ;
+.It
+.Vt uWord wValue ;
+.It
+.Vt uWord wIndex ;
+.It
+.Vt uWord wLength ;
+.El
+.Pp
+The first two are normal byte values that may be simply assigned,
+but the last three must be initialised with the
+.Dv USETW()
+macro.
+.Pp
+The
+.Fa bmRequestType
+holds the request type of this USB request, which describes the
+indended recipient of the request.
+.Pp
+This may be one of:
+.Bl -tag -offset offset -compact
+.It Dv UT_WRITE
+.It Dv UT_READ
+.El
+.Pp
+with one of:
+.Bl -tag -offset offset -compact
+.It Dv UT_STANDARD
+.It Dv UT_CLASS
+.It Dv UT_VENDOR
+.El
+.Pp
+and with one of:
+.Bl -tag -offset offset -compact
+.It Dv UT_DEVICE
+.It Dv UT_INTERFACE
+.It Dv UT_ENDPOINT
+.It Dv UT_OTHER
+.El
+.Pp
+These are also in combinations as:
+.Bl -tag -offset offset -compact
+.It Dv UT_READ_DEVICE
+.It Dv UT_READ_INTERFACE
+.It Dv UT_READ_ENDPOINT
+.It Dv UT_WRITE_DEVICE
+.It Dv UT_WRITE_INTERFACE
+.It Dv UT_WRITE_ENDPOINT
+.It Dv UT_READ_CLASS_DEVICE
+.It Dv UT_READ_CLASS_INTERFACE
+.It Dv UT_READ_CLASS_OTHER
+.It Dv UT_READ_CLASS_ENDPOINT
+.It Dv UT_WRITE_CLASS_DEVICE
+.It Dv UT_WRITE_CLASS_INTERFACE
+.It Dv UT_WRITE_CLASS_OTHER
+.It Dv UT_WRITE_CLASS_ENDPOINT
+.It Dv UT_READ_VENDOR_DEVICE
+.It Dv UT_READ_VENDOR_INTERFACE
+.It Dv UT_READ_VENDOR_OTHER
+.It Dv UT_READ_VENDOR_ENDPOINT
+.It Dv UT_WRITE_VENDOR_DEVICE
+.It Dv UT_WRITE_VENDOR_INTERFACE
+.It Dv UT_WRITE_VENDOR_OTHER
+.It Dv UT_WRITE_VENDOR_ENDPOINT
+.El
+.Pp
+The
+.Fa bRequest
+describes which request is being made. The available values are:
+.Bl -tag -offset offset -compact
+.It Dv UR_GET_STATUS
+.It Dv UR_CLEAR_FEATURE
+.It Dv UR_SET_FEATURE
+.It Dv UR_SET_ADDRESS
+.It Dv UR_GET_DESCRIPTOR
+.It Dv UR_SET_DESCRIPTOR
+.It Dv UR_GET_CONFIG
+.It Dv UR_SET_CONFIG
+.It Dv UR_GET_INTERFACE
+.It Dv UR_SET_INTERFACE
+.It Dv UR_SYNCH_FRAME
+.El
+.Pp
+The
+.Fa wValue ,
+.Fa wIndex
+and
+.Fa wLength
+are device-specific values and must be initialised with the
+.Dv USETW()
+macro.
+.Pp
+.Sh USB REQUEST TYPES AND STRUCTURES
+The
+.Dv UR_GET_STATUS
+request operates on a
+.Va usb_status_t
+structure, which has this member:
+.Bl -item -offset offset -compact
+.It
+.Vt uWord wStatus ;
+.El
+.Pp
+For device status requests, the
+.Fa wStatus
+member may have either of these bit flags set:
+.Bl -tag -offset offset -compact
+.It Dv UDS_SELF_POWERED
+.It Dv UDS_REMOTE_WAKEUP
.El
+.Pp
+For endpoint status requests, the
+.Fa wStatus
+member may have this bit flag set:
+.Bl -tag -offset offset -compact
+.It Dv UES_HALT
+.El
+.Pp
+The
+.Dv UR_CLEAR_FEATURE
+and
+.Dv UR_SET_FEATURE
+requests clear or set special features on USB devices.
+The values for
+.Va wValue ,
+.Va wIndex
+and
+.Va wLength
+depend upon the device and device type.
+.Pp
+The
+.Dv UR_SET_ADDRESS
+request sets the virtual USB address of a port using the
+.Va wValue .
+.Pp
+The
+.Dv UR_GET_DESCRIPTOR
+and
+.Dv UR_SET_DESCRIPTOR
+requests operate on a
+.Va usb_descriptor_t
+structure, which has these members:
+.Bl -item -offset offset -compact
+.It
+.Vt uByte bLength ;
+.It
+.Vt uByte bDescriptorType ;
+.El
+.Pp
+The
+.Fa bDescriptorType
+member may be one of the following values:
+.Bl -tag -offset offset -compact
+.It Dv UDESC_DEVICE
+.It Dv UDESC_CONFIG
+.It Dv UDESC_STRING
+.It Dv UDESC_INTERFACE
+.It Dv UDESC_ENDPOINT
+.It Dv UDESC_DEVICE_QUALIFIER
+.It Dv UDESC_OTHER_SPEED_CONFIGURATION
+.It Dv UDESC_INTERFACE_POWER
+.It Dv UDESC_OTG
+.It Dv UDESC_DEBUG
+.It Dv UDESC_INTERFACE_ASSOC
+.It Dv UDESC_CS_DEVICE
+.It Dv UDESC_CS_CONFIG
+.It Dv UDESC_CS_STRING
+.It Dv UDESC_CS_INTERFACE
+.It Dv UDESC_CS_ENDPOINT
+.It Dv UDESC_HUB
+.El
+.Pp
+.\" these have API front ends
+.\" .It Dv UR_GET_CONFIG
+.\" .It Dv UR_SET_CONFIG
+.\" .It Dv UR_GET_INTERFACE
+.\" .It Dv UR_SET_INTERFACE
+.\" this isn't supported
+.\" .It Dv UR_SYNCH_FRAME
+.\"
.Sh SEE ALSO
-.Xr usb 4
+.Xr usb 4 ,
+.Xr usbd_status 9
.Sh HISTORY
This
.Nm
@@ -187,5 +447,7 @@ Right after this definition the OpenUSBD
source developers, so this interface has not followed the further changes.
The OpenUSBDI specification is now available again, but looks different.
.Sh BUGS
-This man page is under development, so its biggest shortcoming is
+This manual is under development, so its biggest shortcoming is
incompleteness.
+.Pp
+This manual is also out of date.
Added files:
Index: src/share/man/man9/usbd_status.9
diff -u /dev/null src/share/man/man9/usbd_status.9:1.1
--- /dev/null Sun May 13 09:00:53 2012
+++ src/share/man/man9/usbd_status.9 Sun May 13 09:00:52 2012
@@ -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 .
