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

   1 /******************************************************************************
   2 *
   3 * Copyright (C) 2010 - 2015 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_1
  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 * 2.1   sk  02/26/15 Modified the code for MISRA-C:2012 compliance.
 106 *       ms  03/17/17 Added readme.txt file in examples folder for doxygen
 107 *                    generation.
 108 * </pre>
 109 *
 110 ******************************************************************************/
 111 #ifndef XSCUTIMER_H             /* prevent circular inclusions */
 112 #define XSCUTIMER_H             /* by using protection macros */
 113
 114 /***************************** Include Files *********************************/
 115
 116 #include "xstatus.h"
 117 #include "xscutimer_hw.h"
 118
 119 #ifdef __cplusplus
 120 extern "C" {
 121 #endif
 122
 123 /************************** Constant Definitions *****************************/
 124
 125 /**************************** Type Definitions *******************************/
 126
 127 /**
 128  * This typedef contains configuration information for the device.
 129  */
 130 typedef struct {
 131         u16 DeviceId;   /**< Unique ID of device */
 132         u32 BaseAddr;   /**< Base address of the device */
 133 } XScuTimer_Config;
 134
 135 /**
 136  * The XScuTimer driver instance data. The user is required to allocate a
 137  * variable of this type for every timer device in the system.
 138  * A pointer to a variable of this type is then passed to the driver API
 139  * functions.
 140  */
 141 typedef struct {
 142         XScuTimer_Config Config; /**< Hardware Configuration */
 143         u32 IsReady;            /**< Device is initialized and ready */
 144         u32 IsStarted;          /**< Device timer is running */
 145 } XScuTimer;
 146
 147 /***************** Macros (Inline Functions) Definitions *********************/
 148
 149 /****************************************************************************/
 150 /**
 151 *
 152 * Check if the timer has expired.
 153 *
 154 * @param        InstancePtr is a pointer to the XScuTimer instance.
 155 *
 156 * @return
 157 *               - TRUE if the timer has expired.
 158 *               - FALSE if the timer has not expired.
 159 *
 160 * @note         C-style signature:
 161 *               int XScuTimer_IsExpired(XScuTimer *InstancePtr)
 162 *
 163 ******************************************************************************/
 164 #define XScuTimer_IsExpired(InstancePtr) \
 165         ((XScuTimer_ReadReg((InstancePtr)->Config.BaseAddr, \
 166                                 XSCUTIMER_ISR_OFFSET) & \
 167                                 XSCUTIMER_ISR_EVENT_FLAG_MASK) == \
 168                                 XSCUTIMER_ISR_EVENT_FLAG_MASK)
 169
 170 /****************************************************************************/
 171 /**
 172 *
 173 * Re-start the timer. This macro will read the timer load register
 174 * and writes the same value to load register to update the counter register.
 175 *
 176 * @param        InstancePtr is a pointer to the XScuTimer instance.
 177 *
 178 * @return       None.
 179 *
 180 * @note         C-style signature:
 181 *               void XScuTimer_RestartTimer(XScuTimer *InstancePtr)
 182 *
 183 ******************************************************************************/
 184 #define XScuTimer_RestartTimer(InstancePtr)                             \
 185         XScuTimer_LoadTimer((InstancePtr),                              \
 186                 XScuTimer_ReadReg((InstancePtr)->Config.BaseAddr, \
 187                                         XSCUTIMER_LOAD_OFFSET))
 188
 189 /****************************************************************************/
 190 /**
 191 *
 192 * Write to the timer load register. This will also update the
 193 * timer counter register with the new value. This macro can be used to
 194 * change the time-out value.
 195 *
 196 * @param        InstancePtr is a pointer to the XScuTimer instance.
 197 * @param        Value is the count to be loaded in to the load register.
 198 *
 199 * @return       None.
 200 *
 201 * @note         C-style signature:
 202 *               void XScuTimer_LoadTimer(XScuTimer *InstancePtr, u32 Value)
 203 *
 204 ******************************************************************************/
 205 #define XScuTimer_LoadTimer(InstancePtr, Value)                         \
 206         XScuTimer_WriteReg((InstancePtr)->Config.BaseAddr,              \
 207                         XSCUTIMER_LOAD_OFFSET, (Value))
 208
 209 /****************************************************************************/
 210 /**
 211 *
 212 * Returns the current timer counter register value. It can be called at any
 213 * time.
 214 *
 215 * @param        InstancePtr is a pointer to the XScuTimer instance.
 216 *
 217 * @return       Contents of the timer counter register.
 218 *
 219 * @note         C-style signature:
 220                 u32 XScuTimer_GetCounterValue(XScuTimer *InstancePtr)
 221 *
 222 ******************************************************************************/
 223 #define XScuTimer_GetCounterValue(InstancePtr)                          \
 224         XScuTimer_ReadReg((InstancePtr)->Config.BaseAddr,               \
 225                                 XSCUTIMER_COUNTER_OFFSET)
 226
 227 /****************************************************************************/
 228 /**
 229 *
 230 * Enable auto-reload mode.
 231 *
 232 * @param        InstancePtr is a pointer to the XScuTimer instance.
 233 *
 234 * @return       None.
 235 *
 236 * @note         C-style signature:
 237 *               void XScuTimer_EnableAutoReload(XScuTimer *InstancePtr)
 238 *
 239 ******************************************************************************/
 240 #define XScuTimer_EnableAutoReload(InstancePtr)                         \
 241         XScuTimer_WriteReg((InstancePtr)->Config.BaseAddr,              \
 242                         XSCUTIMER_CONTROL_OFFSET,                       \
 243                         (XScuTimer_ReadReg((InstancePtr)->Config.BaseAddr, \
 244                                 XSCUTIMER_CONTROL_OFFSET) |              \
 245                                 XSCUTIMER_CONTROL_AUTO_RELOAD_MASK))
 246
 247 /****************************************************************************/
 248 /**
 249 *
 250 * Disable auto-reload mode.
 251 *
 252 * @param        InstancePtr is a pointer to the XScuTimer instance.
 253 *
 254 * @return       None.
 255 *
 256 * @note         C-style signature:
 257 *               void XScuTimer_DisableAutoReload(XScuTimer *InstancePtr)
 258 *
 259 ******************************************************************************/
 260 #define XScuTimer_DisableAutoReload(InstancePtr)                        \
 261         XScuTimer_WriteReg((InstancePtr)->Config.BaseAddr,              \
 262                         XSCUTIMER_CONTROL_OFFSET,                       \
 263                         (XScuTimer_ReadReg((InstancePtr)->Config.BaseAddr, \
 264                                 XSCUTIMER_CONTROL_OFFSET) &             \
 265                                 ~(XSCUTIMER_CONTROL_AUTO_RELOAD_MASK)))
 266
 267 /****************************************************************************/
 268 /**
 269 *
 270 * Enable the Timer interrupt.
 271 *
 272 * @param        InstancePtr is a pointer to the XScuTimer instance.
 273 *
 274 * @return       None.
 275 *
 276 * @note         C-style signature:
 277 *               void XScuTimer_EnableInterrupt(XScuTimer *InstancePtr)
 278 *
 279 ******************************************************************************/
 280 #define XScuTimer_EnableInterrupt(InstancePtr)                          \
 281         XScuTimer_WriteReg((InstancePtr)->Config.BaseAddr,              \
 282                         XSCUTIMER_CONTROL_OFFSET,                       \
 283                         (XScuTimer_ReadReg((InstancePtr)->Config.BaseAddr, \
 284                                         XSCUTIMER_CONTROL_OFFSET) |     \
 285                                         XSCUTIMER_CONTROL_IRQ_ENABLE_MASK))
 286
 287 /****************************************************************************/
 288 /**
 289 *
 290 * Disable the Timer interrupt.
 291 *
 292 * @param        InstancePtr is a pointer to the XScuTimer instance.
 293 *
 294 * @return       None.
 295 *
 296 * @note         C-style signature:
 297 *               void XScuTimer_DisableInterrupt(XScuTimer *InstancePtr)
 298 *
 299 ******************************************************************************/
 300 #define XScuTimer_DisableInterrupt(InstancePtr)                         \
 301         XScuTimer_WriteReg((InstancePtr)->Config.BaseAddr,              \
 302                         XSCUTIMER_CONTROL_OFFSET,                       \
 303                         (XScuTimer_ReadReg((InstancePtr)->Config.BaseAddr, \
 304                                 XSCUTIMER_CONTROL_OFFSET) &             \
 305                                 ~(XSCUTIMER_CONTROL_IRQ_ENABLE_MASK)))
 306
 307 /*****************************************************************************/
 308 /**
 309 *
 310 * This function reads the interrupt status.
 311 *
 312 * @param        InstancePtr is a pointer to the XScuTimer instance.
 313 *
 314 * @return       None.
 315 *
 316 * @note         C-style signature:
 317 *               void XScuTimer_GetInterruptStatus(XScuTimer *InstancePtr)
 318 *
 319 ******************************************************************************/
 320 #define XScuTimer_GetInterruptStatus(InstancePtr)                       \
 321         XScuTimer_ReadReg((InstancePtr)->Config.BaseAddr,               \
 322                         XSCUTIMER_ISR_OFFSET)
 323
 324 /*****************************************************************************/
 325 /**
 326 *
 327 * This function clears the interrupt status.
 328 *
 329 * @param        InstancePtr is a pointer to the XScuTimer instance.
 330 *
 331 * @return       None.
 332 *
 333 * @note         C-style signature:
 334 *               void XScuTimer_ClearInterruptStatus(XScuTimer *InstancePtr)
 335 *
 336 ******************************************************************************/
 337 #define XScuTimer_ClearInterruptStatus(InstancePtr)                     \
 338         XScuTimer_WriteReg((InstancePtr)->Config.BaseAddr,              \
 339                 XSCUTIMER_ISR_OFFSET, XSCUTIMER_ISR_EVENT_FLAG_MASK)
 340
 341 /************************** Function Prototypes ******************************/
 342
 343 /*
 344  * Lookup configuration in xscutimer_sinit.c
 345  */
 346 XScuTimer_Config *XScuTimer_LookupConfig(u16 DeviceId);
 347
 348 /*
 349  * Selftest function in xscutimer_selftest.c
 350  */
 351 s32 XScuTimer_SelfTest(XScuTimer *InstancePtr);
 352
 353 /*
 354  * Interface functions in xscutimer.c
 355  */
 356 s32 XScuTimer_CfgInitialize(XScuTimer *InstancePtr,
 357                             XScuTimer_Config *ConfigPtr, u32 EffectiveAddress);
 358 void XScuTimer_Start(XScuTimer *InstancePtr);
 359 void XScuTimer_Stop(XScuTimer *InstancePtr);
 360 void XScuTimer_SetPrescaler(XScuTimer *InstancePtr, u8 PrescalerValue);
 361 u8 XScuTimer_GetPrescaler(XScuTimer *InstancePtr);
 362
 363 #ifdef __cplusplus
 364 }
 365 #endif
 366
 367 #endif  /* end of protection macro */
 368 /** @} */