usr/src/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. It may be
  33 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. The structure's members are
  41 documented in
  42 .Xr usb_bulk_req 9S .
  43 .It Fa usb_flags
  44 Flags which describe how allocations should be performed. Valid flags
  45 are:
  46 .Bl -tag -width Sy
  47 .It Sy USB_FLAGS_NOSLEEP
  48 Do not block waiting for memory. If memory is not available the allocation
  49 will fail.
  50 .It Sy USB_FLAGS_SLEEP
  51 Perform a blocking allocation. If memory is not available, the function
  52 will wait until memory is made available.
  53 .Pp
  54 Note, the request may still fail even if
  55 .Sy USB_FLAGS_SLEEP
  56 is specified.
  57 .El
  58 .El
  59 .Sh DESCRIPTION
  60 The
  61 .Fn usba_hcdi_pipe_bulk_xfer
  62 entry point is used to initiate an
  63 .Em asynchronous
  64 USB bulk transfer on the pipe
  65 .Fa ph .
  66 The specific USB bulk transfer is provided in
  67 .Fa ubrp .
  68 For more background on transfer types, see
  69 .Xr usba_hcdi 9E .
  70 .Pp
  71 The host controller driver should first check the USB address of the
  72 pipe handle. It may correspond to the root hub. If it does, the driver
  73 should return
  74 .Sy USB_NOT_SUPPORTED .
  75 .Pp
  76 Bulk transfers may send data to the device or receive data from the
  77 device. A given bulk endpoint is uni-directional. The direction can be
  78 determined from the endpoint address based on the
  79 .Sy p_ep
  80 member of
  81 .Fa ubrp .
  82 See
  83 .Xr usb_ep_descr 9S
  84 for more information on how to determine the direction of the endpoint.
  85 .Pp
  86 The device driver should allocate memory, whether memory suitable for a
  87 DMA transfer or otherwise, to perform the transfer. For all memory
  88 allocated, it should honor the values in
  89 .Fa usb_flags
  90 to determine whether or not it should block for allocations.
  91 .Pp
  92 The length of the bulk transfer and its data can be found in the
  93 .Sy bulk_len
  94 and
  95 .Sy bulk_data
  96 members of
  97 .Fa ubrp
  98 respectively. The
  99 .Xr mblk 9S
 100 structure that should not be used directly and data should be copied to
 101 or from the data buffer that will go the controller.
 102 .Pp
 103 If the driver successfully schedules the I/O, then it should return
 104 .Sy USB_SUCCESS .
 105 When the I/O completes, it must call
 106 .Xr usba_hcdi_cb 9F
 107 with
 108 .Fa ubrp .
 109 If the transfer fails, but the driver returned
 110 .Sy USB_SUCCESS ,
 111 it still must call
 112 .Xr usba_hcdi_cb 9F
 113 and should specify an error there.
 114 .Pp
 115 It is the driver's responsibility to time out bulk transfer
 116 requests. If the timeout in the request as indicated in the
 117 .Sy bulk_timeout
 118 member of
 119 .Fa ubrp
 120 is set to zero, then the driver should use the USBA default timeout of
 121 .Sy HCDI_DEFAULT_TIMEOUT .
 122 All timeout values are in
 123 .Em seconds .
 124 .Ss Callback Handling
 125 When the bulk transfer completes the driver should consider the
 126 following items to determine what actions it should take on the
 127 callback:
 128 .Bl -bullet
 129 .It
 130 If the transfer timed out, it should remove the transfer from the
 131 outstanding list, queue the next transfer, and return the transfer back
 132 to the OS with the error code
 133 .Sy USB_CR_TIMEOUT
 134 with
 135 .Xr usba_hcdi_cb 9F .
 136 .It
 137 If the transfer failed, it should find the appropriate error and call
 138 .Xr usba_hcdi_cb 9F
 139 with that error.
 140 .It
 141 If the transfer succeeded, but less data was transferred than expected,
 142 consult the
 143 .Sy bulk_attributes
 144 member of the
 145 .Fa ubrp .
 146 If the
 147 .Sy USB_ATTRS_SHORT_XFER_OK
 148 flag is not present, then the driver should call
 149 .Xr usba_hcdi_cb 9F
 150 with the error
 151 .Sy USB_CR_DATA_UNDERRUN .
 152 .It
 153 If the transfer was going to the host, then the driver should copy the
 154 data into the transfer's message block and update the
 155 .Sy b_wptr
 156 member of the
 157 .Xr mblk 9S .
 158 .It
 159 If everything was successful, call
 160 .Xr usba_hcdi_cb 9F
 161 with the code
 162 .Sy USB_CR_OK .
 163 .El
 164 .Sh RETURN VALUES
 165 Upon successful completion, the
 166 .Fn usba_hcdi_pipe_bulk_xfer
 167 function should return
 168 .Sy USB_SUCCESS .
 169 Otherwise, it should return the appropriate USB error. If uncertain, use
 170 .Sy USB_FAILURE .
 171 .Sh SEE ALSO
 172 .Xr usba_hcdi 9E ,
 173 .Xr usba_hcdi_cb 9F ,
 174 .Xr mblk 9S ,
 175 .Xr usb_bulk_req 9S ,
 176 .Xr usb_ep_descr 9S ,
 177 .Xr usba_pipe_handle_data 9S