mle.hpp

Go to the documentation of this file.

/*
 *  Copyright (c) 2016, The OpenThread Authors.
 *  All rights reserved.
 *
 *  Redistribution and use in source and binary forms, with or without
 *  modification, are permitted provided that the following conditions are met:
 *  1. Redistributions of source code must retain the above copyright
 *     notice, this list of conditions and the following disclaimer.
 *  2. Redistributions in binary form must reproduce the above copyright
 *     notice, this list of conditions and the following disclaimer in the
 *     documentation and/or other materials provided with the distribution.
 *  3. Neither the name of the copyright holder nor the
 *     names of its contributors may be used to endorse or promote products
 *     derived from this software without specific prior written permission.
 *
 *  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
 *  AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 *  IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
 *  ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
 *  LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
 *  CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
 *  SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
 *  INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
 *  CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
 *  ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 *  POSSIBILITY OF SUCH DAMAGE.
 */

#ifndef MLE_HPP_
#define MLE_HPP_

#include "openthread-core-config.h"

#include <openthread/openthread.h>

#include "common/encoding.hpp"
#include "common/locator.hpp"
#include "common/timer.hpp"
#include "mac/mac.hpp"
#include "meshcop/joiner_router.hpp"
#include "net/udp6.hpp"
#include "thread/mle_constants.hpp"
#include "thread/mle_tlvs.hpp"
#include "thread/topology.hpp"

namespace ot {

class ThreadNetif;
class KeyManager;
class MeshForwarder;

namespace Mac { class Mac; }
namespace NetworkData { class Leader; }

namespace Mle {

class MleRouter;

enum AttachMode
{
    kAttachAny    = 0,  
    kAttachSame1  = 1,  
    kAttachSame2  = 2,  
    kAttachBetter = 3,  
};

enum AlocAllocation
{
    kAloc16Leader                       = 0xfc00,
    kAloc16DhcpAgentStart               = 0xfc01,
    kAloc16DhcpAgentEnd                 = 0xfc0f,
    kAloc16DhcpAgentMask                = 0x000f,
    kAloc16ServiceStart                 = 0xfc10,
    kAloc16ServiceEnd                   = 0xfc2f,
    kAloc16CommissionerStart            = 0xfc30,
    kAloc16CommissionerEnd              = 0xfc37,
    kAloc16NeighborDiscoveryAgentStart  = 0xfc40,
    kAloc16NeighborDiscoveryAgentEnd    = 0xfc4e,
};

enum ServiceID
{
    kServiceMinId = 0x00,  
    kServiceMaxId = 0x0f,  
};

OT_TOOL_PACKED_BEGIN
class Header
{
public:
    void Init(void) { mSecuritySuite = k154Security; mSecurityControl = Mac::Frame::kSecEncMic32; }

    bool IsValid(void) const {
        return (mSecuritySuite == kNoSecurity) ||
               (mSecuritySuite == k154Security &&
                mSecurityControl == (Mac::Frame::kKeyIdMode2 | Mac::Frame::kSecEncMic32));
    }

    uint8_t GetLength(void) const {
        uint8_t rval = sizeof(mSecuritySuite) + sizeof(mCommand);

        if (mSecuritySuite == k154Security) {
            rval += sizeof(mSecurityControl) + sizeof(mFrameCounter) + sizeof(mKeySource) + sizeof(mKeyIndex);
        }

        return rval;
    }

    enum SecuritySuite
    {
        k154Security = 0,    
        kNoSecurity  = 255,  
    };

    SecuritySuite GetSecuritySuite(void) const { return static_cast<SecuritySuite>(mSecuritySuite); }

    void SetSecuritySuite(SecuritySuite aSecuritySuite) { mSecuritySuite = static_cast<uint8_t>(aSecuritySuite); }

    uint8_t GetHeaderLength(void) const {
        return sizeof(mSecurityControl) + sizeof(mFrameCounter) + sizeof(mKeySource) + sizeof(mKeyIndex);
    }

    const uint8_t *GetBytes(void) const {
        return reinterpret_cast<const uint8_t *>(&mSecuritySuite);
    }

    uint8_t GetSecurityControl(void) const { return mSecurityControl; }

    bool IsKeyIdMode2(void) const {
        return (mSecurityControl & Mac::Frame::kKeyIdModeMask) == Mac::Frame::kKeyIdMode2;
    }

    void SetKeyIdMode2(void) {
        mSecurityControl = (mSecurityControl & ~Mac::Frame::kKeyIdModeMask) | Mac::Frame::kKeyIdMode2;
    }

    uint32_t GetKeyId(void) const {
        return Encoding::BigEndian::HostSwap32(mKeySource);
    }

    void SetKeyId(uint32_t aKeySequence) {
        mKeySource = Encoding::BigEndian::HostSwap32(aKeySequence);
        mKeyIndex = (aKeySequence & 0x7f) + 1;
    }

    uint32_t GetFrameCounter(void) const {
        return Encoding::LittleEndian::HostSwap32(mFrameCounter);
    }

    void SetFrameCounter(uint32_t aFrameCounter) {
        mFrameCounter = Encoding::LittleEndian::HostSwap32(aFrameCounter);
    }

    enum Command
    {
        kCommandLinkRequest          = 0,    
        kCommandLinkAccept           = 1,    
        kCommandLinkAcceptAndRequest = 2,    
        kCommandLinkReject           = 3,    
        kCommandAdvertisement        = 4,    
        kCommandUpdate               = 5,    
        kCommandUpdateRequest        = 6,    
        kCommandDataRequest          = 7,    
        kCommandDataResponse         = 8,    
        kCommandParentRequest        = 9,    
        kCommandParentResponse       = 10,   
        kCommandChildIdRequest       = 11,   
        kCommandChildIdResponse      = 12,   
        kCommandChildUpdateRequest   = 13,   
        kCommandChildUpdateResponse  = 14,   
        kCommandAnnounce             = 15,   
        kCommandDiscoveryRequest     = 16,   
        kCommandDiscoveryResponse    = 17,   
    };

    Command GetCommand(void) const {
        if (mSecuritySuite == kNoSecurity) {
            return static_cast<Command>(mSecurityControl);
        }
        else {
            return static_cast<Command>(mCommand);
        }
    }

    void SetCommand(Command aCommand) {
        if (mSecuritySuite == kNoSecurity) {
            mSecurityControl = static_cast<uint8_t>(aCommand);
        }
        else {
            mCommand = static_cast<uint8_t>(aCommand);
        }
    }

private:
    uint8_t mSecuritySuite;
    uint8_t mSecurityControl;
    uint32_t mFrameCounter;
    uint32_t mKeySource;
    uint8_t mKeyIndex;
    uint8_t mCommand;
} OT_TOOL_PACKED_END;

OT_TOOL_PACKED_BEGIN
class DelayedResponseHeader
{
public:
    DelayedResponseHeader(void) { memset(this, 0, sizeof(*this)); };

    DelayedResponseHeader(uint32_t aSendTime, const Ip6::Address &aDestination) {
        mSendTime = aSendTime;
        mDestination = aDestination;
    };

    otError AppendTo(Message &aMessage) {
        return aMessage.Append(this, sizeof(*this));
    };

    uint16_t ReadFrom(Message &aMessage) {
        return aMessage.Read(aMessage.GetLength() - sizeof(*this), sizeof(*this), this);
    };

    static otError RemoveFrom(Message &aMessage) {
        return aMessage.SetLength(aMessage.GetLength() - sizeof(DelayedResponseHeader));
    };

    uint32_t GetSendTime(void) const { return mSendTime; };

    const Ip6::Address &GetDestination(void) const { return mDestination; };

    bool IsEarlier(uint32_t aTime) { return (static_cast<int32_t>(aTime - mSendTime) > 0); };

    bool IsLater(uint32_t aTime) { return (static_cast<int32_t>(aTime - mSendTime) < 0); };

private:
    Ip6::Address mDestination;  
    uint32_t mSendTime;         
} OT_TOOL_PACKED_END;

class Mle: public InstanceLocator
{
public:
    explicit Mle(otInstance &aInstance);

    otError Enable(void);

    otError Disable(void);

    otError Start(bool aEnableReattach, bool aAnnounceAttach);

    otError Stop(bool aClearNetworkDatasets);

    otError Restore(void);

    otError Store(void);

    typedef void (*DiscoverHandler)(otActiveScanResult *aResult, void *aContext);

    otError Discover(uint32_t aScanChannels, uint16_t aPanId, bool aJoiner, bool aEnableEui64Filtering,
                     DiscoverHandler aCallback,
                     void *aContext);

    bool IsDiscoverInProgress(void);

    void HandleDiscoverComplete(void);

    otError SendAnnounce(uint8_t aChannel, bool aOrphanAnnounce);

    otError BecomeDetached(void);

    otError BecomeChild(AttachMode aMode);

    bool IsAttached(void) const;

    otDeviceRole GetRole(void) const { return mRole; }

    uint8_t GetDeviceMode(void) const { return mDeviceMode; }

    bool IsMinimalEndDevice(void) const {
        return (mDeviceMode & (ModeTlv::kModeFFD | ModeTlv::kModeRxOnWhenIdle)) !=
               (ModeTlv::kModeFFD | ModeTlv::kModeRxOnWhenIdle);
    }

    otError SetDeviceMode(uint8_t aMode);

    const uint8_t *GetMeshLocalPrefix(void) const;

    otError SetMeshLocalPrefix(const uint8_t *aPrefix);

    const Ip6::Address &GetLinkLocalAddress(void) const;

    otError UpdateLinkLocalAddress(void);

    const Ip6::Address *GetLinkLocalAllThreadNodesAddress(void) const;

    const Ip6::Address *GetRealmLocalAllThreadNodesAddress(void) const;

    Router *GetParent(void);

    bool IsRoutingLocator(const Ip6::Address &aAddress) const;

    bool IsAnycastLocator(const Ip6::Address &aAddress) const;

    bool IsMeshLocalAddress(const Ip6::Address &aAddress) const;

    uint32_t GetTimeout(void) const { return mTimeout; }

    otError SetTimeout(uint32_t aTimeout);

    uint16_t GetRloc16(void) const;

    const Ip6::Address &GetMeshLocal16(void) const;

    const Ip6::Address &GetMeshLocal64(void) const;

    uint8_t GetLeaderId(void) const;

    otError GetLeaderAddress(Ip6::Address &aAddress) const;

    otError GetLeaderAloc(Ip6::Address &aAddress) const;

#if OPENTHREAD_ENABLE_SERVICE

    otError GetServiceAloc(uint8_t aServiceId, Ip6::Address &aAddress) const;
#endif

    otError AddLeaderAloc(void);

    const LeaderDataTlv &GetLeaderDataTlv(void);

    otError GetLeaderData(otLeaderData &aLeaderData);

    static uint16_t GetChildId(uint16_t aRloc16) { return aRloc16 & kMaxChildId; }

    static uint8_t GetRouterId(uint16_t aRloc16) { return aRloc16 >> kRouterIdOffset; }

    static uint8_t GetServiceIdFromAloc(uint16_t aAloc16) { return static_cast<uint8_t>(aAloc16 - kAloc16ServiceStart); }

    static uint16_t GetServiceAlocFromId(uint8_t aServiceId) { return static_cast<uint16_t>(aServiceId + kAloc16ServiceStart); }

    static uint16_t GetRloc16(uint8_t aRouterId) { return static_cast<uint16_t>(aRouterId << kRouterIdOffset); }

    static bool IsActiveRouter(uint16_t aRloc16) { return GetChildId(aRloc16) == 0; }

    void FillNetworkDataTlv(NetworkDataTlv &aTlv, bool aStableOnly);

    const MessageQueue &GetMessageQueue(void) const { return mDelayedResponses; }

protected:
    enum
    {
        kMleMaxResponseDelay = 1000u,  
    };

    Message *NewMleMessage(void);

    otError AppendHeader(Message &aMessage, Header::Command aCommand);

    otError AppendSourceAddress(Message &aMessage);

    otError AppendMode(Message &aMessage, uint8_t aMode);

    otError AppendTimeout(Message &aMessage, uint32_t aTimeout);

    otError AppendChallenge(Message &aMessage, const uint8_t *aChallenge, uint8_t aChallengeLength);

    otError AppendResponse(Message &aMessage, const uint8_t *aResponse, uint8_t aResponseLength);

    otError AppendLinkFrameCounter(Message &aMessage);

    otError AppendMleFrameCounter(Message &aMessage);

    otError AppendAddress16(Message &aMessage, uint16_t aRloc16);

    otError AppendNetworkData(Message &aMessage, bool aStableOnly);

    otError AppendTlvRequest(Message &aMessage, const uint8_t *aTlvs, uint8_t aTlvsLength);

    otError AppendLeaderData(Message &aMessage);

    otError AppendScanMask(Message &aMessage, uint8_t aScanMask);

    otError AppendStatus(Message &aMessage, StatusTlv::Status aStatus);

    otError AppendLinkMargin(Message &aMessage, uint8_t aLinkMargin);

    otError AppendVersion(Message &aMessage);

    otError AppendAddressRegistration(Message &aMessage);

    otError AppendActiveTimestamp(Message &aMessage);

    otError AppendPendingTimestamp(Message &aMessage);

    otError CheckReachability(uint16_t aMeshSource, uint16_t aMeshDest, Ip6::Header &aIp6Header);

    Neighbor *GetNeighbor(const Mac::Address &aAddress);

    Neighbor *GetNeighbor(Mac::ShortAddress aAddress);

    Neighbor *GetNeighbor(const Mac::ExtAddress &aAddress);

    Neighbor *GetNeighbor(const Ip6::Address &aAddress) { OT_UNUSED_VARIABLE(aAddress); return NULL; }

    Mac::ShortAddress GetNextHop(uint16_t aDestination) const;

    otError SendDataRequest(const Ip6::Address &aDestination, const uint8_t *aTlvs, uint8_t aTlvsLength,
                            uint16_t aDelay);

    otError SendChildUpdateRequest(void);

    otError SendChildUpdateResponse(const uint8_t *aTlvs, uint8_t aNumTlvs, const ChallengeTlv &aChallenge);

    otError SendMessage(Message &aMessage, const Ip6::Address &aDestination);

    otError SetRloc16(uint16_t aRloc16);

    otError SetStateDetached(void);

    otError SetStateChild(uint16_t aRloc16);

    void SetLeaderData(uint32_t aPartitionId, uint8_t aWeighting, uint8_t aLeaderRouterId);

    otError AddDelayedResponse(Message &aMessage, const Ip6::Address &aDestination, uint16_t aDelay);

    void LogMleMessage(const char *aLogMessage, const Ip6::Address &aAddress) const;

    void LogMleMessage(const char *aLogMessage, const Ip6::Address &aAddress, uint16_t aRloc) const;

    LeaderDataTlv mLeaderData;              
    bool mRetrieveNewNetworkData;           

    otDeviceRole mRole;                     
    Router mParent;                         
    uint8_t mDeviceMode;                    

    enum ParentRequestState
    {
        kParentIdle,           
        kParentSynchronize,    
        kParentRequestStart,   
        kParentRequestRouter,  
        kParentRequestChild,   
        kChildIdRequest,       
    };
    ParentRequestState mParentRequestState;  

    enum ReattachState
    {
        kReattachStop       = 0,   
        kReattachStart      = 1,   
        kReattachActive     = 2,   
        kReattachPending    = 3,   
    };
    ReattachState mReattachState;

    TimerMilli mParentRequestTimer;          
    TimerMilli mDelayedResponseTimer;        
    TimerMilli mChildUpdateRequestTimer;     
    uint32_t mLastPartitionId;               
    uint8_t mLastPartitionRouterIdSequence;  
    uint8_t mLastPartitionIdTimeout;         

    uint8_t mParentLeaderCost;

private:
    enum
    {
        kMleMessagePriority = Message::kPriorityHigh,
        kMleHopLimit        = 255,
    };

    void GenerateNonce(const Mac::ExtAddress &aMacAddr, uint32_t aFrameCounter, uint8_t aSecurityLevel,
                       uint8_t *aNonce);

    static void HandleNetifStateChanged(uint32_t aFlags, void *aContext);
    void HandleNetifStateChanged(uint32_t aFlags);
    static void HandleParentRequestTimer(Timer &aTimer);
    void HandleParentRequestTimer(void);
    static void HandleDelayedResponseTimer(Timer &aTimer);
    void HandleDelayedResponseTimer(void);
    static void HandleChildUpdateRequestTimer(Timer &aTimer);
    void HandleChildUpdateRequestTimer(void);
    static void HandleUdpReceive(void *aContext, otMessage *aMessage, const otMessageInfo *aMessageInfo);
    void HandleUdpReceive(Message &aMessage, const Ip6::MessageInfo &aMessageInfo);
    static void HandleSendChildUpdateRequest(Tasklet &aTasklet);
    void HandleSendChildUpdateRequest(void);

    otError HandleAdvertisement(const Message &aMessage, const Ip6::MessageInfo &aMessageInfo);
    otError HandleChildIdResponse(const Message &aMessage, const Ip6::MessageInfo &aMessageInfo);
    otError HandleChildUpdateRequest(const Message &aMessage, const Ip6::MessageInfo &aMessageInfo);
    otError HandleChildUpdateResponse(const Message &aMessage, const Ip6::MessageInfo &aMessageInfo);
    otError HandleDataResponse(const Message &aMessage, const Ip6::MessageInfo &aMessageInfo);
    otError HandleParentResponse(const Message &aMessage, const Ip6::MessageInfo &aMessageInfo,
                                 uint32_t aKeySequence);
    otError HandleAnnounce(const Message &aMessage, const Ip6::MessageInfo &aMessageInfo);
    otError HandleDiscoveryResponse(const Message &aMessage, const Ip6::MessageInfo &aMessageInfo);
    otError HandleLeaderData(const Message &aMessage, const Ip6::MessageInfo &aMessageInfo);

    otError SendParentRequest(void);
    otError SendChildIdRequest(void);
    void SendOrphanAnnounce(void);

    bool IsBetterParent(uint16_t aRloc16, uint8_t aLinkQuality, uint8_t aLinkMargin,
                        ConnectivityTlv &aConnectivityTlv);
    void ResetParentCandidate(void);

#if OPENTHREAD_ENABLE_SERVICE

    void UpdateServiceAlocs(void);
#endif

#if OPENTHREAD_CONFIG_INFORM_PREVIOUS_PARENT_ON_REATTACH
    otError InformPreviousParent(void);
#endif

    static Mle &GetOwner(const Context &aContext);

    MessageQueue mDelayedResponses;

    struct
    {
        uint8_t mChallenge[ChallengeTlv::kMaxSize];
        uint8_t mChallengeLength;
    } mChildIdRequest;

    struct
    {
        uint8_t mChallenge[ChallengeTlv::kMaxSize];
    } mParentRequest;

    AttachMode mParentRequestMode;
    int8_t mParentPriority;
    uint8_t mParentLinkQuality3;
    uint8_t mParentLinkQuality2;
    uint8_t mParentLinkQuality1;
    uint8_t mChildUpdateAttempts;
    LeaderDataTlv mParentLeaderData;
    uint8_t mParentLinkMargin;
    bool mParentIsSingleton;

    Router mParentCandidate;

    Ip6::UdpSocket mSocket;
    uint32_t mTimeout;

    Tasklet mSendChildUpdateRequest;

    DiscoverHandler mDiscoverHandler;
    void *mDiscoverContext;
    bool mIsDiscoverInProgress;
    bool mEnableEui64Filtering;

#if OPENTHREAD_CONFIG_INFORM_PREVIOUS_PARENT_ON_REATTACH
    uint16_t mPreviousParentRloc;
#endif

    uint8_t mAnnounceChannel;
    uint8_t mPreviousChannel;
    uint16_t mPreviousPanId;

    Ip6::NetifUnicastAddress mLeaderAloc;

#if OPENTHREAD_ENABLE_SERVICE
    Ip6::NetifUnicastAddress mServiceAlocs[OPENTHREAD_CONFIG_MAX_SERVER_ALOCS];
#endif

    Ip6::NetifUnicastAddress mLinkLocal64;
    Ip6::NetifUnicastAddress mMeshLocal64;
    Ip6::NetifUnicastAddress mMeshLocal16;
    Ip6::NetifMulticastAddress mLinkLocalAllThreadNodes;
    Ip6::NetifMulticastAddress mRealmLocalAllThreadNodes;

    Ip6::NetifCallback mNetifCallback;
};

}  // namespace Mle

}  // namespace ot

#endif  // MLE_HPP_