WATCHDOG USER GUIDE¶

REVISION HISTORY¶

Revision No.	Description	Date
1.0	Initial release	04/21/2023

1. OVERVIEW¶

The hardware watchdog provides a timeout reset system function, which consists of a timer and a reset function. Users can set a timeout period and perform a "feed dog" operation within the timeout period to reset its internal count. If its internal calculation reaches the set timeout period, the watchdog will reset the system and restart it.

2. KEYWORD DESCRIPTION¶

watchdog

A watchdog is a timer circuit that typically has an input called "kick the dog/service the dog" and an output to the RST terminal of the MCU. When the MCU is working normally, it outputs a signal to the dog feeding terminal at regular intervals to reset the WDT. If the WDT timer exceeds the specified time (usually when the program runs out), it will give a reset signal to the MCU to reset it. Prevent MCU from crashing The role of a watchdog is to prevent the program from looping or running away.
watchdog timeout

The timeout duration of the watchdog. If the watchdog is not fed after this duration, the WDT timer will exceed, and a reset signal will be sent to the MCU to reset it.
watchdog pretimeout

The pre timeout duration of the watchdog. Pretimeout is the length of time from the trigger time to the system restart time point. For example, if you set the timeout to 60, Pretimeout is 10, so the mechanism will be triggered at 50 seconds (10 seconds before restart).

3. FUNCTION DESCRIPTION¶

The Linux kernel supports softdogs based on hrtimer and hardware watchdogs based on hardware, creating/dev/watchdog* device files to interact with user space programs. The watchdog program in user space will feed dogs periodically through the/dev/watchdog* device.

Picture 1-1 watchdog Framework

4. HARDWARE CONNECTION INTRODUCTION¶

NA

5. UBOOT USAGE INTRODUCTION¶

5.1. uboot config configuration¶

Watchdog 驱动相关的 CONFIG 配置如下:

(1) CONFIG_SSTAR_WDT:

[*] SigmaStar drivers  --->
[*]   Sigmastar watchdog

(2) CONFIG_WATCHDOG_AUTOSTART和CONFIG_WATCHDOG_TIMEOUT_MSECS:

[*] Device Drivers  --->
[*]   Watchdog Timer Support --->
[*]     Automatically start watchdog timer
[*]     Watchdog timeout in msec

If CONFIG_WATCHDOGAUTOSTART=Y, Watchdog will start with WATCHDOG_TIMEOUT_SECS as the timeout when uboot starts
CONFIG_WATCHDOG_TIMEOUT_MSECS default is 2000ms same as 2s

(3) CONFIG_WATCHDOG:

[*] Device Drivers  --->
[*]   Watchdog Timer Support --->
[*]       Enable U-Boot watchdog reset

Enable CONFIG_WATCHDOG，uboot feeds watchdog every second
If CONFIG_WATCHDOGAUTOSTART is enabled but CONFIG_WATCHDOG is not enabled, system will restart after WATCHDOG_TIMEOUT_SECS ms

5.2. DTS Configuration¶

The DTS configuration related to Watchdog driver is as follows:

watchdog: watchdog {
    compatible = "sstar,wdt";
    reg = <0x1F006000 0x40>;
    status = "okay";
};

Watchdog DTS configuration instructions:

Attribute	Description	Setting Value	Notes
compatible	Match drivers for driver registration	"sstar,wdt"	Modification prohibited
reg	Watchdog register information	Hardware design decision	Modification prohibited
status	Choose whether to enable watchdog driver	"ok" or "disable"	Modified as needed

5.3. Uboot cmd parameter description¶

List watchdog devices:
```
wdt list - list watchdog devices
```
Parameter Description

NA NA
Get/set current watchdog device:
```
wdt dev [<name>] - get/set current watchdog device
```
Parameter Description

name The current watchdog device without parameters
Start watchdog timer:
```
wdt start <timeout ms> [flags] - start watchdog timer
```
Parameter Description

timeout ms Specify the timeout period for the watchdog, unit ms

flags The flags information passed to the watchdog driver is not being used by the current driver
Stop watchdog timer:
```
wdt stop - stop watchdog timer
```
Parameter Description

NA NA
Reset watchdog timer:
```
wdt reset - reset watchdog timer
```
Parameter Description

NA NA
Expire watchdog timer immediately:
```
wdt expire [flags] - expire watchdog timer immediately
```
Parameter Description

flag NA

The wdt expire command is used to trigger a Watchdog timeout immediately. The native implementation of uboot sets the timeout to 1ms. The current hardware does not support this command.

5.4. Uboot cmd usage instance¶

wdt list →  wdt list                //List available watchdog

wdt dev [<name>] → wdt dev watchdog // Use the name watchdog for this watchdog

wdt start <timeout ms> [flags] → wdt start 10000 //Set watchdog timeout to 10 seconds

wdt reset → wdt reset //Reset watchdog timer before watchdog timeout occurs

wdt stop → wdt stop // Stop watchdog before timeout occurs

When using this tool to test, it need to disable CONFIG_WATCHDOG and CONFIG_WATCHDOGAUTOSTART, otherwise the uboot system will automatically ping the watchdog every once in a while, and you cannot test the wdt start feature.

6. Introduction to Kernel Usage¶

6.1. CONFIG configuration¶

The CONFIG configuration related to Watchdog driver is as follows:

    Device Drivers  --->
    [*] SStar SoC platform drivers  --->
    <*>   watchdog driver

6.2. DTS configuration¶

The DTS configuration related to Watchdog driver is as follows:

    WDT: watchdog {
        compatible = "sstar,wdt";
        reg = <0x0 0x1F006000 0x0 0x40>;
        interrupts = <GIC_SPI INT_FIQ_WDT IRQ_TYPE_LEVEL_HIGH>;
        max-length = <40>;
        status = "okay";
    };

watchdog DTS配置说明:

Attribute	Description	Set Value	Notes
compatible	Match driver for driver registration	"sstar,wdt"	Modification prohibited
reg	Watchdog register information	Hardware design decision	Modification prohibited
interrupts	Specify the hardware interrupt number used by Watchdog	Hardware design decision	Modification prohibited
max-length	Watchodog counting width	Hardware design decision	Modification prohibited
status	Choose whether to enable watchdog driver	"ok" or "disable"	Modify as needed

6.3. Padmux configuration¶

NA

6.4. Module Usage Introduction¶

6.4.1. SYSFS usage method¶

NA

6.4.2. How to use ioctl¶

The header file includes/uapi/Linux/watchdog. h, and the struct watchdog_info structure describes the information of the watchdog device

WDIOC_GETSUPPORT: Obtain the functions supported by the watchdog
WDIOC_SETOPTIONS: Used to turn on or off the watchdog
WDIOC_KEEPALIVE: Keep feeding dog
WDIOC_SETTIMEOUT: Set watchdog timeout time
WDIOC_GETPRETIMEOUT: Get watchdog timeout time

#ifndef _UAPI_LINUX_WATCHDOG_H
#define _UAPI_LINUX_WATCHDOG_H

#include <linux/ioctl.h>
#include <linux/types.h>

#define WATCHDOG_IOCTL_BASE 'W'

struct watchdog_info {
    __u32 options;      /* Options the card/driver supports */
    __u32 firmware_version; /* Firmware version of the card */
    __u8  identity[32]; /* Identity of the board */
};

#define WDIOC_GETSUPPORT    _IOR(WATCHDOG_IOCTL_BASE, 0, struct watchdog_info)
#define WDIOC_GETSTATUS     _IOR(WATCHDOG_IOCTL_BASE, 1, int)
#define WDIOC_GETBOOTSTATUS _IOR(WATCHDOG_IOCTL_BASE, 2, int)
#define WDIOC_GETTEMP       _IOR(WATCHDOG_IOCTL_BASE, 3, int)
#define WDIOC_SETOPTIONS    _IOR(WATCHDOG_IOCTL_BASE, 4, int)
#define WDIOC_KEEPALIVE     _IOR(WATCHDOG_IOCTL_BASE, 5, int)
#define WDIOC_SETTIMEOUT    _IOWR(WATCHDOG_IOCTL_BASE, 6, int)
#define WDIOC_GETTIMEOUT    _IOR(WATCHDOG_IOCTL_BASE, 7, int)
#define WDIOC_SETPRETIMEOUT _IOWR(WATCHDOG_IOCTL_BASE, 8, int)
#define WDIOC_GETPRETIMEOUT _IOR(WATCHDOG_IOCTL_BASE, 9, int)
#define WDIOC_GETTIMELEFT   _IOR(WATCHDOG_IOCTL_BASE, 10, int)

#define WDIOF_UNKNOWN       -1  /* Unknown flag error */
#define WDIOS_UNKNOWN       -1  /* Unknown status error */

#define WDIOF_OVERHEAT      0x0001  /* Reset due to CPU overheat */
#define WDIOF_FANFAULT      0x0002  /* Fan failed */
#define WDIOF_EXTERN1       0x0004  /* External relay 1 */
#define WDIOF_EXTERN2       0x0008  /* External relay 2 */
#define WDIOF_POWERUNDER    0x0010  /* Power bad/power fault */
#define WDIOF_CARDRESET     0x0020  /* Card previously reset the CPU */
#define WDIOF_POWEROVER     0x0040  /* Power over voltage */
#define WDIOF_SETTIMEOUT    0x0080  /* Set timeout (in seconds) */
#define WDIOF_MAGICCLOSE    0x0100  /* Supports magic close char */
#define WDIOF_PRETIMEOUT    0x0200  /* Pretimeout (in seconds), get/set */
#define WDIOF_ALARMONLY     0x0400  /* Watchdog triggers a management or
                    other external alarm not a reboot */
#define WDIOF_KEEPALIVEPING 0x8000  /* Keep alive ping reply */

#define WDIOS_DISABLECARD   0x0001  /* Turn off the watchdog timer */
#define WDIOS_ENABLECARD    0x0002  /* Turn on the watchdog timer */
#define WDIOS_TEMPPANIC     0x0004  /* Kernel panic on temperature trip */

#endif /* _UAPI_LINUX_WATCHDOG_H */

6.5. SampleCode¶

6.5.1. Start Watchdog¶

Open the/dev/watchdog device, and watchdog will be started.

The reference code is as follows：

int wdt_fd = -1;
wdt_fd = open("/dev/watchdog", O_WRONLY);
if (wdt_fd == -1)
{
    // fail to open watchdog device
}

6.5.2. Stop Watchdog¶

The reference code is as follows：

int option = WDIOS_DISABLECARD;
ioctl(wdt_fd, WDIOC_SETOPTIONS, &option);
if (wdt_fd != -1)
{
    close(wdt_fd);
    wdt_fd = -1;
}

6.5.3. Set Timeout¶

Set the timeout in seconds using the standard IOCTL command WDIOC_SETTIMEOUT, with a recommended timeout of more than 5 seconds. The reference code is as follows:

#define WATCHDOG_IOCTL_BASE    'W'
#define WDIOC_SETTIMEOUT       _IOWR(WATCHDOG_IOCTL_BASE, 6, int)
int timeout = 20;
ioctl(wdt_fd, WDIOC_SETTIMEOUT, &timeout);

6.5.4. Feed Watchdog¶

Feed the dog using the standard IOCTL command WDIOC_KEEPALIVE, and the feeding interval should be smaller than the timeout period. The reference code is as follows:

#define WATCHDOG_IOCTL_BASE    'W'
#define WDIOC_KEEPALIVE        _IOR(WATCHDOG_IOCTL_BASE, 5, int)
ioctl(wdt_fd, WDIOC_KEEPALIVE, 0);

6.5.5. demo¶

#include <stdio.h>
#include <iwatchdog.h>
#include <unistd.h>
#include <fcntl.h>
#include <string.h>
#include <errno.h>
#include <sys/ioctl.h>
#include <linux/watchdog.h>

int main() {
    int fd = open("/dev/watchdog", O_WRONLY);
    if (fd < 0) {
        perror("Failed to open /dev/watchdog");
        return -1;
    }
    if (ioctl(fd, WDIOC_SETOPTIONS, WDIOS_ENABLECARD) < 0) {
        perror("Failed to enable watchdog");
        close(fd);
        return -1;
    }
    while (1) {
        if (write(fd, "V", 1) != 1) {  // Reset watchdog timer
            perror("Failed to reset watchdog timer");
            break;
        }
        sleep(1);  // Sleep for a while before resetting again
    }
    close(fd);
    return 0;
}

6.5.6 Test Cases¶

Linux test cases ：<Kernel>drivers/sstar/watchdog/ut/wdt_ut.c

Example:
  # wdt_ut start 10   /* After starting watchdog, the system will continuously feed the dog, so the system will not restart after 10 seconds*/

  # wdt_ut reset 10   /* After starting watchdog, the system will not feed the dog, so the system will restart after 10 seconds*/

7. API Reference¶

NA

8. FAQ¶

NA

Parameter	Description
timeout ms	Specify the timeout period for the watchdog, unit ms
flags	The flags information passed to the watchdog driver is not being used by the current driver