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

   1 '\" te
   2 .\"  Copyright (c) 2007, 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 LDI_EV_REGISTER_CALLBACKS 9F "Oct 24, 2012"
   7 .SH NAME
   8 ldi_ev_register_callbacks \- add a notify and/or finalize callback
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 #include <sys/sunldi.h>
  13
  14 \fBint\fR \fBldi_ev_register_callbacks\fR(\fIldi_handle_t lh\fR,
  15       \fIldi_ev_cookie_t *cookie\fR, \fIldi_ev_callback_t *callb\fR,
  16       \fBvoid\fR \fI*arg\fR, \fIldi_callback_id_t *id\fR);
  17 .fi
  18
  19 .SH INTERFACE LEVEL
  20 .sp
  21 .LP
  22 Solaris DDI specific (Solaris DDI)
  23 .SH PARAMETERS
  24 .sp
  25 .ne 2
  26 .na
  27 \fB\fIldi_handle_t lh\fR\fR
  28 .ad
  29 .sp .6
  30 .RS 4n
  31 A layered handle representing the device for which the event notification was
  32 requested.
  33 .RE
  34
  35 .sp
  36 .ne 2
  37 .na
  38 \fB\fIldi_ev_cookie_t *cookie\fR\fR
  39 .ad
  40 .sp .6
  41 .RS 4n
  42 An opaque event cookie for the event type returned by a previous call to
  43 \fBldi_ev_get_cookie\fR(9F).
  44 .RE
  45
  46 .sp
  47 .ne 2
  48 .na
  49 \fB\fIldi_ev_callback_t *callb\fR\fR
  50 .ad
  51 .sp .6
  52 .RS 4n
  53 A data structure which currently has the following members:
  54 .sp
  55 .in +2
  56 .nf
  57 struct ldi_ev_callback {
  58         uint_t  cb_vers;
  59         int     (*cb_notify)(ldi_handle_t,
  60                              ldi_ev_cookie_t cookie,
  61                              void *arg, void *ev_data);
  62         void    (*cb_finalize)(ldi_handle_t,
  63                                ldi_ev_cookie_t cookie,
  64                                int ldi_result,
  65                                void *arg,
  66                                void *ev_data);
  67  } ldi_ev_callback_t;
  68 .fi
  69 .in -2
  70
  71 where
  72 .sp
  73 .ne 2
  74 .na
  75 \fB\fBcb_vers\fR\fR
  76 .ad
  77 .RS 11n
  78 Version of callback vector. Must be set to \fBLDI_EV_CB_VERS\fR by the caller.
  79 .sp
  80 The arguments passed into the callbacks when they are invoked, include:
  81 .sp
  82 .ne 2
  83 .na
  84 \fB\fBint ldi_result\fR\fR
  85 .ad
  86 .sp .6
  87 .RS 4n
  88 The actual result of the state change operation/event passed to finalize
  89 callback: \fBLDI_EV_SUCCESS\fR: The state change succeeded
  90 \fBLDI_EV_FAILURE\fR: The state change failed.
  91 .RE
  92
  93 .sp
  94 .ne 2
  95 .na
  96 \fB\fBvoid *ev_data\fR\fR
  97 .ad
  98 .sp .6
  99 .RS 4n
 100 Event specific data.
 101 .RE
 102
 103 .RE
 104
 105 .RE
 106
 107 .sp
 108 .ne 2
 109 .na
 110 \fB\fBvoid\fR *\fIarg\fR\fR
 111 .ad
 112 .sp .6
 113 .RS 4n
 114 A pointer to opaque caller private data.
 115 .RE
 116
 117 .sp
 118 .ne 2
 119 .na
 120 \fB\fIldi_callback_id_t *id\fR\fR
 121 .ad
 122 .sp .6
 123 .RS 4n
 124 Unique system wide registration id returned by ldi_ev_register_callbacks(9F)
 125 upon successful registration.
 126 .RE
 127
 128 .SH DESCRIPTION
 129 .sp
 130 .LP
 131 The \fBldi_ev_register_callbacks()\fR interface allows layered drivers to
 132 register notify and finalize callbacks for certain events. These events are
 133 listed in the \fBldi_ev_get_cookie\fR(9F) man page. The notify callback is
 134 invoked only for events that can be blocked, just before the event occurs. The
 135 notify event is not called for events serviced by the \fBNDI\fR event  service
 136 framework since such events are by definition asynchronous. Only  the finalize
 137 callback is invoked for such events. Layered drivers that have registered
 138 notify callbacks for that event have the opportunity of blocking such events.
 139 The finalize callback is invoked once the final disposition of the state of a
 140 device (specifically a device minor node) is known. The callback is invoked
 141 with this result, either \fBLDI_EV_SUCCESS\fR (state change succeeded) or
 142 \fBLDI_EV_FAILURE\fR (state change failed). This allows layered driver
 143 consumers to finalize any changes they made in response to a previous "notify"
 144 callback.
 145 .sp
 146 .LP
 147 For example, a layered driver's notify callback may be invoked in response to a
 148 \fBLDI_EV_OFFLINE\fR event. The layered driver may reconfigure itself to stop
 149 using the device and permit the change to go forward. Once that happens, the
 150 \fBI/O\fR framework attempts to actually take the device offline. This offline
 151 attempt can have two possible outcomes: success or failure. In the former case,
 152 the finalize callback is invoked with the \fIldi_result\fR argument set to
 153 \fBLDI_EV_SUCCESS\fR and the layered driver knows that the device has been
 154 taken offline. In the latter case, finalize is invoked with the
 155 \fIldi_result\fR set to \fBLDI_EV_FAILURE\fR and the layered driver knows that
 156 the state change failed. In this case, it may choose to reconfigure itself to
 157 start using the device again.
 158 .sp
 159 .LP
 160 Finalize callbacks can be registered for all events including events that
 161 cannot be blocked.
 162 .sp
 163 .LP
 164 A layered driver can also propagate these events up the software stack by using
 165 interfaces offered by the \fBLDI\fR event framework. The layered driver may use
 166 \fBldi_ev_notify()\fR to propagate notify events occurring on minors it imports
 167 onto minors it exports. Similarly, it may use \fBldi_ev_finalize()\fR to
 168 propagate finalize events. Both \fBldi_ev_notify()\fR and
 169 \fBldi_ev_finalize()\fR propagate events to device contracts as well as LDI
 170 callbacks  registered against the exported minor nodes.
 171 .sp
 172 .LP
 173 The \fBLDI\fR event framework has the following guarantees and requirements
 174 with respect to these callbacks:
 175 .RS +4
 176 .TP
 177 1.
 178 The \fBnotify()\fR callback is invoked before an event (represented by the
 179 event cookie) occurs on a device (represented by the layered driver handle) and
 180 is invoked only for events that can be blocked. If the callback returns
 181 \fBLDI_EV_FAILURE\fR, the event is blocked. If the callback returns
 182 \fBLDI_EV_SUCCESS\fR, the event is allowed to proceed. If any other value is
 183 returned, it is an error. An error message is logged and the event is blocked.
 184 An example of an event that can be blocked and for which notify callbacks may
 185 be invoked is the offline event \fBLDI_EV_OFFLINE\fR.
 186 .RE
 187 .RS +4
 188 .TP
 189 2.
 190 The finalize callback is invoked for all events (including events that
 191 cannot be blocked) after the event has occurred. It is invoked with either
 192 \fBLDI_EV_SUCCESS\fR indicating that the event successfully happened or
 193 \fBLDI_EV_FAILURE\fR indicating that the event did not occur. The finalize
 194 callback returns no values. Good examples of events that cannot be blocked are
 195 the degrade event (\fBLDI_EV_DEGRADE\fR) and events serviced by the \fBNDI\fR
 196 event service framework.
 197 .RE
 198 .RS +4
 199 .TP
 200 3.
 201 Layered drivers may register one or both of these callbacks (that is, only
 202 for a notify event or only for a finalize event or for both) against any
 203 \fBLDI\fR handle that they may possess. If a finalize or notify event is not
 204 being registered, the corresponding pointer in the \fIldi_ev_callback_t\fR
 205 structure must be set to \fBNULL\fR. It is an error to attempt a registration
 206 with both callbacks set to \fBNULL\fR.
 207 .RE
 208 .RS +4
 209 .TP
 210 4.
 211 A notify and/or finalize callback is invoked only if the corresponding
 212 \fBLDI\fR handle is open. If an \fBLDI\fR handle against which the callbacks
 213 are registered is closed, the corresponding finalize and notify callbacks is
 214 not invoked as it is assumed that the layered driver is no longer interested in
 215 the device. See number 5 below for the exception to this rule.
 216 .RE
 217 .RS +4
 218 .TP
 219 5.
 220 A layered driver that closes it's \fBLDI\fR handle in it's notify routine
 221 receives the corresponding finalize callback after the event has occurred.
 222 Because the \fBLDI\fR handle has been closed, the finalize callback is invoked
 223 with a \fBNULL\fR \fBLDI\fR handle. It is the responsibility of the layered
 224 driver to maintain state in it's private "\fIarg\fR" parameter so that it can
 225 reopen the device (if desired) in it's finalize callback.
 226 .sp
 227 One example where this may happen is with the \fBLDI_EV_OFFLINE\fR event. A
 228 layered driver's notify callback may be invoked for an offline event. The
 229 layered driver may choose to allow this event to proceed. In that case, since
 230 it has a layered open of the device, it must close the \fBLDI\fR handle so that
 231 the offline event can succeed (an offline of a device does not succeed if there
 232 is any open of the device, layered or otherwise). Since the layered driver has
 233 closed the \fBLDI\fR handle in the notify routine, it's finalize callback (if
 234 any) is invoked with a \fBNULL\fR \fBLDI\fR handle. It is the responsibility of
 235 the layered driver to maintain state (such as the device path or \fBdevid\fR)
 236 in it's private "\fIarg\fR" parameter, so that in the finalize routine, it can
 237 do a layered open of the device if the device offline failed.
 238 .sp
 239 This is the only exception where the finalize callback is invoked if the
 240 \fBLDI\fR handle has been closed. In all other cases if the \fBLDI\fR handle
 241 has been closed, no corresponding callbacks is invoked.
 242 .RE
 243 .RS +4
 244 .TP
 245 6.
 246 In order for the offline event to succeed (\fBLDI_EV_OFFLINE\fR), it is
 247 imperative that there be no opens (including \fBLDI\fR handles) to the device.
 248 If a layered driver's notify callback is invoked for an offline event and the
 249 driver intends to allow the offline to proceed, the driver must close the
 250 corresponding \fBLDI\fR handle.
 251 .RE
 252 .RS +4
 253 .TP
 254 7.
 255 The notify and finalize callbacks are not automatically unregistered even if
 256 the corresponding \fBLDI\fR handle has been closed. It is the responsibility of
 257 the layered driver to unregister these callbacks when they are not required. It
 258 may do so using the \fBldi_ev_remove_callbacks\fR(9F) interface. The \fBLDI\fR
 259 framework may panic if the entity registering the callback (such as a
 260 \fBdip\fR, \fBdev_t\fR or \fBmodule\fR) no longer exists on the system and the
 261 corresponding callbacks have not been unregistered.
 262 .RE
 263 .RS +4
 264 .TP
 265 8.
 266 The \fBLDI\fR event framework guarantees that if a layered driver receives a
 267 notify event, it also receives a finalize event except if the layered consumer
 268 itself blocked the event (that is, it returned \fBLDI_EV_FAILURE\fR from it's
 269 notify callback. In this case, the layered driver knows that the event has been
 270 blocked and therefore does not need the finalize callback.
 271 .RE
 272 .RS +4
 273 .TP
 274 9.
 275 If a layered driver propagates notify events on minors it imports to minors
 276 it exports, it must first propagate these events up the software stack via
 277 \fBldi_eve_notify()\fR in it's notify callback. It must do so before attempting
 278 to check if it blocks the event. This is required, because a layered driver
 279 cannot release the device if consumers up the stack are still using the device.
 280 If \fBldi_ev_notify()\fR returns \fBLDI_EV_FAILURE\fR, the callback must
 281 immediately return \fBLDI_EV_FAILURE\fR from it's notify callback. If
 282 \fBldi_ev_notify()\fR  returns \fBLDI_EV_SUCCESS\fR, then the state change is
 283 permissible as far as consumers higher up in the software stack are concerned.
 284 The layered driver must then determine if it can permit the state change. If
 285 the state change is to be allowed, the layered driver must return
 286 \fBLDI_EV_SUCCESS\fR. If the layered driver determines that the state change
 287 should not be permitted, it must invoke \fBldi_ev_finalize()\fR  on minors it
 288 exports with a result of \fBLDI_EV_FAILURE\fR (to inform consumers up the
 289 stack) and then return \fBLDI_EV_FAILURE\fR from it's notify callback.
 290 .RE
 291 .RS +4
 292 .TP
 293 10.
 294 The \fBLDI\fR event framework generates finalize events at the earliest
 295 point where a failure is detected. If the failure is detected in the framework
 296 (such as in \fBldi_ev_notify()\fR) the framework generates the finalize events.
 297 In the event that a failure is first detected in a layered driver (that is, in
 298 the notify callback of a layered driver) the layered driver must use
 299 \fBldi_ev_finalize()\fR  to send finalize events up the software stack . See
 300 the examples for code snippets describing this scenario.
 301 .RE
 302 .RS +4
 303 .TP
 304 11.
 305 The finalize callback must first reconfigure itself before attempting to
 306 propagate the event up the software stack via \fBldi_ev_finalize\fR(9F). This
 307 is so that the minors it exports are available and ready for use before the
 308 finalize event is propagated up the software stack.
 309 .RE
 310 .RS +4
 311 .TP
 312 12.
 313 It may so happen that the event propagated up the software stack is not the
 314 same as the event for which a layered driver's notify/finalize callback is
 315 invoked. For example, a layered driver's callback(s) may be invoked for an
 316 offline event, but the driver may choose to only propagate the degraded event
 317 to its consumers (since it may have a mirror/copy of the data on the device.)
 318 In that case, the layered driver must generate a different event cookie (that
 319 is, one corresponding to the degraded event via \fBldi_ev_get_cookie\fR(9F))
 320 and use that cookie in its propagation calls (that is, \fBldi_ev_notify\fR(9F)
 321 and \fBldi_ev_finalize\fR(9F)).
 322 .RE
 323 .sp
 324 .LP
 325 Once the registration of the callback(s) is successful, an opaque
 326 \fIldi_callback_id_t\fR structure is returned which may be used to
 327 unregister the callback(s) later.
 328 .SH RETURN VALUES
 329 .sp
 330 .LP
 331 The return values for this function are:
 332 .sp
 333 .ne 2
 334 .na
 335 \fB\fBLDI_EV_SUCCESS\fR\fR
 336 .ad
 337 .sp .6
 338 .RS 4n
 339 Callback(s) added successfully.
 340 .RE
 341
 342 .sp
 343 .ne 2
 344 .na
 345 \fB\fBLDI_EV_FAILURE\fR\fR
 346 .ad
 347 .sp .6
 348 .RS 4n
 349 Failed to add callback(s).
 350 .RE
 351
 352 .SH CONTEXT
 353 .sp
 354 .LP
 355 This function can be called from user and kernel contexts only.
 356 .SH EXAMPLES
 357 .LP
 358 \fBExample 1 \fRRegistration and Callbacks for the OFFLINE Event
 359 .sp
 360 .LP
 361 The following example shows how the \fBldi_ev_register_callbacks()\fR function
 362 performs a registration and callback for the offline event:
 363
 364 .sp
 365 .in +2
 366 .nf
 367 static int
 368 event_register(void)
 369 {
 370         ldi_handle_t lh;
 371         ldi_ev_callback_t callb;
 372         ldi_ev_cookie_t off_cookie;
 373
 374         if (ldi_ev_get_cookie(lh, LDI_EV_OFFLINE, &off_cookie)
 375             == LDI_EV_FAILURE)
 376                 goto fail;
 377
 378
 379         callb.cb_vers = LDI_EV_CB_VERS;
 380         callb.cb_notify = off_notify;
 381         callb.cb_finalize = off_finalize;
 382
 383         if (ldi_ev_register_callbacks(lh, off_cookie, &callb, arg, &id)
 384             != LDI_EV_SUCCESS)
 385                 goto fail;
 386 }
 387
 388 static void
 389 event_unregister(ldi_callback_id_t id)
 390 {
 391         ldi_ev_remove_callbacks(id);
 392 }
 393
 394 static int
 395 off_notify(ldi_handle_t lh, ldi_ev_cookie_t off_cookie, void *arg,
 396     void *ev_data)
 397 {
 398
 399         ASSERT(strcmp(ldi_ev_get_type(off_cookie), LDI_EV_OFFLINE) == 0);
 400
 401         /* Map imported minors to exported minor */
 402         widget_map(lh, &minor, &spec_type);
 403
 404         /*
 405          * Call ldi_ev_notify() to propagate events to our consumers.
 406          * This *must* happen before we check if offline should be blocked
 407          */
 408         if (ldi_ev_notify(dip, minor, spec_type, off_cookie, ev_data)
 409             != LDI_EV_SUCCESS)
 410                 return (LDI_EV_FAILURE);
 411
 412         /*
 413          * Next, check if we can allow the offline
 414          */
 415         if (widget_check(lh) == WIDGET_SUCCESS) {
 416                 widget_save_path(arg, lh);
 417                 widget_reconfigure(lh, RELEASE);
 418                 ldi_close(lh);
 419                 return (LDI_EV_SUCCESS)
 420         }
 421
 422         /*
 423          * We cannot permit the offline. The first layer that detects
 424          * failure i.e. us, must generate finalize events for our
 425            consumers
 426          */
 427         ldi_ev_finalize(dip, minor, spec_type, LDI_EV_FAILURE, off_cookie,
 428             ev_data);
 429
 430         return (LDI_EV_FAILURE);
 431 }
 432
 433 /*
 434 /*
 435  * The finalize callback will only be called if we returned LDI_EV_SUCCESS
 436  * in our notify callback. ldi_result passed in may be SUCCESS or FAILURE
 437  */
 438 static void
 439 off_finalize(ldi_handle_t NULL_lh, ldi_ev_cookie_t off_cookie,
 440     int ldi_result, void *arg, void *ev_data)
 441 {
 442         ldi_handle_t lh;
 443
 444         ASSERT(strcmp(ldi_ev_get_type(off_cookie), LDI_EV_OFFLINE) == 0);
 445
 446         path = widget_get_path(arg);
 447
 448         widget_map_by_path(path, &minor, &spec_type);
 449
 450         if (ldi_result == LDI_EV_SUCCESS) {
 451                 ldi_ev_finalize(dip, minor, spec_type, LDI_EV_SUCCESS,
 452                     off_cookie, ev_data);
 453                 return;
 454         }
 455
 456         /* The offline failed. Reopen the device */
 457         ldi_open_by_name(path, &lh);
 458         widget_reconfigure(lh, REACQUIRE);
 459
 460         ldi_ev_finalize(dip, minor, spec_type, LDI_EV_FAILURE, off_cookie,
 461             ev_data);
 462 }
 463 .fi
 464 .in -2
 465
 466 .LP
 467 \fBExample 2 \fRRegistration and Callbacks for the DEGRADE Event
 468 .sp
 469 .LP
 470 The following example shows how the \fBldi_ev_register_callbacks()\fR function
 471 performs a registration and callback for the degrade event:
 472
 473 .sp
 474 .in +2
 475 .nf
 476 static int
 477 event_register(void)
 478 {
 479         ldi_handle_t lh;
 480         ldi_ev_callback_t callb;
 481         ldi_ev_cookie_t dgrd_cookie;
 482
 483         if (ldi_ev_get_cookie(lh, LDI_EV_DEGRADE, &dgrd_cookie)
 484             == LDI_EV_FAILURE)
 485                 goto fail;
 486
 487         /* no notify callbacks allowed for degrade events */
 488         callb.cb_vers = LDI_EV_CB_VERS;
 489         callb.cb_notify = NULL; /* NULL, notify cannot be used for
 490                                    DEGRADE */
 491         callb.cb_finalize = dgrd_finalize;
 492
 493         if (ldi_ev_register_callbacks(lh, dgrd_cookie, &callb, arg, &id)
 494             != LDI_EV_SUCCESS)
 495                 goto fail;
 496 }
 497
 498 static void
 499 event_unregister(ldi_callback_id_t id)
 500 {
 501         ldi_ev_remove_callbacks(id);
 502 }
 503
 504 /*
 505  * For degrade events. ldi_result will always be LDI_EV_SUCCESS
 506  */
 507 static void
 508 dgrd_finalize(ldi_handle_t lh, ldi_ev_cookie_t off_cookie,
 509     int ldi_result, void *arg, void *ev_data)
 510 {
 511         ASSERT(ldi_result == LDI_EV_SUCCESS);
 512         ASSERT(strcmp(ldi_ev_get_type(off_cookie), LDI_EV_DEGRADE) == 0);
 513
 514         widget_map(lh, &minor, &spec_type);
 515
 516         widget_reconfigure(lh, RELEASE);
 517
 518         ldi_ev_finalize(dip, minor, spec_type, LDI_EV_SUCCESS, d
 519             grd_cookie, ev_data);
 520 }
 521 .fi
 522 .in -2
 523
 524 .SH SEE ALSO
 525 .sp
 526 .LP
 527 \fBldi_ev_finalize\fR(9F), \fBldi_ev_get_cookie\fR(9F),
 528 \fBldi_ev_notify\fR(9F), \fBldi_ev_remove_callbacks\fR(9F)