ddi_fm_acc_err_get(9f)

1ddi_fm_acc_err_get(9F)   Kernel Functions for Drivers   ddi_fm_acc_err_get(9F)
2
3
4

NAME

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

SYNOPSIS

10       #include <sys/ndifma.h>
11
12       void ddi_fm_acc_err_get(ddi_acc_handle_t acc_handle,
13            ddi_fm_error_t *error_status, int version);
14
15
16       void ddi_fm_dma_err_get(ddi_dma_handle_t dma_handle,
17            ddi_fm_error_t *error_status, int version);
18
19

INTERFACE LEVEL

21       Solaris DDI specific (Solaris DDI)
22

PARAMETERS

24       acc_handle      Data access handle obtained from  a  previous  call  to
25                       ddi_regs_map_setup(9F),  ddi_dma_mem_alloc(9F), or to a
26                       similar function.
27
28
29       dma_handle      DMA  handle  obtained   from   a   previous   call   to
30                       ddi_dma_mem_alloc(9F) or one of its derivatives.
31
32
33       error_status    Pointer to where the error status for the access or DMA
34                       handle should be returned.
35
36
37       version         Version number of  ddi_fm_error_t.  The  driver  should
38                       always set this to DDI_FME_VERSION.
39
40

DESCRIPTION

42       The  ddi_fm_dma_err_get() and ddi_fm_acc_err_get() functions return the
43       error status for a DMA or access handle respectively. If  a  fault  has
44       occurred  that  affects the resource mapped by the supplied handle, the
45       supplied error_status structure is updated to reflect error information
46       captured  during  error handling by a bus or other device driver in the
47       I/O data path.
48
49
50       If an error is indicated for an access  handle,  the  driver  might  no
51       longer  be  able  to  access  the mapped registers or memory using pro‐
52       grammed I/O through the handle. Typically, this might occur  after  the
53       device  has  failed  to respond to an I/O access - in the case of a bus
54       error, for instance, or a timeout. The effect of programmed I/O  access
55       made at the time of a fault is undefined. Read access via ddi_get8(9F),
56       for  example,  can  return  random  values,  while  write  access   via
57       ddi_put8(9F)  might  or  might not have an effect. It is possible, how‐
58       ever, that the error might be transient. In that case, the  driver  can
59       attempt  to  recover  by  calling ddi_fm_acc_err_clear(), resetting the
60       device to return it to a known state,  then  retrying  any  potentially
61       failed transactions.
62
63
64       If an error is indicated for a DMA handle, it implies that an error has
65       been detected that has or will  affect  DMA  transactions  between  the
66       device  and  the  memory  currently bound to the handle - or the memory
67       most recently bound, if  the  handle  is  currently  unbound.  Possible
68       causes  include  the  failure of a component in the DMA data path or an
69       attempt by the device to make an invalid DMA access.  The  contents  of
70       any  memory  currently or previously bound to the handle should be con‐
71       sidered indeterminate. The driver might be able to continue by  freeing
72       memory  that  is  bound to the handle back to the system, resetting the
73       device to return it to a known state,  then  retrying  any  potentially
74       failed transactions.
75
76
77       If  the  driver  is  unable  to  recover, the operating state should be
78       changed by a call to ddi_fm_service_impact()  that  specifies  DDI_SER‐
79       VICE_LOST  for  the impacted device instance. If the recovery and retry
80       succeed, a call should still be  made  to  ddi_fm_service_impact()  but
81       DDI_SERVICE_UNAFFECTED should be specified.
82

CONTEXT

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

ATTRIBUTES

88       See attributes(5) for descriptions of the following attributes:
89
90
91
92
93       ┌─────────────────────────────┬─────────────────────────────┐
94       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
95       ├─────────────────────────────┼─────────────────────────────┤
96       │Interface Stability          │Committed                    │
97       └─────────────────────────────┴─────────────────────────────┘
98