1'\" 2.\" Copyright (c) 2003, Sun Microsystems, Inc. All Rights Reserved 3.\" Copyright 2024 Oxide Computer Company 4.\" 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. 5.\" 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. 6.\" 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] 7.Dd September 15, 2024 8.Dt DDI_ADD_EVENT_HANDLER 9F 9.Os 10.Sh NAME 11.Nm ddi_add_event_handler 12.Nd add an NDI event service callback handler 13.Sh SYNOPSIS 14.In sys/dditypes.h 15.In sys/sunddi.h 16.Ft int 17.Fo ddi_add_event_handler 18.Fa "dev_info_t *dip" 19.Fa "ddi_eventcookie_t cookie" 20.Fa "void (*handler)(dev_info_t *dip, ddi_eventcookie_t cookie, void *arg, void *bus)" 21.Fa "void *arg" 22.Fa "ddi_callback_id_t *id" 23.Fc 24.Sh INTERFACE LEVEL 25illumos DDI specific 26.Pq illumos DDI . 27.Sh PARAMETERS 28.Bl -tag -width Fa 29.It Fa dip 30Device node registering the callback. 31.It Fa cookie 32Cookie returned from call to 33.Xr ddi_get_eventcookie 9F . 34.It Fa handler 35Callback handler responsible for handling an NDI event service notification. 36Its first 37.Vt "void *" 38argument corresponds to 39.Fa arg . 40The second is bus-specific data. 41.It Fa arg 42Pointer to opaque data supplied by the caller. 43Typically, this would be a pointer to the driver's softstate structure. 44.It Fa id 45Pointer to a callback ID. 46The callback ID will be filled in when this function is called and serves as a 47unique identifier for this particular event handler. 48This ID must be saved so it can be used in a later call to 49.Xr ddi_remove_event_handler 9F 50to remove the callback. 51.El 52.Sh DESCRIPTION 53The 54.Fn ddi_add_event_handler 55function adds a callback handler to be invoked in the face of the event 56specified by 57.Fa cookie . 58The process of adding a callback handler is also known as subscribing to an 59event. 60Upon successful subscription, the handler will be invoked by the system when the 61event occurs. 62The handler can be unregistered by using 63.Xr ddi_remove_event_handler 9F . 64.Pp 65An instance of a driver can register multiple handlers for an event or a single 66handler for multiple events. 67Callback order is not defined and should assumed to be random. 68.Pp 69The callback. 70.Fa handler 71will be invoked with the following arguments: 72.Bl -tag -width Fa 73.It Fa "dev_info_t *dip" 74Device node requesting the notification. 75.It Fa "ddi_eventcookie_t cookie" 76Structure describing event that occurred. 77.It Fa "void *arg" 78Opaque data pointer provided, by the driver, during callback registration. 79.It Fa "void *bus" 80Pointer to event specific data defined by the framework which invokes the 81callback function. 82.El 83.Sh CONTEXT 84The 85.Fn ddi_add_event_handler 86and 87.Fn handler 88function can be called from user and kernel contexts only. 89.Sh RETURN VALUES 90Upon successful completion, 91the 92.Fn ddi_add_event_handler 93function returns 94.Dv DDI_SUCCESS 95and the callback handler is successfully registered. 96Otherwise, 97.Dv DDI_FAILURE 98is returned and the callback handler failed to register. 99Possible reasons include lack of resources or a bad cookie. 100.Sh INTERFACE STABILITY 101.Sy Committed 102.Sh SEE ALSO 103.Xr attributes 7 , 104.Xr ddi_get_eventcookie 9F , 105.Xr ddi_remove_event_handler 9F 106.Rs 107.%T Writing Device Drivers 108.Re 109.Sh NOTES 110Drivers must remove all registered callback handlers for a device instance by 111calling 112.Xr ddi_remove_event_handler 9F 113before 114.Xr detach 9E 115completes. 116