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