share/man/man9f/ldi_ev_finalize.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_FINALIZE 9F "Aug 21, 2007"
   7 .SH NAME
   8 ldi_ev_finalize \- propagate disposition of a state change event
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 #include <sys/sunldi.h>
  13
  14 \fBvoid\fR \fBldi_ev_finalize\fR(\fIdev_info_t *dip\fR, \fIminor_t minor\fR, \fIint spec_type\fR,
  15      \fIint ldi_result\fR, \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\fIint ldi_result\fR\fR
  57 .ad
  58 .sp .6
  59 .RS 4n
  60 The final disposition of the state change.
  61 .RE
  62
  63 .sp
  64 .ne 2
  65 .na
  66 \fB\fIldi_ev_cookie_t cookie\fR\fR
  67 .ad
  68 .sp .6
  69 .RS 4n
  70 An opaque event cookie for the event type returned by a previous call to
  71 \fBldi_ev_get_cookie\fR(9F).
  72 .RE
  73
  74 .sp
  75 .ne 2
  76 .na
  77 \fB\fIvoid *ev_data\fR\fR
  78 .ad
  79 .sp .6
  80 .RS 4n
  81 Event specific data.
  82 .RE
  83
  84 .SH DESCRIPTION
  85 .sp
  86 .LP
  87 The \fBldi_ev_finalize()\fR function propagates the final disposition of an
  88 event up the software stack. It may result in two actions:
  89 .RS +4
  90 .TP
  91 .ie t \(bu
  92 .el o
  93 Invocation of "finalize" \fBLDI\fR callback handlers registered by layered
  94 drivers up the software stack.
  95 .RE
  96 .RS +4
  97 .TP
  98 .ie t \(bu
  99 .el o
 100 Device contract "negotiation end" (\fBCT_EV_NEGEND\fR) events generated on
 101 minors exported to \fBuserland\fR.
 102 .RE
 103 .sp
 104 .LP
 105 The event propagated up the software stack may be different than the event
 106 received by the layered driver invoking \fBldi_ev_finalize()\fR. For example, a
 107 volume manager may receive an "offline" event on one of it's \fBLDI\fR opened
 108 disks, but may choose to propagate a "degraded" event on minors it exports to
 109 \fBuserland\fR (since  it  may have more than one copy of the data). The event
 110 cookie argument to \fBldi_ev_notify\fR(9F) may be different from the event
 111 cookie currently possessed by the layered driver. If that is the case, the
 112 layered driver must generate another event cookie via a new
 113 \fBldi_ev_get_cookie\fR(9F) call.
 114 .SH RETURN VALUES
 115 .sp
 116 .LP
 117 None.
 118 .SH CONTEXT
 119 .sp
 120 .LP
 121 This function can be called from user and kernel contexts only.
 122 .SH EXAMPLES
 123 .LP
 124 \fBExample 1 \fRInvoking ldi_ev_finalize(9F) from widget's finalize callback
 125 .sp
 126 .LP
 127 The following example shows how the \fBldi_ev_finalize()\fR function is invoked
 128 from a widget's finalize callback:
 129
 130 .sp
 131 .in +2
 132 .nf
 133 static void
 134 widget_finalize(ldi_handle_t lh, ldi_ev_cookie_t foo_cookie,
 135     int ldi_result, void *arg, void *ev_data)
 136
 137 {
 138          ASSERT(strcmp(ldi_ev_get_type(foo_cookie), LDI_EV_FOO) == 0);
 139
 140          /* Map imported minor to exported minors */
 141          widget_map(lh, &minor, &spec_type);
 142
 143          if (ldi_result == LDI_EV_SUCCESS) {
 144                  ldi_ev_finalize(dip, minor, spec_type,
 145                      LDI_EV_SUCCESS, foo_cookie, ev_data);
 146           }
 147
 148           /*
 149            * The event foo failed. Reconfigure yourself
 150            * *before* propagating
 151            */
 152           widget_reconfigure(lh, LDI_EV_FOO, REACQUIRE);
 153
 154           ldi_ev_finalize(dip, minor, spec_type, LDI_EV_FAILURE,
 155               foo_cookie, ev_data);
 156 }
 157 .fi
 158 .in -2
 159
 160 .SH SEE ALSO
 161 .sp
 162 .LP
 163 \fBldi_ev_get_cookie\fR(9F), \fBldi_ev_register_callbacks\fR(9F),
 164 \fBldi_ev_remove_callbacks\fR(9F)