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