Module Name: src Committed By: wiz Date: Sun May 13 11:57:39 UTC 2012
Modified Files: src/share/man/man9: usbdi.9 Log Message: Move DESCRIPTION below SYNOPSIS. Remove function descriptions from SYNOPSIS. Some cleanup while here. XXX: most functions lack descriptions. To generate a diff of this commit: cvs rdiff -u -r1.10 -r1.11 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/share/man/man9/usbdi.9 diff -u src/share/man/man9/usbdi.9:1.10 src/share/man/man9/usbdi.9:1.11 --- src/share/man/man9/usbdi.9:1.10 Sun May 13 10:57:09 2012 +++ src/share/man/man9/usbdi.9 Sun May 13 11:57:39 2012 @@ -1,4 +1,4 @@ -.\" $NetBSD: usbdi.9,v 1.10 2012/05/13 10:57:09 mrg Exp $ +.\" $NetBSD: usbdi.9,v 1.11 2012/05/13 11:57:39 wiz Exp $ .\" .\" Copyright (c) 2012 Matthew R. Green .\" All rights reserved. @@ -64,69 +64,7 @@ .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 , -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 -.Fn usbd_setup_xfer -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 -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 -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 -Error handling and other return values are described in -.Xr usbd_status 9 . -.Sh SYNOPSIS .Ss Functions offered by usbdi.h -.Pp .Ft usbd_status .Fn usbd_open_pipe "usbd_interface_handle iface" "uint8_t address" \ "uint8_t flags" "usbd_pipe_handle *pipe" @@ -225,26 +163,10 @@ Error handling and other return values a .Fn usbd_set_polling" usbd_device_handle iface" "int val" .Ft const char * .Fn usbd_errstr "usbd_status err" -Return the string associated with -.Fa err . .Ft void .Fn usbd_add_dev_event "int type" "usbd_device_handle iface" -The -.Ar type -must be one of -.Dv USB_EVENT_CTRLR_ATTACH , -.Dv USB_EVENT_CTRLR_DETACH , -.Dv USB_EVENT_DEVICE_ATTACH -and -.Dv USB_EVENT_DEVICE_DETACH . .Ft void .Fn usbd_add_drv_event "int type" "usbd_device_handle iface" "device_t dv" -The -.Fa type -must be one of -.Dv USB_EVENT_DRIVER_ATTACH -and -.Dv USB_EVENT_DRIVER_DETACH . .Ft char * .Fn usbd_devinfo_alloc "usbd_device_handle iface" "int showclass" .Ft void @@ -278,17 +200,12 @@ and .Ft const struct usb_devno * .Fn usb_lookup "const struct usb_devno *tbl" \ "u_int16_t vendor" "u_int16_t product" -The -.Dv USB_PRODUCT_ANY -macro can be used to match any USB product. -.Pp .Ss Utilities from usbdi_util.h Based on the routines in -.Dv "usbdi.h" +.Dv usbdi.h a number of utility functions have been defined that are accessible through -.Dv "usbdi_util.h" -.Bl -tag -width indent +.Dv usbdi_util.h . .Ft usbd_status .Fn usbd_get_desc "usbd_device_handle dev" "int type" "int index" \ "int len" "void *desc" @@ -336,8 +253,8 @@ through .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" +.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 @@ -359,9 +276,95 @@ through .\" .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 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 , +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 +.Fn usbd_setup_xfer +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 +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 +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 +Error handling and other return values are described in +.Xr usbd_status 9 . +.Pp +Comments on particular functions: +.Bl -tag -width 10n +.It Fn usbd_errstr err +Return the string associated with +.Fa err . +.It Fn usbd_add_dev_event type iface +The +.Ar type +must be one of +.Dv USB_EVENT_CTRLR_ATTACH , +.Dv USB_EVENT_CTRLR_DETACH , +.Dv USB_EVENT_DEVICE_ATTACH +and +.Dv USB_EVENT_DEVICE_DETACH . +.It Fn usbd_add_drv_event type iface dv +The +.Fa type +must be one of +.Dv USB_EVENT_DRIVER_ATTACH +and +.Dv USB_EVENT_DRIVER_DETACH . +.It Fn usb_lookup tbl vendor product +The +.Dv USB_PRODUCT_ANY +macro can be used to match any USB product. .El .Sh INITIALISING USB REQUESTS -There are 5 members of a +There are 5 members of a .Va usb_device_request_t that must be initialised: .Pp @@ -380,7 +383,7 @@ that must be initialised: .Pp The first two are normal byte values that may be simply assigned, but the last three must be initialised with the -.Dv USETW() +.Fn USETW macro. .Pp The @@ -389,20 +392,20 @@ holds the request type of this USB reque indended recipient of the request. .Pp This may be one of: -.Bl -tag -offset offset -compact +.Bl -tag -width UT_WRITEXX -offset offset -compact .It Dv UT_WRITE .It Dv UT_READ .El .Pp with one of: -.Bl -tag -offset offset -compact +.Bl -tag -width UT_STANDARDXX -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 +.Bl -tag -width UT_INTERFACEXX -offset offset -compact .It Dv UT_DEVICE .It Dv UT_INTERFACE .It Dv UT_ENDPOINT @@ -410,7 +413,7 @@ and with one of: .El .Pp These are also in combinations as: -.Bl -tag -offset offset -compact +.Bl -tag -width UT_WRITE_VENDOR_INTERFACEXX -offset offset -compact .It Dv UT_READ_DEVICE .It Dv UT_READ_INTERFACE .It Dv UT_READ_ENDPOINT @@ -437,8 +440,9 @@ These are also in combinations as: .Pp The .Fa bRequest -describes which request is being made. The available values are: -.Bl -tag -offset offset -compact +describes which request is being made. +The available values are: +.Bl -tag -width UR_GET_DESCRIPTORXX -offset offset -compact .It Dv UR_GET_STATUS .It Dv UR_CLEAR_FEATURE .It Dv UR_SET_FEATURE @@ -458,9 +462,8 @@ The and .Fa wLength are device-specific values and must be initialised with the -.Dv USETW() +.Fn USETW macro. -.Pp .Sh USB REQUEST TYPES AND STRUCTURES The .Dv UR_GET_STATUS @@ -475,7 +478,7 @@ structure, which has this member: For device status requests, the .Fa wStatus member may have either of these bit flags set: -.Bl -tag -offset offset -compact +.Bl -tag -width UDS_REMOTE_WAKEUPXX -offset offset -compact .It Dv UDS_SELF_POWERED .It Dv UDS_REMOTE_WAKEUP .El @@ -483,7 +486,7 @@ member may have either of these bit flag For endpoint status requests, the .Fa wStatus member may have this bit flag set: -.Bl -tag -offset offset -compact +.Bl -tag -width UES_HALTXX -offset offset -compact .It Dv UES_HALT .El .Pp @@ -521,7 +524,7 @@ structure, which has these members: The .Fa bDescriptorType member may be one of the following values: -.Bl -tag -offset offset -compact +.Bl -tag -width UDESC_OTHER_SPEED_CONFIGURATIONXX -offset offset -compact .It Dv UDESC_DEVICE .It Dv UDESC_CONFIG .It Dv UDESC_STRING @@ -538,9 +541,9 @@ member may be one of the following value .It Dv UDESC_CS_STRING .It Dv UDESC_CS_INTERFACE .It Dv UDESC_CS_ENDPOINT -.It Dv UDESC_HUB +.It Dv UDESC_HUB .El -.Pp +.\".Pp .\" these have API front ends .\" .It Dv UR_GET_CONFIG .\" .It Dv UR_SET_CONFIG @@ -548,7 +551,6 @@ member may be one of the following value .\" .It Dv UR_SET_INTERFACE .\" this isn't supported .\" .It Dv UR_SYNCH_FRAME -.\" .Sh SEE ALSO .Xr usb 4 , .Xr usbd_status 9