usr/src/man/man9s/usb_ctrl_req.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_CTRL_REQUEST 9S "Jan 5, 2004"
   7 .SH NAME
   8 usb_ctrl_req, usb_ctrl_req_t, usb_ctrl_request \- USB control pipe request structure
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 #include <sys/usb/usba.h>
  13 .fi
  14
  15 .SH INTERFACE LEVEL
  16 .LP
  17 Solaris DDI specific (Solaris DDI)
  18 .SH DESCRIPTION
  19 .LP
  20 A control request is used to send device commands (or requests) and to read
  21 status. Please refer to Section\fI 5.5\fR of the \fIUSB 2.0\fR specification
  22 for information on control pipes. For information on formatting requests, see
  23 Section \fI9.3\fR of the \fIUSB 2.0\fR specification. The USB 2.0 specification
  24 is available at \fIwww.usb.org\fR.
  25 .SH STRUCTURE MEMBERS
  26 .LP
  27 The fields in the usb_ctrl_req_t are used to format a control request:
  28 .sp
  29 .in +2
  30 .nf
  31   uint8_t      ctrl_bmRequestType; /* characteristics of request */
  32   uint8_t      ctrl_bRequest;  /* specific request             */
  33   uint16_t     ctrl_wValue;    /* varies according to request  */
  34   uint16_t     ctrl_wIndex;    /* index or offset              */
  35   uint16_t     ctrl_wLength;   /* number of bytes to xfer      */
  36   mblk_t       *ctrl_data;     /* data for the data phase  */
  37                                /* IN or OUT: allocated by client */
  38   uint_t       ctrl_timeout;   /* time until  USBA framework */
  39                                /* retires req, in seconds */
  40                                /* If set to zero, defaults to 5 sec */
  41   usb_opaque_t    ctrl_client_private; /* client private info */
  42   usb_req_attrs_t ctrl_attributes; /* attrib. for this req */
  43
  44   /* Normal callback function, called upon completion. */
  45   void       (*ctrl_cb)(
  46                  usb_pipe_handle_t ph, struct usb_ctrl_req *req);
  47
  48   /* Exception callback function, for error handling. */
  49   void       (*ctrl_exc_cb)(
  50                  usb_pipe_handle_t ph, struct usb_ctrl_req *req);
  51   usb_cr_t   ctrl_completion_reason; /* overall success status */
  52                                   /* See usb_completion_reason(9S) */
  53   usb_cb_flags_t  ctrl_cb_flags; /* recovery done by callback hndlr */
  54                                 /* See \fBusb_callback_flags(9S)\fR */
  55 .fi
  56 .in -2
  57
  58 .sp
  59 .LP
  60 Request attributes define special handling for transfers. The following
  61 attributes are valid for control requests:
  62 .sp
  63 .ne 2
  64 .na
  65 \fBUSB_ATTRS_SHORT_XFER_OK\fR
  66 .ad
  67 .RS 27n
  68 Accept transfers where less data is received than expected.
  69 .RE
  70
  71 .sp
  72 .ne 2
  73 .na
  74 \fBUSB_ATTRS_AUTOCLEARING\fR
  75 .ad
  76 .RS 27n
  77 Have USB framework reset pipe and clear functional stalls automatically on
  78 exception.
  79 .RE
  80
  81 .sp
  82 .ne 2
  83 .na
  84 \fBUSB_ATTRS_PIPE_RESET\fR
  85 .ad
  86 .RS 27n
  87 Have USB framework reset pipe automatically on exception.
  88 .RE
  89
  90 .sp
  91 .LP
  92 Please see \fBusb_request_attributes\fR(9S) for more information.
  93 .sp
  94 .LP
  95 The following definitions directly pertain to fields in the USB control request
  96 structure. (See Section \fI 9.3\fR of the \fIUSB 2.0\fR specification.)
  97 .sp
  98 .in +2
  99 .nf
 100 Direction bitmasks of a control request's ctrl_bmRequestType field
 101 (USB 2.0 spec, section 9.3.1)
 102
 103      USB_DEV_REQ_HOST_TO_DEV     | Host to device direction
 104      USB_DEV_REQ_DEV_TO_HOST     | Device to host direction
 105      USB_DEV_REQ_DIR_MASK        | Bitmask of direction bits
 106
 107 Request type bitmasks of a control request's ctrl_bmRequestType field
 108 (USB 2.0 spec, section 9.3.1)
 109
 110      USB_DEV_REQ_TYPE_STANDARD   | USB 2.0 defined command
 111                                  | for all USB devices
 112      USB_DEV_REQ_TYPE_CLASS      | USB 2.0 defined
 113                                  | class-specific command
 114      USB_DEV_REQ_TYPE_VENDOR     | Vendor-specific command
 115      USB_DEV_REQ_TYPE_MASK       | Bitmask of request type bits
 116
 117 Recipient bitmasks of a control request's ctrl_bmRequestType field
 118 (USB 2.0 spec, section 9.3.1)
 119
 120      USB_DEV_REQ_RCPT_DEV        | Request is for device
 121      USB_DEV_REQ_RCPT_IF         | Request is for interface
 122      USB_DEV_REQ_RCPT_EP         | Request is for endpoint
 123      USB_DEV_REQ_RCPT_OTHER      | Req is for other than above
 124      USB_DEV_REQ_RCPT_MASK       | Bitmask of request recipient bits
 125
 126 Standard requests (USB 2.0 spec, section 9.4)
 127      USB_REQ_GET_STATUS          | Get status of device, endpoint
 128                                  |or interface (9.4.5)
 129      USB_REQ_CLEAR_FEATURE       | Clear feature specified by
 130                                  |wValue field (9.4.1)
 131      USB_REQ_SET_FEATURE         | Set feature specified by
 132                                  |       wValue field (9.4.9)
 133      USB_REQ_SET_ADDRESS         | Set address specified by
 134                                  |       wValue field (9.4.6)
 135      USB_REQ_GET_DESCR           | Get descr for item/idx in
 136                                  |       wValue field (9.4.3)
 137      USB_REQ_SET_DESCR           | Set descr for item/idx in
 138                                  |       wValue field (9.4.8)
 139      USB_REQ_GET_CFG             | Get current device
 140                                  |        configuration (9.4.2)
 141      USB_REQ_SET_CFG             | Set current device
 142                                  |        configuration (9.4.7)
 143      USB_REQ_GET_IF              | Get alternate interface
 144                                  |       setting (9.4.4)
 145      USB_REQ_SET_IF              | Set alternate interface
 146                                  |       setting (9.4.10)
 147      USB_REQ_SYNC_FRAME          | Set and report an endpoint's
 148                                  |       sync frame (9.4.11)
 149
 150 Unicode language ID, used as wIndex for USB_REQ_SET/GET_DESCRIPTOR
 151
 152      USB_LANG_ID                 | Unicode English Lang ID for
 153                                  | parsing str descr
 154 .fi
 155 .in -2
 156
 157 .SH ATTRIBUTES
 158 .LP
 159 See attributes(5) for descriptions of the following attributes:
 160 .sp
 161
 162 .sp
 163 .TS
 164 box;
 165 c | c
 166 l | l .
 167 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 168 _
 169 Architecture    PCI-based systems
 170 _
 171 Interface stability     Committed
 172 .TE
 173
 174 .SH SEE ALSO
 175 .LP
 176 \fBusb_alloc_request\fR(9F), \fBusb_pipe_bulk_xfer\fR(9F),
 177 \fBusb_pipe_ctrl_xfer\fR(9F), \fBusb_pipe_intr_xfer\fR(9F),
 178 \fBusb_pipe_isoc_xfer\fR(9F), \fBusb_bulk_request\fR(9S),
 179 \fBusb_callback_flags\fR(9S), \fBusb_completion_reason\fR(9S),
 180 \fBusb_intr_request\fR(9S), \fBusb_isoc_request\fR(9S),
 181 \fBusb_request_attributes\fR(9S)