DOC HOME SITE MAP MAN PAGES GNU INFO SEARCH PRINT BOOK
 
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