1ddi_dmae_req(9S) Data Structures for Drivers ddi_dmae_req(9S)
2
6 ddi_dmae_req - DMA engine request structure
7
9 #include <sys/dma_engine.h>
10
13 Solaris x86 DDI specific (Solaris x86 DDI).
14
16 A device driver uses the ddi_dmae_req structure to describe the parame‐
17 ters for a DMA channel. This structure contains all the information
18 necessary to set up the channel, except for the DMA memory address and
19 transfer count. The defaults, as specified below, support most standard
20 devices. Other modes might be desirable for some devices, or to
21 increase performance. The DMA engine request structure is passed to
22 ddi_dmae_prog(9F).
23
25 The ddi_dmae_req structure contains several members, each of which con‐
26 trols some aspect of DMA engine operation. The structure members asso‐
27 ciated with supported DMA engine options are described here.
28 uchar_tder_command; /* Read / Write *
30 /uchar_tder_bufprocess; /* Standard / Chain */
31 uchar_tder_path; /* 8 / 16 / 32 */
32 uchar_tder_cycles; /* Compat / Type A / Type B / Burst */
33 uchar_tder_trans; /* Single / Demand / Block */
34 ddi_dma_cookie_t*(*proc)(); /* address of nextcookie routine */
35 void*procparms; /* parameter for nextcookie call */
36 der_command Specifies what DMA operation is to be performed. The
39 value DMAE_CMD_WRITE signifies that data is to be
40 transferred from memory to the I/O device. The value
41 DMAE_CMD_READ signifies that data is to be trans‐
42 ferred from the I/O device to memory. This field must
43 be set by the driver before calling ddi_dmae_prog().
44 der_bufprocess On some bus types, a driver can set der_bufprocess to
47 the value DMAE_BUF_CHAIN to specify that multiple DMA
48 cookies will be given to the DMA engine for a single
49 I/O transfer. This action causes a scatter/gather
50 operation. In this mode of operation, the driver
51 calls ddi_dmae_prog() to give the DMA engine the DMA
52 engine request structure and a pointer to the first
53 cookie. The proc structure member must be set to the
54 address of a driver nextcookie routine. This routine
55 takes one argument, specified by the procparms struc‐
56 ture member, and returns a pointer to a structure of
57 type ddi_dma_cookie_t that specifies the next cookie
58 for the I/O transfer. When the DMA engine is ready
59 to receive an additional cookie, the bus nexus driver
60 controlling that DMA engine calls the routine speci‐
61 fied by the proc structure member to obtain the next
62 cookie from the driver. The driver's nextcookie rou‐
63 tine must then return the address of the next cookie
64 (in static storage) to the bus nexus routine that
65 called it. If there are no more segments in the cur‐
66 rent DMA window, then (*proc)() must return the NULL
67 pointer.
68 A driver can specify the DMAE_BUF_CHAIN flag only if
70 the particular bus architecture supports the use of
71 multiple DMA cookies in a single I/O transfer. A bus
72 DMA engine can support this feature either with a
73 fixed-length scatter/gather list, or by an interrupt
74 chaining feature. A driver must determine whether its
75 parent bus nexus supports this feature by examining
76 the scatter/gather list size returned in the
77 dlim_sgllen member of the DMA limit structure
78 returned by the driver's call to ddi_dmae_getlim().
79 (See ddi_dma_lim_x86(9S).) If the size of the scat‐
80 ter/gather list is 1, then no chaining is available.
81 The driver must not specify the DMAE_BUF_CHAIN flag
82 in the ddi_dmae_req structure it passes to
83 ddi_dmae_prog(), and the driver need not provide a
84 nextcookie routine.
85 If the size of the scatter/gather list is greater
87 than 1, then DMA chaining is available, and the
88 driver has two options. Under the first option, the
89 driver chooses not to use the chaining feature. In
90 this case (a) the driver must set the size of the
91 scatter/gather list to 1 before passing it to the DMA
92 setup routine, and (b) the driver must not set the
93 DMAE_BUF_CHAIN flag.
94 Under the second option, the driver chooses to use
96 the chaining feature, in which case, (a) it should
97 leave the size of the scatter/gather list alone, and
98 (b) it must set the DMAE_BUF_CHAIN flag in the
99 ddi_dmae_req structure. Before calling
100 ddi_dmae_prog(), the driver must prefetch cookies by
101 repeatedly calling ddi_dma_nextseg(9F) and
102 ddi_dma_segtocookie(9F) until either (1) the end of
103 the DMA window is reached (ddi_dma_nextseg(9F)
104 returns NULL), or (2) the size of the scatter/gather
105 list is reached, whichever occurs first. These cook‐
106 ies must be saved by the driver until they are
107 requested by the nexus driver calling the driver's
108 nextcookie routine. The driver's nextcookie routine
109 must return the prefetched cookies in order, one
110 cookie for each call to the nextcookie routine, until
111 the list of prefetched cookies is exhausted. After
112 the end of the list of cookies is reached, the
113 nextcookie routine must return the NULL pointer.
114 The size of the scatter/gather list determines how
116 many discontiguous segments of physical memory can
117 participate in a single DMA transfer. ISA bus DMA
118 engines have no scatter/gather capability, so their
119 scatter/gather list sizes are 1. Other finite scat‐
120 ter/gather list sizes would also be possible. For
121 performance reasons, drivers should use the chaining
122 capability if it is available on their parent bus.
123 As described above, a driver making use of DMA chain‐
125 ing must prefetch DMA cookies before calling
126 ddi_dmae_prog(). The reasons for this are:
127 o First, the driver must have some way to
129 know the total I/O count with which to
130 program the I/O device. This I/O count
131 must match the total size of all the DMA
132 segments that will be chained together
133 into one DMA operation. Depending on the
134 size of the scatter/gather list and the
135 memory position and alignment of the DMA
136 object, all or just part of the current
137 DMA window might be able to participate in
138 a single I/O operation. The driver must
139 compute the I/O count by adding up the
140 sizes of the prefetched DMA cookies. The
141 number of cookies whose sizes are to be
142 summed is the lesser of (a) the size of
143 the scatter/gather list, or (b) the number
144 of segments remaining in the window.
145 o Second, on some bus architectures, the
147 driver's nextcookie routine can be called
148 from a high-level interrupt routine. If
149 the cookies were not prefetched, the
150 nextcookie routine would have to call
151 ddi_dma_nextseg() and ddi_dma_segto‐
152 cookie() from a high-level interrupt rou‐
153 tine, which is not recommended.
154 When breaking a DMA window into segments, the system
155 arranges for the end of every segment whose number is
156 an integral multiple of the scatter/gather list size
157 to fall on a device-granularity boundary, as speci‐
158 fied in the dlim_granular field in the
159 ddi_dma_lim_x86(9S) structure.
160 If the scatter/gather list size is 1 (either because
162 no chaining is available or because the driver does
163 not want to use the chaining feature), then the total
164 I/O count for a single DMA operation is the size of
165 DMA segment denoted by the single DMA cookie that is
166 passed in the call to ddi_dmae_prog(). In this case,
167 the system arranges for each DMA segment to be a mul‐
168 tiple of the device-granularity size.
169 der_path Specifies the DMA transfer size. The default of zero
172 (DMAE_PATH_DEF) specifies ISA compatibility mode. In
173 that mode, channels 0, 1, 2, and 3 are programmed in
174 8-bit mode (DMAE_PATH_8), and channels 5, 6, and 7
175 are programmed in 16-bit, count-by-word mode
176 (DMAE_PATH_16).
177 der_cycles Specifies the timing mode to be used during DMA data
180 transfers. The default of zero (DMAE_CYCLES_1) speci‐
181 fies ISA compatible timing. Drivers using this mode
182 must also specify DMAE_TRANS_SNGL in the der_trans
183 structure member.
184 der_trans Specifies the bus transfer mode that the DMA engine
187 should expect from the device. The default value of
188 zero (DMAE_TRANS_SNGL) specifies that the device per‐
189 forms one transfer for each bus arbitration cycle.
190 Devices that use ISA compatible timing (specified by
191 a value of zero, which is the default, in the
192 der_cycles structure member) should use the
193 DMAE_TRANS_SNGL mode.
194
197 See attributes(5) for descriptions of the following attributes:
198 ┌─────────────────────────────┬─────────────────────────────┐
203 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
204 ├─────────────────────────────┼─────────────────────────────┤
205 │Architecture │x86 │
206 └─────────────────────────────┴─────────────────────────────┘
207
209 isa(4), attributes(5), ddi_dma_segtocookie(9F), ddi_dmae(9F),
210 ddi_dma_lim_x86(9S), ddi_dma_req(9S)
211SunOS 5.11 18 Nov 2004 ddi_dmae_req(9S)