message.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 MESSAGE_HPP_
#define MESSAGE_HPP_

#include "openthread-core-config.h"

#include "utils/wrap_stdint.h"
#include "utils/wrap_string.h"

#include <openthread/message.h>
#include <openthread/platform/messagepool.h>

#include "common/code_utils.hpp"
#include "common/locator.hpp"
#include "mac/mac_frame.hpp"
#include "thread/link_quality.hpp"

namespace ot {

enum
{
    kNumBuffers = OPENTHREAD_CONFIG_NUM_MESSAGE_BUFFERS,
    kBufferSize = OPENTHREAD_CONFIG_MESSAGE_BUFFER_SIZE,
};

class Message;
class MessagePool;
class MessageQueue;
class PriorityQueue;

struct MessageInfo
{
    enum
    {
        kListAll        = 0,             
        kListInterface  = 1,             
        kNumLists       = 2,             
    };

    Message         *mNext[kNumLists];   
    Message         *mPrev[kNumLists];   
    MessagePool     *mMessagePool;       
    union
    {
        MessageQueue    *mMessage;       
        PriorityQueue   *mPriority;      
    } mQueue;                            

    uint16_t         mReserved;          
    uint16_t         mLength;            
    uint16_t         mOffset;            
    uint16_t         mDatagramTag;       
    RssAverager      mRssAverager;       

    uint8_t          mChildMask[8];      
    uint8_t          mTimeout;           
    int8_t           mInterfaceId;       
    union
    {
        uint16_t     mPanId;             
        uint8_t      mChannel;           
    } mPanIdChannel;                     

    uint8_t          mType : 2;          
    uint8_t          mSubType : 4;       
    bool             mDirectTx : 1;      
    bool             mLinkSecurity : 1;  
    uint8_t          mPriority : 2;      
    bool             mInPriorityQ : 1;   
};

class Buffer : public ::otMessage
{
    friend class Message;

public:
    class Buffer *GetNextBuffer(void) const { return static_cast<Buffer *>(mNext); }

    void SetNextBuffer(class Buffer *buf) { mNext = static_cast<otMessage *>(buf); }

private:
    uint8_t *GetFirstData(void) { return mBuffer.mHead.mData; }

    const uint8_t *GetFirstData(void) const { return mBuffer.mHead.mData; }

    uint8_t *GetData(void) { return mBuffer.mData; }

    const uint8_t *GetData(void) const { return mBuffer.mData; }

    enum
    {
        kBufferDataSize = kBufferSize - sizeof(struct otMessage),
        kHeadBufferDataSize = kBufferDataSize - sizeof(struct MessageInfo),
    };

    union
    {
        struct
        {
            MessageInfo mInfo;
            uint8_t mData[kHeadBufferDataSize];
        } mHead;
        uint8_t mData[kBufferDataSize];
    } mBuffer;
};

class Message: public Buffer
{
    friend class MessagePool;
    friend class MessageQueue;
    friend class PriorityQueue;

public:
    enum
    {
        kTypeIp6         = 0,   
        kType6lowpan     = 1,   
        kTypeMacDataPoll = 2,   
        kTypeSupervision = 3,   
    };

    enum
    {
        kSubTypeNone                   = 0,  
        kSubTypeMleAnnounce            = 1,  
        kSubTypeMleDiscoverRequest     = 2,  
        kSubTypeMleDiscoverResponse    = 3,  
        kSubTypeJoinerEntrust          = 4,  
        kSubTypeMplRetransmission      = 5,  
        kSubTypeMleGeneral             = 6,  
        kSubTypeJoinerFinalizeResponse = 7,  
        kSubTypeMleChildUpdateRequest  = 8,  
    };

    enum
    {
        kPriorityHigh       = 0,    
        kPriorityMedium     = 1,    
        kPriorityLow        = 2,    
        kPriorityVeryLow    = 3,    

        kNumPriorities      = 4,    
    };

    void Free(void);

    Message *GetNext(void) const;

    uint16_t GetLength(void) const { return mBuffer.mHead.mInfo.mLength; }

    otError SetLength(uint16_t aLength);

    uint8_t GetBufferCount(void) const;

    uint16_t GetOffset(void) const { return mBuffer.mHead.mInfo.mOffset; }

    otError MoveOffset(int aDelta);

    otError SetOffset(uint16_t aOffset);

    uint8_t GetType(void) const { return mBuffer.mHead.mInfo.mType; }

    void SetType(uint8_t aType) { mBuffer.mHead.mInfo.mType = aType; }

    uint8_t GetSubType(void) const { return mBuffer.mHead.mInfo.mSubType; }

    void SetSubType(uint8_t aSubType) { mBuffer.mHead.mInfo.mSubType = aSubType; }

    bool IsSubTypeMle(void) const;

    uint8_t GetPriority(void) const { return mBuffer.mHead.mInfo.mPriority; }

    otError SetPriority(uint8_t aPriority);

    otError Prepend(const void *aBuf, uint16_t aLength);

    otError RemoveHeader(uint16_t aLength);

    otError Append(const void *aBuf, uint16_t aLength);

    uint16_t Read(uint16_t aOffset, uint16_t aLength, void *aBuf) const;

    int Write(uint16_t aOffset, uint16_t aLength, const void *aBuf);

    int CopyTo(uint16_t aSourceOffset, uint16_t aDestinationOffset, uint16_t aLength, Message &aMessage) const;

    Message *Clone(uint16_t aLength) const;

    Message *Clone(void) const { return Clone(GetLength()); };

    uint16_t GetDatagramTag(void) const { return mBuffer.mHead.mInfo.mDatagramTag; }

    void SetDatagramTag(uint16_t aTag) { mBuffer.mHead.mInfo.mDatagramTag = aTag; }

    bool GetChildMask(uint8_t aChildIndex) const;

    void ClearChildMask(uint8_t aChildIndex);

    void SetChildMask(uint8_t aChildIndex);

    bool IsChildPending(void) const;

    uint16_t GetPanId(void) const { return mBuffer.mHead.mInfo.mPanIdChannel.mPanId; }

    void SetPanId(uint16_t aPanId) { mBuffer.mHead.mInfo.mPanIdChannel.mPanId = aPanId; }

    uint8_t GetChannel(void) const { return mBuffer.mHead.mInfo.mPanIdChannel.mChannel; }

    void SetChannel(uint8_t aChannel) { mBuffer.mHead.mInfo.mPanIdChannel.mChannel = aChannel; }

    uint8_t GetTimeout(void) const { return mBuffer.mHead.mInfo.mTimeout; }

    void SetTimeout(uint8_t aTimeout) { mBuffer.mHead.mInfo.mTimeout = aTimeout; }

    int8_t GetInterfaceId(void) const { return mBuffer.mHead.mInfo.mInterfaceId; }

    void SetInterfaceId(int8_t aInterfaceId) { mBuffer.mHead.mInfo.mInterfaceId = aInterfaceId; }

    bool GetDirectTransmission(void) const { return mBuffer.mHead.mInfo.mDirectTx; }

    void ClearDirectTransmission(void) { mBuffer.mHead.mInfo.mDirectTx = false; }

    void SetDirectTransmission(void) { mBuffer.mHead.mInfo.mDirectTx = true; }

    bool IsLinkSecurityEnabled(void) const { return mBuffer.mHead.mInfo.mLinkSecurity; }

    void SetLinkSecurityEnabled(bool aEnabled) { mBuffer.mHead.mInfo.mLinkSecurity = aEnabled; }

    void AddRss(int8_t aRss) { mBuffer.mHead.mInfo.mRssAverager.Add(aRss); }

    int8_t GetAverageRss(void) const { return mBuffer.mHead.mInfo.mRssAverager.GetAverage(); }

    const RssAverager &GetRssAverager(void) const { return mBuffer.mHead.mInfo.mRssAverager; }

    static uint16_t UpdateChecksum(uint16_t aChecksum, uint16_t aValue);

    static uint16_t UpdateChecksum(uint16_t aChecksum, const void *aBuf, uint16_t aLength);

    uint16_t UpdateChecksum(uint16_t aChecksum, uint16_t aOffset, uint16_t aLength) const;

    MessageQueue *GetMessageQueue(void) const {
        return (!mBuffer.mHead.mInfo.mInPriorityQ) ? mBuffer.mHead.mInfo.mQueue.mMessage : NULL;
    }

private:

    MessagePool *GetMessagePool(void) const { return mBuffer.mHead.mInfo.mMessagePool; }

    void SetMessagePool(MessagePool *aMessagePool) { mBuffer.mHead.mInfo.mMessagePool = aMessagePool; }

    bool IsInAQueue(void) const { return (mBuffer.mHead.mInfo.mQueue.mMessage != NULL); }

    void SetMessageQueue(MessageQueue *aMessageQueue);

    PriorityQueue *GetPriorityQueue(void) const {
        return (mBuffer.mHead.mInfo.mInPriorityQ) ? mBuffer.mHead.mInfo.mQueue.mPriority : NULL;
    }

    void SetPriorityQueue(PriorityQueue *aPriorityQueue);

    Message *&Next(uint8_t aList) { return mBuffer.mHead.mInfo.mNext[aList]; }

    Message *const &Next(uint8_t aList) const { return mBuffer.mHead.mInfo.mNext[aList]; }

    Message *&Prev(uint8_t aList) { return mBuffer.mHead.mInfo.mPrev[aList]; }

    uint16_t GetReserved(void) const { return mBuffer.mHead.mInfo.mReserved; }

    void SetReserved(uint16_t aReservedHeader) { mBuffer.mHead.mInfo.mReserved = aReservedHeader; }

    otError ResizeMessage(uint16_t aLength);
};

class MessageQueue : public otMessageQueue
{
    friend class Message;
    friend class PriorityQueue;

public:

    enum QueuePosition
    {
        kQueuePositionHead,    
        kQueuePositionTail,    
    };

    MessageQueue(void);

    Message *GetHead(void) const;

    otError Enqueue(Message &aMessage) { return Enqueue(aMessage, kQueuePositionTail); }

    otError Enqueue(Message &aMessage, QueuePosition aPosition);

    otError Dequeue(Message &aMessage);

    void GetInfo(uint16_t &aMessageCount, uint16_t &aBufferCount) const;

private:

    Message *GetTail(void) const { return static_cast<Message *>(mData); }

    void SetTail(Message *aMessage) { mData = aMessage; }

    void AddToList(uint8_t aListId, Message &aMessage) { AddToList(aListId, aMessage, kQueuePositionTail); }

    void AddToList(uint8_t aListId, Message &aMessage, QueuePosition aPosition);

    void RemoveFromList(uint8_t aListId, Message &aMessage);
};

class PriorityQueue
{
    friend class Message;
    friend class MessageQueue;
    friend class MessagePool;

public:
    PriorityQueue(void);

    Message *GetHead(void) const;

    Message *GetHeadForPriority(uint8_t aPriority) const;

    otError Enqueue(Message &aMessage);

    otError Dequeue(Message &aMessage);

    void GetInfo(uint16_t &aMessageCount, uint16_t &aBufferCount) const;

private:

    Message *GetTail(void) const;

    void AddToList(uint8_t aListId, Message &aMessage);

    void RemoveFromList(uint8_t aListId, Message &aMessage);

    uint8_t PrevPriority(uint8_t aPriority) const {
        return (aPriority == 0) ? (Message::kNumPriorities - 1) : (aPriority - 1);
    }

    Message *FindFirstNonNullTail(uint8_t aStartPriorityLevel) const;

private:

    Message *mTails[Message::kNumPriorities];   
};

class MessagePool: public InstanceLocator
{
    friend class Message;
    friend class MessageQueue;
    friend class PriorityQueue;

public:

    class Iterator
    {
        friend class MessagePool;

    public:
        Iterator(void) : mMessage(NULL) { }

        Message *GetMessage(void) const { return mMessage; }

        bool IsEmpty(void) const { return (mMessage == NULL); }

        bool HasEnded(void) const { return IsEmpty(); }

        Iterator GetNext(void) const { return Iterator(Next()); }

        Iterator GetPrev(void) const { return Iterator(Prev()); }

        Iterator &GoToNext(void) { mMessage = Next(); return *this; }

        Iterator &GoToPrev(void) { mMessage = Prev(); return *this; }

    private:
        Iterator(Message *aMessage) : mMessage(aMessage) { }
        Message *Next(void) const;
        Message *Prev(void) const;

        Message *mMessage;
    };

    MessagePool(otInstance &aInstance);

    Message *New(uint8_t aType, uint16_t aReserveHeader);

    void Free(Message *aMessage);

    Iterator GetAllMessagesHead(void) const;

    Iterator GetAllMessagesTail(void) const { return Iterator(mAllQueue.GetTail()); }

#if OPENTHREAD_CONFIG_PLATFORM_MESSAGE_MANAGEMENT
    uint16_t GetFreeBufferCount(void) const { return otPlatMessagePoolNumFreeBuffers(&GetInstance()); }
#else
    uint16_t GetFreeBufferCount(void) const { return mNumFreeBuffers; }
#endif

private:
    enum
    {
        kDefaultMessagePriority = Message::kPriorityLow,
    };

    Buffer *NewBuffer(void);
    void FreeBuffers(Buffer *aBuffer);
    otError ReclaimBuffers(int aNumBuffers);
    PriorityQueue *GetAllMessagesQueue(void) { return &mAllQueue; }

#if OPENTHREAD_CONFIG_PLATFORM_MESSAGE_MANAGEMENT == 0
    uint16_t mNumFreeBuffers;
    Buffer   mBuffers[kNumBuffers];
    Buffer   *mFreeBuffers;
#endif

    PriorityQueue mAllQueue;
};

}  // namespace ot

#endif  // MESSAGE_HPP_