release: fix USB timed hibernate in 1.0.14

Author: lolren

.planning/debug/npm1300-usb-timed-hibernate.md

@@ -751,7 +751,7 @@ PMIC-controlled cold-boot path; it is not interchangeable with a returning
 | Continue after a timed idle | `delayLowPowerIdle(ms)` or normal low-power `delay(ms)` | Returns to the next statement |
 | Lowest CPU System OFF with retained RAM banks | `delaySystemOff(ms)` | Cold reset; explicitly retained `.noinit` state may survive |
 | System OFF without RAM retention | `delaySystemOffNoRetention(ms)` | Cold reset |
-| Lowest timed LM20A board sleep | `npm1300_enter_timed_hibernate_ms(ms)` | PMIC restores power and the board cold-boots |
+| Timed LM20A cold boot (lowest-current path on VBAT) | `npm1300_enter_timed_hibernate_ms(ms)` | PMIC wake on VBAT or GRTC System OFF wake on USB; both cold-reset |
 
 For reproducible measurements, power from VBAT through a PPK2/Joulescope/Otii,
 disconnect USB/VBUS, close serial/debug sessions, keep voltage and temperature
@@ -811,7 +811,7 @@ Examples:
 
 - `npm1300_charger_set_current(ma)` sets the battery charge-current target and now also updates the nPM1300 VBUS input-current limiter so the default 100 mA input limit does not throttle higher charge currents.
 - `npm1300_vbus_set_input_current_limit_ma(ma)` and `npm1300_vbus_get_input_current_limit_ma()` expose the VBUS limiter directly. This limit is the allowed USB/VBUS input draw, not the measured battery charge or discharge current.
-- `npm1300_enter_timed_hibernate_ms(ms)` programs the nPM1300 hibernate wake timer and enters PMIC hibernate mode. On XIAO nRF54LM20A this is the lowest-current timed sleep path; wake is a cold boot after the PMIC restores power. The nPM1300 requires VBUS to be absent before Ship/Hibernate entry, so this helper returns `false` while USB/VBUS is present; test it from VBAT/battery power with USB/debug disconnected.
+- `npm1300_enter_timed_hibernate_ms(ms)` provides one timed cold-boot API for either supply path. With VBUS absent it programs the nPM1300 wake timer and enters true PMIC Hibernate, the lowest-current LM20A path. With USB/VBUS present it uses nRF54 GRTC System OFF because the nPM1300 requires VBUS to be disconnected before Hibernate entry. Both paths accept 1 through `NPM1300_HIBERNATE_TIMER_MAX_MS`, normally do not return after successful entry, and restart from `setup()` on wake. Disconnect USB/debug wiring and power from VBAT when measuring the sub-uA PMIC path.
 - Use `File > Examples > Nrf54L15-Clean-Implementation > PMIC > nPM1300_ChargerControl` or `File > Examples > Power > nPM1300_BatteryCurrent` to compare `IBAT` with the configured `VBUS_ILIM`.
 
 ---

README.md

@@ -1,7 +1,16 @@
 # nRF54 Arduino Core 1.0.13
 
-`1.0.13` fixes the nPM1300 timed-hibernate helper behavior reported in
-[issue #107](https://github.com/lolren/nrf54-arduino-core/issues/107).
+`1.0.13` corrected the battery-powered nPM1300 timer sequence reported in
+[issue #107](https://github.com/lolren/nrf54-arduino-core/issues/107), but its
+VBUS guard left the issue's USB-powered case unresolved.
+
+## Corrected in 1.0.14
+
+Release `1.0.14` keeps true PMIC Hibernate for VBUS-absent battery power and
+uses the nRF54 GRTC System OFF wake-reset path while VBUS is present. This is
+required because Nordic documents VBUS-disconnected as a precondition for
+`TASKENTERHIBERNATE`, while GRTC compare is a valid nRF54 System OFF wake
+source. Both paths cold-reset after the requested delay.
 
 ## nPM1300 timed hibernate
 

docs/RELEASE_1.0.13.md

@@ -0,0 +1,31 @@
+# nRF54 Arduino Core 1.0.14
+
+`1.0.14` completes the timed-hibernate fix reported in
+[issue #107](https://github.com/lolren/nrf54-arduino-core/issues/107).
+
+## nPM1300 timed cold boot
+
+- Keep true nPM1300 timed Hibernate when the XIAO nRF54LM20A is powered from
+  VBAT with VBUS absent.
+- When USB/VBUS is present, use the nRF54 GRTC timed System OFF wake-reset
+  path. Nordic requires VBUS to be disconnected before the PMIC can enter
+  Hibernate, so the SoC fallback provides the requested USB-powered behavior.
+- Preserve one `1` through `268435440` ms API range on both supply paths by
+  retaining the full millisecond delay in the GRTC calculation.
+- Accept the LM20A RADIO EasyDMA cleared-pointer readback during the guarded
+  System OFF shutdown sequence, while retaining the existing idle, disabled,
+  and zero-length DMA checks.
+- Both successful paths cold-boot and restart the sketch from `setup()`.
+
+## Validation
+
+- Core I/O regression suite passes with explicit battery/USB path contracts.
+- `nPM1300_TimedHibernate` compiles for XIAO nRF54LM20A.
+- An attached USB-powered XIAO nRF54LM20A completed three consecutive public
+  API cycles: each entered timed System OFF and cold-booted from the GRTC
+  compare event with no shutdown abort.
+
+## Install or upgrade
+
+Use Arduino Boards Manager after refreshing the package index, or install from
+the release archive attached to `v1.0.14`.

docs/RELEASE_1.0.14.md

@@ -3,7 +3,7 @@
 
 #define ARDUINO_NRF54L15_CLEAN_VERSION_MAJOR 1
 #define ARDUINO_NRF54L15_CLEAN_VERSION_MINOR 0
-#define ARDUINO_NRF54L15_CLEAN_VERSION_PATCH 13
+#define ARDUINO_NRF54L15_CLEAN_VERSION_PATCH 14
 #define ARDUINO_NRF54L15_CLEAN_VERSION_PRERELEASE ""
 #define ARDUINO_NRF54L15_CLEAN_VERSION_IS_PRERELEASE 0
 
@@ -16,6 +16,6 @@
         ARDUINO_NRF54L15_CLEAN_VERSION_MINOR, \
         ARDUINO_NRF54L15_CLEAN_VERSION_PATCH)
 
-#define ARDUINO_NRF54L15_CLEAN_VERSION_STRING "1.0.13"
+#define ARDUINO_NRF54L15_CLEAN_VERSION_STRING "1.0.14"
 
 #endif  // NRF54L15_CLEAN_CORE_VERSION_GENERATED_H

hardware/nrf54l15clean/nrf54l15clean/cores/nrf54l15/CoreVersionGenerated.h

@@ -708,9 +708,9 @@ static uint32_t systemOffMinimumLatencyUs(void)
            kSystemOffMinimumLatencyGuardUs;
 }
 
-static uint32_t clampSystemOffDelayUs(uint32_t delayUs)
+static uint64_t clampSystemOffDelayUs(uint64_t delayUs)
 {
-    const uint32_t minimumLatencyUs = systemOffMinimumLatencyUs();
+    const uint64_t minimumLatencyUs = systemOffMinimumLatencyUs();
     if (delayUs < minimumLatencyUs) {
         return minimumLatencyUs;
     }
@@ -805,7 +805,7 @@ typedef enum {
     kSystemOffWakeCompareFired = 3U
 } system_off_wake_program_status_t;
 
-static system_off_wake_program_status_t programSystemOffWakeUs(uint32_t delayUs)
+static system_off_wake_program_status_t programSystemOffWakeUs(uint64_t delayUs)
 {
     NRF_GRTC_Type* const grtc = NRF_GRTC;
     delayUs = clampSystemOffDelayUs(delayUs);
@@ -828,7 +828,7 @@ static system_off_wake_program_status_t programSystemOffWakeUs(uint32_t delayUs)
     }
 
     const uint32_t minimumLatencyUs = systemOffMinimumLatencyUs();
-    uint32_t wakeDelayUs = delayUs;
+    uint64_t wakeDelayUs = delayUs;
 
     for (uint8_t attempt = 0U; attempt < 2U; ++attempt) {
         ensureGrtcReady(grtc);
@@ -865,7 +865,7 @@ static system_off_wake_program_status_t programSystemOffWakeUs(uint32_t delayUs)
         grtc->CC[wakeChannel].CCEN =
             (GRTC_CC_CCEN_ACTIVE_Disable << GRTC_CC_CCEN_ACTIVE_Pos);
         grtc->EVENTS_COMPARE[wakeChannel] = 0U;
-        if (wakeDelayUs > UINT32_MAX - minimumLatencyUs) {
+        if (wakeDelayUs > UINT64_MAX - minimumLatencyUs) {
             return kSystemOffWakeCompareFired;
         }
         wakeDelayUs += minimumLatencyUs;
@@ -995,11 +995,11 @@ static bool clearResetReasonsForSystemOff(void)
 
 static void enterSystemOffInternal(bool disableRamRetention,
                                    bool timedWake,
-                                   uint32_t delayUs) __attribute__((noreturn));
+                                   uint64_t delayUs) __attribute__((noreturn));
 
 static void enterSystemOffInternal(bool disableRamRetention,
                                    bool timedWake,
-    uint32_t delayUs)
+    uint64_t delayUs)
 {
     clearSystemOffAbortDiagnostic();
     __asm volatile("cpsid i" ::: "memory");
@@ -1072,26 +1072,22 @@ void nrf54_core_system_off_timed_us(uint32_t delayUs,
     enterSystemOffInternal(disableRamRetention != 0U, true, delayUs);
 }
 
-static void enterTimedSystemOff(bool disableRamRetention, uint32_t delayUs)
+static void enterTimedSystemOff(bool disableRamRetention, uint64_t delayUs)
     __attribute__((noreturn));
 
-static void enterTimedSystemOff(bool disableRamRetention, uint32_t delayUs)
+static void enterTimedSystemOff(bool disableRamRetention, uint64_t delayUs)
 {
     enterSystemOffInternal(disableRamRetention, true, delayUs);
 }
 
-static uint32_t systemOffDelayMsToUs(unsigned long ms)
+static uint64_t systemOffDelayMsToUs(unsigned long ms)
 {
-    uint32_t delayMs = (uint32_t)ms;
-    if (delayMs > (0xFFFFFFFFUL / 1000UL)) {
-        delayMs = 0xFFFFFFFFUL / 1000UL;
-    }
-    return delayMs * 1000UL;
+    return (uint64_t)ms * 1000ULL;
 }
 
-static void enterSystemOffWakeReset(uint32_t delayUs) __attribute__((noreturn));
+static void enterSystemOffWakeReset(uint64_t delayUs) __attribute__((noreturn));
 
-static void enterSystemOffWakeReset(uint32_t delayUs)
+static void enterSystemOffWakeReset(uint64_t delayUs)
 {
     enterSystemOffInternal(true, true, delayUs);
 }

hardware/nrf54l15clean/nrf54l15clean/cores/nrf54l15/wiring_time.c

@@ -3,7 +3,7 @@
 
 #define ARDUINO_NRF54L15_CLEAN_VERSION_MAJOR 1
 #define ARDUINO_NRF54L15_CLEAN_VERSION_MINOR 0
-#define ARDUINO_NRF54L15_CLEAN_VERSION_PATCH 13
+#define ARDUINO_NRF54L15_CLEAN_VERSION_PATCH 14
 #define ARDUINO_NRF54L15_CLEAN_VERSION_PRERELEASE ""
 #define ARDUINO_NRF54L15_CLEAN_VERSION_IS_PRERELEASE 0
 
@@ -16,6 +16,6 @@
         ARDUINO_NRF54L15_CLEAN_VERSION_MINOR, \
         ARDUINO_NRF54L15_CLEAN_VERSION_PATCH)
 
-#define ARDUINO_NRF54L15_CLEAN_VERSION_STRING "1.0.13"
+#define ARDUINO_NRF54L15_CLEAN_VERSION_STRING "1.0.14"
 
 #endif  // NRF54L15_CLEAN_CORE_VERSION_GENERATED_H

hardware/nrf54l15clean/nrf54l15clean/cores/nrf54lm20b/CoreVersionGenerated.h

@@ -702,9 +702,9 @@ static uint32_t systemOffMinimumLatencyUs(void)
            kSystemOffMinimumLatencyGuardUs;
 }
 
-static uint32_t clampSystemOffDelayUs(uint32_t delayUs)
+static uint64_t clampSystemOffDelayUs(uint64_t delayUs)
 {
-    const uint32_t minimumLatencyUs = systemOffMinimumLatencyUs();
+    const uint64_t minimumLatencyUs = systemOffMinimumLatencyUs();
     if (delayUs < minimumLatencyUs) {
         return minimumLatencyUs;
     }
@@ -799,7 +799,7 @@ typedef enum {
     kSystemOffWakeCompareFired = 3U
 } system_off_wake_program_status_t;
 
-static system_off_wake_program_status_t programSystemOffWakeUs(uint32_t delayUs)
+static system_off_wake_program_status_t programSystemOffWakeUs(uint64_t delayUs)
 {
     NRF_GRTC_Type* const grtc = NRF_GRTC;
     delayUs = clampSystemOffDelayUs(delayUs);
@@ -822,7 +822,7 @@ static system_off_wake_program_status_t programSystemOffWakeUs(uint32_t delayUs)
     }
 
     const uint32_t minimumLatencyUs = systemOffMinimumLatencyUs();
-    uint32_t wakeDelayUs = delayUs;
+    uint64_t wakeDelayUs = delayUs;
 
     for (uint8_t attempt = 0U; attempt < 2U; ++attempt) {
         ensureGrtcReady(grtc);
@@ -859,7 +859,7 @@ static system_off_wake_program_status_t programSystemOffWakeUs(uint32_t delayUs)
         grtc->CC[wakeChannel].CCEN =
             (GRTC_CC_CCEN_ACTIVE_Disable << GRTC_CC_CCEN_ACTIVE_Pos);
         grtc->EVENTS_COMPARE[wakeChannel] = 0U;
-        if (wakeDelayUs > UINT32_MAX - minimumLatencyUs) {
+        if (wakeDelayUs > UINT64_MAX - minimumLatencyUs) {
             return kSystemOffWakeCompareFired;
         }
         wakeDelayUs += minimumLatencyUs;
@@ -989,11 +989,11 @@ static bool clearResetReasonsForSystemOff(void)
 
 static void enterSystemOffInternal(bool disableRamRetention,
                                    bool timedWake,
-                                   uint32_t delayUs) __attribute__((noreturn));
+                                   uint64_t delayUs) __attribute__((noreturn));
 
 static void enterSystemOffInternal(bool disableRamRetention,
                                    bool timedWake,
-    uint32_t delayUs)
+    uint64_t delayUs)
 {
     clearSystemOffAbortDiagnostic();
     __asm volatile("cpsid i" ::: "memory");
@@ -1066,26 +1066,22 @@ void nrf54_core_system_off_timed_us(uint32_t delayUs,
     enterSystemOffInternal(disableRamRetention != 0U, true, delayUs);
 }
 
-static void enterTimedSystemOff(bool disableRamRetention, uint32_t delayUs)
+static void enterTimedSystemOff(bool disableRamRetention, uint64_t delayUs)
     __attribute__((noreturn));
 
-static void enterTimedSystemOff(bool disableRamRetention, uint32_t delayUs)
+static void enterTimedSystemOff(bool disableRamRetention, uint64_t delayUs)
 {
     enterSystemOffInternal(disableRamRetention, true, delayUs);
 }
 
-static uint32_t systemOffDelayMsToUs(unsigned long ms)
+static uint64_t systemOffDelayMsToUs(unsigned long ms)
 {
-    uint32_t delayMs = (uint32_t)ms;
-    if (delayMs > (0xFFFFFFFFUL / 1000UL)) {
-        delayMs = 0xFFFFFFFFUL / 1000UL;
-    }
-    return delayMs * 1000UL;
+    return (uint64_t)ms * 1000ULL;
 }
 
-static void enterSystemOffWakeReset(uint32_t delayUs) __attribute__((noreturn));
+static void enterSystemOffWakeReset(uint64_t delayUs) __attribute__((noreturn));
 
-static void enterSystemOffWakeReset(uint32_t delayUs)
+static void enterSystemOffWakeReset(uint64_t delayUs)
 {
     enterSystemOffInternal(true, true, delayUs);
 }

hardware/nrf54l15clean/nrf54l15clean/cores/nrf54lm20b/wiring_time.c

@@ -1,15 +1,18 @@
 /*
  * nPM1300 Timed Hibernate
  *
- * XIAO nRF54LM20A PMIC hibernate example. This programs the nPM1300 wake
- * timer, then asks the PMIC to enter hibernate mode. On a battery/PPK2 supply
- * this is the sub-uA path reported by msfujino's test sketch.
+ * XIAO nRF54LM20A timed cold-boot example.
+ * - On battery/VBAT, the helper programs the nPM1300 wake timer and enters
+ *   true PMIC Hibernate.
+ * - On USB/VBUS, where the PMIC cannot enter Hibernate, the helper uses the
+ *   nRF54 GRTC System OFF wake-reset path.
  *
  * Current measurement notes:
- * - Measure from the VBAT/battery pads, not through USB.
- * - USB/VBUS must be disconnected before PMIC Hibernate entry; the helper
- *   returns false while VBUS is present.
- * - Wake is a cold boot after the PMIC timer expires.
+ * - To measure the lowest-current PMIC path, supply the VBAT/battery pads and
+ *   disconnect USB/VBUS plus debug wiring.
+ * - The USB fallback keeps the board's USB power path active and is not the
+ *   sub-uA PMIC Hibernate measurement case.
+ * - Both successful paths wake by cold boot and restart setup().
  */
 
 #include <Arduino.h>
@@ -36,8 +39,8 @@ void setup() {
   delay(2000);
 
   if (!npm1300_enter_timed_hibernate_ms(kHibernateMs)) {
-    // PMIC not present or timer setup failed. Blink fast so the failure is
-    // visible without requiring Serial while measuring current.
+    // Invalid delay, PMIC status read, or timer setup failed. Blink fast so
+    // the failure is visible without requiring Serial while measuring current.
     while (true) {
       digitalWrite(LED_BUILTIN, LOW);
       delay(50);

hardware/nrf54l15clean/nrf54l15clean/libraries/Nrf54L15-Clean-Implementation/examples/PMIC/nPM1300_TimedHibernate/nPM1300_TimedHibernate.ino

@@ -705,10 +705,22 @@ bool npm1300_configure_hibernate_timer_ms(uint32_t delay_ms) {
 }
 
 bool npm1300_enter_timed_hibernate_ms(uint32_t delay_ms) {
-    if (!npm1300_vbus_absent_for_ship_hibernate()) {
+    if (delay_ms == 0UL || delay_ms > NPM1300_HIBERNATE_TIMER_MAX_MS) {
         return false;
     }
 
+    uint8_t vbusStatus = 0U;
+    if (!npm1300_vbus_status(&vbusStatus)) {
+        return false;
+    }
+
+    if ((vbusStatus & NPM1300_VBUS_STATUS_PRESENT) != 0U) {
+        // nPM1300 Hibernate requires VBUS to be absent, and VBUS is itself a
+        // PMIC wake source. Use the SoC's timed System OFF cold-reset path
+        // while USB is powering the board.
+        systemOffWakeReset(delay_ms);
+    }
+
     if (!npm1300_configure_hibernate_timer_ms(delay_ms)) {
         return false;
     }