share/man/man9e/usba_hcdi_pipe_bulk_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_BULK_XFER 9E
  16 .Os
  17 .Sh NAME
  18 .Nm usba_hcdi_pipe_bulk_xfer
  19 .Nd perform a USB bulk transfer
  20 .Sh SYNOPSIS
  21 .In sys/usb/usba/hcdi.h
  22 .Ft int
  23 .Fo prefix_hcdi_pipe_bulk_xfer
  24 .Fa "usba_pipe_handle_data_t *ph"
  25 .Fa "usb_bulk_req_t *ubrp"
  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 ubrp
  40 A pointer to a USB bulk transfer request.
  41 The structure's members are documented in
  42 .Xr usb_bulk_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_bulk_xfer
  63 entry point is used to initiate an
  64 .Em asynchronous
  65 USB bulk transfer on the pipe
  66 .Fa ph .
  67 The specific USB bulk transfer is provided in
  68 .Fa ubrp .
  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, the driver should return
  76 .Sy USB_NOT_SUPPORTED .
  77 .Pp
  78 Bulk transfers may send data to the device or receive data from the device.
  79 A given bulk endpoint is uni-directional.
  80 The direction can be determined from the endpoint address based on the
  81 .Sy p_ep
  82 member of
  83 .Fa ubrp .
  84 See
  85 .Xr usb_ep_descr 9S
  86 for more information on how to determine the direction of the endpoint.
  87 .Pp
  88 The device driver should allocate memory, whether memory suitable for a
  89 DMA transfer or otherwise, to perform the transfer.
  90 For all memory allocated, it should honor the values in
  91 .Fa usb_flags
  92 to determine whether or not it should block for allocations.
  93 .Pp
  94 The length of the bulk transfer and its data can be found in the
  95 .Sy bulk_len
  96 and
  97 .Sy bulk_data
  98 members of
  99 .Fa ubrp
 100 respectively.
 101 The
 102 .Xr mblk 9S
 103 structure that should not be used directly and data should be copied to
 104 or from the data buffer that will go the controller.
 105 .Pp
 106 If the driver successfully schedules the I/O, then it should return
 107 .Sy USB_SUCCESS .
 108 When the I/O completes, it must call
 109 .Xr usba_hcdi_cb 9F
 110 with
 111 .Fa ubrp .
 112 If the transfer fails, but the driver returned
 113 .Sy USB_SUCCESS ,
 114 it still must call
 115 .Xr usba_hcdi_cb 9F
 116 and should specify an error there.
 117 .Pp
 118 It is the driver's responsibility to time out bulk transfer requests.
 119 If the timeout in the request as indicated in the
 120 .Sy bulk_timeout
 121 member of
 122 .Fa ubrp
 123 is set to zero, then the driver should use the USBA default timeout of
 124 .Sy HCDI_DEFAULT_TIMEOUT .
 125 All timeout values are in
 126 .Em seconds .
 127 .Ss Callback Handling
 128 When the bulk transfer completes the driver should consider the
 129 following items to determine what actions it should take on the
 130 callback:
 131 .Bl -bullet
 132 .It
 133 If the transfer timed out, it should remove the transfer from the
 134 outstanding list, queue the next transfer, and return the transfer back
 135 to the OS with the error code
 136 .Sy USB_CR_TIMEOUT
 137 with
 138 .Xr usba_hcdi_cb 9F .
 139 .It
 140 If the transfer failed, it should find the appropriate error and call
 141 .Xr usba_hcdi_cb 9F
 142 with that error.
 143 .It
 144 If the transfer succeeded, but less data was transferred than expected,
 145 consult the
 146 .Sy bulk_attributes
 147 member of the
 148 .Fa ubrp .
 149 If the
 150 .Sy USB_ATTRS_SHORT_XFER_OK
 151 flag is not present, then the driver should call
 152 .Xr usba_hcdi_cb 9F
 153 with the error
 154 .Sy USB_CR_DATA_UNDERRUN .
 155 .It
 156 If the transfer was going to the host, then the driver should copy the
 157 data into the transfer's message block and update the
 158 .Sy b_wptr
 159 member of the
 160 .Xr mblk 9S .
 161 .It
 162 If everything was successful, call
 163 .Xr usba_hcdi_cb 9F
 164 with the code
 165 .Sy USB_CR_OK .
 166 .El
 167 .Sh RETURN VALUES
 168 Upon successful completion, the
 169 .Fn usba_hcdi_pipe_bulk_xfer
 170 function should return
 171 .Sy USB_SUCCESS .
 172 Otherwise, it should return the appropriate USB error.
 173 If uncertain, use
 174 .Sy USB_FAILURE .
 175 .Sh SEE ALSO
 176 .Xr usba_hcdi 9E ,
 177 .Xr usba_hcdi_cb 9F ,
 178 .Xr mblk 9S ,
 179 .Xr usb_bulk_req 9S ,
 180 .Xr usb_ep_descr 9S ,
 181 .Xr usba_pipe_handle_data 9S