1# Watchdog 2 3 4## **Overview** 5 6A watchdog, also called a watchdog timer, is a hardware timing device used to facilitate automatic correction of temporary hardware faults or recover from system malfunctions. If an error occurs in the main program of the system and the watchdog timer is not cleared in time, the watchdog timer sends a reset signal to restore the system to the normal state. 7 8 9## Available APIs 10 11**Table 1** Watchdog APIs 12 13| API| Description| 14| -------- | -------- | 15| WatchdogOpen | Opens a watchdog.| 16| WatchdogClose | Closes a watchdog.| 17| WatchdogStart | Starts a watchdog.| 18| WatchdogStop | Stops a watchdog.| 19| WatchdogSetTimeout | Sets the watchdog timeout duration.| 20| WatchdogGetTimeout | Obtains the watchdog timeout duration.| 21| WatchdogGetStatus | Obtains the watchdog status.| 22| WatchdogFeed | Feeds a watchdog or resets a watchdog timer.| 23 24>  **NOTE** 25> 26> All watchdog APIs provided in this document can be called only in kernel mode. 27 28 29## Usage Guidelines 30 31 32### How to Use 33 34The figure below shows how to use the watchdog APIs. 35 36Figure 1 Using watchdog APIs 37 38 39 40 41### Opening a Watchdog 42 43Use **WatchdogOpen()** to open a watchdog. A system may have multiple watchdogs. You need to specify the ID of the watchdog to open. 44 45``` 46DevHandle WatchdogOpen(int16_t wdtId); 47``` 48 49**Table 2** Description of WatchdogOpen 50 51| **Parameter**| **Description**| 52| -------- | -------- | 53| wdtId | Watchdog ID.| 54| **Return Value**| **Description**| 55| NULL | The operation failed.| 56| **DevHandle** pointer| The operation is successful. The pointer to the watchdog device handle is returned.| 57 58 59``` 60DevHandle handle = NULL; 61handle = WatchdogOpen(0); /* Open watchdog 0.*/ 62if (handle == NULL) { 63 HDF_LOGE("WatchdogOpen: failed, ret %d\n", ret); 64 return; 65} 66``` 67 68 69### Obtaining the Watchdog Status 70 71``` 72int32_t WatchdogGetStatus(DevHandle handle, int32_t *status); 73``` 74 75**Table 3** Description of WatchdogGetStatus 76 77| **Parameter**| **Description**| 78| -------- | -------- | 79| handle | Watchdog device handle.| 80| status | Pointer to the watchdog status obtained.| 81| **Return Value**| **Description**| 82| 0 | The operation is successful.| 83| Negative value| The operation failed.| 84 85 86``` 87int32_t ret; 88int32_t status; 89/* Obtain the watchdog status. */ 90ret = WatchdogGetStatus(handle, &status); 91if (ret != 0) { 92 HDF_LOGE("WatchdogGetStatus: failed, ret %d\n", ret); 93 return; 94} 95``` 96 97 98### Setting the Timeout Duration 99 100``` 101int32_t WatchdogSetTimeout(DevHandle *handle, uint32_t seconds); 102``` 103 104**Table 4** Description of WatchdogSetTimeout 105 106| **Parameter**| **Description**| 107| -------- | -------- | 108| handle | Pointer to the watchdog device handle.| 109| seconds | Timeout duration to set, in seconds.| 110| **Return Value**| **Description**| 111| 0 | The operation is successful.| 112| Negative value| The operation failed.| 113 114 115``` 116int32_t ret; 117uint32_t timeOut = 60; 118/* Set the timeout duration to 60 seconds. */ 119ret = WatchdogSetTimeout(handle, timeOut); 120if (ret != 0) { 121 HDF_LOGE("WatchdogSetTimeout: failed, ret %d\n", ret); 122 return; 123} 124``` 125 126 127### Obtaining the Timeout Duration 128 129``` 130int32_t WatchdogGetTimeout(DevHandle *handle, uint32_t *seconds); 131``` 132 133**Table 5** Description of WatchdogGetTimeout 134 135| **Parameter**| **Description**| 136| -------- | -------- | 137| handle | Pointer to the watchdog device handle.| 138| seconds | Pointer to the timeout duration, in seconds.| 139| **Return Value**| **Description**| 140| 0 | The operation is successful.| 141| Negative value| The operation failed.| 142 143 144``` 145int32_t ret; 146uint32_t timeOut; 147/* Obtain the timeout duration, in seconds. */ 148ret = WatchdogGetTimeout(handle, &timeOut); 149if (ret != 0) { 150 HDF_LOGE("WatchdogGetTimeout: failed, ret %d\n", ret); 151 return; 152} 153``` 154 155 156### Starting a Watchdog 157 158``` 159int32_t WatchdogStart(DevHandle handle); 160``` 161 162**Table 6** Description of WatchdogStart 163 164| **Parameter**| **Description**| 165| -------- | -------- | 166| handle | Watchdog device handle.| 167| **Return Value**| **Description**| 168| 0 | The operation is successful.| 169| Negative value| The operation failed.| 170 171 172``` 173int32_t ret; 174/* Start the watchdog. */ 175ret = WatchdogStart(handle); 176if (ret != 0) { 177 HDF_LOGE("WatchdogStart: failed, ret %d\n", ret); 178 return; 179} 180``` 181 182 183### Feeding a Watchdog 184 185``` 186int32_t WatchdogFeed(DevHandle handle); 187``` 188 189**Table 7** Description of WatchdogFeed 190 191| **Parameter**| **Description**| 192| -------- | -------- | 193| handle | Watchdog device handle.| 194| **Return Value**| **Description**| 195| 0 | The operation is successful.| 196| Negative value| The operation failed.| 197 198 199``` 200int32_t ret; 201/* Feed the watchdog. */ 202ret = WatchdogFeed(handle); 203if (ret != 0) { 204 HDF_LOGE("WatchdogFeed: failed, ret %d\n", ret); 205 return; 206} 207``` 208 209 210### Stopping a Watchdog 211 212``` 213int32_t WatchdogStop(DevHandle handle); 214``` 215 216**Table 8** Description of WatchdogStop 217 218| **Parameter**| **Description**| 219| -------- | -------- | 220| handle | Watchdog device handle.| 221| **Return Value**| **Description**| 222| 0 | The operation is successful.| 223| Negative value| The operation failed.| 224 225 226``` 227int32_t ret; 228/* Stop the watchdog. */ 229ret = WatchdogStop(handle); 230if (ret != 0) { 231 HDF_LOGE("WatchdogStop: failed, ret %d\n", ret); 232 return; 233} 234``` 235 236 237### Closing a Watchdog 238 239If a watchdog is no longer required, call **WatchdogClose()** to close it. 240 241``` 242void WatchdogClose(DevHandle handle); 243``` 244 245**Table 9** Description of WatchdogClose 246 247| **Parameter**| **Description**| 248| -------- | -------- | 249| handle | Watchdog device handle.| 250 251 252``` 253/* Close the watchdog. */ 254ret = WatchdogClose(handle); 255``` 256 257 258## Example 259 260The following example provides the complete development process. 261 2621. Open a watchdog, set the timeout duration, and start the watchdog. 263 2642. Feed the watchdog periodically to ensure that the system is not reset due to timer expiry. 2653. Stop feeding the watchdog and check whether the system is reset after the timer expires. 266 267Sample code: 268 269``` 270#include "watchdog_if.h" 271#include "hdf_log.h" 272#include "osal_irq.h" 273#include "osal_time.h" 274 275#define WATCHDOG_TEST_TIMEOUT 2 276#define WATCHDOG_TEST_FEED_TIME 6 277 278static int32_t TestCaseWatchdog(void) 279{ 280 int32_t i; 281 int32_t ret; 282 uint32_t timeout; 283 DevHandle handle = NULL; 284 285 /* Open watchdog 0. */ 286 handle = WatchdogOpen(0); 287 if (handle == NULL) { 288 HDF_LOGE("Open watchdog failed!"); 289 return -1; 290 } 291 292 /* Set the timeout duration. */ 293 ret = WatchdogSetTimeout(handle, WATCHDOG_TEST_TIMEOUT); 294 if (ret != HDF_SUCCESS) { 295 HDF_LOGE("%s: set timeout fail! ret:%d\n", __func__, ret); 296 WatchdogClose(handle); 297 return ret; 298 } 299 300 /* Obtain the timeout duration. */ 301 ret = WatchdogGetTimeout(handle, &timeout); 302 if (ret != HDF_SUCCESS) { 303 HDF_LOGE("%s: get timeout fail! ret:%d\n", __func__, ret); 304 WatchdogClose(handle); 305 return ret; 306 } 307 HDF_LOGI("%s: read timeout back:%u\n", __func__, timeout); 308 309 /* Start the watchdog. The timer starts. */ 310 ret = WatchdogStart(handle); 311 if (ret != HDF_SUCCESS) { 312 HDF_LOGE("%s: start fail! ret:%d\n", __func__, ret); 313 WatchdogClose(handle); 314 return ret; 315 } 316 317 /* Feed the watchdog every other second. */ 318 for (i = 0; i < WATCHDOG_TEST_FEED_TIME; i++) { 319 HDF_LOGI("%s: feeding watchdog %d times... \n", __func__, i); 320 ret = WatchdogFeed(handle); 321 if (ret != HDF_SUCCESS) { 322 HDF_LOGE("%s: feed dog fail! ret:%d\n", __func__, ret); 323 WatchdogClose(handle); 324 return ret; 325 } 326 OsalSleep(1); 327 } 328 /* Because the interval for feeding the watchdog is shorter than the timeout duration, the system does not reset, and logs can be printed normally. */ 329 HDF_LOGI("%s: no reset ... feeding test OK!!!\n", __func__); 330 331 /* Stop feeding the watchdog to make the timer expire. */ 332 for (i = 0; i < WATCHDOG_TEST_FEED_TIME; i++) { 333 HDF_LOGI("%s: waiting dog buck %d times... \n", __func__, i); 334 OsalSleep(1); 335 } 336 337 /* The system resets when the timer expires. Theoretically, this log is not displayed. */ 338 HDF_LOGI("%s: dog hasn't back!!! \n", __func__, i); 339 WatchdogClose(handle); 340 return -1; 341} 342``` 343
