1 /******************************************************************************
3 * Copyright (C) 2014 Xilinx, Inc. All rights reserved.
5 * Permission is hereby granted, free of charge, to any person obtaining a copy
6 * of this software and associated documentation files (the "Software"), to deal
7 * in the Software without restriction, including without limitation the rights
8 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9 * copies of the Software, and to permit persons to whom the Software is
10 * furnished to do so, subject to the following conditions:
12 * The above copyright notice and this permission notice shall be included in
13 * all copies or substantial portions of the Software.
15 * Use of the Software is limited solely to applications:
16 * (a) running on a Xilinx device, or
17 * (b) that interact with a Xilinx device through a bus or interconnect.
19 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
20 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
21 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
22 * XILINX BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
23 * WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF
24 * OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
27 * Except as contained in this notice, the name of the Xilinx shall not be used
28 * in advertising or otherwise to promote the sale, use or other dealings in
29 * this Software without prior written authorization from Xilinx.
31 ******************************************************************************/
32 /*****************************************************************************/
36 * @addtogroup zdma_v1_0
40 * ZDMA is a general purpose DMA designed to support memory to memory and memory
41 * to IO buffer transfers. ALTO has two instance of general purpose ZDMA.
42 * One is located in FPD (full power domain) which is GDMA and other is located
43 * in LPD (low power domain) which is ADMA.
45 * GMDA & ADMA are configured each with 8 DMA channels and and each channel can
46 * be programmed secure or non-secure.
47 * Each channel is divided into two functional sides, Source (Read) and
48 * Destination (Write). Each DMA channel can be independently programmed
49 * in one of following DMA modes.
51 * - Normal data transfer from source to destination.
54 * - Scatter Gather DMA
55 * - Only Normal mode it can't support other two modes.
56 * In Scatter gather descriptor can be of 3 types
57 * - Linear descriptor.
58 * - Linked list descriptor
59 * - Hybrid descriptor (Combination of both Linear and Linked list)
60 * Our driver will not support Hybrid type of descriptor.
62 * <b>Initialization & Configuration</b>
64 * The device driver enables higher layer software (e.g., an application) to
65 * communicate to the ZDMA core.
67 * XZDma_CfgInitialize() API is used to initialize the ZDMA core.
68 * The user needs to first call the XZDma_LookupConfig() API which returns
69 * the Configuration structure pointer which is passed as a parameter to the
70 * XZDma_CfgInitialize() API.
73 * The driver provides an interrupt handler XZDma_IntrHandler for handling
74 * the interrupt from the ZDMA core. The users of this driver have to
75 * register this handler with the interrupt system and provide the callback
76 * functions by using XZDma_SetCallBack API. In this version Descriptor done
79 * <b> Virtual Memory </b>
81 * This driver supports Virtual Memory. The RTOS is responsible for calculating
82 * the correct device base address in Virtual Memory space.
86 * This driver is not thread safe. Any needs for threads or thread mutual
87 * exclusion must be satisfied by the layer above this driver.
91 * Asserts are used within all Xilinx drivers to enforce constraints on argument
92 * values. Asserts can be turned off on a system-wide basis by defining, at
93 * compile time, the NDEBUG identifier. By default, asserts are turned on and it
94 * is recommended that users leave asserts on during development.
96 * <b> Building the driver </b>
98 * The XZDma driver is composed of several source files. This allows the user
99 * to build and link only those parts of the driver that are necessary.
101 * This header file contains identifiers and register-level driver functions (or
102 * macros), range macros, structure typedefs that can be used to access the
103 * Xilinx ZDMA core instance.
106 * MODIFICATION HISTORY:
108 * Ver Who Date Changes
109 * ----- ------ -------- ------------------------------------------------------
110 * 1.0 vns 2/27/15 First release
111 * 1.1 vns 15/02/16 Corrected Destination descriptor addresss calculation
112 * in XZDma_CreateBDList API
113 * Modified XZDma_SetMode to return XST_FAILURE on
114 * selecting DMA mode other than normal mode in
115 * scatter gather mode data transfer and corrected
116 * XZDma_SetChDataConfig API to set over fetch and
117 * src issue parameters correctly.
121 ******************************************************************************/
129 /***************************** Include Files *********************************/
131 #include "xzdma_hw.h"
132 #include "xil_assert.h"
134 #include "xil_cache.h"
136 /************************** Constant Definitions *****************************/
139 /**************************** Type Definitions *******************************/
141 /** @name ZDMA Handler Types
145 XZDMA_HANDLER_DONE, /**< For Done Handler */
146 XZDMA_HANDLER_ERROR, /**< For Error Handler */
150 /** @name ZDMA Descriptors Types
154 XZDMA_LINEAR, /**< Linear descriptor */
155 XZDMA_LINKEDLIST, /**< Linked list descriptor */
159 /** @name ZDMA Operation modes
163 XZDMA_NORMAL_MODE, /**< Normal transfer from source to
165 XZDMA_WRONLY_MODE, /**< Write only mode */
166 XZDMA_RDONLY_MODE /**< Read only mode */
174 XZDMA_IDLE, /**< ZDMA is in Idle state */
175 XZDMA_PAUSE, /**< Paused state */
176 XZDMA_BUSY, /**< Busy state */
180 /** @name ZDMA AXI Burst type
184 XZDMA_FIXED_BURST = 0, /**< Fixed burst type */
185 XZDMA_INCR_BURST /**< Increment burst type */
189 /******************************************************************************/
191 * This typedef contains scatter gather descriptor fields for ZDMA core.
194 void *SrcDscrPtr; /**< Source Descriptor pointer */
195 void *DstDscrPtr; /**< Destination Descriptor pointer */
196 u32 DscrCount; /**< Count of descriptors available */
197 XZDma_DscrType DscrType;/**< Type of descriptor either Linear or
198 * Linked list type */
201 /******************************************************************************/
203 * This typedef contains scatter gather descriptor fields for ZDMA core.
206 u64 Address; /**< Address */
207 u32 Size; /**< Word2, Size of data */
208 u32 Cntl; /**< Word3 Control data */
209 u64 NextDscr; /**< Address of next descriptor */
210 u64 Reserved; /**< Reserved address */
211 } __attribute__ ((packed)) XZDma_LlDscr;
213 /******************************************************************************/
215 * This typedef contains Linear descriptor fields for ZDMA core.
218 u64 Address; /**< Address */
219 u32 Size; /**< Word3, Size of data */
220 u32 Cntl; /**< Word4, control data */
221 } __attribute__ ((packed)) XZDma_LiDscr;
223 /******************************************************************************/
226 * This typedef contains the data configurations of ZDMA core
229 u8 OverFetch; /**< Enable Over fetch */
230 u8 SrcIssue; /**< Outstanding transactions for Source */
231 XZDma_BurstType SrcBurstType;
232 /**< Burst type for SRC */
233 u8 SrcBurstLen; /**< AXI length for data read */
234 XZDma_BurstType DstBurstType;
235 /**< Burst type for DST */
236 u8 DstBurstLen; /**< AXI length for data write */
237 u8 SrcCache; /**< AXI cache bits for data read */
238 u8 SrcQos; /**< AXI QOS bits for data read */
239 u8 DstCache; /**< AXI cache bits for data write */
240 u8 DstQos; /**< AXI QOS bits for data write */
243 /******************************************************************************/
246 * This typedef contains the descriptor configurations of ZDMA core
249 u8 AxCoherent; /**< AXI transactions are coherent or non-coherent */
250 u8 AXCache; /**< AXI cache for DSCR fetch */
251 u8 AXQos; /**< Qos bit for DSCR fetch */
254 /******************************************************************************/
256 * Callback type for Completion of all data transfers.
258 * @param CallBackRef is a callback reference passed in by the upper layer
259 * when setting the callback functions, and passed back to the
260 * upper layer when the callback is invoked.
261 *******************************************************************************/
262 typedef void (*XZDma_DoneHandler) (void *CallBackRef);
264 /******************************************************************************/
266 * Callback type for all error interrupts.
268 * @param CallBackRef is a callback reference passed in by the upper layer
269 * when setting the callback functions, and passed back to the
270 * upper layer when the callback is invoked.
271 * @param ErrorMask is a bit mask indicating the cause of the error. Its
272 * value equals 'OR'ing one or more XZDMA_IXR_* values defined in
274 ****************************************************************************/
275 typedef void (*XZDma_ErrorHandler) (void *CallBackRef, u32 ErrorMask);
278 * This typedef contains configuration information for a ZDMA core
279 * Each ZDMA core should have a configuration structure associated.
282 u16 DeviceId; /**< Device Id of ZDMA */
283 u32 BaseAddress; /**< BaseAddress of ZDMA */
284 u8 DmaType; /**< Type of DMA */
287 /******************************************************************************/
290 * The XZDma driver instance data structure. A pointer to an instance data
291 * structure is passed around by functions to refer to a specific driver
295 XZDma_Config Config; /**< Hardware configuration */
296 u32 IsReady; /**< Device and the driver instance
298 u32 IntrMask; /**< Mask for enabling interrupts */
300 XZDma_Mode Mode; /**< Mode of ZDMA core to be operated */
301 u8 IsSgDma; /**< Is ZDMA core is in scatter gather or
302 * not will be specified */
303 XZDma_Descriptor Descriptor; /**< It contains information about
306 XZDma_DoneHandler DoneHandler; /**< Call back for transfer
308 void *DoneRef; /**< To be passed to the done
309 * interrupt callback */
311 XZDma_ErrorHandler ErrorHandler;/**< Call back for error
313 void *ErrorRef; /**< To be passed to the error
314 * interrupt callback */
315 XZDma_DataConfig DataConfig; /**< Current configurations */
316 XZDma_DscrConfig DscrConfig; /**< Current configurations */
317 XZDmaState ChannelState; /**< ZDMA channel is busy */
321 /******************************************************************************/
324 * This typedef contains the fields for transfer of data.
327 UINTPTR SrcAddr; /**< Source address */
328 UINTPTR DstAddr; /**< Destination Address */
329 u32 Size; /**< Size of the data to be transferred */
330 u8 SrcCoherent; /**< Source coherent */
331 u8 DstCoherent; /**< Destination coherent */
332 u8 Pause; /**< Will pause data transmission after
333 * this transfer only for SG mode */
336 /***************** Macros (Inline Functions) Definitions *********************/
338 /*****************************************************************************/
341 * This function returns interrupt status read from Interrupt Status Register.
342 * Use the XZDMA_IXR_DMA_*_MASK constants defined in xzdma_hw.h to interpret the
345 * @param InstancePtr is a pointer to the XZDma instance.
347 * @return The pending interrupts of the ZDMA core.
348 * Use the masks specified in xzdma_hw.h to interpret
349 * the returned value.
352 * void XZDma_IntrGetStatus(XZDma *InstancePtr)
354 ******************************************************************************/
355 #define XZDma_IntrGetStatus(InstancePtr) \
356 XZDma_ReadReg((InstancePtr)->Config.BaseAddress, XZDMA_CH_ISR_OFFSET)
358 /*****************************************************************************/
361 * This function clears interrupt(s). Every bit set in Interrupt Status
362 * Register indicates that a specific type of interrupt is occurring, and this
363 * function clears one or more interrupts by writing a bit mask to Interrupt
366 * @param InstancePtr is a pointer to the XZDma instance.
367 * @param Mask is the type of the interrupts to enable. Use OR'ing of
368 * XZDMA_IXR_DMA_*_MASK constants defined in xzdma_hw.h to create
369 * this parameter value.
375 * void XZDma_IntrClear(XZDma *InstancePtr)
377 ******************************************************************************/
378 #define XZDma_IntrClear(InstancePtr, Mask) \
379 XZDma_WriteReg( (InstancePtr)->Config.BaseAddress, \
380 XZDMA_CH_ISR_OFFSET, ((u32)(Mask) & (u32)XZDMA_IXR_ALL_INTR_MASK))
382 /*****************************************************************************/
385 * This function returns interrupt mask to know which interrupts are
386 * enabled and which of them were disabled.
388 * @param InstancePtr is a pointer to the XZDma instance.
390 * @return The current interrupt mask. The mask indicates which interrupts
391 * are enabled/disabled.
392 * 0 bit represents .....corresponding interrupt is enabled.
393 * 1 bit represents .....Corresponding interrupt is disabled.
397 * void XZDma_GetIntrMask(XZDma *InstancePtr)
399 ******************************************************************************/
400 #define XZDma_GetIntrMask(InstancePtr) \
401 XZDma_ReadReg((InstancePtr)->Config.BaseAddress, \
402 (u32)(XZDMA_CH_IMR_OFFSET))
404 /*****************************************************************************/
407 * This function enables individual interrupts of the ZDMA core by updating
408 * the Interrupt Enable register.
410 * @param InstancePtr is a pointer to the XZDma instance.
411 * @param Mask is the type of the interrupts to enable. Use OR'ing of
412 * XZDMA_IXR_DMA_*_MASK constants defined in xzdma_hw.h to create
413 * this parameter value.
417 * @note The existing enabled interrupt(s) will remain enabled.
419 * void XZDma_EnableIntr(XZDma *InstancePtr, u32 Mask)
421 ******************************************************************************/
422 #define XZDma_EnableIntr(InstancePtr, Mask) \
423 (InstancePtr)->IntrMask = ((InstancePtr)->IntrMask | (Mask))
425 /*****************************************************************************/
428 * This function disables individual interrupts of the ZDMA core by updating
429 * the Interrupt Disable register.
431 * @param InstancePtr is a pointer to the XZDma instance.
432 * @param Mask is the type of the interrupts to disable. Use OR'ing of
433 * XZDMA_IXR_DMA_*_MASK constants defined in xzdma_hw.h to create
434 * this parameter value.
438 * @note The existing disabled interrupt(s) will remain disabled.
440 * void XZDma_DisableIntr(XZDma *InstancePtr, u32 Mask)
442 ******************************************************************************/
443 #define XZDma_DisableIntr(InstancePtr, Mask) \
444 XZDma_WriteReg( (InstancePtr)->Config.BaseAddress, \
445 XZDMA_CH_IDS_OFFSET, \
446 ((u32)XZDma_ReadReg((InstancePtr)->Config.BaseAddress, \
447 XZDMA_CH_IDS_OFFSET) | ((u32)(Mask) & (u32)XZDMA_IXR_ALL_INTR_MASK)))
449 /*****************************************************************************/
452 * This function returns source current payload address under process
455 * @param InstancePtr is a pointer to the XZDma instance.
459 * @note This address may not be precise due to ZDMA pipeline structure
461 * u64 XZDma_SrcCurPyld(XZDma *InstancePtr)
463 ******************************************************************************/
464 #define XZDma_SrcCurPyld(InstancePtr) \
465 ((u64)(XZDma_ReadReg((InstancePtr)->Config.BaseAddress, \
466 XZDMA_CH_SRC_CUR_PYLD_LSB_OFFSET)) | \
467 ((u64)(XZDma_ReadReg((InstancePtr)->Config.BaseAddress, \
468 XZDMA_CH_SRC_CUR_PYLD_MSB_OFFSET)) << XZDMA_WORD1_MSB_SHIFT))
470 /*****************************************************************************/
473 * This function returns destination current payload address under process
476 * @param InstancePtr is a pointer to the XZDma instance.
480 * @note This address may not be precise due to ZDMA pipeline structure
482 * u64 XZDma_DstCurPyld(XZDma *InstancePtr)
484 ******************************************************************************/
485 #define XZDma_DstCurPyld(InstancePtr) \
486 ((u64)(XZDma_ReadReg((InstancePtr)->Config.BaseAddress, \
487 XZDMA_CH_DST_CUR_PYLD_LSB_OFFSET)) | \
488 ((u64)(XZDma_ReadReg((InstancePtr)->Config.BaseAddress, \
489 XZDMA_CH_DST_CUR_PYLD_MSB_OFFSET)) << XZDMA_WORD1_MSB_SHIFT))
491 /*****************************************************************************/
494 * This function returns source descriptor current payload address under
495 * process of ZDMA core.
497 * @param InstancePtr is a pointer to the XZDma instance.
501 * @note This address may not be precise due to ZDMA pipeline structure
503 * u64 XZDma_SrcDscrCurPyld(XZDma *InstancePtr)
505 ******************************************************************************/
506 #define XZDma_SrcDscrCurPyld(InstancePtr) \
507 ((u64)(XZDma_ReadReg((InstancePtr)->Config.BaseAddress, \
508 XZDMA_CH_SRC_CUR_DSCR_LSB_OFFSET)) | \
509 ((u64)(XZDma_ReadReg((InstancePtr)->Config.BaseAddress, \
510 XZDMA_CH_SRC_CUR_DSCR_MSB_OFFSET)) << XZDMA_WORD1_MSB_SHIFT))
513 /*****************************************************************************/
516 * This function returns destination descriptor current payload address under
517 * process of ZDMA core.
519 * @param InstancePtr is a pointer to the XZDma instance.
523 * @note This address may not be precise due to ZDMA pipeline structure
525 * u64 XZDma_DstDscrCurPyld(XZDma *InstancePtr)
527 ******************************************************************************/
528 #define XZDma_DstDscrCurPyld(InstancePtr) \
529 ((u64)(XZDma_ReadReg((InstancePtr)->Config.BaseAddress, \
530 XZDMA_CH_DST_CUR_DSCR_LSB_OFFSET)) | \
531 ((u64)(XZDma_ReadReg((InstancePtr)->Config.BaseAddress, \
532 XZDMA_CH_DST_CUR_DSCR_MSB_OFFSET)) << XZDMA_WORD1_MSB_SHIFT))
534 /*****************************************************************************/
537 * This function gets the count of total bytes transferred through core
538 * since last clear in ZDMA core.
540 * @param InstancePtr is a pointer to the XZDma instance.
546 * void XZDma_GetTotalByte(XZDma *InstancePtr)
548 ******************************************************************************/
549 #define XZDma_GetTotalByte(InstancePtr) \
550 XZDma_ReadReg((InstancePtr)->Config.BaseAddress, \
551 XZDMA_CH_TOTAL_BYTE_OFFSET)
553 /*****************************************************************************/
556 * This function clears the count of total bytes transferred in ZDMA core.
558 * @param InstancePtr is a pointer to the XZDma instance.
564 * void XZDma_TotalByteClear(XZDma *InstancePtr)
566 ******************************************************************************/
567 #define XZDma_TotalByteClear(InstancePtr) \
568 XZDma_WriteReg((InstancePtr)->Config.BaseAddress, \
569 XZDMA_CH_TOTAL_BYTE_OFFSET, \
570 XZDma_ReadReg((InstancePtr)->Config.BaseAddress, \
571 XZDMA_CH_TOTAL_BYTE_OFFSET))
573 /*****************************************************************************/
576 * This function gets the total number of Interrupt count for source after last
579 * @param InstancePtr is a pointer to the XZDma instance.
583 * @note Once this API is called then count will become zero.
585 * void XZDma_GetSrcIntrCnt(XZDma *InstancePtr)
587 ******************************************************************************/
588 #define XZDma_GetSrcIntrCnt(InstancePtr) \
589 XZDma_ReadReg((InstancePtr)->Config.BaseAddress, \
590 XZDMA_CH_IRQ_SRC_ACCT_OFFSET)
592 /*****************************************************************************/
595 * This function gets the total number of Interrupt count for destination
596 * after last call of this API.
598 * @param InstancePtr is a pointer to the XZDma instance.
602 * @note Once this API is called then count will become zero.
604 * void XZDma_GetDstIntrCnt(XZDma *InstancePtr)
606 ******************************************************************************/
607 #define XZDma_GetDstIntrCnt(InstancePtr) \
608 XZDma_ReadReg((InstancePtr)->Config.BaseAddress, \
609 XZDMA_CH_IRQ_DST_ACCT_OFFSET)
611 /*****************************************************************************/
614 * This function Enable's the ZDMA core for initiating the data transfer once the
615 * data transfer completes it will be automatically disabled.
617 * @param InstancePtr is a pointer to the XZDma instance.
623 * void XZDma_EnableCh(XZDma *InstancePtr)
625 ******************************************************************************/
626 #define XZDma_EnableCh(InstancePtr) \
627 XZDma_WriteReg((InstancePtr)->Config.BaseAddress, \
628 (XZDMA_CH_CTRL2_OFFSET), (XZDMA_CH_CTRL2_EN_MASK))
630 /*****************************************************************************/
633 * This function Disable's the ZDMA core.
635 * @param InstancePtr is a pointer to the XZDma instance.
641 * void XZDma_DisableCh(XZDma *InstancePtr)
643 ******************************************************************************/
644 #define XZDma_DisableCh(InstancePtr) \
645 XZDma_WriteReg((InstancePtr)->Config.BaseAddress,\
646 (XZDMA_CH_CTRL2_OFFSET), (XZDMA_CH_CTRL2_DIS_MASK))
648 /************************ Prototypes of functions **************************/
650 XZDma_Config *XZDma_LookupConfig(u16 DeviceId);
652 s32 XZDma_CfgInitialize(XZDma *InstancePtr, XZDma_Config *CfgPtr,
654 s32 XZDma_SetMode(XZDma *InstancePtr, u8 IsSgDma, XZDma_Mode Mode);
655 u32 XZDma_CreateBDList(XZDma *InstancePtr, XZDma_DscrType TypeOfDscr,
656 UINTPTR Dscr_MemPtr, u32 NoOfBytes);
657 s32 XZDma_SetChDataConfig(XZDma *InstancePtr, XZDma_DataConfig *Configure);
658 void XZDma_GetChDataConfig(XZDma *InstancePtr, XZDma_DataConfig *Configure);
659 s32 XZDma_SetChDscrConfig(XZDma *InstancePtr, XZDma_DscrConfig *Configure);
660 void XZDma_GetChDscrConfig(XZDma *InstancePtr, XZDma_DscrConfig *Configure);
661 s32 XZDma_Start(XZDma *InstancePtr, XZDma_Transfer *Data, u32 Num);
662 void XZDma_WOData(XZDma *InstancePtr, u32 *Buffer);
663 void XZDma_Resume(XZDma *InstancePtr);
664 void XZDma_Reset(XZDma *InstancePtr);
665 XZDmaState XZDma_ChannelState(XZDma *InstancePtr);
667 s32 XZDma_SelfTest(XZDma *InstancePtr);
669 void XZDma_IntrHandler(void *Instance);
670 s32 XZDma_SetCallBack(XZDma *InstancePtr, XZDma_Handler HandlerType,
671 void *CallBackFunc, void *CallBackRef);
680 #endif /* XZDMA_H_ */