usr/src/man/man9e/usba_hcdi_pipe_ctrl_xfer.9e

   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 Dec 22, 2016
  15 .Dt USBA_HCDI_PIPE_CTRL_XFER 9E
  16 .Os
  17 .Sh NAME
  18 .Nm usba_hcdi_pipe_ctrl_xfer
  19 .Nd perform a USB control transfer
  20 .Sh SYNOPSIS
  21 .In sys/usb/usba/hcdi.h
  22 .Ft int
  23 .Fo prefix_hcdi_pipe_ctrl_xfer
  24 .Fa "usba_pipe_handle_data_t *ph"
  25 .Fa "usb_ctrl_req_t *ucrp"
  26 .Fa "usb_flags_t usb_flags"
  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 a USB pipe handle as defined in
  38 .Xr usba_pipe_handle_data 9S .
  39 .It Fa ucrp
  40 A pointer to a USB control transfer request.
  41 The structure's members are documented in
  42 .Xr usb_ctrl_req 9S .
  43 .It Fa usb_flags
  44 Flags which describe how allocations should be performed.
  45 Valid flags are:
  46 .Bl -tag -width Sy
  47 .It Sy USB_FLAGS_NOSLEEP
  48 Do not block waiting for memory.
  49 If memory is not available the allocation will fail.
  50 .It Sy USB_FLAGS_SLEEP
  51 Perform a blocking allocation.
  52 If memory is not available, the function will wait until memory is made
  53 available.
  54 .Pp
  55 Note, the request may still fail even if
  56 .Sy USB_FLAGS_SLEEP
  57 is specified.
  58 .El
  59 .El
  60 .Sh DESCRIPTION
  61 The
  62 .Fn usba_hcdi_pipe_ctrl_xfer
  63 entry point is used to initiate an
  64 .Em asynchronous
  65 USB Control transfer on the pipe
  66 .Fa ph .
  67 The specific USB control transfer is provided in
  68 .Fa ucrp .
  69 For more background on transfer types, see
  70 .Xr usba_hcdi 9E .
  71 .Pp
  72 The host controller driver should first check the USB address of the
  73 pipe handle.
  74 It may correspond to the root hub.
  75 If it does, rather than initiating an I/O transfer, the driver may need to
  76 emulate it using available information.
  77 .Pp
  78 Control endpoints are always bi-directional.
  79 A given endpoint may perform transfer data from the OS to the device, or from
  80 the device to the OS.
  81 The driver will need to look at the control transfer request and transform that
  82 into the appropriate format for the controller.
  83 .Pp
  84 Control transfers are made up of three parts.
  85 A setup stage, an optional data stage, and a status stage.
  86 Depending on the controller, the driver may need to transform the transfer
  87 request into a format that matches this.
  88 Refer to the device's controller specification for more information on whether
  89 this is required or not.
  90 .Pp
  91 The device driver should a request based on the information present in
  92 the control request
  93 .Fa ucrp .
  94 If there is a non-zero length for the transfer, indicated by the
  95 .Sy ctrl_wLength
  96 member of
  97 .Fa ucrp
  98 being greater than zero, then the controller needs to allocate a
  99 separate memory buffer for the request.
 100 The corresponding data will be found in an
 101 .Xr mblk 9S
 102 structure as the
 103 .Sy ctrl_data
 104 member of
 105 .Fa ucrp .
 106 .Pp
 107 If this transfer needs to be sent to a device through the controller and
 108 is not being handled directly by the driver, then the driver should
 109 allocate a separate region of memory (generally memory suitable for a
 110 DMA transfer) for the transfer.
 111 If sending data to the device, the data in the message block should be copied
 112 prior to the transfer.
 113 Otherwise, once the transfer completes, data should be transferred into the
 114 message block and the write pointer incremented.
 115 .Pp
 116 If the driver needs to allocate memory for this transfer, it should
 117 honor the values set in
 118 .Fa usb_flags
 119 to indicate whether or not it should block for memory, whether DMA
 120 memory or normal kernel memory.
 121 .Pp
 122 If the driver successfully schedules the I/O or it can handle the I/O
 123 itself because it's a synthetic root hub request, then it should return
 124 .Sy USB_SUCCESS .
 125 If the driver returns successfully, it must call
 126 .Xr usba_hcdi_cb 9F
 127 with
 128 .Fa ucrp
 129 either before or after it returns.
 130 The only times that a driver would call the callback before the function returns
 131 are for requests to the root hub that it handles inline and does not need to
 132 send off asynchronous activity to the controller.
 133 .Pp
 134 For asynchronous requests, the controller is also responsible for
 135 timing out the request if it does not complete.
 136 If the timeout in the request as indicated in the
 137 .Sy ctrl_timeout
 138 member is set to zero, then the driver should use the USBA default
 139 timeout of
 140 .Sy HCDI_DEFAULT_TIMEOUT .
 141 All timeout values are in
 142 .Em seconds .
 143 .Ss Callback Handling
 144 When the control transfer completes the driver should consider the
 145 following items to determine what actions it should take on the callback:
 146 .Bl -bullet
 147 .It
 148 If the transfer timed out, it should remove the transfer from the
 149 outstanding list, queue the next transfer, and return the transfer back
 150 to the OS with the error code
 151 .Sy USB_CR_TIMEOUT
 152 with
 153 .Xr usba_hcdi_cb 9F .
 154 .It
 155 If the transfer failed, it should find the appropriate error and call
 156 .Xr usba_hcdi_cb 9F
 157 with that error.
 158 .It
 159 If the transfer succeeded, but less data was transferred than expected,
 160 consult the
 161 .Sy ctrl_attributes
 162 member of the
 163 .Fa ucrp .
 164 If the
 165 .Sy USB_ATTRS_SHORT_XFER_OK
 166 flag is not present, then the driver should call
 167 .Xr usba_hcdi_cb 9F
 168 with the error
 169 .Sy USB_CR_DATA_UNDERRUN .
 170 .It
 171 If the transfer was going to the host, then the driver should copy the
 172 data into the transfer's message block and update the
 173 .Sy b_wptr
 174 member of the
 175 .Xr mblk 9S .
 176 .It
 177 If everything was successful, call
 178 .Xr usba_hcdi_cb 9F
 179 with the code
 180 .Sy USB_CR_OK .
 181 .El
 182 .Sh RETURN VALUES
 183 Upon successful completion, the
 184 .Fn usba_hcdi_pipe_ctrl_xfer
 185 function should return
 186 .Sy USB_SUCCESS .
 187 Otherwise, it should return the appropriate USB error.
 188 If uncertain, use
 189 .Sy USB_FAILURE .
 190 .Sh SEE ALSO
 191 .Xr usba_hcdi 9E ,
 192 .Xr usba_hcdi_cb 9F ,
 193 .Xr mblk 9S ,
 194 .Xr usb_ctrl_req 9S ,
 195 .Xr usba_pipe_handle_data 9S