From 8af4d65c9af6126712e6716461b54d1ce566cdae Mon Sep 17 00:00:00 2001 From: Gregory Nutt Date: Tue, 8 Feb 2022 15:12:36 -0600 Subject: [PATCH] Added comment to wdog_start Add a comment briefly explaining why one timer tick is added to the watchdog delay. This has confused a lot of people and has resulted in numerous awkward discussions and ill-informed attempts to modify the code to remove that addition. Perhaps a rather lengthy comment will reduce that confusion and put an end to this thrashing. --- sched/wdog/wd_start.c | 15 ++++++++++++++- 1 file changed, 14 insertions(+), 1 deletion(-) diff --git a/sched/wdog/wd_start.c b/sched/wdog/wd_start.c index 072d056750..f41606919c 100644 --- a/sched/wdog/wd_start.c +++ b/sched/wdog/wd_start.c @@ -204,7 +204,20 @@ int wd_start(FAR struct wdog_s *wdog, sclock_t delay, up_getpicbase(&wdog->picbase); wdog->arg = arg; - /* Calculate delay+1, forcing the delay into a range that we can handle */ + /* Calculate delay+1, forcing the delay into a range that we can handle. + * + * NOTE that one is added to the delay. This is correct and must not be + * changed: The contract for the use wdog_start is that the wdog will + * delay FOR AT LEAST as long as requested, but may delay longer due to + * variety of factors. The wdog logic has no knowledge of the the phase + * of the system timer when it is started: The next timer interrupt may + * occur immediately or may be delayed for almost a full cycle. In order + * to meet the contract requirement, the requested time is also always + * incremented by one so that the delay is always at least as long as + * requested. + * + * This is extensive documentation about this time issue elsewhere. + */ if (delay <= 0) {