1ddi_dma_setup(9F) Kernel Functions for Drivers ddi_dma_setup(9F)
2
3
4
6 ddi_dma_setup - setup DMA resources
7
9 #include <sys/ddi.h>
10 #include <sys/sunddi.h>
11
12
13
14 int ddi_dma_setup(dev_info_t *dip, ddi_dma_req_t *dmareqp,
15 ddi_dma_handle_t *handlep);
16
17
19 This interface is obsolete. The functions ddi_dma_addr_bind_handle(9F),
20 ddi_dma_alloc_handle(9F), ddi_dma_buf_bind_handle(9F),
21 ddi_dma_free_handle(9F), and ddi_dma_unbind_handle(9F) should be used
22 instead.
23
25 dip A pointer to the device's dev_info structure.
26
27
28 dmareqp A pointer to a DMA request structure (see ddi_dma_req(9S)).
29
30
31 handlep A pointer to a DMA handle to be filled in. See below for a
32 discussion of a handle. If handlep is NULL, the call to
33 ddi_dma_setup() is considered an advisory call, in which
34 case no resources are allocated, but a value indicating the
35 legality and the feasibility of the request is returned.
36
37
39 The ddi_dma_setup() function allocates resources for a memory object
40 such that a device can perform DMA to or from that object.
41
42
43 A call to ddi_dma_setup() informs the system that device referred to by
44 dip wishes to perform DMA to or from a memory object. The memory
45 object, the device's DMA capabilities, the device driver's policy on
46 whether to wait for resources, are all specified in the ddi_dma_req
47 structure pointed to by dmareqp.
48
49
50 A successful call to ddi_dma_setup() fills in the value pointed to by
51 handlep. This is an opaque object called a DMA handle. This handle is
52 then used in subsequent DMA calls, until ddi_dma_free(9F) is called.
53
54
55 Again a DMA handle is opaque—drivers may not attempt to interpret its
56 value. When a driver wants to enable its DMA engine, it must retrieve
57 the appropriate address to supply to its DMA engine using a call to
58 ddi_dma_htoc(9F), which takes a pointer to a DMA handle and returns
59 the appropriate DMA address.
60
61
62 When DMA transfer completes, the driver should free up the allocated
63 DMA resources by calling ddi_dma_free()
64
66 The ddi_dma_setup() function returns:
67
68 DDI_DMA_MAPPED Successfully allocated resources for the object.
69 In the case of an advisory call, this indicates
70 that the request is legal.
71
72
73 DDI_DMA_PARTIAL_MAP Successfully allocated resources for a part of
74 the object. This is acceptable when partial
75 transfers are allowed using a flag setting in
76 the ddi_dma_req structure (see ddi_dma_req(9S)
77 and ddi_dma_movwin(9F)).
78
79
80 DDI_DMA_NORESOURCES When no resources are available.
81
82
83 DDI_DMA_NOMAPPING The object cannot be reached by the device
84 requesting the resources.
85
86
87 DDI_DMA_TOOBIG The object is too big and exceeds the available
88 resources. The maximum size varies depending on
89 machine and configuration.
90
91
93 The ddi_dma_setup() function can be called from user, interrupt, or
94 kernel context, except when the dmar_fp member of the ddi_dma_req
95 structure pointed to by dmareqp is set to DDI_DMA_SLEEP, in which case
96 it cannot be called from interrupt context.
97
99 See attributes(5) for a description of the following attributes:
100
101
102
103
104 ┌─────────────────────────────┬─────────────────────────────┐
105 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
106 ├─────────────────────────────┼─────────────────────────────┤
107 │Stability Level │Obsolete │
108 └─────────────────────────────┴─────────────────────────────┘
109
111 attributes(5), ddi_dma_addr_bind_handle(9F), ddi_dma_alloc_handle(9F),
112 ddi_dma_buf_bind_handle(9F), ddi_dma_free_handle(9F),
113 ddi_dma_unbind_handle(9F)ddi_dma_addr_setup(9F), ddi_dma_buf_setup(9F),
114 ddi_dma_free(9F), ddi_dma_htoc(9F), ddi_dma_movwin(9F),
115 ddi_dma_sync(9F), ddi_dma_req(9S)
116
117
118 Writing Device Drivers
119
121 The construction of the ddi_dma_req structure is complicated. Use of
122 the provided interface functions such as ddi_dma_buf_setup(9F) simpli‐
123 fies this task.
124
125
126
127SunOS 5.11 16 Jan 2006 ddi_dma_setup(9F)