usr/src/man/man9f/usb_get_status.9f

   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_GET_STATUS 9F "Jan 5, 2004"
   7 .SH NAME
   8 usb_get_status \- Get status of a USB device/endpoint/interface
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 #include <sys/usb/usba.h>
  13
  14
  15
  16 \fBint\fR \fBusb_get_status\fR(\fBdev_info_t *\fR\fIdip\fR, \fBusb_pipe_handle_t\fR \fIpipe_handle\fR,
  17      \fBuint_t\fR \fIrequest_type\fR, \fBuint_t\fR \fIwhich\fR, \fBuint16_t *\fR\fIstatus\fR,
  18      \fBusb_flags_t\fR \fIflags\fR);
  19 .fi
  20
  21 .SH INTERFACE LEVEL
  22 .sp
  23 .LP
  24 Solaris DDI specific (Solaris DDI)
  25 .SH PARAMETERS
  26 .sp
  27 .ne 2
  28 .na
  29 \fB\fIdip\fR\fR
  30 .ad
  31 .RS 16n
  32 Pointer to device's dev_info structure.
  33 .RE
  34
  35 .sp
  36 .ne 2
  37 .na
  38 \fB\fIpipe_handle\fR\fR
  39 .ad
  40 .RS 16n
  41 Default control pipe handle on which request is made.
  42 .RE
  43
  44 .sp
  45 .ne 2
  46 .na
  47 \fB\fIrequest_type\fR\fR
  48 .ad
  49 .RS 16n
  50 bmRequestType. Either:
  51 .sp
  52 USB_DEV_REQ_RCPT_DEV \(em Get device status.
  53 .sp
  54 USB_DEV_REQ_RCPT_IF \(em Get interface status.
  55 .sp
  56 USB_DEV_REQ_RCPT_EP \(em Get endpoint status.
  57 .RE
  58
  59 .sp
  60 .ne 2
  61 .na
  62 \fB\fIwhich\fR\fR
  63 .ad
  64 .RS 16n
  65 Device, interface or endpoint from which to get status.  Either  number of
  66 interface or endpoint, or  0 if device status requested.
  67 .RE
  68
  69 .sp
  70 .ne 2
  71 .na
  72 \fB\fIstatus\fR\fR
  73 .ad
  74 .RS 16n
  75 Address into which the status is written.
  76 .RE
  77
  78 .sp
  79 .ne 2
  80 .na
  81 \fB\fIflags\fR\fR
  82 .ad
  83 .RS 16n
  84 None are recognized.
  85 .RE
  86
  87 .SH DESCRIPTION
  88 .sp
  89 .LP
  90 The \fBusb_get_status()\fR function returns the status of a device, interface
  91 or endpoint.  All status requests use the default control pipe. Length of data
  92 returned is USB_GET_STATUS_LEN bytes.  Always block and wait for resources if
  93 not available, regardless of the flags argument.
  94 .sp
  95 .LP
  96 When the \fIrequest_type\fR recipient is USB_DEV_REQ_RCPT_DEV, device status is
  97 requested. Status returned includes bits for USB_DEV_SLF_PWRD_STATUS (device is
  98 currently  self-powered) and USB_DEV_RWAKEUP_STATUS (device has remote  wakeup
  99 enabled). A set bit indicates the corresponding status.
 100 .sp
 101 .LP
 102 When the \fIrequest_type\fR is USB_DEV_REQ_RCPT_EP, endpoint status is
 103 requested. Status returned includes bits for USB_EP_HALT_STATUS (endpoint is
 104 halted). A set bit indicates the corresponding status.
 105 .sp
 106 .LP
 107 When the \fIrequest_type\fR is USB_DEV_REQ_RCPT_IF, interface status is
 108 requested and USB_IF_STATUS (zero) is returned.
 109 .SH RETURN VALUES
 110 .sp
 111 .ne 2
 112 .na
 113 \fBUSB_SUCCESS\fR
 114 .ad
 115 .RS 20n
 116 Status returned successfully in the status argument.
 117 .RE
 118
 119 .sp
 120 .ne 2
 121 .na
 122 \fBUSB_INVALID_ARGS\fR
 123 .ad
 124 .RS 20n
 125 Status pointer and/or dip argument is NULL.
 126 .RE
 127
 128 .sp
 129 .ne 2
 130 .na
 131 \fBUSB_INVALID_PIPE\fR
 132 .ad
 133 .RS 20n
 134 Pipe handle is NULL.
 135 .RE
 136
 137 .sp
 138 .ne 2
 139 .na
 140 \fBUSB_FAILURE\fR
 141 .ad
 142 .RS 20n
 143 Status not returned successfully.
 144 .RE
 145
 146 .SH CONTEXT
 147 .sp
 148 .LP
 149 May be called from user or kernel context.
 150 .SH EXAMPLES
 151 .sp
 152 .in +2
 153 .nf
 154   uint16_t status;
 155
 156   if (usb_get_status(
 157       dip, pipe_handle, USB_DEV_REQ_RCPT_DEV, 0 &status, 0) ==
 158       USB_SUCCESS) {
 159           if (status & USB_DEV_SLF_PWRD_STATUS) {
 160                   cmn_err (CE_WARN,
 161                       "%s%d: USB device is running on its own power.",
 162                       ddi_driver_name(dip), ddi_get_instance(dip));
 163           }
 164   }
 165 .fi
 166 .in -2
 167
 168 .SH ATTRIBUTES
 169 .sp
 170 .LP
 171 See \fBattributes\fR(5) for descriptions of the following attributes:
 172 .sp
 173
 174 .sp
 175 .TS
 176 box;
 177 c | c
 178 l | l .
 179 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 180 _
 181 Architecture    PCI-based systems
 182 _
 183 Interface stability     Committed
 184 .TE
 185
 186 .SH SEE ALSO
 187 .sp
 188 .LP
 189 \fBattributes\fR(5), \fBusb_clr_feature\fR(9F), \fBusb_get_alt_if\fR(9F),
 190 \fBusb_pipe_get_state\fR(9F), \fBusb_get_cfg\fR(9F),