share/man/man9f/usb_pipe_bulk_xfer.9f

   1 '\" te
   2 .\" Copyright (c) 2006, Sun Microsystems, Inc., All Rights Reserved
   3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   5 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   6 .TH USB_PIPE_BULK_XFER 9F "Sep 16, 2016"
   7 .SH NAME
   8 usb_pipe_bulk_xfer \- USB bulk transfer function
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 #include <sys/usb/usba.h>
  13
  14
  15
  16 \fBint\fR \fBusb_pipe_bulk_xfer\fR(\fBusb_pipe_handle_t\fR \fIpipe_handle\fR,
  17      \fBusb_bulk_req_t *\fR\fIrequest\fR, \fBusb_flags_t\fR \fIflags\fR);
  18 .fi
  19
  20 .SH INTERFACE LEVEL
  21 .LP
  22 Solaris DDI specific (Solaris DDI)
  23 .SH PARAMETERS
  24 .ne 2
  25 .na
  26 \fB\fIpipe_handle\fR\fR
  27 .ad
  28 .RS 15n
  29 Bulk pipe handle on which request is made.
  30 .RE
  31
  32 .sp
  33 .ne 2
  34 .na
  35 \fB\fIrequest\fR\fR
  36 .ad
  37 .RS 15n
  38 Pointer to bulk transfer request.
  39 .RE
  40
  41 .sp
  42 .ne 2
  43 .na
  44 \fB\fIflags\fR\fR
  45 .ad
  46 .RS 15n
  47 USB_FLAGS_SLEEP is the only flag recognized. Wait for request to complete.
  48 .RE
  49
  50 .SH DESCRIPTION
  51 .LP
  52 The \fBusb_pipe_bulk_xfer()\fR function requests the USBA framework to perform
  53 a transfer through a USB bulk pipe. The request is passed to the host
  54 controller driver (HCD), which performs the necessary transactions to complete
  55 the request. Requests are synchronous when USB_FLAGS_SLEEP has been specified
  56 in flags. Calls for synchronous requests will not return until their
  57 transaction has completed. Asynchronous requests (made without specifying the
  58 USB_FLAGS_SLEEP flag) notify the caller of their completion via a callback
  59 function.
  60 .sp
  61 .LP
  62 Requests for bulk transfers must have mblks attached to store data. Allocate an
  63 mblk for data when a request is allocated via \fBusb_alloc_bulk_req\fR(9F) by
  64 passing a non-negative value for the \fIlen\fR argument.
  65 .SH RETURN VALUES
  66 .ne 2
  67 .na
  68 \fBUSB_SUCCESS\fR
  69 .ad
  70 .RS 25n
  71 Transfer was successful.
  72 .RE
  73
  74 .sp
  75 .ne 2
  76 .na
  77 \fBUSB_INVALID_ARGS\fR
  78 .ad
  79 .RS 25n
  80 Request is \fBNULL\fR.
  81 .RE
  82
  83 .sp
  84 .ne 2
  85 .na
  86 \fBUSB_INVALID_CONTEXT\fR
  87 .ad
  88 .RS 25n
  89 Called from interrupt context with the USB_FLAGS_SLEEP flag set.
  90 .RE
  91
  92 .sp
  93 .ne 2
  94 .na
  95 \fBUSB_INVALID_REQUEST\fR
  96 .ad
  97 .RS 25n
  98 The request has been freed or otherwise invalidated.
  99 .sp
 100 A set of conflicting attributes were specified. See \fBusb_bulk_request\fR(9S).
 101 .sp
 102 The normal and/or exception callback was NULL and USB_FLAGS_SLEEP was not set.
 103 .sp
 104 Data space is not provided to a non-zero length bulk request:
 105 .sp
 106 .in +2
 107 .nf
 108 (bulk_data == NULL and bulk_len != 0)
 109 .fi
 110 .in -2
 111
 112 .RE
 113
 114 .sp
 115 .ne 2
 116 .na
 117 \fBUSB_INVALID_PIPE\fR
 118 .ad
 119 .RS 25n
 120 Pipe handle is NULL or invalid.
 121 .sp
 122 Pipe is closing or closed.
 123 .RE
 124
 125 .sp
 126 .ne 2
 127 .na
 128 \fBUSB_PIPE_ERROR\fR
 129 .ad
 130 .RS 25n
 131 Pipe handle refers to a pipe which is in the USB_PIPE_STATE_ERROR state.
 132 .RE
 133
 134 .sp
 135 .ne 2
 136 .na
 137 \fBUSB_NO_RESOURCES\fR
 138 .ad
 139 .RS 25n
 140 Memory, descriptors or other resources are unavailable.
 141 .RE
 142
 143 .sp
 144 .ne 2
 145 .na
 146 \fBUSB_HC_HARDWARE_ERROR\fR
 147 .ad
 148 .RS 25n
 149 Host controller is in error state.
 150 .RE
 151
 152 .sp
 153 .ne 2
 154 .na
 155 \fBUSB_FAILURE\fR
 156 .ad
 157 .RS 25n
 158 An asynchronous transfer failed or an internal error occurred.
 159 .sp
 160 A bulk request requested too much data:
 161 .sp
 162 .in +2
 163 .nf
 164 (length > usb_get_max_bulk_xfer size())
 165 .fi
 166 .in -2
 167
 168 The pipe is in a unsuitable state (error, busy, not ready).
 169 .RE
 170
 171 .sp
 172 .LP
 173 Additional status information may be available in the bulk_completion_reason
 174 and bulk_cb_flags fields of the request. Please see
 175 \fBusb_completion_reason\fR(9S) and \fBusb_callback_flags\fR(9S) for more
 176 information.
 177 .SH CONTEXT
 178 .LP
 179 May be called from kernel or user context without regard to arguments. May be
 180 called from interrupt context only when the USB_FLAGS_SLEEP flag is clear.
 181 .SH EXAMPLES
 182 .in +2
 183 .nf
 184    /* Allocate, initialize and issue a synchronous bulk request. */
 185
 186     usb_bulk_req_t bulk_req;
 187     mblk_t *mblk;
 188
 189     bulk_req = usb_alloc_bulk_req(dip, bp->b_bcount, USB_FLAGS_SLEEP);
 190
 191     bulk_req->bulk_attributes   = USB_ATTRS_AUTOCLEARING;
 192     mblk = bulk_req->bulk_data;
 193     bcopy(buffer, mblk->b_wptr, bp->b_bcount);
 194     mblk->b_wptr += bp->b_bcount;
 195
 196     if ((rval = usb_pipe_bulk_xfer(pipe, bulk_req, USB_FLAGS_SLEEP))
 197         != USB_SUCCESS) {
 198             cmn_err (CE_WARN, "%s%d: Error writing bulk data.",
 199                 ddi_driver_name(dip), ddi_get_instance(dip));
 200     }
 201
 202 .fi
 203 .in -2
 204
 205 .SH ATTRIBUTES
 206 .LP
 207 See \fBattributes\fR(5) for descriptions of the following attributes:
 208 .sp
 209
 210 .sp
 211 .TS
 212 box;
 213 c | c
 214 l | l .
 215 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 216 _
 217 Architecture    PCI-based systems
 218 _
 219 Interface stability     Committed
 220 .TE
 221
 222 .SH SEE ALSO
 223 .LP
 224 \fBattributes\fR(5), \fBusb_alloc_request\fR(9F), \fBusb_get_cfg\fR(9F),
 225 \fBusb_get_status\fR(9F), \fBusb_pipe_ctrl_xfer\fR(9F),
 226 \fBusb_pipe_get_state\fR(9F), \fBusb_pipe_intr_xfer\fR(9F),
 227 \fBusb_pipe_isoc_xfer\fR(9F), \fBusb_pipe_xopen\fR(9F),
 228 \fBusb_pipe_reset\fR(9F), \fBusb_bulk_request\fR(9S),
 229 \fBusb_callback_flags\fR(9S), \fBusb_completion_reason\fR(9S),
 230 \fBusb_ctrl_request\fR(9S), \fBusb_intr_request\fR(9S),
 231 \fBusb_isoc_request\fR(9S)