git.sur5r.net Git - freertos/blob - FreeRTOS/Demo/CORTEX_A53_64-bit_UltraScale_MPSoC/RTOSDemo_A53_bsp/psu_cortexa53_0/libsrc/csudma_v1_1/src/xcsudma.h

   1 /******************************************************************************
   2 *
   3 * Copyright (C) 2014 Xilinx, Inc.  All rights reserved.
   4 *
   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:
  11 *
  12 * The above copyright notice and this permission notice shall be included in
  13 * all copies or substantial portions of the Software.
  14 *
  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.
  18 *
  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
  25 * SOFTWARE.
  26 *
  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.
  30 *
  31 ******************************************************************************/
  32 /*****************************************************************************/
  33 /**
  34 *
  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).
  40 *
  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
  43 * transfer data:
  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
  47 *
  48 * <b>Initialization & Configuration</b>
  49 *
  50 * The device driver enables higher layer software (e.g., an application) to
  51 * communicate to the CSU_DMA core.
  52 *
  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.
  57 *
  58 * <b> Interrupts </b>
  59 * This driver will not support handling of interrupts user should write handler
  60 * to handle the interrupts.
  61 *
  62 * <b> Virtual Memory </b>
  63 *
  64 * This driver supports Virtual Memory. The RTOS is responsible for calculating
  65 * the correct device base address in Virtual Memory space.
  66 *
  67 * <b> Threads </b>
  68 *
  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.
  71 *
  72 * <b> Asserts </b>
  73 *
  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.
  78 *
  79 * <b> Building the driver </b>
  80 *
  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.
  83 *
  84 * @file xcsudma.h
  85 * @addtogroup csudma_v1_0
  86 * @{
  87 * @details
  88 *
  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.
  92 *
  93 *
  94 * <pre>
  95 * MODIFICATION HISTORY:
  96 *
  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.
 102 * </pre>
 103 *
 104 ******************************************************************************/
 105
 106 #ifndef XCSUDMA_H_
 107 #define XCSUDMA_H_      /**< Prevent circular inclusions
 108                           *  by using protection macros */
 109
 110 #ifdef __cplusplus
 111 extern "C" {
 112 #endif
 113
 114 /***************************** Include Files *********************************/
 115
 116 #include "xcsudma_hw.h"
 117 #include "xil_types.h"
 118 #include "xil_assert.h"
 119 #include "xstatus.h"
 120 #include "xil_cache.h"
 121
 122 /************************** Constant Definitions *****************************/
 123
 124 /** @name CSU_DMA Channels
 125  * @{
 126  */
 127 typedef enum {
 128         XCSUDMA_SRC_CHANNEL = 0U,       /**< Source Channel of CSU_DMA */
 129         XCSUDMA_DST_CHANNEL             /**< Destination Channel of CSU_DMA */
 130 }XCsuDma_Channel;
 131 /*@}*/
 132
 133 /** @name CSU_DMA pause types
 134  * @{
 135  */
 136 typedef enum {
 137         XCSUDMA_PAUSE_MEMORY,           /**< Pauses memory data transfer
 138                                           *  to/from CSU_DMA */
 139         XCSUDMA_PAUSE_STREAM,           /**< Pauses stream data transfer
 140                                           *  to/from CSU_DMA */
 141 }XCsuDma_PauseType;
 142
 143 /*@}*/
 144
 145
 146 /** @name Ranges of Size
 147  * @{
 148  */
 149 #define XCSUDMA_SIZE_MAX 0x07FFFFFF     /**< Maximum allowed no of words */
 150
 151 /*@}*/
 152
 153 /***************** Macros (Inline Functions) Definitions *********************/
 154
 155 /*****************************************************************************/
 156 /**
 157 *
 158 * This function resets the CSU_DMA core.
 159 *
 160 * @param        None.
 161 *
 162 * @return       None.
 163 *
 164 * @note         None.
 165 *               C-style signature:
 166 *               void XCsuDma_Reset()
 167 *
 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));
 174
 175 /*****************************************************************************/
 176 /**
 177 * This function will be in busy while loop until the data transfer is
 178 * completed.
 179 *
 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
 182 *               Destination.
 183 *               Source channel      - XCSUDMA_SRC_CHANNEL
 184 *               Destination Channel - XCSUDMA_DST_CHANNEL
 185 *
 186 * @return       None.
 187 *
 188 * @note         This function should be called after XCsuDma_Transfer in polled
 189 *               mode  to wait until the data gets transfered completely.
 190 *               C-style signature:
 191 *               void XCsuDma_WaitForDone(XCsuDma *InstancePtr,
 192 *                                               XCsuDma_Channel Channel)
 193 *
 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))
 200
 201 /*****************************************************************************/
 202 /**
 203 *
 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.
 206 *
 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
 209 *               Destination.
 210 *               Source channel      - XCSUDMA_SRC_CHANNEL
 211 *               Destination Channel - XCSUDMA_DST_CHANNEL
 212 *
 213 * @return       Count is number of completed DMA transfers but not acknowledged
 214 *               (Range is 0 to 7).
 215 *               - 000 - All finished transfers have been acknowledged.
 216 *               - Count - Count number of finished transfers are still
 217 *               outstanding.
 218 *
 219 * @note         None.
 220 *               C-style signature:
 221 *               u8 XCsuDma_GetDoneCount(XCsuDma *InstancePtr,
 222 *                                               XCsuDma_Channel Channel)
 223 *
 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))
 231
 232 /*****************************************************************************/
 233 /**
 234 *
 235 * This function returns the current SRC/DST FIFO level in 32 bit words of the
 236 * selected channel
 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
 239 *               Destination.
 240 *               Source channel      - XCSUDMA_SRC_CHANNEL
 241 *               Destination Channel - XCSUDMA_DST_CHANNEL
 242 *
 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.
 246 *
 247 * @note         None.
 248 *               C-style signature:
 249 *               u8 XCsuDma_GetFIFOLevel(XCsuDma *InstancePtr,
 250 *                                       XCsuDma_Channel Channel)
 251 *
 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))
 259
 260 /*****************************************************************************/
 261 /**
 262 *
 263 * This function returns the current number of read(src)/write(dst) outstanding
 264 * commands based on the type of channel selected.
 265 *
 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
 268 *               Destination.
 269 *               Source channel      - XCSUDMA_SRC_CHANNEL
 270 *               Destination Channel - XCSUDMA_DST_CHANNEL
 271 *
 272 * @return       Count of outstanding commands. (Range is 0 to 9).
 273 *
 274 * @note         None.
 275 *               C-style signature:
 276 *               u8 XCsuDma_GetWROutstandCount(XCsuDma *InstancePtr,
 277 *                                               XCsuDma_Channel Channel)
 278 *
 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))
 286
 287 /*****************************************************************************/
 288 /**
 289 *
 290 * This function returns the status of Channel either it is busy or not.
 291 *
 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
 294 *               Destination.
 295 *               Source channel      - XCSUDMA_SRC_CHANNEL
 296 *               Destination Channel - XCSUDMA_DST_CHANNEL
 297 *
 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.
 301 *
 302 * @note         None.
 303 *               C-style signature:
 304 *               s32 XCsuDma_IsBusy(XCsuDma *InstancePtr, XCsuDma_Channel Channel)
 305 *
 306 ******************************************************************************/
 307
 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)) ? \
 313                                 (TRUE) : (FALSE)
 314
 315
 316 /**************************** Type Definitions *******************************/
 317
 318 /**
 319 * This typedef contains configuration information for a CSU_DMA core.
 320 * Each CSU_DMA core should have a configuration structure associated.
 321 */
 322 typedef struct {
 323         u16 DeviceId;           /**< DeviceId is the unique ID of the
 324                                   *  device */
 325         u32 BaseAddress;        /**< BaseAddress is the physical base address
 326                                   *  of the device's registers */
 327 } XCsuDma_Config;
 328
 329
 330 /******************************************************************************/
 331 /**
 332 *
 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
 335 * instance.
 336 */
 337 typedef struct {
 338         XCsuDma_Config Config;          /**< Hardware configuration */
 339         u32 IsReady;                    /**< Device and the driver instance
 340                                           *  are initialized */
 341 }XCsuDma;
 342
 343
 344 /******************************************************************************/
 345 /**
 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.
 349 */
 350 typedef struct {
 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
 362                                   *  commands */
 363 }XCsuDma_Configure;
 364
 365 /*****************************************************************************/
 366
 367
 368 /************************** Function Prototypes ******************************/
 369
 370 XCsuDma_Config *XCsuDma_LookupConfig(u16 DeviceId);
 371
 372 s32 XCsuDma_CfgInitialize(XCsuDma *InstancePtr, XCsuDma_Config *CfgPtr,
 373                         u32 EffectiveAddr);
 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,
 377                                                 u32 Size);
 378 u64 XCsuDma_GetAddr(XCsuDma *InstancePtr, XCsuDma_Channel Channel);
 379 u32 XCsuDma_GetSize(XCsuDma *InstancePtr, XCsuDma_Channel Channel);
 380
 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);
 387
 388 u32 XCsuDma_GetCheckSum(XCsuDma *InstancePtr);
 389 void XCsuDma_ClearCheckSum(XCsuDma *InstancePtr);
 390
 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);
 396
 397 void XCsuDma_SetSafetyCheck(XCsuDma *InstancePtr, u32 Value);
 398 u32 XCsuDma_GetSafetyCheck(XCsuDma *InstancePtr);
 399
 400 /* Interrupt related APIs */
 401 u32 XCsuDma_IntrGetStatus(XCsuDma *InstancePtr, XCsuDma_Channel Channel);
 402 void XCsuDma_IntrClear(XCsuDma *InstancePtr, XCsuDma_Channel Channel,
 403                                                                 u32 Mask);
 404 void XCsuDma_EnableIntr(XCsuDma *InstancePtr, XCsuDma_Channel Channel,
 405                                                                 u32 Mask);
 406 void XCsuDma_DisableIntr(XCsuDma *InstancePtr, XCsuDma_Channel Channel,
 407                                                                 u32 Mask);
 408 u32 XCsuDma_GetIntrMask(XCsuDma *InstancePtr, XCsuDma_Channel Channel);
 409
 410 s32 XCsuDma_SelfTest(XCsuDma *InstancePtr);
 411
 412 /******************************************************************************/
 413
 414 #ifdef __cplusplus
 415 }
 416
 417 #endif
 418
 419 #endif /* End of protection macro */
 420 /** @} */