git.sur5r.net Git - freertos/blob - FreeRTOS/Demo/CORTEX_A9_Zynq_ZC702/RTOSDemo_bsp/ps7_cortexa9_0/libsrc/scuwdt_v2_1/src/xscuwdt.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 xscuwdt.h
  36 * @addtogroup scuwdt_v2_1
  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 * 2.1   sk  02/26/15 Modified the code for MISRA-C:2012 compliance.
 128 *       ms  03/17/17 Added readme.txt file in examples folder for doxygen
 129 *                    generation.
 130 * </pre>
 131 *
 132 ******************************************************************************/
 133 #ifndef XSCUWDT_H               /* prevent circular inclusions */
 134 #define XSCUWDT_H               /* by using protection macros */
 135
 136 /***************************** Include Files *********************************/
 137
 138 #include "xstatus.h"
 139 #include "xscuwdt_hw.h"
 140
 141 #ifdef __cplusplus
 142 extern "C" {
 143 #endif
 144
 145 /************************** Constant Definitions *****************************/
 146
 147 /**************************** Type Definitions *******************************/
 148
 149 /**
 150  * This typedef contains configuration information for the device.
 151  */
 152 typedef struct {
 153         u16 DeviceId;           /**< Unique ID of device */
 154         u32 BaseAddr;           /**< Base address of the device */
 155 } XScuWdt_Config;
 156
 157 /**
 158  * The XScuWdt driver instance data. The user is required to allocate a
 159  * variable of this type for every watchdog/timer device in the system.
 160  * A pointer to a variable of this type is then passed to the driver API
 161  * functions.
 162  */
 163 typedef struct {
 164         XScuWdt_Config Config;/**< Hardware Configuration */
 165         u32 IsReady;            /**< Device is initialized and ready */
 166         u32 IsStarted;          /**< Device watchdog timer is running */
 167 } XScuWdt;
 168
 169 /***************** Macros (Inline Functions) Definitions *********************/
 170 /****************************************************************************/
 171 /**
 172 *
 173 * This function is used to check if the watchdog has timed-out and the last
 174 * reset was caused by the watchdog reset.
 175 *
 176 * @param        InstancePtr is a pointer to the XScuWdt instance.
 177 *
 178 * @return
 179 *               - TRUE if the watchdog has expired.
 180 *               - FALSE if the watchdog has not expired.
 181 *
 182 * @note         C-style signature:
 183 *               int XScuWdt_IsWdtExpired(XScuWdt *InstancePtr)
 184 *
 185 ******************************************************************************/
 186 #define XScuWdt_IsWdtExpired(InstancePtr)                               \
 187         ((XScuWdt_ReadReg((InstancePtr)->Config.BaseAddr,               \
 188                           XSCUWDT_RST_STS_OFFSET) &                     \
 189          XSCUWDT_RST_STS_RESET_FLAG_MASK) == XSCUWDT_RST_STS_RESET_FLAG_MASK)
 190
 191 /****************************************************************************/
 192 /**
 193 *
 194 * This function is used to check if the watchdog counter has reached 0 in timer
 195 * mode.
 196 *
 197 * @param        InstancePtr is a pointer to the XScuWdt instance.
 198 *
 199 * @return
 200 *               - TRUE if the watchdog has expired.
 201 *               - FALSE if the watchdog has not expired.
 202 *
 203 * @note         C-style signature:
 204 *               int XScuWdt_IsTimerExpired(XScuWdt *InstancePtr)
 205 *
 206 ******************************************************************************/
 207 #define XScuWdt_IsTimerExpired(InstancePtr)                             \
 208         ((XScuWdt_ReadReg((InstancePtr)->Config.BaseAddr,               \
 209                           XSCUWDT_ISR_OFFSET) &                         \
 210          XSCUWDT_ISR_EVENT_FLAG_MASK) == XSCUWDT_ISR_EVENT_FLAG_MASK)
 211
 212 /****************************************************************************/
 213 /**
 214 *
 215 * Re-start the watchdog timer. This macro will read the watchdog load register
 216 * and write the same value to load register to update the counter register.
 217 * An application needs to call this function periodically to keep the watchdog
 218 * from asserting the WDRESETREQ reset request output pin.
 219 *
 220 * @param        InstancePtr is a pointer to the XScuWdt instance.
 221 *
 222 * @return       None.
 223 *
 224 * @note         C-style signature:
 225 *               void XScuWdt_RestartWdt(XScuWdt *InstancePtr)
 226 *
 227 ******************************************************************************/
 228 #define XScuWdt_RestartWdt(InstancePtr)                                  \
 229         XScuWdt_LoadWdt((InstancePtr),                                   \
 230                         (XScuWdt_ReadReg((InstancePtr)->Config.BaseAddr, \
 231                                          XSCUWDT_LOAD_OFFSET)))
 232
 233 /****************************************************************************/
 234 /**
 235 *
 236 * Write to the watchdog timer load register. This will also update the
 237 * watchdog counter register with the new value. This macro can be used to
 238 * change the time-out value.
 239 *
 240 * @param        InstancePtr is a pointer to the XScuWdt instance.
 241 * @param        Value is the value to be written to the Watchdog Load register.
 242 *
 243 * @return       None.
 244 *
 245 * @note         C-style signature:
 246 *               void XScuWdt_LoadWdt(XScuWdt *InstancePtr, u32 Value)
 247 *
 248 ******************************************************************************/
 249 #define XScuWdt_LoadWdt(InstancePtr, Value)                             \
 250         XScuWdt_WriteReg((InstancePtr)->Config.BaseAddr,                \
 251                         XSCUWDT_LOAD_OFFSET, (Value))
 252
 253 /****************************************************************************/
 254 /**
 255 *
 256 * Put the watchdog timer in Watchdog mode by setting the WD mode bit of the
 257 * Watchdog control register.
 258 *
 259 * @param        InstancePtr is a pointer to the XScuWdt instance.
 260 *
 261 * @return       None.
 262 *
 263 * @note         C-style signature:
 264 *               void XScuWdt_SetWdMode(XScuWdt *InstancePtr)
 265 *
 266 ******************************************************************************/
 267 #define XScuWdt_SetWdMode(InstancePtr)                                    \
 268         XScuWdt_WriteReg((InstancePtr)->Config.BaseAddr,                  \
 269                          XSCUWDT_CONTROL_OFFSET,                          \
 270                          (XScuWdt_ReadReg((InstancePtr)->Config.BaseAddr, \
 271                           XSCUWDT_CONTROL_OFFSET) |                       \
 272                           (XSCUWDT_CONTROL_WD_MODE_MASK)))
 273
 274 /****************************************************************************/
 275 /**
 276 *
 277 * Put the watchdog timer in Timer mode by writing 0x12345678 and 0x87654321
 278 * successively to the Watchdog Disable Register.
 279 * The software must write 0x12345678 and 0x87654321 successively to the
 280 * Watchdog Disable Register so that the watchdog mode bit in the Watchdog
 281 * Control Register is set to zero.
 282 *
 283 * @param        InstancePtr is a pointer to the XScuWdt instance.
 284 *
 285 * @return       None.
 286 *
 287 * @note         C-style signature:
 288 *               void XScuWdt_SetTimerMode(XScuWdt *InstancePtr)
 289 *
 290 ******************************************************************************/
 291 #define XScuWdt_SetTimerMode(InstancePtr)                               \
 292 {                                                                       \
 293         XScuWdt_WriteReg((InstancePtr)->Config.BaseAddr,                \
 294                         XSCUWDT_DISABLE_OFFSET,                         \
 295                         XSCUWDT_DISABLE_VALUE1);                        \
 296         XScuWdt_WriteReg((InstancePtr)->Config.BaseAddr,                \
 297                         XSCUWDT_DISABLE_OFFSET,                         \
 298                         XSCUWDT_DISABLE_VALUE2);                        \
 299 }
 300
 301 /****************************************************************************/
 302 /**
 303 *
 304 * Get the contents of the watchdog control register.
 305 *
 306 * @param        InstancePtr is a pointer to the XScuWdt instance.
 307 *
 308 * @return       Contents of the watchdog control register.
 309 *
 310 * @note         C-style signature:
 311                 u32 XScuWdt_GetControlReg(XScuWdt *InstancePtr)
 312 *
 313 ******************************************************************************/
 314 #define XScuWdt_GetControlReg(InstancePtr)                              \
 315         XScuWdt_ReadReg((InstancePtr)->Config.BaseAddr,                 \
 316                         XSCUWDT_CONTROL_OFFSET)
 317
 318 /****************************************************************************/
 319 /**
 320 *
 321 * Write to the watchdog control register.
 322 *
 323 * @param        InstancePtr is a pointer to the XScuWdt instance.
 324 * @param        ControlReg is the value to be written to the watchdog control
 325 *               register.
 326 *
 327 * @return       None.
 328 *
 329 * @note         C-style signature:
 330                 void XScuWdt_SetControlReg(XScuWdt *InstancePtr, u32 ControlReg)
 331 *
 332 ******************************************************************************/
 333 #define XScuWdt_SetControlReg(InstancePtr, ControlReg)                  \
 334         XScuWdt_WriteReg((InstancePtr)->Config.BaseAddr,                \
 335                          XSCUWDT_CONTROL_OFFSET, (ControlReg))
 336
 337 /****************************************************************************/
 338 /**
 339 *
 340 * Enable auto-reload mode.
 341 *
 342 * @param        InstancePtr is a pointer to the XScuWdt instance.
 343 *
 344 * @return       None.
 345 *
 346 * @note         C-style signature:
 347 *               void XScuWdt_EnableAutoReload(XScuWdt *InstancePtr)
 348 *
 349 ******************************************************************************/
 350 #define XScuWdt_EnableAutoReload(InstancePtr)                           \
 351         XScuWdt_SetControlReg((InstancePtr),                            \
 352                               (XScuWdt_GetControlReg(InstancePtr) |     \
 353                               XSCUWDT_CONTROL_AUTO_RELOAD_MASK))
 354
 355 /************************** Function Prototypes ******************************/
 356
 357 /*
 358  * Lookup configuration in xscuwdt_sinit.c.
 359  */
 360 XScuWdt_Config *XScuWdt_LookupConfig(u16 DeviceId);
 361
 362 /*
 363  * Selftest function in xscuwdt_selftest.c
 364  */
 365 s32 XScuWdt_SelfTest(XScuWdt *InstancePtr);
 366
 367 /*
 368  * Interface functions in xscuwdt.c
 369  */
 370 s32 XScuWdt_CfgInitialize(XScuWdt *InstancePtr,
 371                           XScuWdt_Config *ConfigPtr, u32 EffectiveAddress);
 372
 373 void XScuWdt_Start(XScuWdt *InstancePtr);
 374
 375 void XScuWdt_Stop(XScuWdt *InstancePtr);
 376
 377
 378 #ifdef __cplusplus
 379 }
 380 #endif
 381
 382 #endif  /* end of protection macro */
 383 /** @} */