Tribblix: manual page: usba_hcdi_pipe_intr

USBA_HCDI_PIPE_INTR_XFER(9E) Driver Entry Points

NAME

usba_hcdi_pipe_intr_xfer - perform a USB interrupt transfer

SYNOPSIS

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

int
prefix_hcdi_pipe_intr_xfer(usba_pipe_handle_data_t *ph,
usb_intr_req_t *uirp, 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).

uirp A pointer to a USB interrupt transfer request. The
structure's members are documented in usb_intr_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_intr_xfer() entry point is used to initiate an
asynchronous USB interrupt 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, rather
than initiating an I/O transfer, the driver may need to emulate it.

Unlike other transfers, interrupt transfers may be periodic. If the
transfer is meant to be a one-shot, then the USB_ATTRS_ONE_XFER flag
will be set in the intr_attributes member of the uirp structure. If
the USB_ATTRS_ONE_XFER flag is not set, then the transfer begins a
periodic transfer. Periodic transfers have different handling and
behavior.

Interrupt transfers may send data to the device or receive data from
the device. A given interrupt 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 interrupt transfer and its data can be found in the
intr_len and intr_data members of uirp 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.

Unlike bulk and control transfers, the intr_data member may not be
allocated for interrupt-IN transfers. In such cases, the device driver
is required to allocate the message block through something like
allocb(9F) and assign it to the intr_data member.

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 uirp. 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 one-shot interrupt
transfer requests. If the timeout in the request as indicated in the
intr_timeout member of uirp is set to zero, then the driver should use
the USBA default timeout of HCDI_DEFAULT_TIMEOUT. All timeout values
are in seconds.

Periodic Transfers

When the USB_ATTRS_ONE_XFER flag is not present, it indicates that a
periodic interrupt transfer is being initiated. Once a periodic
interrupt transfer is initiated, every time data is received the driver
should call usba_hcdi_cb(9F) with the 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 interrupt
request, uirp. Instead, it should duplicate the request through the
usba_hcdi_dup_intr_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_intr_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.

If the periodic interrupt transfer is for the root hub, the driver will
need to emulate the behavior of a hub as specified in the USB
specification. For more information, see the Root Hub Management
section in usba_hcdi(9E).

Callback Handling

When the interrupt 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 intr_attributes member of the uirp. 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.

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

RETURN VALUES

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