From 9c94f403d652d6919baa35853995c29677f21186 Mon Sep 17 00:00:00 2001 From: mrg Date: Sat, 2 Jun 2012 23:10:12 +0000 Subject: [PATCH] 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. --- share/man/man9/usbdi.9 | 129 ++++++++++++++++++++++++++++++++--------- 1 file changed, 103 insertions(+), 26 deletions(-) diff --git a/share/man/man9/usbdi.9 b/share/man/man9/usbdi.9 index 4cbc035399ec..50a0bc55e7e9 100644 --- a/share/man/man9/usbdi.9 +++ b/share/man/man9/usbdi.9 @@ -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 @@ 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. +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 control pipe transfers, by 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 @@ bulk fashion, and are front-ends to the 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 @@ with the .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 @@ for the particular interface .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 @@ macro can be used to match any USB product by a particular vendor. .\" .\" 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" \