1.\" $OpenBSD: usbd_transfer.9,v 1.5 2014/07/12 16:07:06 mpi 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: July 12 2014 $ 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. 35.Pp 36The function 37.Fn usbd_setup_xfer 38is used to initialize the structure pointed to by 39.Fa xfer , 40describing an individual transfer to submit. 41It takes the following arguments: 42.Bl -tag -width callback 43.It Fa xfer 44A pointer to an existing structure describing a transfer. 45.It Fa pipe 46A pointer to a pipe associated with the endpoint for the transfer. 47.It Fa priv 48A pointer to a private cookie untouched by the USB stack for reuse in the 49.Fa callback . 50.It Fa buffer 51A pointer to the data buffer. 52.It Fa length 53The total length of the data to read or write. 54.It Fa flags 55The characteristics of the transfer: 56.Bl -tag -width xxx -offset indent 57.It Dv USBD_NO_COPY 58Do not copy data between 59.Fa buffer 60and the DMA buffer. 61.It Dv USBD_SYNCHRONOUS 62Causes 63.Fn usbd_transfer 64to sleep until the I/O transfer is complete or the 65.Fa timeout 66expires. 67.It Dv USBD_SHORT_XFER_OK 68Do not report short reads, when the length of the data read is lower than 69.Fa length , 70as errors. 71.It Dv USBD_FORCE_SHORT_XFER 72Submit a supplementary zero length packet at the end of the written data. 73Some requests may need such packets in order to be properly terminated. 74.It Dv USBD_CATCH 75Used in conjunction with the 76.Dv USBD_SYNCHRONOUS 77flag to pass the 78.Dv PCATCH 79flag to 80.Xr tsleep 9 81in order to check for signals before and after sleeping. 82.El 83.It Fa timeout 84Timeout of the transfer in milliseconds. 85.It Fa callback 86A routine invoked upon completion of the transfer whether successful or not. 87.El 88.Pp 89The function 90.Fn usbd_transfer 91is used to submit the USB transfer described by 92.Fa xfer 93to the corresponding 94.Xr usb 4 95host controller to perform I/O with devices. 96.Sh CONTEXT 97.Fn usbd_setup_xfer 98can be called during autoconf, from process context, or from interrupt context. 99.Pp 100.Fn usbd_transfer 101can be called during autoconf, from process context, or from interrupt context 102if 103.Dv USBD_SYNCHRONOUS 104has not been passed via 105.Fa flags . 106.Sh SEE ALSO 107.Xr ehci 4 , 108.Xr ohci 4 , 109.Xr uhci 4 , 110.Xr usb 4 , 111.Xr tsleep 9 112