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/locator.hpp" 58 #include "common/log.hpp" 59 #include "common/non_copyable.hpp" 60 #include "net/netif.hpp" 61 #include "thread/network_data.hpp" 62 63 namespace ot { 64 65 namespace BackboneRouter { 66 67 /** 68 * This class implements the definitions for local Backbone Router service. 69 * 70 */ 71 class Local : public InstanceLocator, private NonCopyable 72 { 73 public: 74 typedef otBackboneRouterState BackboneRouterState; 75 76 /** 77 * This constructor initializes the local Backbone Router. 78 * 79 * @param[in] aInstance A reference to the OpenThread instance. 80 * 81 */ 82 explicit Local(Instance &aInstance); 83 84 /** 85 * This method enables/disables Backbone function. 86 * 87 * @param[in] aEnable TRUE to enable the backbone function, FALSE otherwise. 88 * 89 */ 90 void SetEnabled(bool aEnable); 91 92 /** 93 * This method retrieves the Backbone Router state. 94 * 95 * 96 * @retval OT_BACKBONE_ROUTER_STATE_DISABLED Backbone function is disabled. 97 * @retval OT_BACKBONE_ROUTER_STATE_SECONDARY Secondary Backbone Router. 98 * @retval OT_BACKBONE_ROUTER_STATE_PRIMARY Primary Backbone Router. 99 * 100 */ GetState(void) const101 BackboneRouterState GetState(void) const { return mState; } 102 103 /** 104 * This method resets the local Thread Network Data. 105 * 106 */ 107 void Reset(void); 108 109 /** 110 * This method gets local Backbone Router configuration. 111 * 112 * @param[out] aConfig The local Backbone Router configuration. 113 * 114 */ 115 void GetConfig(BackboneRouterConfig &aConfig) const; 116 117 /** 118 * This method sets local Backbone Router configuration. 119 * 120 * @param[in] aConfig The configuration to set. 121 * 122 * @retval kErrorNone Successfully updated configuration. 123 * @retval kErrorInvalidArgs The configuration in @p aConfig is invalid. 124 * 125 */ 126 Error SetConfig(const BackboneRouterConfig &aConfig); 127 128 /** 129 * This method registers Backbone Router Dataset to Leader. 130 * 131 * @param[in] aForce True to force registration regardless of current BackboneRouterState. 132 * False to decide based on current BackboneRouterState. 133 * 134 * 135 * @retval kErrorNone Successfully added the Service entry. 136 * @retval kErrorInvalidState Not in the ready state to register. 137 * @retval kErrorNoBufs Insufficient space to add the Service entry. 138 * 139 */ 140 Error AddService(bool aForce = false); 141 142 /** 143 * This method indicates whether or not the Backbone Router is Primary. 144 * 145 * @retval True if the Backbone Router is Primary. 146 * @retval False if the Backbone Router is not Primary. 147 * 148 */ IsPrimary(void) const149 bool IsPrimary(void) const { return mState == OT_BACKBONE_ROUTER_STATE_PRIMARY; } 150 151 /** 152 * This method indicates whether or not the Backbone Router is enabled. 153 * 154 * @retval True if the Backbone Router is enabled. 155 * @retval False if the Backbone Router is not enabled. 156 * 157 */ IsEnabled(void) const158 bool IsEnabled(void) const { return mState != OT_BACKBONE_ROUTER_STATE_DISABLED; } 159 160 /** 161 * This method sets the Backbone Router registration jitter value. 162 * 163 * @param[in] aRegistrationJitter the Backbone Router registration jitter value to set. 164 * 165 */ SetRegistrationJitter(uint8_t aRegistrationJitter)166 void SetRegistrationJitter(uint8_t aRegistrationJitter) { mRegistrationJitter = aRegistrationJitter; } 167 168 /** 169 * This method returns the Backbone Router registration jitter value. 170 * 171 * @returns The Backbone Router registration jitter value. 172 * 173 */ GetRegistrationJitter(void) const174 uint8_t GetRegistrationJitter(void) const { return mRegistrationJitter; } 175 176 /** 177 * This method notifies Primary Backbone Router status. 178 * 179 * @param[in] aState The state or state change of Primary Backbone Router. 180 * @param[in] aConfig The Primary Backbone Router service. 181 * 182 */ 183 void HandleBackboneRouterPrimaryUpdate(Leader::State aState, const BackboneRouterConfig &aConfig); 184 185 /** 186 * This method gets the Domain Prefix configuration. 187 * 188 * @param[out] aConfig A reference to the Domain Prefix configuration. 189 * 190 * @retval kErrorNone Successfully got the Domain Prefix configuration. 191 * @retval kErrorNotFound No Domain Prefix was configured. 192 * 193 */ 194 Error GetDomainPrefix(NetworkData::OnMeshPrefixConfig &aConfig); 195 196 /** 197 * This method removes the local Domain Prefix configuration. 198 * 199 * @param[in] aPrefix A reference to the IPv6 Domain Prefix. 200 * 201 * @retval kErrorNone Successfully removed the Domain Prefix. 202 * @retval kErrorInvalidArgs @p aPrefix is invalid. 203 * @retval kErrorNotFound No Domain Prefix was configured or @p aPrefix doesn't match. 204 * 205 */ 206 Error RemoveDomainPrefix(const Ip6::Prefix &aPrefix); 207 208 /** 209 * This method sets the local Domain Prefix configuration. 210 * 211 * @param[in] aConfig A reference to the Domain Prefix configuration. 212 * 213 * @returns kErrorNone Successfully set the local Domain Prefix. 214 * @returns kErrorInvalidArgs @p aConfig is invalid. 215 * 216 */ 217 Error SetDomainPrefix(const NetworkData::OnMeshPrefixConfig &aConfig); 218 219 /** 220 * This method returns a reference to the All Network Backbone Routers Multicast Address. 221 * 222 * @returns A reference to the All Network Backbone Routers Multicast Address. 223 * 224 */ GetAllNetworkBackboneRoutersAddress(void) const225 const Ip6::Address &GetAllNetworkBackboneRoutersAddress(void) const { return mAllNetworkBackboneRouters; } 226 227 /** 228 * This method returns a reference to the All Domain Backbone Routers Multicast Address. 229 * 230 * @returns A reference to the All Domain Backbone Routers Multicast Address. 231 * 232 */ GetAllDomainBackboneRoutersAddress(void) const233 const Ip6::Address &GetAllDomainBackboneRoutersAddress(void) const { return mAllDomainBackboneRouters; } 234 235 /** 236 * This method applies the Mesh Local Prefix. 237 * 238 */ 239 void ApplyMeshLocalPrefix(void); 240 241 /** 242 * This method updates the subscription of All Domain Backbone Routers Multicast Address. 243 * 244 * @param[in] aState The Domain Prefix state or state change. 245 * 246 */ 247 void HandleDomainPrefixUpdate(Leader::DomainPrefixState aState); 248 249 /** 250 * This method sets the Domain Prefix callback. 251 * 252 * @param[in] aCallback The callback function. 253 * @param[in] aContext A user context pointer. 254 * 255 */ 256 void SetDomainPrefixCallback(otBackboneRouterDomainPrefixCallback aCallback, void *aContext); 257 258 private: 259 void SetState(BackboneRouterState aState); 260 void RemoveService(void); 261 void AddDomainPrefixToNetworkData(void); 262 void RemoveDomainPrefixFromNetworkData(void); 263 void SequenceNumberIncrease(void); 264 #if OT_SHOULD_LOG_AT(OT_LOG_LEVEL_INFO) 265 void LogBackboneRouterService(const char *aAction, Error aError); 266 void LogDomainPrefix(const char *aAction, Error aError); 267 #else LogBackboneRouterService(const char *,Error)268 void LogBackboneRouterService(const char *, Error) {} LogDomainPrefix(const char *,Error)269 void LogDomainPrefix(const char *, Error) {} 270 #endif 271 272 BackboneRouterState mState; 273 uint32_t mMlrTimeout; 274 uint16_t mReregistrationDelay; 275 uint8_t mSequenceNumber; 276 uint8_t mRegistrationJitter; 277 278 // Indicates whether or not already add Backbone Router Service to local server data. 279 // Used to check whether or not in restore stage after reset or whether to remove 280 // Backbone Router service for Secondary Backbone Router if it was added by force. 281 bool mIsServiceAdded; 282 283 NetworkData::OnMeshPrefixConfig mDomainPrefixConfig; 284 285 Ip6::Netif::UnicastAddress mBackboneRouterPrimaryAloc; 286 Ip6::Address mAllNetworkBackboneRouters; 287 Ip6::Address mAllDomainBackboneRouters; 288 otBackboneRouterDomainPrefixCallback mDomainPrefixCallback; 289 void * mDomainPrefixCallbackContext; 290 }; 291 292 } // namespace BackboneRouter 293 294 /** 295 * @} 296 */ 297 298 } // namespace ot 299 300 #endif // OPENTHREAD_FTD && OPENTHREAD_CONFIG_BACKBONE_ROUTER_ENABLE 301 302 #endif // BACKBONE_ROUTER_LOCAL_HPP_ 303