1 #ifndef __ALT_DMA_H__
2 #define __ALT_DMA_H__
3
4 /******************************************************************************
5 * *
6 * License Agreement *
7 * *
8 * Copyright (c) 2004-2005 Altera Corporation, San Jose, California, USA. *
9 * All rights reserved. *
10 * *
11 * Permission is hereby granted, free of charge, to any person obtaining a *
12 * copy of this software and associated documentation files (the "Software"), *
13 * to deal in the Software without restriction, including without limitation *
14 * the rights to use, copy, modify, merge, publish, distribute, sublicense, *
15 * and/or sell copies of the Software, and to permit persons to whom the *
16 * Software is furnished to do so, subject to the following conditions: *
17 * *
18 * The above copyright notice and this permission notice shall be included in *
19 * all copies or substantial portions of the Software. *
20 * *
21 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR *
22 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, *
23 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE *
24 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER *
25 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING *
26 * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER *
27 * DEALINGS IN THE SOFTWARE. *
28 * *
29 * *
30 * Altera does not recommend, suggest or require that this reference design *
31 * file be used in conjunction or combination with any other product. *
32 ******************************************************************************/
33
34 /******************************************************************************
35 * *
36 * THIS IS A LIBRARY READ-ONLY SOURCE FILE. DO NOT EDIT. *
37 * *
38 ******************************************************************************/
39
40 #include "sys/alt_dma_dev.h"
41 #include "alt_types.h"
42
43 #include <errno.h>
44
45 #ifdef __cplusplus
46 extern "C"
47 {
48 #endif /* __cplusplus */
49
50 /*
51 * This header contains the application side interface for accessing DMA
52 * resources. See alt_dma_dev.h for the dma device driver interface.
53 *
54 * The interface model treats a DMA transaction as being composed of two
55 * halves (read and write).
56 *
57 * The application can supply data for transmit using an "alt_dma_txchan"
58 * descriptor. Alternatively an "alt_dma_rxchan" descriptor can be used to
59 * receive data.
60 */
61
62 /*
63 * alt_dma_txchan_open() is used to obtain an "alt_dma_txchan" descriptor for
64 * a DMA transmit device. The name is the name of the associated physical
65 * device (e.g. "/dev/dma_0").
66 *
67 * The return value will be NULL on failure, and non-NULL otherwise.
68 */
69
70 extern alt_dma_txchan alt_dma_txchan_open (const char* name);
71
72 /*
73 * alt_dma_txchan_close() is provided so that an application can notify the
74 * system that it has finished with a given DMA transmit channel. This is only
75 * provided for completness.
76 */
77
alt_dma_txchan_close(alt_dma_txchan dma)78 static ALT_INLINE int alt_dma_txchan_close (alt_dma_txchan dma)
79 {
80 return 0;
81 }
82
83 /*
84 * alt_dma_txchan_send() posts a transmit request to a DMA transmit channel.
85 * The input arguments are:
86 *
87 * dma: the channel to use.
88 * from: a pointer to the start of the data to send.
89 * length: the length of the data to send in bytes.
90 * done: callback function that will be called once the data has been sent.
91 * handle: opaque value passed to "done".
92 *
93 * The return value will be negative if the request cannot be posted, and
94 * zero otherwise.
95 */
96
alt_dma_txchan_send(alt_dma_txchan dma,const void * from,alt_u32 length,alt_txchan_done * done,void * handle)97 static ALT_INLINE int alt_dma_txchan_send (alt_dma_txchan dma,
98 const void* from,
99 alt_u32 length,
100 alt_txchan_done* done,
101 void* handle)
102 {
103 return dma ? dma->dma_send (dma,
104 from,
105 length,
106 done,
107 handle) : -ENODEV;
108 }
109
110 /*
111 * alt_dma_txchan_space() returns the number of tranmit requests that can be
112 * posted to the specified DMA transmit channel.
113 *
114 * A negative value indicates that the value could not be determined.
115 */
116
alt_dma_txchan_space(alt_dma_txchan dma)117 static ALT_INLINE int alt_dma_txchan_space (alt_dma_txchan dma)
118 {
119 return dma ? dma->space (dma) : -ENODEV;
120 }
121
122 /*
123 * alt_dma_txchan_ioctl() can be used to perform device specific I/O
124 * operations on the indicated DMA transmit channel. For example some drivers
125 * support options to control the width of the transfer operations. See
126 * alt_dma_dev.h for the list of generic requests.
127 *
128 * A negative return value indicates failure, otherwise the interpretation
129 * of the return value is request specific.
130 */
131
alt_dma_txchan_ioctl(alt_dma_txchan dma,int req,void * arg)132 static ALT_INLINE int alt_dma_txchan_ioctl (alt_dma_txchan dma,
133 int req,
134 void* arg)
135 {
136 return dma ? dma->ioctl (dma, req, arg) : -ENODEV;
137 }
138
139 /*
140 * alt_dma_rxchan_open() is used to obtain an "alt_dma_rxchan" descriptor for
141 * a DMA receive channel. The name is the name of the associated physical
142 * device (e.g. "/dev/dma_0").
143 *
144 * The return value will be NULL on failure, and non-NULL otherwise.
145 */
146
147 extern alt_dma_rxchan alt_dma_rxchan_open (const char* dev);
148
149 /*
150 * alt_dma_rxchan_close() is provided so that an application can notify the
151 * system that it has finished with a given DMA receive channel. This is only
152 * provided for completness.
153 */
154
alt_dma_rxchan_close(alt_dma_rxchan dma)155 static ALT_INLINE int alt_dma_rxchan_close (alt_dma_rxchan dma)
156 {
157 return 0;
158 }
159
160 /*
161 *
162 */
163
164 /*
165 * alt_dma_rxchan_prepare() posts a receive request to a DMA receive channel.
166 *
167 * The input arguments are:
168 *
169 * dma: the channel to use.
170 * data: a pointer to the location that data is to be received to.
171 * len: the maximum length of the data to receive.
172 * done: callback function that will be called once the data has been
173 * received.
174 * handle: opaque value passed to "done".
175 *
176 * The return value will be negative if the request cannot be posted, and
177 * zero otherwise.
178 */
179
alt_dma_rxchan_prepare(alt_dma_rxchan dma,void * data,alt_u32 len,alt_rxchan_done * done,void * handle)180 static ALT_INLINE int alt_dma_rxchan_prepare (alt_dma_rxchan dma,
181 void* data,
182 alt_u32 len,
183 alt_rxchan_done* done,
184 void* handle)
185 {
186 return dma ? dma->prepare (dma, data, len, done, handle) : -ENODEV;
187 }
188
189 /*
190 * alt_dma_rxchan_ioctl() can be used to perform device specific I/O
191 * operations on the indicated DMA receive channel. For example some drivers
192 * support options to control the width of the transfer operations. See
193 * alt_dma_dev.h for the list of generic requests.
194 *
195 * A negative return value indicates failure, otherwise the interpretation
196 * of the return value is request specific.
197 */
198
alt_dma_rxchan_ioctl(alt_dma_rxchan dma,int req,void * arg)199 static ALT_INLINE int alt_dma_rxchan_ioctl (alt_dma_rxchan dma,
200 int req,
201 void* arg)
202 {
203 return dma ? dma->ioctl (dma, req, arg) : -ENODEV;
204 }
205
206 /*
207 * alt_dma_rxchan_depth() returns the depth of the receive FIFO used to store
208 * receive requests.
209 */
210
alt_dma_rxchan_depth(alt_dma_rxchan dma)211 static ALT_INLINE alt_u32 alt_dma_rxchan_depth(alt_dma_rxchan dma)
212 {
213 return dma->depth;
214 }
215
216 /*
217 *
218 */
219
220 #ifdef __cplusplus
221 }
222 #endif /* __cplusplus */
223
224 #endif /* __ALT_DMA_H__ */
225
