Add strong guarantee on monotonicity of system clock (#31885)

* Add strong guarantee on monotonicity of system clock

- It was observed some platforms have decrementing values from
  `SystemClock::GetMonotonicMilliseconds64()` implementation
  which can violate the required invariant that they NEVER go back,
  since multiple deadlines are computed from this clock, which could
  then never hit. This was observed to break in the field in subtle
  ways after ~48 days (2^32 milliseconds).
- This change introduces a VerifyOrDie to allow crash/restart if
  the invariant is broken, since that leaves the stack in a possibly
  wedged state.
- The new invariant is constructed to be reentrant-safe to maintain
  the invariant, in a way that it will eventually be caught, even
  if there are many threads/cores calling `GetMonotonicTimestamp()`.
  This was done in a lock-free manner, and was added since the public
  API of SystemLayer is not guaranteed to only be called from Matter
  thread context.

Issue #31875

Testing done:

- All unit tests still pass.
- All integration tests still pass.
- When `mockClock.AdvanceMonotonic(200_ms);` is replaced with
  `mockClock.AdvanceMonotonic(0xffff'ffff'ffff'ffff_ms);` in
  `TestSystemTimer.cpp::CheckOrder()`, the test crashes as expected
  due to detection of wraparound.

* Fix review comments and move to intrinsics

* Restyled by clang-format

* Fix build and add warning

* Fix build

* Restyled by clang-format

* Address review comment, add new define instead of linux && darwin

* Restyled by clang-format

---------

Co-authored-by: tennessee.carmelveilleux@gmail.com <tennessee@google.com>
Co-authored-by: Restyled.io <commits@restyled.io>

Author: 3 people

src/system/SystemClock.cpp

@@ -61,6 +61,39 @@ ClockBase * gClockBase = &gClockImpl;
 
 } // namespace Internal
 
+Timestamp ClockBase::GetMonotonicTimestamp()
+{
+    // Below implementation uses `__atomic_*` API which has wider support than
+    // <atomic> on embedded platforms, so that embedded platforms can use
+    // it by widening the #ifdefs later.
+#if CHIP_DEVICE_LAYER_USE_ATOMICS_FOR_CLOCK
+    uint64_t prevTimestamp = __atomic_load_n(&mLastTimestamp, __ATOMIC_SEQ_CST);
+    static_assert(sizeof(prevTimestamp) == sizeof(Timestamp), "Must have scalar match between timestamp and uint64_t for atomics.");
+
+    // Force a reorder barrier to prevent GetMonotonicMilliseconds64() from being
+    // optimizer-called before prevTimestamp loading, so that newTimestamp acquisition happens-after
+    // the prevTimestamp load.
+    __atomic_signal_fence(__ATOMIC_SEQ_CST);
+#else
+    uint64_t prevTimestamp = mLastTimestamp;
+#endif // CHIP_DEVICE_LAYER_USE_ATOMICS_FOR_CLOCK
+
+    Timestamp newTimestamp = GetMonotonicMilliseconds64();
+
+    // Need to guarantee the invariant that monotonic clock never goes backwards, which would break multiple system
+    // assumptions which use these clocks.
+    VerifyOrDie(newTimestamp.count() >= prevTimestamp);
+
+#if CHIP_DEVICE_LAYER_USE_ATOMICS_FOR_CLOCK
+    // newTimestamp guaranteed to never be < the last timestamp.
+    __atomic_store_n(&mLastTimestamp, newTimestamp.count(), __ATOMIC_SEQ_CST);
+#else
+    mLastTimestamp         = newTimestamp.count();
+#endif // CHIP_DEVICE_LAYER_USE_ATOMICS_FOR_CLOCK
+
+    return newTimestamp;
+}
+
 #if !CHIP_SYSTEM_CONFIG_PLATFORM_PROVIDES_TIME
 
 #if CHIP_SYSTEM_CONFIG_USE_POSIX_TIME_FUNCTS

src/system/SystemClock.h

@@ -43,6 +43,14 @@
 #include <chrono>
 #include <stdint.h>
 
+#if CHIP_DEVICE_LAYER_TARGET_DARWIN || CHIP_DEVICE_LAYER_TARGET_LINUX
+#define CHIP_DEVICE_LAYER_USE_ATOMICS_FOR_CLOCK 1
+#endif // CHIP_DEVICE_LAYER_TARGET_DARWIN || CHIP_DEVICE_LAYER_TARGET_LINUX
+
+#ifndef CHIP_DEVICE_LAYER_USE_ATOMICS_FOR_CLOCK
+#define CHIP_DEVICE_LAYER_USE_ATOMICS_FOR_CLOCK 0
+#endif
+
 namespace chip {
 namespace System {
 
@@ -149,15 +157,20 @@ class ClockBase
      *
      * Although some platforms may choose to return a value that measures the time since boot for the
      * system, applications must *not* rely on this.
+     *
+     * WARNING: *** It is up to each platform to ensure that GetMonotonicTimestamp can be
+     *              called safely in a re-entrant way from multiple contexts if making use
+     *              of this method from the application, outside the Matter stack execution
+     *              serialization context. ***
      */
-    Timestamp GetMonotonicTimestamp() { return GetMonotonicMilliseconds64(); }
+    virtual Timestamp GetMonotonicTimestamp();
 
     /**
-     * Returns a monotonic system time in units of microseconds.
+     * Returns a monotonic system time in units of microseconds, from the platform.
      *
      * This function returns an elapsed time in microseconds since an arbitrary, platform-defined epoch.
-     * The value returned is guaranteed to be ever-increasing (i.e. never wrapping or decreasing) between
-     * reboots of the system.  Additionally, the underlying time source is guaranteed to tick
+     * The value returned MUST BE guaranteed to be ever-increasing (i.e. never wrapping or decreasing) until
+     * reboot of the system.  Additionally, the underlying time source is guaranteed to tick
      * continuously during any system sleep modes that do not entail a restart upon wake.
      *
      * Although some platforms may choose to return a value that measures the time since boot for the
@@ -176,11 +189,11 @@ class ClockBase
     virtual Microseconds64 GetMonotonicMicroseconds64() = 0;
 
     /**
-     * Returns a monotonic system time in units of milliseconds.
+     * Returns a monotonic system time in units of microseconds, from the platform.
      *
      * This function returns an elapsed time in milliseconds since an arbitrary, platform-defined epoch.
-     * The value returned is guaranteed to be ever-increasing (i.e. never wrapping or decreasing) between
-     * reboots of the system.  Additionally, the underlying time source is guaranteed to tick
+     * The value returned MUST BE guaranteed to be ever-increasing (i.e. never wrapping or decreasing) until
+     * reboot of the system.  Additionally, the underlying time source is guaranteed to tick
      * continuously during any system sleep modes that do not entail a restart upon wake.
      *
      * Although some platforms may choose to return a value that measures the time since boot for the
@@ -288,6 +301,9 @@ class ClockBase
      *                                      current time.
      */
     virtual CHIP_ERROR SetClock_RealTime(Microseconds64 aNewCurTime) = 0;
+
+protected:
+    uint64_t mLastTimestamp = 0;
 };
 
 // Currently we have a single implementation class, ClockImpl, whose members are implemented in build-specific files.
@@ -334,7 +350,14 @@ class MockClock : public ClockImpl
         return CHIP_NO_ERROR;
     }
 
-    void SetMonotonic(Milliseconds64 timestamp) { mSystemTime = timestamp; }
+    void SetMonotonic(Milliseconds64 timestamp)
+    {
+        mSystemTime = timestamp;
+#if CHIP_DEVICE_LAYER_USE_ATOMICS_FOR_CLOCK
+        __atomic_store_n(&mLastTimestamp, timestamp.count(), __ATOMIC_SEQ_CST);
+#endif // CHIP_DEVICE_LAYER_USE_ATOMICS_FOR_CLOCK
+    }
+
     void AdvanceMonotonic(Milliseconds64 increment) { mSystemTime += increment; }
     void AdvanceRealTime(Milliseconds64 increment) { mRealTime += increment; }