git.sur5r.net Git - freertos/blob

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