ddi_fm_acc_err_get(9F)					   Kernel Functions for Drivers 				    ddi_fm_acc_err_get(9F)

NAME

       ddi_fm_acc_err_get, ddi_fm_dma_err_get - get the error status for an access or DMA handle

SYNOPSIS

       #include <sys/ndifma.h>

       void ddi_fm_acc_err_get(ddi_acc_handle_t acc_handle,
	    ddi_fm_error_t *error_status, int version);

       void ddi_fm_dma_err_get(ddi_dma_handle_t dma_handle,
	    ddi_fm_error_t *error_status, int version);

INTERFACE LEVEL

       Solaris DDI specific (Solaris DDI)

PARAMETERS

       acc_handle      Data  access  handle  obtained from a previous call to ddi_regs_map_setup(9F), ddi_dma_mem_alloc(9F), or to a similar func-
		       tion.

       dma_handle      DMA handle obtained from a previous call to ddi_dma_mem_alloc(9F) or one of its derivatives.

       error_status    Pointer to where the error status for the access or DMA handle should be returned.

       version	       Version number of ddi_fm_error_t. The driver should always set this to DDI_FME_VERSION.

DESCRIPTION

       The ddi_fm_dma_err_get() and ddi_fm_acc_err_get() functions return the error status for a DMA or access handle respectively. If a fault has
       occurred  that affects the resource mapped by the supplied handle, the supplied error_status structure is updated to reflect error informa-
       tion captured during error handling by a bus or other device driver in the I/O data path.

       If an error is indicated for an access handle, the driver might no longer be able to access the mapped registers or memory using programmed
       I/O  through  the handle. Typically, this might occur after the device has failed to respond to an I/O access - in the case of a bus error,
       for instance, or a timeout. The effect of programmed I/O access made at the time of a fault is undefined. Read access via ddi_get8(9F), for
       example, can return random values, while write access via ddi_put8(9F) might or might not have an effect. It is possible, however, that the
       error might be transient. In that case, the driver can attempt to recover by calling ddi_fm_acc_err_clear(), resetting the device to return
       it to a known state, then retrying any potentially failed transactions.

       If  an error is indicated for a DMA handle, it implies that an error has been detected that has or will affect DMA transactions between the
       device and the memory currently bound to the handle - or the memory most recently bound, if  the  handle  is  currently	unbound.  Possible
       causes  include	the failure of a component in the DMA data path or an attempt by the device to make an invalid DMA access. The contents of
       any memory currently or previously bound to the handle should be considered indeterminate. The driver might be able to continue by  freeing
       memory  that  is  bound to the handle back to the system, resetting the device to return it to a known state, then retrying any potentially
       failed transactions.

       If the driver is unable to recover, the operating state should be changed by a call  to	ddi_fm_service_impact()  that  specifies  DDI_SER-
       VICE_LOST  for  the impacted device instance. If the recovery and retry succeed, a call should still be made to ddi_fm_service_impact() but
       DDI_SERVICE_UNAFFECTED should be specified.

CONTEXT

       The ddi_fm_acc_err_get() and ddi_fm_dma_err_get() functions can be called from user, kernel, or high-level interrupt context.

ATTRIBUTES

       See attributes(5) for descriptions of the following attributes:

       +-----------------------------+-----------------------------+
       |      ATTRIBUTE TYPE	     |	    ATTRIBUTE VALUE	   |
       +-----------------------------+-----------------------------+
       |Interface Stability	     |Committed 		   |
       +-----------------------------+-----------------------------+

SEE ALSO

       attributes(5), ddi_dma_mem_alloc(9F), ddi_fm_acc_err_clear(9F), ddi_fm_service_impact(9F),  ddi_get8(9F),  ddi_put8(9F),  ddi_regs_map_set-
       up(9F), ddi_fm_error(9S),

       Writing Device Drivers

SunOS 5.11							    13 May 2007 					    ddi_fm_acc_err_get(9F)