SVR5
drv_callback(D3)
drv_callback --
call a function when an exceptional event happens
Synopsis
#include <sys/f_ddi.h>
void drv_callback(int event, int (*func)(), void *arg)
Description
Arguments
event -
The event for which the handler is to be registered
or unregistered.
The existing set of events are:
MCA_ATTACH-
Register an MCA (machine-check) handler.
MCA_DETACH-
Unregister an MCA (machine-check) handler.
NMI_ATTACH-
Register an NMI interrupt handler.
NMI_DETACH-
Unregister an NMI interrupt handler.
POWERDOWN_ATTACH-
Register a power-down handler.
POWERDOWN_DETACH-
Unregister a power-down handler.
WATCHDOG_ALIVE_ATTACH-
Register a watchdog keep-alive handler.
WATCHDOG_ALIVE_DETACH-
Unregister a watchdog keep-alive handler.
func-
Function or driver routine to be called when
the event happens.
arg-
Argument to the function to be called when an
event happens.
Usage
drv_callback is most commonly called during driver
init(D2)
or
_load(D2)
and
halt(D2)
or
_unload(D2)
routines to register and unregister, respectively, event handlers.
When a driver has an event handler that needs to be called
when either an external hardware or software event happens
it can register the event handler with the base kernel.
The base kernel, upon receipt of the event, does the necessary
preprocessing and calls the handler to service the event.
There can be multiple handlers for the same event.
All of the attached handlers of the given type will be called when an
event occurs.
Handlers remain attached until the corresponding detach operation is
invoked with the same func and arg.
Loadable drivers must be sure to detach all handlers before being
unloaded (e.g. in their _unload routines).
Event handlers are called with a single argument which is
the arg value passed to drv_callback,
with the exception of MCA handlers
which have an additional second
argument that is a pointer to an
mca_info(D4)
structure
Return values (MCA handlers)
MCA handlers are called
when a Machine Check condition occurs,
which may indicate a hardware problem
external to the CPU
or a problem in the CPU itself.
Machine Check is only supported on certain CPUs,
such as the Pentium Pro.
The mca_info passed
to the MCA handler gives details about the event.
On return from the handler,
the driver must no longer access the mca_info structure.
MCA handlers should return one of the following values:
MCA_UNKNOWN-
The driver could not recognize the machine check condition.
That is, the driver has checked its device's status
registers, and no check condition is indicated.
MCA_FATAL-
A fatal machine check has occurred.
The base kernel panics the system upon receipt of this return value
from the driver.
MCA_REBOOT-
The system will be shutdown, and a reboot will be triggered.
MCA_BENIGN-
A non-fatal machine check has occurred.
The base kernel continues after the reception of this
return value.
MCA_BUS_TIMEOUT-
The driver has detected a bus timeout or bus fault
condition.
This typically results from an attempt
to access non-existent physical memory.
Return values (NMI handlers)
NMI handlers are called when a Non-Maskable Interrupt occurs,
which may indicate an external (to the CPU) hardware problem.
NMI handlers should return one of the following values:
NMI_UNKNOWN-
The driver could not recognize the NMI interrupt.
That is, the driver has checked its device's status
registers, and no NMI condition is indicated.
NMI_FATAL-
A fatal NMI interrupt has occurred.
The base kernel panics the system upon receipt of this return value
from the driver.
NMI_REBOOT-
The system will be shutdown, and a reboot will be triggered.
NMI_BENIGN-
A non-fatal NMI interrupt has occurred.
The base kernel continues after the reception of this
return value.
NMI_BUS_TIMEOUT-
The driver has detected a bus timeout or bus fault
condition.
This typically results from an attempt
to access non-existent physical memory.
Return values (POWERDOWN handlers)
POWERDOWN handlers are called just before halting the system,
after all I/O has completed (including dumping the system memory image,
if applicable), to allow a power management driver to turn off system power.
POWERDOWN handlers should always return zero.
Return values (WATCHDOG_ALIVE handlers)
WATCHDOG_ALIVE handlers are called periodically
whenever the system is running
with interrupts disabled for a long period of time
(such as while using the kernel debugger).
This allows drivers that manage watchdog timers
to send keep-alive signals to their timers,
which they would normally do under control of some
interrupt-driven event.
WATCHDOG_ALIVE handlers should always return zero.
Context and synchronization
User or blockable
context.
Hardware applicability
PC-AT compatible architectures
Version applicability
For NMI_ATTACH, NMI_DETACH:-
ddi:
6, 6mp, 7, 7mp, 7.1, 7.1mp, 8mp
For all others:-
ddi: in HDK Technical Reference
7.1, 7.1mp, 8, 8mp
References
drv_shutdown(D3),
mca_info(D4)
19 June 2005
© 2005 The SCO Group, Inc. All rights reserved.
OpenServer 6 and UnixWare (SVR5) HDK - June 2005