[src/trunk]: src/share/man/man9 clarify some descriptions. document a couple...

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

details:   https://anonhg.NetBSD.org/src/rev/90e4caba4407
branches:  trunk
changeset: 779302:90e4caba4407
user:      mrg <mrg%NetBSD.org@localhost>
date:      Thu May 17 02:58:14 2012 +0000

description:
clarify some descriptions.  document a couple more functions.
make a big commented list of the functions that are lacking real
descriptions.

diffstat:

 share/man/man9/usbdi.9 |  212 +++++++++++++++++++++++++++++++++++++++++++-----
 1 files changed, 189 insertions(+), 23 deletions(-)

diffs (295 lines):

diff -r 9d474e0583f7 -r 90e4caba4407 share/man/man9/usbdi.9
--- a/share/man/man9/usbdi.9    Wed May 16 19:12:59 2012 +0000
+++ b/share/man/man9/usbdi.9    Thu May 17 02:58:14 2012 +0000
@@ -1,4 +1,4 @@
-.\"    $NetBSD: usbdi.9,v 1.13 2012/05/13 19:29:59 mrg Exp $
+.\"    $NetBSD: usbdi.9,v 1.14 2012/05/17 02:58:14 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 13, 2012
+.Dd May 16, 2012
 .Dt USBDI 9
 .Os
 .Sh NAME
@@ -71,7 +71,7 @@
 .Ft usbd_status
 .Fn usbd_close_pipe "usbd_pipe_handle pipe"
 .Ft usbd_status
-.Fn usbd_transfer "usbd_xfer_handle req"
+.Fn usbd_transfer "usbd_xfer_handle xfer"
 .Ft usbd_xfer_handle
 .Fn usbd_alloc_xfer "usbd_device_handle dev"
 .Ft usbd_status
@@ -161,7 +161,7 @@
 .Ft void
 .Fn usbd_dopoll "usbd_interface_handle iface"
 .Ft void
-.Fn usbd_set_polling" usbd_device_handle iface" "int val"
+.Fn usbd_set_polling "usbd_device_handle iface" "int val"
 .Ft const char *
 .Fn usbd_errstr "usbd_status err"
 .Ft void
@@ -217,7 +217,7 @@
 .Fn usbd_get_config_desc_full "usbd_device_handle" "int dev" "void *d" "int size"
 .Ft usbd_status
 .Fn usbd_get_device_desc "usbd_device_handle dev" \
-"usb_device_descriptor_t *d"
+ "usb_device_descriptor_t *d"
 .Ft usbd_status
 .Fn usbd_set_address "usbd_device_handle dev" "int addr"
 .Ft usbd_status
@@ -267,7 +267,7 @@
  "uint16_t flags" "uint32_t timeout" "void *buf" "uint32_t *size" "char *lbl"
 .Ft usbd_status
 .Fn usbd_intr_transfer "usbd_xfer_handle xfer" "usbd_pipe_handle pipe" \
-"uint16_t flags" "uint32_t timeout" "void *buf" "uint32_t *size" "char *lbl"
+ "uint16_t flags" "uint32_t timeout" "void *buf" "uint32_t *size" "char *lbl"
 .\" these are very different in usbmp
 .Ft void
 .Fn usb_detach_waitold "device_t dv"
@@ -283,6 +283,15 @@
 A transfer is an abstract concept that can result in several
 physical packets being transferred to or from a device.
 .Pp
+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.
+.Pp
 A transfer is described by a
 .Va usbd_xfer_handle ,
 a largely opaque cookie.
@@ -297,30 +306,39 @@
 for bulk and interrupt transfers, and by
 .Fn usbd_setup_isoc_xfer
 for isochronous transfers.
-.Pp
-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
+.\" XXX describe args to usbd_setup*xfer
+Transfers are initiated by calling
+.Fn usbd_transfer .
+The
+.Fn usbd_bulk_transfer
 and
-.Fn usbd_close_pipe
-functions.
-It is common to have more than one pipe per device.
+.Fn usbd_intr_transfer
+functions are used to transfer data in either an interrupt or
+bulk fashion, and are front-ends to the
+.Fn usbd_setup_xfer ,
+.Fn usbd_transfer
+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.
 Transfers are aborted via this pipe with
-.Fn usbd_abort_pipe .
+.Fn usbd_abort_pipe 
+and
+.Fn usbd_abort_default_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.
+.\" XXX something about
+.\" .Fn usbd_clear_endpoint_toggle .
+To obtain the
+.Ft usbd_device_handle
+associated with a pipe the
+.Fn usbd_pipe2device_handle
+function should be used.
 .Pp
 A request is described by a
 .Va usb_device_request_t
@@ -336,7 +354,7 @@
 Error handling and other return values are described in
 .Xr usbd_status 9 .
 .Pp
-Comments on particular functions:
+Additional comments on particular functions:
 .Bl -tag -width 10n
 .It Fn usbd_errstr err
 Return the string associated with
@@ -357,11 +375,159 @@
 .Dv USB_EVENT_DRIVER_ATTACH
 and
 .Dv USB_EVENT_DRIVER_DETACH .
+The
+.Fa dv
+corresponds with the
+.Ft device_t
+associated with the device attached or detached.
 .It Fn usb_lookup tbl vendor product
+Lookup a USB device.
+The returned
+.Va struct usb_devno
+pointer has these members:
+.Bl -item -offset offset -compact
+.It
+.Vt u_int16_t ud_vendor ;
+.It
+.Vt u_int16_t ud_product ;
+.El
 The
 .Dv USB_PRODUCT_ANY
-macro can be used to match any USB product.
+macro can be used to match any USB product by a particular vendor.
 .El
+.\"
+.\" 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_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" \
+.\"  "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"
+.\" .Fn usbd_do_request "usbd_device_handle dev" "usb_device_request_t *req" \
+.\"  "void *data"
+.\" .Fn usbd_do_request_flags "usbd_device_handle dev" \
+.\"  "usb_device_request_t *req" "void *data" "uint16_t flags" "int *actlen" \
+.\"  "u_int32_t timo"
+.\" .Fn usbd_get_interface_descriptor "usbd_interface_handle iface"
+.\" .Fn usbd_get_config_descriptor "usbd_device_handle dev"
+.\" .Fn usbd_get_device_descriptor "usbd_device_handle dev"
+.\" .Fn usbd_set_interface "usbd_interface_handle iface" "int altidx"
+.\" .Fn usbd_get_no_alts "usb_config_descriptor_t *iface" "int ifaceno"
+.\" .Fn usbd_get_interface "usbd_interface_handle iface" "uint8_t *aiface"
+.\" .Fn usbd_fill_deviceinfo "usbd_device_handle dev" "struct usb_device_info *di"
+.\" .Fn usbd_get_interface_altindex "usbd_interface_handle iface"
+.\" .Fn usbd_find_idesc "usb_config_descriptor_t *cd" "int iindex" "int ano"
+.\" .Fn usbd_find_edesc "usb_config_descriptor_t *cd" "int ifaceidx" "int altidx" \
+.\"  "int endptidx"
+.\" .Fn usbd_dopoll "usbd_interface_handle iface"
+.\" .Fn usbd_set_polling" usbd_device_handle iface" "int val"
+.\" 
+.\" .Fn usbd_add_dev_event "int type" "usbd_device_handle iface"
+.\" .Fn usbd_add_drv_event "int type" "usbd_device_handle iface" "device_t dv"
+.\" 
+.\" .Fn usbd_devinfo_alloc "usbd_device_handle iface" "int showclass"
+.\" .Fn usbd_devinfo_free "char *str"
+.\" 
+.\" .Fn usbd_get_quirks "usbd_device_handle iface"
+.\" .Fn usbd_get_endpoint_descriptor "usbd_interface_handle dev" \
+.\"  "u_int8_t address"
+.\" .Fn usbd_reload_device_desc "usbd_device_handle iface"
+.\" .Fn usbd_ratecheck "struct timeval *tv"
+.\" .Fn usbd_get_string "usbd_device_handle iface" "int si" "char *buf"
+.\" .Fn usbd_get_string0 "usbd_device_handle iface" "int" si "char *buf" \
+.\"  "int unicode"
+.\"
+.\" .Fn usb_desc_iter_init "usbd_device_handle iface" "usbd_desc_iter_t *iter"
+.\" .Fn usb_desc_iter_next "usbd_desc_iter_t *iter"
+.\" .Fn usb_add_task "usbd_device_handle iface" "struct usb_task *task" \
+.\"  "int queue"
+.\" .Fn usb_rem_task "usbd_device_handle iface" "struct usb_task *task"
+.\" .Fn usb_init_task "struct usb_task *task" "void (*func)(void *)" \
+.\"  "void *arg"
+.\"
+.\" XXX functions missing descriptions in usbdi.h XXX
+.\"
+.\" .Dv usbdi_util.h .
+.\" .Ft usbd_status
+.\" .Fn usbd_get_desc "usbd_device_handle dev" "int type" "int index" \
+.\"  "int len" "void *desc"
+.\" .Ft usbd_status
+.\" .Fn usbd_get_config_desc "usbd_device_handle dev" "int confidx" \
+.\"  "usb_config_descriptor_t *d"
+.\" .Ft usbd_status
+.\" .Fn usbd_get_config_desc_full "usbd_device_handle" "int dev" "void *d" "int size"
+.\" .Ft usbd_status
+.\" .Fn usbd_get_device_desc "usbd_device_handle dev" \
+.\"  "usb_device_descriptor_t *d"
+.\" .Ft usbd_status
+.\" .Fn usbd_set_address "usbd_device_handle dev" "int addr"
+.\" .Ft usbd_status
+.\" .Fn usbd_get_port_status "usbd_device_handle dev" "intp ort" "usb_port_status_t *ps"
+.\" .Ft usbd_status
+.\" .Fn usbd_set_hub_feature "usbd_device_handle dev" "int sel"
+.\" .Ft usbd_status
+.\" .Fn usbd_clear_hub_feature "usbd_device_handle dev" "int sel"
+.\" .Ft usbd_status
+.\" .Fn usbd_set_port_feature "usbd_device_handle dev" "int port" "int sel"
+.\" .Ft usbd_status
+.\" .Fn usbd_clear_port_feature "usbd_device_handle dev" "int port" "int sel"
+.\" .Ft usbd_status
+.\" .Fn usbd_get_device_status "usbd_device_handle dev" "usb_status_t *st"
+.\" .Ft usbd_status
+.\" .Fn usbd_get_hub_status "usbd_device_handle dev" "usb_hub_status_t *st"
+.\" .Ft usbd_status
+.\" .Fn usbd_set_protocol "usbd_interface_handle dev" "int report"
+.\" .Ft usbd_status
+.\" .Fn usbd_get_report_descriptor  "usbd_device_handle dev" "int ifcno" "int repid" "int size" "void *d"
+.\" .Ft struct usb_hid_descriptor *
+.\" .Fn usbd_get_hid_descriptor "usbd_interface_handle ifc"
+.\" .Ft usbd_status
+.\" .Fn usbd_set_report "usbd_interface_handle iface" "nt type" "int id" "void *data" "int len"
+.\" .Ft usbd_status
+.\" .Fn usbd_set_report_async "usbd_interface_handle iface" "int type" "int id" "void *data" "int len"
+.\" .Ft usbd_status
+.\" .Fn usbd_get_report "usbd_interface_handle iface" "int type" "int id" "void *data" "int len"
+.\" .Ft usbd_status
+.\" .Fn usbd_set_idle "usbd_interface_handle iface" "int duration" "int id"
+.\" .Ft usbd_status
+.\" .Fn usbd_alloc_report_desc "usbd_interface_handle ifc" "void **descp" \
+.\"  "int *sizep" "int mem"
+.\" .Ft usbd_status
+.\" .Fn usbd_get_config "usbd_device_handle dev" "uint8_t *conf"
+.\" .Ft usbd_status
+.\" .Fn usbd_get_string_desc "usbd_device_handle dev" "int sindex" "int langid" \
+.\"  "usb_string_descriptor_t *sdesc"
+.\" .Ft void
+.\" .Fn usbd_delay_ms "usbd_device_handle dev" "u_int ms"
+.\" .Ft usbd_status
+.\" .Fn usbd_set_config_no "usbd_device_handle dev" "int no" "int msg"
+.\" .Ft usbd_status
+.\" .Fn usbd_set_config_index "usbd_device_handle dev" "int index" "int msg"
+.\" .Ft usbd_status
+.\" .\" these are very different in usbmp
+.\" .Ft void
+.\" .Fn usb_detach_waitold "device_t dv"
+.\" .Ft void
+.\" .Fn usb_detach_wakeupold "device_t dv"
+.\" .Ft void
+.\" .Fn usb_detach_wait "device_t dv" "kcondvar_t *cv" "kmutex_t *lk"
+.\" .Ft void
+.\" .Fn usb_detach_broadcast "device_t dv" "kcondvar_t *cv"
+.\"
 .Sh INITIALISING USB REQUESTS
 There are 5 members of a
 .Va usb_device_request_t