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.

SEE ALSO


usba_hcdi(9E), usba_hcdi_pipe_bulk_xfer(9E), usba_hcdi_pipe_ctrl_xfer(9E),
usba_hcdi_pipe_intr_xfer(9E), usba_hcdi_pipe_isoc_xfer(9E),
usba_hcdi_pipe_open(9E), mblk(9S), usb_bulk_req(9S), usb_ctrl_req(9S),
usb_intr_req(9S), usb_isoc_req(9S)

illumos November 26, 2017 illumos