USBD_TRANSFER(9) | Kernel Developer's Manual | USBD_TRANSFER(9)

# NAME

`usbd_setup_xfer`, `usbd_transfer` — submit USB data transfers

# SYNOPSIS

`#include <dev/usb/usb.h>`
`#include <dev/usb/usbdi.h>`

void
`usbd_setup_xfer`(struct usbd_xfer *xfer, struct usbd_pipe *pipe, void *priv, void *buffer, uint32_t length, uint16_t flags, uint32_t timeout, usbd_callback callback);

usbd_status
`usbd_transfer`(struct usbd_xfer *xfer);

# DESCRIPTION

These functions provide a controller independent mechanism to perform USB data transfers. They make use of a pipe created by usbd_open_pipe(9) or usbd_open_pipe_intr(9).

The function `usbd_setup_xfer`() is used to initialize the structure pointed to by xfer, describing an individual transfer to submit. It takes the following arguments:

xfer
  A pointer to an existing structure describing a transfer.
pipe
  A pointer to a pipe associated with the endpoint for the transfer.
priv
  A pointer to a private cookie untouched by the USB stack for reuse in the callback.
buffer
  A pointer to the data buffer.
length
  The total length of the data to read or write.
flags
  The characteristics of the transfer:
  `USBD_NO_COPY`
    Do not copy data between buffer and the DMA buffer.
  `USBD_SYNCHRONOUS`
    Causes `usbd_transfer`() to sleep until the I/O transfer is complete or the timeout expires.
  `USBD_SHORT_XFER_OK`
    Do not report short reads, when the length of the data read is lower than length, as errors.
  `USBD_FORCE_SHORT_XFER`
    Submit a supplementary zero length packet at the end of the written data. Some requests may need such packets in order to be properly terminated.
  `USBD_CATCH`
    Used in conjunction with the `USBD_SYNCHRONOUS` flag to pass the `PCATCH` flag to tsleep(9) in order to check for signals before and after sleeping.
timeout
  Timeout of the transfer in milliseconds.
callback
  A routine invoked upon completion of the transfer whether successful or not.

The function `usbd_transfer`() is used to submit the USB transfer described by xfer to the corresponding usb(4) host controller to perform I/O with devices.

# CONTEXT

`usbd_setup_xfer`() can be called during autoconf, from process context, or from interrupt context.

`usbd_transfer`() can be called during autoconf, from process context, or from interrupt context if `USBD_SYNCHRONOUS` has not been passed via flags.

# SEE ALSO

ehci(4), ohci(4), uhci(4), usb(4), tsleep(9), usbd_open_pipe(9), usbd_open_pipe_intr(9)

May 4, 2015 | Debian