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 /*****************************************************************************/
35 * The CSU_DMA is present inside CSU (Configuration Security Unit) module which
36 * is located within the Low-Power Subsystem (LPS) internal to the PS.
37 * CSU_DMA allows the CSU to move data efficiently between the memory (32 bit
38 * AXI interface) and the CSU stream peripherals (SHA, AES and PCAP) via Secure
39 * Stream Switch (SSS).
41 * The CSU_DMA is a 2 channel simple DMA, allowing separate control of the SRC
42 * (read) channel and DST (write) channel. The DMA is effectively able to
44 * - From PS-side to the SSS-side (SRC DMA only)
45 * - From SSS-side to the PS-side (DST DMA only)
46 * - Simultaneous PS-side to SSS_side and SSS-side to the PS-side
48 * <b>Initialization & Configuration</b>
50 * The device driver enables higher layer software (e.g., an application) to
51 * communicate to the CSU_DMA core.
53 * XCsuDma_CfgInitialize() API is used to initialize the CSU_DMA core.
54 * The user needs to first call the XCsuDma_LookupConfig() API which returns
55 * the Configuration structure pointer which is passed as a parameter to the
56 * XCsuDma_CfgInitialize() API.
59 * This driver will not support handling of interrupts user should write handler
60 * to handle the interrupts.
62 * <b> Virtual Memory </b>
64 * This driver supports Virtual Memory. The RTOS is responsible for calculating
65 * the correct device base address in Virtual Memory space.
69 * This driver is not thread safe. Any needs for threads or thread mutual
70 * exclusion must be satisfied by the layer above this driver.
74 * Asserts are used within all Xilinx drivers to enforce constraints on argument
75 * values. Asserts can be turned off on a system-wide basis by defining, at
76 * compile time, the NDEBUG identifier. By default, asserts are turned on and it
77 * is recommended that users leave asserts on during development.
79 * <b> Building the driver </b>
81 * The XCsuDma driver is composed of several source files. This allows the user
82 * to build and link only those parts of the driver that are necessary.
85 * @addtogroup csudma_v1_0
89 * This header file contains identifiers and register-level driver functions (or
90 * macros), range macros, structure typedefs that can be used to access the
91 * Xilinx CSU_DMA core instance.
95 * MODIFICATION HISTORY:
97 * Ver Who Date Changes
98 * ----- ------ -------- -----------------------------------------------------
99 * 1.0 vnsld 22/10/14 First release
100 * 1.1 adk 10/05/16 Fixed CR#951040 race condition in the recv path when
101 * source and destination points to the same buffer.
104 ******************************************************************************/
107 #define XCSUDMA_H_ /**< Prevent circular inclusions
108 * by using protection macros */
114 /***************************** Include Files *********************************/
116 #include "xcsudma_hw.h"
117 #include "xil_types.h"
118 #include "xil_assert.h"
120 #include "xil_cache.h"
122 /************************** Constant Definitions *****************************/
124 /** @name CSU_DMA Channels
128 XCSUDMA_SRC_CHANNEL = 0U, /**< Source Channel of CSU_DMA */
129 XCSUDMA_DST_CHANNEL /**< Destination Channel of CSU_DMA */
133 /** @name CSU_DMA pause types
137 XCSUDMA_PAUSE_MEMORY, /**< Pauses memory data transfer
139 XCSUDMA_PAUSE_STREAM, /**< Pauses stream data transfer
146 /** @name Ranges of Size
149 #define XCSUDMA_SIZE_MAX 0x07FFFFFF /**< Maximum allowed no of words */
153 /***************** Macros (Inline Functions) Definitions *********************/
155 /*****************************************************************************/
158 * This function resets the CSU_DMA core.
166 * void XCsuDma_Reset()
168 ******************************************************************************/
169 #define XCsuDma_Reset() \
170 Xil_Out32(((u32)(XCSU_BASEADDRESS) + (u32)(XCSU_DMA_RESET_OFFSET)), \
171 (u32)(XCSUDMA_RESET_SET_MASK)); \
172 Xil_Out32(((u32)(XCSU_BASEADDRESS) + (u32)(XCSU_DMA_RESET_OFFSET)), \
173 (u32)(XCSUDMA_RESET_UNSET_MASK));
175 /*****************************************************************************/
177 * This function will be in busy while loop until the data transfer is
180 * @param InstancePtr is a pointer to XCsuDma instance to be worked on.
181 * @param Channel represents the type of channel either it is Source or
183 * Source channel - XCSUDMA_SRC_CHANNEL
184 * Destination Channel - XCSUDMA_DST_CHANNEL
188 * @note This function should be called after XCsuDma_Transfer in polled
189 * mode to wait until the data gets transfered completely.
191 * void XCsuDma_WaitForDone(XCsuDma *InstancePtr,
192 * XCsuDma_Channel Channel)
194 ******************************************************************************/
195 #define XCsuDma_WaitForDone(InstancePtr,Channel) \
196 while((XCsuDma_ReadReg(((InstancePtr)->Config.BaseAddress), \
197 ((u32)(XCSUDMA_I_STS_OFFSET) + \
198 ((u32)(Channel) * (u32)(XCSUDMA_OFFSET_DIFF)))) & \
199 (u32)(XCSUDMA_IXR_DONE_MASK)) != (XCSUDMA_IXR_DONE_MASK))
201 /*****************************************************************************/
204 * This function returns the number of completed SRC/DST DMA transfers that
205 * have not been acknowledged by software based on the channel selection.
207 * @param InstancePtr is a pointer to XCsuDma instance to be worked on.
208 * @param Channel represents the type of channel either it is Source or
210 * Source channel - XCSUDMA_SRC_CHANNEL
211 * Destination Channel - XCSUDMA_DST_CHANNEL
213 * @return Count is number of completed DMA transfers but not acknowledged
215 * - 000 - All finished transfers have been acknowledged.
216 * - Count - Count number of finished transfers are still
221 * u8 XCsuDma_GetDoneCount(XCsuDma *InstancePtr,
222 * XCsuDma_Channel Channel)
224 ******************************************************************************/
225 #define XCsuDma_GetDoneCount(InstancePtr, Channel) \
226 ((XCsuDma_ReadReg(((InstancePtr)->Config.BaseAddress), \
227 ((u32)(XCSUDMA_STS_OFFSET) + \
228 ((u32)(Channel) * (u32)(XCSUDMA_OFFSET_DIFF)))) & \
229 (u32)(XCSUDMA_STS_DONE_CNT_MASK)) >> \
230 (u32)(XCSUDMA_STS_DONE_CNT_SHIFT))
232 /*****************************************************************************/
235 * This function returns the current SRC/DST FIFO level in 32 bit words of the
237 * @param InstancePtr is a pointer to XCsuDma instance to be worked on.
238 * @param Channel represents the type of channel either it is Source or
240 * Source channel - XCSUDMA_SRC_CHANNEL
241 * Destination Channel - XCSUDMA_DST_CHANNEL
243 * @return FIFO level. (Range is 0 to 128)
244 * - 0 Indicates empty
245 * - Any number 1 to 128 indicates the number of entries in FIFO.
249 * u8 XCsuDma_GetFIFOLevel(XCsuDma *InstancePtr,
250 * XCsuDma_Channel Channel)
252 ******************************************************************************/
253 #define XCsuDma_GetFIFOLevel(InstancePtr, Channel) \
254 ((XCsuDma_ReadReg(((InstancePtr)->Config.BaseAddress), \
255 ((u32)(XCSUDMA_STS_OFFSET) + \
256 ((u32)(Channel) * (u32)(XCSUDMA_OFFSET_DIFF)))) & \
257 (u32)(XCSUDMA_STS_FIFO_LEVEL_MASK)) >> \
258 (u32)(XCSUDMA_STS_FIFO_LEVEL_SHIFT))
260 /*****************************************************************************/
263 * This function returns the current number of read(src)/write(dst) outstanding
264 * commands based on the type of channel selected.
266 * @param InstancePtr is a pointer to XCsuDma instance to be worked on.
267 * @param Channel represents the type of channel either it is Source or
269 * Source channel - XCSUDMA_SRC_CHANNEL
270 * Destination Channel - XCSUDMA_DST_CHANNEL
272 * @return Count of outstanding commands. (Range is 0 to 9).
276 * u8 XCsuDma_GetWROutstandCount(XCsuDma *InstancePtr,
277 * XCsuDma_Channel Channel)
279 ******************************************************************************/
280 #define XCsuDma_GetWROutstandCount(InstancePtr, Channel) \
281 ((XCsuDma_ReadReg(((InstancePtr)->Config.BaseAddress), \
282 ((u32)(XCSUDMA_STS_OFFSET) + \
283 ((u32)(Channel) * (u32)(XCSUDMA_OFFSET_DIFF)))) & \
284 (u32)(XCUSDMA_STS_OUTSTDG_MASK)) >> \
285 (u32)(XCUSDMA_STS_OUTSTDG_SHIFT))
287 /*****************************************************************************/
290 * This function returns the status of Channel either it is busy or not.
292 * @param InstancePtr is a pointer to XCsuDma instance to be worked on.
293 * @param Channel represents the type of channel either it is Source or
295 * Source channel - XCSUDMA_SRC_CHANNEL
296 * Destination Channel - XCSUDMA_DST_CHANNEL
298 * @return Returns the current status of the core.
299 * - TRUE represents core is currently busy.
300 * - FALSE represents core is not involved in any transfers.
304 * s32 XCsuDma_IsBusy(XCsuDma *InstancePtr, XCsuDma_Channel Channel)
306 ******************************************************************************/
308 #define XCsuDma_IsBusy(InstancePtr, Channel) \
309 ((XCsuDma_ReadReg(((InstancePtr)->Config.BaseAddress), \
310 ((u32)(XCSUDMA_STS_OFFSET) + \
311 ((u32)(Channel) * (u32)(XCSUDMA_OFFSET_DIFF)))) & \
312 (u32)(XCSUDMA_STS_BUSY_MASK)) == (XCSUDMA_STS_BUSY_MASK)) ? \
316 /**************************** Type Definitions *******************************/
319 * This typedef contains configuration information for a CSU_DMA core.
320 * Each CSU_DMA core should have a configuration structure associated.
323 u16 DeviceId; /**< DeviceId is the unique ID of the
325 u32 BaseAddress; /**< BaseAddress is the physical base address
326 * of the device's registers */
330 /******************************************************************************/
333 * The XCsuDma driver instance data structure. A pointer to an instance data
334 * structure is passed around by functions to refer to a specific driver
338 XCsuDma_Config Config; /**< Hardware configuration */
339 u32 IsReady; /**< Device and the driver instance
344 /******************************************************************************/
346 * This typedef contains all the configuration feilds which needs to be set
347 * before the start of the data transfer. All these feilds of CSU_DMA can be
348 * configured by using XCsuDma_SetConfig API.
351 u8 SssFifoThesh; /**< SSS FIFO threshold value */
352 u8 ApbErr; /**< ABP invalid access error */
353 u8 EndianType; /**< Type of endianess */
354 u8 AxiBurstType; /**< Type of AXI bus */
355 u32 TimeoutValue; /**< Time out value */
356 u8 FifoThresh; /**< FIFO threshold value */
357 u8 Acache; /**< AXI CACHE selection */
358 u8 RouteBit; /**< Selection of Route */
359 u8 TimeoutEn; /**< Enable of time out counters */
360 u16 TimeoutPre; /**< Pre scaler value */
361 u8 MaxOutCmds; /**< Maximum number of outstanding
365 /*****************************************************************************/
368 /************************** Function Prototypes ******************************/
370 XCsuDma_Config *XCsuDma_LookupConfig(u16 DeviceId);
372 s32 XCsuDma_CfgInitialize(XCsuDma *InstancePtr, XCsuDma_Config *CfgPtr,
374 void XCsuDma_Transfer(XCsuDma *InstancePtr, XCsuDma_Channel Channel,
375 UINTPTR Addr, u32 Size, u8 EnDataLast);
376 void XCsuDma_LoopBackTransfer(XCsuDma *InstancePtr, u64 SrcAddr, u64 DstAddr,
378 u64 XCsuDma_GetAddr(XCsuDma *InstancePtr, XCsuDma_Channel Channel);
379 u32 XCsuDma_GetSize(XCsuDma *InstancePtr, XCsuDma_Channel Channel);
381 void XCsuDma_Pause(XCsuDma *InstancePtr, XCsuDma_Channel Channel,
382 XCsuDma_PauseType Type);
383 s32 XCsuDma_IsPaused(XCsuDma *InstancePtr, XCsuDma_Channel Channel,
384 XCsuDma_PauseType Type);
385 void XCsuDma_Resume(XCsuDma *InstancePtr, XCsuDma_Channel Channel,
386 XCsuDma_PauseType Type);
388 u32 XCsuDma_GetCheckSum(XCsuDma *InstancePtr);
389 void XCsuDma_ClearCheckSum(XCsuDma *InstancePtr);
391 void XCsuDma_SetConfig(XCsuDma *InstancePtr, XCsuDma_Channel Channel,
392 XCsuDma_Configure *ConfigurValues);
393 void XCsuDma_GetConfig(XCsuDma *InstancePtr, XCsuDma_Channel Channel,
394 XCsuDma_Configure *ConfigurValues);
395 void XCsuDma_ClearDoneCount(XCsuDma *InstancePtr, XCsuDma_Channel Channel);
397 void XCsuDma_SetSafetyCheck(XCsuDma *InstancePtr, u32 Value);
398 u32 XCsuDma_GetSafetyCheck(XCsuDma *InstancePtr);
400 /* Interrupt related APIs */
401 u32 XCsuDma_IntrGetStatus(XCsuDma *InstancePtr, XCsuDma_Channel Channel);
402 void XCsuDma_IntrClear(XCsuDma *InstancePtr, XCsuDma_Channel Channel,
404 void XCsuDma_EnableIntr(XCsuDma *InstancePtr, XCsuDma_Channel Channel,
406 void XCsuDma_DisableIntr(XCsuDma *InstancePtr, XCsuDma_Channel Channel,
408 u32 XCsuDma_GetIntrMask(XCsuDma *InstancePtr, XCsuDma_Channel Channel);
410 s32 XCsuDma_SelfTest(XCsuDma *InstancePtr);
412 /******************************************************************************/
419 #endif /* End of protection macro */