| /* |
| * |
| * Copyright (c) 2015-2017 Nest Labs, Inc. |
| * All rights reserved. |
| * |
| * Licensed under the Apache License, Version 2.0 (the "License"); |
| * you may not use this file except in compliance with the License. |
| * You may obtain a copy of the License at |
| * |
| * http://www.apache.org/licenses/LICENSE-2.0 |
| * |
| * Unless required by applicable law or agreed to in writing, software |
| * distributed under the License is distributed on an "AS IS" BASIS, |
| * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| * See the License for the specific language governing permissions and |
| * limitations under the License. |
| */ |
| |
| /** |
| * @file |
| * This file defines API's and platform abstractions |
| * for Nest Labs' Weave Address and Routing Module (WARM). |
| * |
| * \page Weave Address Assignment |
| * \section intro Introduction: |
| * Because there are a number of inter-dependencies between interfaces and because |
| * different Device configurations can require different TCP/IP address and route |
| * assignment, it was deemed essential that the logic for controlling IP address |
| * and Route assignment be consolidated into a single module. WARM serves the purpose |
| * of properly adding and removing TCP/IP addresses and Routes to Weave related IP interfaces |
| * as those interfaces transition from active<->inactive. |
| * |
| * WARM is intended to be configured at compile time via WarmProjectConfig.h and WarmConfig.h. |
| * WarmProjectConfig.h must accurately reflect the supported features of the device upon which |
| * WARM will execute. |
| * |
| * WARM is a portable module that limits its dependency on how a TCP/IP stack and Thread Interface |
| * are configured. For this purpose WARM relies on a Set of Platform API's which |
| * must be implemented by the Platform Integrator. Furthermore, the Platform Integrator is |
| * responsible for making the various nl::Warm API calls from appropriate execution points within |
| * the Platform code base. |
| * |
| * \section theory Theory of Operation: |
| * The Platform code base will call nl::Warm API's to announce a change of State for related |
| * features such as the WiFi interface and Thread interface. A call to any of these nl::Warm API's |
| * may result in a call by WARM to Platform::RequestInvokeActions(). Platform::RequestInvokeActions() |
| * must be implemented to perform the necessary operations that will call Warm::InvokeActions(). This |
| * process at first glance may appear un-necessarily indirect. Why wouldn't WARM call InvokeActions |
| * directly? The answer to that question, is to allow for any task in a multi-tasking system to call |
| * the nl::Warm State Change API's, and to provide a mechanism so that only a specific task will call |
| * the Platform:: API's. After taking the Platform requirements into consideration, the Platform |
| * Integrator may choose to implement Platform::RequestInvokeActions() so that it posts an event to |
| * the appropriate task that will react by calling Warm::InvokeActions(). If, for a given platform, it is |
| * decided that no such multi-tasking concerns exist, Platform::RequestInvokeActions() can be implemented |
| * to call Warm::InvokeActions() directly. |
| * |
| * When Warm::InvokeActions() is called the WARM logic will examine the current System State and |
| * make any necessary Platform:: API calls in order to bring the address and routing State in line |
| * with the System and Configuration State. These calls are made in a pre-defined order and if any of these API's |
| * return kPlatformResultInProgress, execution of the ordered list will suspend and exit. Furthermore, when |
| * one of these API's returns kPlatformResultInProgress, it is interpreted that the operation |
| * will complete asynchronously and that the WARM logic should wait for that operation to complete. |
| * Upon operation completion, the Platform code should call Warm::ReportActionComplete(), passing in a |
| * result of kPlatformResultSuccess or kPlatformResultFailure. Upon receiving this call the WARM |
| * logic will again call Platform::RequestInvokeActions() in order to restart execution of the |
| * ordered action list. |
| * |
| * In this way WARM does not require its own task but can instead rely on another task to call into Warm |
| * as appropriate. Additionally, any task may call one or more of the System State change API's, thus |
| * simplifying integration. |
| * |
| */ |
| |
| #ifndef WARM_H_ |
| #define WARM_H_ |
| |
| #include <Warm/WarmConfig.h> |
| #include <InetLayer/IPAddress.h> |
| #include <InetLayer/IPPrefix.h> |
| #include <Weave/Core/WeaveCore.h> |
| |
| #if WARM_CONFIG_SUPPORT_WEAVE_TUNNEL |
| #include <Weave/Profiles/weave-tunneling/WeaveTunnelAgent.h> |
| #endif |
| |
| using namespace nl::Weave; |
| |
| /** |
| * @namespace nl::Weave::Warm |
| * |
| * @brief |
| * This namespace includes interfaces for the Weave Address and Routing Module, a |
| * portable Module for configuring Weave IP addresses and Routes. |
| */ |
| namespace nl { |
| namespace Weave { |
| namespace Warm { |
| |
| /** |
| * An enum of possible platform API return values. |
| * |
| */ |
| typedef enum { |
| kPlatformResultSuccess = 0, // The API completed successfully. |
| kPlatformResultFailure, // The API execution failed. |
| kPlatformResultInProgress // The operation is in-progress and will complete asynchronously. |
| } PlatformResult; |
| |
| /** |
| * An enum of possible interface types. |
| * |
| * @note |
| * Do not change the elements in this enum as it is used as an index into arrays. |
| * Products will typically support a subset of these possible interfaces. |
| * |
| */ |
| typedef enum { |
| kInterfaceTypeLegacy6LoWPAN = 0, // Thread alarm interface. |
| kInterfaceTypeThread, // Thread interface. |
| kInterfaceTypeWiFi, // The WiFi interface. |
| kInterfaceTypeTunnel, // The Tunnel interface. |
| kInterfaceTypeCellular, // The Cellular interface. |
| |
| kInterfaceTypeMax |
| } InterfaceType; |
| |
| /** |
| * An enum of possible route priorities so that one route can be given priority over another. |
| * |
| */ |
| typedef enum { |
| kRoutePriorityLow = 0, |
| kRoutePriorityMedium, |
| kRoutePriorityHigh |
| } RoutePriority; |
| |
| /** |
| * An enum of possible Interface State values. |
| * |
| */ |
| typedef enum { |
| kInterfaceStateUp = true, |
| kInterfaceStateDown = false |
| } InterfaceState; |
| |
| /** |
| * @class WarmFabricStateDelegate |
| * |
| * @brief |
| * This is an internal class to WarmCore. It implements the FabricStateDelegate interface. |
| * An instance of this class (namely sWarmFabricStateDelegate), is set as the delegate of |
| * WeaveFabricState. Warm uses this to be notified of Fabric state changes. |
| */ |
| class WarmFabricStateDelegate |
| : public FabricStateDelegate |
| { |
| public: |
| /** |
| * This method is invoked by WeaveFabricState when joining/creating a new fabric. |
| * |
| * @param[in] fabricState The WeaveFabricState which is changed |
| * @param[in] newFabricId The new fabric id |
| * |
| * @return none. |
| */ |
| virtual void DidJoinFabric(WeaveFabricState *fabricState, uint64_t newFabricId); |
| |
| /** |
| * This method is invoked by WeaveFabricState when leaving/clearing a fabric. |
| * |
| * @param[in] fabricState The WeaveFabricState which is changed |
| * @param[in] oldFabricId The old/previous fabric id |
| * |
| * @return none. |
| */ |
| virtual void DidLeaveFabric(WeaveFabricState *fabricState, uint64_t oldFabricId); |
| }; |
| |
| /** |
| * @namespace nl::Warm::Platform |
| * |
| * @brief |
| * This namespace includes all interfaces within Warm. Functions in this |
| * namespace are to be implemented by platforms that use Warm, |
| * according to the needs/constraints of the particular environment. |
| * |
| */ |
| namespace Platform { |
| /** |
| * A platform API that Warm will call as part of nl::Warm::Init execution. |
| * |
| * @note |
| * Any Platform specific initialization for Warm should be performed by this function. |
| * Initializing an object to support CriticalSectionEnter is one expected action of this API. |
| * |
| * @param[in] inFabricStateDelegate A pointer to the fabricStateDelegate object used by Warm |
| * to receive updates for the fabric state. |
| * |
| * @return WEAVE_NO_ERROR on success, error code otherwise. |
| * |
| */ |
| extern WEAVE_ERROR Init(WarmFabricStateDelegate *inFabricStateDelegate); |
| |
| /** |
| * A platform API that Warm will call to protect access to internal State. |
| * |
| * @note |
| * Compliments CriticalSectionExit. |
| * If all Warm execution occurs in a single Task context this API can be stubbed. |
| * |
| * @return none. |
| * |
| */ |
| extern void CriticalSectionEnter(void); |
| |
| /** |
| * A platform API that Warm will call to release protected access to internal State. |
| * |
| * @note |
| * Compliments CriticalSectionEnter. |
| * If all Warm execution occurs in a single Task context this API can be stubbed. |
| * |
| * @return none. |
| * |
| */ |
| extern void CriticalSectionExit(void); |
| |
| /** |
| * A platform API that Warm will call to announce that the platform should call InvokeActions. |
| * |
| * @note |
| * In order to allow Platform API's to be called from a dedicated task, Warm will call this |
| * API when it desires the Platform to call InvokeActions. If no multi-task concerns exist, |
| * the Platform can call InvokeActions directly. |
| * |
| * @return none. |
| * |
| */ |
| extern void RequestInvokeActions(void); |
| |
| /** |
| * A platform API that Warm will call to add / remove a host IP address to the specified interface on the Host TCP/IP stack. |
| * |
| * @note |
| * This function must be able to acquire access to the specified interface. |
| * |
| * @param[in] inInterfaceType The Interface to be modified. |
| * |
| * @param[in] inAddress The IP address to be added/removed. |
| * |
| * @param[in] inPrefixLength The Prefix length of the inAddress. |
| * |
| * @param[in] inAdd true to add the address, false to remove the address. |
| * |
| * @return kPlatformResultSuccess - If the operation completed successfully. |
| * @return kPlatformResultFailure - If the operation failed. |
| * @return kPlatformResultInProgress - If the operation will complete asynchronously. |
| * The platform must then call ReportActionComplete with the final result. |
| * |
| */ |
| extern PlatformResult AddRemoveHostAddress (InterfaceType inInterfaceType, const Inet::IPAddress &inAddress, uint8_t inPrefixLength, bool inAdd); |
| |
| /** |
| * A platform API that Warm will call to add / remove a IP address to the specified interface on the Thread TCP/IP stack. |
| * |
| * @note |
| * This function must be able to acquire access to the specified interface. |
| * |
| * @param[in] inInterfaceType The Interface to be modified. |
| * |
| * @param[in] inAddress The IP address to be added/removed. |
| * |
| * @param[in] inPrefixLength The Prefix length of the inAddress. |
| * |
| * @param[in] inAdd true to add the address, false to remove the address. |
| * |
| * @return kPlatformResultSuccess - If the operation completed successfully. |
| * @return kPlatformResultFailure - If the operation failed. |
| * @return kPlatformResultInProgress - If the operation will complete asynchronously. |
| * The platform must then call ReportActionComplete with the final result. |
| * |
| */ |
| extern PlatformResult AddRemoveThreadAddress (InterfaceType inInterfaceType, const Inet::IPAddress &inAddress, bool inAdd); |
| |
| /** |
| * A platform API that Warm will call to start / stop advertisement of a IP prefix on the Thread interface. |
| * |
| * @note |
| * This function must be able to acquire access to the specified interface. |
| * |
| * @param[in] inInterfaceType The Interface to be modified. |
| * |
| * @param[in] inPrefix The IP prefix for which advertising should be started / stopped. |
| * |
| * @param[in] inStart true to start advertising, false to stop advertising. |
| * |
| * @return kPlatformResultSuccess - If the operation completed successfully. |
| * @return kPlatformResultFailure - If the operation failed. |
| * @return kPlatformResultInProgress - If the operation will complete asynchronously. |
| * The platform must then call ReportActionComplete with the final result. |
| * |
| */ |
| extern PlatformResult StartStopThreadAdvertisement (InterfaceType inInterfaceType, const Inet::IPPrefix &inPrefix, bool inStart); |
| |
| /** |
| * A platform API that Warm will call to add / remove a IP route for the specified interface on the host TCP/IP stack. |
| * |
| * @note |
| * This function must be able to acquire access to the specified interface. |
| * |
| * @param[in] inInterfaceType The Interface to be modified. |
| * |
| * @param[in] inPrefix The IP prefix to add / remove. |
| * |
| * @param[in] inPriority The priority to use when the route is assigned. |
| * |
| * @param[in] inAdd true to add the prefix as a route, false to remove the prefix as a route. |
| * |
| * @return kPlatformResultSuccess - If the operation completed successfully. |
| * @return kPlatformResultFailure - If the operation failed. |
| * @return kPlatformResultInProgress - If the operation will complete asynchronously. |
| * The platform must then call ReportActionComplete with the final result. |
| * |
| */ |
| extern PlatformResult AddRemoveHostRoute (InterfaceType inInterfaceType, const Inet::IPPrefix &inPrefix, RoutePriority inPriority, bool inAdd); |
| |
| /** |
| * A platform API that Warm will call to add / remove a IP route for the specified interface on the Thread TCP/IP stack. |
| * |
| * @note |
| * This function must be able to acquire access to the specified interface. |
| * |
| * @param[in] inInterfaceType The Interface to be modified. |
| * |
| * @param[in] inPrefix The IP prefix to assign / remove. |
| * |
| * @param[in] inPriority The priority to use when the route is assigned. |
| * |
| * @param[in] inAdd true to add the prefix as a route, false to remove the prefix as a route. |
| * |
| * @return kPlatformResultSuccess - If the operation completed successfully. |
| * @return kPlatformResultFailure - If the operation failed. |
| * @return kPlatformResultInProgress - If the operation will complete asynchronously. |
| * The platform must then call ReportActionComplete with the final result. |
| */ |
| extern PlatformResult AddRemoveThreadRoute (InterfaceType inInterfaceType, const Inet::IPPrefix &inPrefix, RoutePriority inPriority, bool inAdd); |
| |
| /** |
| * A platform API that Warm will call to change the priority of an existing IP route for the specified interface on the Thread TCP/IP stack. |
| * |
| * @note |
| * This function must be able to acquire access to the specified interface. |
| * |
| * @param[in] inInterfaceType The Interface to be modified. |
| * |
| * @param[in] inPrefix The IP prefix to modify. |
| * |
| * @param[in] inPriority The new priority to apply to the route. |
| * |
| * @return kPlatformResultSuccess - If the operation completed successfully. |
| * @return kPlatformResultFailure - If the operation failed. |
| * @return kPlatformResultInProgress - If the operation will complete asynchronously. |
| * The platform must then call ReportActionComplete with the final result. |
| * |
| */ |
| extern PlatformResult SetThreadRoutePriority (InterfaceType inInterfaceType, const Inet::IPPrefix &inPrefix, RoutePriority inPriority); |
| |
| }; // namespace Platform |
| |
| /** |
| * A WARM API to perform one time module initialization. |
| * |
| * @note |
| * It must be called prior to any other nl::Warm API calls. |
| * |
| * @param[in] inFabricState A reference to a valid WeaveFabricState. |
| * |
| * @return WEAVE_NO_ERROR on success, error code otherwise. |
| * |
| */ |
| WEAVE_ERROR Init(WeaveFabricState &inFabricState); |
| |
| /** |
| * A WARM API called by a dedicated task to perform various platform API actions. |
| * |
| * @brief |
| * This represents the entry point to perform the actions necessary which will satisfy |
| * the current System State. If for example the Thread stack transitioned from |
| * disabled to enabled, then this function would make the necessary platform calls |
| * to assign the thread host address etc. This function should be called by platform |
| * code only in response to a Warm call to RequestInvokeActions. Calling InvokeActions |
| * will result in one or more calls to nl::Warm::Platform API's. |
| * Developers should therefore implement RequestInvokeActions and the caller of |
| * InvokeActions() appropriately. It might be appropriate for RequestInvokeActions to post |
| * an event to the task which would call InvokeActions() for example. Conversely, if the system |
| * is single threaded, then RequestInvokeActions could be implemented to call InvokeActions() |
| * directly. See this documentation \ref warmpage1 for more information. |
| * |
| * @return none. |
| * |
| */ |
| void InvokeActions(void); |
| |
| /** |
| * A WARM API called to announce the completion of a previous asynchronous platform API call. |
| * |
| * @brief |
| * It is assumed that platform action API's may need to perform asynchronous operations. |
| * If this is true then the platform API will return kPlatformResultInProgress. |
| * When this happens new Address and Routing Actions will be suspended until the system |
| * calls ReportActionComplete to announce the completion of the operation. |
| * |
| * @param[in] inResult The result of the pending action. must be one of: {kPlatformResultSuccess | kPlatformResultFailure} |
| * |
| * @return none. |
| * |
| */ |
| void ReportActionComplete(PlatformResult inResult); |
| |
| /** |
| * A WARM API called to announce a State change for the WiFi interface. |
| * |
| * @note |
| * Platform code should call this function when the WiFi interface transitions between up <-> down. |
| * If this call results in a change of State WARM will call RequestInvokeActions. |
| * |
| * @param[in] inState kInterfaceStateUp if the WiFi interface is up, kInterfaceStateDown otherwise. |
| * |
| * @return none. |
| * |
| */ |
| void WiFiInterfaceStateChange(InterfaceState inState); |
| |
| /** |
| * A WARM API called to announce a State change for the Thread interface. |
| * |
| * @note |
| * Platform code should call this function when the Thread interface transitions between up <-> down. |
| * If this call results in a change of State WARM will call RequestInvokeActions. |
| * |
| * @param[in] inState kInterfaceStateUp if the Thread interface is up, kInterfaceStateDown otherwise. |
| * |
| * @return none. |
| * |
| */ |
| void ThreadInterfaceStateChange(InterfaceState inState); |
| |
| /** |
| * A WARM API called to announce a State change for the Cellular interface. |
| * |
| * @note |
| * Platform code should call this function when the Cellular interface transitions between up <-> down. |
| * If this call results in a change of State WARM will call RequestInvokeActions. |
| * |
| * @param[in] inState kInterfaceStateUp if the Cellular interface is up, kInterfaceStateDown otherwise. |
| * |
| * @return none. |
| * |
| */ |
| void CellularInterfaceStateChange(InterfaceState inState); |
| |
| /** |
| * A WARM API called to announce a State change for the Thread Routing feature. |
| * |
| * @note |
| * Platform code should call this function when the ThreadRouting feature transitions between active <-> deactive. |
| * If this call results in a change of State WARM will call RequestInvokeActions. |
| * |
| * @param[in] inState kInterfaceStateUp if the Thread routing feature is up, kInterfaceStateDown otherwise. |
| * |
| * @return none. |
| * |
| */ |
| void ThreadRoutingStateChange(InterfaceState inState); |
| |
| /** |
| * A WARM API called to announce a State change for the Border router feature. |
| * |
| * @note |
| * Platform code should call this when the Border Routing feature transitions between active <-> deactive. |
| * If this call results in a change of State WARM will call RequestInvokeActions. |
| * |
| * @param[in] inState kInterfaceStateUp if the Border router feature is up, kInterfaceStateDown otherwise. |
| * |
| * @return none. |
| * |
| */ |
| void BorderRouterStateChange(InterfaceState inState); |
| |
| /** |
| * A WARM API to acquire a ULA for a specified interface type. |
| * |
| * @note |
| * Platform code should call this only after WARM has been initialized. Calling this API |
| * prior to initialization will result in an error. |
| * |
| * @param[in] inInterfaceType The type of interface for which a ULA is desired. |
| * |
| * @param[out] outAddress An address object used to hold the resulting ULA. |
| * |
| * @return WEAVE_NO_ERROR - On success. |
| * WEAVE_ERROR_INCORRECT_STATE - If this API is called while WARM is |
| * not a member of a Fabric. |
| * WEAVE_ERROR_INVALID_ARGUMENT - If this API is called with an invalid Interface Type. |
| * |
| */ |
| WEAVE_ERROR GetULA(InterfaceType inInterfaceType, Inet::IPAddress &outAddress); |
| |
| /** |
| * A WARM API to acquire the FabricState object that was provided to Warm during Init. |
| * |
| * @note |
| * Platform code should call this only after WARM has been initialized. Calling this API |
| * prior to initialization will result in an error. |
| * |
| * @param[out] outFabricState A pointer reference to a fabricState object. |
| * |
| * @return WEAVE_NO_ERROR - On success. |
| * WEAVE_ERROR_INCORRECT_STATE - If this API is called before WARM |
| * has been initialized. |
| * |
| */ |
| WEAVE_ERROR GetFabricState(const WeaveFabricState *&outFabricState); |
| |
| } /* namespace Warm */ |
| } /* namespace Weave */ |
| } /* namespace nl */ |
| |
| #endif /* WARM_H_ */ |
