linux笔记—看门狗API文档翻译


  • 随手翻译的文档,要看懂linux内核,内核附带的文档自然是逃不过😂,全英文配合Google翻译也得上。。。。

  • 最后更新时间 10/05/2007

  • linux看门狗设备API

  • Copyright 2002 Christer Weingel wingel@nano-system.com

  • 本文档的一些内容来自 sbc60xxwdt ,版权属于 Copyright 2000 Jakob Oestergaard jakob@ostenfeld.dk

  • 本文档基于linux内核 2.4.18


介绍

  • 你应该已经知道了,看门狗定时器(WDT)是一个硬件复位电路,在系统软件出现故障时复位系统。
  • 通常,用户空间的定期喂狗程序通过/dev/watchdog的设备文件通知内核看门狗驱动程序。驱动收到通知,会告知硬件看门狗一切正常,硬件看门狗需要等一会再复位系统。如果用户空间通知失败(RAM错误、内核漏洞等等),通知将停止。超时后,硬件看门狗将复位系统(重启)。
  • linux看门狗的API是相当特殊的结构,不同的驱动程序对API的执行各不相同,有时会碰到不兼容的情况。本文档参数记录现有的情况,以供未来的驱动开发参考。

最简单的API

  • 所有驱动都支持的基本操作模式。/dev/watchdog被打开后,看门狗被激活并复位系统,除非在一小段时间内被ping通?(喂狗),这段时间被称为超时时间或间断时间。简单的喂狗的方式是向驱动程序写入一些数据,一个非常简单的实例在see samples/watchdog/watchdog-simple.c下.
  • 更高级的驱动程序可以做到例如检查一个http服务器,在执行喂狗操作之前,做出回应。
  • /dev/下设备节点被关闭后,看门狗也同时被禁用,除非支持“Magic Close”(见下文),这并不是个好办法。因为如果看看门狗demo有bug导致系统崩溃,但系统不会重启。因为这样一些驱动支持”Disable watchdog shutdown on close”, CONFIG_WATCHDOG_NOWAYOUT”这样的配置选项。一旦编译内核时候启用这些选项,一旦看门狗程序激活,就不可能禁用看门狗。如果看门狗demo崩溃,系统会在超时后自动重启。看门狗驱动通常也支持nowayout module parameter,以便在运行时控制nowayout module。

Magic Close feature

  • 如果驱动程序支持Magic Close,那么设备将不支持禁用看门狗,除非在关闭设备文件前,向/dev/watchdog下设备文件写入特定的magic 字符 ‘V’。如果用户空间的 daemon关闭了看门的设备文件,但是没有发送那个特定的字符,驱动会认为daemon进程已经被杀,并且停止了定期喂狗行为。这样会导致超时后系统重启。

ioctl API

  • 所有的驱动程序都支持ioctl API

  • 喂狗操作使用ioctl完成

  • 所有的驱动都要支持一个KEEPALIVE的ioctl命令,这个命令可以起到向驱动写入数据一样的作用。所以watchdog daemon的主函数循环可以这样实现

    1
    2
    3
    4
    while (1) {
    ioctl(fd, WDIOC_KEEPALIVE, 0);
    sleep(10);
    }

Setting and getting the timeout

  • 某些驱动支持运行时通过SETTIMEOUT ioctl命令修改超时时间,这些驱动都有WDIOF_SETTIMEOUT的标志位_。超时时间是一个单位为秒的整数,驱动程序会返回这个变量实际设置的数值,但是由于硬件限制,返回的数值可能与设置数值不同。

    1
    2
    3
    int timeout = 45;
    ioctl(fd, WDIOC_SETTIMEOUT, &timeout);
    printf("The timeout was set to %d seconds\n", timeout);
  • 这个实例或许会输出”The timeout was set to 60 seconds”,如果设备超时时间为分钟。

  • 自从2.4.18内核开始,可以使用GETTIMEOUT ioctl命令,获取超时时间。

    1
    2
    ioctl(fd, WDIOC_GETTIMEOUT, &timeout);
    printf("The timeout was is %d seconds\n", timeout);

Pretimeouts

  • 一些看门狗定时器可以在系统重启前一段时间设置一个触发器。这样运行linux在系统从前记录一些重要的信息(像panic信息和kernel coredumps),具体可以通过NMT、中断等机制实现。

    1
    2
    pretimeout = 10;
    ioctl(fd, WDIOC_SETPRETIMEOUT, &pretimeout);
  • 请注意,pretimeout 时间是在 超时关闭系统 之前的秒数。不是直到发生pretimeout 事件的秒数。例如设定的超时时间是60s, pretimeout是10s。pretimeout事件会在50s时发生。pretimeout设置为0代表禁用pretimeout。

  • 同样存在一个获取pretimeout的ioctl命令。

    1
    2
    ioctl(fd, WDIOC_GETPRETIMEOUT, &timeout);
    printf("The pretimeout was is %d seconds\n", timeout);
  • 不是所有看门狗驱动都支持 pretimeout

获取重启前秒数

  • 一些看门狗驱动支持获取系统重启前秒数。通过WDIOC_GETTIMELEFT ioctl_命令可以返回系统重启前秒数。

    1
    2
    ioctl(fd, WDIOC_GETTIMELEFT, &timeleft);
    printf("The timeout was is %d seconds\n", timeleft);

环境监测

  • 所有的看门狗驱动都被要求返回更多关于系统最后一次重启的信息,像是温度、风扇转速、电源等。GETSUPPORT ioctl 的命令可以返回 设备可以支持的信息。

    1
    2
    struct watchdog_info ident;
    ioctl(fd, WDIOC_GETSUPPORT, &ident);
  • 返回的结构ident中的字段如下:

    1
    2
    3
    4
    5
    identity  描述watchdog driver的字符串

    firmware_version the firmware version of the card if available
    options 设备支持情况的标志位

  • options描述了GET_STATUS 和GET_BOOT_STATUS ioctl命令_可以返回那些信息。并且可以设置。()**??无法理解什么意思??**

  • WDIOF_OVERHEAT cpu过热复位_
    系统重启因为,超过了温度限制上限。

  • WDIOF_FANFAULT 风扇失效复位_

  • WDIOF_EXTERN1 External relay 1_
    外部监控电源1被触发,???Controllers intended for real world applications include external monitoring pins that will trigger a reset.??(不明白什么意思)

  • WDIOF_EXTERN2 External relay 2
    外部监控电源2被触发

  • WDIOF_POWERUNDER 电源坏了,电源带不动了
    机器显示欠压。


  • 后面一点不翻了,有时间再添坑

  • WDIOF_CARDRESET Card previously reset the CPU
    The last reboot was caused by the watchdog card

  • WDIOF_POWEROVER Power over voltage
    The machine is showing an overvoltage status. Note that if one level is under and one over both bits will be set - this may seem odd but makes sense.

  • WDIOF_KEEPALIVEPING Keep alive ping reply
    The watchdog saw a keepalive ping since it was last queried.

  • WDIOF_SETTIMEOUT Can set/get the timeout
    The watchdog can do pretimeouts.

  • WDIOF_PRETIMEOUT Pretimeout (in seconds), get/set
    For those drivers that return any bits set in the option field, the GETSTATUS and GETBOOTSTATUS ioctls can be used to ask for the current status, and the status at the last reboot, respectively.

    1
    2
    3

    int flags;
    ioctl(fd, WDIOC_GETSTATUS, &flags);

    or

    1
    ioctl(fd, WDIOC_GETBOOTSTATUS, &flags);
  • Note that not all devices support these two calls, and some only support the GETBOOTSTATUS call.

  • Some drivers can measure the temperature using the GETTEMP ioctl. The returned value is the temperature in degrees fahrenheit.

    1
    2
    int temperature;
    ioctl(fd, WDIOC_GETTEMP, &temperature);
  • Finally the SETOPTIONS ioctl can be used to control some aspects of the cards operation.

    1
    2
    int options = 0;
    ioctl(fd, WDIOC_SETOPTIONS, &options);
  • The following options are available:

    • WDIOS_DISABLECARD Turn off the watchdog timer
    • WDIOS_ENABLECARD Turn on the watchdog timer
    • WDIOS_TEMPPANIC Kernel panic on temperature trip