git.sur5r.net Git - freertos/blob - FreeRTOS/Demo/CORTEX_A9_Zynq_ZC702/RTOSDemo_bsp/ps7_cortexa9_0/libsrc/scutimer_v2_0/src/xscutimer.h

   1 /******************************************************************************
   2 *
   3 * Copyright (C) 2010 - 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 * @file xscutimer.h
  36 * @addtogroup scutimer_v2_0
  37 * @{
  38 * @details
  39 *
  40 * The timer driver supports the Cortex A9 private timer.
  41 *
  42 * The timer driver supports the following features:
  43 * - Normal mode and Auto reload mode
  44 * - Interrupts (Interrupt handler is not provided in this driver. Application
  45 *               has to register it's own handler)
  46 *
  47 * <b> Initialization and Configuration </b>
  48 *
  49 * The device driver enables higher layer software (e.g., an application) to
  50 * communicate with the Timer.
  51 *
  52 * XScuTimer_CfgInitialize() API is used to initialize the Timer. The
  53 * user needs to first call the XScuTimer_LookupConfig() API which returns
  54 * the Configuration structure pointer which is passed as a parameter to
  55 * the XScuTimer_CfgInitialize() API.
  56 *
  57 * <b> Interrupts </b>
  58 *
  59 * The Timer hardware supports interrupts.
  60 *
  61 * This driver does not provide a Interrupt Service Routine (ISR) for the device.
  62 * It is the responsibility of the application to provide one if needed. Refer to
  63 * the interrupt example provided with this driver for details on using the
  64 * Timer in interrupt mode.
  65 *
  66 * <b> Virtual Memory </b>
  67 *
  68 * This driver supports Virtual Memory. The RTOS is responsible for calculating
  69 * the correct device base address in Virtual Memory space.
  70 *
  71 * <b> Threads </b>
  72 *
  73 * This driver is not thread safe. Any needs for threads or thread mutual
  74 * exclusion must be satisfied by the layer above this driver.
  75 *
  76 * <b> Asserts </b>
  77 *
  78 * Asserts are used within all Xilinx drivers to enforce constraints on argument
  79 * values. Asserts can be turned off on a system-wide basis by defining, at
  80 * compile time, the NDEBUG identifier. By default, asserts are turned on and it
  81 * is recommended that users leave asserts on during development.
  82 *
  83 * <b> Building the driver </b>
  84 *
  85 * The XScuTimer driver is composed of several source files. This allows the user
  86 * to build and link only those parts of the driver that are necessary.
  87 *
  88 * <br><br>
  89 *
  90 * NOTE:
  91 * The timer is not a part of the snoop control unit as indicated by the
  92 * prefix "scu" in the name of the driver.
  93 * It is an independent module in APU.
  94 *
  95 * <pre>
  96 * MODIFICATION HISTORY:
  97 *
  98 * Ver   Who Date     Changes
  99 * ----- --- -------- ---------------------------------------------
 100 * 1.00a nm  03/10/10 First release
 101 * 1.02a sg  07/17/12 Included xil_assert.h for CR 667947. This is an issue
 102 *                    when the xstatus.h in the common driver overwrites
 103 *                    the xstatus.h of the standalone BSP during the
 104 *                    libgen.
 105 * </pre>
 106 *
 107 ******************************************************************************/
 108 #ifndef XSCUTIMER_H             /* prevent circular inclusions */
 109 #define XSCUTIMER_H             /* by using protection macros */
 110
 111 /***************************** Include Files *********************************/
 112
 113 #include "xstatus.h"
 114 #include "xscutimer_hw.h"
 115
 116 #ifdef __cplusplus
 117 extern "C" {
 118 #endif
 119
 120 /************************** Constant Definitions *****************************/
 121
 122 /**************************** Type Definitions *******************************/
 123
 124 /**
 125  * This typedef contains configuration information for the device.
 126  */
 127 typedef struct {
 128         u16 DeviceId;   /**< Unique ID of device */
 129         u32 BaseAddr;   /**< Base address of the device */
 130 } XScuTimer_Config;
 131
 132 /**
 133  * The XScuTimer driver instance data. The user is required to allocate a
 134  * variable of this type for every timer device in the system.
 135  * A pointer to a variable of this type is then passed to the driver API
 136  * functions.
 137  */
 138 typedef struct {
 139         XScuTimer_Config Config; /**< Hardware Configuration */
 140         u32 IsReady;            /**< Device is initialized and ready */
 141         u32 IsStarted;          /**< Device timer is running */
 142 } XScuTimer;
 143
 144 /***************** Macros (Inline Functions) Definitions *********************/
 145
 146 /****************************************************************************/
 147 /**
 148 *
 149 * Check if the timer has expired.
 150 *
 151 * @param        InstancePtr is a pointer to the XScuTimer instance.
 152 *
 153 * @return
 154 *               - TRUE if the timer has expired.
 155 *               - FALSE if the timer has not expired.
 156 *
 157 * @note         C-style signature:
 158 *               int XScuTimer_IsExpired(XScuTimer *InstancePtr)
 159 *
 160 ******************************************************************************/
 161 #define XScuTimer_IsExpired(InstancePtr) \
 162         ((XScuTimer_ReadReg((InstancePtr)->Config.BaseAddr, \
 163                                 XSCUTIMER_ISR_OFFSET) & \
 164                                 XSCUTIMER_ISR_EVENT_FLAG_MASK) == \
 165                                 XSCUTIMER_ISR_EVENT_FLAG_MASK)
 166
 167 /****************************************************************************/
 168 /**
 169 *
 170 * Re-start the timer. This macro will read the timer load register
 171 * and writes the same value to load register to update the counter register.
 172 *
 173 * @param        InstancePtr is a pointer to the XScuTimer instance.
 174 *
 175 * @return       None.
 176 *
 177 * @note         C-style signature:
 178 *               void XScuTimer_RestartTimer(XScuTimer *InstancePtr)
 179 *
 180 ******************************************************************************/
 181 #define XScuTimer_RestartTimer(InstancePtr)                             \
 182         XScuTimer_LoadTimer(InstancePtr,                                \
 183                 XScuTimer_ReadReg((InstancePtr)->Config.BaseAddr, \
 184                                         XSCUTIMER_LOAD_OFFSET))
 185
 186 /****************************************************************************/
 187 /**
 188 *
 189 * Write to the timer load register. This will also update the
 190 * timer counter register with the new value. This macro can be used to
 191 * change the time-out value.
 192 *
 193 * @param        InstancePtr is a pointer to the XScuTimer instance.
 194 * @param        Value is the count to be loaded in to the load register.
 195 *
 196 * @return       None.
 197 *
 198 * @note         C-style signature:
 199 *               void XScuTimer_LoadTimer(XScuTimer *InstancePtr, u32 Value)
 200 *
 201 ******************************************************************************/
 202 #define XScuTimer_LoadTimer(InstancePtr, Value)                         \
 203         XScuTimer_WriteReg((InstancePtr)->Config.BaseAddr,              \
 204                         XSCUTIMER_LOAD_OFFSET, Value)
 205
 206 /****************************************************************************/
 207 /**
 208 *
 209 * Returns the current timer counter register value. It can be called at any
 210 * time.
 211 *
 212 * @param        InstancePtr is a pointer to the XScuTimer instance.
 213 *
 214 * @return       Contents of the timer counter register.
 215 *
 216 * @note         C-style signature:
 217                 u32 XScuTimer_GetCounterValue(XScuTimer *InstancePtr)
 218 *
 219 ******************************************************************************/
 220 #define XScuTimer_GetCounterValue(InstancePtr)                          \
 221         XScuTimer_ReadReg((InstancePtr)->Config.BaseAddr,               \
 222                                 XSCUTIMER_COUNTER_OFFSET)
 223
 224 /****************************************************************************/
 225 /**
 226 *
 227 * Enable auto-reload mode.
 228 *
 229 * @param        InstancePtr is a pointer to the XScuTimer instance.
 230 *
 231 * @return       None.
 232 *
 233 * @note         C-style signature:
 234 *               void XScuTimer_EnableAutoReload(XScuTimer *InstancePtr)
 235 *
 236 ******************************************************************************/
 237 #define XScuTimer_EnableAutoReload(InstancePtr)                         \
 238         XScuTimer_WriteReg((InstancePtr)->Config.BaseAddr,              \
 239                         XSCUTIMER_CONTROL_OFFSET,                       \
 240                         (XScuTimer_ReadReg((InstancePtr)->Config.BaseAddr, \
 241                                 XSCUTIMER_CONTROL_OFFSET) |              \
 242                                 XSCUTIMER_CONTROL_AUTO_RELOAD_MASK))
 243
 244 /****************************************************************************/
 245 /**
 246 *
 247 * Disable auto-reload mode.
 248 *
 249 * @param        InstancePtr is a pointer to the XScuTimer instance.
 250 *
 251 * @return       None.
 252 *
 253 * @note         C-style signature:
 254 *               void XScuTimer_DisableAutoReload(XScuTimer *InstancePtr)
 255 *
 256 ******************************************************************************/
 257 #define XScuTimer_DisableAutoReload(InstancePtr)                        \
 258         XScuTimer_WriteReg((InstancePtr)->Config.BaseAddr,              \
 259                         XSCUTIMER_CONTROL_OFFSET,                       \
 260                         (XScuTimer_ReadReg((InstancePtr)->Config.BaseAddr, \
 261                                 XSCUTIMER_CONTROL_OFFSET) &             \
 262                                 ~(XSCUTIMER_CONTROL_AUTO_RELOAD_MASK)))
 263
 264 /****************************************************************************/
 265 /**
 266 *
 267 * Enable the Timer interrupt.
 268 *
 269 * @param        InstancePtr is a pointer to the XScuTimer instance.
 270 *
 271 * @return       None.
 272 *
 273 * @note         C-style signature:
 274 *               void XScuTimer_EnableInterrupt(XScuTimer *InstancePtr)
 275 *
 276 ******************************************************************************/
 277 #define XScuTimer_EnableInterrupt(InstancePtr)                          \
 278         XScuTimer_WriteReg((InstancePtr)->Config.BaseAddr,              \
 279                         XSCUTIMER_CONTROL_OFFSET,                       \
 280                         (XScuTimer_ReadReg((InstancePtr)->Config.BaseAddr, \
 281                                         XSCUTIMER_CONTROL_OFFSET) |     \
 282                                         XSCUTIMER_CONTROL_IRQ_ENABLE_MASK))
 283
 284 /****************************************************************************/
 285 /**
 286 *
 287 * Disable the Timer interrupt.
 288 *
 289 * @param        InstancePtr is a pointer to the XScuTimer instance.
 290 *
 291 * @return       None.
 292 *
 293 * @note         C-style signature:
 294 *               void XScuTimer_DisableInterrupt(XScuTimer *InstancePtr)
 295 *
 296 ******************************************************************************/
 297 #define XScuTimer_DisableInterrupt(InstancePtr)                         \
 298         XScuTimer_WriteReg((InstancePtr)->Config.BaseAddr,              \
 299                         XSCUTIMER_CONTROL_OFFSET,                       \
 300                         (XScuTimer_ReadReg((InstancePtr)->Config.BaseAddr, \
 301                                 XSCUTIMER_CONTROL_OFFSET) &             \
 302                                 ~(XSCUTIMER_CONTROL_IRQ_ENABLE_MASK)))
 303
 304 /*****************************************************************************/
 305 /**
 306 *
 307 * This function reads the interrupt status.
 308 *
 309 * @param        InstancePtr is a pointer to the XScuTimer instance.
 310 *
 311 * @return       None.
 312 *
 313 * @note         C-style signature:
 314 *               void XScuTimer_GetInterruptStatus(XScuTimer *InstancePtr)
 315 *
 316 ******************************************************************************/
 317 #define XScuTimer_GetInterruptStatus(InstancePtr)                       \
 318         XScuTimer_ReadReg((InstancePtr)->Config.BaseAddr,               \
 319                         XSCUTIMER_ISR_OFFSET)
 320
 321 /*****************************************************************************/
 322 /**
 323 *
 324 * This function clears the interrupt status.
 325 *
 326 * @param        InstancePtr is a pointer to the XScuTimer instance.
 327 *
 328 * @return       None.
 329 *
 330 * @note         C-style signature:
 331 *               void XScuTimer_ClearInterruptStatus(XScuTimer *InstancePtr)
 332 *
 333 ******************************************************************************/
 334 #define XScuTimer_ClearInterruptStatus(InstancePtr)                     \
 335         XScuTimer_WriteReg((InstancePtr)->Config.BaseAddr,              \
 336                 XSCUTIMER_ISR_OFFSET, XSCUTIMER_ISR_EVENT_FLAG_MASK)
 337
 338 /************************** Function Prototypes ******************************/
 339
 340 /*
 341  * Lookup configuration in xscutimer_sinit.c
 342  */
 343 XScuTimer_Config *XScuTimer_LookupConfig(u16 DeviceId);
 344
 345 /*
 346  * Selftest function in xscutimer_selftest.c
 347  */
 348 int XScuTimer_SelfTest(XScuTimer *InstancePtr);
 349
 350 /*
 351  * Interface functions in xscutimer.c
 352  */
 353 int XScuTimer_CfgInitialize(XScuTimer *InstancePtr,
 354                             XScuTimer_Config *ConfigPtr, u32 EffectiveAddress);
 355 void XScuTimer_Start(XScuTimer *InstancePtr);
 356 void XScuTimer_Stop(XScuTimer *InstancePtr);
 357 void XScuTimer_SetPrescaler(XScuTimer *InstancePtr, u8 PrescalerValue);
 358 u8 XScuTimer_GetPrescaler(XScuTimer *InstancePtr);
 359
 360 #ifdef __cplusplus
 361 }
 362 #endif
 363
 364 #endif  /* end of protection macro */
 365 /** @} */