Current File : //usr/share/man/man9f/usb_clr_feature.9f

'\" te
.\" Copyright (c) 2004, Sun Microsystems, Inc., All Rights Reserved
.TH usb_clr_feature 9F "Feb 9 2004" "SunOS 5.11" "Kernel Functions for Drivers"
.SH NAME
usb_clr_feature \- Clear feature of USB device, interface or endpoint
.SH SYNOPSIS
.LP
.nf
#include <sys/usb/usba.h>

\fBint\fR \fBusb_clr_feature\fR(\fBdev_info_t *\fR\fIdip\fR, 
     \fBuint_t\fR \fIrequest_type\fR, \fBuint_t\fR \fIfeature\fR,
     \fBuint_t\fR \fIwhich\fR, \fBusb_flags_t\fR \fIflags\fR, 
     \fBvoid (\fR\fI*callback)\fR (usb_pipe_handle_t \fIpipe_handle\fR,
     \fBusb_opaque_t\fR \fIcallback_arg\fR, \fBint\fR \fIrval\fR, \fBusb_cb_flags_t\fR \fIflags)\fR, 
     \fBusb_opaque_t\fR \fIcallback_arg\fR);
.fi

.SH INTERFACE LEVEL
.sp
.LP
Solaris DDI specific (Solaris DDI)
.SH PARAMETERS
.sp
.ne 2
.mk
.na
\fB\fIdip\fR\fR
.ad
.RS 16n
.rt  
Pointer to the device's dev_info structure.
.RE

.sp
.ne 2
.mk
.na
\fB\fIpipe_handle\fR\fR
.ad
.RS 16n
.rt  
Pipe handle to device, device interface or endpoint.
.RE

.sp
.ne 2
.mk
.na
\fB\fIrequest_type\fR\fR
.ad
.RS 16n
.rt  
bmRequestType to be used.  One of the following: 
.sp
USB_DEV_REQ_RCPT_DEV - Clear feature on device.
.sp
USB_DEV_REQ_RCPT_IF - Clear feature on interface.
.sp
USB_DEV_REQ_RCPT_EP - Clear feature on endpoint.
.RE

.sp
.ne 2
.mk
.na
\fB\fIfeature\fR\fR
.ad
.RS 16n
.rt  
Feature to be cleared. Can be any device-defined device-, interface-, or endpoint-specific feature, including the following which are defined in the \fIUSB 2.0\fR specification: 
.sp
USB_EP_HALT - Clear a HALT on an endpoint.
.sp
USB_DEV_REMOTE_WAKEUP - Clear REMOTE_WAKEUP on a device.
.sp
USB_DEV_TEST_MODE - Clear TEST_MODE on a device.
.RE

.sp
.ne 2
.mk
.na
\fBwhich\fR
.ad
.RS 9n
.rt  
Device, interface or endpoint on which to  clear the feature. One of: 
.br
.in +2
Interface number, for interfaces.
.in -2
.br
.in +2
Endpoint number, for endpoints.
.in -2
.br
.in +2
0 for devices.
.in -2
.RE

.sp
.ne 2
.mk
.na
\fBflags\fR
.ad
.RS 16n
.rt  
USB_FLAGS_SLEEP is the only flag recognized. Wait for completion and do not call callback.
.RE

.sp
.ne 2
.mk
.na
\fBcallback\fR
.ad
.RS 16n
.rt  
Callback handler to notify of asynchronous completion.
.RE

.sp
.ne 2
.mk
.na
\fBcallback_arg\fR
.ad
.RS 16n
.rt  
Second argument passed to callback handler.
.RE

.SH DESCRIPTION
.sp
.LP
The \fBusb_clr_feature()\fR function clears a specific feature of a device, interface or endpoint. This function always blocks and waits for resources if not available, regardless of the flags argument.
.sp
.LP
This call blocks for completion if USB_FLAGS_SLEEP is set in flags. It returns immediately and calls the callback upon completion if USB_FLAGS_SLEEP is not set.
.SH RETURN VALUES
.sp
.ne 2
.mk
.na
\fBUSB_SUCCESS\fR
.ad
.RS 23n
.rt  
Feature was successfully cleared.
.RE

.sp
.ne 2
.mk
.na
\fBUSB_INVALID_ARGS\fR
.ad
.RS 23n
.rt  
\fIdip\fR argument is NULL.
.RE

.sp
.ne 2
.mk
.na
\fBUSB_INVALID_PIPE\fR
.ad
.RS 23n
.rt  
\fIpipe_handle\fR argument is NULL
.RE

.sp
.ne 2
.mk
.na
\fBUSB_INVALID_CONTEXT\fR
.ad
.RS 23n
.rt  
Called from interrupt context with USB_FLAGS_SLEEP flag set.
.RE

.sp
.ne 2
.mk
.na
\fBUSB_FAILURE\fR
.ad
.RS 23n
.rt  
Clearing of feature was unsuccessful.
.RE

.SH CONTEXT
.sp
.LP
May always be called from user or kernel context. May be called from interrupt context only if USB_FLAGS_SLEEP is not set in flags.
.sp
.LP
If the USB_CB_ASYNC_REQ_FAILED bit is clear in usb_cb_flags_t, the callback, if supplied, can block because it is executing in  kernel context. Otherwise the callback cannot block. Please see \fBusb_callback_flags\fR(9S) for more information on callbacks.
.SH EXAMPLES
.sp
.in +2
.nf
if (usb_clr_feature(dip, pipe_handle, USB_DEV_REQ_RCPT_EP,
       USB_EP_HALT, data_endpoint_num, 0) == USB_FAILURE) {
           cmn_err (CE_WARN,
               "%s%d: Error clearing halt condition on data endpoint %d.",
               ddi_driver_name(dip), ddi_get_instance(dip),
               data_endpoint_num);
   }
                
.fi
.in -2

.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(5) for descriptions of the following attributes: 
.sp

.sp
.TS
tab() box;
cw(2.75i) |cw(2.75i) 
lw(2.75i) |lw(2.75i) 
.
ATTRIBUTE TYPEATTRIBUTE VALUE
_
ArchitecturePCI-based systems
_
Interface StabilityCommitted
_
Availabilitysystem/io/usb
.TE

.SH SEE ALSO
.sp
.LP
\fBattributes\fR(5), \fBusb_get_status\fR(9F), \fBusb_pipe_reset\fR(9F), \fBusb_pipe_get_state\fR(9F), \fBusb_callback_flags\fR(9S)