Print this page
4888 Undocument dma_req(9s)
4884 EOF scsi_hba_attach
4886 EOF ddi_dmae_getlim
4887 EOF ddi_iomin
4634 undocument scsi_hba_attach() and ddi_dma_lim(9s)
4630 clean stale references to ddi_iopb_alloc and ddi_iopb_free
| Split |
Close |
| Expand all |
| Collapse all |
--- old/usr/src/man/man9f/ddi_check_acc_handle.9f
+++ new/usr/src/man/man9f/ddi_check_acc_handle.9f
1 1 '\" te
2 +.\" Copyright 2014 Garrett D'Amore <garrett@damore.org>
2 3 .\" Copyright (c) 1999, Sun Microsystems, Inc. All Rights Reserved
3 4 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License.
4 5 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License.
5 6 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
6 -.TH DDI_CHECK_ACC_HANDLE 9F "Aug 13, 1999"
7 +.TH DDI_CHECK_ACC_HANDLE 9F "May 24, 2014"
7 8 .SH NAME
8 9 ddi_check_acc_handle, ddi_check_dma_handle \- Check data access and DMA handles
9 10 .SH SYNOPSIS
10 11 .LP
11 12 .nf
12 13 #include <sys/ddi.h>
13 14 #include <sys/sunddi.h>
14 15
15 16
16 17
17 18 \fBint\fR \fBddi_check_acc_handle\fR(\fBddi_acc_handle_t\fR \fI acc_handle\fR );
18 19 .fi
19 20
20 21 .LP
21 22 .nf
22 23 \fBint\fR \fBddi_check_dma_handle\fR(\fBddi_dma_handle_t\fR \fIdma_handle\fR );
23 24 .fi
24 25
25 26 .SH INTERFACE LEVEL
26 27 .sp
27 28 .LP
28 29 Solaris DDI specific (Solaris DDI)
29 30 .SH PARAMETERS
30 31 .sp
31 32 .ne 2
32 33 .na
33 34 \fB\fIacc_handle\fR \fR
34 35 .ad
35 36 .RS 15n
|
↓ open down ↓ |
19 lines elided |
↑ open up ↑ |
36 37 Data access handle obtained from a previous call to
37 38 \fBddi_regs_map_setup\fR(9F), \fBddi_dma_mem_alloc\fR(9F), or similar function.
38 39 .RE
39 40
40 41 .sp
41 42 .ne 2
42 43 .na
43 44 \fB\fIdma_handle\fR \fR
44 45 .ad
45 46 .RS 15n
46 -DMA handle obtained from a previous call to \fBddi_dma_setup\fR(9F) or one of
47 -its derivatives.
47 +DMA handle obtained from \fBddi_dma_alloc_handle\fP(9F).
48 48 .RE
49 49
50 50 .SH DESCRIPTION
51 51 .sp
52 52 .LP
53 53 The \fBddi_check_acc_handle()\fR\fB and ddi_check_dma_handle()\fR functions
54 54 check for faults that can interfere with communication between a driver and the
55 55 device it controls. Each function checks a single handle of a specific type and
56 56 returns a status value indicating whether faults affecting the resource mapped
57 57 by the supplied handle have been detected.
58 58 .sp
59 59 .LP
60 60 If a fault is indicated when checking a data access handle, this implies that
61 61 the driver is no longer able to access the mapped registers or memory using
62 62 programmed I/O through that handle. Typically, this might occur after the
63 63 device has failed to respond to an I/O access (for example, has incurred a bus
64 64 error or timed out). The effect of programmed I/O accesses made after this
65 65 happens is undefined; for example, read accesses (for example,
66 66 \fBddi_get8\fR(9F)) may return random values, and write accesses (for example,
67 67 \fBddi_put8\fR(9F)) may or may not have any effect. This type of fault is
68 68 normally fatal to the operation of the device, and the driver should report it
69 69 via \fBddi_dev_report_fault\fR(9F) specifying \fBDDI_SERVICE_LOST\fR for the
70 70 impact, and \fBDDI_DATAPATH_FAULT\fR for the location.
71 71 .sp
72 72 .LP
73 73 If a fault is indicated when checking a DMA handle, it implies that a fault has
74 74 been detected that has (or will) affect DMA transactions between the device and
75 75 the memory currently bound to the handle (or most recently bound, if the handle
76 76 is currently unbound). Possible causes include the failure of a component in
77 77 the DMA data path, or an attempt by the device to make an invalid DMA access.
78 78 The driver may be able to continue by falling back to a non-DMA mode of
79 79 operation, but in general, DMA faults are non-recoverable. The contents of the
80 80 memory currently (or previously) bound to the handle should be regarded as
81 81 indeterminate. The fault indication associated with the current transaction is
82 82 lost once the handle is (re-)bound, but because the fault may persist, future
83 83 DMA operations may not succeed.
84 84 .sp
85 85 .LP
86 86 Note that some implementations cannot detect all types of failure. If a fault
87 87 is not indicated, this does not constitute a guarantee that communication is
88 88 possible. However, if a check fails, this is a positive indication that a
89 89 problem \fBdoes\fR exist with respect to communication using that handle.
90 90 .SH RETURN VALUES
91 91 .sp
92 92 .LP
93 93 The \fBddi_check_acc_handle()\fR and \fBddi_check_dma_handle()\fR functions
94 94 return \fBDDI_SUCCESS\fR if no faults affecting the supplied handle are
95 95 detected and \fBDDI_FAILURE\fR if any fault affecting the supplied handle is
96 96 detected.
97 97 .SH EXAMPLES
98 98 .sp
99 99 .in +2
100 100 .nf
101 101 static int
102 102 xxattach(dev_info_t *dip, ddi_attach_cmd_t cmd)
103 103 {
104 104 \&...
105 105 /* This driver uses only a single register-access handle */
106 106 status = ddi_regs_map_setup(dip, REGSET_ZERO, ®addr,
107 107 0, 0, , &acc_attrs, &acc_hdl);
108 108 if (status != DDI_SUCCESS)
109 109 return (DDI_FAILURE);
110 110 \&...
111 111 }
112 112
113 113 static int
114 114 xxread(dev_t dev, struct uio *uio_p, cred_t *cred_p)
115 115 {
116 116 \&...
117 117 if (ddi_check_acc_handle(acc_hdl) != DDI_SUCCESS) {
118 118 ddi_dev_report_fault(dip, DDI_SERVICE_LOST,
119 119 DDI_DATAPATH_FAULT, "register access fault during read");
120 120 return (EIO);
121 121 }
122 122 \&...
123 123 .fi
|
↓ open down ↓ |
66 lines elided |
↑ open up ↑ |
124 124 .in -2
125 125
126 126 .SH CONTEXT
127 127 .sp
128 128 .LP
129 129 The \fBddi_check_acc_handle()\fR and \fBddi_check_dma_handle()\fR functions may
130 130 be called from user, kernel, or interrupt context.
131 131 .SH SEE ALSO
132 132 .sp
133 133 .LP
134 -\fBddi_regs_map_setup\fR(9F), \fBddi_dma_setup\fR(9F),
134 +\fBddi_regs_map_setup\fR(9F), \fBddi_dma_alloc_handle\fR(9F),
135 135 \fBddi_dev_report_fault\fR(9F), \fBddi_get8\fR(9F), \fBddi_put8\fR(9F)
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX