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