Tribblix: manual page: usba_hcdi

USBA_HCDI_CB(9F) Kernel Functions for Drivers USBA_HCDI_CB(9F)

NAME

usba_hcdi_cb - USBA transfer callback

SYNOPSIS

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

void
usba_hcdi_cb(usba_pipe_handle_data_t *ph, usb_opaque_t req,
ucb_cr_t cr);

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 the USBA pipe handle that was passed to the
HCD driver during a call to the usba_hcdi_pipe_open(9E)
entry point.

req A pointer to the request structure that is being
completed.

cr The completion code for the request.

DESCRIPTION

The usba_hcdi_cb() function is used when the HCD controller has
completed processing a USB transfer request, whether successfully or
not.

The USB transfer will have been initiated by a call to
usba_hcdi_pipe_bulk_xfer(9E), usba_hcdi_pipe_ctrl_xfer(9E),
usba_hcdi_pipe_intr_xfer(9E), or usba_hcdi_pipe_isoc_xfer(9E). If the
transfer initiated was a periodic transfer (certain Interrupt-IN and
Isochronous-IN transfers), then there may be more than one callback
performed over the life of the transfer.

This function must not be used if the HCD driver returned a value other
than USB_SUCCESS to one of the transfer initialization functions listed
above. For more information on transfer request handling, see
usba_hcdi(9E).

The ph argument corresponds to the USBA framework's pipe handle that
was given to the HCDI when the pipe was opened. See
usba_hcdi_pipe_open(9E) and usba_hcdi(9E) for more information.

The req argument is one of the four request structures,
usb_bulk_req(9S), usb_ctrl_req(9S), usb_intr_req(9S), or
usb_isoc_req(9S), which have been cast to the type usb_opaque_t. The
caller should ensure that all appropriate members of the request
structure have been filled in. For example, if expecting data from the
device and the request has completed successfully, then that data
should be copied into the request structure's mblk(9S) prior to handing
the request structure to the usb_hcdi_cb() function. Similarly, the
usb_isoc_req(9S) structure's isoc_pkt_descr member should be filled in
with the appropriate data.

Once the request structure has been passed to the usba_hcdi_cb()
function, the HCD driver must not access the structure ever again. It
should be treated as freed memory.

The cr argument us used to indicate whether the transfer was successful
or not. If cr is set to USB_CR_OK that indicates that the transfer
completed successfully. This should also be used when a permitted
short transfer has occurred. Otherwise, it should be set to one of the
completion reasons.

Locking

The HCD driver should not hold its own internal locks across a call to
the usba_hcdi_cb() function. It is possible that the driver will have
once of its usba_hcdi(9E) entry points called based on the return value
specified.

CONTEXT

The usba_hcdi_cb() function may be called from user, kernel, or
interrupt context.