[bbr-leader] introduce PrimaryEvent to represent PBBR changes (#13112)

This commit introduces `PrimaryEvent` to represent changes in the
Primary Backbone Router (PBBR) configuration, replacing the previous
`State` enum. Calling it `State` was misleading as the values
describe transitions or updates to the PBBR rather than a persistent
state.

The new `PrimaryEvent` enum provides a more descriptive way to notify
dependent modules (`Mlr::Manager`, `DuaManager`, and `Bbr::Local`)
about specific changes in the PBBR, such as when it is added,
removed, or when its configuration parameters (e.g., RLOC16, Sequence
Number, or MLR Timeout) are updated.

src/core/backbone_router/bbr_leader.cpp

@@ -129,19 +129,17 @@ exit:
 
 #if OT_SHOULD_LOG_AT(OT_LOG_LEVEL_INFO)
 
-const char *Leader::StateToString(State aState)
+const char *Leader::PrimaryEventToString(PrimaryEvent aEvent)
 {
-#define StateMapList(_)                        \
-    _(kStateNone, "None")                      \
-    _(kStateAdded, "Added")                    \
-    _(kStateRemoved, "Removed")                \
-    _(kStateToTriggerRereg, "Rereg triggered") \
-    _(kStateRefreshed, "Refreshed")            \
-    _(kStateUnchanged, "Unchanged")
+#define PrimaryEventMapList(_)              \
+    _(kPrimaryAdded, "Added")               \
+    _(kPrimaryRemoved, "Removed")           \
+    _(kPrimaryUpdatedReregister, "Updated") \
+    _(kPrimaryConfigParameterChanged, "ConfigChanged")
 
-    DefineEnumStringArray(StateMapList);
+    DefineEnumStringArray(PrimaryEventMapList);
 
-    return kStrings[aState];
+    return kStrings[aEvent];
 }
 
 const char *Leader::DomainPrefixEventToString(DomainPrefixEvent aEvent)
@@ -169,50 +167,39 @@ void Leader::HandleNotifierEvents(Events aEvents)
 
 void Leader::UpdateBackboneRouterPrimary(void)
 {
-    Config newConfig;
-    State  state;
+    Config       newConfig;
+    PrimaryEvent event;
 
     Get<NetworkData::Service::Manager>().GetBackboneRouterPrimary(newConfig);
 
     newConfig.AdjustMlrTimeout();
 
-    if (newConfig.GetServer16() != mConfig.GetServer16())
+    if (!mConfig.IsPresent())
     {
-        if (!newConfig.IsPresent())
-        {
-            state = kStateRemoved;
-        }
-        else if (!mConfig.IsPresent())
-        {
-            state = kStateAdded;
-        }
-        else
-        {
-            // Short Address of PBBR changes.
-            state = kStateToTriggerRereg;
-        }
+        VerifyOrExit(newConfig.IsPresent());
+        event = kPrimaryAdded;
     }
     else if (!newConfig.IsPresent())
     {
-        // If no Primary all the time.
-        state = kStateNone;
+        event = kPrimaryRemoved;
     }
-    else if (newConfig.GetSequenceNumber() != mConfig.GetSequenceNumber())
+    else if (newConfig.GetServer16() != mConfig.GetServer16() ||
+             newConfig.GetSequenceNumber() != mConfig.GetSequenceNumber())
     {
-        state = kStateToTriggerRereg;
+        event = kPrimaryUpdatedReregister;
     }
     else if (newConfig.GetReregistrationDelay() != mConfig.GetReregistrationDelay() ||
              newConfig.GetMlrTimeout() != mConfig.GetMlrTimeout())
     {
-        state = kStateRefreshed;
+        event = kPrimaryConfigParameterChanged;
     }
     else
     {
-        state = kStateUnchanged;
+        ExitNow(); // No changes
     }
 
 #if OT_SHOULD_LOG_AT(OT_LOG_LEVEL_INFO)
-    LogInfo("PBBR event: %s", StateToString(state));
+    LogInfo("PrimaryEvent: %s", PrimaryEventToString(event));
     mConfig.Log("Old");
     newConfig.Log("New");
 #endif
@@ -220,18 +207,19 @@ void Leader::UpdateBackboneRouterPrimary(void)
     mConfig = newConfig;
 
 #if OPENTHREAD_FTD && OPENTHREAD_CONFIG_BACKBONE_ROUTER_ENABLE
-    Get<BackboneRouter::Local>().HandleBackboneRouterPrimaryUpdate(state);
+    Get<BackboneRouter::Local>().HandleBackboneRouterPrimaryUpdate(event);
 #endif
 
 #if OPENTHREAD_CONFIG_MLR_ENABLE || (OPENTHREAD_FTD && OPENTHREAD_CONFIG_TMF_PROXY_MLR_ENABLE)
-    Get<Mlr::Manager>().HandleBackboneRouterPrimaryUpdate(state);
+    Get<Mlr::Manager>().HandleBackboneRouterPrimaryUpdate(event);
 #endif
 
 #if OPENTHREAD_CONFIG_DUA_ENABLE || (OPENTHREAD_FTD && OPENTHREAD_CONFIG_TMF_PROXY_DUA_ENABLE)
-    Get<DuaManager>().HandleBackboneRouterPrimaryUpdate(state);
+    Get<DuaManager>().HandleBackboneRouterPrimaryUpdate(event);
 #endif
 
-    OT_UNUSED_VARIABLE(state);
+exit:
+    OT_UNUSED_VARIABLE(event);
 }
 
 void Leader::UpdateDomainPrefixConfig(void)

src/core/backbone_router/bbr_leader.hpp

@@ -77,6 +77,17 @@ enum DomainPrefixEvent : uint8_t
     kDomainPrefixRefreshed = OT_BACKBONE_ROUTER_DOMAIN_PREFIX_CHANGED, ///< Domain Prefix Changed.
 };
 
+/**
+ * Represents Primary Backbone Router events.
+ */
+enum PrimaryEvent : uint8_t
+{
+    kPrimaryAdded,                  ///< A new Primary Backbone Router is added.
+    kPrimaryRemoved,                ///< The Primary Backbone Router is removed.
+    kPrimaryUpdatedReregister,      ///< The Primary BBR is updated, need re-registration (server16 or seqno change).
+    kPrimaryConfigParameterChanged, ///< Config parameter changed: Re-registration Delay or MLR Timeout value.
+};
+
 class Leader;
 
 /**
@@ -155,18 +166,6 @@ class Leader : public InstanceLocator, private NonCopyable
     friend class ot::Notifier;
 
 public:
-    // Primary Backbone Router Service state or state change.
-    enum State : uint8_t
-    {
-        kStateNone = 0,       ///< Not exist (trigger Backbone Router register its service).
-        kStateAdded,          ///< Newly added.
-        kStateRemoved,        ///< Newly removed (trigger Backbone Router register its service).
-        kStateToTriggerRereg, ///< Short address or sequence number changes (trigger re-registration).
-                              ///< May also have ReregistrationDelay or MlrTimeout update.
-        kStateRefreshed,      ///< Only ReregistrationDelay or MlrTimeout changes.
-        kStateUnchanged,      ///< No change on Primary Backbone Router information (only for logging).
-    };
-
     /**
      * Initializes the `Leader`.
      *
@@ -251,7 +250,7 @@ private:
     void UpdateBackboneRouterPrimary(void);
     void UpdateDomainPrefixConfig(void);
 #if OT_SHOULD_LOG_AT(OT_LOG_LEVEL_INFO)
-    static const char *StateToString(State aState);
+    static const char *PrimaryEventToString(PrimaryEvent aEvent);
     static const char *DomainPrefixEventToString(DomainPrefixEvent aEvent);
 #endif
 

src/core/backbone_router/bbr_local.cpp

@@ -237,9 +237,9 @@ exit:
     return;
 }
 
-void Local::HandleBackboneRouterPrimaryUpdate(Leader::State aState)
+void Local::HandleBackboneRouterPrimaryUpdate(PrimaryEvent aEvent)
 {
-    OT_UNUSED_VARIABLE(aState);
+    OT_UNUSED_VARIABLE(aEvent);
 
     VerifyOrExit(IsEnabled() && Get<Mle::Mle>().IsAttached());
 

src/core/backbone_router/bbr_local.hpp

@@ -182,11 +182,11 @@ public:
     uint8_t GetRegistrationJitter(void) const { return mRegistrationJitter; }
 
     /**
-     * Notifies Primary Backbone Router status.
+     * Notifies the `Local` of a Primary Backbone Router event.
      *
-     * @param[in]  aState   The state or state change of Primary Backbone Router.
+     * @param[in]  aEvent   The Primary Backbone Router event.
      */
-    void HandleBackboneRouterPrimaryUpdate(Leader::State aState);
+    void HandleBackboneRouterPrimaryUpdate(PrimaryEvent aEvent);
 
     /**
      * Gets the Domain Prefix configuration.

src/core/thread/dua_manager.cpp

@@ -332,9 +332,9 @@ exit:
     return;
 }
 
-void DuaManager::HandleBackboneRouterPrimaryUpdate(BackboneRouter::Leader::State aState)
+void DuaManager::HandleBackboneRouterPrimaryUpdate(BackboneRouter::PrimaryEvent aEvent)
 {
-    if (aState == BackboneRouter::Leader::kStateAdded || aState == BackboneRouter::Leader::kStateToTriggerRereg)
+    if (aEvent == BackboneRouter::kPrimaryAdded || aEvent == BackboneRouter::kPrimaryUpdatedReregister)
     {
 #if OPENTHREAD_CONFIG_DUA_ENABLE
         if (Get<Mle::Mle>().IsFullThreadDevice() || Get<Mle::Mle>().GetParent().IsThreadVersion1p1())

src/core/thread/dua_manager.hpp

@@ -114,11 +114,11 @@ public:
     void HandleDomainPrefixUpdate(BackboneRouter::DomainPrefixEvent aEvent);
 
     /**
-     * Notifies Primary Backbone Router status.
+     * Notifies the `DuaManager` of a Primary Backbone Router event.
      *
-     * @param[in]  aState   The state or state change of Primary Backbone Router.
+     * @param[in]  aEvent   The Primary Backbone Router event.
      */
-    void HandleBackboneRouterPrimaryUpdate(BackboneRouter::Leader::State aState);
+    void HandleBackboneRouterPrimaryUpdate(BackboneRouter::PrimaryEvent aEvent);
 
 #if OPENTHREAD_CONFIG_DUA_ENABLE
 

src/core/thread/mlr_manager.cpp

@@ -68,14 +68,14 @@ void Manager::HandleNotifierEvents(Events aEvents)
     }
 }
 
-void Manager::HandleBackboneRouterPrimaryUpdate(BackboneRouter::Leader::State aState)
+void Manager::HandleBackboneRouterPrimaryUpdate(BackboneRouter::PrimaryEvent aEvent)
 {
     RegistrationRequest request = kRenew;
 
-    switch (aState)
+    switch (aEvent)
     {
-    case BackboneRouter::Leader::kStateAdded:
-    case BackboneRouter::Leader::kStateToTriggerRereg:
+    case BackboneRouter::kPrimaryAdded:
+    case BackboneRouter::kPrimaryUpdatedReregister:
         request = kReregister;
         break;
     default:

src/core/thread/mlr_manager.hpp

@@ -92,11 +92,11 @@ public:
     explicit Manager(Instance &aInstance);
 
     /**
-     * Notifies Primary Backbone Router status.
+     * Notifies the `MlrManager` of a Primary Backbone Router event.
      *
-     * @param[in]  aState   The state or state change of Primary Backbone Router.
+     * @param[in]  aEvent   The Primary Backbone Router event.
      */
-    void HandleBackboneRouterPrimaryUpdate(BackboneRouter::Leader::State aState);
+    void HandleBackboneRouterPrimaryUpdate(BackboneRouter::PrimaryEvent aEvent);
 
 #if OPENTHREAD_FTD && OPENTHREAD_CONFIG_TMF_PROXY_MLR_ENABLE
     static constexpr uint16_t kMaxChildAddresses = OPENTHREAD_CONFIG_MLE_IP_ADDRS_PER_CHILD - 1; ///< Max MLR addresses