illumos: manual page: usba_hcdi_pipe_bulk

USBA_HCDI_PIPE_BULK_XFER(9E) Driver Entry Points USBA_HCDI_PIPE_BULK_XFER(9E)

NAME

usba_hcdi_pipe_bulk_xfer - perform a USB bulk transfer

SYNOPSIS

#include <sys/usb/usba/hcdi.h>

int
prefix_hcdi_pipe_bulk_xfer(usba_pipe_handle_data_t *ph,
usb_bulk_req_t *ubrp, usb_flags_t usb_flags);

INTERFACE LEVEL

Volatile - illumos USB HCD private function

This is a private function that is not part of the stable DDI. It may be
removed or changed at any time.

PARAMETERS

ph A pointer to a USB pipe handle as defined in
usba_pipe_handle_data(9S).

ubrp A pointer to a USB bulk transfer request. The structure's
members are documented in usb_bulk_req(9S).

usb_flags Flags which describe how allocations should be performed.
Valid flags are:

USB_FLAGS_NOSLEEP
Do not block waiting for memory. If memory is not
available the allocation will fail.

USB_FLAGS_SLEEP
Perform a blocking allocation. If memory is not
available, the function will wait until memory is
made available.

Note, the request may still fail even if
USB_FLAGS_SLEEP is specified.

DESCRIPTION

The usba_hcdi_pipe_bulk_xfer() entry point is used to initiate an
asynchronous USB bulk transfer on the pipe ph. The specific USB bulk
transfer is provided in ubrp. For more background on transfer types, see
usba_hcdi(9E).

The host controller driver should first check the USB address of the pipe
handle. It may correspond to the root hub. If it does, the driver should
return USB_NOT_SUPPORTED.

Bulk transfers may send data to the device or receive data from the device.
A given bulk endpoint is uni-directional. The direction can be determined
from the endpoint address based on the p_ep member of ubrp. See
usb_ep_descr(9S) for more information on how to determine the direction of
the endpoint.

The device driver should allocate memory, whether memory suitable for a DMA
transfer or otherwise, to perform the transfer. For all memory allocated,
it should honor the values in usb_flags to determine whether or not it
should block for allocations.

The length of the bulk transfer and its data can be found in the bulk_len
and bulk_data members of ubrp respectively. The mblk(9S) structure that
should not be used directly and data should be copied to or from the data
buffer that will go the controller.

If the driver successfully schedules the I/O, then it should return
USB_SUCCESS. When the I/O completes, it must call usba_hcdi_cb(9F) with
ubrp. If the transfer fails, but the driver returned USB_SUCCESS, it still
must call usba_hcdi_cb(9F) and should specify an error there.

It is the driver's responsibility to time out bulk transfer requests. If
the timeout in the request as indicated in the bulk_timeout member of ubrp
is set to zero, then the driver should use the USBA default timeout of
HCDI_DEFAULT_TIMEOUT. All timeout values are in seconds.

Callback Handling

When the bulk transfer completes the driver should consider the following
items to determine what actions it should take on the callback:

+o If the transfer timed out, it should remove the transfer from the
outstanding list, queue the next transfer, and return the transfer back
to the OS with the error code USB_CR_TIMEOUT with usba_hcdi_cb(9F).

+o If the transfer failed, it should find the appropriate error and call
usba_hcdi_cb(9F) with that error.

+o If the transfer succeeded, but less data was transferred than expected,
consult the bulk_attributes member of the ubrp. If the
USB_ATTRS_SHORT_XFER_OK flag is not present, then the driver should
call usba_hcdi_cb(9F) with the error USB_CR_DATA_UNDERRUN.

+o If the transfer was going to the host, then the driver should copy the
data into the transfer's message block and update the b_wptr member of
the mblk(9S).

+o If everything was successful, call usba_hcdi_cb(9F) with the code
USB_CR_OK.

RETURN VALUES

Upon successful completion, the usba_hcdi_pipe_bulk_xfer() function should
return USB_SUCCESS. Otherwise, it should return the appropriate USB error.
If uncertain, use USB_FAILURE.