share/man/man9s/usb_request_attributes.9s

   1 '\" te
   2 .\" Copyright (c) 2004, 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_REQUEST_ATTRIBUTES 9S "Jan 5, 2004"
   7 .SH NAME
   8 usb_request_attributes \- Definition of USB request attributes
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 #include  <sys/usb/usba.h>
  13 .fi
  14
  15 .SH INTERFACE LEVEL
  16 .sp
  17 .LP
  18 Solaris DDI specific (Solaris DDI)
  19 .SH DESCRIPTION
  20 .sp
  21 .LP
  22 Request attributes specify how the USBA framework handles request execution.
  23 Request attributes are specified in the request's *_attributes field and belong
  24 to the enumerated type usb_req_attrs_t.
  25 .sp
  26 .LP
  27 Supported request attributes are:
  28 .sp
  29 .ne 2
  30 .na
  31 \fBUSB_ATTRS_SHORT_XFER_OK\fR
  32 .ad
  33 .RS 30n
  34 Use this attribute when the  maximum transfer  size is known,  but it is
  35 possible for the request to receive a smaller amount of data. This attribute
  36 tells the USBA framework to accept  without error transfers which are shorter
  37 than expected.
  38 .RE
  39
  40 .sp
  41 .ne 2
  42 .na
  43 \fBUSB_ATTRS_PIPE_RESET\fR
  44 .ad
  45 .RS 30n
  46 Have the USB framework reset the pipe automatically if an error     occurs
  47 during the transfer. Do not attempt to clear any stall. The USB_CB_RESET_PIPE
  48 callback flag is passed to the client driver's exception handler to show the
  49 pipe has been reset. Pending requests on pipes which are reset are flushed
  50 unless the pipe is the default pipe.
  51 .RE
  52
  53 .sp
  54 .ne 2
  55 .na
  56 \fBUSB_ATTRS_AUTOCLEARING\fR
  57 .ad
  58 .RS 30n
  59 Have the USB framework reset the pipe and clear functional stalls automatically
  60 if an error occurs during the transfer. The callback flags passed to the client
  61 driver's exception handler show the status after the attempt to clear the
  62 stall.
  63 .sp
  64 USB_CB_FUNCTIONAL_STALL is set in the callback flags to indicate that a
  65 functional stall occurred. USB_CB_STALL_CLEARED is also set if the stall is
  66 cleared. The default pipe never shows a functional stall if the
  67 USB_ATTRS_AUTOCLEARING attribute is set. If USB_CB_FUNCTIONAL_STALL is seen
  68 when autoclearing is enabled, the device has a fatal error.
  69 .sp
  70 USB_CB_PROTOCOL_STALL is set without USB_CB_STALL_CLEARED in the callback flags
  71 to indicate that a protocol stall was seen but was not explicitly cleared.
  72 Protocol stalls are cleared automatically when a subsequent command is issued.
  73 .sp
  74 Autoclearing a stalled default pipe is not allowed. The USB_CB_PROTOCOL_STALL
  75 callback flag is set in the callback flags to indicate the default pipe is
  76 stalled.
  77 .sp
  78 Autoclearing is not allowed when the request is USB_REQ_GET_STATUS on the
  79 default pipe.
  80 .RE
  81
  82 .sp
  83 .ne 2
  84 .na
  85 \fBUSB_ATTRS_ONE_XFER\fR
  86 .ad
  87 .RS 30n
  88 Applies only to interrupt-IN requests. Without this flag, interrupt-IN requests
  89 start periodic polling of the interrupt pipe. This flag specifies to perform
  90 only a single transfer.  Do not start periodic transfers with this request.
  91 .RE
  92
  93 .sp
  94 .ne 2
  95 .na
  96 \fBUSB_ATTRS_ISOC_START_FRAME\fR
  97 .ad
  98 .RS 30n
  99 Applies only to isochronous requests and specifies that a request be started at
 100 a given frame number. The starting frame number is provided in the
 101 isoc_frame_no field of the usb_isoc_req_t. Please see
 102 \fBusb_isoc_request\fR(9S) for more information about isochronous requests.
 103 .sp
 104 USB_ATTRS_ISOC_START_FRAME can be used to delay a transfer by a few frames,
 105 allowing transfers to an endpoint to sync up with another source.  (For
 106 example, synching up audio endpoints to a video source.) The number of a
 107 suitable starting frame in the near future can be found by adding an offset
 108 number of frames (usually between four and ten) to the current frame number
 109 returned from \fBusb_get_current_frame_number\fR(9F). Note that requests with
 110 starting frames which have passed are rejected.
 111 .RE
 112
 113 .sp
 114 .ne 2
 115 .na
 116 \fBUSB_ATTRS_ISOC_XFER_ASAP\fR
 117 .ad
 118 .RS 30n
 119 Applies only to isochronous requests and specifies that a request start as soon
 120 as possible. The host controller driver picks a starting frame number which
 121 immediately follows the last frame of the last queued request. The
 122 isoc_frame_no of the usb_isoc_req_t is ignored. Please see
 123 \fBusb_isoc_request\fR(9S) for more information about isochronous requests.
 124 .RE
 125
 126 .SH EXAMPLES
 127 .sp
 128 .in +2
 129 .nf
 130     /*
 131      * Allocate, initialize and issue a synchronous bulk-IN request.
 132      * Allow for short transfers.
 133      */
 134
 135     struct buf *bp;
 136     usb_bulk_req_t bulk_req;
 137     mblk_t *mblk;
 138
 139     bulk_req = usb_alloc_bulk_req(dip, bp->b_bcount, USB_FLAGS_SLEEP);
 140
 141     bulk_req->bulk_attributes =
 142         USB_ATTRS_AUTOCLEARING | USB_ATTRS_SHORT_XFER_OK;
 143
 144     if ((rval = usb_pipe_bulk_xfer(pipe, bulk_req, USB_FLAGS_SLEEP)) !=
 145         USB_SUCCESS) {
 146             cmn_err (CE_WARN, "%s%d: Error reading bulk data.",
 147                 ddi_driver_name(dip), ddi_get_instance(dip));
 148     }
 149
 150     mblk = bulk_req->bulk_data;
 151     bcopy(mblk->rptr, buf->b_un.b_addr, mblk->wptr - mblk->rptr);
 152     bp->b_resid = bp->b_count - (mblk->wptr = mblk->rptr);
 153     ...
 154     ...
 155
 156     ----
 157
 158     usb_pipe_handle_t handle;
 159     usb_frame_number_t offset = 10;
 160     usb_isoc_req_t *isoc_req;
 161
 162     isoc_req = usb_alloc_isoc_req(...);
 163       ...
 164       ...
 165     isoc_req->isoc_frame_no = usb_get_current_frame_number(dip) + offset;
 166     isoc_req->isoc_attributes = USB_ATTRS_ISOC_START_FRAME;
 167       ...
 168       ...
 169     if (usb_pipe_isoc_xfer(handle, isoc_req, 0) != USB_SUCCESS) {
 170       ...
 171     }
 172 .fi
 173 .in -2
 174
 175 .SH ATTRIBUTES
 176 .sp
 177 .LP
 178 See attributes(5) for descriptions of the following attributes:
 179 .sp
 180
 181 .sp
 182 .TS
 183 box;
 184 c | c
 185 l | l .
 186 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 187 _
 188 Architecture    PCI-based systems
 189 _
 190 Interface stability     Committed
 191 .TE
 192
 193 .SH SEE ALSO
 194 .sp
 195 .LP
 196 \fBusb_alloc_request\fR(9F), \fBusb_get_current_frame_number\fR(9F),
 197 \fBusb_pipe_bulk_xfer\fR(9F), \fBusb_pipe_ctrl_xfer\fR(9F),
 198 \fBusb_pipe_intr_xfer\fR(9F), \fBusb_pipe_isoc_xfer\fR(9F),
 199 \fBusb_bulk_request\fR(9S), \fBusb_callback_flags\fR(9S),
 200 \fBusb_ctrl_request\fR(9S), \fBusb_intr_request\fR(9S),
 201 \fBusb_isoc_request\fR(9S), \fBusb_completion_reason\fR(9S)