Difference between revisions of "Watchdog overview"

[quality revision] [quality revision]
m
 
 

Template:ArticleMainWriter Template:ArticleApprovedVersion SUMMARY
This article provides information on the Linux® WDT (Watchdog Timer) framework.
It explains how to activate the WDT interface and, based on examples, how to use it.

1 Framework purpose[edit]

A Watchdog Timer is a hardware circuit that can reset the computer system in case of a software fault (for example, when the software is blocked in an infinity loop and cannot reload the timer before an elapsed time).

2 System overview[edit]

Watchdog overview.png

2.1 Component description[edit]

From client application to hardware, the components are the following:

  • Application (User Space): an application that configures and regularly pings the char device[1].
  • User Space interface: composed of a standard char device[1].
  • Watchdog framework (Kernel Space): this component provides a watchdog common interface [2](through a char device) to configure and control a watchdog hardware block.
  • User driver (Kernel Space): Linux kernel drivers that handle internal peripherals or external devices under watchdog core[3].
  • STM32 peripherals (Hardware): Hardware block for watchdog handling (IWDT).

2.2 API description[edit]

A userspace daemon notifies the kernel watchdog driver that the userspace is still alive at regular intervals. This is done via the char device[1] special device file ((/dev/watchdog). When such a notification occurs, the driver tells the hardware watchdog that everything is in order, and that the watchdog must wait a little more to reset the system. If the userspace fails (because of a RAM error or a kernel bug), the notifications stop and the hardware watchdog resets the system after the timeout occurs, thus causing a reboot.

3 Configuration[edit]

3.1 Kernel configuration[edit]

By default, the Watchdog Timer (WDT[2]) framework is activated in STMicroelectronics deliveries. If a specific configuration is needed, this section indicates how the WDT framework can be activated/inactivated in the kernel.

The WDT framework can be activated in the kernel configuration via Linux® Menuconfig tool. Follow the steps below to configure the kernel via Menuconfig: 

[*] Watchdog Timer Support  --->
    [*] Disable watchdog shutdown on close
    [*] Update boot-enabled watchdog until userspace takes over
    <*>   STM32 Independent WatchDoG (IWDG) support

3.2 Device tree configuration[edit]

DT configuration can be done thanks to STM32CubeMX.

Please refer to the IWDG device tree configuration.

4 How to use the Watchdog framework[edit]

The Watchdog framework can be used by the userspace application:

  • The kernel provides a simple code example[4]
  • Busybox provides a watchdog daemon[5]
  • Systemd provides a watchdog support[6]

5 How to trace and debug the framework[edit]

5.1 How to trace[edit]

For details on dynamic trace usage, refer to How to use the kernel dynamic debug. 

 echo "file drivers/watchdog/* +p" > /sys/kernel/debug/dynamic_debug/control

6 Source code location[edit]

7 References[edit]

  1. ↑ 1.01.11.2 character device interface, Linux Kernel and Driver Development training document, see Character drivers and Kernel frameworks for device drivers chapter
  2. ↑ 2.02.1 kernel.org watchdog user api
  3. ↑ kernel.org watchdog user api
  4. ↑ user example
  5. ↑ busybox commands
  6. ↑ systemd watchdog configuration 


<noinclude>

{{ArticleBasedOnModel | [[Framework overview article model]]}}
{{ArticleMainWriter | LudovicB}}
{{ArticleApprovedVersion | LudovicB | AlexandreT (PASSED 901) | No previous approved version | AnneJ - 17Jan'19 - 10344 | 17Jan'19}}
[[Category:Watchdog|0]]</noinclude>


'''SUMMARY '''<br>
This article provides information on the Linux<sup>&reg;</sup> WDT (Watchdog Timer) framework.<br/>

It explains how to activate the WDT interface and, based on examples, how to use it.<br />
<br />


== Framework purpose ==
A Watchdog Timer is a hardware circuit that can reset the computer system in case of a software fault (for example, when the software is blocked in an infinity loop and cannot reload the timer before an elapsed time).

==System overview==
[[File:watchdog_overview.png|center|link=]]

===Component description===
From client application to hardware, the components are the following:
*'''Application''' (User Space): an application that configures and regularly pings the char device<ref name="char device">[https://bootlin.com/doc/training/linux-kernel/linux-kernel-slides.pdf character device interface], ''Linux Kernel and Driver Development'' training document, see '''Character drivers''' and '''Kernel frameworks for device drivers''' chapter</ref>.
*'''User Space interface''': composed of a standard char device<ref name="char device" />.
*'''Watchdog framework''' (Kernel Space): this component provides a watchdog common interface <ref name="wdt user api">{{CodeSource | Linux kernel | Documentation/watchdog/watchdog-api.txt | kernel.org watchdog user api}}</ref>(through a char device) to configure and control a watchdog hardware block.
*'''User driver''' (Kernel Space): Linux kernel drivers that handle internal peripherals or external devices under watchdog core<ref name="wdt kernel api">{{CodeSource | Linux kernel | Documentation/watchdog/watchdog-kernl-api.txt | kernel.org watchdog user api}}</ref>.
*'''STM32 peripherals''' (Hardware): Hardware block for watchdog handling ([[IWDG internal peripheral|IWDT]]).

===API description===
A userspace daemon notifies the kernel watchdog driver that the userspace is still alive at regular intervals. This is done via the char device<ref name="char device" /> special device file ((/dev/watchdog). When such a notification occurs, the driver tells the hardware watchdog that everything is in order, and that the watchdog must wait a little more to reset the system. 
If the userspace fails (because of a RAM error or a kernel bug), the notifications stop and the hardware watchdog resets the system after the timeout occurs, thus causing a reboot.

==Configuration ==

===Kernel configuration===
By default, the Watchdog Timer (WDT<ref name="wdt user api"/>) framework is activated in STMicroelectronics deliveries. If a specific configuration is needed, this section indicates how the WDT framework can be activated/inactivated in the kernel.

The WDT framework can be activated in the kernel configuration via Linux<sup>&reg;</sup> Menuconfig tool.
Follow the steps below to configure the kernel via Menuconfig:<pre>

[*] Watchdog Timer Support  --->
    [*] Disable watchdog shutdown on close
    [*] Update boot-enabled watchdog until userspace takes over<*>   STM32 Independent WatchDoG (IWDG) support</pre>


===Device tree configuration===
DT configuration can be done thanks to STM32CubeMX.

Please refer to the [[IWDG_device_tree_configuration| IWDG device tree configuration]].

==How to use the Watchdog framework==
The Watchdog framework can be used by the userspace application:

* The kernel provides a simple code example<ref>{{CodeSource | Linux kernel | samples/watchdog/watchdog-simple.c | user example}}</ref>

* Busybox provides a watchdog daemon<ref>[https://busybox.net/downloads/BusyBox.html busybox commands]</ref>

* Systemd provides a watchdog support<ref>[http://0pointer.de/blog/projects/watchdog.html systemd watchdog configuration]</ref>


==How to trace and debug the framework==
===How to trace===
For details on dynamic trace usage, refer to How to use the kernel dynamic debug.
 {{Board$}} echo "file drivers/watchdog/* +p" > /sys/kernel/debug/dynamic_debug/control

==Source code location==
*{{CodeSource | Linux kernel | drivers/watchdog/watchdog_core.c | WatchdogAPI core}}
*{{CodeSource | Linux kernel | include/uapi/linux/watchdog.h | WatchdogAPI interface}}
*{{CodeSource | Linux kernel | drivers/watchdog/stm32_iwdg.c | stm32 iwdg drivers}}

==References==<references />

<noinclude>

[[Category:Watchdog|0]]
{{PublicationRequestId | 10344 | 2019-01-17 | AnneJ}}
{{ArticleBasedOnModel | Framework overview article model}}</noinclude>
Line 1: Line 1:
−
<noinclude>
  
−
{{ArticleBasedOnModel | [[Framework overview article model]]}}
  
−
{{ArticleMainWriter | LudovicB}}
  
−
{{ArticleApprovedVersion | LudovicB | AlexandreT (PASSED 901) | No previous approved version | AnneJ - 17Jan'19 - 10344 | 17Jan'19}}
  
−
[[Category:Watchdog|0]]
  
−
</noinclude>
  
−
 
−
'''SUMMARY '''<br>
  
 
This article provides information on the Linux<sup>&reg;</sup> WDT (Watchdog Timer) framework.<br/>
  
This article provides information on the Linux<sup>&reg;</sup> WDT (Watchdog Timer) framework.<br/>
 
It explains how to activate the WDT interface and, based on examples, how to use it.<br />
  
It explains how to activate the WDT interface and, based on examples, how to use it.<br />
Line 68: Line 60:
 
==References==
  
==References==
 
<references />
  
<references />
  +
  +
<noinclude>
  +
[[Category:Watchdog|0]]
  +
{{PublicationRequestId | 10344 | 2019-01-17 | AnneJ}}
  +
{{ArticleBasedOnModel | Framework overview article model}}
  +
</noinclude>
Retrieved from "https://wiki.st.com/stm32mpu-ecosystem-v1/index.php?title=Watchdog_overview&oldid=67198"