Commit | Line | Data |
---|---|---|
1a4a561b LC |
1 | /***************************************************************************** |
2 | * Copyright 2004 - 2008 Broadcom Corporation. All rights reserved. | |
3 | * | |
4 | * Unless you and Broadcom execute a separate written software license | |
5 | * agreement governing use of this software, this software is licensed to you | |
6 | * under the terms of the GNU General Public License version 2, available at | |
7 | * http://www.broadcom.com/licenses/GPLv2.php (the "GPL"). | |
8 | * | |
9 | * Notwithstanding the above, under no circumstances may you combine this | |
10 | * software in any way with any other Broadcom software provided under a | |
11 | * license other than the GPL, without Broadcom's express prior written | |
12 | * consent. | |
13 | *****************************************************************************/ | |
14 | ||
15 | /****************************************************************************/ | |
16 | /** | |
17 | * @file dmacHw.h | |
18 | * | |
19 | * @brief API definitions for low level DMA controller driver | |
20 | * | |
21 | */ | |
22 | /****************************************************************************/ | |
23 | #ifndef _DMACHW_H | |
24 | #define _DMACHW_H | |
25 | ||
26 | #include <stddef.h> | |
27 | ||
28 | #include <csp/stdint.h> | |
29 | #include <mach/csp/dmacHw_reg.h> | |
30 | ||
31 | /* Define DMA Channel ID using DMA controller number (m) and channel number (c). | |
32 | ||
33 | System specific channel ID should be defined as follows | |
34 | ||
35 | For example: | |
36 | ||
37 | #include <dmacHw.h> | |
38 | ... | |
39 | #define systemHw_LCD_CHANNEL_ID dmacHw_MAKE_CHANNEL_ID(0,5) | |
40 | #define systemHw_SWITCH_RX_CHANNEL_ID dmacHw_MAKE_CHANNEL_ID(0,0) | |
41 | #define systemHw_SWITCH_TX_CHANNEL_ID dmacHw_MAKE_CHANNEL_ID(0,1) | |
42 | #define systemHw_APM_RX_CHANNEL_ID dmacHw_MAKE_CHANNEL_ID(0,3) | |
43 | #define systemHw_APM_TX_CHANNEL_ID dmacHw_MAKE_CHANNEL_ID(0,4) | |
44 | ... | |
45 | #define systemHw_SHARED1_CHANNEL_ID dmacHw_MAKE_CHANNEL_ID(1,4) | |
46 | #define systemHw_SHARED2_CHANNEL_ID dmacHw_MAKE_CHANNEL_ID(1,5) | |
47 | #define systemHw_SHARED3_CHANNEL_ID dmacHw_MAKE_CHANNEL_ID(0,6) | |
48 | ... | |
49 | */ | |
50 | #define dmacHw_MAKE_CHANNEL_ID(m, c) (m << 8 | c) | |
51 | ||
52 | typedef enum { | |
53 | dmacHw_CHANNEL_PRIORITY_0 = dmacHw_REG_CFG_LO_CH_PRIORITY_0, /* Channel priority 0. Lowest priority DMA channel */ | |
54 | dmacHw_CHANNEL_PRIORITY_1 = dmacHw_REG_CFG_LO_CH_PRIORITY_1, /* Channel priority 1 */ | |
55 | dmacHw_CHANNEL_PRIORITY_2 = dmacHw_REG_CFG_LO_CH_PRIORITY_2, /* Channel priority 2 */ | |
56 | dmacHw_CHANNEL_PRIORITY_3 = dmacHw_REG_CFG_LO_CH_PRIORITY_3, /* Channel priority 3 */ | |
57 | dmacHw_CHANNEL_PRIORITY_4 = dmacHw_REG_CFG_LO_CH_PRIORITY_4, /* Channel priority 4 */ | |
58 | dmacHw_CHANNEL_PRIORITY_5 = dmacHw_REG_CFG_LO_CH_PRIORITY_5, /* Channel priority 5 */ | |
59 | dmacHw_CHANNEL_PRIORITY_6 = dmacHw_REG_CFG_LO_CH_PRIORITY_6, /* Channel priority 6 */ | |
60 | dmacHw_CHANNEL_PRIORITY_7 = dmacHw_REG_CFG_LO_CH_PRIORITY_7 /* Channel priority 7. Highest priority DMA channel */ | |
61 | } dmacHw_CHANNEL_PRIORITY_e; | |
62 | ||
63 | /* Source destination master interface */ | |
64 | typedef enum { | |
65 | dmacHw_SRC_MASTER_INTERFACE_1 = dmacHw_REG_CTL_SMS_1, /* Source DMA master interface 1 */ | |
66 | dmacHw_SRC_MASTER_INTERFACE_2 = dmacHw_REG_CTL_SMS_2, /* Source DMA master interface 2 */ | |
67 | dmacHw_DST_MASTER_INTERFACE_1 = dmacHw_REG_CTL_DMS_1, /* Destination DMA master interface 1 */ | |
68 | dmacHw_DST_MASTER_INTERFACE_2 = dmacHw_REG_CTL_DMS_2 /* Destination DMA master interface 2 */ | |
69 | } dmacHw_MASTER_INTERFACE_e; | |
70 | ||
71 | typedef enum { | |
72 | dmacHw_SRC_TRANSACTION_WIDTH_8 = dmacHw_REG_CTL_SRC_TR_WIDTH_8, /* Source 8 bit (1 byte) per transaction */ | |
73 | dmacHw_SRC_TRANSACTION_WIDTH_16 = dmacHw_REG_CTL_SRC_TR_WIDTH_16, /* Source 16 bit (2 byte) per transaction */ | |
74 | dmacHw_SRC_TRANSACTION_WIDTH_32 = dmacHw_REG_CTL_SRC_TR_WIDTH_32, /* Source 32 bit (4 byte) per transaction */ | |
75 | dmacHw_SRC_TRANSACTION_WIDTH_64 = dmacHw_REG_CTL_SRC_TR_WIDTH_64, /* Source 64 bit (8 byte) per transaction */ | |
76 | dmacHw_DST_TRANSACTION_WIDTH_8 = dmacHw_REG_CTL_DST_TR_WIDTH_8, /* Destination 8 bit (1 byte) per transaction */ | |
77 | dmacHw_DST_TRANSACTION_WIDTH_16 = dmacHw_REG_CTL_DST_TR_WIDTH_16, /* Destination 16 bit (2 byte) per transaction */ | |
78 | dmacHw_DST_TRANSACTION_WIDTH_32 = dmacHw_REG_CTL_DST_TR_WIDTH_32, /* Destination 32 bit (4 byte) per transaction */ | |
79 | dmacHw_DST_TRANSACTION_WIDTH_64 = dmacHw_REG_CTL_DST_TR_WIDTH_64 /* Destination 64 bit (8 byte) per transaction */ | |
80 | } dmacHw_TRANSACTION_WIDTH_e; | |
81 | ||
82 | typedef enum { | |
83 | dmacHw_SRC_BURST_WIDTH_0 = dmacHw_REG_CTL_SRC_MSIZE_0, /* Source No burst */ | |
84 | dmacHw_SRC_BURST_WIDTH_4 = dmacHw_REG_CTL_SRC_MSIZE_4, /* Source 4 X dmacHw_TRANSACTION_WIDTH_xxx bytes per burst */ | |
85 | dmacHw_SRC_BURST_WIDTH_8 = dmacHw_REG_CTL_SRC_MSIZE_8, /* Source 8 X dmacHw_TRANSACTION_WIDTH_xxx bytes per burst */ | |
86 | dmacHw_SRC_BURST_WIDTH_16 = dmacHw_REG_CTL_SRC_MSIZE_16, /* Source 16 X dmacHw_TRANSACTION_WIDTH_xxx bytes per burst */ | |
87 | dmacHw_DST_BURST_WIDTH_0 = dmacHw_REG_CTL_DST_MSIZE_0, /* Destination No burst */ | |
88 | dmacHw_DST_BURST_WIDTH_4 = dmacHw_REG_CTL_DST_MSIZE_4, /* Destination 4 X dmacHw_TRANSACTION_WIDTH_xxx bytes per burst */ | |
89 | dmacHw_DST_BURST_WIDTH_8 = dmacHw_REG_CTL_DST_MSIZE_8, /* Destination 8 X dmacHw_TRANSACTION_WIDTH_xxx bytes per burst */ | |
90 | dmacHw_DST_BURST_WIDTH_16 = dmacHw_REG_CTL_DST_MSIZE_16 /* Destination 16 X dmacHw_TRANSACTION_WIDTH_xxx bytes per burst */ | |
91 | } dmacHw_BURST_WIDTH_e; | |
92 | ||
93 | typedef enum { | |
94 | dmacHw_TRANSFER_TYPE_MEM_TO_MEM = dmacHw_REG_CTL_TTFC_MM_DMAC, /* Memory to memory transfer */ | |
95 | dmacHw_TRANSFER_TYPE_PERIPHERAL_TO_MEM = dmacHw_REG_CTL_TTFC_PM_DMAC, /* Peripheral to memory transfer */ | |
96 | dmacHw_TRANSFER_TYPE_MEM_TO_PERIPHERAL = dmacHw_REG_CTL_TTFC_MP_DMAC, /* Memory to peripheral transfer */ | |
97 | dmacHw_TRANSFER_TYPE_PERIPHERAL_TO_PERIPHERAL = dmacHw_REG_CTL_TTFC_PP_DMAC /* Peripheral to peripheral transfer */ | |
98 | } dmacHw_TRANSFER_TYPE_e; | |
99 | ||
100 | typedef enum { | |
101 | dmacHw_TRANSFER_MODE_PERREQUEST, /* Block transfer per DMA request */ | |
102 | dmacHw_TRANSFER_MODE_CONTINUOUS, /* Continuous transfer of streaming data */ | |
103 | dmacHw_TRANSFER_MODE_PERIODIC /* Periodic transfer of streaming data */ | |
104 | } dmacHw_TRANSFER_MODE_e; | |
105 | ||
106 | typedef enum { | |
107 | dmacHw_SRC_ADDRESS_UPDATE_MODE_INC = dmacHw_REG_CTL_SINC_INC, /* Increment source address after every transaction */ | |
108 | dmacHw_SRC_ADDRESS_UPDATE_MODE_DEC = dmacHw_REG_CTL_SINC_DEC, /* Decrement source address after every transaction */ | |
109 | dmacHw_DST_ADDRESS_UPDATE_MODE_INC = dmacHw_REG_CTL_DINC_INC, /* Increment destination address after every transaction */ | |
110 | dmacHw_DST_ADDRESS_UPDATE_MODE_DEC = dmacHw_REG_CTL_DINC_DEC, /* Decrement destination address after every transaction */ | |
111 | dmacHw_SRC_ADDRESS_UPDATE_MODE_NC = dmacHw_REG_CTL_SINC_NC, /* No change in source address after every transaction */ | |
112 | dmacHw_DST_ADDRESS_UPDATE_MODE_NC = dmacHw_REG_CTL_DINC_NC /* No change in destination address after every transaction */ | |
113 | } dmacHw_ADDRESS_UPDATE_MODE_e; | |
114 | ||
115 | typedef enum { | |
116 | dmacHw_FLOW_CONTROL_DMA, /* DMA working as flow controller (default) */ | |
117 | dmacHw_FLOW_CONTROL_PERIPHERAL /* Peripheral working as flow controller */ | |
118 | } dmacHw_FLOW_CONTROL_e; | |
119 | ||
120 | typedef enum { | |
121 | dmacHw_TRANSFER_STATUS_BUSY, /* DMA Transfer ongoing */ | |
122 | dmacHw_TRANSFER_STATUS_DONE, /* DMA Transfer completed */ | |
123 | dmacHw_TRANSFER_STATUS_ERROR /* DMA Transfer error */ | |
124 | } dmacHw_TRANSFER_STATUS_e; | |
125 | ||
126 | typedef enum { | |
127 | dmacHw_INTERRUPT_DISABLE, /* Interrupt disable */ | |
128 | dmacHw_INTERRUPT_ENABLE /* Interrupt enable */ | |
129 | } dmacHw_INTERRUPT_e; | |
130 | ||
131 | typedef enum { | |
132 | dmacHw_INTERRUPT_STATUS_NONE = 0x0, /* No DMA interrupt */ | |
133 | dmacHw_INTERRUPT_STATUS_TRANS = 0x1, /* End of DMA transfer interrupt */ | |
134 | dmacHw_INTERRUPT_STATUS_BLOCK = 0x2, /* End of block transfer interrupt */ | |
135 | dmacHw_INTERRUPT_STATUS_ERROR = 0x4 /* Error interrupt */ | |
136 | } dmacHw_INTERRUPT_STATUS_e; | |
137 | ||
138 | typedef enum { | |
139 | dmacHw_CONTROLLER_ATTRIB_CHANNEL_NUM, /* Number of DMA channel */ | |
140 | dmacHw_CONTROLLER_ATTRIB_CHANNEL_MAX_BLOCK_SIZE, /* Maximum channel burst size */ | |
141 | dmacHw_CONTROLLER_ATTRIB_MASTER_INTF_NUM, /* Number of DMA master interface */ | |
142 | dmacHw_CONTROLLER_ATTRIB_CHANNEL_BUS_WIDTH, /* Channel Data bus width */ | |
143 | dmacHw_CONTROLLER_ATTRIB_CHANNEL_FIFO_SIZE /* Channel FIFO size */ | |
144 | } dmacHw_CONTROLLER_ATTRIB_e; | |
145 | ||
146 | typedef unsigned long dmacHw_HANDLE_t; /* DMA channel handle */ | |
147 | typedef uint32_t dmacHw_ID_t; /* DMA channel Id. Must be created using | |
148 | "dmacHw_MAKE_CHANNEL_ID" macro | |
149 | */ | |
150 | /* DMA channel configuration parameters */ | |
151 | typedef struct { | |
152 | uint32_t srcPeripheralPort; /* Source peripheral port */ | |
153 | uint32_t dstPeripheralPort; /* Destination peripheral port */ | |
154 | uint32_t srcStatusRegisterAddress; /* Source status register address */ | |
155 | uint32_t dstStatusRegisterAddress; /* Destination status register address of type */ | |
156 | ||
157 | uint32_t srcGatherWidth; /* Number of bytes gathered before successive gather opearation */ | |
158 | uint32_t srcGatherJump; /* Number of bytes jumpped before successive gather opearation */ | |
159 | uint32_t dstScatterWidth; /* Number of bytes sacattered before successive scatter opearation */ | |
160 | uint32_t dstScatterJump; /* Number of bytes jumpped before successive scatter opearation */ | |
161 | uint32_t maxDataPerBlock; /* Maximum number of bytes to be transferred per block/descrptor. | |
162 | 0 = Maximum possible. | |
163 | */ | |
164 | ||
165 | dmacHw_ADDRESS_UPDATE_MODE_e srcUpdate; /* Source address update mode */ | |
166 | dmacHw_ADDRESS_UPDATE_MODE_e dstUpdate; /* Destination address update mode */ | |
167 | dmacHw_TRANSFER_TYPE_e transferType; /* DMA transfer type */ | |
168 | dmacHw_TRANSFER_MODE_e transferMode; /* DMA transfer mode */ | |
169 | dmacHw_MASTER_INTERFACE_e srcMasterInterface; /* DMA source interface */ | |
170 | dmacHw_MASTER_INTERFACE_e dstMasterInterface; /* DMA destination interface */ | |
171 | dmacHw_TRANSACTION_WIDTH_e srcMaxTransactionWidth; /* Source transaction width */ | |
172 | dmacHw_TRANSACTION_WIDTH_e dstMaxTransactionWidth; /* Destination transaction width */ | |
173 | dmacHw_BURST_WIDTH_e srcMaxBurstWidth; /* Source burst width */ | |
174 | dmacHw_BURST_WIDTH_e dstMaxBurstWidth; /* Destination burst width */ | |
175 | dmacHw_INTERRUPT_e blockTransferInterrupt; /* Block trsnafer interrupt */ | |
176 | dmacHw_INTERRUPT_e completeTransferInterrupt; /* Complete DMA trsnafer interrupt */ | |
177 | dmacHw_INTERRUPT_e errorInterrupt; /* Error interrupt */ | |
178 | dmacHw_CHANNEL_PRIORITY_e channelPriority; /* Channel priority */ | |
179 | dmacHw_FLOW_CONTROL_e flowControler; /* Data flow controller */ | |
180 | } dmacHw_CONFIG_t; | |
181 | ||
182 | /****************************************************************************/ | |
183 | /** | |
184 | * @brief Initializes DMA | |
185 | * | |
186 | * This function initializes DMA CSP driver | |
187 | * | |
188 | * @note | |
189 | * Must be called before using any DMA channel | |
190 | */ | |
191 | /****************************************************************************/ | |
192 | void dmacHw_initDma(void); | |
193 | ||
194 | /****************************************************************************/ | |
195 | /** | |
196 | * @brief Exit function for DMA | |
197 | * | |
198 | * This function isolates DMA from the system | |
199 | * | |
200 | */ | |
201 | /****************************************************************************/ | |
202 | void dmacHw_exitDma(void); | |
203 | ||
204 | /****************************************************************************/ | |
205 | /** | |
206 | * @brief Gets a handle to a DMA channel | |
207 | * | |
208 | * This function returns a handle, representing a control block of a particular DMA channel | |
209 | * | |
210 | * @return -1 - On Failure | |
211 | * handle - On Success, representing a channel control block | |
212 | * | |
213 | * @note | |
214 | * None Channel ID must be created using "dmacHw_MAKE_CHANNEL_ID" macro | |
215 | */ | |
216 | /****************************************************************************/ | |
217 | dmacHw_HANDLE_t dmacHw_getChannelHandle(dmacHw_ID_t channelId /* [ IN ] DMA Channel Id */ | |
218 | ); | |
219 | ||
220 | /****************************************************************************/ | |
221 | /** | |
222 | * @brief Initializes a DMA channel for use | |
223 | * | |
224 | * This function initializes and resets a DMA channel for use | |
225 | * | |
226 | * @return -1 - On Failure | |
227 | * 0 - On Success | |
228 | * | |
229 | * @note | |
230 | * None | |
231 | */ | |
232 | /****************************************************************************/ | |
233 | int dmacHw_initChannel(dmacHw_HANDLE_t handle /* [ IN ] DMA Channel handle */ | |
234 | ); | |
235 | ||
236 | /****************************************************************************/ | |
237 | /** | |
238 | * @brief Estimates number of descriptor needed to perform certain DMA transfer | |
239 | * | |
240 | * | |
241 | * @return On failure : -1 | |
242 | * On success : Number of descriptor count | |
243 | * | |
244 | * | |
245 | */ | |
246 | /****************************************************************************/ | |
247 | int dmacHw_calculateDescriptorCount(dmacHw_CONFIG_t *pConfig, /* [ IN ] Configuration settings */ | |
248 | void *pSrcAddr, /* [ IN ] Source (Peripheral/Memory) address */ | |
249 | void *pDstAddr, /* [ IN ] Destination (Peripheral/Memory) address */ | |
250 | size_t dataLen /* [ IN ] Data length in bytes */ | |
251 | ); | |
252 | ||
253 | /****************************************************************************/ | |
254 | /** | |
255 | * @brief Initializes descriptor ring | |
256 | * | |
257 | * This function will initializes the descriptor ring of a DMA channel | |
258 | * | |
259 | * | |
260 | * @return -1 - On failure | |
261 | * 0 - On success | |
262 | * @note | |
263 | * - "len" parameter should be obtained from "dmacHw_descriptorLen" | |
264 | * - Descriptor buffer MUST be 32 bit aligned and uncached as it | |
265 | * is accessed by ARM and DMA | |
266 | */ | |
267 | /****************************************************************************/ | |
268 | int dmacHw_initDescriptor(void *pDescriptorVirt, /* [ IN ] Virtual address of uncahced buffer allocated to form descriptor ring */ | |
269 | uint32_t descriptorPhyAddr, /* [ IN ] Physical address of pDescriptorVirt (descriptor buffer) */ | |
270 | uint32_t len, /* [ IN ] Size of the pBuf */ | |
271 | uint32_t num /* [ IN ] Number of descriptor in the ring */ | |
272 | ); | |
273 | ||
274 | /****************************************************************************/ | |
275 | /** | |
276 | * @brief Finds amount of memory required to form a descriptor ring | |
277 | * | |
278 | * | |
279 | * @return Number of bytes required to form a descriptor ring | |
280 | * | |
281 | * | |
282 | * @note | |
283 | * None | |
284 | */ | |
285 | /****************************************************************************/ | |
286 | uint32_t dmacHw_descriptorLen(uint32_t descCnt /* [ IN ] Number of descriptor in the ring */ | |
287 | ); | |
288 | ||
289 | /****************************************************************************/ | |
290 | /** | |
291 | * @brief Configure DMA channel | |
292 | * | |
293 | * @return 0 : On success | |
294 | * -1 : On failure | |
295 | */ | |
296 | /****************************************************************************/ | |
297 | int dmacHw_configChannel(dmacHw_HANDLE_t handle, /* [ IN ] DMA Channel handle */ | |
298 | dmacHw_CONFIG_t *pConfig /* [ IN ] Configuration settings */ | |
299 | ); | |
300 | ||
301 | /****************************************************************************/ | |
302 | /** | |
303 | * @brief Set descriptors for known data length | |
304 | * | |
305 | * When DMA has to work as a flow controller, this function prepares the | |
306 | * descriptor chain to transfer data | |
307 | * | |
308 | * from: | |
309 | * - Memory to memory | |
310 | * - Peripheral to memory | |
311 | * - Memory to Peripheral | |
312 | * - Peripheral to Peripheral | |
313 | * | |
314 | * @return -1 - On failure | |
315 | * 0 - On success | |
316 | * | |
317 | */ | |
318 | /****************************************************************************/ | |
319 | int dmacHw_setDataDescriptor(dmacHw_CONFIG_t *pConfig, /* [ IN ] Configuration settings */ | |
320 | void *pDescriptor, /* [ IN ] Descriptor buffer */ | |
321 | void *pSrcAddr, /* [ IN ] Source (Peripheral/Memory) address */ | |
322 | void *pDstAddr, /* [ IN ] Destination (Peripheral/Memory) address */ | |
323 | size_t dataLen /* [ IN ] Length in bytes */ | |
324 | ); | |
325 | ||
326 | /****************************************************************************/ | |
327 | /** | |
328 | * @brief Indicates whether DMA transfer is in progress or completed | |
329 | * | |
330 | * @return DMA transfer status | |
331 | * dmacHw_TRANSFER_STATUS_BUSY: DMA Transfer ongoing | |
332 | * dmacHw_TRANSFER_STATUS_DONE: DMA Transfer completed | |
333 | * dmacHw_TRANSFER_STATUS_ERROR: DMA Transfer error | |
334 | * | |
335 | */ | |
336 | /****************************************************************************/ | |
337 | dmacHw_TRANSFER_STATUS_e dmacHw_transferCompleted(dmacHw_HANDLE_t handle /* [ IN ] DMA Channel handle */ | |
338 | ); | |
339 | ||
340 | /****************************************************************************/ | |
341 | /** | |
342 | * @brief Set descriptor carrying control information | |
343 | * | |
344 | * This function will be used to send specific control information to the device | |
345 | * using the DMA channel | |
346 | * | |
347 | * | |
348 | * @return -1 - On failure | |
349 | * 0 - On success | |
350 | * | |
351 | * @note | |
352 | * None | |
353 | */ | |
354 | /****************************************************************************/ | |
355 | int dmacHw_setControlDescriptor(dmacHw_CONFIG_t *pConfig, /* [ IN ] Configuration settings */ | |
356 | void *pDescriptor, /* [ IN ] Descriptor buffer */ | |
357 | uint32_t ctlAddress, /* [ IN ] Address of the device control register */ | |
358 | uint32_t control /* [ IN ] Device control information */ | |
359 | ); | |
360 | ||
361 | /****************************************************************************/ | |
362 | /** | |
363 | * @brief Read data DMA transferred to memory | |
364 | * | |
25985edc | 365 | * This function will read data that has been DMAed to memory while transferring from: |
1a4a561b LC |
366 | * - Memory to memory |
367 | * - Peripheral to memory | |
368 | * | |
369 | * @return 0 - No more data is available to read | |
370 | * 1 - More data might be available to read | |
371 | * | |
372 | */ | |
373 | /****************************************************************************/ | |
374 | int dmacHw_readTransferredData(dmacHw_HANDLE_t handle, /* [ IN ] DMA Channel handle */ | |
375 | dmacHw_CONFIG_t *pConfig, /* [ IN ] Configuration settings */ | |
376 | void *pDescriptor, /* [ IN ] Descriptor buffer */ | |
377 | void **ppBbuf, /* [ OUT ] Data received */ | |
378 | size_t *pLlen /* [ OUT ] Length of the data received */ | |
379 | ); | |
380 | ||
381 | /****************************************************************************/ | |
382 | /** | |
383 | * @brief Prepares descriptor ring, when source peripheral working as a flow controller | |
384 | * | |
385 | * This function will form the descriptor ring by allocating buffers, when source peripheral | |
386 | * has to work as a flow controller to transfer data from: | |
387 | * - Peripheral to memory. | |
388 | * | |
389 | * @return -1 - On failure | |
390 | * 0 - On success | |
391 | * | |
392 | * | |
393 | * @note | |
394 | * None | |
395 | */ | |
396 | /****************************************************************************/ | |
397 | int dmacHw_setVariableDataDescriptor(dmacHw_HANDLE_t handle, /* [ IN ] DMA Channel handle */ | |
398 | dmacHw_CONFIG_t *pConfig, /* [ IN ] Configuration settings */ | |
399 | void *pDescriptor, /* [ IN ] Descriptor buffer */ | |
400 | uint32_t srcAddr, /* [ IN ] Source peripheral address */ | |
401 | void *(*fpAlloc) (int len), /* [ IN ] Function pointer that provides destination memory */ | |
402 | int len, /* [ IN ] Number of bytes "fpAlloc" will allocate for destination */ | |
403 | int num /* [ IN ] Number of descriptor to set */ | |
404 | ); | |
405 | ||
406 | /****************************************************************************/ | |
407 | /** | |
408 | * @brief Program channel register to initiate transfer | |
409 | * | |
410 | * @return void | |
411 | * | |
412 | * | |
413 | * @note | |
414 | * - Descriptor buffer MUST ALWAYS be flushed before calling this function | |
415 | * - This function should also be called from ISR to program the channel with | |
416 | * pending descriptors | |
417 | */ | |
418 | /****************************************************************************/ | |
419 | void dmacHw_initiateTransfer(dmacHw_HANDLE_t handle, /* [ IN ] DMA Channel handle */ | |
420 | dmacHw_CONFIG_t *pConfig, /* [ IN ] Configuration settings */ | |
421 | void *pDescriptor /* [ IN ] Descriptor buffer */ | |
422 | ); | |
423 | ||
424 | /****************************************************************************/ | |
425 | /** | |
426 | * @brief Resets descriptor control information | |
427 | * | |
428 | * @return void | |
429 | */ | |
430 | /****************************************************************************/ | |
431 | void dmacHw_resetDescriptorControl(void *pDescriptor /* [ IN ] Descriptor buffer */ | |
432 | ); | |
433 | ||
434 | /****************************************************************************/ | |
435 | /** | |
436 | * @brief Program channel register to stop transfer | |
437 | * | |
438 | * Ensures the channel is not doing any transfer after calling this function | |
439 | * | |
440 | * @return void | |
441 | * | |
442 | */ | |
443 | /****************************************************************************/ | |
444 | void dmacHw_stopTransfer(dmacHw_HANDLE_t handle /* [ IN ] DMA Channel handle */ | |
445 | ); | |
446 | ||
447 | /****************************************************************************/ | |
448 | /** | |
25985edc | 449 | * @brief Check the existence of pending descriptor |
1a4a561b LC |
450 | * |
451 | * This function confirmes if there is any pending descriptor in the chain | |
452 | * to program the channel | |
453 | * | |
454 | * @return 1 : Channel need to be programmed with pending descriptor | |
455 | * 0 : No more pending descriptor to programe the channel | |
456 | * | |
457 | * @note | |
458 | * - This function should be called from ISR in case there are pending | |
459 | * descriptor to program the channel. | |
460 | * | |
461 | * Example: | |
462 | * | |
463 | * dmac_isr () | |
464 | * { | |
465 | * ... | |
466 | * if (dmacHw_descriptorPending (handle)) | |
467 | * { | |
468 | * dmacHw_initiateTransfer (handle); | |
469 | * } | |
470 | * } | |
471 | * | |
472 | */ | |
473 | /****************************************************************************/ | |
474 | uint32_t dmacHw_descriptorPending(dmacHw_HANDLE_t handle, /* [ IN ] DMA Channel handle */ | |
475 | void *pDescriptor /* [ IN ] Descriptor buffer */ | |
476 | ); | |
477 | ||
478 | /****************************************************************************/ | |
479 | /** | |
480 | * @brief Deallocates source or destination memory, allocated | |
481 | * | |
482 | * This function can be called to deallocate data memory that was DMAed successfully | |
483 | * | |
484 | * @return -1 - On failure | |
485 | * 0 - On success | |
486 | * | |
487 | * @note | |
488 | * This function will be called ONLY, when source OR destination address is pointing | |
489 | * to dynamic memory | |
490 | */ | |
491 | /****************************************************************************/ | |
492 | int dmacHw_freeMem(dmacHw_CONFIG_t *pConfig, /* [ IN ] Configuration settings */ | |
493 | void *pDescriptor, /* [ IN ] Descriptor buffer */ | |
494 | void (*fpFree) (void *) /* [ IN ] Function pointer to free data memory */ | |
495 | ); | |
496 | ||
497 | /****************************************************************************/ | |
498 | /** | |
499 | * @brief Clears the interrupt | |
500 | * | |
501 | * This function clears the DMA channel specific interrupt | |
502 | * | |
503 | * @return N/A | |
504 | * | |
505 | * @note | |
506 | * Must be called under the context of ISR | |
507 | */ | |
508 | /****************************************************************************/ | |
509 | void dmacHw_clearInterrupt(dmacHw_HANDLE_t handle /* [ IN ] DMA Channel handle */ | |
510 | ); | |
511 | ||
512 | /****************************************************************************/ | |
513 | /** | |
514 | * @brief Returns the cause of channel specific DMA interrupt | |
515 | * | |
516 | * This function returns the cause of interrupt | |
517 | * | |
518 | * @return Interrupt status, each bit representing a specific type of interrupt | |
519 | * of type dmacHw_INTERRUPT_STATUS_e | |
520 | * @note | |
521 | * This function should be called under the context of ISR | |
522 | */ | |
523 | /****************************************************************************/ | |
524 | dmacHw_INTERRUPT_STATUS_e dmacHw_getInterruptStatus(dmacHw_HANDLE_t handle /* [ IN ] DMA Channel handle */ | |
525 | ); | |
526 | ||
527 | /****************************************************************************/ | |
528 | /** | |
529 | * @brief Indentifies a DMA channel causing interrupt | |
530 | * | |
531 | * This functions returns a channel causing interrupt of type dmacHw_INTERRUPT_STATUS_e | |
532 | * | |
533 | * @return NULL : No channel causing DMA interrupt | |
534 | * ! NULL : Handle to a channel causing DMA interrupt | |
535 | * @note | |
536 | * dmacHw_clearInterrupt() must be called with a valid handle after calling this function | |
537 | */ | |
538 | /****************************************************************************/ | |
539 | dmacHw_HANDLE_t dmacHw_getInterruptSource(void); | |
540 | ||
541 | /****************************************************************************/ | |
542 | /** | |
543 | * @brief Sets channel specific user data | |
544 | * | |
25985edc | 545 | * This function associates user data to a specific DMA channel |
1a4a561b LC |
546 | * |
547 | */ | |
548 | /****************************************************************************/ | |
549 | void dmacHw_setChannelUserData(dmacHw_HANDLE_t handle, /* [ IN ] DMA Channel handle */ | |
550 | void *userData /* [ IN ] User data */ | |
551 | ); | |
552 | ||
553 | /****************************************************************************/ | |
554 | /** | |
555 | * @brief Gets channel specific user data | |
556 | * | |
557 | * This function returns user data specific to a DMA channel | |
558 | * | |
559 | * @return user data | |
560 | */ | |
561 | /****************************************************************************/ | |
562 | void *dmacHw_getChannelUserData(dmacHw_HANDLE_t handle /* [ IN ] DMA Channel handle */ | |
563 | ); | |
564 | ||
565 | /****************************************************************************/ | |
566 | /** | |
567 | * @brief Displays channel specific registers and other control parameters | |
568 | * | |
569 | * | |
570 | * @return void | |
571 | * | |
572 | * @note | |
573 | * None | |
574 | */ | |
575 | /****************************************************************************/ | |
576 | void dmacHw_printDebugInfo(dmacHw_HANDLE_t handle, /* [ IN ] DMA Channel handle */ | |
577 | void *pDescriptor, /* [ IN ] Descriptor buffer */ | |
578 | int (*fpPrint) (const char *, ...) /* [ IN ] Print callback function */ | |
579 | ); | |
580 | ||
581 | /****************************************************************************/ | |
582 | /** | |
583 | * @brief Provides DMA controller attributes | |
584 | * | |
585 | * | |
586 | * @return DMA controller attributes | |
587 | * | |
588 | * @note | |
589 | * None | |
590 | */ | |
591 | /****************************************************************************/ | |
592 | uint32_t dmacHw_getDmaControllerAttribute(dmacHw_HANDLE_t handle, /* [ IN ] DMA Channel handle */ | |
b595076a | 593 | dmacHw_CONTROLLER_ATTRIB_e attr /* [ IN ] DMA Controller attribute of type dmacHw_CONTROLLER_ATTRIB_e */ |
1a4a561b LC |
594 | ); |
595 | ||
596 | #endif /* _DMACHW_H */ |