ldi_ev_notify(9f)

1ldi_ev_notify(9F)        Kernel Functions for Drivers        ldi_ev_notify(9F)
2
3
4

NAME

6       ldi_ev_notify - propagate notification of a state change event
7

SYNOPSIS

9       #include <sys/sunldi.h>
10
11       int ldi_ev_notify(dev_info_t *dip, minor_t minor, int spec_type,
12            ldi_ev_cookie_t cookie, void *ev_data);
13
14

INTERFACE LEVEL

16       Solaris DDI specific (Solaris DDI)
17

PARAMETERS

19       dev_info_t *dip
20
21           The  devinfo  node  of  the  layered  consumer  exporting the minor
22           device.
23
24
25       minor_t minor
26
27           The minor number of the exported minor device.
28
29
30       int spec_type
31
32           The type of minor device (S_IFCHR or S_IFBLK).
33
34
35       ldi_ev_cookie_t cookie
36
37           An opaque event cookie for the event type returned  by  a  previous
38           call to ldi_ev_get_cookie(9F).
39
40
41       void *ev_data
42
43           Event specific data.
44
45

DESCRIPTION

47       The ldi_ev_notify() function propagates an event up the software stack.
48       It may result in two actions:
49
50           o      Invocation of LDI callback handlers  registered  by  layered
51                  drivers up the software stack.
52
53           o      Device contract events generated on minors exported to user‐
54                  land.
55
56
57       The event propagated up the software stack may be  different  than  the
58       event  received  by  the  layered  driver invoking ldi_ev_notify(). For
59       example, a volume manager may receive an "offline" event on one of it's
60       LDI  opened  disks,  but  may choose to propagate a "degraded" event on
61       minors it exports to userland (since it may have more than one copy  of
62       the  data). The event cookie argument to ldi_ev_notify() may be differ‐
63       ent from the event cookie currently possessed by the layered driver. If
64       that is the case, the layered driver must generate another event cookie
65       via a new ldi_ev_get_cookie(9F) call.
66
67
68       Theldi_ev_* interfaces are designed to ensure that a "finalize" call is
69       generated  for  layered driver consumers at the earliest point where an
70       LDI_EV_FAILURE is detected. If this happens inside the LDI event frame‐
71       work,  then  the framework will invoke finalize. In the event a layered
72       driver detects/generates an LDI_EV_FAILURE,  then  the  layered  driver
73       must invoke ldi_ev_finalize(). The following is an example of a layered
74       driver invoking ldi_ev_finalize() for the "foo" event:
75
76         static int
77          widget_notify(ldi_handle_t lh, ldi_ev_cookie_t foo_cookie, void *arg,
78              void *ev_data)
79          {
80
81                  ASSERT(strcmp(ldi_ev_get_type(foo_cookie), LDI_EV_FOO) == 0);
82
83                  /* Map imported minors to exported minor */
84                  widget_map(lh, &minor, &spec_type);
85
86                  /*
87                   * Call ldi_ev_notify() to propagate events to our consumers.
88                   * This *must* happen before we check if widget should block
89                   * foo
90                   */
91                   if (ldi_ev_notify(dip, minor, spec_type, foo_cookie, ev_data)
92                       != LDI_EV_SUCCESS)
93                           return (LDI_EV_FAILURE);
94
95                  /*
96                   * Next, check if we can allow the foo event
97                   */
98                   if (widget_release(lh, LDI_EV_FOO) == WIDGET_SUCCESS) {
99                           return (LDI_EV_SUCCESS)
100                   }
101
102                   /*
103                    * We cannot permit the foo event. The first layer that detects
104                    * failure i.e. us, must generate finalize events for *our*
105                    * consumers
106                    */
107                   ldi_ev_finalize(dip, minor, spec_type, LDI_EV_FAILURE,
108                       foo_cookie, ev_data);
109
110                   return (LDI_EV_FAILURE);
111         }
112
113

RETURN VALUES

115       The return values for this function are:
116
117       LDI_EV_SUCCESS
118
119           Consumers up the software stack permit state change.
120
121
122       LDI_EV_FAILURE
123
124           Consumers are blocking the state change.
125
126

CONTEXT

128       This function can be called from user and kernel context only.
129