usr/src/man/man9f/usb_client_attach.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_CLIENT_ATTACH 9F "Oct 30, 2016"
   8 .SH NAME
   9 usb_client_attach, usb_client_detach \- USBA framework registration of client
  10 USB drivers
  11 .SH SYNOPSIS
  12 .LP
  13 .nf
  14 #define USBDRV_MAJOR_VER    <major>
  15 #define USBDRV_MINOR_VER    <minor>
  16 #include <sys/usb/usba.h>
  17
  18
  19
  20 \fBint\fR \fBusb_client_attach\fR(\fBdev_info_t *\fR\fIdip\fR,
  21     \fBuint_t\fR \fIversion\fR, \fBusb_flags_t\fR \fIflags\fR);
  22 .fi
  23
  24 .LP
  25 .nf
  26 \fBvoid\fR \fBusb_client_detach\fR(\fBdev_info_t *\fR\fIdip\fR,
  27     \fBusb_client_dev_data_t *\fR\fIdev_data\fR);
  28 .fi
  29
  30 .SH INTERFACE LEVEL
  31 .LP
  32 Solaris DDI specific (Solaris DDI)
  33 .SH PARAMETERS
  34 .LP
  35 For \fBusb_client_attach()\fR:
  36 .sp
  37 .ne 2
  38 .na
  39 \fB\fIdip\fR\fR
  40 .ad
  41 .RS 11n
  42 Pointer to the device's dev_info structure.
  43 .RE
  44
  45 .sp
  46 .ne 2
  47 .na
  48 \fB\fIversion\fR\fR
  49 .ad
  50 .RS 11n
  51 Must be set to USBDRV_VERSION. (See below.)
  52 .RE
  53
  54 .sp
  55 .ne 2
  56 .na
  57 \fB\fIflags\fR\fR
  58 .ad
  59 .RS 11n
  60 Not used.
  61 .RE
  62
  63 .sp
  64 .LP
  65 For \fBusb_client_detach()\fR:
  66 .sp
  67 .ne 2
  68 .na
  69 \fB\fIdip\fR\fR
  70 .ad
  71 .RS 12n
  72 Pointer to the device's dev_info structure.
  73 .RE
  74
  75 .sp
  76 .ne 2
  77 .na
  78 \fB\fIdev_data\fR\fR
  79 .ad
  80 .RS 12n
  81 Pointer to a usb_client_dev_data_t to free. Can be NULL.
  82 .RE
  83
  84 .SH DESCRIPTION
  85 .LP
  86 The \fBusb_client_attach()\fR function registers a driver with the USBA
  87 framework and must be called before any other USBA function. Usually,
  88 \fBusb_client_attach()\fR is followed by a call to \fBusb_get_dev_data\fR(9F).
  89 .sp
  90 .LP
  91 The \fBusb_client_detach()\fR function unregisters a driver with the USBA
  92 framework. The \fBusb_client_detach()\fR function releases memory for all
  93 strings, descriptors and trees set up by \fBusb_get_dev_data\fR(9F) when its
  94 dev_data argument is non-NULL.  The \fBusb_client_detach()\fR function is the
  95 last USBA function a client calls before completing \fBdetach\fR(9E). It is not
  96 necessary to call \fBusb_client_detach()\fR during a suspend operation.
  97 .SS "VERSIONING"
  98 .LP
  99 USBDRV_VERSION is a macro which creates a version number based on the
 100 USBDRV_MAJOR_VER and USBDRV_MINOR_VER definitions. It must be passed as the
 101 version argument.
 102 .sp
 103 .LP
 104 For drivers version 2.0 or greater, the value of USBDRV_MAJOR_VERSION must
 105 match its corresponding USBA_MAJOR_VER value in <\fBsys/usb/usbai.h\fR>, and
 106 the value of USBDRV_MINOR_VERSION must not be greater than its corresponding
 107 USBA_MINOR_VER value also in <sys/usb/usbai.h>.
 108 .sp
 109 .LP
 110 Version 0.8 drivers from previous releases are binary compatible and run on
 111 illumos, but are not compilable.
 112 .sp
 113 .LP
 114 Definitions of USBDRV_MAJOR_VERSION and USBDRV_MINOR_VERSION must appear in the
 115 client driver above the reference to <\fBsys/usb/usba.h\fR>. Note that
 116 different releases have different USBA_[MAJOR|MINOR]_VER numbers.
 117 .SH RETURN VALUES
 118 .LP
 119 For \fBusb_client_attach()\fR:
 120 .sp
 121 .ne 2
 122 .na
 123 \fBUSB_SUCCESS\fR
 124 .ad
 125 .RS 23n
 126 Registration is successful.
 127 .RE
 128
 129 .sp
 130 .ne 2
 131 .na
 132 \fBUSB_INVALID_ARGS\fR
 133 .ad
 134 .RS 23n
 135 \fIdip\fR is \fBNULL\fR.
 136 .RE
 137
 138 .sp
 139 .ne 2
 140 .na
 141 \fBUSB_INVALID_CONTEXT\fR
 142 .ad
 143 .RS 23n
 144 Called from interrupt context. Not called from an attach routine context.
 145 .RE
 146
 147 .sp
 148 .ne 2
 149 .na
 150 \fBUSB_INVALID_VERSION\fR
 151 .ad
 152 .RS 23n
 153 Version passed in version is invalid.
 154 .RE
 155
 156 .sp
 157 .ne 2
 158 .na
 159 \fBUSB_FAILURE\fR
 160 .ad
 161 .RS 23n
 162 Other internal error.
 163 .RE
 164
 165 .sp
 166 .LP
 167 For \fBusb_client_detach()\fR:
 168 .sp
 169 .ne 2
 170 .na
 171 \fBUSB_INVALID_ARGS\fR
 172 .ad
 173 .RS 23n
 174 \fIdip\fR is \fBNULL\fR.
 175 .RE
 176
 177 .sp
 178 .ne 2
 179 .na
 180 \fBUSB_INVALID_CONTEXT\fR
 181 .ad
 182 .RS 23n
 183 Not called from an attach routine context.
 184 .RE
 185
 186 .SH CONTEXT
 187 .LP
 188 The \fBusb_client_attach()\fR function may only be called from
 189 \fBattach\fR(9E).
 190 .sp
 191 .LP
 192 The \fBusb_client_detach()\fR function may be called only from \fBattach\fR(9E)
 193 or \fBdetach\fR(9E).
 194 .SH EXAMPLES
 195 .in +2
 196 .nf
 197   if (usb_client_attach(dip, USBDRV_VERSION, 0) != USB_SUCCESS) {
 198             cmn_err (CE_WARN, "%s%d: Couldn't register USB device",
 199                 ddi_driver_name(dip), ddi_get_instance(dip));
 200
 201            return (USB_FAILURE);
 202    }
 203
 204    if (usb_get_dev_data(dip, &dev_data, USB_PARSE_LVL_IF, 0) !=
 205        USB_SUCCESS) {
 206            cmn_err (CE_WARN, "%s%d: Couldn't get device descriptor data.",
 207                ddi_driver_name(dip), ddi_get_instance(dip));
 208
 209            return (USB_FAILURE);
 210    }
 211
 212 .fi
 213 .in -2
 214
 215 .SH ATTRIBUTES
 216 .LP
 217 See \fBattributes\fR(5) for descriptions of the following attributes:
 218 .sp
 219
 220 .sp
 221 .TS
 222 box;
 223 c | c
 224 l | l .
 225 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 226 _
 227 Architecture    PCI-based systems
 228 _
 229 Interface stability     Committed
 230 .TE
 231
 232 .SH SEE ALSO
 233 .LP
 234 \fBattributes\fR(5), \fBattach\fR(9E), \fBdetach\fR(9E),
 235 \fBusb_get_dev_data\fR(9F)