Kernel Functions for Drivers                    ldievnotify(9F)



NAME
     ldievnotify - propagate notification  of  a  state  change
     event

SYNOPSIS
     #include 

     int ldievnotify(devinfot *dip, minort minor, int spectype,
          ldievcookiet cookie, void *evdata);


INTERFACE LEVEL
     Solaris DI specific (Solaris DI)

PARAMETERS
     devinfot *dip

         The devinfo node of the layered consumer  exporting  the
         minor device.


     minort minor

         The minor number of the exported minor device.


     int spectype

         The type of minor device (SIFCHR or SIFBLK).


     ldievcookiet cookie

         An opaque event cookie for the event type returned by  a
         previous call to ldievgetcookie(9F).


     void *evdata

         Event specific data.


DESCRIPTION
     The ldievnotify() function  propagates  an  event  up  the
     software stack. It may result in two actions:

         o    Invocation of LDI callback handlers  registered  by
              layered drivers up the software stack.

         o    Device contract events generated on minors exported
              to userland.




SunOS 5.11          Last change: 21 Aug 2007                    1






Kernel Functions for Drivers                    ldievnotify(9F)



     The event propagated up the software stack may be  different
     than  the  event  received  by  the  layered driver invoking
     ldievnotify(). For example, a volume manager  may  receive
     an  "offline" event on one of it's LDI opened disks, but may
     choose to propagate a "degraded" event on minors it  exports
     to  userland  (since  it  may have more than one copy of the
     data). The event cookie argument to ldievnotify()  may  be
     different  from  the event cookie currently possessed by the
     layered driver. If that is the case, the layered driver must
     generate     another     event     cookie    via    a    new
     ldievgetcookie(9F) call.


     Theldiev* interfaces are designed to ensure that a "final-
     ize"  call  is generated for layered driver consumers at the
     earliest point where an LDIEVFAILURE is detected. If  this
     happens  inside  the LDI event framework, then the framework
     will  invoke  finalize.  In  the  event  a  layered   driver
     detects/generates an LDIEVFAILURE, then the layered driver
     must invoke ldievfinalize(). The following is  an  example
     of a layered driver invoking ldievfinalize() for the "foo"
     event:

       static int
        widgetnotify(ldihandlet lh, ldievcookiet foocookie, void *arg,
            void *evdata)
        {

                ASERT(strcmp(ldievgettype(foocookie), LDIEVFO) == 0);

                /* Map imported minors to exported minor */
                widgetmap(lh, &minor, &spectype);

                /*
                 * Call ldievnotify() to propagate events to our consumers.
                 * This *must* happen before we check if widget should block
                 * foo
                 */
                 if (ldievnotify(dip, minor, spectype, foocookie, evdata)
                     != LDIEVSUCES)
                         return (LDIEVFAILURE);

                /*
                 * Next, check if we can allow the foo event
                 */
                 if (widgetrelease(lh, LDIEVFO) == WIDGETSUCES) {
                         return (LDIEVSUCES)
                 }

                 /*
                  * We cannot permit the foo event. The first layer that detects
                  * failure i.e. us, must generate finalize events for *our*



SunOS 5.11          Last change: 21 Aug 2007                    2






Kernel Functions for Drivers                    ldievnotify(9F)



                  * consumers
                  */
                 ldievfinalize(dip, minor, spectype, LDIEVFAILURE,
                     foocookie, evdata);

                 return (LDIEVFAILURE);
       }


RETURN VALUES
     The return values for this function are:

     LDIEVSUCES

         Consumers up the software stack permit state change.


     LDIEVFAILURE

         Consumers are blocking the state change.


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

SEE ALSO
     ldievgetcookie(9F),        ldievregistercallbacks(9F),
     ldievremovecallbacks(9F)


























SunOS 5.11          Last change: 21 Aug 2007                    3