Kernel Functions for Drivers ddidevreportfault(9F)
NAME
ddidevreportfault - Report a hardware failure
SYNOPSIS
#include
#include
void ddidevreportfault (devinfot *dip,
ddifaultimpactt impact, ddifaultlocationt location,
const char *message );
INTERFACE LEVEL
Solaris DI specific (Solaris DI)
PARAMETERS
dip Pointer to the driver's devinfo structure to
which the fault report relates. (Normally the
caller's own devinfo pointer).
impact One of a set of enumerated values indicating
the impact of the fault on the device's ability
to provide normal service.
location One of a set of enumerated values indicating
the location of the fault, relative to the
hardware controlled by the driver specified by
dip.
message Text of the message describing the fault being
reported.
DESCRIPTION
This function provides a standardized mechanism through
which device drivers can report hardware faults. Use of
this reporting mechanism enables systems equipped with a
fault management system to respond to faults discovered by a
driver. On a suitably equipped system, this might include
automatic failover to an alternative device and/or schedul-
ing replacement of the faulty hardware.
The driver must indicate the impact of the fault being
reported on its ability to provide service by passing one of
the following values for the impact parameter:
SunOS 5.11 Last change: 13 August 1999 1
Kernel Functions for Drivers ddidevreportfault(9F)
DISERVICELOST Indicates a total loss of service.
The driver is unable to implement
the normal functions of its
hardware.
DISERVICEDEGRADED The driver is unable to provide
normal service, but can provide a
partial or degraded level of ser-
vice. The driver may have to make
repeated attempts to perform an
operation before it succeeds, or
it may be running at less than its
configured speed. A driver may use
this value to indicate that an
alternative device should be used
if available, but that it can con-
tinue operation if no alternative
exists.
DISERVICEUNAFECTED The service provided by the device
is currently unaffected by the
reported fault. This value may be
used to report recovered errors
for predictive failure analysis.
DISERVICERESTORED The driver has resumed normal ser-
vice, following a previous report
that service was lost or degraded.
This message implies that any pre-
viously reported fault condition
no longer exists.
The location parameter should be one of the following
values:
DIDATAPATHFAULT The fault lies in the datapath between
the driver and the device. The device
may be unplugged, or a problem may
exist in the bus on which the device
resides. This value is appropriate if
the device is not responding to
accesses, (for example, the device may
not be present) or if a call to
ddicheckacchandle(9F) returns
DIFAILURE.
SunOS 5.11 Last change: 13 August 1999 2
Kernel Functions for Drivers ddidevreportfault(9F)
DIDEVICEFAULT The fault lies in the device con-
trolled by the driver. This value is
appropriate if the device returns an
error from a selftest function, or if
the driver is able to determine that
device is present and accessible, but
is not functioning correctly.
DIEXTERNALFAULT The fault is external to the device.
For example, an Ethernet driver would
use this value when reporting a cable
fault.
If a device returns detectably bad
data during normal operation (an
"impossible" value in a register or
DMA status area, for example), the
driver should check the associated
handle using ddicheckacchandle(9F)
or ddicheckdmahandle(9F) before
reporting the fault. If the fault is
associated with the handle, the driver
should specify DIDATAPATHFAULT
rather than DIDEVICEFAULT. As a
consequence of this call, the device's
state may be updated to reflect the
level of service currently available.
See ddigetdevstate(9F).
Note that if a driver calls
ddigetdevstate(9F) and discovers
that its device is down, a fault
should not be reported- the device is
down as the result of a fault that has
already been reported. Additionally, a
driver should avoid incurring or
reporting additional faults when the
device is already known to be unus-
able. The ddidevreportfault() call
should only be used to report hardware
(device) problems and should not be
used to report purely software prob-
lems such as memory (or other
resource) exhaustion.
EXAMPLES
An Ethernet driver receives an error interrupt from its dev-
ice if various fault conditions occur. The driver must read
an error status register to determine the nature of the
fault, and report it appropriately:
SunOS 5.11 Last change: 13 August 1999 3
Kernel Functions for Drivers ddidevreportfault(9F)
static int
xxerrorintr(xxsoftstate *ssp)
{
...
errorstatus = ddiget32(ssp->handle, &ssp->regs->xxerrstatus);
if (ddicheckacchandle(ssp->handle) != DISUCES) {
ddidevreportfault(ssp->dip, DISERVICELOST,
DIDATAPATHFAULT, "register access fault");
return DINTRUNCLAIMED;
}
if (ssp->errorstatus & XCABLEFAULT) {
ddidevreportfault(ssp->dip, DISERVICELOST,
DIEXTERNALFAULT, "cable fault")
return DINTRCLAIMED;
}
if (ssp->errorstatus & XJABER) {
ddidevreportfault(ssp->dip, DISERVICEDEGRADED,
DIEXTERNALFAULT, "jabbering detected")
return DINTRCLAIMED;
}
...
}
CONTEXT
The ddidevreportfault() function may be called from user,
kernel, or interrupt context.
SEE ALSO
ddicheckacchandle(9F), ddicheckdmahandle(9F),
ddigetdevstate(9F)
SunOS 5.11 Last change: 13 August 1999 4
|
