lr-wpan-mac.h

Go to the documentation of this file.

/* -*-  Mode: C++; c-file-style: "gnu"; indent-tabs-mode:nil; -*- */
/*
 * Copyright (c) 2011 The Boeing Company
 *
 * This program is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License version 2 as
 * published by the Free Software Foundation;
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program; if not, write to the Free Software
 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
 *
 * Authors:
 *  Gary Pei <guangyu.pei@boeing.com>
 *  kwong yin <kwong-sang.yin@boeing.com>
 *  Tom Henderson <thomas.r.henderson@boeing.com>
 *  Sascha Alexander Jopen <jopen@cs.uni-bonn.de>
 *  Alberto Gallegos Ramonet <ramonet@fc.ritsumei.ac.jp>
 */
#ifndef LR_WPAN_MAC_H
#define LR_WPAN_MAC_H

#include <ns3/object.h>
#include <ns3/traced-callback.h>
#include <ns3/traced-value.h>
#include <ns3/mac16-address.h>
#include <ns3/mac64-address.h>
#include <ns3/sequence-number.h>
#include <ns3/lr-wpan-phy.h>
#include <ns3/lr-wpan-fields.h>
#include <ns3/event-id.h>
#include <deque>


namespace ns3 {

class Packet;
class LrWpanCsmaCa;

typedef enum
{
  TX_OPTION_NONE = 0,    
  TX_OPTION_ACK = 1,     
  TX_OPTION_GTS = 2,     
  TX_OPTION_INDIRECT = 4 
} LrWpanTxOption;

typedef enum
{
  MAC_IDLE,              
  MAC_CSMA,              
  MAC_SENDING,           
  MAC_ACK_PENDING,       
  CHANNEL_ACCESS_FAILURE, 
  CHANNEL_IDLE,          
  SET_PHY_TX_ON,         
  MAC_GTS,               
  MAC_INACTIVE,          
  MAC_CSMA_DEFERRED      
} LrWpanMacState;

typedef enum
{
  BEACON,           
  CAP,              
  CFP,              
  INACTIVE          
} SuperframeStatus;

typedef enum
{
  OUTGOING = 0,   
  INCOMING = 1    
} SuperframeType;


namespace TracedValueCallback {

typedef void (*LrWpanMacState)(LrWpanMacState oldValue,
                               LrWpanMacState newValue);

typedef void (*SuperframeStatus)(SuperframeStatus oldValue,
                                 SuperframeStatus newValue);

}  // namespace TracedValueCallback

typedef enum
{
  NO_PANID_ADDR = 0,
  ADDR_MODE_RESERVED = 1,
  SHORT_ADDR = 2,
  EXT_ADDR = 3
} LrWpanAddressMode;

typedef enum
{
  ASSOCIATED = 0,
  PAN_AT_CAPACITY = 1,
  PAN_ACCESS_DENIED = 2,
  ASSOCIATED_WITHOUT_ADDRESS = 0xfe,
  DISASSOCIATED = 0xff
} LrWpanAssociationStatus;

typedef enum
{
  IEEE_802_15_4_SUCCESS                = 0,
  IEEE_802_15_4_TRANSACTION_OVERFLOW   = 1,
  IEEE_802_15_4_TRANSACTION_EXPIRED    = 2,
  IEEE_802_15_4_CHANNEL_ACCESS_FAILURE = 3,
  IEEE_802_15_4_INVALID_ADDRESS        = 4,
  IEEE_802_15_4_INVALID_GTS            = 5,
  IEEE_802_15_4_NO_ACK                 = 6,
  IEEE_802_15_4_COUNTER_ERROR          = 7,
  IEEE_802_15_4_FRAME_TOO_LONG         = 8,
  IEEE_802_15_4_UNAVAILABLE_KEY        = 9,
  IEEE_802_15_4_UNSUPPORTED_SECURITY   = 10,
  IEEE_802_15_4_INVALID_PARAMETER      = 11
} LrWpanMcpsDataConfirmStatus;

typedef enum
{
  MLMESTART_SUCCESS                = 0,
  MLMESTART_NO_SHORT_ADDRESS       = 1,
  MLMESTART_SUPERFRAME_OVERLAP     = 2,
  MLMESTART_TRACKING_OFF           = 3,
  MLMESTART_INVALID_PARAMETER      = 4,
  MLMESTART_COUNTER_ERROR          = 5,
  MLMESTART_FRAME_TOO_LONG         = 6,
  MLMESTART_UNAVAILABLE_KEY        = 7,
  MLMESTART_UNSUPPORTED_SECURITY   = 8,
  MLMESTART_CHANNEL_ACCESS_FAILURE = 9
} LrWpanMlmeStartConfirmStatus;

typedef enum
{
  MLMESYNCLOSS_PAN_ID_CONFLICT    = 0,
  MLMESYNCLOSS_REALIGMENT         = 1,
  MLMESYNCLOSS_BEACON_LOST        = 2,
  MLMESYNCLOSS_SUPERFRAME_OVERLAP = 3
} LrWpanSyncLossReason;


typedef enum
{
  MLMEPOLL_SUCCESS                = 0,
  MLMEPOLL_CHANNEL_ACCESS_FAILURE = 2,
  MLMEPOLL_NO_ACK                 = 3,
  MLMEPOLL_NO_DATA                = 4,
  MLMEPOLL_COUNTER_ERROR          = 5,
  MLMEPOLL_FRAME_TOO_LONG         = 6,
  MLMEPOLL_UNAVAILABLE_KEY        = 7,
  MLMEPOLL_UNSUPPORTED_SECURITY   = 8,
  MLMEPOLL_INVALID_PARAMETER      = 9
} LrWpanMlmePollConfirmStatus;

struct McpsDataRequestParams
{
  McpsDataRequestParams ()
    : m_srcAddrMode (SHORT_ADDR),
      m_dstAddrMode (SHORT_ADDR),
      m_dstPanId (0),
      m_dstAddr (),
      m_msduHandle (0),
      m_txOptions (0)
  {}
  LrWpanAddressMode m_srcAddrMode; 
  LrWpanAddressMode m_dstAddrMode; 
  uint16_t m_dstPanId;             
  Mac16Address m_dstAddr;          
  Mac64Address m_dstExtAddr;       
  uint8_t m_msduHandle;            
  uint8_t m_txOptions;             
};

struct McpsDataConfirmParams
{
  uint8_t m_msduHandle; 
  LrWpanMcpsDataConfirmStatus m_status; 
};
struct McpsDataIndicationParams
{
  uint8_t m_srcAddrMode;      
  uint16_t m_srcPanId;        
  Mac16Address m_srcAddr;     
  Mac64Address m_srcExtAddr;  
  uint8_t m_dstAddrMode;      
  uint16_t m_dstPanId;        
  Mac16Address m_dstAddr;     
  Mac64Address m_dstExtAddr;  
  uint8_t m_mpduLinkQuality;  
  uint8_t m_dsn;              
};
struct MlmeStartRequestParams
{
  MlmeStartRequestParams ()
    : m_PanId (0),
      m_logCh (11),
      m_logChPage (0),
      m_startTime (0),
      m_bcnOrd (15),
      m_sfrmOrd (15),
      m_panCoor (false),
      m_battLifeExt (false),
      m_coorRealgn (false)
  {}
  uint16_t m_PanId;                
  uint8_t m_logCh;                 
  uint32_t m_logChPage;            
  uint32_t m_startTime;            
  uint8_t m_bcnOrd;                
  uint8_t m_sfrmOrd;               
  bool m_panCoor;                  
  bool m_battLifeExt;              
  bool m_coorRealgn;               
};
struct MlmeSyncRequestParams
{
  MlmeSyncRequestParams ()
    : m_logCh (),
      m_trackBcn (false)
  {}
  uint8_t m_logCh;                
  bool m_trackBcn;                
};
struct MlmePollRequestParams
{
  MlmePollRequestParams ()
    : m_coorAddrMode (SHORT_ADDR),
      m_coorPanId (0),
      m_coorShortAddr (),
      m_coorExtAddr ()
  {}
  LrWpanAddressMode m_coorAddrMode; 
  uint16_t m_coorPanId;             
  Mac16Address m_coorShortAddr;     
  Mac64Address m_coorExtAddr;       


};
struct MlmeStartConfirmParams
{
  LrWpanMlmeStartConfirmStatus m_status; 
};
struct MlmeBeaconNotifyIndicationParams
{
  uint8_t m_bsn; 
  //TODO: Add other params
  //m_PanDesc;
  //m_PenAddrSpec
  //m_sduAddrList
  //m_sduLength
  //m_sdu;
};
struct MlmeSyncLossIndicationParams
{
  LrWpanSyncLossReason m_lossReason;   
  uint16_t m_panId;                    
  uint8_t  m_logCh;                    
};
struct MlmePollConfirmParams
{
  LrWpanMlmePollConfirmStatus m_status; 
};
typedef Callback<void, McpsDataConfirmParams> McpsDataConfirmCallback;
typedef Callback<void, McpsDataIndicationParams, Ptr<Packet> > McpsDataIndicationCallback;
typedef Callback<void, MlmeStartConfirmParams> MlmeStartConfirmCallback;
typedef Callback<void, MlmeBeaconNotifyIndicationParams, Ptr<Packet> > MlmeBeaconNotifyIndicationCallback;
typedef Callback<void, MlmeSyncLossIndicationParams> MlmeSyncLossIndicationCallback;
typedef Callback<void, MlmePollConfirmParams> MlmePollConfirmCallback;
class LrWpanMac : public Object
{
public:
  static TypeId GetTypeId (void);
  //MAC sublayer constants
  static const uint32_t aMinMPDUOverhead;
  static const uint32_t aBaseSlotDuration;
  static const uint32_t aNumSuperframeSlots;
  static const uint32_t aBaseSuperframeDuration;
  static const uint32_t aMaxLostBeacons;
  static const uint32_t aMaxSIFSFrameSize;
  LrWpanMac (void);
  virtual ~LrWpanMac (void);
  bool GetRxOnWhenIdle (void);
  void SetRxOnWhenIdle (bool rxOnWhenIdle);
  // XXX these setters will become obsolete if we use the attribute system
  void SetShortAddress (Mac16Address address);
  Mac16Address GetShortAddress (void) const;
  void SetExtendedAddress (Mac64Address address);
  Mac64Address GetExtendedAddress (void) const;
  void SetPanId (uint16_t panId);
  uint16_t GetPanId (void) const;
  void McpsDataRequest (McpsDataRequestParams params, Ptr<Packet> p);
  void MlmeStartRequest (MlmeStartRequestParams params);
  void MlmeSyncRequest (MlmeSyncRequestParams params);
  void MlmePollRequest (MlmePollRequestParams params);
  void SetCsmaCa (Ptr<LrWpanCsmaCa> csmaCa);
  void SetPhy (Ptr<LrWpanPhy> phy);
  Ptr<LrWpanPhy> GetPhy (void);
  void SetMcpsDataIndicationCallback (McpsDataIndicationCallback c);
  void SetMcpsDataConfirmCallback (McpsDataConfirmCallback c);
  void SetMlmeStartConfirmCallback (MlmeStartConfirmCallback c);
  void SetMlmeBeaconNotifyIndicationCallback (MlmeBeaconNotifyIndicationCallback c);
  void SetMlmeSyncLossIndicationCallback (MlmeSyncLossIndicationCallback c);
  void SetMlmePollConfirmCallback (MlmePollConfirmCallback c);

  // interfaces between MAC and PHY

  void PdDataIndication (uint32_t psduLength, Ptr<Packet> p, uint8_t lqi);
  void PdDataConfirm (LrWpanPhyEnumeration status);
  void PlmeCcaConfirm (LrWpanPhyEnumeration status);
  void PlmeEdConfirm (LrWpanPhyEnumeration status, uint8_t energyLevel);
  void PlmeGetAttributeConfirm (LrWpanPhyEnumeration status,
                                LrWpanPibAttributeIdentifier id,
                                LrWpanPhyPibAttributes* attribute);
  void PlmeSetTRXStateConfirm (LrWpanPhyEnumeration status);
  void PlmeSetAttributeConfirm (LrWpanPhyEnumeration status,
                                LrWpanPibAttributeIdentifier id);
  void SetLrWpanMacState (LrWpanMacState macState);
  LrWpanAssociationStatus GetAssociationStatus (void) const;

  void SetAssociationStatus (LrWpanAssociationStatus status);


  //MAC PIB attributes

  Time m_macBeaconTxTime;
  Time m_macBeaconRxTime;
  Mac16Address m_macCoordShortAddress;
  Mac64Address m_macCoordExtendedAddress;
  uint64_t m_macSyncSymbolOffset;
  uint8_t m_macBeaconOrder;
  uint8_t m_macSuperframeOrder;
  uint16_t m_macTransactionPersistanceTime;
  uint64_t m_rxBeaconSymbols;
  uint8_t m_fnlCapSlot;
  uint8_t m_incomingBeaconOrder;
  uint8_t m_incomingSuperframeOrder;
  uint8_t m_incomingFnlCapSlot;
  bool m_macPromiscuousMode;
  uint16_t m_macPanId;
  SequenceNumber8 m_macDsn;
  SequenceNumber8 m_macBsn;
  uint8_t m_macMaxFrameRetries;
  bool m_macRxOnWhenIdle;
  uint32_t m_macLIFSPeriod;
  uint32_t m_macSIFSPeriod;
  bool m_macAutoRequest;
  uint32_t m_ifs;
  bool m_panCoor;
  uint32_t m_beaconInterval;
  uint32_t m_superframeDuration;
  uint32_t m_incomingBeaconInterval;
  uint32_t m_incomingSuperframeDuration;
  uint8_t m_deviceCapability;
  bool m_beaconTrackingOn;
  uint8_t  m_numLostBeacons;
  uint64_t GetMacAckWaitDuration (void) const;
  uint8_t GetMacMaxFrameRetries (void) const;
  void PrintTransmitQueueSize (void);
  void SetMacMaxFrameRetries (uint8_t retries);
  bool isCoordDest (void);
  void SetAssociatedCoor (Mac16Address mac);
  void SetAssociatedCoor (Mac64Address mac);
  uint32_t GetIfsSize ();
  uint64_t GetTxPacketSymbols (void);
  bool isTxAckReq (void);
  typedef void (*SentTracedCallback)(Ptr<const Packet> packet, uint8_t retries, uint8_t backoffs);

  typedef void (*StateTracedCallback)(LrWpanMacState oldState, LrWpanMacState newState);

protected:
  // Inherited from Object.
  virtual void DoInitialize (void);
  virtual void DoDispose (void);

private:
  struct TxQueueElement
  {
    uint8_t txQMsduHandle; 
    Ptr<Packet> txQPkt;    

  };
  struct IndTxQueueElement
  {
    uint8_t txQMsduHandle; 
    Ptr<Packet> txQPkt;    
    Time expireTime;       
  };
  void SendOneBeacon (void);
  void StartCFP (SuperframeType superframeType);
  void StartCAP (SuperframeType superframeType);
  void StartInactivePeriod (SuperframeType superframeType);
  void AwaitBeacon (void);
  void BeaconSearchTimeout (void);
  void SendAck (uint8_t seqno);
  void RemoveFirstTxQElement ();
  void ChangeMacState (LrWpanMacState newState);
  void AckWaitTimeout (void);
  void IfsWaitTimeout (Time ifsTime);
  bool PrepareRetransmission (void);
  void CheckQueue (void);
  SuperframeField GetSuperframeField (void);
  GtsFields GetGtsFields (void);
  PendingAddrFields GetPendingAddrFields (void);

  TracedCallback<Time> m_macIfsEndTrace;
  TracedCallback<Ptr<const Packet>, uint8_t, uint8_t > m_sentPktTrace;
  TracedCallback<Ptr<const Packet> > m_macTxEnqueueTrace;
  TracedCallback<Ptr<const Packet> > m_macTxDequeueTrace;
  TracedCallback<Ptr<const Packet> > m_macTxTrace;
  TracedCallback<Ptr<const Packet> > m_macTxOkTrace;
  TracedCallback<Ptr<const Packet> > m_macTxDropTrace;
  TracedCallback<Ptr<const Packet> > m_macPromiscRxTrace;
  TracedCallback<Ptr<const Packet> > m_macRxTrace;
  TracedCallback<Ptr<const Packet> > m_macRxDropTrace;
  TracedCallback<Ptr<const Packet> > m_snifferTrace;

  TracedCallback<Ptr<const Packet> > m_promiscSnifferTrace;
  TracedCallback<LrWpanMacState, LrWpanMacState> m_macStateLogger;
  Ptr<LrWpanPhy> m_phy;
  Ptr<LrWpanCsmaCa> m_csmaCa;
  MlmeBeaconNotifyIndicationCallback m_mlmeBeaconNotifyIndicationCallback;
  MlmeSyncLossIndicationCallback m_mlmeSyncLossIndicationCallback;
  MlmePollConfirmCallback m_mlmePollConfirmCallback;
  MlmeStartConfirmCallback m_mlmeStartConfirmCallback;
  McpsDataIndicationCallback m_mcpsDataIndicationCallback;
  McpsDataConfirmCallback m_mcpsDataConfirmCallback;
  TracedValue<LrWpanMacState> m_lrWpanMacState;
  TracedValue<SuperframeStatus> m_incSuperframeStatus;
  TracedValue<SuperframeStatus> m_outSuperframeStatus;
  LrWpanAssociationStatus m_associationStatus;
  Ptr<Packet> m_txPkt;  // XXX need packet buffer instead of single packet
  Mac16Address m_shortAddress;
  Mac64Address m_selfExt;
  std::deque<TxQueueElement*> m_txQueue;
  std::deque<IndTxQueueElement*> m_indTxQueue;
  uint8_t m_retransmission;
  uint8_t m_numCsmacaRetry;
  EventId m_ackWaitTimeout;
  EventId m_setMacState;
  EventId m_ifsEvent;
  EventId m_beaconEvent;
  EventId m_capEvent;
  EventId m_cfpEvent;
  EventId m_incCapEvent;
  EventId m_incCfpEvent;
  EventId m_trackingEvent;
};
} // namespace ns3

#endif /* LR_WPAN_MAC_H */