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)