'\" te
.\" Copyright (c) 2004, Sun Microsystems, Inc.,
.\" All Rights Reserved
.\" 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.
.\" 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.
.\" 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]
.TH usb_client_attach 9F "5 Jan 2004" "SunOS 5.11" "Kernel Functions for Drivers"
.SH NAME
usb_client_attach, usb_client_detach \- USBA framework registration of client
USB drivers
.SH SYNOPSIS
.LP
.nf
#define USBDRV_MAJOR_VER    <major>
#define USBDRV_MINOR_VER    <minor>
#include <sys/usb/usba.h>



\fBint\fR \fBusb_client_attach\fR(\fBdev_info_t *\fR\fIdip\fR, 
    \fBuint_t\fR \fIversion\fR, \fBusb_flags_t\fR \fIflags\fR);
.fi

.LP
.nf
\fBvoid\fR \fBusb_client_detach\fR(\fBdev_info_t *\fR\fIdip\fR, 
    \fBusb_client_dev_data_t *\fR\fIdev_data\fR);
.fi

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

.sp
.ne 2
.mk
.na
\fB\fIversion\fR\fR
.ad
.RS 11n
.rt  
Must be set to USBDRV_VERSION. (See below.)
.RE

.sp
.ne 2
.mk
.na
\fB\fIflags\fR\fR
.ad
.RS 11n
.rt  
Not used.
.RE

.sp
.LP
For \fBusb_client_detach()\fR:
.sp
.ne 2
.mk
.na
\fB\fIdip\fR\fR
.ad
.RS 12n
.rt  
Pointer to the device's dev_info structure.
.RE

.sp
.ne 2
.mk
.na
\fB\fIdev_data\fR\fR
.ad
.RS 12n
.rt  
Pointer to a usb_client_dev_data_t to free. Can be NULL.
.RE

.SH DESCRIPTION
.sp
.LP
The \fBusb_client_attach()\fR function registers a driver with the USBA
framework and must be called before any other USBA function. Usually,
\fBusb_client_attach()\fR is followed by a call to \fBusb_get_dev_data\fR(9F).
.sp
.LP
The \fBusb_client_detach()\fR function unregisters a driver with the USBA
framework. The \fBusb_client_detach()\fR function releases memory for all
strings, descriptors and trees set up by \fBusb_get_dev_data\fR(9F) when its
dev_data argument is non-NULL.  The \fBusb_client_detach()\fR function is the
last USBA function a client calls before completing \fBdetach\fR(9E). It is not
necessary to call \fBusb_client_detach()\fR during a suspend operation.
.SS "VERSIONING"
.sp
.LP
USBDRV_VERSION is a macro which creates a version number based on the
USBDRV_MAJOR_VER and USBDRV_MINOR_VER definitions. It must be passed as the
version argument.
.sp
.LP
For drivers version 2.0 or greater, the value of USBDRV_MAJOR_VERSION must
match its corresponding USBA_MAJOR_VER value in <\fBsys/usb/usbai.h\fR>, and
the value of USBDRV_MINOR_VERSION must not be greater than its corresponding
USBA_MINOR_VER value also in <sys/usb/usbai.h>.
.sp
.LP
Version 0.8 drivers from previous releases are binary compatible and run on
Solaris 10, but are not compilable. Version 0.8 binary compatibility will not
be supported in subsequent Solaris OS releases.
.sp
.LP
Definitions of USBDRV_MAJOR_VERSION and USBDRV_MINOR_VERSION must appear in the
client driver above the reference to <\fBsys/usb/usba.h\fR>. Note that
different releases have different USBA_[MAJOR|MINOR]_VER numbers.
.SH RETURN VALUES
.sp
.LP
For \fBusb_client_attach()\fR:
.sp
.ne 2
.mk
.na
\fBUSB_SUCCESS\fR
.ad
.RS 23n
.rt  
Registration is successful.
.RE

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

.sp
.ne 2
.mk
.na
\fBUSB_INVALID_CONTEXT\fR
.ad
.RS 23n
.rt  
Called from interrupt context. Not called from an attach routine context.
.RE

.sp
.ne 2
.mk
.na
\fBUSB_INVALID_VERSION\fR
.ad
.RS 23n
.rt  
Version passed in version is invalid.
.RE

.sp
.ne 2
.mk
.na
\fBUSB_FAILURE\fR
.ad
.RS 23n
.rt  
Other internal error.
.RE

.sp
.LP
For \fBusb_client_detach()\fR:
.sp
.ne 2
.mk
.na
\fBUSB_INVALID_ARGS\fR
.ad
.RS 23n
.rt  
\fIdip\fR is \fBNULL\fR.
.RE

.sp
.ne 2
.mk
.na
\fBUSB_INVALID_CONTEXT\fR
.ad
.RS 23n
.rt  
Not called from an attach routine context.
.RE

.SH CONTEXT
.sp
.LP
The \fBusb_client_attach()\fR function may only be called from
\fBattach\fR(9E).
.sp
.LP
The \fBusb_client_detach()\fR function may be called only from \fBattach\fR(9E)
or \fBdetach\fR(9E).
.SH EXAMPLES
.sp
.in +2
.nf
  if (usb_client_attach(dip, USBDRV_VERSION, 0) != USB_SUCCESS) {
            cmn_err (CE_WARN, "%s%d: Couldn't register USB device",
                ddi_driver_name(dip), ddi_get_instance(dip));
                
           return (USB_FAILURE);
   }

   if (usb_get_dev_data(dip, &dev_data, USB_PARSE_LVL_IF, 0) !=
       USB_SUCCESS) {
           cmn_err (CE_WARN, "%s%d: Couldn't get device descriptor data.",
               ddi_driver_name(dip), ddi_get_instance(dip));

           return (USB_FAILURE);
   }
                
.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
.TE

.SH SEE ALSO
.sp
.LP
\fBattributes\fR(5), \fBattach\fR(9E), \fBdetach\fR(9E),
\fBusb_get_dev_data\fR(9F)