share/man/man9f/usb_clr_feature.9f

   1 '\" te
   2 .\" Copyright (c) 2004, Sun Microsystems, Inc.,
   3 .\" All Rights Reserved
   4 .\" 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.
   5 .\" 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.
   6 .\" 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]
   7 .TH USB_CLR_FEATURE 9F "Feb 9, 2004"
   8 .SH NAME
   9 usb_clr_feature \- Clear feature of USB device, interface or endpoint
  10 .SH SYNOPSIS
  11 .LP
  12 .nf
  13 #include <sys/usb/usba.h>
  14
  15
  16
  17 \fBint\fR \fBusb_clr_feature\fR(\fBdev_info_t *\fR\fIdip\fR,
  18      \fBuint_t\fR \fIrequest_type\fR, \fBuint_t\fR \fIfeature\fR,
  19      \fBuint_t\fR \fIwhich\fR, \fBusb_flags_t\fR \fIflags\fR,
  20      \fBvoid (\fR\fI*callback)\fR (usb_pipe_handle_t \fIpipe_handle\fR,
  21      \fBusb_opaque_t\fR \fIcallback_arg\fR, \fBint\fR \fIrval\fR, \fBusb_cb_flags_t\fR \fIflags)\fR,
  22      \fBusb_opaque_t\fR \fIcallback_arg\fR);
  23 .fi
  24
  25 .SH INTERFACE LEVEL
  26 .sp
  27 .LP
  28 Solaris DDI specific (Solaris DDI)
  29 .SH PARAMETERS
  30 .sp
  31 .ne 2
  32 .na
  33 \fB\fIdip\fR\fR
  34 .ad
  35 .RS 16n
  36 Pointer to the device's dev_info structure.
  37 .RE
  38
  39 .sp
  40 .ne 2
  41 .na
  42 \fB\fIpipe_handle\fR\fR
  43 .ad
  44 .RS 16n
  45 Pipe handle to device, device interface or endpoint.
  46 .RE
  47
  48 .sp
  49 .ne 2
  50 .na
  51 \fB\fIrequest_type\fR\fR
  52 .ad
  53 .RS 16n
  54 bmRequestType to be used.  One of the following:
  55 .sp
  56 USB_DEV_REQ_RCPT_DEV - Clear feature on device.
  57 .sp
  58 USB_DEV_REQ_RCPT_IF - Clear feature on interface.
  59 .sp
  60 USB_DEV_REQ_RCPT_EP - Clear feature on endpoint.
  61 .RE
  62
  63 .sp
  64 .ne 2
  65 .na
  66 \fB\fIfeature\fR\fR
  67 .ad
  68 .RS 16n
  69 Feature to be cleared. Can be any device-defined device-, interface-, or
  70 endpoint-specific feature, including the following which are defined in the
  71 \fIUSB 2.0\fR specification:
  72 .sp
  73 USB_EP_HALT - Clear a HALT on an endpoint.
  74 .sp
  75 USB_DEV_REMOTE_WAKEUP - Clear REMOTE_WAKEUP on a device.
  76 .sp
  77 USB_DEV_TEST_MODE - Clear TEST_MODE on a device.
  78 .RE
  79
  80 .sp
  81 .ne 2
  82 .na
  83 \fBwhich\fR
  84 .ad
  85 .RS 9n
  86 Device, interface or endpoint on which to  clear the feature. One of:
  87 .br
  88 .in +2
  89 Interface number, for interfaces.
  90 .in -2
  91 .br
  92 .in +2
  93 Endpoint number, for endpoints.
  94 .in -2
  95 .br
  96 .in +2
  97 0 for devices.
  98 .in -2
  99 .RE
 100
 101 .sp
 102 .ne 2
 103 .na
 104 \fBflags\fR
 105 .ad
 106 .RS 16n
 107 USB_FLAGS_SLEEP is the only flag recognized. Wait for completion and do not
 108 call callback.
 109 .RE
 110
 111 .sp
 112 .ne 2
 113 .na
 114 \fBcallback\fR
 115 .ad
 116 .RS 16n
 117 Callback handler to notify of asynchronous completion.
 118 .RE
 119
 120 .sp
 121 .ne 2
 122 .na
 123 \fBcallback_arg\fR
 124 .ad
 125 .RS 16n
 126 Second argument passed to callback handler.
 127 .RE
 128
 129 .SH DESCRIPTION
 130 .sp
 131 .LP
 132 The \fBusb_clr_feature()\fR function clears a specific feature of a device,
 133 interface or endpoint. This function always blocks and waits for resources if
 134 not available, regardless of the flags argument.
 135 .sp
 136 .LP
 137 This call blocks for completion if USB_FLAGS_SLEEP is set in flags. It returns
 138 immediately and calls the callback upon completion if USB_FLAGS_SLEEP is not
 139 set.
 140 .SH RETURN VALUES
 141 .sp
 142 .ne 2
 143 .na
 144 \fBUSB_SUCCESS\fR
 145 .ad
 146 .RS 23n
 147 Feature was successfully cleared.
 148 .RE
 149
 150 .sp
 151 .ne 2
 152 .na
 153 \fBUSB_INVALID_ARGS\fR
 154 .ad
 155 .RS 23n
 156 \fIdip\fR argument is NULL.
 157 .RE
 158
 159 .sp
 160 .ne 2
 161 .na
 162 \fBUSB_INVALID_PIPE\fR
 163 .ad
 164 .RS 23n
 165 \fIpipe_handle\fR argument is NULL
 166 .RE
 167
 168 .sp
 169 .ne 2
 170 .na
 171 \fBUSB_INVALID_CONTEXT\fR
 172 .ad
 173 .RS 23n
 174 Called from interrupt context with USB_FLAGS_SLEEP flag set.
 175 .RE
 176
 177 .sp
 178 .ne 2
 179 .na
 180 \fBUSB_FAILURE\fR
 181 .ad
 182 .RS 23n
 183 Clearing of feature was unsuccessful.
 184 .RE
 185
 186 .SH CONTEXT
 187 .sp
 188 .LP
 189 May always be called from user or kernel context. May be called from interrupt
 190 context only if USB_FLAGS_SLEEP is not set in flags.
 191 .sp
 192 .LP
 193 If the USB_CB_ASYNC_REQ_FAILED bit is clear in usb_cb_flags_t, the callback, if
 194 supplied, can block because it is executing in  kernel context. Otherwise the
 195 callback cannot block. Please see \fBusb_callback_flags\fR(9S) for more
 196 information on callbacks.
 197 .SH EXAMPLES
 198 .sp
 199 .in +2
 200 .nf
 201 if (usb_clr_feature(dip, pipe_handle, USB_DEV_REQ_RCPT_EP,
 202        USB_EP_HALT, data_endpoint_num, 0) == USB_FAILURE) {
 203            cmn_err (CE_WARN,
 204                "%s%d: Error clearing halt condition on data endpoint %d.",
 205                ddi_driver_name(dip), ddi_get_instance(dip),
 206                data_endpoint_num);
 207    }
 208
 209 .fi
 210 .in -2
 211
 212 .SH ATTRIBUTES
 213 .sp
 214 .LP
 215 See \fBattributes\fR(5) for descriptions of the following attributes:
 216 .sp
 217
 218 .sp
 219 .TS
 220 box;
 221 c | c
 222 l | l .
 223 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 224 _
 225 Architecture    PCI-based systems
 226 _
 227 Interface stability     Committed
 228 .TE
 229
 230 .SH SEE ALSO
 231 .sp
 232 .LP
 233 \fBattributes\fR(5), \fBusb_get_status\fR(9F), \fBusb_pipe_reset\fR(9F),
 234 \fBusb_pipe_get_state\fR(9F), \fBusb_callback_flags\fR(9S)