1.\" $OpenBSD: usbd_transfer.9,v 1.7 2015/05/04 14:36:26 jmc Exp $ 2.\" 3.\" Copyright (c) 2013 Martin Pieuchot 4.\" 5.\" Permission to use, copy, modify, and distribute this software for any 6.\" purpose with or without fee is hereby granted, provided that the above 7.\" copyright notice and this permission notice appear in all copies. 8.\" 9.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 10.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 11.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 12.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 13.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 14.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 15.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 16.\" 17.Dd $Mdocdate: May 4 2015 $ 18.Dt USBD_TRANSFER 9 19.Os 20.Sh NAME 21.Nm usbd_setup_xfer , usbd_transfer 22.Nd submit USB data transfers 23.Sh SYNOPSIS 24.In dev/usb/usb.h 25.In dev/usb/usbdi.h 26.Ft void 27.Fn usbd_setup_xfer "struct usbd_xfer *xfer" "struct usbd_pipe *pipe" \ 28 "void *priv" "void *buffer" "uint32_t length" "uint16_t flags" \ 29 "uint32_t timeout" "usbd_callback callback" 30.Ft usbd_status 31.Fn usbd_transfer "struct usbd_xfer *xfer" 32.Sh DESCRIPTION 33These functions provide a controller independent mechanism to perform USB 34data transfers. 35They make use of a pipe created by 36.Xr usbd_open_pipe 9 37or 38.Xr usbd_open_pipe_intr 9 . 39.Pp 40The function 41.Fn usbd_setup_xfer 42is used to initialize the structure pointed to by 43.Fa xfer , 44describing an individual transfer to submit. 45It takes the following arguments: 46.Bl -tag -width callback 47.It Fa xfer 48A pointer to an existing structure describing a transfer. 49.It Fa pipe 50A pointer to a pipe associated with the endpoint for the transfer. 51.It Fa priv 52A pointer to a private cookie untouched by the USB stack for reuse in the 53.Fa callback . 54.It Fa buffer 55A pointer to the data buffer. 56.It Fa length 57The total length of the data to read or write. 58.It Fa flags 59The characteristics of the transfer: 60.Bl -tag -width xxx -offset indent 61.It Dv USBD_NO_COPY 62Do not copy data between 63.Fa buffer 64and the DMA buffer. 65.It Dv USBD_SYNCHRONOUS 66Causes 67.Fn usbd_transfer 68to sleep until the I/O transfer is complete or the 69.Fa timeout 70expires. 71.It Dv USBD_SHORT_XFER_OK 72Do not report short reads, when the length of the data read is lower than 73.Fa length , 74as errors. 75.It Dv USBD_FORCE_SHORT_XFER 76Submit a supplementary zero length packet at the end of the written data. 77Some requests may need such packets in order to be properly terminated. 78.It Dv USBD_CATCH 79Used in conjunction with the 80.Dv USBD_SYNCHRONOUS 81flag to pass the 82.Dv PCATCH 83flag to 84.Xr tsleep 9 85in order to check for signals before and after sleeping. 86.El 87.It Fa timeout 88Timeout of the transfer in milliseconds. 89.It Fa callback 90A routine invoked upon completion of the transfer whether successful or not. 91.El 92.Pp 93The function 94.Fn usbd_transfer 95is used to submit the USB transfer described by 96.Fa xfer 97to the corresponding 98.Xr usb 4 99host controller to perform I/O with devices. 100.Sh CONTEXT 101.Fn usbd_setup_xfer 102can be called during autoconf, from process context, or from interrupt context. 103.Pp 104.Fn usbd_transfer 105can be called during autoconf, from process context, or from interrupt context 106if 107.Dv USBD_SYNCHRONOUS 108has not been passed via 109.Fa flags . 110.Sh SEE ALSO 111.Xr ehci 4 , 112.Xr ohci 4 , 113.Xr uhci 4 , 114.Xr usb 4 , 115.Xr tsleep 9 , 116.Xr usbd_open_pipe 9 , 117.Xr usbd_open_pipe_intr 9 118