What You Will Learn

• Every attribute exposed under /sys/class/watchdog/watchdogX/ and what each one means
• How to enable the sysfs interface with CONFIG_WATCHDOG_SYSFS
• What a pretimeout governor is, and how noop and panic differ
• How to read and switch governors, and read the pretimeout value, from a shell script
• How this closes out the watchdog subsystem chapter of the course

Prerequisites

This lecture builds directly on our earlier coverage of struct watchdog_device, the WDIOF_* flags, and the boot/status ioctls. If pretimeout as a concept is new to you, it was introduced when we covered the watchdog governor framework earlier in this chapter — a quick refresher there will help this lecture land faster.

Enabling the Sysfs Interface

The sysfs view of a watchdog device is gated behind the CONFIG_WATCHDOG_SYSFS kernel config option. When it’s enabled, every registered watchdog gets its own directory at /sys/class/watchdog/watchdogX/, where X is the index the kernel assigned that device — the same index used in /dev/watchdogX. This is a genuinely useful design: it means the exact same device can be driven by a C program using ioctls, or scripted entirely from the shell, without either approach knowing about the other.

The Watchdog Attribute Directory

Each watchdog’s sysfs directory exposes the following read-only or read-mostly attributes:

Notice the pattern: nearly every ioctl we’ve covered in this chapter has a direct sysfs equivalent. That is intentional — the watchdog core implements both interfaces on top of the same internal watchdog_device state, so they can never disagree with each other on a given kernel.

Reading Attributes From the Shell

Every read-only attribute is a plain text file, so inspecting a watchdog needs nothing more than cat:

$ cat /sys/class/watchdog/watchdog0/identity
ep_swwdt
$ cat /sys/class/watchdog/watchdog0/timeout
30
$ cat /sys/class/watchdog/watchdog0/state
active
$ cat /sys/class/watchdog/watchdog0/timeleft
17

This is genuinely handy for a health-check cron job or a monitoring agent that shouldn’t have to open a device node and issue ioctls just to confirm a watchdog is still counting down.

Pretimeout Governors: The Policy Layer

A pretimeout is a warning that fires shortly before the watchdog’s real timeout expires — enough advance notice to, say, dump a stack trace or flush a log before the reset actually happens. What the kernel *does* with that warning is decided by a pretimeout governor, and governors are a familiar pattern if you’ve touched other kernel subsystems: CPUFreq has governors for scaling policy, thermal has governors for cooling policy, and watchdog has governors for pretimeout policy. Each one lives in its own small driver and is selected independently per device.

Two governors ship in mainline:

• noop — does nothing beyond notifying the core; useful when user space itself wants to handle the warning (for example, by watching /dev/watchdogX for the pretimeout event).
• panic — immediately panics the kernel when the pretimeout fires, which is useful when you specifically want a full kernel panic dump captured before the hardware watchdog forces a hard reset that would otherwise erase all diagnostic context.

Checking and Selecting a Governor

You can list which governors are available for a given watchdog, read which one is active, and switch it — all without writing a single line of C:

# List available governors
$ cat /sys/class/watchdog/watchdog0/pretimeout_available_governors
noop panic

# Check the currently active governor
$ cat /sys/class/watchdog/watchdog0/pretimeout_governor
panic

# Switch to noop
$ echo -n noop > /sys/class/watchdog/watchdog0/pretimeout_governor

# Confirm the switch took effect
$ cat /sys/class/watchdog/watchdog0/pretimeout_governor
noop

# Check how many seconds before timeout the pretimeout fires
$ cat /sys/class/watchdog/watchdog0/pretimeout
10

Note the -n flag on echo — it suppresses the trailing newline. Some sysfs write handlers are strict about trailing whitespace, and it’s a good habit to carry into any sysfs scripting you do elsewhere in the kernel.

Original Demo: ep_wdt_sysfs_report.sh

Here is a small original shell script — written for this course, not lifted from any reference — that dumps a complete, readable snapshot of a watchdog device using only the sysfs interface:

#!/bin/sh
# ep_wdt_sysfs_report.sh
# Usage: ./ep_wdt_sysfs_report.sh 0
WD=/sys/class/watchdog/watchdog${1:-0}

if [ ! -d "$WD" ]; then
    echo "No such watchdog: $WD" >&2
    exit 1
fi

echo "== $WD report =="
echo "identity   : $(cat $WD/identity 2>/dev/null)"
echo "state      : $(cat $WD/state 2>/dev/null)"
echo "timeout    : $(cat $WD/timeout 2>/dev/null)s"
echo "timeleft   : $(cat $WD/timeleft 2>/dev/null)s"
echo "nowayout   : $(cat $WD/nowayout 2>/dev/null)"
echo "bootstatus : $(cat $WD/bootstatus 2>/dev/null)"

if [ -f "$WD/pretimeout_governor" ]; then
    echo "pretimeout : $(cat $WD/pretimeout 2>/dev/null)s, governor=$(cat $WD/pretimeout_governor)"
fi

Common Mistakes and Troubleshooting

• Assuming pretimeout attributes always exist — pretimeout_governor and friends only appear if the driver supports pretimeout and CONFIG_WATCHDOG_PRETIMEOUT_GOV is enabled; always check the file exists before reading it.
• Writing an unsupported governor name — the write fails with -EINVAL if the name isn’t in pretimeout_available_governors; always check that file first.
• Forgetting sysfs needs root — writes to pretimeout_governor typically require root privileges even though reads don’t.
• Racing ioctl and sysfs writers — because both interfaces share the same underlying watchdog_device, having one process ping via ioctl while another reconfigures via sysfs is safe from a data-corruption standpoint, but can be confusing operationally; pick one interface per device where you can.

Best Practices

• Use sysfs for monitoring and occasional configuration from shell scripts or udev rules; use the ioctl/device-node interface for the actual keep-alive daemon that must run continuously.
• Choose the panic pretimeout governor on boards where capturing a kernel panic dump before reset is more valuable than a graceful user-space warning.
• Always verify a written governor took effect by reading it back — sysfs write success does not always guarantee the value matches what you expect if the driver applies additional validation.

Performance and Security Considerations

Sysfs reads and writes here are cheap — single register reads or simple field assignments — so there’s no meaningful performance concern for periodic polling. The security angle is more relevant: because sysfs writes to pretimeout_governor (and to timeout, on devices that expose it) usually require root, make sure any daemon or udev rule that touches these files runs with the minimum privilege actually needed, rather than blanket root access to the whole device tree.

Wrapping Up the Watchdog Chapter

Across this chapter of the course we went from the watchdog subsystem’s core data structures, through capability flags and the full watchdog_ops callback table, registration and restart-priority handling, pretimeout and GPIO-based watchdogs, the /dev/watchdog user-space lifecycle with magic-close semantics, ioctl-based status and boot-status queries, and now the complete sysfs interface with pretimeout governors. Together these give you everything needed to both write a robust watchdog driver and correctly consume one from user space — whether you’re servicing it with a compiled daemon or a shell script running from cron.

Summary / Key Takeaways

• CONFIG_WATCHDOG_SYSFS exposes every watchdog device at /sys/class/watchdog/watchdogX/.
• Sysfs attributes mirror the ioctl interface one-for-one, backed by the same in-kernel watchdog_device state.
• Pretimeout governors decide what happens when a pretimeout warning fires — noop defers to user space, panic forces a kernel panic for diagnostics.
• Governors and the pretimeout value itself can be inspected and changed with nothing more than cat and echo.

Conclusion

The sysfs interface is often the fastest way to sanity-check a watchdog during board bring-up, long before a full user-space daemon exists to manage it. Combined with the ioctl interface covered earlier in this free embedded systems course, you now have a complete toolkit for both driving and observing Linux watchdog devices. The next chapter moves into kernel development and debugging techniques, starting with how to read a kernel panic and use kernel tracing effectively.

Frequently Asked Questions