summaryrefslogtreecommitdiffstats
path: root/c/src/lib/libbsp/shared/vmeUniverse/VMEDMA.h
blob: 6b53b127d61afc8fcc37e24218b154ce463c96aa (plain) (blame)
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
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
/**
 *  @file
 *
 *  @ingroup shared_vmedma
 *
 *  @brief Public interface of DMA routines
 */

#ifndef BSP_VME_DMA_H
#define BSP_VME_DMA_H

/*
 * Authorship
 * ----------
 * This software was created by
 *     Till Straumann <strauman@slac.stanford.edu>, 2006, 2007
 * 	   Stanford Linear Accelerator Center, Stanford University.
 *
 * Acknowledgement of sponsorship
 * ------------------------------
 * This software was produced by
 *     the Stanford Linear Accelerator Center, Stanford University,
 * 	   under Contract DE-AC03-76SFO0515 with the Department of Energy.
 *
 * Government disclaimer of liability
 * ----------------------------------
 * Neither the United States nor the United States Department of Energy,
 * nor any of their employees, makes any warranty, express or implied, or
 * assumes any legal liability or responsibility for the accuracy,
 * completeness, or usefulness of any data, apparatus, product, or process
 * disclosed, or represents that its use would not infringe privately owned
 * rights.
 *
 * Stanford disclaimer of liability
 * --------------------------------
 * Stanford University makes no representations or warranties, express or
 * implied, nor assumes any liability for the use of this software.
 *
 * Stanford disclaimer of copyright
 * --------------------------------
 * Stanford University, owner of the copyright, hereby disclaims its
 * copyright and all other rights in this software.  Hence, anyone may
 * freely use it for any purpose without restriction.
 *
 * Maintenance of notices
 * ----------------------
 * In the interest of clarity regarding the origin and status of this
 * SLAC software, this and all the preceding Stanford University notices
 * are to remain affixed to any copy or derivative of this software made
 * or distributed by the recipient and are to be affixed to any copy of
 * software made or distributed by the recipient that contains a copy or
 * derivative of this software.
 *
 * ------------------ SLAC Software Notices, Set 4 OTT.002a, 2004 FEB 03
 */

#include <stdint.h>

#ifdef __cplusplus
extern "C" {
#endif

/**
 *  @defgroup shared_vmedma VMEDMA Support
 *
 *  @ingroup shared_vmeuniverse
 *
 *  @brief VMEDMA Support Package
 */


/* NOTE: Access to DMA Channels is *not* protected / thread-safe.
 *       It is the responsability of the user to provide appropriate
 *       locking/serialization.
 */

/* Simple abstraction of DMA controller setup / bus utilization:  */

/* Since VME is the bottleneck, the settings for PCI are always
 * chosen aggressively.
 */


/* Optimize for throughput; accept longer latencies:
 * Choose a large block size (1k) and immediately re-request
 * the bus at block boundaries.
 */
#define BSP_VMEDMA_OPT_THROUGHPUT	1
/* Optimize for latency, accept throughput penalty:
 * Choose a small block size (32b) and immediately re-request
 * the bus at block boundaries.
 */
#define BSP_VMEDMA_OPT_LOWLATENCY	2

/* Optimize for bus sharing with other devices:
 * Choose relatively small block size (128) and back off for 64us
 * at each block boundary.
 */
#define BSP_VMEDMA_OPT_SHAREDBUS	3

/* Choose bridge default/reset configuration:
 * (see manual)
 */
#define BSP_VMEDMA_OPT_DEFAULT		4

/* Provide custom configuration pass pointer to array
 * with as many 32-bit words the particular bridge chip
 * expects.
 */
#define BSP_VMEDMA_OPT_CUSTOM		5

/* VME Transfer modes */

/* Bitwise OR of the VME address-modifier/transfer-type
 * with driver specific (no standard AM code for 2eVME and
 * 2eSST defined) and optional special flags (see below)
 */

/* Additional qualifiers: */

/* Don't increment VME address */
#define BSP_VMEDMA_MODE_NOINC_VME	(1<<20)
/* Don't increment PCI address */
#define BSP_VMEDMA_MODE_NOINC_PCI	(1<<21)

/* Direction */
#define BSP_VMEDMA_MODE_PCI2VME		(1<<31)

typedef void *BSP_VMEDmaListDescriptor;

/* Program the device for the selected mode;
 *
 *  'bus_mode': one of the ...VMEDMA_OPT... choices
 *              listed above.
 * 'xfer_mode': VME address-modifier optionally ORed with
 *              ...VMEDMA_MODE... bits listed above.
 *    'custom': (only used if bus_mode is VMEDMA_OPT_CUSTOM)
 *              pointer to a list of setup parameters (chip-driver
 *              specific).
 *
 * RETURNS: 0 on success, nonzero on error (mode or channel
 *          unsupported).
 *
 * NOTES:   The setup is preserved across multiple DMA transfers.
 *          It is the responsibility of the driver to reprogram
 *          the setup if the hardware does not preserve it.
 *          However - in linked list mode, some fields may be
 *          read from the list descriptors.
 *
 *          Usually this routine must be used even in linked-list
 *          mode to program the 'bus_mode'.
 *
 *          Direction of transfer is specified by a bit in the
 *          'xfer_mode' (BSP_VMEDMA_MODE_PCI2VME).
 */
int
BSP_VMEDmaSetup(int channel, uint32_t bus_mode, uint32_t xfer_mode, void *custom_setup);

/* Start direct (not linked-list) transfer.
 *
 * RETURNS: 0 on success, nonzero on failure
 */
int
BSP_VMEDmaStart(int channel, uint32_t pci_addr, uint32_t vme_addr, uint32_t n_bytes);

/* Transfer status/result */
#define BSP_VMEDMA_STATUS_OK		0
/* Unsupported channel */
#define BSP_VMEDMA_STATUS_UNSUP		(-1)
/* Bus error on VME */
#define BSP_VMEDMA_STATUS_BERR_VME	1
/* Bus error on PCI */
#define BSP_VMEDMA_STATUS_BERR_PCI	2
/* Channel busy        */
#define BSP_VMEDMA_STATUS_BUSY		3
/* Setup/programming error */
#define BSP_VMEDMA_STATUS_PERR		4
/* Other/unspecified error */
#define BSP_VMEDMA_STATUS_OERR		5

/* Retrieve status of last transfer.
 *
 * RETURNS: 0 if the transfer was successful,
 *          nonzero on error (e.g., one of the
 *          values defined above).
 *
 *    NOTE: Driver is allowed to pass other,
 *          device specific codes
 */

uint32_t
BSP_VMEDmaStatus(int channel);

/*
 * Hook a callback (executed from ISR context) to DMA interrupt and
 * enable it.
 * If called with NULL callback then an existing callback is removed
 * and the interrupt disabled.
 *
 * RETURNS: 0 on success, nonzero on failure (IRQ in use, unsupported
 *          channel).
 */
typedef void (*BSP_VMEDmaIRQCallback)(void *usr_arg);

int
BSP_VMEDmaInstallISR(int channel, BSP_VMEDmaIRQCallback cb, void *usr_arg);

/*
 * DMA List operations.
 *
 * Note that the list is totally unprotected, i.e., the user is
 * responsible for maintaining coherency against concurrent
 * access by multiple threads or hardware.
 * We assume the user builds/updates a list, hands it over to
 * the hardware (list start command) and leaves it alone until
 * the DMA controller is done with it.
 */

/* Modify a list entry. If the list element pointer is NULL
 * then a new list element is allocated.
 * Only the fields with its corresponding bit set in the mask
 * argument are touched.
 *
 * RETURNS: 'd' or newly allocated descriptor or NULL (no memory,
 *          or invalid setup).
 */
#define BSP_VMEDMA_MSK_ATTR		(1<<0)
#define BSP_VMEDMA_MSK_PCIA		(1<<1)
#define BSP_VMEDMA_MSK_VMEA		(1<<2)
#define BSP_VMEDMA_MSK_BCNT		(1<<3)
#define BSP_VMEDMA_MSK_ALL		(0xf)
BSP_VMEDmaListDescriptor
BSP_VMEDmaListDescriptorSetup(
		BSP_VMEDmaListDescriptor d,
		uint32_t                 attr_mask,
		uint32_t				 xfer_mode,
		uint32_t                 pci_addr,
		uint32_t                 vme_addr,
		uint32_t                 n_bytes);

/* De-allocate a list descriptor previously obtained by
 * BSP_VMEDmaListDescriptorSetup(0,...);
 *
 * RETURNS: 0 on success, nonzero on failure (d currently on a list)
 */
int
BSP_VMEDmaListDescriptorDestroy(BSP_VMEDmaListDescriptor d);

/* Traverse a list of descriptors and destroy all elements */
int
BSP_VMEDmaListDestroy(BSP_VMEDmaListDescriptor anchor);

/* Enqueue a list descriptor 'd' after 'tail'
 *
 * If 'tail' is NULL then 'd' is removed from
 * the list it is currently on.
 *
 * RETURNS: 0 on success, nonzero if 'd' is already
 *          on a list (enqueue) or if it is not currently
 *          on a list (dequeue).
 *
 * NOTE: it is obviously the user's responsibility to update
 *       list queue/tail pointers when changing the
 *       structure of the list.
 */
int
BSP_VMEDmaListDescriptorEnq(
		BSP_VMEDmaListDescriptor tail,
		BSP_VMEDmaListDescriptor d);

/* Obtain next and previous descriptors */
BSP_VMEDmaListDescriptor
BSP_VMEDmaListDescriptorNext(BSP_VMEDmaListDescriptor d);

BSP_VMEDmaListDescriptor
BSP_VMEDmaListDescriptorPrev(BSP_VMEDmaListDescriptor d);

/* Set and get a 'usrData' pointer in the descriptor */
void
BSP_VMEDmaListDescriptorSetUsr(BSP_VMEDmaListDescriptor d, void *usrData);

void *
BSP_VMEDmaListDescriptorGetUsr(BSP_VMEDmaListDescriptor d);

/* Refresh an entire list. Some DMA controllers modify certain
 * fields (e.g., byte count) and this command restores the original
 * setup.
 */

int
BSP_VMEDmaListRefresh(BSP_VMEDmaListDescriptor anchor);

/* Start linked-list operation.
 *
 * RETURNS: 0 on success, nonzero on failure
 */
int
BSP_VMEDmaListStart(int channel, BSP_VMEDmaListDescriptor list);

#ifdef __cplusplus
}
#endif

#endif