1 | /** |
---|
2 | * @file |
---|
3 | * |
---|
4 | * @ingroup shared_vmedma |
---|
5 | * |
---|
6 | * @brief Public interface of DMA routines |
---|
7 | */ |
---|
8 | |
---|
9 | #ifndef BSP_VME_DMA_H |
---|
10 | #define BSP_VME_DMA_H |
---|
11 | |
---|
12 | /* |
---|
13 | * Authorship |
---|
14 | * ---------- |
---|
15 | * This software was created by |
---|
16 | * Till Straumann <strauman@slac.stanford.edu>, 2006, 2007 |
---|
17 | * Stanford Linear Accelerator Center, Stanford University. |
---|
18 | * |
---|
19 | * Acknowledgement of sponsorship |
---|
20 | * ------------------------------ |
---|
21 | * This software was produced by |
---|
22 | * the Stanford Linear Accelerator Center, Stanford University, |
---|
23 | * under Contract DE-AC03-76SFO0515 with the Department of Energy. |
---|
24 | * |
---|
25 | * Government disclaimer of liability |
---|
26 | * ---------------------------------- |
---|
27 | * Neither the United States nor the United States Department of Energy, |
---|
28 | * nor any of their employees, makes any warranty, express or implied, or |
---|
29 | * assumes any legal liability or responsibility for the accuracy, |
---|
30 | * completeness, or usefulness of any data, apparatus, product, or process |
---|
31 | * disclosed, or represents that its use would not infringe privately owned |
---|
32 | * rights. |
---|
33 | * |
---|
34 | * Stanford disclaimer of liability |
---|
35 | * -------------------------------- |
---|
36 | * Stanford University makes no representations or warranties, express or |
---|
37 | * implied, nor assumes any liability for the use of this software. |
---|
38 | * |
---|
39 | * Stanford disclaimer of copyright |
---|
40 | * -------------------------------- |
---|
41 | * Stanford University, owner of the copyright, hereby disclaims its |
---|
42 | * copyright and all other rights in this software. Hence, anyone may |
---|
43 | * freely use it for any purpose without restriction. |
---|
44 | * |
---|
45 | * Maintenance of notices |
---|
46 | * ---------------------- |
---|
47 | * In the interest of clarity regarding the origin and status of this |
---|
48 | * SLAC software, this and all the preceding Stanford University notices |
---|
49 | * are to remain affixed to any copy or derivative of this software made |
---|
50 | * or distributed by the recipient and are to be affixed to any copy of |
---|
51 | * software made or distributed by the recipient that contains a copy or |
---|
52 | * derivative of this software. |
---|
53 | * |
---|
54 | * ------------------ SLAC Software Notices, Set 4 OTT.002a, 2004 FEB 03 |
---|
55 | */ |
---|
56 | |
---|
57 | #include <stdint.h> |
---|
58 | |
---|
59 | #ifdef __cplusplus |
---|
60 | extern "C" { |
---|
61 | #endif |
---|
62 | |
---|
63 | /** |
---|
64 | * @defgroup shared_vmedma VMEDMA Support |
---|
65 | * |
---|
66 | * @ingroup shared_vmeuniverse |
---|
67 | * |
---|
68 | * @brief VMEDMA Support Package |
---|
69 | */ |
---|
70 | |
---|
71 | |
---|
72 | /* NOTE: Access to DMA Channels is *not* protected / thread-safe. |
---|
73 | * It is the responsability of the user to provide appropriate |
---|
74 | * locking/serialization. |
---|
75 | */ |
---|
76 | |
---|
77 | /* Simple abstraction of DMA controller setup / bus utilization: */ |
---|
78 | |
---|
79 | /* Since VME is the bottleneck, the settings for PCI are always |
---|
80 | * chosen aggressively. |
---|
81 | */ |
---|
82 | |
---|
83 | |
---|
84 | /* Optimize for throughput; accept longer latencies: |
---|
85 | * Choose a large block size (1k) and immediately re-request |
---|
86 | * the bus at block boundaries. |
---|
87 | */ |
---|
88 | #define BSP_VMEDMA_OPT_THROUGHPUT 1 |
---|
89 | /* Optimize for latency, accept throughput penalty: |
---|
90 | * Choose a small block size (32b) and immediately re-request |
---|
91 | * the bus at block boundaries. |
---|
92 | */ |
---|
93 | #define BSP_VMEDMA_OPT_LOWLATENCY 2 |
---|
94 | |
---|
95 | /* Optimize for bus sharing with other devices: |
---|
96 | * Choose relatively small block size (128) and back off for 64us |
---|
97 | * at each block boundary. |
---|
98 | */ |
---|
99 | #define BSP_VMEDMA_OPT_SHAREDBUS 3 |
---|
100 | |
---|
101 | /* Choose bridge default/reset configuration: |
---|
102 | * (see manual) |
---|
103 | */ |
---|
104 | #define BSP_VMEDMA_OPT_DEFAULT 4 |
---|
105 | |
---|
106 | /* Provide custom configuration pass pointer to array |
---|
107 | * with as many 32-bit words the particular bridge chip |
---|
108 | * expects. |
---|
109 | */ |
---|
110 | #define BSP_VMEDMA_OPT_CUSTOM 5 |
---|
111 | |
---|
112 | /* VME Transfer modes */ |
---|
113 | |
---|
114 | /* Bitwise OR of the VME address-modifier/transfer-type |
---|
115 | * with driver specific (no standard AM code for 2eVME and |
---|
116 | * 2eSST defined) and optional special flags (see below) |
---|
117 | */ |
---|
118 | |
---|
119 | /* Additional qualifiers: */ |
---|
120 | |
---|
121 | /* Don't increment VME address */ |
---|
122 | #define BSP_VMEDMA_MODE_NOINC_VME (1<<20) |
---|
123 | /* Don't increment PCI address */ |
---|
124 | #define BSP_VMEDMA_MODE_NOINC_PCI (1<<21) |
---|
125 | |
---|
126 | /* Direction */ |
---|
127 | #define BSP_VMEDMA_MODE_PCI2VME (1<<31) |
---|
128 | |
---|
129 | typedef void *BSP_VMEDmaListDescriptor; |
---|
130 | |
---|
131 | /* Program the device for the selected mode; |
---|
132 | * |
---|
133 | * 'bus_mode': one of the ...VMEDMA_OPT... choices |
---|
134 | * listed above. |
---|
135 | * 'xfer_mode': VME address-modifier optionally ORed with |
---|
136 | * ...VMEDMA_MODE... bits listed above. |
---|
137 | * 'custom': (only used if bus_mode is VMEDMA_OPT_CUSTOM) |
---|
138 | * pointer to a list of setup parameters (chip-driver |
---|
139 | * specific). |
---|
140 | * |
---|
141 | * RETURNS: 0 on success, nonzero on error (mode or channel |
---|
142 | * unsupported). |
---|
143 | * |
---|
144 | * NOTES: The setup is preserved across multiple DMA transfers. |
---|
145 | * It is the responsibility of the driver to reprogram |
---|
146 | * the setup if the hardware does not preserve it. |
---|
147 | * However - in linked list mode, some fields may be |
---|
148 | * read from the list descriptors. |
---|
149 | * |
---|
150 | * Usually this routine must be used even in linked-list |
---|
151 | * mode to program the 'bus_mode'. |
---|
152 | * |
---|
153 | * Direction of transfer is specified by a bit in the |
---|
154 | * 'xfer_mode' (BSP_VMEDMA_MODE_PCI2VME). |
---|
155 | */ |
---|
156 | int |
---|
157 | BSP_VMEDmaSetup(int channel, uint32_t bus_mode, uint32_t xfer_mode, void *custom_setup); |
---|
158 | |
---|
159 | /* Start direct (not linked-list) transfer. |
---|
160 | * |
---|
161 | * RETURNS: 0 on success, nonzero on failure |
---|
162 | */ |
---|
163 | int |
---|
164 | BSP_VMEDmaStart(int channel, uint32_t pci_addr, uint32_t vme_addr, uint32_t n_bytes); |
---|
165 | |
---|
166 | /* Transfer status/result */ |
---|
167 | #define BSP_VMEDMA_STATUS_OK 0 |
---|
168 | /* Unsupported channel */ |
---|
169 | #define BSP_VMEDMA_STATUS_UNSUP (-1) |
---|
170 | /* Bus error on VME */ |
---|
171 | #define BSP_VMEDMA_STATUS_BERR_VME 1 |
---|
172 | /* Bus error on PCI */ |
---|
173 | #define BSP_VMEDMA_STATUS_BERR_PCI 2 |
---|
174 | /* Channel busy */ |
---|
175 | #define BSP_VMEDMA_STATUS_BUSY 3 |
---|
176 | /* Setup/programming error */ |
---|
177 | #define BSP_VMEDMA_STATUS_PERR 4 |
---|
178 | /* Other/unspecified error */ |
---|
179 | #define BSP_VMEDMA_STATUS_OERR 5 |
---|
180 | |
---|
181 | /* Retrieve status of last transfer. |
---|
182 | * |
---|
183 | * RETURNS: 0 if the transfer was successful, |
---|
184 | * nonzero on error (e.g., one of the |
---|
185 | * values defined above). |
---|
186 | * |
---|
187 | * NOTE: Driver is allowed to pass other, |
---|
188 | * device specific codes |
---|
189 | */ |
---|
190 | |
---|
191 | uint32_t |
---|
192 | BSP_VMEDmaStatus(int channel); |
---|
193 | |
---|
194 | /* |
---|
195 | * Hook a callback (executed from ISR context) to DMA interrupt and |
---|
196 | * enable it. |
---|
197 | * If called with NULL callback then an existing callback is removed |
---|
198 | * and the interrupt disabled. |
---|
199 | * |
---|
200 | * RETURNS: 0 on success, nonzero on failure (IRQ in use, unsupported |
---|
201 | * channel). |
---|
202 | */ |
---|
203 | typedef void (*BSP_VMEDmaIRQCallback)(void *usr_arg); |
---|
204 | |
---|
205 | int |
---|
206 | BSP_VMEDmaInstallISR(int channel, BSP_VMEDmaIRQCallback cb, void *usr_arg); |
---|
207 | |
---|
208 | /* |
---|
209 | * DMA List operations. |
---|
210 | * |
---|
211 | * Note that the list is totally unprotected, i.e., the user is |
---|
212 | * responsible for maintaining coherency against concurrent |
---|
213 | * access by multiple threads or hardware. |
---|
214 | * We assume the user builds/updates a list, hands it over to |
---|
215 | * the hardware (list start command) and leaves it alone until |
---|
216 | * the DMA controller is done with it. |
---|
217 | */ |
---|
218 | |
---|
219 | /* Modify a list entry. If the list element pointer is NULL |
---|
220 | * then a new list element is allocated. |
---|
221 | * Only the fields with its corresponding bit set in the mask |
---|
222 | * argument are touched. |
---|
223 | * |
---|
224 | * RETURNS: 'd' or newly allocated descriptor or NULL (no memory, |
---|
225 | * or invalid setup). |
---|
226 | */ |
---|
227 | #define BSP_VMEDMA_MSK_ATTR (1<<0) |
---|
228 | #define BSP_VMEDMA_MSK_PCIA (1<<1) |
---|
229 | #define BSP_VMEDMA_MSK_VMEA (1<<2) |
---|
230 | #define BSP_VMEDMA_MSK_BCNT (1<<3) |
---|
231 | #define BSP_VMEDMA_MSK_ALL (0xf) |
---|
232 | BSP_VMEDmaListDescriptor |
---|
233 | BSP_VMEDmaListDescriptorSetup( |
---|
234 | BSP_VMEDmaListDescriptor d, |
---|
235 | uint32_t attr_mask, |
---|
236 | uint32_t xfer_mode, |
---|
237 | uint32_t pci_addr, |
---|
238 | uint32_t vme_addr, |
---|
239 | uint32_t n_bytes); |
---|
240 | |
---|
241 | /* De-allocate a list descriptor previously obtained by |
---|
242 | * BSP_VMEDmaListDescriptorSetup(0,...); |
---|
243 | * |
---|
244 | * RETURNS: 0 on success, nonzero on failure (d currently on a list) |
---|
245 | */ |
---|
246 | int |
---|
247 | BSP_VMEDmaListDescriptorDestroy(BSP_VMEDmaListDescriptor d); |
---|
248 | |
---|
249 | /* Traverse a list of descriptors and destroy all elements */ |
---|
250 | int |
---|
251 | BSP_VMEDmaListDestroy(BSP_VMEDmaListDescriptor anchor); |
---|
252 | |
---|
253 | /* Enqueue a list descriptor 'd' after 'tail' |
---|
254 | * |
---|
255 | * If 'tail' is NULL then 'd' is removed from |
---|
256 | * the list it is currently on. |
---|
257 | * |
---|
258 | * RETURNS: 0 on success, nonzero if 'd' is already |
---|
259 | * on a list (enqueue) or if it is not currently |
---|
260 | * on a list (dequeue). |
---|
261 | * |
---|
262 | * NOTE: it is obviously the user's responsibility to update |
---|
263 | * list queue/tail pointers when changing the |
---|
264 | * structure of the list. |
---|
265 | */ |
---|
266 | int |
---|
267 | BSP_VMEDmaListDescriptorEnq( |
---|
268 | BSP_VMEDmaListDescriptor tail, |
---|
269 | BSP_VMEDmaListDescriptor d); |
---|
270 | |
---|
271 | /* Obtain next and previous descriptors */ |
---|
272 | BSP_VMEDmaListDescriptor |
---|
273 | BSP_VMEDmaListDescriptorNext(BSP_VMEDmaListDescriptor d); |
---|
274 | |
---|
275 | BSP_VMEDmaListDescriptor |
---|
276 | BSP_VMEDmaListDescriptorPrev(BSP_VMEDmaListDescriptor d); |
---|
277 | |
---|
278 | /* Set and get a 'usrData' pointer in the descriptor */ |
---|
279 | void |
---|
280 | BSP_VMEDmaListDescriptorSetUsr(BSP_VMEDmaListDescriptor d, void *usrData); |
---|
281 | |
---|
282 | void * |
---|
283 | BSP_VMEDmaListDescriptorGetUsr(BSP_VMEDmaListDescriptor d); |
---|
284 | |
---|
285 | /* Refresh an entire list. Some DMA controllers modify certain |
---|
286 | * fields (e.g., byte count) and this command restores the original |
---|
287 | * setup. |
---|
288 | */ |
---|
289 | |
---|
290 | int |
---|
291 | BSP_VMEDmaListRefresh(BSP_VMEDmaListDescriptor anchor); |
---|
292 | |
---|
293 | /* Start linked-list operation. |
---|
294 | * |
---|
295 | * RETURNS: 0 on success, nonzero on failure |
---|
296 | */ |
---|
297 | int |
---|
298 | BSP_VMEDmaListStart(int channel, BSP_VMEDmaListDescriptor list); |
---|
299 | |
---|
300 | #ifdef DEBUG |
---|
301 | void |
---|
302 | BSP_VMEDmaListDump(BSP_VMEDmaListDescriptor p); |
---|
303 | #endif |
---|
304 | |
---|
305 | #ifdef __cplusplus |
---|
306 | } |
---|
307 | #endif |
---|
308 | |
---|
309 | #endif |
---|