From 47c6c96284501c46b8caf2b69b3ca090f008e300 Mon Sep 17 00:00:00 2001 From: Tim Gover Date: Wed, 23 Jul 2025 15:32:11 +0100 Subject: [PATCH 1/3] boot-watchdog: Describe the new boot-watchdog for Pi4 / Pi5 --- .../raspberry-pi/eeprom-bootloader.adoc | 23 +++++++++++++++++++ 1 file changed, 23 insertions(+) diff --git a/documentation/asciidoc/computers/raspberry-pi/eeprom-bootloader.adoc b/documentation/asciidoc/computers/raspberry-pi/eeprom-bootloader.adoc index bfa9560982..7e4145696c 100644 --- a/documentation/asciidoc/computers/raspberry-pi/eeprom-bootloader.adoc +++ b/documentation/asciidoc/computers/raspberry-pi/eeprom-bootloader.adoc @@ -146,6 +146,29 @@ The `BOOT_ORDER` property defines the sequence for the different boot modes. It | Try NVMe first, followed by USB-MSD then repeat |=== + +[[BOOT_WATCHDOG_TIMEOUT]] +==== `BOOT_WATCHDOG_TIMEOUT` + +If set to a non-zero value (in seconds), enables a hardware watchdog timer in the bootloader. If the OS is not started within the specified time, the watchdog will reset the system. + +The bootloader watchdog is automatically cancelled as soon as the ARM CPU is started. It does **not** monitor the OS after the handover from the bootloader. + +This is useful for unattended or remote systems to ensure recovery from failed boots (e.g., if the OS never loads). + +Default: `0` (disabled) + +[[BOOT_WATCHDOG_PARTITION]] +==== `BOOT_WATCHDOG_PARTITION` + +If the bootloader watchdog triggers, this property specifies the partition number to boot from after the reset. This allows for automatic failover to a recovery or alternate partition. + +If not set, the bootloader will retry the default partition (0). + +You can use this in conjunction with the xref:config_txt.adoc#the-expression-filter[expression filter] to apply different settings or select a different boot flow when the watchdog triggers a reboot to a specific partition. + +Default: `0` + [[MAX_RESTARTS]] ==== `MAX_RESTARTS` From 25cf0f78b43594f369c99ac1885f34a778a9bbb3 Mon Sep 17 00:00:00 2001 From: Tim Gover Date: Wed, 23 Jul 2025 15:43:16 +0100 Subject: [PATCH 2/3] watchdog: Describe the new kernel_watchdog parameters --- .../asciidoc/computers/config_txt/boot.adoc | 29 +++++++++++++++++++ 1 file changed, 29 insertions(+) diff --git a/documentation/asciidoc/computers/config_txt/boot.adoc b/documentation/asciidoc/computers/config_txt/boot.adoc index b87ef830d3..d26b80d1c0 100644 --- a/documentation/asciidoc/computers/config_txt/boot.adoc +++ b/documentation/asciidoc/computers/config_txt/boot.adoc @@ -208,6 +208,35 @@ This property could be used to debug different xref:raspberry-pi.adoc#BOOT_ORDER Default: `` +[[kernel_watchdog_timeout]] +==== `kernel_watchdog_timeout` + +If set to a non-zero value (in seconds), this property enables a hardware watchdog timer that is handed over to the operating system (OS) at boot. If the OS does not regularly "kick" or reset the watchdog, the system will be reset after the specified timeout. + +This property sets the `systemd` `watchdog.open_timeout` parameter, which controls how long the OS has to initialize and start servicing the watchdog. The value is passed to the OS via the kernel command line. For ongoing operation, the OS must also regularly reset the watchdog, typically controlled by the `RuntimeWatchdogSec` parameter in `systemd`. For more information, see https://www.freedesktop.org/software/systemd/man/systemd-system.conf.html#RuntimeWatchdogSec=[systemd watchdog documentation]. + +[NOTE] +==== +On Raspberry Pi OS Bookworm and earlier, the `RuntimeWatchdogSec` parameter is **not enabled by default** and this setting must be configured first in `/etc/systemd/system.conf` before the firmware kernel watchdog can be used. + +If both `BOOT_WATCHDOG_TIMEOUT` (EEPROM/bootloader setting, only supported on Raspberry Pi 4 and 5) and `kernel_watchdog_timeout` are set, the bootloader will seamlessly hand over from the bootloader watchdog to the kernel watchdog at the point the OS is started. This provides continuous watchdog coverage from power-on through to OS runtime. + +It is preferred to use `kernel_watchdog_timeout` rather than `dtparam=watchdog` because `kernel_watchdog_timeout` explicitly sets the `open_timeout` parameter, ensuring the watchdog is active until systemd takes over. +==== + +This is useful for ensuring that the system can recover from OS hangs or crashes after the boot process has completed. + +Default: `0` (disabled) + +[[kernel_watchdog_partition]] +==== `kernel_watchdog_partition` + +If the kernel watchdog triggers (i.e., the OS fails to reset the watchdog within the timeout), this property specifies the partition number to boot from after the reset. This allows for automatic failover to a recovery or alternate partition. + +You can use this in conjunction with the xref:config_txt.adoc#the-expression-filter[expression filter] to apply different settings or select a different boot flow when the watchdog triggers a reboot to a specific partition. + +Default: `0` (default partition) + [[eeprom_write_protect]] ==== `eeprom_write_protect` From dfdf01f45103f51ce3baaa2afddf27c7a8c21078 Mon Sep 17 00:00:00 2001 From: Tim Gover Date: Thu, 24 Jul 2025 11:13:32 +0100 Subject: [PATCH 3/3] watchdog: Link to the PARTITION EEPROM property Describe how to remap partition numbers --- documentation/asciidoc/computers/config_txt/boot.adoc | 4 +++- .../asciidoc/computers/raspberry-pi/eeprom-bootloader.adoc | 4 +++- 2 files changed, 6 insertions(+), 2 deletions(-) diff --git a/documentation/asciidoc/computers/config_txt/boot.adoc b/documentation/asciidoc/computers/config_txt/boot.adoc index d26b80d1c0..50aca0aa5d 100644 --- a/documentation/asciidoc/computers/config_txt/boot.adoc +++ b/documentation/asciidoc/computers/config_txt/boot.adoc @@ -231,10 +231,12 @@ Default: `0` (disabled) [[kernel_watchdog_partition]] ==== `kernel_watchdog_partition` -If the kernel watchdog triggers (i.e., the OS fails to reset the watchdog within the timeout), this property specifies the partition number to boot from after the reset. This allows for automatic failover to a recovery or alternate partition. +If the kernel watchdog triggers (i.e. the OS fails to reset the watchdog within the timeout), this property specifies the partition number to boot from after the reset. This allows for automatic failover to a recovery or alternate partition. You can use this in conjunction with the xref:config_txt.adoc#the-expression-filter[expression filter] to apply different settings or select a different boot flow when the watchdog triggers a reboot to a specific partition. +See also the xref:raspberry-pi.adoc#PARTITION[PARTITION] property for more information about how to use high partition numbers to detect a watchdog trigger. + Default: `0` (default partition) diff --git a/documentation/asciidoc/computers/raspberry-pi/eeprom-bootloader.adoc b/documentation/asciidoc/computers/raspberry-pi/eeprom-bootloader.adoc index 7e4145696c..29ff4f1726 100644 --- a/documentation/asciidoc/computers/raspberry-pi/eeprom-bootloader.adoc +++ b/documentation/asciidoc/computers/raspberry-pi/eeprom-bootloader.adoc @@ -154,7 +154,7 @@ If set to a non-zero value (in seconds), enables a hardware watchdog timer in th The bootloader watchdog is automatically cancelled as soon as the ARM CPU is started. It does **not** monitor the OS after the handover from the bootloader. -This is useful for unattended or remote systems to ensure recovery from failed boots (e.g., if the OS never loads). +This is useful for unattended or remote systems to ensure recovery from failed boots (e.g. if the OS never loads). Default: `0` (disabled) @@ -167,6 +167,8 @@ If not set, the bootloader will retry the default partition (0). You can use this in conjunction with the xref:config_txt.adoc#the-expression-filter[expression filter] to apply different settings or select a different boot flow when the watchdog triggers a reboot to a specific partition. +See also the xref:raspberry-pi.adoc#PARTITION[PARTITION] property for more information about how to use high partition numbers to detect a watchdog trigger. + Default: `0` [[MAX_RESTARTS]]