L'API du pilote Linux Watchdog

https://www.kernel.org/doc/html/latest/watchdog/watchdog-api.html

Docs » Linux Watchdog Support » The Linux Watchdog driver API

The Linux Watchdog driver API

Last reviewed: 10/05/2007

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.

Ce document est écrit avec le noyau Linux 2.4.18.

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.

Watchdog Timer (WDT) est un circuit matériel qui peut réinitialiser le système informatique en cas de problème logiciel. Vous le savez peut-être déjà.

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.

Normalement, les démons de l'espace utilisateur notifient périodiquement au pilote wachdog du noyau qu'ils sont toujours actifs via le fichier de périphérique spécial / dev / watchdog qui est actif dans l'espace utilisateur. Lorsqu'une telle notification se produit, le pilote avise généralement le chien de garde matériel que tout va bien, et le chien de garde doit encore attendre un peu plus longtemps pour réinitialiser le système. S'il y a un problème d'espace utilisateur (problème de RAM, bogue du noyau, etc.), l'historique ne se produira plus et le chien de garde du matériel réinitialisera le système après un timeout (ie un redémarrage). Masu).

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.

L'API de surveillance Linux est une structure improvisée. Différents pilotes ont des implémentations différentes, sont incompatibles et implémentent certains d'entre eux. Ce fichier est une tentative de documenter l'utilisation existante et de la rendre visible aux auteurs de pilotes traditionnels.

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

Tous les pilotes prennent en charge les modes de traitement de base. watchdog est activé dès que / dev / watchdog est ouvert. Ensuite, lorsque la notification au chien de garde pour une certaine période de temps meurt, il redémarre. Ce temps est appelé timeout ou marge. Le moyen le plus simple d'envoyer une requête ping à Watchdog est d'écrire des données sur l'appareil. Ainsi, un démon de surveillance très simple ressemble au fichier source suivant: Voir 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.

Les pilotes plus avancés peuvent vérifier que le serveur HTTP répond toujours, par exemple, avant d'effectuer un appel en écriture pour envoyer une requête ping au chien de garde.

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.

Watchdog est désactivé lorsque l'appareil est fermé, si la fonction «Magic Close» n'est pas prise en charge (voir ci-dessous). Ce n'est pas toujours une bonne idée. S'il y a un bogue dans le démon watchdog et qu'il plante, le système ne pourra pas redémarrer. Par conséquent, certains pilotes prennent en charge l'option de configuration «Diasable watchdog shutdown on close», CONFIG_WATCHDOG_NOWAYOUT. Si ce paramètre est défini sur Y lors de la compilation du noyau, il n'y a aucun moyen de l'arrêter une fois que le chien de garde démarre. Par conséquent, si le démon de surveillance tombe en panne, le système sera redémarré une fois le délai écoulé. Les dispositifs de surveillance prennent également généralement en charge un paramètre de module nowayout pour contrôler cette option au moment de l'exécution.

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.

Si le pilote prend en charge "Magic Close", le pilote ne peut pas désactiver le caractère magique "V" spécifique au chien de garde sans l'envoyer à / dev / watchdog avant de fermer le fichier. Lorsque le démon de l'espace utilisateur ferme le fichier sans envoyer de chaîne spéciale, le pilote avertira le chien de garde sans arrêter le démon (et généralement l'espace utilisateur) de mourir pour la première fois. Il est considéré comme arrêté. Si le chien de garde ne rouvre pas suffisamment longtemps, cela entraînera un redémarrage.

The ioctl API

All conforming drivers also support an ioctl API.

Tous les pilotes compatibles prennent également en charge l'API ioctl.

Pinging the watchdog using an ioctl:

Notification au chien de garde utilisant 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:

Les pilotes avec une interface ioctl prennent en charge au moins l'interface KEEP ALIVE. Cet ioctl est identique à l'écriture sur le dispositif de surveillance, de sorte que la boucle principale du programme précédent peut être réécrite comme suit:

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

the argument to the ioctl is ignored.

L'argument ioctl n'est pas valide.

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:

Certains pilotes vous permettent de modifier le délai d'expiration du chien de garde pendant l'exécution avec SETTIMEOUT ioctl. L'indicateur WDIOF_SETTIMEOUT est défini dans le champ d'option pour ces pilotes. L'argument est de type entier et indique le nombre de secondes d'expiration du délai. Le pilote renvoie le délai d'expiration réel en utilisant la même variable. Ce délai d'expiration peut différer de ce qui a été demandé en raison de limitations matérielles.

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.

Dans cet exemple, si le délai d'expiration de l'appareil est en minutes, la sortie réelle serait «Le délai d'expiration a été défini sur 60 secondes».

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

Depuis le noyau Linux 2.4.18, vous pouvez également demander le timeout actuel avec GETTIMEOUT ioctl.


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

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:

Certains minuteries Watcjdog vous permettent de définir un déclencheur avant l'heure réelle de redémarrage du système. Il peut tirer parti des NMI, des interruptions ou d'autres mécanismes. Cela permet à Linux de conserver des informations utiles (par exemple, des informations de panique et des vidages du noyau du noyau) avant de redémarrer.

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.

Notez que le délai d'attente est le temps en secondes avant que le délai d'attente ne soit déclenché. Ce n'est pas une lettre k avant l'expiration du délai. Ainsi, par exemple, si vous définissez le délai d'expiration à 60 secondes et le délai d'expiration à 10 secondes, le délai d'expiration sera activé à 50 secondes. Il peut être désactivé en définissant le pretimeout sur 0.

There is also a get function for getting the pretimeout:

Il existe également une fonction pour obtenir le pretimeout.

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

Not all watchdog drivers will support a pretimeout.

Tous les pilotes Watchdog ne prennent pas en charge le pretimeout.

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:

Certains pilotes Watchdog ont la possibilité de vous informer du temps restant avant le redémarrage du système. WDIOC_GETTIMELEFT est un ioctl qui renvoie le nombre de secondes avant le redémarrage.

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

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:

Tous les pilotes de surveillance doivent renvoyer de nombreuses informations détaillées sur le système. Certains contrôlent la température, le ventilateur et les niveaux de puissance. Certains vous avertiront comme le dernier facteur qui a provoqué le redémarrage du système. GETSUPPORT ioctl peut demander ce que l'appareil peut faire.

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

the fields returned in the ident struct are:

Le champ de la structure ident est le suivant.

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

Chaîne d'identifiant du pilote de surveillance ʻIdentity firmware_version Si activé, la version du firmware de la carte ʻOptions Les descripteurs d'indicateur pris en charge par l'appareil

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. [FIXME – Is this correct?]

Dans le champ d'option, vous pouvez concourir pour les bits suivants et renvoyer des informations dans GET_STATUS ou GET_BOOT_STATUS ioctl [FIXME-Est-ce vrai? ]

WDIOF_OVERHEAT Reset due to CPU overheat The machine was last rebooted by the watchdog because the thermal limit was exceeded:

WDIOF_OVERHEAT Redémarrage en raison d'une surchauffe du processeur La machine a atteint sa limite de température et le chien de garde a fait un dernier redémarrage.

WDIOF_FANFAULT Fan failed A system fan monitored by the watchdog card has failed

WDIOF_FANFAULT Fan failed Ce système a échoué le ventilateur surveillé par la carte de surveillance.

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.

WDIO F_EXTERN1 Facteur externe 1 Un facteur de surveillance externe / déclenchement de la source 1 s'est produit. Le contrôleur pour les applications du monde réel contient une broche pour déclencher une réinitialisation.

WDIOF_EXTERN2 External relay 2 External monitoring relay/source 2 was triggered

WDIOF_EXTERN2 External relay 2 Un facteur de surveillance externe / déclenchement de la source 1 s'est produit.

WDIOF_POWERUNDER Power bad/power fault The machine is showing an undervoltage status

WDIOF_POWERUNDER Panne de courant / panne de courant Une condition de basse tension a été observée sur cette machine.

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

WDIOF_CARDRESET Card previously reset the CPU La carte de surveillance a provoqué le redémarrage final.

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.

WDIO F_POWEROVER Alimentation de surintensité

Cette machine a détecté une condition de surintensité. Notez que cela peut sembler étrange si un niveau descend et un niveau est défini sur les deux bits, mais cela a du sens.

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

WDIOF_KEEPALIVEPING Keep alive ping reply watchdog a détecté une notification keepalive de la dernière demande.

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

WDIOF_SETTIMEOUT Can set/get the timeout Watchdog peut effectuer un pretimeout

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:

WDIOF_PRETIMEOUT Pretimeout (in seconds), get/set Le pilote qui renvoie le bit défini dans le champ d'option peut utiliser GETSTATUS et GETBOOTSTATUS ioctl pour vérifier l'état actuel et l'état au moment du dernier redémarrage. Comme ci-dessous…

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.

Notez que tous les pilotes ne prennent pas en charge ces deux appels et que certains ne prennent en charge que l'appel GETBOOTSTATUS.

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

Certains conducteurs peuvent utiliser GET TEMP icotl pour mesurer la température. La valeur renvoyée est la température en degrés Fahrenheit.


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

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

Enfin, SETOPTION ioctl peut donner des instructions sur plusieurs aspects du fonctionnement de la carte.

int options = 0;
ioctl(fd, WDIOC_SETOPTIONS, &options);

The following options are available:

Les options suivantes sont valides.

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

WDIOS_DISABLECARD Arrêter la minuterie de la station d'accueil Démarrage de la minuterie Witch Dock WDIOS_TEMPPANIC Provoque une panique du noyau en raison de facteurs de température

[FIXME – better explanations]

À l'origine, il fait partie du code source du noyau Linux, il sera donc traité comme GPLv2 (reconnaissance qu'il devrait l'être).

https://www.kernel.org/doc/html/latest/index.html

Licensing documentation

The following describes the license of the Linux kernel source code (GPLv2), how to properly mark the license of individual files in the source tree, as well as links to the full license text.

https://www.kernel.org/doc/html/latest/process/license-rules.html#kernel-licensing