RTEMS: bsps/powerpc/include/bsp/VMEDMA.h Source File

| RTEMS 5.4-rc2

Loading...
Searching...
No Matches
VMEDMA.h
Go to the documentation of this file.
1
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
60extern "C" {
61#endif
62
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
129typedef 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 */
156int
157BSP_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 */
163int
164BSP_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
191uint32_t
192BSP_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 */
203typedef void (*BSP_VMEDmaIRQCallback)(void *usr_arg);
204
205int
206BSP_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)
232BSP_VMEDmaListDescriptor
233BSP_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 */
246int
247BSP_VMEDmaListDescriptorDestroy(BSP_VMEDmaListDescriptor d);
248
249/* Traverse a list of descriptors and destroy all elements */
250int
251BSP_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 */
266int
267BSP_VMEDmaListDescriptorEnq(
268 BSP_VMEDmaListDescriptor tail,
269 BSP_VMEDmaListDescriptor d);
270
271/* Obtain next and previous descriptors */
272BSP_VMEDmaListDescriptor
273BSP_VMEDmaListDescriptorNext(BSP_VMEDmaListDescriptor d);
274
275BSP_VMEDmaListDescriptor
276BSP_VMEDmaListDescriptorPrev(BSP_VMEDmaListDescriptor d);
277
278/* Set and get a 'usrData' pointer in the descriptor */
279void
280BSP_VMEDmaListDescriptorSetUsr(BSP_VMEDmaListDescriptor d, void *usrData);
281
282void *
283BSP_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
290int
291BSP_VMEDmaListRefresh(BSP_VMEDmaListDescriptor anchor);
292
293/* Start linked-list operation.
294 *
295 * RETURNS: 0 on success, nonzero on failure
296 */
297int
298BSP_VMEDmaListStart(int channel, BSP_VMEDmaListDescriptor list);
299
300#ifdef DEBUG
301void
302BSP_VMEDmaListDump(BSP_VMEDmaListDescriptor p);
303#endif
304
305#ifdef __cplusplus
306}
307#endif
308
309#endif
p
unsigned p
Definition: tte.h:17