USB_CLIENT_ATTACH(9F) Kernel Functions for Drivers USB_CLIENT_ATTACH(9F)

NAME


usb_client_attach, usb_client_detach - USBA framework registration of
client USB drivers

SYNOPSIS


#define USBDRV_MAJOR_VER <major>
#define USBDRV_MINOR_VER <minor>
#include <sys/usb/usba.h>


int usb_client_attach(dev_info_t *dip,
uint_t version, usb_flags_t flags);


void usb_client_detach(dev_info_t *dip,
usb_client_dev_data_t *dev_data);


INTERFACE LEVEL


illumos DDI specific (illumos DDI)

PARAMETERS


For usb_client_attach():

dip
Pointer to the device's dev_info structure.


version
Must be set to USBDRV_VERSION. (See below.)


flags
Not used.


For usb_client_detach():

dip
Pointer to the device's dev_info structure.


dev_data
Pointer to a usb_client_dev_data_t to free. Can be NULL.


DESCRIPTION


The usb_client_attach() function registers a driver with the USBA
framework and must be called before any other USBA function. Usually,
usb_client_attach() is followed by a call to usb_get_dev_data(9F).


The usb_client_detach() function unregisters a driver with the USBA
framework. The usb_client_detach() function releases memory for all
strings, descriptors and trees set up by usb_get_dev_data(9F) when its
dev_data argument is non-NULL. The usb_client_detach() function is the
last USBA function a client calls before completing detach(9E). It is not
necessary to call usb_client_detach() during a suspend operation.

VERSIONING


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.


For drivers version 2.0 or greater, the value of USBDRV_MAJOR_VERSION
must match its corresponding USBA_MAJOR_VER value in <sys/usb/usbai.h>,
and the value of USBDRV_MINOR_VERSION must not be greater than its
corresponding USBA_MINOR_VER value also in <sys/usb/usbai.h>.


Version 0.8 drivers from previous releases are binary compatible and run
on illumos, but are not compilable.


Definitions of USBDRV_MAJOR_VERSION and USBDRV_MINOR_VERSION must appear
in the client driver above the reference to <sys/usb/usba.h>. Note that
different releases have different USBA_[MAJOR|MINOR]_VER numbers.

RETURN VALUES


For usb_client_attach():

USB_SUCCESS
Registration is successful.


USB_INVALID_ARGS
dip is NULL.


USB_INVALID_CONTEXT
Called from interrupt context. Not called from an
attach routine context.


USB_INVALID_VERSION
Version passed in version is invalid.


USB_FAILURE
Other internal error.


For usb_client_detach():

USB_INVALID_ARGS
dip is NULL.


USB_INVALID_CONTEXT
Not called from an attach routine context.


CONTEXT


The usb_client_attach() function may only be called from attach(9E).


The usb_client_detach() function may be called only from attach(9E) or
detach(9E).

EXAMPLES


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);
}


ATTRIBUTES


See attributes(7) for descriptions of the following attributes:


+--------------------+-------------------+
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
+--------------------+-------------------+
|Architecture | PCI-based systems |
+--------------------+-------------------+
|Interface stability | Committed |
+--------------------+-------------------+

SEE ALSO


attributes(7), attach(9E), detach(9E), usb_get_dev_data(9F)

illumos October 30, 2016 USB_CLIENT_ATTACH(9F)