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>
 */
#ifndef LR_WPAN_MAC_H
#define LR_WPAN_MAC_H

#include <ns3/object.h>
#include <ns3/traced-callback.h>
#include <ns3/mac16-address.h>
#include <ns3/mac64-address.h>
#include <ns3/sequence-number.h>
#include <ns3/lr-wpan-phy.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
} LrWpanMacState;

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;

/*
 * Table 42 of 802.15.4-2006
 */
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;

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;
  uint8_t m_msduHandle;
  uint8_t m_txOptions;  // bitmap
};

struct McpsDataConfirmParams
{
  uint8_t m_msduHandle;
  LrWpanMcpsDataConfirmStatus m_status;
};

struct McpsDataIndicationParams
{
  uint8_t m_srcAddrMode;
  uint16_t m_srcPanId;
  Mac16Address m_srcAddr;
  uint8_t m_dstAddrMode;
  uint16_t m_dstPanId;
  Mac16Address m_dstAddr;
  uint8_t m_mpduLinkQuality;
  uint8_t m_dsn;
};

// This callback is called after a McpsDataRequest has been called from
// the higher layer.  It returns a status of the outcome of the
// transmission request
typedef Callback<void, McpsDataConfirmParams> McpsDataConfirmCallback;

// This callback is called after a Mcps has successfully received a
// frame and wants to deliver it to the higher layer.
//
// XXX for now, we do not deliver all of the parameters in section
// 7.1.1.3.1 but just send up the packet.
typedef Callback<void, McpsDataIndicationParams, Ptr<Packet> > McpsDataIndicationCallback;


class LrWpanMac : public Object
{
public:
  static TypeId GetTypeId (void);

  static const uint32_t aMinMPDUOverhead;

  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 SetCsmaCa (Ptr<LrWpanCsmaCa> csmaCa);

  void SetPhy (Ptr<LrWpanPhy> phy);

  Ptr<LrWpanPhy> GetPhy (void);

  void SetMcpsDataIndicationCallback (McpsDataIndicationCallback c);

  void SetMcpsDataConfirmCallback (McpsDataConfirmCallback 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 sublayer constants
  uint64_t m_aBaseSlotDuration;

  uint64_t m_aNumSuperframeSlots;

  uint64_t m_aBaseSuperframeDuration;

  //MAC PIB attributes
  uint64_t m_macBeaconTxTime;

  uint64_t m_macSyncSymbolOffset;

  uint64_t m_macBeaconOrder;

  uint64_t m_macSuperframeOrder;

  bool m_macPromiscuousMode;

  uint16_t m_macPanId;

  SequenceNumber8 m_macDsn;

  uint8_t m_macMaxFrameRetries;

  bool m_macRxOnWhenIdle;

  uint64_t GetMacAckWaitDuration (void) const;

  uint8_t GetMacMaxFrameRetries (void) const;

  void SetMacMaxFrameRetries (uint8_t retries);

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

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

  void SendAck (uint8_t seqno);

  void RemoveFirstTxQElement ();

  void ChangeMacState (LrWpanMacState newState);

  void AckWaitTimeout (void);

  bool PrepareRetransmission (void);

  void CheckQueue (void);

  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;

  /*
   * A trace source that fires when the LrWpanMac changes states.
   * Parameters are the old mac state and the new mac state.
   */
  TracedCallback<LrWpanMacState, LrWpanMacState> m_macStateLogger;

  Ptr<LrWpanPhy> m_phy;

  Ptr<LrWpanCsmaCa> m_csmaCa;

  McpsDataIndicationCallback m_mcpsDataIndicationCallback;

  McpsDataConfirmCallback m_mcpsDataConfirmCallback;

  LrWpanMacState m_lrWpanMacState;

  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;

  uint8_t m_retransmission;

  uint8_t m_numCsmacaRetry;

  EventId m_ackWaitTimeout;

  EventId m_setMacState;
};


} // namespace ns3

#endif /* LR_WPAN_MAC_H */