git.sur5r.net Git - freertos/blob - FreeRTOS/Demo/CORTEX_A9_Zynq_ZC702/RTOSDemo_bsp/ps7_cortexa9_0/include/xscuwdt.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 xscuwdt.h
  36 *
  37 * The Xilinx SCU watchdog timer driver (XScuWdt) supports the Xilinx SCU private
  38 * watchdog timer hardware.
  39 *
  40 * The XScuWdt driver supports the following features:
  41 * - Watchdog mode
  42 * - Timer mode
  43 * - Auto reload (timer mode only)
  44 *
  45 * The watchdog counter register is a down counter and starts decrementing when
  46 * the watchdog is started.
  47 * In watchdog mode, when the counter reaches 0, the Reset flag is set in the
  48 * Reset status register and the WDRESETREQ pin is asserted, causing a system
  49 * reset. The Reset flag is not reset by normal processor reset and is cleared
  50 * when written with a value of 1. This enables the user to differentiate a
  51 * normal reset and a reset caused by watchdog time-out. The user needs to call
  52 * XScuWdt_RestartWdt() periodically, to avoid the watchdog from being timed-out.
  53 *
  54 * The IsWdtExpired function can be used to check if the watchdog was the cause
  55 * of the last reset. In this situation, call Initialize then call IsWdtExpired.
  56 * If the result is true, watchdog timeout caused the last system reset. The
  57 * application then needs to clear the Reset flag.
  58 *
  59 * In timer mode, when the counter reaches 0, the Event flag is set in the
  60 * Interrupt status register and if interrupts are enabled, interrupt ID 30 is
  61 * set as pending in the interrupt distributor. The IsTimerExpired function
  62 * is used to check if the watchdog counter has decremented to 0 in timer mode.
  63 * If auto-reload mode is enabled, the Counter register is automatically reloaded
  64 * from the Load register.
  65 *
  66 * <b> Initialization and Configuration </b>
  67 *
  68 * The device driver enables higher layer software (e.g., an application) to
  69 * communicate with the Watchdog Timer.
  70 *
  71 * XScuWdt_CfgInitialize() API is used to initialize the Watchdog Timer. The
  72 * user needs to first call the XScuWdt_LookupConfig() API which returns
  73 * the Configuration structure pointer which is passed as a parameter to
  74 * the XScuWdt_CfgInitialize() API.
  75 *
  76 * <b>Interrupts</b>
  77 *
  78 * The SCU Watchdog Timer supports interrupts in Timer mode.
  79 *
  80 * This driver does not provide a Interrupt Service Routine (ISR) for the device.
  81 * It is the responsibility of the application to provide one if needed. Refer to
  82 * the interrupt example provided with this driver for details on using the
  83 * Timer in interrupt mode.
  84 *
  85 * <b> Virtual Memory </b>
  86 *
  87 * This driver supports Virtual Memory. The RTOS is responsible for calculating
  88 * the correct device base address in Virtual Memory space.
  89 *
  90 * <b> Threads </b>
  91 *
  92 * This driver is not thread safe. Any needs for threads or thread mutual
  93 * exclusion must be satisfied by the layer above this driver.
  94 *
  95 * <b> Asserts </b>
  96 *
  97 * Asserts are used within all Xilinx drivers to enforce constraints on argument
  98 * values. Asserts can be turned off on a system-wide basis by defining, at
  99 * compile time, the NDEBUG identifier. By default, asserts are turned on and it
 100 * is recommended that users leave asserts on during development.
 101 *
 102 * <b> Building the driver </b>
 103 *
 104 * The XScuWdt driver is composed of several source files. This allows the user
 105 * to build and link only those parts of the driver that are necessary.
 106 *
 107 * <br><br>
 108 *
 109 * NOTE:
 110 * The watchdog timer is not a part of the snoop control unit as indicated
 111 * by the prefix "scu" in the name of the driver.
 112 * It is an independent module in APU.
 113 *
 114 * <pre>
 115 * MODIFICATION HISTORY:
 116 *
 117 * Ver   Who Date     Changes
 118 * ----- --- -------- ---------------------------------------------
 119 * 1.00a sdm 01/15/10 First release
 120 * 1.02a  sg 07/17/12 Included xil_assert.h for CR 667947. This is an issue
 121 *                    when the xstatus.h in the common driver overwrites
 122 *                    the xstatus.h of the standalone BSP during the
 123 *                    libgen.
 124 * </pre>
 125 *
 126 ******************************************************************************/
 127 #ifndef XSCUWDT_H               /* prevent circular inclusions */
 128 #define XSCUWDT_H               /* by using protection macros */
 129
 130 /***************************** Include Files *********************************/
 131
 132 #include "xstatus.h"
 133 #include "xscuwdt_hw.h"
 134
 135 #ifdef __cplusplus
 136 extern "C" {
 137 #endif
 138
 139 /************************** Constant Definitions *****************************/
 140
 141 /**************************** Type Definitions *******************************/
 142
 143 /**
 144  * This typedef contains configuration information for the device.
 145  */
 146 typedef struct {
 147         u16 DeviceId;           /**< Unique ID of device */
 148         u32 BaseAddr;           /**< Base address of the device */
 149 } XScuWdt_Config;
 150
 151 /**
 152  * The XScuWdt driver instance data. The user is required to allocate a
 153  * variable of this type for every watchdog/timer device in the system.
 154  * A pointer to a variable of this type is then passed to the driver API
 155  * functions.
 156  */
 157 typedef struct {
 158         XScuWdt_Config Config;/**< Hardware Configuration */
 159         u32 IsReady;            /**< Device is initialized and ready */
 160         u32 IsStarted;          /**< Device watchdog timer is running */
 161 } XScuWdt;
 162
 163 /***************** Macros (Inline Functions) Definitions *********************/
 164 /****************************************************************************/
 165 /**
 166 *
 167 * This function is used to check if the watchdog has timed-out and the last
 168 * reset was caused by the watchdog reset.
 169 *
 170 * @param        InstancePtr is a pointer to the XScuWdt instance.
 171 *
 172 * @return
 173 *               - TRUE if the watchdog has expired.
 174 *               - FALSE if the watchdog has not expired.
 175 *
 176 * @note         C-style signature:
 177 *               int XScuWdt_IsWdtExpired(XScuWdt *InstancePtr)
 178 *
 179 ******************************************************************************/
 180 #define XScuWdt_IsWdtExpired(InstancePtr)                               \
 181         ((XScuWdt_ReadReg((InstancePtr)->Config.BaseAddr,               \
 182                           XSCUWDT_RST_STS_OFFSET) &                     \
 183          XSCUWDT_RST_STS_RESET_FLAG_MASK) == XSCUWDT_RST_STS_RESET_FLAG_MASK)
 184
 185 /****************************************************************************/
 186 /**
 187 *
 188 * This function is used to check if the watchdog counter has reached 0 in timer
 189 * mode.
 190 *
 191 * @param        InstancePtr is a pointer to the XScuWdt instance.
 192 *
 193 * @return
 194 *               - TRUE if the watchdog has expired.
 195 *               - FALSE if the watchdog has not expired.
 196 *
 197 * @note         C-style signature:
 198 *               int XScuWdt_IsTimerExpired(XScuWdt *InstancePtr)
 199 *
 200 ******************************************************************************/
 201 #define XScuWdt_IsTimerExpired(InstancePtr)                             \
 202         ((XScuWdt_ReadReg((InstancePtr)->Config.BaseAddr,               \
 203                           XSCUWDT_ISR_OFFSET) &                         \
 204          XSCUWDT_ISR_EVENT_FLAG_MASK) == XSCUWDT_ISR_EVENT_FLAG_MASK)
 205
 206 /****************************************************************************/
 207 /**
 208 *
 209 * Re-start the watchdog timer. This macro will read the watchdog load register
 210 * and write the same value to load register to update the counter register.
 211 * An application needs to call this function periodically to keep the watchdog
 212 * from asserting the WDRESETREQ reset request output pin.
 213 *
 214 * @param        InstancePtr is a pointer to the XScuWdt instance.
 215 *
 216 * @return       None.
 217 *
 218 * @note         C-style signature:
 219 *               void XScuWdt_RestartWdt(XScuWdt *InstancePtr)
 220 *
 221 ******************************************************************************/
 222 #define XScuWdt_RestartWdt(InstancePtr)                                  \
 223         XScuWdt_LoadWdt(InstancePtr,                                     \
 224                         (XScuWdt_ReadReg((InstancePtr)->Config.BaseAddr, \
 225                                          XSCUWDT_LOAD_OFFSET)))
 226
 227 /****************************************************************************/
 228 /**
 229 *
 230 * Write to the watchdog timer load register. This will also update the
 231 * watchdog counter register with the new value. This macro can be used to
 232 * change the time-out value.
 233 *
 234 * @param        InstancePtr is a pointer to the XScuWdt instance.
 235 * @param        Value is the value to be written to the Watchdog Load register.
 236 *
 237 * @return       None.
 238 *
 239 * @note         C-style signature:
 240 *               void XScuWdt_LoadWdt(XScuWdt *InstancePtr, u32 Value)
 241 *
 242 ******************************************************************************/
 243 #define XScuWdt_LoadWdt(InstancePtr, Value)                             \
 244         XScuWdt_WriteReg((InstancePtr)->Config.BaseAddr,                \
 245                         XSCUWDT_LOAD_OFFSET, Value)
 246
 247 /****************************************************************************/
 248 /**
 249 *
 250 * Put the watchdog timer in Watchdog mode by setting the WD mode bit of the
 251 * Watchdog control register.
 252 *
 253 * @param        InstancePtr is a pointer to the XScuWdt instance.
 254 *
 255 * @return       None.
 256 *
 257 * @note         C-style signature:
 258 *               void XScuWdt_SetWdMode(XScuWdt *InstancePtr)
 259 *
 260 ******************************************************************************/
 261 #define XScuWdt_SetWdMode(InstancePtr)                                    \
 262         XScuWdt_WriteReg((InstancePtr)->Config.BaseAddr,                  \
 263                          XSCUWDT_CONTROL_OFFSET,                          \
 264                          (XScuWdt_ReadReg((InstancePtr)->Config.BaseAddr, \
 265                           XSCUWDT_CONTROL_OFFSET) |                       \
 266                           XSCUWDT_CONTROL_WD_MODE_MASK))
 267
 268 /****************************************************************************/
 269 /**
 270 *
 271 * Put the watchdog timer in Timer mode by writing 0x12345678 and 0x87654321
 272 * successively to the Watchdog Disable Register.
 273 * The software must write 0x12345678 and 0x87654321 successively to the
 274 * Watchdog Disable Register so that the watchdog mode bit in the Watchdog
 275 * Control Register is set to zero.
 276 *
 277 * @param        InstancePtr is a pointer to the XScuWdt instance.
 278 *
 279 * @return       None.
 280 *
 281 * @note         C-style signature:
 282 *               void XScuWdt_SetTimerMode(XScuWdt *InstancePtr)
 283 *
 284 ******************************************************************************/
 285 #define XScuWdt_SetTimerMode(InstancePtr)                               \
 286 {                                                                       \
 287         XScuWdt_WriteReg((InstancePtr)->Config.BaseAddr,                \
 288                         XSCUWDT_DISABLE_OFFSET,                         \
 289                         XSCUWDT_DISABLE_VALUE1);                        \
 290         XScuWdt_WriteReg((InstancePtr)->Config.BaseAddr,                \
 291                         XSCUWDT_DISABLE_OFFSET,                         \
 292                         XSCUWDT_DISABLE_VALUE2);                        \
 293 }
 294
 295 /****************************************************************************/
 296 /**
 297 *
 298 * Get the contents of the watchdog control register.
 299 *
 300 * @param        InstancePtr is a pointer to the XScuWdt instance.
 301 *
 302 * @return       Contents of the watchdog control register.
 303 *
 304 * @note         C-style signature:
 305                 u32 XScuWdt_GetControlReg(XScuWdt *InstancePtr)
 306 *
 307 ******************************************************************************/
 308 #define XScuWdt_GetControlReg(InstancePtr)                              \
 309         XScuWdt_ReadReg((InstancePtr)->Config.BaseAddr,                 \
 310                         XSCUWDT_CONTROL_OFFSET)
 311
 312 /****************************************************************************/
 313 /**
 314 *
 315 * Write to the watchdog control register.
 316 *
 317 * @param        InstancePtr is a pointer to the XScuWdt instance.
 318 * @param        ControlReg is the value to be written to the watchdog control
 319 *               register.
 320 *
 321 * @return       None.
 322 *
 323 * @note         C-style signature:
 324                 void XScuWdt_SetControlReg(XScuWdt *InstancePtr, u32 ControlReg)
 325 *
 326 ******************************************************************************/
 327 #define XScuWdt_SetControlReg(InstancePtr, ControlReg)                  \
 328         XScuWdt_WriteReg((InstancePtr)->Config.BaseAddr,                \
 329                          XSCUWDT_CONTROL_OFFSET, ControlReg)
 330
 331 /****************************************************************************/
 332 /**
 333 *
 334 * Enable auto-reload mode.
 335 *
 336 * @param        InstancePtr is a pointer to the XScuWdt instance.
 337 *
 338 * @return       None.
 339 *
 340 * @note         C-style signature:
 341 *               void XScuWdt_EnableAutoReload(XScuWdt *InstancePtr)
 342 *
 343 ******************************************************************************/
 344 #define XScuWdt_EnableAutoReload(InstancePtr)                           \
 345         XScuWdt_SetControlReg((InstancePtr),                            \
 346                               (XScuWdt_GetControlReg(InstancePtr) |     \
 347                               XSCUWDT_CONTROL_AUTO_RELOAD_MASK))
 348
 349 /************************** Function Prototypes ******************************/
 350
 351 /*
 352  * Lookup configuration in xscuwdt_sinit.c.
 353  */
 354 XScuWdt_Config *XScuWdt_LookupConfig(u16 DeviceId);
 355
 356 /*
 357  * Selftest function in xscuwdt_selftest.c
 358  */
 359 int XScuWdt_SelfTest(XScuWdt *InstancePtr);
 360
 361 /*
 362  * Interface functions in xscuwdt.c
 363  */
 364 int XScuWdt_CfgInitialize(XScuWdt *InstancePtr,
 365                           XScuWdt_Config *ConfigPtr, u32 EffectiveAddress);
 366
 367 void XScuWdt_Start(XScuWdt *InstancePtr);
 368
 369 void XScuWdt_Stop(XScuWdt *InstancePtr);
 370
 371 /*
 372  * Self-test function in xwdttb_selftest.c.
 373  */
 374 int XScuWdt_SelfTest(XScuWdt *InstancePtr);
 375
 376 #ifdef __cplusplus
 377 }
 378 #endif
 379
 380 #endif  /* end of protection macro */