watchdog.h

Go to the documentation of this file.

#pragma once

 
#include "fl/stl/stdint.h"
#include "fl/stl/noexcept.h"
#include "fl/stl/compiler_control.h"   // FL_NO_RETURN
#include "fl/stl/span.h"
#include "fl/stl/function.h"
#include "fl/stl/string_view.h"        // for resetCauseName() return type
 
namespace fl {

enum class ResetCause : fl::u8 {
    UNKNOWN = 0,
    POWER_ON,
    BROWNOUT,
    EXTERNAL_PIN,
    WATCHDOG,
    SOFTWARE,
    LOCKUP,
    DEBUGGER,
    PANIC,
};

inline fl::string_view resetCauseName(ResetCause c) FL_NO_EXCEPT {
    switch (c) {
        case ResetCause::POWER_ON:     return fl::string_view("POWER_ON");
        case ResetCause::BROWNOUT:     return fl::string_view("BROWNOUT");
        case ResetCause::EXTERNAL_PIN: return fl::string_view("EXTERNAL_PIN");
        case ResetCause::WATCHDOG:     return fl::string_view("WATCHDOG");
        case ResetCause::SOFTWARE:     return fl::string_view("SOFTWARE");
        case ResetCause::LOCKUP:       return fl::string_view("LOCKUP");
        case ResetCause::DEBUGGER:     return fl::string_view("DEBUGGER");
        case ResetCause::PANIC:        return fl::string_view("PANIC");
        case ResetCause::UNKNOWN:
        default:                       return fl::string_view("UNKNOWN");
    }
}

struct ResetInfo {
    ResetCause cause;          
    fl::u8     subcauseId;     
    fl::u32    rawRegister;    

    fl::string_view causeName() const FL_NO_EXCEPT { return resetCauseName(cause); }

    fl::string_view subcauseName() const FL_NO_EXCEPT;

    fl::size describe(fl::span<char> out, bool verbose = false) const FL_NO_EXCEPT;
};

using WatchdogTimeoutCallback = void(*)(void* user_data);

struct WatchdogCrashReport {
    bool        valid;
    fl::u32     pc;
    fl::u32     lr;
    fl::u32     psr;
    fl::u32     fault_status;
    fl::u32     fault_address;
    const char* fault_type;
};

class Watchdog {
public:
    // Singleton accessor — DECLARATION ONLY. The function-local `static
    // Watchdog` must live in a `.cpp.hpp` / `.impl.hpp` TU (one definition,
    // one guard variable) so the Teensy 3.x `__cxa_guard` ABI conflict does
    // not pull a guarded singleton path into every TU that includes
    // FastLED.h. See `agents/docs/cpp-standards.md` → "Header rules:
    // function-local statics with non-trivial constructors are forbidden in
    // `src/**/*.h`."
    static Watchdog& instance() FL_NO_EXCEPT;
 
    // ========== Tier 0 — universal ==========
 
    void       begin(fl::u32 timeout_ms) FL_NO_EXCEPT;
    void       feed() FL_NO_EXCEPT;
    void       disable() FL_NO_EXCEPT;
 
    ResetCause lastResetCause() const FL_NO_EXCEPT;
    bool       lastResetWasWatchdog() const FL_NO_EXCEPT;

    ResetInfo lastResetInfo() const FL_NO_EXCEPT;
 
    fl::u8     persistRead(fl::size idx) const FL_NO_EXCEPT;
    void       persistWrite(fl::size idx, fl::u8 v) FL_NO_EXCEPT;
 
    fl::u16    consecutiveCrashCount() const FL_NO_EXCEPT;
    void       markCleanShutdown() FL_NO_EXCEPT;
    bool       isInSafeMode() const FL_NO_EXCEPT;
    fl::u16    safeModeThreshold() const FL_NO_EXCEPT;
    void       setSafeModeThreshold(fl::u16 threshold) FL_NO_EXCEPT;

    fl::u16 bootloaderEscapeThreshold() const FL_NO_EXCEPT;

    void setBootloaderEscapeThreshold(fl::u16 threshold) FL_NO_EXCEPT;

    bool shouldEscapeToBootloader() const FL_NO_EXCEPT;

    bool escapeToBootloaderIfLooping() FL_NO_EXCEPT;

    fl::u32 bootGuardCount() const FL_NO_EXCEPT;

    void markBootHealthy() FL_NO_EXCEPT;
 
    FL_NO_RETURN void reboot() FL_NO_EXCEPT;
 
    // ========== Tier 1 — most platforms ==========
 
    bool       onTimeout(WatchdogTimeoutCallback cb, void* user_data = nullptr) FL_NO_EXCEPT;
    bool       onTimeout(fl::function<void()> cb) FL_NO_EXCEPT;
    bool       setPauseOnDebug(bool pause) FL_NO_EXCEPT;
    bool       writeCrashLog(fl::span<const fl::u8> payload) FL_NO_EXCEPT;
    fl::size   readCrashLog(fl::span<fl::u8> out) const FL_NO_EXCEPT;
    bool       rebootIntoBootloader() FL_NO_EXCEPT;
 
    // ========== Tier 2 — advanced platforms ==========
 
    bool                setWindow(fl::u32 window_min_ms, fl::u32 window_max_ms) FL_NO_EXCEPT;
    bool                hasCrashReport() const FL_NO_EXCEPT;
    WatchdogCrashReport readCrashReport() const FL_NO_EXCEPT;
    void                clearCrashReport() FL_NO_EXCEPT;
 
private:
    Watchdog() FL_NO_EXCEPT = default;
    ~Watchdog() FL_NO_EXCEPT = default;
    Watchdog(const Watchdog&) FL_NO_EXCEPT = delete;
    Watchdog& operator=(const Watchdog&) FL_NO_EXCEPT = delete;
 
    fl::u16 mSafeModeThreshold = 2;
    fl::u16 mBootloaderEscapeThreshold = 0;   // 0 = escape disabled
};
 
namespace platforms {
fl::u32 watchdogBootGuardRead() FL_NO_EXCEPT;
void    watchdogBootGuardWrite(fl::u32 boots) FL_NO_EXCEPT;
void    watchdogBootGuardReleaseEarlyTimer() FL_NO_EXCEPT;
} // namespace platforms

class ScopedWatchdog {
public:
    ScopedWatchdog() FL_NO_EXCEPT : ScopedWatchdog(15000u) {}

    explicit ScopedWatchdog(fl::u32 timeout_ms) FL_NO_EXCEPT;

    ~ScopedWatchdog() FL_NO_EXCEPT;

    static int activeScopeCount() FL_NO_EXCEPT;
 
    ScopedWatchdog(const ScopedWatchdog&)            FL_NO_EXCEPT = delete;
    ScopedWatchdog& operator=(const ScopedWatchdog&) FL_NO_EXCEPT = delete;
};
 
} // namespace fl
 
// ============================================================================
// FL_WATCHDOG_AUTO(...) — the canonical zero-setup loop()-top guard.
//
// Variadic so the same macro covers both the no-argument default (15 000 ms)
// and the explicit-timeout form:
//
//   void loop() {
//       FL_WATCHDOG_AUTO();      // 15 000 ms default
//       doWork();
//   }
//
//   void loop() {
//       FL_WATCHDOG_AUTO(5000);  // 5-second timeout
//       doWork();
//   }
//
// "AUTO" because this macro does more than just feed: it lazily arms the WDT
// on first call, prints the prior-boot reset/crash diagnostic, pauses 3 s on
// a crash so the developer can read the message, and feeds the WDT on both
// construction AND destruction. Single source-line use; the macro stamps the
// local variable name from `__LINE__` so two `FL_WATCHDOG_AUTO()` on the same
// line are a compile error. Two on different lines but simultaneously alive
// (nested scopes) trigger a one-shot runtime warning — see ScopedWatchdog.
//
// Future variants stay grouped under the `FL_WATCHDOG_*` prefix:
//   FL_WATCHDOG_AUTO_QUIET / FL_WATCHDOG_AUTO_VERBOSE — log-level variants
//   FL_WATCHDOG_MANUAL                                — non-RAII setup helper
// ============================================================================
 
#define FL_WATCHDOG__CONCAT_INNER(a, b) a##b
#define FL_WATCHDOG__CONCAT(a, b)       FL_WATCHDOG__CONCAT_INNER(a, b)
#define FL_WATCHDOG_AUTO(...)                                                  \
    ::fl::ScopedWatchdog FL_WATCHDOG__CONCAT(_fl_wdt_, __LINE__) { __VA_ARGS__ }
 
// ============================================================================
// FL_WATCHDOG_* capability macros — defined by the per-platform impl.
// The noop fallback defines NONE of the boolean flags and defaults numerics to 0.
// User code may #ifdef on the boolean flags or static_assert on the numerics.
// ============================================================================
//
//   #define FL_WATCHDOG_HAS_HARDWARE          // 1 wherever a real or emulated WDT runs
//   #define FL_WATCHDOG_PERSIST_BYTES N       // small persistent buffer size, >= 8
//   #define FL_WATCHDOG_HAS_PRE_TIMEOUT_IRQ   // pre-reset callback honored at HW level
//   #define FL_WATCHDOG_HAS_WINDOW_MODE       // setWindow() honored
//   #define FL_WATCHDOG_HAS_CRASH_REPORT      // hasCrashReport()/readCrashReport() honored
//   #define FL_WATCHDOG_HAS_BOOTLOADER_REBOOT // rebootIntoBootloader() honored
//   #define FL_WATCHDOG_HAS_BOOT_GUARD        // FL_WATCHDOG_BOOT_GUARD() early hook (fl/wdt/boot_guard.h)
//   #define FL_WATCHDOG_HAS_BOOT_GUARD_STORAGE // bootGuardCount()/markBootHealthy() persist
//   #define FL_WATCHDOG_MAX_TIMEOUT_MS N      // upper bound, in ms
//
// The Tier 0 surface is always callable; Tier 1/2 methods return false on
// platforms whose impl does not honor them, so user code that checks the
// return value works portably.