#ident "@(#)ddi_cb_register.9f 1.5 08/10/07 SMI" Kernel Functions for Device Drivers ddi_cb_register(9F) NAME ddi_cb_register, ddi_cb_unregister - register and unregister a device driver callback handler SYNOPSIS #include int ddi_cb_register(dev_info_t *dip, ddi_cb_flags_t flags, ddi_cb_func_t cbfunc, void *arg1, void *arg2, ddi_cb_handle_t *ret_hdlp); int ddi_cb_unregister(ddi_cb_handle_t hdl); INTERFACE LEVEL Solaris DDI specific (Solaris DDI). PARAMETERS ddi_cb_register() dip Pointer to the dev_info structure flags Flags to determine which callback events can be handled cbfunc Callback handler function arg1 First argument for the callback handler arg2 Second, optional, argument for the callback handler ret_hdlp Pointer to return a handle to the registered callback ddi_cb_unregister() hdl Handle to the registered callback to unregister DESCRIPTION The ddi_cb_register() function is used by a device driver to install a callback handler which can then process various actions that require the driver's attention while it is attached. The driver specifies through the flags parameter which callback actions it can handle. Upon each relevant action, the specified callback function will be passed the arguments arg1 and arg2 along with the description of each callback event. The ddi_cb_unregister() function will then uninstall a previously installed callback handler and prevent future processing of actions. The flags parameter should be the following: DDI_CB_FLAG_INTR The device driver participates in interrupt resource management. It may receive additional interrupt resources from the system, but only because it can accept callback notices informing it when it has more or less resources available. Callback notices can occur at anytime after the driver is attached. And interrupt availability varies based on the overall needs of the system. The cbfunc parameter is a callback handler with the following prototype: typedef int (*ddi_cb_func_t)(dev_info_t *dip, ddi_cb_action_t action, void *cbarg, void *arg1, void *arg2); The routine cbfunc with the arguments dip, action, cbarg, arg1 and arg2 is called upon receipt of any callbacks for which the driver is registered. The callback handler should return DDI_SUCCESS if the callback was handled successfully, DDI_ENOTSUP if it received a callback action that it did not know how to process, or DDI_FAILURE if it has an internal failure while processing an action. The action parameter is one of the following: DDI_CB_INTR_ADD For interrupt resource management, the driver has more available interrupts. Using ddi_intr_alloc(9F), it can allocate more interrupt vectors and then setup more interrupt handling functions. DDI_CB_INTR_REMOVE For interrupt resource management, the driver has fewer available interrupts. Using ddi_intr_free(9F), it must release any previously allocated interrupts in excess of what is now available. The cbarg parameter points to an action specific argument. Each class of registered actions will specify its own data structure that a callback handler should dereference when it receives those actions. The cbarg parameter is defined as an integer in the case of DDI_CB_INTR_ADD and DDI_CB_INTR_REMOVE actions. The callback handler should cast the cbarg parameter to an (int). The integer represents how many interrupts have been added or removed from the total number available to the device driver. If a driver participates in interrupt resource management, it must register a callback with the DDI_CB_FLAG_INTR flag. It will then receive the actions DDI_CB_INTR_ADD and DDI_CB_INTR_REMOVE whenever its interrupt availability has changed. The callback handler should use the interrupt functions ddi_intr_alloc(9F) and ddi_intr_free(9F) functions to respond accordingly. A driver is not required to allocate all interrupts that are available to it. But it is required to manage its allocations so that it never uses more interrupts than are currently available. RETURN VALUES The ddi_cb_register() and ddi_cb_unregister() functions return: DDI_SUCCESS On success. DDI_EINVAL An invalid parameter was given when registering a callback handler. Or an invalid handle was given when unregistering. DDI_EALREADY An attempt was made to register a callback handler while a previous registration still exists. The cbfunc routine must return: DDI_SUCCESS On success. DDI_ENOTSUP On device not supporting operation. DDI_FAILURE On any implementation specific failure. EXAMPLES /* * attach(9F) routine. * * Creates soft state, registers callback handler, initializes * hardware, and sets up interrupt handling for the driver. */ xx_attach(dev_info_t *dip, ddi_attach_cmd_t cmd) { xx_state_t *statep = NULL; xx_intr_t *intrs = NULL; ddi_intr_handle_t *hdls; ddi_cb_handle_t cb_hdl; int instance; int type; int types; int nintrs; int nactual; int inum; /* Get device instance */ instance = ddi_get_instance(dip); switch (cmd) { case DDI_ATTACH: /* Get soft state */ if (ddi_soft_state_zalloc(state_list, instance) != 0) return (DDI_FAILURE); statep = ddi_get_soft_state(state_list, instance); ddi_set_driver_private(dip, (caddr_t)statep); statep->dip = dip; /* Initialize hardware */ xx_initialize(statep); /* Register callback handler */ if (ddi_cb_register(dip, DDI_CB_FLAG_INTR, xx_cbfunc, statep, NULL, &cb_hdl) != 0) { ddi_soft_state_free(state_list, instance); return (DDI_FAILURE); } statep->cb_hdl = cb_hdl; /* Select interrupt type */ ddi_intr_get_supported_types(dip, &types); if (types & DDI_INTR_TYPE_MSIX) { type = DDI_INTR_TYPE_MSIX; } else if (types & DDI_INTR_TYPE_MSI) { type = DDI_INTR_TYPE_MSI; } else { type = DDI_INTR_TYPE_FIXED; } statep->type = type; /* Get number of supported interrupts */ ddi_intr_get_nintrs(dip, type, &nintrs); /* Allocate interrupt handle array */ hdls = kmem_zalloc(nintrs * sizeof (ddi_intr_handle_t), KMEM_SLEEP); statep->hdls = hdls; /* Allocate interrupt setup array */ intrs = kmem_zalloc(nintrs * sizeof (xx_intr_t), KMEM_SLEEP); statep->intrs = intrs; /* Allocate interrupt vectors */ ddi_intr_alloc(dip, hdls, type, 0, nintrs, &nactual, 0); statep->nactual = nactual; /* Configure interrupt handling */ xx_setup_interrupts(statep, nactual, statep->intrs); /* Install and enable interrupt handlers */ for (inum = 0; inum < nactual; inum++) { ddi_intr_add_handler(&hdls[inum], intrs[inum].inthandler, intrs[inum].arg1, intrs[inum].arg2); ddi_intr_enable(hdls[inum]); } break; case DDI_RESUME: /* Get soft state */ statep = ddi_get_soft_state(state_list, instance); if (statep == NULL) return (DDI_FAILURE); /* Resume hardware */ xx_resume(statep); break; } return (DDI_SUCESS); } /* * detach(9F) routine. * * Stops the hardware, disables interrupt handling, unregisters * a callback handler, and destroys the soft state for the driver. */ xx_detach(dev_info_t *dip, ddi_detach_cmd_t cmd) { xx_state_t *statep = NULL; int instance; int inum; /* Get device instance */ instance = ddi_get_instance(dip); switch (cmd) { case DDI_DETACH: /* Get soft state */ statep = ddi_get_soft_state(state_list, instance); if (statep == NULL) return (DDI_FAILURE); /* Stop device */ xx_uninitialize(statep); /* Disable interrupts */ for (inum = 0; inum < statep->nactual; inum++) { ddi_intr_disable(statep->hdls[inum]); ddi_intr_remove_handler(statep->hdls[inum]); } /* Unregister callback handler */ ddi_cb_unregister(statep->cb_hdl); /* Free soft state */ ddi_soft_state_free(state_list, instance); break; case DDI_SUSPEND: /* Get soft state */ statep = ddi_get_soft_state(state_list, instance); if (statep == NULL) return (DDI_FAILURE); /* Suspend hardware */ xx_quiesce(statep); break; } return (DDI_SUCCESS); } /* * (*ddi_cbfunc)() routine. * * Adapt interrupt usage when availability changes. */ int xx_cbfunc(dev_info_t *dip, ddi_cb_action_t cbaction, void *cbarg, void *arg1, void *arg2) { xx_state_t *statep = (xx_state_t *)arg1; int count; int inum; int nactual; switch (cbaction) { case DDI_CB_INTR_ADD: case DDI_CB_INTR_REMOVE: /* Get change in availability */ count = (int)(uintptr_t)cbarg; /* Suspend hardware */ xx_quiesce(statep); /* Tear down previous interrupt handling */ for (inum = 0; inum < statep->nactual; inum++) { ddi_intr_disable(statep->hdls[inum]); ddi_intr_remove_handler(statep->hdls[inum]); } /* Adjust interrupt vector allocations */ if (cbaction == DDI_CB_INTR_ADD) { /* Allocate additional interrupt vectors */ ddi_intr_alloc(dip, statep->hdls, statep->type, statep->nactual, count, &nactual, 0); /* Update actual count of available interrupts */ statep->nactual += nactual; } else { /* Free removed interrupt vectors */ for (inum = statep->nactual - count; inum < statep->nactual; inum++) { ddi_intr_free(statep->hdls[inum]); } /* Update actual count of available interrupts */ statep->nactual -= count; } /* Configure interrupt handling */ xx_setup_interrupts(statep, statep->nactual, statep->intrs); /* Install and enable interrupt handlers */ for (inum = 0; inum < nactual; inum++) { ddi_intr_add_handler(&hdls[inum], intrs[inum].inthandler, intrs[inum].arg1, intrs[inum].arg2); ddi_intr_enable(hdls[inum]); } /* Resume hardware */ xx_resume(statep); break; default: return (DDI_ENOTSUP); } return (DDI_SUCCESS); } ATTRIBUTES See attributes(5) for descriptions of the following attributes: ____________________________________________________________ | ATTRIBUTE TYPE | ATTRIBUTE VALUE | |___________________________|________________________________| | Interface Stability | Consolidation Private | |___________________________|________________________________| | MT-Level | MT-Safe | |___________________________|________________________________| SEE ALSO attributes(5), ddi_intr_alloc(9F) ddi_intr_free(9F), ddi_intr_set_nreq(9F) NOTES Consumers of these interfaces that register for DDI_CB_FLAG_INTR become participants in interrupt resource management. With that participation comes a responsibility to properly adjust interrupt usage. In the case of a DDI_CB_INTR_ADD action, the system guarantees that a driver can allocate a total number of interrupt resources up to its new number of available interrupts. The total number of interrupt resources is the sum of all resources allocated by the function ddi_intr_alloc(9F), minus all previously released by the function ddi_intr_free(9F). In the case of a DDI_CB_INTR_REMOVE action, the driver might have more interrupts allocated than are now currently available. It is necessary for the driver to release the excess interrupts, or else it will have a negative impact on the interrupt availability for other drivers in the system. A failure to release interrupts in response to a DDI_CB_INTR_REMOVE callback will generate the following warning on the system console: WARNING: : failed to release interrupts for IRM (nintrs = ##, navail=##).