1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
|
'\" te
.\" Copyright (c) 2006, Sun Microsystems, Inc.
.\" 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.
.\" 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.
.\" 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]
.TH DDI_DMA_SETUP 9F "Jan 16, 2006"
.SH NAME
ddi_dma_setup \- setup DMA resources
.SH SYNOPSIS
.LP
.nf
#include <sys/ddi.h>
#include <sys/sunddi.h>
\fBint\fR \fBddi_dma_setup\fR(\fBdev_info_t *\fR\fIdip\fR, \fBddi_dma_req_t *\fR\fIdmareqp\fR,
\fBddi_dma_handle_t *\fR\fIhandlep\fR);
.fi
.SH INTERFACE LEVEL
.sp
.LP
This interface is obsolete. The functions \fBddi_dma_addr_bind_handle\fR(9F),
\fBddi_dma_alloc_handle\fR(9F), \fBddi_dma_buf_bind_handle\fR(9F),
\fBddi_dma_free_handle\fR(9F), and \fBddi_dma_unbind_handle\fR(9F) should be
used instead.
.SH PARAMETERS
.sp
.ne 2
.na
\fB\fIdip\fR\fR
.ad
.RS 11n
A pointer to the device's \fBdev_info\fR structure.
.RE
.sp
.ne 2
.na
\fB\fIdmareqp\fR\fR
.ad
.RS 11n
A pointer to a \fBDMA\fR request structure (see \fBddi_dma_req\fR(9S)).
.RE
.sp
.ne 2
.na
\fB\fIhandlep\fR\fR
.ad
.RS 11n
A pointer to a \fBDMA\fR handle to be filled in. See below for a discussion of
a handle. If \fIhandlep\fR is \fINULL\fR, the call to \fBddi_dma_setup()\fR is
considered an advisory call, in which case no resources are allocated, but a
value indicating the legality and the feasibility of the request is returned.
.RE
.SH DESCRIPTION
.sp
.LP
The \fBddi_dma_setup()\fR function allocates resources for a memory object such
that a device can perform \fBDMA\fR to or from that object.
.sp
.LP
A call to \fBddi_dma_setup()\fR informs the system that device referred to by
\fIdip\fR wishes to perform \fBDMA\fR to or from a memory object. The memory
object, the device's \fBDMA\fR capabilities, the device driver's policy on
whether to wait for resources, are all specified in the \fBddi_dma_req\fR
structure pointed to by \fIdmareqp\fR.
.sp
.LP
A successful call to \fBddi_dma_setup()\fR fills in the value pointed to by
\fIhandlep\fR. This is an opaque object called a \fBDMA\fR handle. This handle
is then used in subsequent \fBDMA\fR calls, until \fBddi_dma_free\fR(9F) is
called.
.sp
.LP
Again a \fBDMA\fR handle is opaque\(emdrivers may \fBnot\fR attempt to
interpret its value. When a driver wants to enable its \fBDMA\fR engine, it
must retrieve the appropriate address to supply to its \fBDMA\fR engine using a
call to \fBddi_dma_htoc\fR(9F), which takes a pointer to a \fBDMA\fR handle
and returns the appropriate \fBDMA\fR address.
.sp
.LP
When \fBDMA\fR transfer completes, the driver should free up the allocated
\fBDMA\fR resources by calling \fBddi_dma_free()\fR
.SH RETURN VALUES
.sp
.LP
The \fBddi_dma_setup()\fR function returns:
.sp
.ne 2
.na
\fB\fBDDI_DMA_MAPPED\fR\fR
.ad
.RS 23n
Successfully allocated resources for the object. In the case of an
\fBadvisory\fR call, this indicates that the request is legal.
.RE
.sp
.ne 2
.na
\fB\fBDDI_DMA_PARTIAL_MAP\fR\fR
.ad
.RS 23n
Successfully allocated resources for a \fBpart\fR of the object. This is
acceptable when partial transfers are allowed using a flag setting in the
\fBddi_dma_req\fR structure (see \fBddi_dma_req\fR(9S) and
\fBddi_dma_movwin\fR(9F)).
.RE
.sp
.ne 2
.na
\fB\fBDDI_DMA_NORESOURCES\fR\fR
.ad
.RS 23n
When no resources are available.
.RE
.sp
.ne 2
.na
\fB\fBDDI_DMA_NOMAPPING\fR\fR
.ad
.RS 23n
The object cannot be reached by the device requesting the resources.
.RE
.sp
.ne 2
.na
\fB\fBDDI_DMA_TOOBIG\fR\fR
.ad
.RS 23n
The object is too big and exceeds the available resources. The maximum size
varies depending on machine and configuration.
.RE
.SH CONTEXT
.sp
.LP
The \fBddi_dma_setup()\fR function can be called from user, interrupt, or
kernel context, except when the \fBdmar_fp\fR member of the \fBddi_dma_req\fR
structure pointed to by \fIdmareqp\fR is set to \fBDDI_DMA_SLEEP\fR, in which
case it cannot be called from interrupt context.
.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(5) for a description of the following attributes:
.sp
.sp
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE ATTRIBUTE VALUE
_
Stability Level Obsolete
.TE
.SH SEE ALSO
.sp
.LP
\fBattributes\fR(5), \fBddi_dma_addr_bind_handle\fR(9F),
\fBddi_dma_alloc_handle\fR(9F), \fBddi_dma_buf_bind_handle\fR(9F),
\fBddi_dma_free_handle\fR(9F),
\fBddi_dma_unbind_handle\fR(9F)\fBddi_dma_addr_setup\fR(9F),
\fBddi_dma_buf_setup\fR(9F), \fBddi_dma_free\fR(9F), \fBddi_dma_htoc\fR(9F),
\fBddi_dma_movwin\fR(9F), \fBddi_dma_sync\fR(9F), \fBddi_dma_req\fR(9S)
.sp
.LP
\fIWriting Device Drivers\fR
.SH NOTES
.sp
.LP
The construction of the \fBddi_dma_req\fR structure is complicated. Use of the
provided interface functions such as \fBddi_dma_buf_setup\fR(9F) simplifies
this task.
|
