git.sur5r.net Git - freertos/blob - FreeRTOS/Demo/CORTEX_R5_UltraScale_MPSoC/RTOSDemo_R5_bsp/psu_cortexr5_0/libsrc/csudma_v1_2/src/xcsudma.h

   1 /******************************************************************************
   2 *
   3 * Copyright (C) 2014-2018 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_2
  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 *       ms      03/17/17 Added readme.txt file in examples folder for doxygen
 103 *                        generation.
 104 *       ms      04/10/17 Modified filename tag in xcsudma_selftest_example.c to
 105 *                        include the file in doxygen examples.
 106 * 1.2   adk     11/22/17 Added peripheral test app support for CSUDMA driver.
 107 *       adk     09/03/18 Added new API XCsuDma_64BitTransfer() useful for 64-bit
 108 *                        dma transfers through PMU processor(CR#996201).
 109 * </pre>
 110 *
 111 ******************************************************************************/
 112
 113 #ifndef XCSUDMA_H_
 114 #define XCSUDMA_H_      /**< Prevent circular inclusions
 115                           *  by using protection macros */
 116
 117 #ifdef __cplusplus
 118 extern "C" {
 119 #endif
 120
 121 /***************************** Include Files *********************************/
 122
 123 #include "xcsudma_hw.h"
 124 #include "xil_types.h"
 125 #include "xil_assert.h"
 126 #include "xstatus.h"
 127 #include "xil_cache.h"
 128
 129 /************************** Constant Definitions *****************************/
 130
 131 /** @name CSU_DMA Channels
 132  * @{
 133  */
 134 typedef enum {
 135         XCSUDMA_SRC_CHANNEL = 0U,       /**< Source Channel of CSU_DMA */
 136         XCSUDMA_DST_CHANNEL             /**< Destination Channel of CSU_DMA */
 137 }XCsuDma_Channel;
 138 /*@}*/
 139
 140 /** @name CSU_DMA pause types
 141  * @{
 142  */
 143 typedef enum {
 144         XCSUDMA_PAUSE_MEMORY,           /**< Pauses memory data transfer
 145                                           *  to/from CSU_DMA */
 146         XCSUDMA_PAUSE_STREAM,           /**< Pauses stream data transfer
 147                                           *  to/from CSU_DMA */
 148 }XCsuDma_PauseType;
 149
 150 /*@}*/
 151
 152
 153 /** @name Ranges of Size
 154  * @{
 155  */
 156 #define XCSUDMA_SIZE_MAX 0x07FFFFFF     /**< Maximum allowed no of words */
 157
 158 /*@}*/
 159
 160 /***************** Macros (Inline Functions) Definitions *********************/
 161
 162 /*****************************************************************************/
 163 /**
 164 *
 165 * This function resets the CSU_DMA core.
 166 *
 167 * @param        None.
 168 *
 169 * @return       None.
 170 *
 171 * @note         None.
 172 *               C-style signature:
 173 *               void XCsuDma_Reset()
 174 *
 175 ******************************************************************************/
 176 #define XCsuDma_Reset()  \
 177         Xil_Out32(((u32)(XCSU_BASEADDRESS) + (u32)(XCSU_DMA_RESET_OFFSET)), \
 178                                 (u32)(XCSUDMA_RESET_SET_MASK)); \
 179         Xil_Out32(((u32)(XCSU_BASEADDRESS) + (u32)(XCSU_DMA_RESET_OFFSET)), \
 180                                         (u32)(XCSUDMA_RESET_UNSET_MASK));
 181
 182 /*****************************************************************************/
 183 /**
 184 * This function will be in busy while loop until the data transfer is
 185 * completed.
 186 *
 187 * @param        InstancePtr is a pointer to XCsuDma instance to be worked on.
 188 * @param        Channel represents the type of channel either it is Source or
 189 *               Destination.
 190 *               Source channel      - XCSUDMA_SRC_CHANNEL
 191 *               Destination Channel - XCSUDMA_DST_CHANNEL
 192 *
 193 * @return       None.
 194 *
 195 * @note         This function should be called after XCsuDma_Transfer in polled
 196 *               mode  to wait until the data gets transfered completely.
 197 *               C-style signature:
 198 *               void XCsuDma_WaitForDone(XCsuDma *InstancePtr,
 199 *                                               XCsuDma_Channel Channel)
 200 *
 201 ******************************************************************************/
 202 #define XCsuDma_WaitForDone(InstancePtr,Channel) \
 203                 while((XCsuDma_ReadReg(((InstancePtr)->Config.BaseAddress), \
 204                         ((u32)(XCSUDMA_I_STS_OFFSET) + \
 205                         ((u32)(Channel) * (u32)(XCSUDMA_OFFSET_DIFF)))) & \
 206                 (u32)(XCSUDMA_IXR_DONE_MASK)) != (XCSUDMA_IXR_DONE_MASK))
 207
 208 /*****************************************************************************/
 209 /**
 210 *
 211 * This function returns the number of completed SRC/DST DMA transfers that
 212 * have not been acknowledged by software based on the channel selection.
 213 *
 214 * @param        InstancePtr is a pointer to XCsuDma instance to be worked on.
 215 * @param        Channel represents the type of channel either it is Source or
 216 *               Destination.
 217 *               Source channel      - XCSUDMA_SRC_CHANNEL
 218 *               Destination Channel - XCSUDMA_DST_CHANNEL
 219 *
 220 * @return       Count is number of completed DMA transfers but not acknowledged
 221 *               (Range is 0 to 7).
 222 *               - 000 - All finished transfers have been acknowledged.
 223 *               - Count - Count number of finished transfers are still
 224 *               outstanding.
 225 *
 226 * @note         None.
 227 *               C-style signature:
 228 *               u8 XCsuDma_GetDoneCount(XCsuDma *InstancePtr,
 229 *                                               XCsuDma_Channel Channel)
 230 *
 231 ******************************************************************************/
 232 #define XCsuDma_GetDoneCount(InstancePtr, Channel)  \
 233                 ((XCsuDma_ReadReg(((InstancePtr)->Config.BaseAddress), \
 234                         ((u32)(XCSUDMA_STS_OFFSET) + \
 235                         ((u32)(Channel) * (u32)(XCSUDMA_OFFSET_DIFF)))) & \
 236                         (u32)(XCSUDMA_STS_DONE_CNT_MASK)) >> \
 237                                 (u32)(XCSUDMA_STS_DONE_CNT_SHIFT))
 238
 239 /*****************************************************************************/
 240 /**
 241 *
 242 * This function returns the current SRC/DST FIFO level in 32 bit words of the
 243 * selected channel
 244 * @param        InstancePtr is a pointer to XCsuDma instance to be worked on.
 245 * @param        Channel represents the type of channel either it is Source or
 246 *               Destination.
 247 *               Source channel      - XCSUDMA_SRC_CHANNEL
 248 *               Destination Channel - XCSUDMA_DST_CHANNEL
 249 *
 250 * @return       FIFO level. (Range is 0 to 128)
 251 *               - 0 Indicates empty
 252 *               - Any number 1 to 128 indicates the number of entries in FIFO.
 253 *
 254 * @note         None.
 255 *               C-style signature:
 256 *               u8 XCsuDma_GetFIFOLevel(XCsuDma *InstancePtr,
 257 *                                       XCsuDma_Channel Channel)
 258 *
 259 ******************************************************************************/
 260 #define XCsuDma_GetFIFOLevel(InstancePtr, Channel)  \
 261                 ((XCsuDma_ReadReg(((InstancePtr)->Config.BaseAddress), \
 262                         ((u32)(XCSUDMA_STS_OFFSET) + \
 263                         ((u32)(Channel) * (u32)(XCSUDMA_OFFSET_DIFF)))) & \
 264                         (u32)(XCSUDMA_STS_FIFO_LEVEL_MASK)) >> \
 265                                         (u32)(XCSUDMA_STS_FIFO_LEVEL_SHIFT))
 266
 267 /*****************************************************************************/
 268 /**
 269 *
 270 * This function returns the current number of read(src)/write(dst) outstanding
 271 * commands based on the type of channel selected.
 272 *
 273 * @param        InstancePtr is a pointer to XCsuDma instance to be worked on.
 274 * @param        Channel represents the type of channel either it is Source or
 275 *               Destination.
 276 *               Source channel      - XCSUDMA_SRC_CHANNEL
 277 *               Destination Channel - XCSUDMA_DST_CHANNEL
 278 *
 279 * @return       Count of outstanding commands. (Range is 0 to 9).
 280 *
 281 * @note         None.
 282 *               C-style signature:
 283 *               u8 XCsuDma_GetWROutstandCount(XCsuDma *InstancePtr,
 284 *                                               XCsuDma_Channel Channel)
 285 *
 286 ******************************************************************************/
 287 #define XCsuDma_GetWROutstandCount(InstancePtr, Channel)  \
 288                 ((XCsuDma_ReadReg(((InstancePtr)->Config.BaseAddress), \
 289                                 ((u32)(XCSUDMA_STS_OFFSET) + \
 290                         ((u32)(Channel) * (u32)(XCSUDMA_OFFSET_DIFF)))) & \
 291                         (u32)(XCUSDMA_STS_OUTSTDG_MASK)) >> \
 292                                 (u32)(XCUSDMA_STS_OUTSTDG_SHIFT))
 293
 294 /*****************************************************************************/
 295 /**
 296 *
 297 * This function returns the status of Channel either it is busy or not.
 298 *
 299 * @param        InstancePtr is a pointer to XCsuDma instance to be worked on.
 300 * @param        Channel represents the type of channel either it is Source or
 301 *               Destination.
 302 *               Source channel      - XCSUDMA_SRC_CHANNEL
 303 *               Destination Channel - XCSUDMA_DST_CHANNEL
 304 *
 305 * @return       Returns the current status of the core.
 306 *               - TRUE represents core is currently busy.
 307 *               - FALSE represents core is not involved in any transfers.
 308 *
 309 * @note         None.
 310 *               C-style signature:
 311 *               s32 XCsuDma_IsBusy(XCsuDma *InstancePtr, XCsuDma_Channel Channel)
 312 *
 313 ******************************************************************************/
 314
 315 #define XCsuDma_IsBusy(InstancePtr, Channel) \
 316                 ((XCsuDma_ReadReg(((InstancePtr)->Config.BaseAddress), \
 317                                         ((u32)(XCSUDMA_STS_OFFSET) + \
 318                         ((u32)(Channel) * (u32)(XCSUDMA_OFFSET_DIFF)))) & \
 319                 (u32)(XCSUDMA_STS_BUSY_MASK)) == (XCSUDMA_STS_BUSY_MASK)) ? \
 320                                 (TRUE) : (FALSE)
 321
 322
 323 /**************************** Type Definitions *******************************/
 324
 325 /**
 326 * This typedef contains configuration information for a CSU_DMA core.
 327 * Each CSU_DMA core should have a configuration structure associated.
 328 */
 329 typedef struct {
 330         u16 DeviceId;           /**< DeviceId is the unique ID of the
 331                                   *  device */
 332         u32 BaseAddress;        /**< BaseAddress is the physical base address
 333                                   *  of the device's registers */
 334 } XCsuDma_Config;
 335
 336
 337 /******************************************************************************/
 338 /**
 339 *
 340 * The XCsuDma driver instance data structure. A pointer to an instance data
 341 * structure is passed around by functions to refer to a specific driver
 342 * instance.
 343 */
 344 typedef struct {
 345         XCsuDma_Config Config;          /**< Hardware configuration */
 346         u32 IsReady;                    /**< Device and the driver instance
 347                                           *  are initialized */
 348 }XCsuDma;
 349
 350
 351 /******************************************************************************/
 352 /**
 353 * This typedef contains all the configuration feilds which needs to be set
 354 * before the start of the data transfer. All these feilds of CSU_DMA can be
 355 * configured by using XCsuDma_SetConfig API.
 356 */
 357 typedef struct {
 358         u8 SssFifoThesh;        /**< SSS FIFO threshold value */
 359         u8 ApbErr;              /**< ABP invalid access error */
 360         u8 EndianType;          /**< Type of endianess */
 361         u8 AxiBurstType;        /**< Type of AXI bus */
 362         u32 TimeoutValue;       /**< Time out value */
 363         u8 FifoThresh;          /**< FIFO threshold value */
 364         u8 Acache;              /**< AXI CACHE selection */
 365         u8 RouteBit;            /**< Selection of Route */
 366         u8 TimeoutEn;           /**< Enable of time out counters */
 367         u16 TimeoutPre;         /**< Pre scaler value */
 368         u8 MaxOutCmds;          /**< Maximum number of outstanding
 369                                   *  commands */
 370 }XCsuDma_Configure;
 371
 372 /*****************************************************************************/
 373
 374
 375 /************************** Function Prototypes ******************************/
 376
 377 XCsuDma_Config *XCsuDma_LookupConfig(u16 DeviceId);
 378
 379 s32 XCsuDma_CfgInitialize(XCsuDma *InstancePtr, XCsuDma_Config *CfgPtr,
 380                         u32 EffectiveAddr);
 381 void XCsuDma_Transfer(XCsuDma *InstancePtr, XCsuDma_Channel Channel,
 382                                         UINTPTR Addr, u32 Size, u8 EnDataLast);
 383 void XCsuDma_64BitTransfer(XCsuDma *InstancePtr, XCsuDma_Channel Channel,
 384                            u32 AddrLow, u32 AddrHigh, u32 Size, u8 EnDataLast);
 385 void XCsuDma_LoopBackTransfer(XCsuDma *InstancePtr, u64 SrcAddr, u64 DstAddr,
 386                                                 u32 Size);
 387 u64 XCsuDma_GetAddr(XCsuDma *InstancePtr, XCsuDma_Channel Channel);
 388 u32 XCsuDma_GetSize(XCsuDma *InstancePtr, XCsuDma_Channel Channel);
 389
 390 void XCsuDma_Pause(XCsuDma *InstancePtr, XCsuDma_Channel Channel,
 391                                                 XCsuDma_PauseType Type);
 392 s32 XCsuDma_IsPaused(XCsuDma *InstancePtr, XCsuDma_Channel Channel,
 393                                                 XCsuDma_PauseType Type);
 394 void XCsuDma_Resume(XCsuDma *InstancePtr, XCsuDma_Channel Channel,
 395                                                 XCsuDma_PauseType Type);
 396
 397 u32 XCsuDma_GetCheckSum(XCsuDma *InstancePtr);
 398 void XCsuDma_ClearCheckSum(XCsuDma *InstancePtr);
 399
 400 void XCsuDma_SetConfig(XCsuDma *InstancePtr, XCsuDma_Channel Channel,
 401                                         XCsuDma_Configure *ConfigurValues);
 402 void XCsuDma_GetConfig(XCsuDma *InstancePtr, XCsuDma_Channel Channel,
 403                                         XCsuDma_Configure *ConfigurValues);
 404 void XCsuDma_ClearDoneCount(XCsuDma *InstancePtr, XCsuDma_Channel Channel);
 405
 406 void XCsuDma_SetSafetyCheck(XCsuDma *InstancePtr, u32 Value);
 407 u32 XCsuDma_GetSafetyCheck(XCsuDma *InstancePtr);
 408
 409 /* Interrupt related APIs */
 410 u32 XCsuDma_IntrGetStatus(XCsuDma *InstancePtr, XCsuDma_Channel Channel);
 411 void XCsuDma_IntrClear(XCsuDma *InstancePtr, XCsuDma_Channel Channel,
 412                                                                 u32 Mask);
 413 void XCsuDma_EnableIntr(XCsuDma *InstancePtr, XCsuDma_Channel Channel,
 414                                                                 u32 Mask);
 415 void XCsuDma_DisableIntr(XCsuDma *InstancePtr, XCsuDma_Channel Channel,
 416                                                                 u32 Mask);
 417 u32 XCsuDma_GetIntrMask(XCsuDma *InstancePtr, XCsuDma_Channel Channel);
 418
 419 s32 XCsuDma_SelfTest(XCsuDma *InstancePtr);
 420
 421 /******************************************************************************/
 422
 423 #ifdef __cplusplus
 424 }
 425
 426 #endif
 427
 428 #endif /* End of protection macro */
 429 /** @} */