[mle] Consolidate role transition management in RoleTransitioner

This commit introduces the `RoleTransitioner` class (renamed from
`RouterRoleTransition`) to centralize the management of state
related to router role allowed, up/downgrade thresholds,
and the address solicit state without introducing functional changes,
to support future changes related to configuring these parameters.

This commit is intended to not change any functionality, though some
expected enhancements have been added in several TODO comments.

The following state and logic are moved from the `Mle` class into
the `RoleTransitioner`:
- Increased scope of the state tracked by the `RoleTransitioner` class
  for all operations directly related to determining the transition
  state or timing for FTDs. This includes logic on values that can be
  passed with simple parameters to check functions, but excludes
  `InstanceLocator` operations, so that the class can remain focused on
  determining the role transition state.
- `Signal...` methods of the `RoleTransitioner` class have been defined
  to clarify events affecting state transitions.
- Named transition conditions on thresholds to `MayUpgrade()`,
  `MayBeginDowngradeTimer()`, and `MayCompleteTimedDowngrade()` to
  clarify that additional conditions may apply where called and to be
  more descriptive of the use of each threshold.
- Renamed `WillBecomeRouterSoon()` -> `MayBecomeRouterSoon()` to match
  other related name changes and indicate that a pending upgrade may
  fail to take effect.
- This also includes the downgrade blocking state (`mDowngradeBlocked`).
- Includes adding an extra delay in the Leader role when starting a
  downgrade timer due to the router role no longer allowed.
- Caches separate states affecting the `mRouterRoleAllowed` state
  independently, also detecting if a downgrade timer should be started
  when disallowed: `mRouterEligible`, `mUsingFtdMode`, and
  `mRouterRoleAllowedBySecurityPolicy`
- Some related switch cases have been replaced by short if-else blocks
  where it has a measurable improvement on codespace for the size-check
  build.

Author: jthompson-lutron

src/core/api/thread_ftd_api.cpp

@@ -63,6 +63,7 @@ otError otThreadSetMaxChildIpAddresses(otInstance *aInstance, uint8_t aMaxIpAddr
 
 bool otThreadIsRouterEligible(otInstance *aInstance)
 {
+    // The value returned by the API is based on all factors affecting the Router-role-allowed status.
     return AsCoreType(aInstance).Get<Mle::Mle>().IsRouterRoleAllowed();
 }
 

src/core/thread/dua_manager.cpp

@@ -319,7 +319,7 @@ void DuaManager::HandleNotifierEvents(Events aEvents)
             // Wait for link establishment with neighboring routers.
             UpdateRegistrationDelay(kNewRouterRegistrationDelay);
         }
-        else if (Get<Mle::Mle>().WillBecomeRouterSoon())
+        else if (Get<Mle::Mle>().MayBecomeRouterSoon())
         {
             // Will check again in case the device decides to stay REED when jitter timeout expires.
             UpdateRegistrationDelay(Get<Mle::Mle>().GetRouterRoleTransitionTimeout() + kNewRouterRegistrationDelay + 1);
@@ -432,7 +432,7 @@ void DuaManager::PerformNextRegistration(void)
     // Only send DUA.req when necessary
 #if OPENTHREAD_CONFIG_DUA_ENABLE
 #if OPENTHREAD_FTD
-    if (!Get<Mle::Mle>().IsRouterOrLeader() && Get<Mle::Mle>().WillBecomeRouterSoon())
+    if (!Get<Mle::Mle>().IsRouterOrLeader() && Get<Mle::Mle>().MayBecomeRouterSoon())
     {
         UpdateRegistrationDelay(Get<Mle::Mle>().GetRouterRoleTransitionTimeout() + kNewRouterRegistrationDelay + 1);
         ExitNow();

src/core/thread/mle.cpp

@@ -80,8 +80,6 @@ Mle::Mle(Instance &aInstance)
     , mWedAttachTimer(aInstance)
 #endif
 #if OPENTHREAD_FTD
-    , mAddressSolicitPending(false)
-    , mAddressSolicitRejected(false)
     , mNetworkIdTimeout(kNetworkIdTimeout)
     , mPreviousPartitionRouterIdSequence(0)
     , mPreviousPartitionIdTimeout(0)
@@ -99,7 +97,6 @@ Mle::Mle(Instance &aInstance)
     , mAdvertiseTrickleTimer(aInstance, Mle::HandleAdvertiseTrickleTimer)
     , mChildTable(aInstance)
     , mRouterTable(aInstance)
-    , mRoleTransitioner(aInstance)
 #endif // OPENTHREAD_FTD
 #if OPENTHREAD_CONFIG_P2P_ENABLE
     , mP2p(aInstance)
@@ -294,6 +291,10 @@ void Mle::SetRole(DeviceRole aRole)
 
     SuccessOrExit(Get<Notifier>().Update(mRole, aRole, kEventThreadRoleChanged));
 
+#if OPENTHREAD_FTD
+    mRoleTransitioner.SignalRoleChanged();
+#endif
+
     LogNote("Role %s -> %s", RoleToString(oldRole), RoleToString(mRole));
 
     if ((oldRole == kRoleDetached) && IsAttached())
@@ -446,10 +447,6 @@ void Mle::Restore(void)
     // non-volatile settings after boot.
     mHasRestored = true;
 
-#if OPENTHREAD_FTD
-    mRoleTransitioner.UpdateRouterRoleAllowed(RoleTransitioner::kReasonMleInit);
-#endif
-
 exit:
     return;
 }
@@ -598,7 +595,7 @@ void Mle::SetStateDetached(void)
     Get<MeshForwarder>().SetRxOnWhenIdle(true);
     Get<Mac::Mac>().SetBeaconEnabled(false);
 #if OPENTHREAD_FTD
-    mRoleTransitioner.SetDowngradeBlocked(false);
+    mRoleTransitioner.SignalDowngradeBlocked(false);
     ClearAlternateRloc16();
     HandleDetachStart();
 #endif
@@ -719,7 +716,7 @@ Error Mle::SetDeviceMode(DeviceMode aDeviceMode)
         ClearAlternateRloc16();
     }
 
-    mRoleTransitioner.UpdateRouterRoleAllowed(RoleTransitioner::kReasonDeviceModeChanged);
+    mRoleTransitioner.SignalFtdModeChanged(IsFullThreadDevice(), mRole);
 #endif
 
     if (IsAttached())
@@ -1044,7 +1041,7 @@ void Mle::HandleNotifierEvents(Events aEvents)
 #if OPENTHREAD_FTD
     if (aEvents.Contains(kEventSecurityPolicyChanged))
     {
-        mRoleTransitioner.UpdateRouterRoleAllowed(RoleTransitioner::kReasonSecurityPolicyChanged);
+        HandleRouterRoleAllowedFromSecurityPolicy();
     }
 
     if (mRoleTransitioner.IsDowngradeBlocked() && aEvents.Contains(kEventThreadChildRemoved))
@@ -1060,7 +1057,7 @@ void Mle::HandleNotifierEvents(Events aEvents)
             }
         }
 
-        mRoleTransitioner.SetDowngradeBlocked(shouldBlock);
+        mRoleTransitioner.SignalDowngradeBlocked(shouldBlock);
     }
 #endif
 

src/core/thread/mle.hpp

@@ -771,7 +771,7 @@ class Mle : public InstanceLocator, private NonCopyable
      * @retval kErrorNone         Successfully set the router-eligible configuration.
      * @retval kErrorNotCapable   The device is not capable of becoming a router.
      */
-    Error SetRouterEligible(bool aEligible) { return mRoleTransitioner.SetRouterEligible(aEligible); }
+    Error SetRouterEligible(bool aEligible);
 
     /**
      * Indicates whether the router role is currently allowed.
@@ -1022,7 +1022,7 @@ class Mle : public InstanceLocator, private NonCopyable
      * @retval TRUE   If the REED is going to become a Router soon.
      * @retval FALSE  If the REED is not going to become a Router soon.
      */
-    bool WillBecomeRouterSoon(void) const { return mRoleTransitioner.WillBecomeRouterSoon(); }
+    bool MayBecomeRouterSoon(void) const { return IsChild() && mRoleTransitioner.MayBecomeRouterSoon(); }
 
     /**
      * Removes a link to a neighbor.
@@ -1179,14 +1179,14 @@ class Mle : public InstanceLocator, private NonCopyable
      *
      * @param[in]  aEnabled  TRUE if the device was commissioned using CCM, FALSE otherwise.
      */
-    void SetCcmEnabled(bool aEnabled) { mRoleTransitioner.SetCcmEnabled(aEnabled); }
+    void SetCcmEnabled(bool aEnabled);
 
     /**
      * Sets whether the Security Policy TLV version-threshold for routing (VR field) is enabled.
      *
      * @param[in]  aEnabled  TRUE to enable Security Policy TLV version-threshold for routing, FALSE otherwise.
      */
-    void SetThreadVersionCheckEnabled(bool aEnabled) { mRoleTransitioner.SetThreadVersionCheckEnabled(aEnabled); }
+    void SetThreadVersionCheckEnabled(bool aEnabled);
 
     /**
      * Gets the current Interval Max value used by Advertisement trickle timer.
@@ -1344,12 +1344,8 @@ class Mle : public InstanceLocator, private NonCopyable
     static constexpr uint32_t kMaxLeaderToRouterTimeout      = 90000;  // (in msec)
     static constexpr uint8_t  kMinDowngradeNeighbors         = 7;
     static constexpr uint8_t  kNetworkIdTimeout              = 120; // (in sec)
-    static constexpr uint8_t  kRouterSelectionJitter         = 120; // (in sec)
-    static constexpr uint8_t  kRouterDowngradeThreshold      = 23;
-    static constexpr uint8_t  kRouterUpgradeThreshold        = 16;
     static constexpr uint16_t kDiscoveryMaxJitter            = 250; // Max jitter delay Discovery Responses (in msec).
     static constexpr uint16_t kUnsolicitedDataResponseJitter = 500; // Max delay for unsol Data Response (in msec).
-    static constexpr uint8_t  kLeaderDowngradeExtraDelay     = 10;  // Extra delay to downgrade leader (in sec).
     static constexpr uint8_t  kDefaultLeaderWeight           = 64;
     static constexpr uint8_t  kAlternateRloc16Timeout        = 8; // Time to use alternate RLOC16 (in sec).
 
@@ -2204,58 +2200,98 @@ class Mle : public InstanceLocator, private NonCopyable
 
 #if OPENTHREAD_FTD
 
-    class RoleTransitioner : public InstanceLocator
+    class RoleTransitioner
     {
-        // Manages the router role upgrade/downgrade transitions
-
     public:
-        enum UpdateRouterRoleAllowedReason : uint8_t // Used in `UpdateRouterRoleAllowed()`
-        {
-            kReasonMleInit,
-            kReasonDeviceModeChanged,
-            kReasonConfigParameterChanged,
-            kReasonSecurityPolicyChanged,
-        };
+        explicit RoleTransitioner(void);
 
-        explicit RoleTransitioner(Instance &aInstance);
+        bool IsAddressSolicitPending(void) const { return mAddressSolicitState == kAddressSolicitStatePending; }
+        bool IsRouterRoleAllowed(void) const { return mRouterRoleAllowed; }
+        bool IsTransitionPending(void) const { return (mTimeout != 0); }
+        bool IsDowngradeBlocked(void) const { return mDowngradeBlocked; }
+
+#if OPENTHREAD_CONFIG_REFERENCE_DEVICE_ENABLE
+        bool IsCcmEnabled(void) const { return mCcmEnabled; }
+        bool IsThreadVersionCheckEnabled(void) const { return mThreadVersionCheckEnabled; }
+#endif
 
-        bool    IsRouterRoleAllowed(void) const { return mRouterRoleAllowed; }
-        void    UpdateRouterRoleAllowed(UpdateRouterRoleAllowedReason aReason);
-        Error   SetRouterEligible(bool aEligible);
+        bool MayBecomeRouterSoon(void) const;
+        bool MayBeginDowngradeTimer(uint8_t aRouterCount, uint16_t aValidChildren) const;
+        bool MayCompleteTimedDowngrade(uint8_t aRouterCount) const;
+        bool MayUpgrade(uint8_t aRouterCount) const;
+
+        uint8_t GetTimeout(void) const { return mTimeout; }
         uint8_t GetJitter(void) const { return mJitter; }
-        void    SetJitter(uint8_t aJitter) { mJitter = aJitter; }
         uint8_t GetUpgradeThreshold(void) const { return mUpgradeThreshold; }
-        void    SetUpgradeThreshold(uint8_t aThreshold) { mUpgradeThreshold = aThreshold; }
         uint8_t GetDowngradeThreshold(void) const { return mDowngradeThreshold; }
-        void    SetDowngradeThreshold(uint8_t aThreshold) { mDowngradeThreshold = aThreshold; }
-        bool    IsDowngradeBlocked(void) const { return mDowngradeBlocked; }
-        void    SetDowngradeBlocked(bool aBlocked) { mDowngradeBlocked = aBlocked; }
-        bool    IsTransitionPending(void) const { return (mTimeout != 0); }
-        bool    WillBecomeRouterSoon(void) const;
-        void    StartTimeout(void);
-        void    StopTimeout(void) { mTimeout = 0; }
-        void    IncreaseTimeout(uint8_t aIncrement) { mTimeout += aIncrement; }
-        uint8_t GetTimeout(void) const { return mTimeout; }
-        bool    IsRouterCountBelowUpgradeThreshold(void) const;
-        void    HandleTimeTick(void);
-        void    DecideWhetherToUpgrade(void);
-        void    DecideWhetherToDowngrade(uint8_t aNeighborId, const RouteTlv &aRouteTlv);
+
+        bool HandleTimeTick(void);
+
+        void SetJitter(uint8_t aJitter) { mJitter = aJitter; }
+        void SetUpgradeThreshold(uint8_t aThreshold) { mUpgradeThreshold = aThreshold; }
+        void SetDowngradeThreshold(uint8_t aThreshold) { mDowngradeThreshold = aThreshold; }
+
+        // ------------------------
+        // State transition signals
+        void SignalAddressSolicitFinished(void);
+        void SignalAddressSolicitPending(void) { mAddressSolicitState = kAddressSolicitStatePending; }
+        void SignalAddressSolicitRejected(void) { mAddressSolicitState = kAddressSolicitStateRejected; }
+        void SignalBecomingRouter(void) { StopTimer(); }
+        void SignalBeginTimedLeaderDowngrade(void);
+        void SignalBeginTimedRouterDowngrade(void);
+        void SignalChildUpgradeStart(void);
+        void SignalDowngradeAborted(void);
+        void SignalDowngradeBlocked(bool aShouldBlock);
+        void SignalParentAdvertisementReceived(uint8_t aRouterCount);
+        void SignalRoleChanged(void);
+
+        // -----------------------------------------------------------------
+        // State transition signals affecting the Router role allowed status
+        void SignalFtdModeChanged(bool aIsFtdMode, DeviceRole aRole);
+        void SignalRouterEligible(bool aEligible, DeviceRole aRole);
+        void SignalRouterRoleAllowedBySecurityPolicy(bool aAllowed, DeviceRole aRole);
+
 #if OPENTHREAD_CONFIG_REFERENCE_DEVICE_ENABLE
-        void SetCcmEnabled(bool aEnabled);
-        void SetThreadVersionCheckEnabled(bool aEnabled);
+        // Setters for additional states affecting the SecurityPolicy router-role-allowed status
+        void SetCcmEnabled(bool aCcmEnabled) { mCcmEnabled = aCcmEnabled; }
+        void SetThreadVersionCheckEnabled(bool aThreadVersionCheckEnabled)
+        {
+            mThreadVersionCheckEnabled = aThreadVersionCheckEnabled;
+        }
 #endif
 
     private:
-        bool DetermineIfRouterRoleAllowed(void) const;
-        bool NeighborHasComparableConnectivity(uint8_t aNeighborId, const RouteTlv &aRouteTlv) const;
+        enum AddressSolicitState : uint8_t
+        {
+            kAddressSolicitStateIdle,
+            kAddressSolicitStatePending,
+            kAddressSolicitStateRejected,
+        };
+
+        void BeginTimer(void);
+        void StopTimer(void);
+        void SignalRouterRoleAllowedUpdate(DeviceRole aRole);
+
+        static constexpr uint8_t kLeaderDowngradeExtraDelay    = 10;  ///< Extra delay to downgrade leader (in sec).
+        static constexpr uint8_t kMaxDelayToTransitionSoon     = 10;  ///< Time window considered "soon" (in sec).
+        static constexpr uint8_t kRouterSelectionJitterDefault = 120; ///< Timeout jitter (in sec).
 
-        bool mRouterEligible : 1;
-        bool mRouterRoleAllowed : 1;
-        bool mDowngradeBlocked : 1;
+        static constexpr uint8_t kRouterDowngradeThresholdDefault = 23; ///< Default downgrade threshold
+        static constexpr uint8_t kRouterUpgradeThresholdDefault   = 16; ///< Default upgrade threshold
+
+        // Router Role Allowed statuses
+        bool mRouterRoleAllowed : 1; ///< Cached state of the router role allowed status
+        bool mRouterEligible : 1;    ///< Router Eligible configuration affecting the role allowed status
+        bool mUsingFtdMode : 1;      ///< FTD mode
+        bool mRouterRoleAllowedBySecurityPolicy : 1; ///< Cached state of the security policy router role allowed status
+        bool mDowngradeBlocked : 1;                  ///< Router role blocked from downgrading
 #if OPENTHREAD_CONFIG_REFERENCE_DEVICE_ENABLE
-        bool mCcmEnabled : 1;
-        bool mThreadVersionCheckEnabled : 1;
+        bool mCcmEnabled : 1;                ///< Whether to allow the security policy CCM commissioned check
+        bool mThreadVersionCheckEnabled : 1; ///< Whether to allow the security policy version check
 #endif
+
+        AddressSolicitState mAddressSolicitState;
+
         uint8_t mTimeout;
         uint8_t mJitter;
         uint8_t mUpgradeThreshold;
@@ -2446,6 +2482,8 @@ class Mle : public InstanceLocator, private NonCopyable
     void     ClearAlternateRloc16(void);
     uint8_t  SelectLeaderId(void) const;
     uint32_t SelectPartitionId(void) const;
+    void     HandleRouterRoleAllowedFromSecurityPolicy(void);
+    void     HandleRoleAllowedChangedFromConfig(void);
     void     DetermineConnectivity(Connectivity &aConnectivity) const;
     void     HandleDetachStart(void);
     void     HandleChildStart(void);
@@ -2493,6 +2531,8 @@ class Mle : public InstanceLocator, private NonCopyable
     void     SetChildStateToValid(Child &aChild);
     bool     HasChildren(void);
     void     RemoveChildren(void);
+    void     CheckOrBeginRouterDowngrade(uint8_t aNeighborId, const RouteTlv &aRouteTlv);
+    bool     NeighborHasComparableConnectivity(const RouteTlv &aRouteTlv, uint8_t aNeighborId) const;
     void     HandleAdvertiseTrickleTimer(void);
     void     HandleTimeTick(void);
     void     HandleRouterTableEvent(RouterTable::Events aEvents);
@@ -2571,13 +2611,13 @@ class Mle : public InstanceLocator, private NonCopyable
 
 #if OPENTHREAD_FTD
 
-    bool    mAddressSolicitPending : 1;
-    bool    mAddressSolicitRejected : 1;
+#if OPENTHREAD_CONFIG_REFERENCE_DEVICE_ENABLE
+    bool mCcmEnabled : 1;
+    bool mThreadVersionCheckEnabled : 1;
+#endif
     uint8_t mRouterId;
     uint8_t mPreviousRouterId;
     uint8_t mNetworkIdTimeout;
-    uint8_t mRouterUpgradeThreshold;
-    uint8_t mRouterDowngradeThreshold;
     uint8_t mLeaderWeight;
     uint8_t mPreviousPartitionRouterIdSequence;
     uint8_t mPreviousPartitionIdTimeout;