illumos: manual page: usba_hcdi_pipe_isoc

USBA_HCDI_PIPE_ISOC_XFER(9E) Driver Entry Points USBA_HCDI_PIPE_ISOC_XFER(9E)

NAME

usba_hcdi_pipe_isoc_xfer - perform a USB isochronous transfer

SYNOPSIS

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

int
prefix_hcdi_pipe_isoc_xfer(usba_pipe_handle_data_t *ph,
usb_isoc_req_t *usrp, 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).

usrp A pointer to a USB isochronous transfer request. The
structure's members are documented in usb_isoc_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_isoc_xfer() entry point is used to initiate an
asynchronous USB isochronous transfer on the pipe ph. The specific USB
interrupt transfer is provided in uirp. 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.

Isochronous transfers happen once a period. Isochronous transfers may just
be told to start as son as possible or to line up to a specific frame. At
this time, nothing in the system uses the later behavior. It is reasonable
for a new driver to require that the USB_ATTRS_ISOC_XFER_ASAP flag be set
in the isoc_attributes member of the usrp argument. In the case where it's
not set and the controller driver does not support setting the frame, it
should return USB_NOT_SUPPORTED.

Isochronous-IN transfers are always periodic. Isochronous-OUT transfers
are one shot transfers. Periodic transfers have slightly different
handling and behavior.

Isochronous transfers may send data to the device or receive data from the
device. A given isochronous 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.

Isochronous transfers are a little bit different from other transfers.
While there is still a single mblk(9S) structure that all the data goes to
or from, the transfer may be broken up into multiple packets. All of these
packets make up a single transfer request and each one represents the data
that is transferred during a single portion of a frame. For the
description of them, see usb_isoc_req(9S). Because of these data
structures, the way that transfers are recorded is different and will be
discussed later on.

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.

For isochronous-out transfers which are one-shot transfers, the driver
should verify that the sum of all of the individual packet counts matches
the message block length of the data. If it does not, then the driver
should return USB_INVALID_ARGS.

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
usrp. If the transfer fails, but the driver returned USB_SUCCESS, it still
must call usba_hcdi_cb(9F) and should specify an error there.

The driver is responsible for timing out all one-shot outgoing requests.
As there is no timeout member in the isochronous request structure, then
the timeout should be set to HCDI_DEFAULT_TIMEOUT.

Periodic Transfers

All isochronous-in transfers are periodic transfers. Once a periodic
transfer is initiated, every time data is received the driver should call
the usba_hcdi_cb(9F) function with updated data.

When a periodic transfer is initiated, many controller drivers will
allocate multiple transfers up front and schedule them all. Many drivers
do this to ensure that data isn't lost between servicing the first transfer
and scheduling the next. The number of such transfers used depends on the
polling frequency specified in the endpoint descriptor.

Unless an error occurs, the driver must not use the original isochronous
request, usrp. Instead, it should duplicate the request through the
usba_hcdi_dup_isoc_req(9F) function before calling usba_hcdi_cb(9F).

The driver should return the original transfer in one of the following
conditions:

+o A pipe reset request came in from the usba_hcdi_pipe_reset(9E) entry
point.

+o A request to stop polling came in from the
usba_hcdi_pipe_stop_isoc_polling(9E) entry point.

+o A request to close the pipe came in from the usba_hcdi_pipe_close(9E)
entry point.

+o An out of memory condition occurred. The caller should call
usba_hcdi_cb(9F) with the code USB_CR_NO_RESOURCES.

+o Some other transfer error occurred.

Callback Handling

When the isochronous transfer completes, the driver should consider the
following items to determine what actions it should take on the callback:
USB_SUCCESS. Otherwise, it should return the appropriate USB error. If
uncertain, use USB_FAILURE.

+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 isoc_attributes member of the usrp. 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 The driver should update the isoc_pkt_actual_length member of the
isoc_pkt_descr array of the usb_isoc_req(9S) structure with the actual
transfer amounts.

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

+o If this was a periodic transfer, it should reschedule the transfer.

RETURN VALUES

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