share/man/man9f/usba_hcdi_cb.9f

   1 .\"
   2 .\" This file and its contents are supplied under the terms of the
   3 .\" Common Development and Distribution License ("CDDL"), version 1.0.
   4 .\" You may only use this file in accordance with the terms of version
   5 .\" 1.0 of the CDDL.
   6 .\"
   7 .\" A full copy of the text of the CDDL should have accompanied this
   8 .\" source.  A copy of the CDDL is also available via the Internet at
   9 .\" http://www.illumos.org/license/CDDL.
  10 .\"
  11 .\"
  12 .\" Copyright 2016 Joyent, Inc.
  13 .\"
  14 .Dd Sep 16, 2016
  15 .Dt USBA_HCDI_CB 9F
  16 .Os
  17 .Sh NAME
  18 .Nm usba_hcdi_cb
  19 .Nd USBA transfer callback
  20 .Sh SYNOPSIS
  21 .In sys/usb/usba/hcdi.h
  22 .Ft void
  23 .Fo usba_hcdi_cb
  24 .Fa "usba_pipe_handle_data_t *ph"
  25 .Fa "usb_opaque_t req"
  26 .Fa "ucb_cr_t cr"
  27 .Fc
  28 .Sh INTERFACE LEVEL
  29 .Sy Volatile -
  30 illumos USB HCD private function
  31 .Pp
  32 This is a private function that is not part of the stable DDI.
  33 It may be removed or changed at any time.
  34 .Sh PARAMETERS
  35 .Bl -tag -width Fa
  36 .It Fa ph
  37 A pointer to the USBA pipe handle that was passed to the HCD driver
  38 during a call to the
  39 .Xr usba_hcdi_pipe_open 9E
  40 entry point.
  41 .It Fa req
  42 A pointer to the request structure that is being completed.
  43 .It Fa cr
  44 The completion code for the request.
  45 .El
  46 .Sh DESCRIPTION
  47 The
  48 .Fn usba_hcdi_cb
  49 function is used when the HCD controller has completed processing a USB
  50 transfer request, whether
  51 successfully or not.
  52 .Pp
  53 The USB transfer will have been initiated by a call to
  54 .Xr usba_hcdi_pipe_bulk_xfer 9E ,
  55 .Xr usba_hcdi_pipe_ctrl_xfer 9E ,
  56 .Xr usba_hcdi_pipe_intr_xfer 9E ,
  57 or
  58 .Xr usba_hcdi_pipe_isoc_xfer 9E .
  59 If the transfer initiated was a periodic transfer (certain Interrupt-IN
  60 and Isochronous-IN transfers), then there may be more than one callback
  61 performed over the life of the transfer.
  62 .Pp
  63 This function must not be used if the HCD driver returned a value
  64 other than
  65 .Sy USB_SUCCESS
  66 to one of the transfer initialization functions listed above.
  67 For more information on transfer request handling, see
  68 .Xr usba_hcdi 9E .
  69 .Pp
  70 The
  71 .Fa ph
  72 argument corresponds to the USBA framework's pipe handle that was given
  73 to the HCDI when the pipe was opened.
  74 See
  75 .Xr usba_hcdi_pipe_open 9E
  76 and
  77 .Xr usba_hcdi 9E
  78 for more information.
  79 .Pp
  80 The
  81 .Fa req
  82 argument is one of the four request structures,
  83 .Xr usb_bulk_req 9S ,
  84 .Xr usb_ctrl_req 9S ,
  85 .Xr usb_intr_req 9S ,
  86 or
  87 .Xr usb_isoc_req 9S ,
  88 which have been cast to the type
  89 .Ft usb_oapque_t .
  90 The caller should ensure that all appropriate members of the request
  91 structure have been filled in.
  92 For example, if expecting data from the device and the request has completed
  93 successfully, then that data should be copied into the request structure's
  94 .Xr mblk 9S
  95 prior to handing the request structure to the
  96 .Fn usb_hcdi_cb
  97 function.
  98 Similarly, the
  99 .Xr usb_isoc_req 9S
 100 structure's
 101 .Sy isoc_pkt_descr
 102 member should be filled in with the appropriate data.
 103 .Pp
 104 Once the request structure has been passed to the
 105 .Fn usba_hcdi_cb
 106 function, the HCD driver must not access the structure ever again.
 107 It should be treated as freed memory.
 108 .Pp
 109 The
 110 .Fa cr
 111 argument us used to indicate whether the transfer was successful or not.
 112 If
 113 .Fa cr
 114 is set to
 115 .Sy USB_CR_OK
 116 that indicates that the transfer completed successfully.
 117 This should also be used when a permitted short transfer has occurred.
 118 Otherwise, it should be set to one of the completion reasons.
 119 .Ss Locking
 120 The HCD driver should not hold its own internal locks across a call to
 121 the
 122 .Fn usba_hcdi_cb
 123 function.
 124 It is possible that the driver will have once of its
 125 .Xr usba_hcdi 9E
 126 entry points called based on the return value specified.
 127 .Sh CONTEXT
 128 The
 129 .Fn usba_hcdi_cb
 130 function may be called from
 131 .Sy user ,
 132 .Sy kernel ,
 133 or
 134 .Sy interrupt
 135 context.
 136 .Sh SEE ALSO
 137 .Xr usba_hcdi 9E ,
 138 .Xr usba_hcdi_pipe_bulk_xfer 9E ,
 139 .Xr usba_hcdi_pipe_ctrl_xfer 9E ,
 140 .Xr usba_hcdi_pipe_intr_xfer 9E ,
 141 .Xr usba_hcdi_pipe_isoc_xfer 9E ,
 142 .Xr usba_hcdi_pipe_open 9E ,
 143 .Xr mblk 9S ,
 144 .Xr usb_bulk_req 9S ,
 145 .Xr usb_ctrl_req 9S ,
 146 .Xr usb_intr_req 9S ,
 147 .Xr usb_isoc_req 9S