LDI_ADD_EVENT_HANDLER(9F) Kernel Functions for Drivers


NAME


ldi_add_event_handler - add NDI event service callback handler

SYNOPSIS


#include <sys/ddi_obsolete.h>

int ldi_add_event_handler(ldi_handle_t lh, ddi_eventcookie_t ec,
void (*handler)(ldi_handle_t, ddi_eventcookie_t,
void *, void *) void *arg, ldi_callback_id_t *id);


INTERFACE LEVEL


Obsolete

PARAMETERS


ldi_handle_t lh

Layered handle representing event notification device.


ddi_eventcookie_t ec

Cookie returned from call to ldi_get_eventcookie(9F).


void (*handler)(ldi_handle_t, ddi_eventcookie_t, void *, void *)

Callback handler for NDI event service notification.


void *arg

Pointer to opaque data supplied by caller. Typically, this is a
pointer to the layered driver's softstate structure.


ldi_callback_id_t *id

Pointer to registration id, where a unique registration id is
returned. Registration id must be saved and used when calling
ldi_remove_event_handler(9F) to unregister a callback handler.


DESCRIPTION


This function is obsolete and is only maintained for compatibility. Use
of this function is strongly discouraged. For equivalent functionality
provided by new interfaces, see ldi_ev_get_cookie(9F) and
ldi_ev_register_callbacks(9F).


The ldi_add_event_handler() function adds a callback handler to be
invoked at the occurrence of the event specified by the cookie. Adding a
callback handler is also known as subscribing to an event. Upon
successful subscription, the handler is invoked when the event occurs.
You can unregister the handler by using ldi_remove_event_handler(9F).


An instance of a layered driver can register multiple handlers for an
event or a single handler for multiple events. Callback order is not
defined and should be assumed to be random.


The routine handler is invoked with the following arguments:

ldi_handle_t lh
Layered handle representing the device for which
the event notification is requested.


ddi_eventcookie_t ec
Structure describing event that occurred.


void *arg
Opaque data pointer provided by the driver during
callback registration.


void *impl_data
Pointer to event specific data defined by the
framework that invokes the callback function.


RETURN VALUES


DDI_SUCCESS
Callback handler registered successfully.


DDI_FAILURE
Failed to register callback handler. Possible reasons
include lack of resources or a bad cookie.


CONTEXT


The ldi_add_event_handler() function can be called from user and kernel
contexts only.

SEE ALSO


ldi_ev_get_cookie(9F), ldi_ev_register_callbacks(9F),
ldi_get_eventcookie(9F), ldi_remove_event_handler(9F)


Writing Device Drivers

NOTES


Layered drivers must remove all registered callback handlers for a device
instance, represented by the layered handle, by calling
ldi_remove_event_handler(9F) before the layered driver's detach(9E)
routine completes.


illumos April 9, 2016 LDI_ADD_EVENT_HANDLER(9F)