1 /* 2 * Copyright (c) 2019, The OpenThread Authors. 3 * All rights reserved. 4 * 5 * Redistribution and use in source and binary forms, with or without 6 * modification, are permitted provided that the following conditions are met: 7 * 1. Redistributions of source code must retain the above copyright 8 * notice, this list of conditions and the following disclaimer. 9 * 2. Redistributions in binary form must reproduce the above copyright 10 * notice, this list of conditions and the following disclaimer in the 11 * documentation and/or other materials provided with the distribution. 12 * 3. Neither the name of the copyright holder nor the 13 * names of its contributors may be used to endorse or promote products 14 * derived from this software without specific prior written permission. 15 * 16 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" 17 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 18 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 19 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE 20 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 21 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 22 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 23 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 24 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 25 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 26 * POSSIBILITY OF SUCH DAMAGE. 27 */ 28 29 /** 30 * @file 31 * This file includes definitions for local Backbone Router service. 32 */ 33 34 #ifndef BACKBONE_ROUTER_LOCAL_HPP_ 35 #define BACKBONE_ROUTER_LOCAL_HPP_ 36 37 #include "openthread-core-config.h" 38 39 #if OPENTHREAD_FTD && OPENTHREAD_CONFIG_BACKBONE_ROUTER_ENABLE 40 41 #if (OPENTHREAD_CONFIG_THREAD_VERSION < OT_THREAD_VERSION_1_2) 42 #error "Thread 1.2 or higher version is required for OPENTHREAD_CONFIG_BACKBONE_ROUTER_ENABLE." 43 #endif 44 45 #if !OPENTHREAD_CONFIG_BORDER_ROUTER_ENABLE 46 #error "OPENTHREAD_CONFIG_BORDER_ROUTER_ENABLE is required for OPENTHREAD_CONFIG_BACKBONE_ROUTER_ENABLE." 47 #endif 48 49 #if !OPENTHREAD_CONFIG_TMF_NETDATA_SERVICE_ENABLE 50 #error "OPENTHREAD_CONFIG_TMF_NETDATA_SERVICE_ENABLE is required for OPENTHREAD_CONFIG_BACKBONE_ROUTER_ENABLE." 51 #endif 52 53 #include <openthread/backbone_router.h> 54 #include <openthread/backbone_router_ftd.h> 55 56 #include "backbone_router/bbr_leader.hpp" 57 #include "common/as_core_type.hpp" 58 #include "common/callback.hpp" 59 #include "common/locator.hpp" 60 #include "common/log.hpp" 61 #include "common/non_copyable.hpp" 62 #include "common/time_ticker.hpp" 63 #include "net/netif.hpp" 64 #include "thread/network_data.hpp" 65 66 namespace ot { 67 68 namespace BackboneRouter { 69 70 /** 71 * Implements the definitions for local Backbone Router service. 72 */ 73 class Local : public InstanceLocator, private NonCopyable 74 { 75 friend class ot::TimeTicker; 76 77 public: 78 typedef otBackboneRouterDomainPrefixCallback DomainPrefixCallback; ///< Domain Prefix callback. 79 80 /** 81 * Represents Backbone Router state. 82 */ 83 enum State : uint8_t 84 { 85 kStateDisabled = OT_BACKBONE_ROUTER_STATE_DISABLED, ///< Backbone function is disabled. 86 kStateSecondary = OT_BACKBONE_ROUTER_STATE_SECONDARY, ///< Secondary Backbone Router. 87 kStatePrimary = OT_BACKBONE_ROUTER_STATE_PRIMARY, ///< The Primary Backbone Router. 88 }; 89 90 /** 91 * Represents registration mode used as input to `AddService()` method. 92 */ 93 enum RegisterMode : uint8_t 94 { 95 kDecideBasedOnState, ///< Decide based on current state. 96 kForceRegistration, ///< Force registration regardless of current state. 97 }; 98 99 /** 100 * Initializes the local Backbone Router. 101 * 102 * @param[in] aInstance A reference to the OpenThread instance. 103 */ 104 explicit Local(Instance &aInstance); 105 106 /** 107 * Enables/disables Backbone function. 108 * 109 * @param[in] aEnable TRUE to enable the backbone function, FALSE otherwise. 110 */ 111 void SetEnabled(bool aEnable); 112 113 /** 114 * Retrieves the Backbone Router state. 115 * 116 * 117 * @returns The current state of Backbone Router. 118 */ GetState(void) const119 State GetState(void) const { return mState; } 120 121 /** 122 * Resets the local Thread Network Data. 123 */ 124 void Reset(void); 125 126 /** 127 * Gets local Backbone Router configuration. 128 * 129 * @param[out] aConfig The local Backbone Router configuration. 130 */ 131 void GetConfig(Config &aConfig) const; 132 133 /** 134 * Sets local Backbone Router configuration. 135 * 136 * @param[in] aConfig The configuration to set. 137 * 138 * @retval kErrorNone Successfully updated configuration. 139 * @retval kErrorInvalidArgs The configuration in @p aConfig is invalid. 140 */ 141 Error SetConfig(const Config &aConfig); 142 143 /** 144 * Registers Backbone Router Dataset to Leader. 145 * 146 * @param[in] aMode The registration mode to use (decide based on current state or force registration). 147 * 148 * @retval kErrorNone Successfully added the Service entry. 149 * @retval kErrorInvalidState Not in the ready state to register. 150 * @retval kErrorNoBufs Insufficient space to add the Service entry. 151 */ 152 Error AddService(RegisterMode aMode); 153 154 /** 155 * Indicates whether or not the Backbone Router is Primary. 156 * 157 * @retval True if the Backbone Router is Primary. 158 * @retval False if the Backbone Router is not Primary. 159 */ IsPrimary(void) const160 bool IsPrimary(void) const { return mState == kStatePrimary; } 161 162 /** 163 * Indicates whether or not the Backbone Router is enabled. 164 * 165 * @retval True if the Backbone Router is enabled. 166 * @retval False if the Backbone Router is not enabled. 167 */ IsEnabled(void) const168 bool IsEnabled(void) const { return mState != kStateDisabled; } 169 170 /** 171 * Sets the Backbone Router registration jitter value. 172 * 173 * @param[in] aRegistrationJitter the Backbone Router registration jitter value to set. 174 */ SetRegistrationJitter(uint8_t aRegistrationJitter)175 void SetRegistrationJitter(uint8_t aRegistrationJitter) { mRegistrationJitter = aRegistrationJitter; } 176 177 /** 178 * Returns the Backbone Router registration jitter value. 179 * 180 * @returns The Backbone Router registration jitter value. 181 */ GetRegistrationJitter(void) const182 uint8_t GetRegistrationJitter(void) const { return mRegistrationJitter; } 183 184 /** 185 * Notifies Primary Backbone Router status. 186 * 187 * @param[in] aState The state or state change of Primary Backbone Router. 188 * @param[in] aConfig The Primary Backbone Router service. 189 */ 190 void HandleBackboneRouterPrimaryUpdate(Leader::State aState, const Config &aConfig); 191 192 /** 193 * Gets the Domain Prefix configuration. 194 * 195 * @param[out] aConfig A reference to the Domain Prefix configuration. 196 * 197 * @retval kErrorNone Successfully got the Domain Prefix configuration. 198 * @retval kErrorNotFound No Domain Prefix was configured. 199 */ 200 Error GetDomainPrefix(NetworkData::OnMeshPrefixConfig &aConfig); 201 202 /** 203 * Removes the local Domain Prefix configuration. 204 * 205 * @param[in] aPrefix A reference to the IPv6 Domain Prefix. 206 * 207 * @retval kErrorNone Successfully removed the Domain Prefix. 208 * @retval kErrorInvalidArgs @p aPrefix is invalid. 209 * @retval kErrorNotFound No Domain Prefix was configured or @p aPrefix doesn't match. 210 */ 211 Error RemoveDomainPrefix(const Ip6::Prefix &aPrefix); 212 213 /** 214 * Sets the local Domain Prefix configuration. 215 * 216 * @param[in] aConfig A reference to the Domain Prefix configuration. 217 * 218 * @returns kErrorNone Successfully set the local Domain Prefix. 219 * @returns kErrorInvalidArgs @p aConfig is invalid. 220 */ 221 Error SetDomainPrefix(const NetworkData::OnMeshPrefixConfig &aConfig); 222 223 /** 224 * Returns a reference to the All Network Backbone Routers Multicast Address. 225 * 226 * @returns A reference to the All Network Backbone Routers Multicast Address. 227 */ GetAllNetworkBackboneRoutersAddress(void) const228 const Ip6::Address &GetAllNetworkBackboneRoutersAddress(void) const { return mAllNetworkBackboneRouters; } 229 230 /** 231 * Returns a reference to the All Domain Backbone Routers Multicast Address. 232 * 233 * @returns A reference to the All Domain Backbone Routers Multicast Address. 234 */ GetAllDomainBackboneRoutersAddress(void) const235 const Ip6::Address &GetAllDomainBackboneRoutersAddress(void) const { return mAllDomainBackboneRouters; } 236 237 /** 238 * Applies the Mesh Local Prefix. 239 */ 240 void ApplyNewMeshLocalPrefix(void); 241 242 /** 243 * Updates the subscription of All Domain Backbone Routers Multicast Address. 244 * 245 * @param[in] aEvent The Domain Prefix event. 246 */ 247 void HandleDomainPrefixUpdate(DomainPrefixEvent aEvent); 248 249 /** 250 * Sets the Domain Prefix callback. 251 * 252 * @param[in] aCallback The callback function. 253 * @param[in] aContext A user context pointer. 254 */ SetDomainPrefixCallback(DomainPrefixCallback aCallback,void * aContext)255 void SetDomainPrefixCallback(DomainPrefixCallback aCallback, void *aContext) 256 { 257 mDomainPrefixCallback.Set(aCallback, aContext); 258 } 259 260 private: 261 enum Action : uint8_t 262 { 263 kActionSet, 264 kActionAdd, 265 kActionRemove, 266 }; 267 268 void SetState(State aState); 269 void RemoveService(void); 270 void HandleTimeTick(void); 271 void AddDomainPrefixToNetworkData(void); 272 void RemoveDomainPrefixFromNetworkData(void); 273 void IncrementSequenceNumber(void); 274 #if OT_SHOULD_LOG_AT(OT_LOG_LEVEL_INFO) 275 static const char *ActionToString(Action aAction); 276 void LogService(Action aAction, Error aError); 277 void LogDomainPrefix(Action aAction, Error aError); 278 #else LogService(Action,Error)279 void LogService(Action, Error) {} LogDomainPrefix(Action,Error)280 void LogDomainPrefix(Action, Error) {} 281 #endif 282 283 // Indicates whether or not already add Backbone Router Service to local server data. 284 // Used to check whether or not in restore stage after reset or whether to remove 285 // Backbone Router service for Secondary Backbone Router if it was added by force. 286 bool mIsServiceAdded; 287 State mState; 288 uint8_t mSequenceNumber; 289 uint8_t mRegistrationJitter; 290 uint16_t mReregistrationDelay; 291 uint16_t mRegistrationTimeout; 292 uint32_t mMlrTimeout; 293 NetworkData::OnMeshPrefixConfig mDomainPrefixConfig; 294 Ip6::Netif::UnicastAddress mBbrPrimaryAloc; 295 Ip6::Address mAllNetworkBackboneRouters; 296 Ip6::Address mAllDomainBackboneRouters; 297 Callback<DomainPrefixCallback> mDomainPrefixCallback; 298 }; 299 300 } // namespace BackboneRouter 301 302 DefineMapEnum(otBackboneRouterState, BackboneRouter::Local::State); 303 304 /** 305 * @} 306 */ 307 308 } // namespace ot 309 310 #endif // OPENTHREAD_FTD && OPENTHREAD_CONFIG_BACKBONE_ROUTER_ENABLE 311 312 #endif // BACKBONE_ROUTER_LOCAL_HPP_ 313