ddi_check_acc_handle(9f)

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

NAME

6       ddi_check_acc_handle,  ddi_check_dma_handle - Check data access and DMA
7       handles
8

SYNOPSIS

10       #include <sys/ddi.h>
11       #include <sys/sunddi.h>
12
13
14
15       int ddi_check_acc_handle(ddi_acc_handle_t  acc_handle );
16
17
18       int ddi_check_dma_handle(ddi_dma_handle_t  dma_handle );
19
20

INTERFACE LEVEL

22       Solaris DDI specific (Solaris DDI)
23

PARAMETERS

25       acc_handle     Data access handle obtained  from  a  previous  call  to
26                      ddi_regs_map_setup(9F),  ddi_dma_mem_alloc(9F), or simi‐
27                      lar function.
28
29
30       dma_handle     DMA handle obtained from a previous call to ddi_dma_set‐
31                      up(9F) or one of its derivatives.
32
33

DESCRIPTION

35       The  ddi_check_acc_handle()  and ddi_check_dma_handle() functions check
36       for faults that can interfere with communication between a  driver  and
37       the  device it controls. Each function checks a single handle of a spe‐
38       cific type and returns a status value indicating whether faults affect‐
39       ing the resource mapped by the supplied handle have been detected.
40
41
42       If  a  fault  is  indicated  when  checking  a data access handle, this
43       implies that the driver is no longer able to access the  mapped  regis‐
44       ters  or  memory  using programmed I/O through that handle.  Typically,
45       this might occur after the device has  failed  to  respond  to  an  I/O
46       access (for example, has incurred a bus error or timed out). The effect
47       of programmed I/O accesses made after this happens  is  undefined;  for
48       example,  read  accesses  (for example, ddi_get8(9F)) may return random
49       values, and write accesses (for example, ddi_put8(9F)) may or  may  not
50       have  any effect. This type of fault is normally fatal to the operation
51       of   the   device,   and   the   driver   should    report    it    via
52       ddi_dev_report_fault(9F)  specifying  DDI_SERVICE_LOST  for the impact,
53       and DDI_DATAPATH_FAULT for the location.
54
55
56       If a fault is indicated when checking a DMA handle, it implies  that  a
57       fault  has  been  detected  that  has (or will) affect DMA transactions
58       between the device and the memory currently bound  to  the  handle  (or
59       most  recently  bound,  if  the  handle is currently unbound). Possible
60       causes include the failure of a component in the DMA data path,  or  an
61       attempt  by the device to make an invalid DMA access. The driver may be
62       able to continue by falling back to a non-DMA mode of operation, but in
63       general,  DMA  faults  are non-recoverable.  The contents of the memory
64       currently (or previously) bound to the handle  should  be  regarded  as
65       indeterminate.  The fault indication associated with the current trans‐
66       action is lost once the handle is (re-)bound, but because the fault may
67       persist, future DMA operations may not succeed.
68
69
70       Note that some implementations cannot detect all types of failure. If a
71       fault is not indicated, this does not constitute a guarantee that  com‐
72       munication  is  possible. However, if a check fails, this is a positive
73       indication that a problem does  exist  with  respect  to  communication
74       using that handle.
75

RETURN VALUES

77       The  ddi_check_acc_handle() and ddi_check_dma_handle() functions return
78       DDI_SUCCESS if no faults affecting the supplied handle are detected and
79       DDI_FAILURE if any fault affecting the supplied handle is detected.
80

EXAMPLES

82         static int
83         xxattach(dev_info_t *dip, ddi_attach_cmd_t cmd)
84         {
85             ...
86             /* This driver uses only a single register-access handle */
87             status = ddi_regs_map_setup(dip, REGSET_ZERO, &regaddr,
88                                         0, 0, , &acc_attrs, &acc_hdl);
89             if (status != DDI_SUCCESS)
90                 return (DDI_FAILURE);
91             ...
92         }
93
94         static int
95         xxread(dev_t  dev, struct uio *uio_p, cred_t *cred_p)
96         {
97             ...
98             if (ddi_check_acc_handle(acc_hdl) != DDI_SUCCESS) {
99                 ddi_dev_report_fault(dip, DDI_SERVICE_LOST,
100                     DDI_DATAPATH_FAULT, "register access fault during read");
101                 return (EIO);
102             }
103             ...
104
105

CONTEXT

107       The  ddi_check_acc_handle() and ddi_check_dma_handle() functions may be
108       called from user, kernel, or interrupt context.
109