[mle] add API to configure the store frame counter ahead (#10576)

Currently the OPENTHREAD_CONFIG_STORE_FRAME_COUNTER_AHEAD
is hard-coded in the OT core, yet sometimes it is
desired to modify this value which requires
re-building of the OT libraries and forces
re-certification of the end product.

Implement `otThreadSetStoreFrameCounterAhead`
and `otThreadGetStoreFrameCounterAhead` to allow
API clients to configure the store frame counter
ahead parameter at run-time. This extension offloads
product makers from the need of re-certification
in case the store frame counter ahead must be tuned.

Signed-off-by: Marcin Kajor <[email protected]>

etc/cmake/options.cmake

@@ -204,6 +204,7 @@ ot_option(OT_DNS_UPSTREAM_QUERY OPENTHREAD_CONFIG_DNS_UPSTREAM_QUERY_ENABLE "All
 ot_option(OT_DNSSD_DISCOVERY_PROXY OPENTHREAD_CONFIG_DNSSD_DISCOVERY_PROXY_ENABLE "DNS-SD discovery proxy")
 ot_option(OT_DNSSD_SERVER OPENTHREAD_CONFIG_DNSSD_SERVER_ENABLE "DNS-SD server")
 ot_option(OT_DUA OPENTHREAD_CONFIG_DUA_ENABLE "Domain Unicast Address (DUA)")
+ot_option(OT_DYNAMIC_STORE_FRAME_AHEAD_COUNTER OPENTHREAD_CONFIG_DYNAMIC_STORE_FRAME_AHEAD_COUNTER_ENABLE "dynamic store frame ahead counter")
 ot_option(OT_ECDSA OPENTHREAD_CONFIG_ECDSA_ENABLE "ECDSA")
 ot_option(OT_EXTERNAL_HEAP OPENTHREAD_CONFIG_HEAP_EXTERNAL_ENABLE "external heap")
 ot_option(OT_FIREWALL OPENTHREAD_POSIX_CONFIG_FIREWALL_ENABLE "firewall")

include/openthread/instance.h

@@ -53,7 +53,7 @@ extern "C" {
  * @note This number versions both OpenThread platform and user APIs.
  *
  */
-#define OPENTHREAD_API_VERSION (439)
+#define OPENTHREAD_API_VERSION (440)
 
 /**
  * @addtogroup api-instance

include/openthread/thread.h

@@ -1167,6 +1167,33 @@ otError otThreadDetachGracefully(otInstance *aInstance, otDetachGracefullyCallba
  */
 void otConvertDurationInSecondsToString(uint32_t aDuration, char *aBuffer, uint16_t aSize);
 
+/**
+ * Sets the store frame counter ahead.
+ *
+ * Requires `OPENTHREAD_CONFIG_DYNAMIC_STORE_FRAME_AHEAD_COUNTER_ENABLE` to be enabled.
+ *
+ * The OpenThread stack stores the MLE and MAC security frame counter values in non-volatile storage,
+ * ensuring they persist across device resets. These saved values are set to be ahead of their current
+ * values by the "frame counter ahead" value.
+ *
+ * @param[in] aInstance                  A pointer to an OpenThread instance.
+ * @param[in] aStoreFrameCounterAhead    The store frame counter ahead to set.
+ *
+ */
+void otThreadSetStoreFrameCounterAhead(otInstance *aInstance, uint32_t aStoreFrameCounterAhead);
+
+/**
+ * Gets the store frame counter ahead.
+ *
+ * Requires `OPENTHREAD_CONFIG_DYNAMIC_STORE_FRAME_AHEAD_COUNTER_ENABLE` to be enabled.
+ *
+ * @param[in] aInstance A pointer to an OpenThread instance.
+ *
+ * @returns The current store frame counter ahead.
+ *
+ */
+uint32_t otThreadGetStoreFrameCounterAhead(otInstance *aInstance);
+
 /**
  * @}
  *

src/core/api/thread_api.cpp

@@ -510,6 +510,18 @@ otError otThreadDetachGracefully(otInstance *aInstance, otDetachGracefullyCallba
     return AsCoreType(aInstance).Get<Mle::MleRouter>().DetachGracefully(aCallback, aContext);
 }
 
+#if OPENTHREAD_CONFIG_DYNAMIC_STORE_FRAME_AHEAD_COUNTER_ENABLE
+void otThreadSetStoreFrameCounterAhead(otInstance *aInstance, uint32_t aStoreFrameCounterAhead)
+{
+    return AsCoreType(aInstance).Get<Mle::Mle>().SetStoreFrameCounterAhead(aStoreFrameCounterAhead);
+}
+
+uint32_t otThreadGetStoreFrameCounterAhead(otInstance *aInstance)
+{
+    return AsCoreType(aInstance).Get<Mle::Mle>().GetStoreFrameCounterAhead();
+}
+#endif
+
 #endif // OPENTHREAD_FTD || OPENTHREAD_MTD
 
 #if OPENTHREAD_CONFIG_UPTIME_ENABLE

src/core/config/mle.h

@@ -348,6 +348,16 @@
 #define OPENTHREAD_CONFIG_MLE_LINK_METRICS_SERIES_MTD 2
 #endif
 
+/**
+ * @def OPENTHREAD_CONFIG_DYNAMIC_STORE_FRAME_AHEAD_COUNTER_ENABLE
+ *
+ * Enable setting the store frame counter ahead.
+ *
+ */
+#ifndef OPENTHREAD_CONFIG_DYNAMIC_STORE_FRAME_AHEAD_COUNTER_ENABLE
+#define OPENTHREAD_CONFIG_DYNAMIC_STORE_FRAME_AHEAD_COUNTER_ENABLE 0
+#endif
+
 /**
  * @}
  *

src/core/thread/mle.cpp

@@ -100,6 +100,7 @@ Mle::Mle(Instance &aInstance)
     , mAttachCounter(0)
     , mAnnounceDelay(kAnnounceTimeout)
     , mAlternatePanId(Mac::kPanIdBroadcast)
+    , mStoreFrameCounterAhead(kDefaultStoreFrameCounterAhead)
     , mTimeout(kDefaultChildTimeout)
 #if OPENTHREAD_CONFIG_MAC_CSL_RECEIVER_ENABLE
     , mCslTimeout(kDefaultCslTimeout)
@@ -501,8 +502,8 @@ Error Mle::Store(void)
     }
 
     networkInfo.SetKeySequence(Get<KeyManager>().GetCurrentKeySequence());
-    networkInfo.SetMleFrameCounter(Get<KeyManager>().GetMleFrameCounter() + kStoreFrameCounterAhead);
+    networkInfo.SetMleFrameCounter(Get<KeyManager>().GetMleFrameCounter() + mStoreFrameCounterAhead);
-    networkInfo.SetMacFrameCounter(Get<KeyManager>().GetMaximumMacFrameCounter() + kStoreFrameCounterAhead);
+    networkInfo.SetMacFrameCounter(Get<KeyManager>().GetMaximumMacFrameCounter() + mStoreFrameCounterAhead);
     networkInfo.SetDeviceMode(mDeviceMode.Get());
 
     SuccessOrExit(error = Get<Settings>().Save(networkInfo));

src/core/thread/mle.hpp

@@ -737,6 +737,27 @@ public:
         return (&aAddress == &mLinkLocalAllThreadNodes) || (&aAddress == &mRealmLocalAllThreadNodes);
     }
 
+#if OPENTHREAD_CONFIG_DYNAMIC_STORE_FRAME_AHEAD_COUNTER_ENABLE
+    /**
+     * Sets the store frame counter ahead.
+     *
+     * @param[in]  aStoreFrameCounterAhead  The store frame counter ahead to set.
+     *
+     */
+    void SetStoreFrameCounterAhead(uint32_t aStoreFrameCounterAhead)
+    {
+        mStoreFrameCounterAhead = aStoreFrameCounterAhead;
+    }
+
+    /**
+     * Gets the current store frame counter ahead.
+     *
+     * @returns The current store frame counter ahead.
+     *
+     */
+    uint32_t GetStoreFrameCounterAhead(void) { return mStoreFrameCounterAhead; }
+#endif // OPENTHREAD_CONFIG_DYNAMIC_STORE_FRAME_AHEAD_COUNTER_ENABLE
+
 #if OPENTHREAD_CONFIG_MAC_CSL_RECEIVER_ENABLE
     /**
      * Gets the CSL timeout.
@@ -829,12 +850,12 @@ private:
     static constexpr uint8_t kMaxServiceAlocs = OPENTHREAD_CONFIG_TMF_NETDATA_SERVICE_MAX_ALOCS;
 #endif
 
-    static constexpr uint8_t  kMleHopLimit              = 255;
+    static constexpr uint8_t  kMleHopLimit                   = 255;
-    static constexpr uint8_t  kMleSecurityTagSize       = 4;
+    static constexpr uint8_t  kMleSecurityTagSize            = 4;
-    static constexpr uint32_t kStoreFrameCounterAhead   = OPENTHREAD_CONFIG_STORE_FRAME_COUNTER_AHEAD;
+    static constexpr uint32_t kDefaultStoreFrameCounterAhead = OPENTHREAD_CONFIG_STORE_FRAME_COUNTER_AHEAD;
-    static constexpr uint8_t  kMaxIpAddressesToRegister = OPENTHREAD_CONFIG_MLE_IP_ADDRS_TO_REGISTER;
+    static constexpr uint8_t  kMaxIpAddressesToRegister      = OPENTHREAD_CONFIG_MLE_IP_ADDRS_TO_REGISTER;
-    static constexpr uint32_t kDefaultChildTimeout      = OPENTHREAD_CONFIG_MLE_CHILD_TIMEOUT_DEFAULT;
+    static constexpr uint32_t kDefaultChildTimeout           = OPENTHREAD_CONFIG_MLE_CHILD_TIMEOUT_DEFAULT;
-    static constexpr uint32_t kDefaultCslTimeout        = OPENTHREAD_CONFIG_CSL_TIMEOUT;
+    static constexpr uint32_t kDefaultCslTimeout             = OPENTHREAD_CONFIG_CSL_TIMEOUT;
 
     //------------------------------------------------------------------------------------------------------------------
     // Enumerations
@@ -1431,6 +1452,7 @@ private:
     uint16_t mAttachCounter;
     uint16_t mAnnounceDelay;
     uint16_t mAlternatePanId;
+    uint32_t mStoreFrameCounterAhead;
     uint32_t mTimeout;
 #if OPENTHREAD_CONFIG_MAC_CSL_RECEIVER_ENABLE
     uint32_t mCslTimeout;