U-Boot Cyclic Callbacks: Registration Does Not Guarantee a Watchdog Service Deadline

A watchdog can be registered for periodic servicing and still expire
during a long U-Boot operation. The cyclic framework is cooperative: its
callbacks run when execution reaches schedule().
Registration and a short configured interval do not create an
independent timer interrupt or a preemptive worker.

This article examines U-Boot v2025.01’s cyclic framework and
driver-model watchdog integration. It does not establish a safe watchdog
timeout for a particular board. That requires the hardware’s actual
timing contract and measured worst-case service gaps.

Trace the scheduling
opportunity

The cyclic
guide places cyclic processing inside schedule(). A
long polling loop that never calls this function can prevent registered
callbacks from running, regardless of how small their requested delays
are.

In the implementation,
registration initializes the callback structure and records its
requested delay. The next-call field starts at zero. The first eligible
scheduling pass can therefore invoke it without first waiting one full
configured interval.

Later passes compare the current time with the stored deadline. When
a callback is due, the framework sets its next deadline to the current
time plus the delay, then calls it synchronously. It does not run one
invocation for every interval missed while the main execution path was
busy.

For example, if execution returns after several nominal periods, the
callback runs once in that pass. Its next deadline is based on that
pass’s time rather than a fixed phase established at registration. This
describes the source algorithm, not a measured execution trace.

Callback time
consumes everyone else’s opportunity

Callbacks are processed in the caller’s execution context. A slow
callback delays progress to the remaining callbacks and to the code that
called schedule(). The requested interval is therefore not
an upper bound on the gap between actual invocations.

The framework measures callback CPU time and warns once when it
exceeds CONFIG_CYCLIC_MAX_CPU_TIME_US. In this version, the
warning does not disable the callback, abort it or preempt it at the
threshold. Treat the setting as a diagnostic threshold, not an execution
budget enforced by a scheduler.

A recursion guard also prevents nested cyclic processing. Calling
schedule() from inside an already running cyclic callback
does not recursively service the other cyclic callbacks. It cannot be
used to turn a long callback into a cooperative nested scheduler. The
separate legacy hardware-watchdog hook has its own placement in
schedule() and should not be confused with this
driver-model callback path.

Watchdog
start and automatic service are separate

The watchdog
uclass first calls the device’s start operation. After success, it
registers a cyclic service callback only when the relevant
CONFIG_WATCHDOG integration is enabled. The hardware can
therefore be started without this automatic servicing path.

The callback checks that the device is active and marked running
before calling wdt_reset. Its registration delay comes from
the uclass reset-period setting. A successful registration does not
prove that the main code reaches scheduling points frequently enough,
nor does the callback invocation alone prove that the driver’s reset
operation succeeded.

Keep three observations separate: the hardware was started, the
service callback ran, and the hardware accepted a refresh. They answer
different questions when a reset appears only during a slow storage or
network operation.

Qualify the
longest gap, not the average period

Instrument scheduling opportunities and actual device refreshes
around the longest intended operations. Include error and timeout paths,
because a path that waits for absent hardware can behave differently
from the normal fast path. Keep cyclic callbacks short and make long
foreground loops provide appropriate service opportunities.

Use a controlled board fixture with recovery access; changing
watchdog policy on a deployed system can cause resets or conceal
failures. No watchdog was started, stopped or serviced for this
analysis. The useful source-level conclusion is that a configured cyclic
period expresses eligibility at cooperative scheduling points, not a
guaranteed service deadline.