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)