Kernel Functions for Drivers ddifmhandlerregister(9F)
NAME
ddifmhandlerregister, ddifmhandlerunregister - regis-
ter or unregister an error handling callback
SYNOPSIS
#include
void ddifmhandlerregister(devinfot *dip,
ddierrfunct errorhandler, void *impldata);
void ddifmhandlerunregister(devinfot *dip);
INTERFACE LEVEL
Solaris DI specific (Solaris DI)
PARAMETERS
dip Pointer to the devinfo structure
errorhandler Pointer to an error handler callback func-
tion
impldata Pointer to private data for use by the
caller
DESCRIPTION
The ddifmhandlerregister() function registers an error
handler callback routine with the I/O Fault Management
framework. The error handler callback, errorhandler, is
called to process error conditions detected by the system.
In addition to its device instance, dip, the error handler
is called with a pointer to a fault management error status
structure, ddifmerrort. For example:
int (*ddierrfunct)(devinfot *dip, ddifmerrort *errorstatus);
A driver error handling callback is passed the following
arguments:
o a pointer to the device instance registered for
this callback.
o a data structure containing common fault management
data and status for error handling.
SunOS 5.11 Last change: 14 May 2007 1
Kernel Functions for Drivers ddifmhandlerregister(9F)
The primary responsibilities of the error handler include:
o to check for outstanding hardware or software
errors.
o where possible, to isolate the device that might
have caused the errors.
o to report errors that were detected.
During the invocation of an error handler, a device driver
might need to quiesce or suspend all I/O activities in order
to check for error conditions or status in:
o hardware control and status registers.
o outstanding I/O transactions.
o access or DMA handles.
For each error detected, the driver must formulate and post
an error report via ddifmereportpost() for problem
analysis by the Solaris Fault Manager fmd(1M).
For a PCI, PCI/X, or PCI Express leaf device, the
pciereportpost() function is provided to carry out report-
ing responsibilities on behalf of the driver. In many cases,
an error handler callback function of the following form can
be used:
xxxerrcb(devinfot *dip, ddifmerrort *errp) {
pciereportpost(dip, errp, NUL);
return (errp->fmestatus);
}
In addition, the driver might be able to carry out further
device specific checks within the error handler.
Error handlers can be called from kernel, interrupt, or
high-level interrupt context. The interrupt block cookie
returned from ddifminit() should be used to allocate and
initialize any synchronization variables and locks that
might be used within the error handler callback function.
Such locks may not be held by the driver when a device
register is accessed with functions such as ddiget8(9F) and
ddiput8(9F).
SunOS 5.11 Last change: 14 May 2007 2
Kernel Functions for Drivers ddifmhandlerregister(9F)
The data structure, ddifmerrort, contains an FMA protocol
(format 1) ENA for the current error propagation chain, the
status of the error handler callback, an error expectation
flag, and any potential access or DMA handles associated
with an error detected by the parent nexus.
The ddifmhandlerunregister() function removes a previ-
ously registered error handling callback for the device
instance specified by the dip.
CONTEXT
The ddifmhandlerregister() and
ddifmhandlerunregister() functions must be called from
kernel context in an attach(9E) or detach(9E) entry point.
The registered error handler, errorhandler, callback can be
called from kernel, interrupt, or high level interrupt con-
text.
ATRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
ATRIBUTE TYPE ATRIBUTE VALUE
Interface Stability Committed
SEE ALSO
fmd(1M), attributes(5), attach(9E), detach(9E),
ddifmereportpost(9F), ddifminit(9F), ddiget8(9F),
ddiput8(9F), pciereportpost(9F), ddifmerror(9S)
Writing Device Drivers
SunOS 5.11 Last change: 14 May 2007 3
|
