NTP1061/src/nbwatchdog.h

/*NB_REVISION*/
 
/*NB_COPYRIGHT*/
 
/*  nbwatchdog.h
 *  Easy-to-use WDOG1 watchdog helpers for the SOMRT1061 (i.MX RT1061).
 *
 *  A watchdog is a hardware timer that resets the processor unless the
 *  application keeps restarting it ("servicing" it). Arm it once with a timeout,
 *  then service it regularly from healthy code; if the application hangs and
 *  stops servicing it, the module reboots itself.
 *
 *      WatchdogEnable(4000);   // reboot if not serviced within ~4 s
 *      ...
 *      WatchdogService();      // call comfortably more often than the timeout
 *
 *  ==========================================================================
 *  IMPORTANT -- how the reboot works on the SOMRT1061
 *  ==========================================================================
 *  A *raw* hardware watchdog timeout resets the i.MX RT1061 core through the
 *  System Reset Controller (SRC), but on the SOMRT1061 module the part does NOT
 *  cleanly reboot from that -- it HANGS and needs a power cycle. The clean,
 *  bootable reset path on this module is ForceReboot() / DoSWReset(), which
 *  drives the boot/reset GPIOs and writes the SRC->GPR magic value the
 *  bootloader needs. A bare watchdog reset skips all of that.
 *
 *  So WatchdogEnable() does not rely on the raw reset. It arms WDOG1 with a
 *  pre-timeout INTERRUPT that fires ~0.5 s before the hardware timeout, and that
 *  interrupt calls ForceReboot() -- a clean, bootable reset. "Not serviced in
 *  time" therefore means an automatic clean reboot; the raw hardware reset is
 *  only ever reached if the core is so wedged that interrupts no longer run (in
 *  which case a power cycle is the recovery anyway).
 *
 *  See ReadMe.txt for the full picture, including RSTI (reset-in) / RSTO
 *  (reset-out) and why a watchdog reboot does not reach the Ethernet PHY or
 *  HyperRAM on this module.
 */
 
#ifndef NBWATCHDOG_H
#define NBWATCHDOG_H
 
#include <stdint.h>
#include <sim.h>   // pulls in <MIMXRT1061.h> -> WDOG1, SRC
 
// ---------------------------------------------------------------------------
// Reset-cause reporting
// ---------------------------------------------------------------------------

struct WatchdogResetCause
{
    uint32_t srsr;          // raw SRC->SRSR value at capture time
    uint16_t wrsr;          // raw WDOG1->WRSR value at capture time
 
    bool powerOn;           // power-on reset          (WRSR.POR)
    bool externalPin;       // external RSTI / DoSWReset (SRSR bit 0, ipp_reset_b)
    bool watchdog1;         // raw WDOG1 timeout       (SRSR bit 4 / WRSR.TOUT)
    bool softwareReset;     // core lockup / SYSRESETREQ / WRSR.SFTW
    bool jtag;              // JTAG-initiated reset    (SRSR bit 5/6)
    bool temperature;       // temperature-sensor reset (SRSR bit 8)
};

void WatchdogCaptureResetCause();

const WatchdogResetCause &WatchdogLastReset();

void WatchdogPrintResetCause();

void WatchdogClearResetCause();
 
// ---------------------------------------------------------------------------
// WDOG1 -- the watchdog
// ---------------------------------------------------------------------------

void WatchdogEnable(uint32_t timeoutMs);

void WatchdogService();

void WatchdogReportStall(char code);

bool WatchdogIsEnabled();

uint32_t WatchdogTimeoutMs();
 
// ---------------------------------------------------------------------------
// Pre-reboot hook (hang diagnostics)
// ---------------------------------------------------------------------------

typedef void (*WatchdogPreRebootHook)(uint32_t stackedPc, uint32_t stackedLr);
void WatchdogSetPreRebootHook(WatchdogPreRebootHook hook);
 
#endif // NBWATCHDOG_H