Kernel Functions for Drivers ldi_ev_register_callbacks(9F)
NAME
ldi_ev_register_callbacks - add a notify and/or finalize
callbackSYNOPSIS
#include
int ldi_ev_get_cookie(ldi_handle_t lh, ldi_ev_cookie_t *cookie,
ldi_ev_callback_t *callb, void *arg, ldi_ev_callback_id_t *id);
INTERFACE LEVEL
Solaris DDI specific (Solaris DDI)PARAMETERS
ldi_handle_t lh
A layered handle representing the device for which the event notification was requested.ldi_ev_cookie_t *cookie
An opaque event cookie for the event type returned by aprevious call to ldi_ev_get_cookie(9F).
ldi_ev_callback_t *callb
A data structure which currently has the following members:struct ldi_ev_callback {
uint_t cb_vers;
int (*cb_notify)(ldi_handle_t,
ldi_ev_cookie_t cookie,
void *arg, void *ev_data);
void (*cb_finalize)(ldi_handle_t,
ldi_ev_cookie_t cookie,
int ldi_result,
void *arg,void *ev_data);
} ldi_ev_callback_t;
wherecb_vers Version of callback vector. Must be set to
LDI_EV_CB_VERS by the caller.
The arguments passed into the callbacks when they are invoked, include:SunOS 5.11 Last change: 21 Aug 2007 1
Kernel Functions for Drivers ldi_ev_register_callbacks(9F)
int ldi_result
The actual result of the state changeoperation/event passed to finalize call-
back: LDI_EV_SUCCESS: The state change
succeeded LDI_EV_FAILURE: The state
change failed.void *ev_data
Event specific data. void *arg A pointer to opaque caller private data.ldi_ev_callback_id_t *id
Unique system wide registration id returned byldi_ev_register_callbacks(9F) upon successful registra-
tion.DESCRIPTION
The ldi_ev_register_callbacks() interface allows layered
drivers to register notify and finalize callbacks for cer-
tain events. These events are listed in theldi_ev_get_cookie(9F) man page. The notify callback is
invoked only for events that can be blocked, just before theevent occurs. The notify event is not called for events ser-
viced by the NDI event service framework since such events are by definition asynchronous. Only the finalize callback is invoked for such events. Layered drivers that haveregistered notify callbacks for that event have the oppor-
tunity of blocking such events. The finalize callback is invoked once the final disposition of the state of a device (specifically a device minor node) is known. The callback isinvoked with this result, either LDI_EV_SUCCESS (state
change succeeded) or LDI_EV_FAILURE (state change failed).
This allows layered driver consumers to finalize any changes they made in response to a previous "notify" callback. For example, a layered driver's notify callback may beinvoked in response to a LDI_EV_OFFLINE event. The layered
driver may reconfigure itself to stop using the device andpermit the change to go forward. Once that happens, the I/O
SunOS 5.11 Last change: 21 Aug 2007 2
Kernel Functions for Drivers ldi_ev_register_callbacks(9F)
framework attempts to actually take the device offline. This offline attempt can have two possible outcomes: success or failure. In the former case, the finalize callback isinvoked with the ldi_result argument set to LDI_EV_SUCCESS
and the layered driver knows that the device has been taken offline. In the latter case, finalize is invoked with theldi_result set to LDI_EV_FAILURE and the layered driver
knows that the state change failed. In this case, it may choose to reconfigure itself to start using the device again.Finalize callbacks can be registered for all events includ-
ing events that cannot be blocked. A layered driver can also propagate these events up the software stack by using interfaces offered by the LDI eventframework. The layered driver may use ldi_ev_notify() to
propagate notify events occurring on minors it imports ontominors it exports. Similarly, it may use ldi_ev_finalize()
to propagate finalize events. Both ldi_ev_notify() and
ldi_ev_finalize() propagate events to device contracts as
well as LDI callbacks registered against the exported minor nodes. The LDI event framework has the following guarantees and requirements with respect to these callbacks: 1. The notify() callback is invoked before an event(represented by the event cookie) occurs on a dev-
ice (represented by the layered driver handle) and is invoked only for events that can be blocked. Ifthe callback returns LDI_EV_FAILURE, the event is
blocked. If the callback returns LDI_EV_SUCCESS,
the event is allowed to proceed. If any other value is returned, it is an error. An error message is logged and the event is blocked. An example of an event that can be blocked and for which notify callbacks may be invoked is the offline eventLDI_EV_OFFLINE.
2. The finalize callback is invoked for all events (including events that cannot be blocked) after the event has occurred. It is invoked with eitherLDI_EV_SUCCESS indicating that the event success-
fully happened or LDI_EV_FAILURE indicating that
the event did not occur. The finalize callback returns no values. Good examples of events that cannot be blocked are the degrade event(LDI_EV_DEGRADE) and events serviced by the NDI
SunOS 5.11 Last change: 21 Aug 2007 3
Kernel Functions for Drivers ldi_ev_register_callbacks(9F)
event service framework. 3. Layered drivers may register one or both of these callbacks (that is, only for a notify event or only for a finalize event or for both) against any LDI handle that they may possess. If a finalize or notify event is not being registered, thecorresponding pointer in the ldi_ev_callback_t
structure must be set to NULL. It is an error to attempt a registration with both callbacks set to NULL. 4. A notify and/or finalize callback is invoked only if the corresponding LDI handle is open. If an LDI handle against which the callbacks are registered is closed, the corresponding finalize and notify callbacks is not invoked as it is assumed that thelayered driver is no longer interested in the dev-
ice. See number 5 below for the exception to this rule. 5. A layered driver that closes it's LDI handle in it's notify routine receives the corresponding finalize callback after the event has occurred.Because the LDI handle has been closed, the final-
ize callback is invoked with a NULL LDI handle. It is the responsibility of the layered driver to maintain state in it's private "arg" parameter so that it can reopen the device (if desired) in it's finalize callback. One example where this may happen is with theLDI_EV_OFFLINE event. A layered driver's notify
callback may be invoked for an offline event. The layered driver may choose to allow this event to proceed. In that case, since it has a layered open of the device, it must close the LDI handle so thatthe offline event can succeed (an offline of a dev-
ice does not succeed if there is any open of the device, layered or otherwise). Since the layereddriver has closed the LDI handle in the notify rou-
tine, it's finalize callback (if any) is invoked with a NULL LDI handle. It is the responsibility of the layered driver to maintain state (such as thedevice path or devid) in it's private "arg" parame-
ter, so that in the finalize routine, it can do a layered open of the device if the device offline failed.This is the only exception where the finalize call-
back is invoked if the LDI handle has been closed. In all other cases if the LDI handle has beenSunOS 5.11 Last change: 21 Aug 2007 4
Kernel Functions for Drivers ldi_ev_register_callbacks(9F)
closed, no corresponding callbacks is invoked. 6. In order for the offline event to succeed(LDI_EV_OFFLINE), it is imperative that there be no
opens (including LDI handles) to the device. If a layered driver's notify callback is invoked for an offline event and the driver intends to allow the offline to proceed, the driver must close the corresponding LDI handle.7. The notify and finalize callbacks are not automati-
cally unregistered even if the corresponding LDI handle has been closed. It is the responsibility of the layered driver to unregister these callbacks when they are not required. It may do so using theldi_ev_remove_callbacks(9F) interface. The LDI
framework may panic if the entity registering thecallback (such as a dip, dev_t or module) no longer
exists on the system and the corresponding call-
backs have not been unregistered.8. The LDI event framework guarantees that if a lay-
ered driver receives a notify event, it also receives a finalize event except if the layered consumer itself blocked the event (that is, itreturned LDI_EV_FAILURE from it's notify callback.
In this case, the layered driver knows that the event has been blocked and therefore does not need the finalize callback. 9. If a layered driver propagates notify events on minors it imports to minors it exports, it must first propagate these events up the software stackvia ldi_eve_notify() in it's notify callback. It
must do so before attempting to check if it blocks the event. This is required, because a layered driver cannot release the device if consumers up the stack are still using the device. Ifldi_ev_notify() returns LDI_EV_FAILURE, the call-
back must immediately return LDI_EV_FAILURE from
it's notify callback. If ldi_ev_notify() returns
LDI_EV_SUCCESS, then the state change is permissi-
ble as far as consumers higher up in the software stack are concerned. The layered driver must then determine if it can permit the state change. If the state change is to be allowed, the layered drivermust return LDI_EV_SUCCESS. If the layered driver
determines that the state change should not be per-
mitted, it must invoke ldi_ev_finalize() on minors
it exports with a result of LDI_EV_FAILURE (to
inform consumers up the stack) and then returnLDI_EV_FAILURE from it's notify callback.
SunOS 5.11 Last change: 21 Aug 2007 5
Kernel Functions for Drivers ldi_ev_register_callbacks(9F)
10. The LDI event framework generates finalize events at the earliest point where a failure is detected. If the failure is detected in the framework (suchas in ldi_ev_notify()) the framework generates the
finalize events. In the event that a failure is first detected in a layered driver (that is, in the notify callback of a layered driver) the layereddriver must use ldi_ev_finalize() to send finalize
events up the software stack . See the examples for code snippets describing this scenario. 11. The finalize callback must first reconfigure itself before attempting to propagate the event up thesoftware stack via ldi_ev_finalize(9F). This is so
that the minors it exports are available and ready for use before the finalize event is propagated up the software stack. 12. It may so happen that the event propagated up the software stack is not the same as the event for which a layered driver's notify/finalize callback is invoked. For example, a layered driver's callback(s) may be invoked for an offline event, but the driver may choose to only propagate the degraded event to its consumers (since it may have a mirror/copy of the data on the device.) In that case, the layered driver must generate a different event cookie (that is, one corresponding to thedegraded event via ldi_ev_get_cookie(9F)) and use
that cookie in its propagation calls (that is,ldi_ev_notify(9F) and ldi_ev_finalize(9F)).
Once the registration of the callback(s) is successful, anopaque ldi_ev_callback_id_t structure is returned which may
be used to unregister the callback(s) later.RETURN VALUES
The return values for this function are:LDI_EV_SUCCESS
Callback(s) added successfully.LDI_EV_FAILURE
Failed to add callback(s).CONTEXT
SunOS 5.11 Last change: 21 Aug 2007 6
Kernel Functions for Drivers ldi_ev_register_callbacks(9F)
This function can be called from user and kernel contexts only.EXAMPLES
Example 1 Registration and Callbacks for the OFFLINE Event The following example shows how theldi_ev_register_callbacks() function performs a registration
and callback for the offline event: static intevent_register(void)
{ldi_handle_t lh;
ldi_ev_callback_t callb;
ldi_ev_cookie_t off_cookie;
if (ldi_ev_get_cookie(lh, LDI_EV_OFFLINE, &off_cookie)
== LDI_EV_FAILURE)
goto fail;callb.cb_vers = LDI_EV_CB_VERS;
callb.cb_notify = off_notify;
callb.cb_finalize = off_finalize;
if (ldi_ev_register_callbacks(lh, off_cookie, &callb, arg, &id)
!= LDI_EV_SUCCESS)
goto fail; } static voidevent_unregister(ldi_ev_callback_id_t id)
{ldi_ev_remove_callbacks(id);
} static intoff_notify(ldi_handle_t lh, ldi_ev_cookie_t off_cookie, void *arg,
void *ev_data)
{ASSERT(strcmp(ldi_ev_get_type(off_cookie), LDI_EV_OFFLINE) == 0);
/* Map imported minors to exported minor */widget_map(lh, &minor, &spec_type);
/** Call ldi_ev_notify() to propagate events to our consumers.
* This *must* happen before we check if offline should be blockedSunOS 5.11 Last change: 21 Aug 2007 7
Kernel Functions for Drivers ldi_ev_register_callbacks(9F)
*/if (ldi_ev_notify(dip, minor, spec_type, off_cookie, ev_data)
!= LDI_EV_SUCCESS)
return (LDI_EV_FAILURE);
/* * Next, check if we can allow the offline */if (widget_check(lh) == WIDGET_SUCCESS) {
widget_save_path(arg, lh);
widget_reconfigure(lh, RELEASE);
ldi_close(lh);
return (LDI_EV_SUCCESS)
} /* * We cannot permit the offline. The first layer that detects * failure i.e. us, must generate finalize events for our consumers */ldi_ev_finalize(dip, minor, spec_type, LDI_EV_FAILURE, off_cookie,
ev_data);
return (LDI_EV_FAILURE);
} /* /** The finalize callback will only be called if we returned LDI_EV_SUCCESS
* in our notify callback. ldi_result passed in may be SUCCESS or FAILURE
*/ static voidoff_finalize(ldi_handle_t NULL_lh, ldi_ev_cookie_t off_cookie,
int ldi_result, void *arg, void *ev_data)
{ldi_handle_t lh;
ASSERT(strcmp(ldi_ev_get_type(off_cookie), LDI_EV_OFFLINE) == 0);
path = widget_get_path(arg);
widget_map_by_path(path, &minor, &spec_type);
if (ldi_result == LDI_EV_SUCCESS) {
ldi_ev_finalize(dip, minor, spec_type, LDI_EV_SUCCESS,
off_cookie, ev_data);
return; } /* The offline failed. Reopen the device */ldi_open_by_name(path, &lh);
widget_reconfigure(lh, REACQUIRE);
SunOS 5.11 Last change: 21 Aug 2007 8
Kernel Functions for Drivers ldi_ev_register_callbacks(9F)
ldi_ev_finalize(dip, minor, spec_type, LDI_EV_FAILURE, off_cookie,
ev_data);
} Example 2 Registration and Callbacks for the DEGRADE Event The following example shows how theldi_ev_register_callbacks() function performs a registration
and callback for the degrade event: static intevent_register(void)
{ldi_handle_t lh;
ldi_ev_callback_t callb;
ldi_ev_cookie_t dgrd_cookie;
if (ldi_ev_get_cookie(lh, LDI_EV_DEGRADE, &dgrd_cookie)
== LDI_EV_FAILURE)
goto fail; /* no notify callbacks allowed for degrade events */callb.cb_vers = LDI_EV_CB_VERS;
callb.cb_notify = NULL; /* NULL, notify cannot be used for
DEGRADE */callb.cb_finalize = dgrd_finalize;
if (ldi_ev_register_callbacks(lh, dgrd_cookie, &callb, arg, &id)
!= LDI_EV_SUCCESS)
goto fail; } static voidevent_unregister(ldi_ev_callback_id_t id)
{ldi_ev_remove_callbacks(id);
} /** For degrade events. ldi_result will always be LDI_EV_SUCCESS
*/ static voiddgrd_finalize(ldi_handle_t lh, ldi_ev_cookie_t off_cookie,
int ldi_result, void *arg, void *ev_data)
{ASSERT(ldi_result == LDI_EV_SUCCESS);
ASSERT(strcmp(ldi_ev_get_type(off_cookie), LDI_EV_DEGRADE) == 0);
widget_map(lh, &minor, &spec_type);
SunOS 5.11 Last change: 21 Aug 2007 9
Kernel Functions for Drivers ldi_ev_register_callbacks(9F)
widget_reconfigure(lh, RELEASE);
ldi_ev_finalize(dip, minor, spec_type, LDI_EV_SUCCESS, d
grd_cookie, ev_data);
}SEE ALSO
ldi_ev_finalize(9F), ldi_ev_get_cookie(9F),
ldi_ev_notify(9F), ldi_ev_remove_callbacks(9F)
SunOS 5.11 Last change: 21 Aug 2007 10