mac.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 MAC_HPP_
#define MAC_HPP_

#include "openthread-core-config.h"

#include <openthread/platform/radio.h>

#include "common/context.hpp"
#include "common/locator.hpp"
#include "common/tasklet.hpp"
#include "common/timer.hpp"
#include "mac/mac_frame.hpp"
#include "mac/mac_filter.hpp"
#include "thread/key_manager.hpp"
#include "thread/network_diagnostic_tlvs.hpp"
#include "thread/topology.hpp"

namespace ot {

namespace Mle { class MleRouter; }

namespace Mac {

enum
{
    kMinBE                = 3,                     
    kMaxBE                = 5,                     
    kMaxCSMABackoffs      = 4,                     
    kUnitBackoffPeriod    = 20,                    

    kMinBackoff           = 1,                     

    kAckTimeout           = 16,                    
    kDataPollTimeout      = 100,                   
    kSleepDelay           = 300,                   
    kNonceSize            = 13,                    

    kScanChannelsAll      = OT_CHANNEL_ALL,        
    kScanDurationDefault  = 300,                   

    kDirectFrameMacTxAttempts   = OPENTHREAD_CONFIG_MAX_TX_ATTEMPTS_DIRECT,

    kIndirectFrameMacTxAttempts = OPENTHREAD_CONFIG_MAX_TX_ATTEMPTS_INDIRECT_PER_POLL,
};

class Receiver: public Context
{
    friend class Mac;

public:
    typedef void (*ReceiveFrameHandler)(Receiver &aReceiver, Frame &aFrame);

    typedef void (*DataPollTimeoutHandler)(Receiver &aReceiver);

    Receiver(ReceiveFrameHandler aReceiveFrameHandler, DataPollTimeoutHandler aPollTimeoutHandler, void *aContext):
        Context(aContext),
        mReceiveFrameHandler(aReceiveFrameHandler),
        mPollTimeoutHandler(aPollTimeoutHandler),
        mNext(NULL) {
    }

private:
    void HandleReceivedFrame(Frame &aFrame) { mReceiveFrameHandler(*this, aFrame); }

    void HandleDataPollTimeout(void) {
        if (mPollTimeoutHandler != NULL) {
            mPollTimeoutHandler(*this);
        }
    }

    ReceiveFrameHandler mReceiveFrameHandler;
    DataPollTimeoutHandler mPollTimeoutHandler;
    Receiver *mNext;
};

class Sender: public Context
{
    friend class Mac;

public:
    typedef otError(*FrameRequestHandler)(Sender &aSender, Frame &aFrame);

    typedef void (*SentFrameHandler)(Sender &aSender, Frame &aFrame, otError aError);

    Sender(FrameRequestHandler aFrameRequestHandler, SentFrameHandler aSentFrameHandler, void *aContext):
        Context(aContext),
        mFrameRequestHandler(aFrameRequestHandler),
        mSentFrameHandler(aSentFrameHandler),
        mNext(NULL) {
    }

private:
    otError HandleFrameRequest(Frame &aFrame) { return mFrameRequestHandler(*this, aFrame); }
    void HandleSentFrame(Frame &aFrame, otError aError) { mSentFrameHandler(*this, aFrame, aError); }

    FrameRequestHandler mFrameRequestHandler;
    SentFrameHandler mSentFrameHandler;
    Sender *mNext;
};

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

    typedef void (*ActiveScanHandler)(void *aContext, Frame *aBeaconFrame);

    otError ActiveScan(uint32_t aScanChannels, uint16_t aScanDuration, ActiveScanHandler aHandler, void *aContext);

    otError ConvertBeaconToActiveScanResult(Frame *aBeaconFrame, otActiveScanResult &aResult);

    typedef void (*EnergyScanHandler)(void *aContext, otEnergyScanResult *aResult);

    otError EnergyScan(uint32_t aScanChannels, uint16_t aScanDuration, EnergyScanHandler aHandler, void *aContext);

    void EnergyScanDone(int8_t aEnergyScanMaxRssi);

    bool IsBeaconEnabled(void) const { return mBeaconsEnabled; }

    void SetBeaconEnabled(bool aEnabled) { mBeaconsEnabled = aEnabled; }

    bool GetRxOnWhenIdle(void) const { return mRxOnWhenIdle; }

    void SetRxOnWhenIdle(bool aRxOnWhenIdle);

    otError RegisterReceiver(Receiver &aReceiver);

    otError SendFrameRequest(Sender &aSender);

    void GenerateExtAddress(ExtAddress *aExtAddress);

    const ExtAddress *GetExtAddress(void) const { return &mExtAddress; }

    void SetExtAddress(const ExtAddress &aExtAddress);

    ShortAddress GetShortAddress(void) const { return mShortAddress; }

    otError SetShortAddress(ShortAddress aShortAddress);

    uint8_t GetChannel(void) const { return mChannel; }

    otError SetChannel(uint8_t aChannel);

    int8_t GetMaxTransmitPower(void) const { return mMaxTransmitPower; }

    void SetMaxTransmitPower(int8_t aPower) { mMaxTransmitPower = aPower; }

    const char *GetNetworkName(void) const { return mNetworkName.m8; }

    otError SetNetworkName(const char *aNetworkName);

    uint16_t GetPanId(void) const { return mPanId; }

    otError SetPanId(uint16_t aPanId);

    const uint8_t *GetExtendedPanId(void) const { return mExtendedPanId.m8; }

    otError SetExtendedPanId(const uint8_t *aExtPanId);

#if OPENTHREAD_ENABLE_MAC_FILTER

    Filter &GetFilter(void) { return mFilter; }
#endif  // OPENTHREAD_ENABLE_MAC_FILTER

    void ReceiveDoneTask(Frame *aFrame, otError aError);

    void TransmitStartedTask(otRadioFrame *aFrame);

    void TransmitDoneTask(otRadioFrame *aFrame, otRadioFrame *aAckFrame, otError aError);

    bool IsActiveScanInProgress(void);

    bool IsEnergyScanInProgress(void);

    bool IsInTransmitState(void);

    void SetPcapCallback(otLinkPcapCallback aPcapCallback, void *aCallbackContext);

    bool IsPromiscuous(void);

    void SetPromiscuous(bool aPromiscuous);

    void FillMacCountersTlv(NetworkDiagnostic::MacCountersTlv &aMacCounters) const;

    void ResetCounters(void);

#if OPENTHREAD_CONFIG_ENABLE_BEACON_RSP_WHEN_JOINABLE

    bool IsBeaconJoinable(void);
#endif // OPENTHREAD_CONFIG_ENABLE_BEACON_RSP_WHEN_JOINABLE

    otMacCounters &GetCounters(void) { return mCounters; }

    int8_t GetNoiseFloor(void) { return otPlatRadioGetReceiveSensitivity(&GetInstance()); }

    bool RadioSupportsCsmaBackoff(void);

    bool RadioSupportsRetries(void);

private:
    enum
    {
        kInvalidRssiValue = 127
    };

    enum Operation
    {
        kOperationIdle = 0,
        kOperationActiveScan,
        kOperationEnergyScan,
        kOperationTransmitBeacon,
        kOperationTransmitData,
        kOperationWaitingForData,
    };

    void GenerateNonce(const ExtAddress &aAddress, uint32_t aFrameCounter, uint8_t aSecurityLevel, uint8_t *aNonce);
    void ProcessTransmitSecurity(Frame &aFrame);
    otError ProcessReceiveSecurity(Frame &aFrame, const Address &aSrcAddr, Neighbor *aNeighbor);
    void UpdateIdleMode(void);
    void StartOperation(Operation aOperation);
    void FinishOperation(void);
    void SentFrame(otError aError);
    void SendBeaconRequest(Frame &aFrame);
    void SendBeacon(Frame &aFrame);
    void StartBackoff(void);
    void StartEnergyScan(void);
    otError HandleMacCommand(Frame &aFrame);

    static void HandleMacTimer(Timer &aTimer);
    void HandleMacTimer(void);
    static void HandleBeginTransmit(Timer &aTimer);
    void HandleBeginTransmit(void);
    static void HandleReceiveTimer(Timer &aTimer);
    void HandleReceiveTimer(void);
    static void HandleEnergyScanSampleRssi(Tasklet &aTasklet);
    void HandleEnergyScanSampleRssi(void);

    void StartCsmaBackoff(void);
    otError Scan(Operation aScanOperation, uint32_t aScanChannels, uint16_t aScanDuration, void *aContext);

    otError RadioTransmit(Frame *aSendFrame);
    otError RadioReceive(uint8_t aChannel);
    otError RadioSleep(void);

    static Mac &GetOwner(const Context &aContext);

    static const char *OperationToString(Operation aOperation);

    Operation mOperation;

    bool mPendingActiveScan       : 1;
    bool mPendingEnergyScan       : 1;
    bool mPendingTransmitBeacon   : 1;
    bool mPendingTransmitData     : 1;
    bool mPendingWaitingForData   : 1;
    bool mRxOnWhenIdle            : 1;
    bool mBeaconsEnabled          : 1;
#if OPENTHREAD_CONFIG_STAY_AWAKE_BETWEEN_FRAGMENTS
    bool mDelaySleep              : 1;
#endif

    TimerMilli mMacTimer;
#if OPENTHREAD_CONFIG_ENABLE_PLATFORM_USEC_TIMER
    TimerMicro mBackoffTimer;
#else
    TimerMilli mBackoffTimer;
#endif
    TimerMilli mReceiveTimer;

    ExtAddress mExtAddress;
    ShortAddress mShortAddress;
    PanId mPanId;
    uint8_t mChannel;
    int8_t mMaxTransmitPower;

    otNetworkName mNetworkName;
    otExtendedPanId mExtendedPanId;

    Sender *mSendHead, *mSendTail;
    Receiver *mReceiveHead, *mReceiveTail;

    uint8_t mBeaconSequence;
    uint8_t mDataSequence;
    uint8_t mCsmaAttempts;
    uint8_t mTransmitAttempts;

    uint32_t mScanChannels;
    uint16_t mScanDuration;
    uint8_t mScanChannel;
    int8_t mEnergyScanCurrentMaxRssi;
    void *mScanContext;
    union
    {
        ActiveScanHandler mActiveScanHandler;
        EnergyScanHandler mEnergyScanHandler;
    };
    Tasklet mEnergyScanSampleRssiTask;

    otLinkPcapCallback mPcapCallback;
    void *mPcapCallbackContext;

#if OPENTHREAD_ENABLE_MAC_FILTER
    Filter mFilter;
#endif  // OPENTHREAD_ENABLE_MAC_FILTER

    Frame *mTxFrame;

    otMacCounters mCounters;
    uint32_t mKeyIdMode2FrameCounter;
};

}  // namespace Mac
}  // namespace ot

#endif  // MAC_HPP_