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