usr/src/man/man9f/usb_register_hotplug_cbs.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_REGISTER_HOTPLUG_CBS 9F "Aug 17, 2004"
   8 .SH NAME
   9 usb_register_hotplug_cbs, usb_unregister_hotplug_cbs \- Register/unregister for
  10 notification of device hotplug events
  11 .SH SYNOPSIS
  12 .LP
  13 .nf
  14 #include <sys/usb/usba.h>
  15
  16
  17
  18 \fB\fR\fBint\fR \fBusb_register_hotplug_cbs\fR(\fBdev_info_t *\fR\fIdip\fR,
  19      \fBint\fR \fI(*disconnection_event_handler)\fR(dev_info_t *\fIdip\fR,
  20      \fBint\fR \fI(*reconnection_event_handler)\fR(dev_info_t *\fIdip\fR);
  21 .fi
  22
  23 .LP
  24 .nf
  25  \fBvoid\fR \fB\fR\fBusb_unregister_hotplug_cbs\fR(\fBdev_info_t *\fR\fIdip\fR);
  26 .fi
  27
  28 .SH INTERFACE LEVEL
  29 .sp
  30 .LP
  31 Solaris DDI specific (Solaris DDI)
  32 .SH PARAMETERS
  33 .sp
  34 .LP
  35 For \fBusb_register_hotplug_cbs()\fR
  36 .sp
  37 .ne 2
  38 .na
  39 \fB\fIdip\fR\fR
  40 .ad
  41 .sp .6
  42 .RS 4n
  43 Pointer to the device's \fBdev_info\fR structure.
  44 .RE
  45
  46 .sp
  47 .ne 2
  48 .na
  49 \fB\fIdisconnection_event_handler\fR\fR
  50 .ad
  51 .sp .6
  52 .RS 4n
  53 Called when device is disconnected. This handler takes a dev_info_t as an
  54 argument (representing the device being disconnected) and always returns
  55 USB_SUCCESS.
  56 .RE
  57
  58 .sp
  59 .ne 2
  60 .na
  61 \fB\fIreconnection_event_handler\fR\fR
  62 .ad
  63 .sp .6
  64 .RS 4n
  65 Called when device is reconnected. This handler takes a dev_info_t as an
  66 argument (representing the device being reconnected) and always returns
  67 USB_SUCCESS.
  68 .RE
  69
  70 .sp
  71 .LP
  72 For \fBusb_unregister_hotplug_cbs()\fR:
  73 .sp
  74 .ne 2
  75 .na
  76 \fB\fIdip\fR\fR
  77 .ad
  78 .RS 7n
  79 Pointer to the device's \fBdev_info\fR structure.
  80 .RE
  81
  82 .SH DESCRIPTION
  83 .sp
  84 .LP
  85 The \fBusb_register_hotplug_cbs()\fR function registers callbacks to be
  86 executed when the USB device represented by \fIdip\fR is hotplugged or removed.
  87 .sp
  88 .LP
  89 The \fBusb_unregister_hotplug_cbs()\fR function unregisters or disengages
  90 callbacks from executing when the USB device represented by \fIdip\fR is
  91 hotplugged or removed.
  92 .SH RETURN VALUES
  93 .sp
  94 .LP
  95 For \fBusb_register_hotplug_cbs()\fR:
  96 .sp
  97 .ne 2
  98 .na
  99 \fBUSB_SUCCESS\fR
 100 .ad
 101 .RS 15n
 102 Callbacks were successfully registered.
 103 .RE
 104
 105 .sp
 106 .ne 2
 107 .na
 108 \fBUSB_FAILURE\fR
 109 .ad
 110 .RS 15n
 111 One or more arguments were NULL.
 112 .sp
 113 Callbacks could not be successfully registered.
 114 .RE
 115
 116 .sp
 117 .LP
 118 For \fBusb_unregister_hotplug_cbs()\fR: None
 119 .SH CONTEXT
 120 .sp
 121 .LP
 122 The \fBusb_register_hotplug_cbs()\fR function may be called only from
 123 \fBattach\fR(9E).
 124 .sp
 125 .LP
 126 The \fBusb_unregister_hotplug_cbs()\fR function may be called only from
 127 \fBdetach\fR(9E).
 128 .sp
 129 .LP
 130 Registered callback handlers requiring the use of any DDI (section 9F) function
 131 (except ddi_taskq_* functions), should launch a separate thread using
 132 ddi_taskq_* routines for processing their event, to avoid deadlocks. The new
 133 thread can then safely call any DDI function it needs to handle the event.
 134 .sp
 135 .LP
 136 The registered callback handlers execute in kernel context.
 137 .SH EXAMPLES
 138 .sp
 139 .in +2
 140 .nf
 141
 142     int remove_device(dev_info_t *)
 143     {
 144             ...
 145             ...
 146             return (USB_SUCCESS);
 147     }
 148
 149     int accommodate_device(dev_info_t *)
 150     {
 151             ...
 152             ...
 153             return (USB_SUCCESS);
 154     }
 155
 156     if (usb_register_hotplug_cbs(
 157         dip, remove_device, accommodate_device) == USB_FAILURE) {
 158             cmn_err (CE_WARN,
 159                 "%s%d: Could not register hotplug handlers.",
 160                 ddi_driver_name(dip), ddi_get_instance(dip));
 161     }
 162
 163 .fi
 164 .in -2
 165
 166 .SH ATTRIBUTES
 167 .sp
 168 .LP
 169 See \fBattributes\fR(5) for descriptions of the following attributes:
 170 .sp
 171
 172 .sp
 173 .TS
 174 box;
 175 c | c
 176 l | l .
 177 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 178 _
 179 Architecture    PCI-based systems
 180 _
 181 Interface stability     Committed
 182 .TE
 183
 184 .SH SEE ALSO
 185 .sp
 186 .LP
 187 \fBattributes\fR(5), \fBattach\fR(9E), \fBdetach\fR(9E),
 188 \fBusb_get_status\fR(9F)