The Linux Watchdog driver API

문서 범위와 출처

이 문서는 Linux Watchdog 드라이버 API를 설명하며 마지막 검토일은 2007-10-05입니다. Christer Weingel의 2002년 저작물이고 일부는 Jakob Oestergaard의 `sbc60xxwdt` 드라이버 문서를 그대로 가져왔습니다.

원문은 Linux 2.4.18 시점의 API 상태를 설명하므로 현재 코드를 적용할 때는 커널 API 문서와 구현을 함께 확인해야 합니다.

=============================
The Linux Watchdog driver API
=============================

Last reviewed: 10/05/2007



Copyright 2002 Christer Weingel <wingel@nano-system.com>

Some parts of this document are copied verbatim from the sbc60xxwdt
driver which is (c) Copyright 2000 Jakob Oestergaard <jakob@ostenfeld.dk>

This document describes the state of the Linux 2.4.18 kernel.

WDT와 사용자 공간 daemon

Watchdog Timer, WDT는 소프트웨어 오류가 발생했을 때 컴퓨터를 reset할 수 있는 하드웨어 회로입니다.

일반적으로 사용자 공간 daemon이 `/dev/watchdog` 특수 파일을 통해 일정 간격으로 살아 있음을 커널 드라이버에 알립니다. 드라이버는 하드웨어 watchdog에 정상 상태를 알려 reset을 조금 더 미룹니다.

RAM 오류, 커널 bug 등으로 사용자 공간이 실패해 알림이 끊기면 timeout 뒤 하드웨어 watchdog이 시스템을 reset해 reboot합니다.

Linux watchdog API는 역사적으로 임시방편식으로 만들어져 드라이버마다 지원 범위가 다르고 때로 호환되지 않습니다. 이 문서는 기존 사용법을 기록하고 새 드라이버 작성자가 참고할 기준을 제공합니다.

Introduction
============

A Watchdog Timer (WDT) is a hardware circuit that can reset the
computer system in case of a software fault.  You probably knew that
already.

Usually a userspace daemon will notify the kernel watchdog driver via the
/dev/watchdog special device file that userspace is still alive, at
regular intervals.  When such a notification occurs, the driver will
usually tell the hardware watchdog that everything is in order, and
that the watchdog should wait for yet another little while to reset
the system.  If userspace fails (RAM error, kernel bug, whatever), the
notifications cease to occur, and the hardware watchdog will reset the
system (causing a reboot) after the timeout occurs.

The Linux watchdog API is a rather ad-hoc construction and different
drivers implement different, and sometimes incompatible, parts of it.
This file is an attempt to document the existing usage and allow
future driver writers to use it as a reference.

가장 단순한 API와 nowayout

모든 드라이버는 `/dev/watchdog`을 열면 watchdog이 활성화되고 일정 시간 안에 ping하지 않으면 reboot하는 기본 모드를 지원합니다. 이 시간은 timeout 또는 margin입니다.

가장 단순한 ping은 장치에 데이터를 쓰는 것입니다. 기본 daemon 예는 `samples/watchdog/watchdog-simple.c`에 있습니다. 더 발전된 daemon은 HTTP server가 여전히 응답하는지 확인한 뒤 write할 수 있습니다.

장치를 닫으면 보통 watchdog을 끄지만 Magic Close를 지원하는 경우는 다릅니다. Daemon bug로 파일이 닫힌 뒤 watchdog까지 꺼지면 시스템이 reboot하지 못할 수 있습니다.

이를 막기 위해 일부 드라이버는 `CONFIG_WATCHDOG_NOWAYOUT`을 지원합니다. 커널 빌드 때 `Y`이면 한 번 시작한 watchdog을 끌 수 없습니다. 대부분 장치는 런타임 제어를 위한 `nowayout` 모듈 매개변수도 지원합니다.

The simplest API
================

All drivers support the basic mode of operation, where the watchdog
activates as soon as /dev/watchdog is opened and will reboot unless
the watchdog is pinged within a certain time, this time is called the
timeout or margin.  The simplest way to ping the watchdog is to write
some data to the device.  So a very simple watchdog daemon would look
like this source file:  see samples/watchdog/watchdog-simple.c

A more advanced driver could for example check that a HTTP server is
still responding before doing the write call to ping the watchdog.

When the device is closed, the watchdog is disabled, unless the "Magic
Close" feature is supported (see below).  This is not always such a
good idea, since if there is a bug in the watchdog daemon and it
crashes the system will not reboot.  Because of this, some of the
drivers support the configuration option "Disable watchdog shutdown on
close", CONFIG_WATCHDOG_NOWAYOUT.  If it is set to Y when compiling
the kernel, there is no way of disabling the watchdog once it has been
started.  So, if the watchdog daemon crashes, the system will reboot
after the timeout has passed. Watchdog devices also usually support
the nowayout module parameter so that this option can be controlled at
runtime.

Magic Close

Magic Close를 지원하는 드라이버는 파일을 닫기 직전에 `/dev/watchdog`으로 문자 `V`를 보낸 경우에만 watchdog을 끕니다.

Daemon이 `V` 없이 파일을 닫으면 드라이버는 daemon과 사용자 공간이 죽었다고 판단해 watchdog을 비활성화하지 않고 ping만 멈춥니다. 충분한 시간 안에 장치를 다시 열지 않으면 reboot합니다.

Magic Close feature
===================

If a driver supports "Magic Close", the driver will not disable the
watchdog unless a specific magic character 'V' has been sent to
/dev/watchdog just before closing the file.  If the userspace daemon
closes the file without sending this special character, the driver
will assume that the daemon (and userspace in general) died, and will
stop pinging the watchdog without disabling it first.  This will then
cause a reboot if the watchdog is not re-opened in sufficient time.

WDIOC_KEEPALIVE

규격을 따르는 모든 드라이버는 ioctl API를 지원합니다. Ioctl 인터페이스가 있는 드라이버는 최소한 `WDIOC_KEEPALIVE`를 지원하며 장치에 write하는 것과 똑같이 watchdog을 ping합니다.

원문 예시는 무한 루프에서 `ioctl(fd, WDIOC_KEEPALIVE, 0)`을 호출한 뒤 10초 sleep합니다. ioctl 인수는 무시됩니다.

The ioctl API
=============

All conforming drivers also support an ioctl API.

Pinging the watchdog using an ioctl:

All drivers that have an ioctl interface support at least one ioctl,
KEEPALIVE.  This ioctl does exactly the same thing as a write to the
watchdog device, so the main loop in the above program could be
replaced with::

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

the argument to the ioctl is ignored.

timeout 설정과 조회

일부 드라이버는 `WDIOC_SETTIMEOUT`으로 실행 중 timeout을 바꿀 수 있고 `options`에 `WDIOF_SETTIMEOUT`을 설정합니다. 인수는 초 단위 정수입니다.

드라이버는 실제 적용한 timeout을 같은 변수에 돌려줍니다. 하드웨어 제한 때문에 요청과 다를 수 있습니다. 예를 들어 분 단위 장치는 45초 요청에 60초를 반환할 수 있습니다.

Linux 2.4.18부터 `WDIOC_GETTIMEOUT`으로 현재 timeout을 조회할 수 있습니다.

Setting and getting the timeout
===============================

For some drivers it is possible to modify the watchdog timeout on the
fly with the SETTIMEOUT ioctl, those drivers have the WDIOF_SETTIMEOUT
flag set in their option field.  The argument is an integer
representing the timeout in seconds.  The driver returns the real
timeout used in the same variable, and this timeout might differ from
the requested one due to limitation of the hardware::

    int timeout = 45;
    ioctl(fd, WDIOC_SETTIMEOUT, &timeout);
    printf("The timeout was set to %d seconds\n", timeout);

This example might actually print "The timeout was set to 60 seconds"
if the device has a granularity of minutes for its timeout.

Starting with the Linux 2.4.18 kernel, it is possible to query the
current timeout using the GETTIMEOUT ioctl::

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

pretimeout

일부 watchdog은 실제 시스템 reset 전에 NMI, interrupt 등으로 선행 trigger를 발생시킬 수 있습니다. Linux는 이 시간을 이용해 panic 정보나 kernel coredump 같은 진단 자료를 기록합니다.

`WDIOC_SETPRETIMEOUT`의 값은 지금부터 pretimeout까지 남은 시간이 아니라 최종 timeout보다 몇 초 앞선지를 의미합니다. Timeout 60초, pretimeout 10초라면 trigger는 50초 뒤 발생합니다. 0은 pretimeout을 끕니다.

`WDIOC_GETPRETIMEOUT`으로 현재 값을 조회할 수 있으며 모든 watchdog 드라이버가 pretimeout을 지원하는 것은 아닙니다.

Pretimeouts
===========

Some watchdog timers can be set to have a trigger go off before the
actual time they will reset the system.  This can be done with an NMI,
interrupt, or other mechanism.  This allows Linux to record useful
information (like panic information and kernel coredumps) before it
resets::

    pretimeout = 10;
    ioctl(fd, WDIOC_SETPRETIMEOUT, &pretimeout);

Note that the pretimeout is the number of seconds before the time
when the timeout will go off.  It is not the number of seconds until
the pretimeout.  So, for instance, if you set the timeout to 60 seconds
and the pretimeout to 10 seconds, the pretimeout will go off in 50
seconds.  Setting a pretimeout to zero disables it.

There is also a get function for getting the pretimeout::

    ioctl(fd, WDIOC_GETPRETIMEOUT, &timeout);
    printf("The pretimeout was is %d seconds\n", timeout);

Not all watchdog drivers will support a pretimeout.

reboot까지 남은 시간

남은 시간을 보고할 수 있는 드라이버는 `WDIOC_GETTIMELEFT`로 시스템 reboot까지 남은 초를 반환합니다.

원문 예시는 `timeleft` 정수 변수의 주소를 ioctl에 전달해 결과를 출력합니다.

Get the number of seconds before reboot
=======================================

Some watchdog drivers have the ability to report the remaining time
before the system will reboot. The WDIOC_GETTIMELEFT is the ioctl
that returns the number of seconds before reboot::

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

환경 감시와 상태 플래그

모든 watchdog 드라이버는 시스템에 관한 추가 정보를 반환해야 합니다. 일부는 온도·팬·전원 레벨을 감시하고 일부는 마지막 reboot 원인을 보고합니다. `WDIOC_GETSUPPORT`는 `struct watchdog_info`를 채워 장치 기능을 알려 줍니다.

`identity`는 드라이버 식별 문자열, `firmware_version`은 가능한 경우 카드 firmware 버전, `options`는 지원 기능을 나타내는 flag입니다.

상태 flag는 과열 reset `WDIOF_OVERHEAT`, 팬 고장 `WDIOF_FANFAULT`, 외부 relay 1·2 trigger, 저전압 `WDIOF_POWERUNDER`, 이전 watchdog card CPU reset `WDIOF_CARDRESET`, 과전압 `WDIOF_POWEROVER`를 포함합니다. 한 전원 레벨은 낮고 다른 레벨은 높으면 UNDER와 OVER가 동시에 설정될 수 있습니다.

`WDIOF_KEEPALIVEPING`은 마지막 조회 뒤 keepalive를 받았음을, `WDIOF_SETTIMEOUT`은 timeout 설정·조회를 지원함을, `WDIOF_PRETIMEOUT`은 초 단위 pretimeout 설정·조회를 지원함을 뜻합니다.

`options`에 상태 비트를 반환하는 드라이버는 `WDIOC_GETSTATUS`와 `WDIOC_GETBOOTSTATUS`로 각각 현재 상태와 마지막 reboot 시 상태를 조회할 수 있습니다. 장치에 따라 둘 다 또는 GETBOOTSTATUS만 지원합니다.

일부 드라이버는 `WDIOC_GETTEMP`로 화씨 온도를 반환합니다. `WDIOC_SETOPTIONS`는 `WDIOS_DISABLECARD`, `WDIOS_ENABLECARD`, 온도 이상 시 kernel panic을 일으키는 `WDIOS_TEMPPANIC`을 제어합니다.

Environmental monitoring
========================

All watchdog drivers are required return more information about the system,
some do temperature, fan and power level monitoring, some can tell you
the reason for the last reboot of the system.  The GETSUPPORT ioctl is
available to ask what the device can do::

        struct watchdog_info ident;
        ioctl(fd, WDIOC_GETSUPPORT, &ident);

the fields returned in the ident struct are:

        ================        =============================================
        identity                a string identifying the watchdog driver
        firmware_version        the firmware version of the card if available
        options                        a flags describing what the device supports
        ================        =============================================

the options field can have the following bits set, and describes what
kind of information that the GET_STATUS and GET_BOOT_STATUS ioctls can
return.

        ================        =========================
        WDIOF_OVERHEAT                Reset due to CPU overheat
        ================        =========================

The machine was last rebooted by the watchdog because the thermal limit was
exceeded:

        ==============                ==========
        WDIOF_FANFAULT                Fan failed
        ==============                ==========

A system fan monitored by the watchdog card has failed

        =============                ================
        WDIOF_EXTERN1                External relay 1
        =============                ================

External monitoring relay/source 1 was triggered. Controllers intended for
real world applications include external monitoring pins that will trigger
a reset.

        =============                ================
        WDIOF_EXTERN2                External relay 2
        =============                ================

External monitoring relay/source 2 was triggered

        ================        =====================
        WDIOF_POWERUNDER        Power bad/power fault
        ================        =====================

The machine is showing an undervoltage status

        ===============                =============================
        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::

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

    or

    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::

    int temperature;
    ioctl(fd, WDIOC_GETTEMP, &temperature);

Finally the SETOPTIONS ioctl can be used to control some aspects of
the cards operation::

    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
        =================        ================================

[FIXME -- better explanations]