drivers: watchdog: document and enforce semantics of WDT_DISABLE_AT_BOOT

[mathieuchopstm]

Fixes #86223 (hopefully).

The WDT_DISABLE_AT_BOOT Kconfig option has been interpreted as "enable the WDT if disabled" by some driver implementers, even though this is at best a hack. Document its true purpose explicitly and update all drivers to follow the now-documented semantics.

I took a conservative approach and only updated drivers which were explicitly playing the if (!IS_ENABLED(WDT_DISABLE_AT_BOOT)) { enable_myself(); } game, but maybe other drivers need to be updated too.

[mathieuchopstm]

Gentle poke at NXP folks (@decsny) because there's something that seems weird in your SoCs' CMakeLists:

zephyr/soc/nxp/kinetis/CMakeLists.txt

Line 20 in 8aba2e3

zephyr_compile_definitions_ifndef(CONFIG_WDT_DISABLE_AT_BOOT DISABLE_WDOG=1)

zephyr/soc/nxp/mcx/mcxc/CMakeLists.txt

Line 21 in 8aba2e3

zephyr_compile_definitions_ifndef(CONFIG_WDT_DISABLE_AT_BOOT DISABLE_WDOG=0)

select HAS_WDT_DISABLE_AT_BOOT may need to be added in SoC Kconfig for these targets too, I'd like review on that point.

---

I'm also wondering if WDT_DISABLE_AT_BOOT shouldn't be changed to default y since that is kinda what seems to be the expected behavior (i.e., watchdog would be opt-in rather than opt-out).

Finally, this probably needs an entry in migration guide/release notes since this will most likely break people's apps (for those who were using WDT_DISABLE_AT_BOOT=n as a de facto WDT_ENABLE_AT_BOOT=y).

[henrikbrixandersen]

I like the idea of revisiting this and unifying behaviour across drivers.

I do see a need for having the counterpart in as well (enable watchdog at boot with a given timeout), as this is a common way of ensuring that failure to fully initialise your firmware will be caught somehow (I really prefer MCUs where the watchdog is enabled at boot by hardware for this reason).

[sonarqubecloud]

Quality Gate passed

Issues
1 New issue
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[mathieuchopstm]

I like the idea of revisiting this and unifying behaviour across drivers.

I do see a need for having the counterpart in as well (enable watchdog at boot with a given timeout), as this is a common way of ensuring that failure to fully initialise your firmware will be caught somehow (I really prefer MCUs where the watchdog is enabled at boot by hardware for this reason).

I did consider this (i.e., WDT_ENABLED_AT_BOOT alternative solution in the issue linked) but it's actually much less trivial than I hoped - at least, if one wants the implementation to not be hacky (as in, relying on implementation details). For example, you are supposed to wdt_feed() using the pseudo-handle returned by wdt_install_timeout()... but how can you do that if someone else calls wdt_install_timeout()?

Today, everyone just sets WDT_DISABLED_AT_BOOT=n, gets the watchdog enabled at boot by the driver, calls wdt_feed() with whatever channel_id and everything works out anyways because most drivers ignore channel_id (e.g., because there's only one channel), but it still is a hack regardless of whether it works or not.

So we'd need something else, like maybe a /chosen/zephyr,system-watchdog and a tiny module which does the wdt_install_timeout(), wdt_setup(), wdt_feed() and exposes it through a """new""" API.

There is definitely a need for "set some Kconfig and get a watchdog setup during boot" - that's what WDT_DISABLED_AT_BOOT=n was abused for 🙂 - but I'm not super inspired about how to implement that, which is kinda why I'm trying to get attention / feedback on this topic.