[Peripherals] Working Principle of Linux Watchdog

Table of contents

1. What is a watchdog?

2. Analysis of watchdog kernel source code 

3. Write the watchdog program

4. Special instructions on the role of the watchdog 

---

1. What is a watchdog?

To put it simply, the watchdog is a timer Watchdog Timer (WDT), which is a hardware circuit that can reset the Linux system when the software fails. Here's a brief overview of how it works: 

In the user space, the watchdog program continuously writes data to the watchdog in the form of "feeding the dog" (that is, the kernel's watchdog driver is notified through the /dev/watchdog special device file). If the dog is not fed within a certain period of time (that is, no data is written into the watchdog ), it will execute a system reset, and jump to the interrupt vector table to execute the reset vector.

2. Analysis of watchdog kernel source code 

A complete set of driver interfaces is provided in the kernel, as follows:

wdt_open   : open the device , enter this function when the program calls open
wdt_close  : close the device, enter this function when the program calls close
wdt_write   : write the device, if the size of the incoming data is not 0, feed the dog; enter this function
wdt_ioctl when the program calls write    : This function is the most important, the prototype is as follows (driver/watchdog)

The wdt_ioctl  driver source code is implemented as follows (take w83697hf as an example): 

static long wdt_ioctl(struct file *file, unsigned int cmd, unsigned long arg)
{
	void __user *argp = (void __user *)arg;
	int __user *p = argp;
	int new_timeout;
	static const struct watchdog_info ident = {
		.options = WDIOF_KEEPALIVEPING | WDIOF_SETTIMEOUT
							| WDIOF_MAGICCLOSE,
		.firmware_version = 1,
		.identity = "W83697HF WDT",
	};

	switch (cmd) {
	case WDIOC_GETSUPPORT:
		if (copy_to_user(argp, &ident, sizeof(ident)))
			return -EFAULT;
		break;

	case WDIOC_GETSTATUS:
	case WDIOC_GETBOOTSTATUS:
		return put_user(0, p);

	case WDIOC_SETOPTIONS:
	{
		int options, retval = -EINVAL;

		if (get_user(options, p))
			return -EFAULT;

		if (options & WDIOS_DISABLECARD) {
			wdt_disable();
			retval = 0;
		}

		if (options & WDIOS_ENABLECARD) {
			wdt_enable();
			retval = 0;
		}

		return retval;
	}

	case WDIOC_KEEPALIVE:
		wdt_ping();
		break;

	case WDIOC_SETTIMEOUT:
		if (get_user(new_timeout, p))
			return -EFAULT;
		if (wdt_set_heartbeat(new_timeout))
			return -EINVAL;
		wdt_ping();
		/* Fall */

	case WDIOC_GETTIMEOUT:
		return put_user(timeout, p);

	default:
		return -ENOTTY;
	}
	return 0;
}

Briefly describe the important parameters:
WDIOC_KEEPALIVE     : Feed the dog, similar to the write function
WDIOC_SETTIMEOUT  : Set the timeout value
WDIOC_GETTIMEOUT  : Get the timeout value
WDIOC_SETOPTIONS  : Set the watchdog status, open ( WDIOS_ENABLECARD ) or close ( WDIOS_DISABLECARD ) 

3. Write the watchdog program

#include <stdio.h>
#include <fcntl.h>
#include <unistd.h>
#include <sys/ioctl.h>
#include <linux/types.h>
#include <linux/watchdog.h>

static int open_watchdog(void)
{
	int wtd_fd = 0;
 
	wtd_fd = open("/dev/watchdog", O_RDWR);
	if (wtd_fd < 0) 
		return -1;

	int timeout = 60; //60s
	ioctl(wtd_fd, WDIOC_SETOPTIONS, WDIOS_ENABLECARD);
	ioctl(wtd_fd, WDIOC_SETTIMEOUT, &timeout);
	
	return wtd_fd;
}

static void feed_watchdog(int wtd_fd)
{
	while (1) {
		ioctl(wtd_fd, WDIOC_KEEPALIVE, NULL);
		sleep(10);
	}
}

static int close_watchdog(int wtd_fd)
{
	ioctl(wtd_fd, WDIOC_SETOPTIONS, WDIOS_DISABLECARD);
	close(wtd_fd);
}

int main(void)
{
	int wtd_fd = 0;
 
	/* 打开设备 */
	wtd_fd = open_watchdog(void);
	if (wtd_fd < 0) {  
		printf("wtd open failed\n");  
		return -1;
	}
 
	/* 喂狗 */
	feed_watchdog(wtd_fd);

	/* 关闭设备 */
	close_watchdog(wtd_fd);
	
	return 0;
}

4. Special instructions on the role of the watchdog 

1. In practical applications, it is generally not necessary to take the initiative to close the watchdog ( close  or  WDIOS_DISABLECARD ) , because after closing the watchdog, it will not work, and the system cannot be reset. Only when you clearly do not need the watchdog function to take effect, you can actively turn off the watchdog;

2. When the program crashes or the soft restart fails, the watchdog is the last guarantee to reset the system (if even the watchdog fails, you can only unplug and plug the power supply obediently to restart the system).