Tribblix: manual page: ddi_fm_acc_err

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/ddifm.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

illumos DDI specific (illumos 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 function.

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
information 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_SERVICE_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