versal: support the system watchdog timer (WWDT)

Author: dgarske

.github/workflows/test-configs.yml

@@ -1345,6 +1345,23 @@ jobs:
       config-file: ./config/examples/versal_vmk180_sdcard.config
       make-args: DISK_FS=both
 
+  # Default instance (FPD) and the stop-before-the-OS path
+  versal_vmk180_wdt_fpd_test:
+    uses: ./.github/workflows/test-build-aarch64.yml
+    with:
+      arch: aarch64
+      config-file: ./config/examples/versal_vmk180.config
+      make-args: WATCHDOG=1 WATCHDOG_TIMEOUT_MS=30000
+
+  # LPD instance, and the only build with both the WATCHDOG_HANDOFF branch of
+  # hal_prepare_boot() and the SDHCI refresh hook (src/sdhci.c is SD-only)
+  versal_vmk180_sdcard_wdt_lpd_handoff_test:
+    uses: ./.github/workflows/test-build-aarch64.yml
+    with:
+      arch: aarch64
+      config-file: ./config/examples/versal_vmk180_sdcard.config
+      make-args: WATCHDOG=1 WATCHDOG_HANDOFF=1 WATCHDOG_BASE=0xFF120000
+
   sim_wolfhsm_test:
     uses: ./.github/workflows/test-build.yml
     with:

config/examples/versal_vmk180.config

@@ -56,6 +56,17 @@ NO_XIP=1
 #BOOT_EL1=1
 #BOOT_EL2=1
 
+# System watchdog (SWDT/WWDT)
+# WATCHDOG=1 has wolfBoot service the watchdog through its boot and stop it
+# before Linux, as U-Boot does. WATCHDOG_BASE selects the instance
+# (0xFD4D0000 FPD / 0xFF120000 LPD), and the design's PDI must release that
+# block's reset. WATCHDOG_HANDOFF=1 leaves it armed for the OS instead.
+#WATCHDOG=1
+#WATCHDOG_TIMEOUT_MS=30000
+#WATCHDOG_BASE=0xFD4D0000
+#WATCHDOG_CLK_HZ=150000000
+#WATCHDOG_HANDOFF=1
+
 # ELF loading support
 ELF?=1
 

config/examples/versal_vmk180_sdcard.config

@@ -145,6 +145,17 @@ WOLFBOOT_SECTOR_SIZE=0x1000
 # ============================================================================
 CFLAGS_EXTRA+=-DDEBUG_UART_NUM=0
 
+# System watchdog (SWDT/WWDT)
+# WATCHDOG=1 has wolfBoot service the watchdog through its boot and stop it
+# before Linux, as U-Boot does. WATCHDOG_BASE selects the instance
+# (0xFD4D0000 FPD / 0xFF120000 LPD), and the design's PDI must release that
+# block's reset. WATCHDOG_HANDOFF=1 leaves it armed for the OS instead.
+#WATCHDOG=1
+#WATCHDOG_TIMEOUT_MS=30000
+#WATCHDOG_BASE=0xFD4D0000
+#WATCHDOG_CLK_HZ=150000000
+#WATCHDOG_HANDOFF=1
+
 # ============================================================================
 # Optional Debug Options (uncomment to enable)
 # ============================================================================

docs/Targets.md

@@ -5290,6 +5290,22 @@ Key configuration options in `config/examples/versal_vmk180.config`:
 - `EXT_FLASH=1` - External flash support
 - `ELF=1` - ELF loading support
 
+### System Watchdog (SWDT/WWDT)
+
+Versal has two system watchdog timers: `LPD_SWDT` at `0xFF120000` (wired for the RPU) and `FPD_SWDT` at `0xFD4D0000` (for the APU). `WATCHDOG=1` has wolfBoot reprogram, refresh and settle one of them, for a design that arms it from its `.cdo` so a hung bootloader resets the board.
+
+| Option | Default | Meaning |
+|--------|---------|---------|
+| `WATCHDOG` | `0` | Manage the watchdog through wolfBoot's boot and settle it before the OS. |
+| `WATCHDOG_TIMEOUT_MS` | `30000` | Timeout to program. It has to exceed a signature verify, which is one call with no loop to refresh from. |
+| `WATCHDOG_BASE` | `0xFD4D0000` | Instance to use; `0xFF120000` is the LPD one. |
+| `WATCHDOG_CLK_HZ` | `150000000` | Counting clock, `FPD_LSBUS` or `LPD_LSBUS`. The default is the rate the VMK180 reference design uses, not the 100 MHz its device tree advertises; below the real rate the window shortens in proportion, so a design with a different lsbus divider must set this. |
+| `WATCHDOG_HANDOFF` | `0` | Leave it armed with a full window for an OS that will take it over, instead of stopping it. The OS watchdog node then has to be enabled and its driver servicing it. |
+
+The default stops the watchdog in `hal_prepare_boot()`, as U-Boot does before it boots Linux. wolfBoot reprograms the timer with no closed (first) window so that its own refreshes - from the hash, decompression, flash and disk loops via `wolfBoot_watchdog_feed()` - are always legal. A refresh or a disable is only honored while the open (second) window is current, elsewhere the hardware records a bad event and ignores a disable, so both wait for that window and report rather than assume. Window and generic mode are both handled and a generic-mode watchdog stays generic; Q&A mode is reported and left alone.
+
+The PDI must release the block's reset and clock (`CRF.RST_FPD_SWDT` at `0xFD1A0314`, `CRL.RST_LPD_SWDT` at `0xFF5E034C`); wolfBoot makes no EEMI calls. Without `WATCHDOG` it neither reads nor writes the block, since a read of one still in reset can abort at EL2 - so a CDO-armed watchdog is only handled in a `WATCHDOG=1` build.
+
 ### QSPI Boot (default)
 
 Use `config/examples/versal_vmk180.config`.

docs/compile.md

@@ -538,6 +538,10 @@ iterating over a range of flash sectors and erasing them one at a time. Setting
 single HAL flash erase invocation with a larger erase length versus the iterative approach. On targets where multi-sector erases are more performant, this option can be used to dramatically speed up the
 image swap procedure.
 
+### Hardware watchdog
+
+`WATCHDOG=1` tells the HAL to manage a hardware watchdog across wolfBoot's own boot, with `WATCHDOG_TIMEOUT_MS` as the timeout it programs. wolfBoot calls `wolfBoot_watchdog_feed()` from its hash, decompression, flash copy/erase and disk read loops; the weak default in `src/libwolfboot.c` is a no-op that a HAL overrides, and without `WATCHDOG` the calls compile out. A signature verify is one blocking call with no loop to refresh from, so the timeout has to exceed it. Which watchdog a target drives, and what it does with it at the handoff, is per-HAL: see `hal/versal.c`, `hal/mpfs250.c`, `hal/s32k1xx.c`, `hal/renesas-rx.c` and the per-target options in [Targets.md](Targets.md).
+
 ### Building with the ARM Compiler for Embedded (armclang)
 
 wolfBoot can be built with the [ARM Compiler for Embedded](https://developer.arm.com/Tools%20and%20Software/Arm%20Compiler%20for%20Embedded)

hal/versal.c

@@ -270,6 +270,146 @@ uint64_t hal_get_timer_us(void)
 }
 
 
+/* ============================================================================
+ * System Watchdog Timer (WWDT)
+ * ============================================================================
+ * Only touched under WATCHDOG=1: reading a block a PDI left in reset can
+ * abort at EL2. A restart or a disable is honored only in the open (second)
+ * window, so both wait for it; see docs/Targets.md.
+ */
+#ifdef WATCHDOG
+
+static int versal_wwdt_wait_open(void)
+{
+    uint64_t deadline;
+
+    deadline = timer_deadline_us((uint32_t)(WWDT_OPEN_WAIT_US > 0xFFFFFFFFULL ?
+        0xFFFFFFFFULL : WWDT_OPEN_WAIT_US));
+    while ((WWDT_ESR & WWDT_ESR_WSW) == 0) {
+        if (timer_expired(deadline)) {
+            return -1;
+        }
+    }
+    return 0;
+}
+
+static int versal_wwdt_stop(void)
+{
+    uint32_t esr;
+
+    if (WWDT_GWCSR & WWDT_GWCSR_GWEN) {
+        WWDT_GWCSR = WWDT_GWCSR & ~WWDT_GWCSR_GWEN;
+        dsb();
+        return ((WWDT_GWCSR & WWDT_GWCSR_GWEN) == 0) ? 0 : -1;
+    }
+    if ((WWDT_ESR & WWDT_ESR_WEN) == 0) {
+        return 0;
+    }
+    if (WWDT_MWR & WWDT_MWR_AEN) {
+        wolfBoot_printf("WDT: always-enabled, cannot be disabled\n");
+        return -1;
+    }
+    /* WDP guards WEN, so it has to come down first */
+    if (WWDT_FCR & WWDT_FCR_WDP) {
+        WWDT_MWR = WWDT_MWR_MWC;
+        dsb();
+        WWDT_FCR = WWDT_FCR & ~WWDT_FCR_WDP;
+        dsb();
+    }
+    if (versal_wwdt_wait_open() != 0) {
+        wolfBoot_printf("WDT: open window never arrived, still enabled\n");
+        return -1;
+    }
+
+    WWDT_MWR = WWDT_MWR_MWC;
+    dsb();
+    esr = WWDT_ESR;
+    esr &= ~(WWDT_ESR_WEN | WWDT_ESR_WSW);
+    WWDT_ESR = esr;
+    dsb();
+
+    if (WWDT_ESR & WWDT_ESR_WEN) {
+        wolfBoot_printf("WDT: disable rejected\n");
+        return -1;
+    }
+    return 0;
+}
+
+static int versal_wwdt_arm(uint32_t timeout_ms)
+{
+    uint64_t ticks;
+    uint32_t count;
+
+    ticks = (uint64_t)timeout_ms * (WATCHDOG_CLK_HZ / 1000ULL);
+    count = (ticks > WWDT_COUNT_MAX) ? (uint32_t)WWDT_COUNT_MAX
+                                     : (uint32_t)ticks;
+
+    /* Q&A mode expects a token handshake wolfBoot does not take part in */
+    if (WWDT_FCR & WWDT_FCR_WM) {
+        wolfBoot_printf("WDT: Q&A mode in use, leaving it alone\n");
+        return -1;
+    }
+    /* Generic mode stays generic: widen and refresh it where it is */
+    if (WWDT_GWCSR & WWDT_GWCSR_GWEN) {
+        WWDT_GWOR = count;
+        WWDT_GWRR = WWDT_GWRR_REFRESH;
+        dsb();
+        return 0;
+    }
+    /* Windows are configured while disabled, so bring a running one down */
+    if (versal_wwdt_stop() != 0) {
+        return -1;
+    }
+
+    WWDT_MWR = WWDT_MWR_MWC;
+    dsb();
+    WWDT_FWR = 0;
+    WWDT_SWR = count;
+    WWDT_FCR = 0;
+    dsb();
+    /* Enabling can auto-clear MWC, so reopen the space first */
+    WWDT_MWR = WWDT_MWR_MWC;
+    dsb();
+    WWDT_ESR = WWDT_ESR | WWDT_ESR_WEN;
+    dsb();
+
+    if ((WWDT_ESR & WWDT_ESR_WEN) == 0) {
+        wolfBoot_printf("WDT: enable did not take, is the block in reset?\n");
+        return -1;
+    }
+    return 0;
+}
+
+/* Overrides the weak no-op in src/libwolfboot.c */
+void RAMFUNCTION wolfBoot_watchdog_feed(void)
+{
+    if (WWDT_GWCSR & WWDT_GWCSR_GWEN) {
+        WWDT_GWRR = WWDT_GWRR_REFRESH;
+        dsb();
+        return;
+    }
+    /* A restart in the closed window is a bad event, and Q&A mode expects a
+     * token handshake instead of a WSW write */
+    if ((WWDT_ESR & (WWDT_ESR_WEN | WWDT_ESR_WSW))
+            != (WWDT_ESR_WEN | WWDT_ESR_WSW)
+            || (WWDT_FCR & WWDT_FCR_WM)) {
+        return;
+    }
+    WWDT_MWR = WWDT_MWR_MWC;
+    dsb();
+    WWDT_ESR = WWDT_ESR | WWDT_ESR_WSW;
+    dsb();
+}
+
+/* Overrides the weak no-op in src/sdhci.c */
+void sdhci_platform_wdt_pet(void)
+{
+    wolfBoot_watchdog_feed();
+}
+
+#endif /* WATCHDOG */
+
+
 /* ============================================================================
  * QSPI Flash Driver (GQSPI)
  * ============================================================================
@@ -486,8 +626,9 @@ static int qspi_dma_wait(void)
 {
     uint32_t timeout = GQSPIDMA_TIMEOUT_TRIES;
 
-    while (!(GQSPIDMA_ISR & GQSPIDMA_ISR_DONE) && --timeout)
-        ;
+    while (!(GQSPIDMA_ISR & GQSPIDMA_ISR_DONE) && --timeout) {
+        wolfBoot_watchdog_feed();
+    }
 
     if (timeout == 0) {
         QSPI_DEBUG_PRINTF("QSPI: DMA timeout\n");
@@ -1185,6 +1326,16 @@ void hal_init(void)
 #endif
 #endif
 
+#ifdef WATCHDOG
+    /* ESR[LBE] names the last bad event, which is how a mis-fed or
+     * already-expired watchdog announces itself */
+    wolfBoot_printf("WDT: base 0x%x ESR 0x%x FCR 0x%x\n",
+        (uint32_t)WATCHDOG_BASE, (uint32_t)WWDT_ESR, (uint32_t)WWDT_FCR);
+    if (versal_wwdt_arm(WATCHDOG_TIMEOUT_MS) == 0) {
+        wolfBoot_printf("WDT: armed, %d ms\n", (int)WATCHDOG_TIMEOUT_MS);
+    }
+#endif
+
 #ifdef EXT_FLASH
     qspi_init();
 #endif
@@ -1197,6 +1348,19 @@ void hal_prepare_boot(void)
     qspi_exit_4byte_addr(&qspiDev);
 #endif
 
+#ifdef WATCHDOG
+#ifdef WATCHDOG_HANDOFF
+    /* Full window ahead of the OS, whose driver takes over from here. The
+     * arm can have failed, so report the state rather than assert it. */
+    wolfBoot_watchdog_feed();
+    wolfBoot_printf("WDT: handed over, ESR 0x%x\n", (uint32_t)WWDT_ESR);
+#else
+    if (versal_wwdt_stop() == 0) {
+        wolfBoot_printf("WDT: stopped\n");
+    }
+#endif
+#endif
+
     /* Flush any pending UART output (with timeout) */
 #ifdef DEBUG_UART
     {

hal/versal.h

@@ -592,6 +592,80 @@
 #define VERSAL_SD1_BASE         0xF1050000UL
 
 
+/* ============================================================================
+ * System Watchdog Timer (SWDT, also called WWDT)
+ * ============================================================================
+ * Register set per AM011 Table 141. LPD is wired for the RPU, FPD for the
+ * APU; the design's PDI must release the block's reset and clock.
+ */
+#define VERSAL_WWDT_LPD_BASE    0xFF120000UL
+#define VERSAL_WWDT_FPD_BASE    0xFD4D0000UL
+
+#ifndef WATCHDOG_BASE
+#define WATCHDOG_BASE           VERSAL_WWDT_FPD_BASE
+#endif
+#ifndef WATCHDOG_TIMEOUT_MS
+#define WATCHDOG_TIMEOUT_MS     30000U
+#endif
+/* FPD_LSBUS or LPD_LSBUS (AM011 Table 136). The default is what the VMK180
+ * reference design clocks them at, not the 100 MHz its DTB advertises; a
+ * design with a different lsbus divider must say so, since a value below the
+ * real rate shortens the window in proportion. */
+#ifndef WATCHDOG_CLK_HZ
+#define WATCHDOG_CLK_HZ         150000000UL
+#endif
+
+/* One configured period plus slack, as the bound on a wait for the open
+ * window. 64-bit so a large timeout cannot wrap; the caller clamps. */
+#define WWDT_OPEN_WAIT_US \
+    ((((uint64_t)WATCHDOG_TIMEOUT_MS) * 1000ULL) + 1000ULL)
+
+/* Window timer registers, then the generic timer's separate page */
+#define WWDT_MWR_OFFSET         0x0000
+#define WWDT_ESR_OFFSET         0x0004
+#define WWDT_FCR_OFFSET         0x0008
+#define WWDT_FWR_OFFSET         0x000C
+#define WWDT_SWR_OFFSET         0x0010
+#define WWDT_GWRR_OFFSET        0x1000
+#define WWDT_GWCSR_OFFSET       0x2000
+#define WWDT_GWOR_OFFSET        0x2008
+
+#define WWDT_REG(offset) \
+    (*((volatile uint32_t*)(WATCHDOG_BASE + (offset))))
+#define WWDT_MWR                WWDT_REG(WWDT_MWR_OFFSET)
+#define WWDT_ESR                WWDT_REG(WWDT_ESR_OFFSET)
+#define WWDT_FCR                WWDT_REG(WWDT_FCR_OFFSET)
+#define WWDT_FWR                WWDT_REG(WWDT_FWR_OFFSET)
+#define WWDT_SWR                WWDT_REG(WWDT_SWR_OFFSET)
+#define WWDT_GWRR               WWDT_REG(WWDT_GWRR_OFFSET)
+#define WWDT_GWCSR              WWDT_REG(WWDT_GWCSR_OFFSET)
+#define WWDT_GWOR               WWDT_REG(WWDT_GWOR_OFFSET)
+
+/* MWC opens the window register space for writing; AEN makes the watchdog
+ * undisableable until the block is reset. */
+#define WWDT_MWR_MWC            (1UL << 0)
+#define WWDT_MWR_AEN            (1UL << 1)
+
+/* WSW reads 1 while the open (second) window is current and writing it back
+ * restarts the timer. WINT and WRP are W1C; FCV and LBE record bad events. */
+#define WWDT_ESR_WEN            (1UL << 0)
+#define WWDT_ESR_WSW            (1UL << 8)
+#define WWDT_ESR_WINT           (1UL << 16)
+#define WWDT_ESR_WRP            (1UL << 17)
+#define WWDT_ESR_FCV_SHIFT      20
+#define WWDT_ESR_FCV_MASK       (7UL << WWDT_ESR_FCV_SHIFT)
+#define WWDT_ESR_LBE_SHIFT      24
+#define WWDT_ESR_LBE_MASK       (7UL << WWDT_ESR_LBE_SHIFT)
+
+/* WDP guards WEN against being cleared; WM selects Q&A over basic mode */
+#define WWDT_FCR_WDP            (1UL << 0)
+#define WWDT_FCR_WM             (1UL << 1)
+
+#define WWDT_GWRR_REFRESH       (1UL << 0)
+#define WWDT_GWCSR_GWEN         (1UL << 0)
+#define WWDT_COUNT_MAX          0xFFFFFFFFUL
+
+
 /* ============================================================================
  * Helper Functions (C code only)
  * ============================================================================