For ddi_get_soft_iblock_cookie():
ddi_get_soft_iblock_cookie() retrieves the interrupt block cookie associated with a particular soft interrupt preference level. This routine should be called before ddi_add_softintr() to retrieve the interrupt block cookie needed to initialize locks ( mutex(9F), rwlock(9F)) used by the software interrupt routine. preference determines which type of soft interrupt to retrieve the cookie for. The possible values for preference are:
-
DDI_SOFTINT_LOW
- Low priority soft interrupt.
-
DDI_SOFTINT_MED
- Medium priority soft interrupt.
-
DDI_SOFTINT_HIGH
- High priority soft interrupt.
On a successful return, iblock_cookiep contains information needed for initializing locks associated with this soft interrupt (see mutex_init(9F)
and rw_init(9F)). The driver can then initialize mutexes acquired by the interrupt routine before calling ddi_add_softintr() which prevents a possible race condition where
the driver's soft interrupt handler is called immediately after the driver has called ddi_add_softintr() but before the driver has initialized the mutexes. This can happen when a soft interrupt for a different device occurs on the same soft
interrupt priority level. If the soft interrupt routine acquires the mutex before it has been initialized, undefined behavior may result.
For ddi_add_softintr():
ddi_add_softintr() adds a soft interrupt to the system. The user specified hint preference identifies three suggested levels for the system to attempt to allocate the soft interrupt priority at. The value for preference should be the
same as that used in the corresponding call to ddi_get_soft_iblock_cookie(). Refer to the description of ddi_get_soft_iblock_cookie() above.
The value returned in the location pointed at by idp is the soft interrupt identifier. This value is used in later calls to ddi_remove_softintr() and ddi_trigger_softintr() to identify the soft interrupt and the soft interrupt handler.
The value returned in the location pointed at by iblock_cookiep is an interrupt block cookie which contains information used for initializing mutexes associated with this soft interrupt (see mutex_init(9F) and rw_init(9F)). Note that the interrupt block cookie is normally obtained using ddi_get_soft_iblock_cookie() to avoid
the race conditions described above (refer to the description of ddi_get_soft_iblock_cookie() above). For this reason, iblock_cookiep is no longer useful and should be set to NULL.
idevice_cookiep is not used and should be set to NULL.
The routine int_handler, with its argument int_handler_arg, is called upon receipt of a software interrupt. Software interrupt handlers must not assume that they have work to do when they run, since (like hardware interrupt handlers) they may run because
a soft interrupt occurred for some other reason. For example, another driver may have triggered a soft interrupt at the same level. For this reason, before triggering the soft interrupt, the driver must indicate to its soft interrupt handler that it should do work. This is usually done by setting a flag
in the state structure. The routine int_handler checks this flag, reachable through int_handler_arg, to determine if it should claim the interrupt and do its work.
The interrupt handler must return DDI_INTR_CLAIMED if the interrupt was claimed, DDI_INTR_UNCLAIMED otherwise.
If successful, ddi_add_softintr() will return DDI_SUCCESS; if the interrupt information cannot be found, it will return DDI_FAILURE.
For ddi_remove_softintr():
ddi_remove_softintr() removes a soft interrupt from the system. The soft interrupt identifier id, which was returned from a call to ddi_add_softintr(), is used to determine which soft interrupt and which soft interrupt handler to remove.
Drivers must remove any soft interrupt handlers before allowing the system to unload the driver.
For ddi_trigger_softintr():
ddi_trigger_softintr() triggers a soft interrupt. The soft interrupt identifier id is used to determine which soft interrupt to trigger. This function is used by device drivers when they wish to trigger a soft interrupt which has been set up using ddi_add_softintr().
|