ddi_dev_report_fault man page on SmartOS

Man page or keyword search:  
man Server   16655 pages
apropos Keyword Search (all sections)
Output format
SmartOS logo
[printable version]


       ddi_dev_report_fault - Report a hardware failure

       #include <sys/ddi.h>
       #include <sys/sunddi.h>

       void  ddi_dev_report_fault (dev_info_t	*dip,
	    ddi_fault_impact_t impact,	ddi_fault_location_t location,
	    const char	 *message );

       Solaris DDI specific (Solaris DDI)

		    Pointer  to	 the  driver's dev_info structure to which the
		    fault report relates. (Normally the caller's own  dev_info

		    One of a set of enumerated values indicating the impact of
		    the fault on the device's ability to provide  normal  ser‐

		    One	 of a set of enumerated values indicating the location
		    of the fault, relative to the hardware controlled  by  the
		    driver specified by dip.

		    Text of the message describing the fault being reported.

       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 sched‐
       uling 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:

				 Indicates a total loss of service. The driver
				 is  unable  to implement the normal functions
				 of its hardware.

				 The driver is unable to provide  normal  ser‐
				 vice,	but  can provide a partial or degraded
				 level of service. 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  alterna‐
				 tive  device should be used if available, but
				 that it can continue operation if no alterna‐
				 tive exists.

				 The  service  provided	 by the device is cur‐
				 rently unaffected by the reported fault. This
				 value	may be used to report recovered errors
				 for predictive failure analysis.

				 The driver has resumed normal	service,  fol‐
				 lowing	 a  previous  report  that service was
				 lost or degraded.  This message implies  that
				 any  previously  reported  fault condition no
				 longer exists.

       The location parameter should be one of the following values:

			     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
			     ddi_check_acc_handle(9F) returns DDI_FAILURE.

			     The fault lies in the device  controlled  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

			     The  fault	 is external to the device.  For exam‐
			     ple, 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 reg‐
			     ister  or	DMA  status  area,  for	 example), the
			     driver should check the associated	 handle	 using
			     ddi_check_acc_handle(9F)	or  ddi_check_dma_han‐
			     dle(9F) before reporting the fault. If the	 fault
			     is	 associated with the handle, the driver should
			     specify	 DDI_DATAPATH_FAULT    rather	  than
			     DDI_DEVICE_FAULT.	As a consequence of this call,
			     the device's state may be updated to reflect  the
			     level   of	  service   currently  available.  See

			     Note that if a driver calls  ddi_get_devstate(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    unusable.	   The
			     ddi_dev_report_fault()  call  should only be used
			     to report hardware (device) problems  and	should
			     not  be  used  to report purely software problems
			     such as memory (or other resource) exhaustion.

       An Ethernet driver receives an error interrupt from its device if vari‐
       ous  fault conditions occur.  The driver must read an error status reg‐
       ister to determine the nature of the fault,  and	 report	 it  appropri‐

	 static int
	 xx_error_intr(xx_soft_state *ssp)
	     error_status = ddi_get32(ssp->handle, &ssp->regs->xx_err_status);
	     if (ddi_check_acc_handle(ssp->handle) != DDI_SUCCESS) {
		 ddi_dev_report_fault(ssp->dip, DDI_SERVICE_LOST,
		     DDI_DATAPATH_FAULT, "register access fault");
	     if (ssp->error_status & XX_CABLE_FAULT) {
		 ddi_dev_report_fault(ssp->dip, DDI_SERVICE_LOST,
		     DDI_EXTERNAL_FAULT, "cable fault")
	     if (ssp->error_status & XX_JABBER) {
		 ddi_dev_report_fault(ssp->dip, DDI_SERVICE_DEGRADED,
		     DDI_EXTERNAL_FAULT, "jabbering detected")

       The ddi_dev_report_fault() function may be called from user, kernel, or
       interrupt context.

       ddi_check_acc_handle(9F),    ddi_check_dma_handle(9F),	 ddi_get_devs‐

				 Aug 13, 1999	      DDI_DEV_REPORT_FAULT(9F)

List of man pages available for SmartOS

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
Vote for polarhome
Free Shell Accounts :: the biggest list on the net