usr/src/man/man9f/ldi_ev_notify.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_NOTIFY 9F "Aug 21, 2007"
   7 .SH NAME
   8 ldi_ev_notify \- propagate notification of a state change event
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 #include <sys/sunldi.h>
  13
  14 \fBint\fR \fBldi_ev_notify\fR(\fIdev_info_t *dip\fR, \fIminor_t minor\fR, \fIint spec_type\fR,
  15      \fIldi_ev_cookie_t cookie\fR, \fIvoid *ev_data\fR);
  16 .fi
  17
  18 .SH INTERFACE LEVEL
  19 .sp
  20 .LP
  21 Solaris DDI specific (Solaris DDI)
  22 .SH PARAMETERS
  23 .sp
  24 .ne 2
  25 .na
  26 \fB\fIdev_info_t *dip\fR\fR
  27 .ad
  28 .sp .6
  29 .RS 4n
  30 The \fBdevinfo\fR node of the layered consumer exporting the minor device.
  31 .RE
  32
  33 .sp
  34 .ne 2
  35 .na
  36 \fB\fIminor_t minor\fR\fR
  37 .ad
  38 .sp .6
  39 .RS 4n
  40 The minor number of the exported minor device.
  41 .RE
  42
  43 .sp
  44 .ne 2
  45 .na
  46 \fB\fIint spec_type\fR\fR
  47 .ad
  48 .sp .6
  49 .RS 4n
  50 The type of minor device (\fBS_IFCHR\fR or \fBS_IFBLK\fR).
  51 .RE
  52
  53 .sp
  54 .ne 2
  55 .na
  56 \fB\fIldi_ev_cookie_t cookie\fR\fR
  57 .ad
  58 .sp .6
  59 .RS 4n
  60 An opaque event cookie for the event type returned by a previous call to
  61 \fBldi_ev_get_cookie\fR(9F).
  62 .RE
  63
  64 .sp
  65 .ne 2
  66 .na
  67 \fB\fIvoid *ev_data\fR\fR
  68 .ad
  69 .sp .6
  70 .RS 4n
  71 Event specific data.
  72 .RE
  73
  74 .SH DESCRIPTION
  75 .sp
  76 .LP
  77 The \fBldi_ev_notify()\fR function propagates an event up the software stack.
  78 It may result in two actions:
  79 .RS +4
  80 .TP
  81 .ie t \(bu
  82 .el o
  83 Invocation of \fBLDI\fR callback handlers registered by layered drivers up the
  84 software stack.
  85 .RE
  86 .RS +4
  87 .TP
  88 .ie t \(bu
  89 .el o
  90 Device contract events generated on minors exported to \fBuserland\fR.
  91 .RE
  92 .sp
  93 .LP
  94 The event propagated up the software stack may be different than the event
  95 received by the layered driver invoking \fBldi_ev_notify()\fR. For example, a
  96 volume manager may receive an "offline" event on one of it's \fBLDI\fR opened
  97 disks, but may choose to propagate a "degraded" event on minors it exports to
  98 \fBuserland\fR (since it may have more than one copy of the data). The event
  99 cookie argument to \fBldi_ev_notify()\fR may be different from the event cookie
 100 currently possessed by the layered driver. If that is the case, the layered
 101 driver must generate another event cookie via a new \fBldi_ev_get_cookie\fR(9F)
 102 call.
 103 .sp
 104 .LP
 105 The\fBldi_ev_*\fR interfaces are designed to ensure that a "finalize" call is
 106 generated for layered driver consumers at the earliest point where an
 107 \fBLDI_EV_FAILURE\fR is detected. If this happens inside the \fBLDI\fR event
 108 framework, then the framework will invoke finalize. In the event a layered
 109 driver detects/generates an \fBLDI_EV_FAILURE\fR, then the layered driver must
 110 invoke \fBldi_ev_finalize()\fR. The following is an example of a layered driver
 111 invoking \fBldi_ev_finalize()\fR for the "foo" event:
 112 .sp
 113 .in +2
 114 .nf
 115 static int
 116  widget_notify(ldi_handle_t lh, ldi_ev_cookie_t foo_cookie, void *arg,
 117      void *ev_data)
 118  {
 119
 120          ASSERT(strcmp(ldi_ev_get_type(foo_cookie), LDI_EV_FOO) == 0);
 121
 122          /* Map imported minors to exported minor */
 123          widget_map(lh, &minor, &spec_type);
 124
 125          /*
 126           * Call ldi_ev_notify() to propagate events to our consumers.
 127           * This *must* happen before we check if widget should block
 128           * foo
 129           */
 130           if (ldi_ev_notify(dip, minor, spec_type, foo_cookie, ev_data)
 131               != LDI_EV_SUCCESS)
 132                   return (LDI_EV_FAILURE);
 133
 134          /*
 135           * Next, check if we can allow the foo event
 136           */
 137           if (widget_release(lh, LDI_EV_FOO) == WIDGET_SUCCESS) {
 138                   return (LDI_EV_SUCCESS)
 139           }
 140
 141           /*
 142            * We cannot permit the foo event. The first layer that detects
 143            * failure i.e. us, must generate finalize events for *our*
 144            * consumers
 145            */
 146           ldi_ev_finalize(dip, minor, spec_type, LDI_EV_FAILURE,
 147               foo_cookie, ev_data);
 148
 149           return (LDI_EV_FAILURE);
 150 }
 151 .fi
 152 .in -2
 153
 154 .SH RETURN VALUES
 155 .sp
 156 .LP
 157 The return values for this function are:
 158 .sp
 159 .ne 2
 160 .na
 161 \fB\fBLDI_EV_SUCCESS\fR\fR
 162 .ad
 163 .sp .6
 164 .RS 4n
 165 Consumers up the software stack permit state change.
 166 .RE
 167
 168 .sp
 169 .ne 2
 170 .na
 171 \fB\fBLDI_EV_FAILURE\fR\fR
 172 .ad
 173 .sp .6
 174 .RS 4n
 175 Consumers are blocking the state change.
 176 .RE
 177
 178 .SH CONTEXT
 179 .sp
 180 .LP
 181 This function can be called from user and kernel context only.
 182 .SH SEE ALSO
 183 .sp
 184 .LP
 185 \fBldi_ev_get_cookie\fR(9F), \fBldi_ev_register_callbacks\fR(9F),
 186 \fBldi_ev_remove_callbacks\fR(9F)