A Discrete-Event Network Simulator
API
lr-wpan-mac.h
Go to the documentation of this file.
1 /* -*- Mode: C++; c-file-style: "gnu"; indent-tabs-mode:nil; -*- */
2 /*
3  * Copyright (c) 2011 The Boeing Company
4  *
5  * This program is free software; you can redistribute it and/or modify
6  * it under the terms of the GNU General Public License version 2 as
7  * published by the Free Software Foundation;
8  *
9  * This program is distributed in the hope that it will be useful,
10  * but WITHOUT ANY WARRANTY; without even the implied warranty of
11  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12  * GNU General Public License for more details.
13  *
14  * You should have received a copy of the GNU General Public License
15  * along with this program; if not, write to the Free Software
16  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
17  *
18  * Authors:
19  * Gary Pei <guangyu.pei@boeing.com>
20  * kwong yin <kwong-sang.yin@boeing.com>
21  * Tom Henderson <thomas.r.henderson@boeing.com>
22  * Sascha Alexander Jopen <jopen@cs.uni-bonn.de>
23  */
24 #ifndef LR_WPAN_MAC_H
25 #define LR_WPAN_MAC_H
26 
27 #include <ns3/object.h>
28 #include <ns3/traced-callback.h>
29 #include <ns3/traced-value.h>
30 #include <ns3/mac16-address.h>
31 #include <ns3/mac64-address.h>
32 #include <ns3/sequence-number.h>
33 #include <ns3/lr-wpan-phy.h>
34 #include <ns3/event-id.h>
35 #include <deque>
36 
37 
38 namespace ns3 {
39 
40 class Packet;
41 class LrWpanCsmaCa;
42 
54 typedef enum
55 {
61 
67 typedef enum
68 {
77 
78 namespace TracedValueCallback {
79 
87  typedef void (* LrWpanMacState)(LrWpanMacState oldValue,
88  LrWpanMacState newValue);
89 
90 } // namespace TracedValueCallback
91 
97 typedef enum
98 {
104 
110 typedef enum
111 {
118 
124 typedef enum
125 {
139 
140 
147 {
151  m_dstPanId (0),
152  m_dstAddr (),
153  m_msduHandle (0),
154  m_txOptions (0)
155  {
156  }
159  uint16_t m_dstPanId;
162  uint8_t m_msduHandle;
163  uint8_t m_txOptions;
164 };
165 
172 {
173  uint8_t m_msduHandle;
175 };
176 
183 {
184  uint8_t m_srcAddrMode;
185  uint16_t m_srcPanId;
188  uint8_t m_dstAddrMode;
189  uint16_t m_dstPanId;
193  uint8_t m_dsn;
194 };
195 
204 
215 
216 
222 class LrWpanMac : public Object
223 {
224 public:
230  static TypeId GetTypeId (void);
231 
236  static const uint32_t aMinMPDUOverhead;
237 
241  LrWpanMac (void);
242  virtual ~LrWpanMac (void);
243 
249  bool GetRxOnWhenIdle (void);
250 
256  void SetRxOnWhenIdle (bool rxOnWhenIdle);
257 
258  // XXX these setters will become obsolete if we use the attribute system
265 
271  Mac16Address GetShortAddress (void) const;
272 
279 
285  Mac64Address GetExtendedAddress (void) const;
286 
292  void SetPanId (uint16_t panId);
293 
299  uint16_t GetPanId (void) const;
300 
310 
316  void SetCsmaCa (Ptr<LrWpanCsmaCa> csmaCa);
317 
323  void SetPhy (Ptr<LrWpanPhy> phy);
324 
330  Ptr<LrWpanPhy> GetPhy (void);
331 
340 
349 
350  // interfaces between MAC and PHY
359  void PdDataIndication (uint32_t psduLength, Ptr<Packet> p, uint8_t lqi);
360 
367  void PdDataConfirm (LrWpanPhyEnumeration status);
368 
374  void PlmeCcaConfirm (LrWpanPhyEnumeration status);
375 
382  void PlmeEdConfirm (LrWpanPhyEnumeration status, uint8_t energyLevel);
383 
394  LrWpanPhyPibAttributes* attribute);
395 
403 
413 
419  void SetLrWpanMacState (LrWpanMacState macState);
420 
427 
434 
435  //MAC sublayer constants
442 
448 
455 
456  //MAC PIB attributes
463 
469 
476 
484 
491 
497  uint16_t m_macPanId;
498 
504 
510 
517 
523  uint64_t GetMacAckWaitDuration (void) const;
524 
530  uint8_t GetMacMaxFrameRetries (void) const;
531 
537  void SetMacMaxFrameRetries (uint8_t retries);
538 
546  typedef void (* SentTracedCallback)
547  (Ptr<const Packet> packet, uint8_t retries, uint8_t backoffs);
548 
558  typedef void (* StateTracedCallback)
559  (LrWpanMacState oldState, LrWpanMacState newState);
560 
561 protected:
562  // Inherited from Object.
563  virtual void DoInitialize (void);
564  virtual void DoDispose (void);
565 
566 private:
571  {
572  uint8_t txQMsduHandle;
574  };
575 
581  void SendAck (uint8_t seqno);
582 
587  void RemoveFirstTxQElement ();
588 
594  void ChangeMacState (LrWpanMacState newState);
595 
600  void AckWaitTimeout (void);
601 
608  bool PrepareRetransmission (void);
609 
615  void CheckQueue (void);
616 
628 
636 
644 
651 
660 
668 
677 
686 
695 
715 
735 
745 
750 
755 
761 
768 
773 
778 
782  Ptr<Packet> m_txPkt; // XXX need packet buffer instead of single packet
783 
790 
796 
800  std::deque<TxQueueElement*> m_txQueue;
801 
807 
812 
818 
823 };
824 
825 
826 } // namespace ns3
827 
828 #endif /* LR_WPAN_MAC_H */
TracedValue< LrWpanMacState > m_lrWpanMacState
The current state of the MAC layer.
Definition: lr-wpan-mac.h:772
uint16_t m_dstPanId
Destination PAN identifier.
Definition: lr-wpan-mac.h:159
TX_OPTION_INDIRECT.
Definition: lr-wpan-mac.h:59
uint64_t m_aBaseSuperframeDuration
Length of a superframe in symbols.
Definition: lr-wpan-mac.h:454
void CheckQueue(void)
Check the transmission queue.
Definition: lr-wpan-mac.cc:447
Class that implements the LR-WPAN Mac state machine.
Definition: lr-wpan-mac.h:222
void PlmeGetAttributeConfirm(LrWpanPhyEnumeration status, LrWpanPibAttributeIdentifier id, LrWpanPhyPibAttributes *attribute)
IEEE 802.15.4-2006 section 6.2.2.6 PLME-GET.confirm Get attributes per definition from Table 23 in se...
Definition: lr-wpan-mac.cc:935
Mac16Address m_dstAddr
Destination address.
Definition: lr-wpan-mac.h:160
void RemoveFirstTxQElement()
Remove the tip of the transmission queue, including clean up related to the last packet transmission...
Definition: lr-wpan-mac.cc:767
Mac64Address m_srcExtAddr
Source extended address.
Definition: lr-wpan-mac.h:187
virtual ~LrWpanMac(void)
Definition: lr-wpan-mac.cc:155
TracedCallback< Ptr< const Packet > > m_macTxOkTrace
The trace source fired when packets where successfully transmitted, that is an acknowledgment was rec...
Definition: lr-wpan-mac.h:659
LrWpanPibAttributeIdentifier
IEEE802.15.4-2006 PHY PIB Attribute Identifiers Table 23 in section 6.4.2.
Definition: lr-wpan-phy.h:140
CHANNEL_IDLE.
Definition: lr-wpan-mac.h:74
Forward calls to a chain of Callback.
McpsDataConfirmCallback m_mcpsDataConfirmCallback
This callback is used to report data transmission request status to the upper layers.
Definition: lr-wpan-mac.h:767
std::deque< TxQueueElement * > m_txQueue
The transmit queue used by the MAC.
Definition: lr-wpan-mac.h:800
Mac64Address GetExtendedAddress(void) const
Get the extended address of this MAC.
Definition: lr-wpan-mac.cc:244
Mac16Address m_dstAddr
Destination address.
Definition: lr-wpan-mac.h:190
uint8_t m_dstAddrMode
Destination address mode.
Definition: lr-wpan-mac.h:188
Mac64Address m_dstExtAddr
Destination extended address.
Definition: lr-wpan-mac.h:191
LrWpanAssociationStatus m_associationStatus
The current association status of the MAC layer.
Definition: lr-wpan-mac.h:777
Mac64Address m_dstExtAddr
Destination extended address.
Definition: lr-wpan-mac.h:161
virtual void DoDispose(void)
Destructor implementation.
Definition: lr-wpan-mac.cc:175
TracedCallback< LrWpanMacState, LrWpanMacState > m_macStateLogger
A trace source that fires when the LrWpanMac changes states.
Definition: lr-wpan-mac.h:744
void SetShortAddress(Mac16Address address)
Set the short address of this MAC.
Definition: lr-wpan-mac.cc:222
IEEE802.15.4-2006 PHY PIB Attributes Table 23 in section 6.4.2.
Definition: lr-wpan-phy.h:157
McpsDataIndicationCallback m_mcpsDataIndicationCallback
This callback is used to notify incoming packets to the upper layers.
Definition: lr-wpan-mac.h:760
void SetMcpsDataConfirmCallback(McpsDataConfirmCallback c)
Set the callback for the confirmation of a data transmission request.
Definition: lr-wpan-mac.cc:485
void McpsDataRequest(McpsDataRequestParams params, Ptr< Packet > p)
IEEE 802.15.4-2006, section 7.1.1.1 MCPS-DATA.request Request to transfer a MSDU. ...
Definition: lr-wpan-mac.cc:250
uint8_t m_numCsmacaRetry
The number of CSMA/CA retries used for sending the current packet.
Definition: lr-wpan-mac.h:811
uint8_t m_msduHandle
MSDU handle.
Definition: lr-wpan-mac.h:162
uint8_t m_msduHandle
MSDU handle.
Definition: lr-wpan-mac.h:173
uint16_t m_dstPanId
Destination PAN identifier.
Definition: lr-wpan-mac.h:189
TracedCallback< Ptr< const Packet > > m_macTxTrace
The trace source fired when packets are being sent down to L1.
Definition: lr-wpan-mac.h:650
an EUI-64 address
Definition: mac64-address.h:43
phy
Definition: third.py:93
Ptr< Packet > m_txPkt
The packet which is currently being sent by the MAC layer.
Definition: lr-wpan-mac.h:782
bool GetRxOnWhenIdle(void)
Check if the receiver will be enabled when the MAC is idle.
Definition: lr-wpan-mac.cc:197
LrWpanAssociationStatus GetAssociationStatus(void) const
Get the current association status.
void SetLrWpanMacState(LrWpanMacState macState)
CSMA-CA algorithm calls back the MAC after executing channel assessment.
Definition: lr-wpan-mac.cc:988
uint64_t m_macBeaconOrder
Specification of how often the coordinator transmits its beacon.
Definition: lr-wpan-mac.h:475
void SetMacMaxFrameRetries(uint8_t retries)
Set the macMaxFrameRetries attribute value.
void PlmeEdConfirm(LrWpanPhyEnumeration status, uint8_t energyLevel)
IEEE 802.15.4-2006 section 6.2.2.4 PLME-ED.confirm status and energy level.
Definition: lr-wpan-mac.cc:928
TracedCallback< Ptr< const Packet > > m_promiscSnifferTrace
A trace source that emulates a promiscuous mode protocol sniffer connected to the device...
Definition: lr-wpan-mac.h:734
TX_OPTION_ACK.
Definition: lr-wpan-mac.h:57
TracedCallback< Ptr< const Packet > > m_macTxEnqueueTrace
The trace source fired when packets come into the "top" of the device at the L3/L2 transition...
Definition: lr-wpan-mac.h:635
TracedCallback< Ptr< const Packet > > m_macRxTrace
The trace source fired for packets successfully received by the device immediately before being forwa...
Definition: lr-wpan-mac.h:685
uint64_t m_macSyncSymbolOffset
Symbol boundary is same as m_macBeaconTxTime.
Definition: lr-wpan-mac.h:468
Ptr< Packet > txQPkt
Queued packet.
Definition: lr-wpan-mac.h:573
bool PrepareRetransmission(void)
Check for remaining retransmissions for the packet currently being sent.
Definition: lr-wpan-mac.cc:809
void PlmeCcaConfirm(LrWpanPhyEnumeration status)
IEEE 802.15.4-2006 section 6.2.2.2 PLME-CCA.confirm status.
Definition: lr-wpan-mac.cc:920
EventId m_ackWaitTimeout
Scheduler event for the ACK timeout of the currently transmitted data packet.
Definition: lr-wpan-mac.h:817
TracedCallback< Ptr< const Packet > > m_macTxDropTrace
The trace source fired when packets are dropped due to missing ACKs or because of transmission failur...
Definition: lr-wpan-mac.h:667
uint16_t GetPanId(void) const
Get the PAN id used by this MAC.
EventId m_setMacState
Scheduler event for a deferred MAC state change.
Definition: lr-wpan-mac.h:822
LrWpanMcpsDataConfirmStatus
Table 42 of 802.15.4-2006.
Definition: lr-wpan-mac.h:124
Helper structure for managing transmission queue elements.
Definition: lr-wpan-mac.h:570
bool m_macRxOnWhenIdle
Indication of whether the MAC sublayer is to enable its receiver during idle periods.
Definition: lr-wpan-mac.h:516
uint64_t m_macBeaconTxTime
The time that the device transmitted its last beacon frame, in symbol periods.
Definition: lr-wpan-mac.h:462
MCPS-DATA.confirm params.
Definition: lr-wpan-mac.h:171
void PdDataConfirm(LrWpanPhyEnumeration status)
IEEE 802.15.4-2006 section 6.2.1.2 Confirm the end of transmission of an MPDU to MAC.
Definition: lr-wpan-mac.cc:839
uint8_t m_txOptions
Tx Options (bitfield)
Definition: lr-wpan-mac.h:163
SET_PHY_TX_ON.
Definition: lr-wpan-mac.h:75
uint8_t m_mpduLinkQuality
LQI value measured during reception of the MPDU.
Definition: lr-wpan-mac.h:192
void SetPhy(Ptr< LrWpanPhy > phy)
Set the underlying PHY for the MAC.
Definition: lr-wpan-mac.cc:467
TracedCallback< Ptr< const Packet >, uint8_t, uint8_t > m_sentPktTrace
The trace source fired when packets are considered as successfully sent or the transmission has been ...
Definition: lr-wpan-mac.h:627
void PdDataIndication(uint32_t psduLength, Ptr< Packet > p, uint8_t lqi)
IEEE 802.15.4-2006 section 6.2.1.3 PD-DATA.indication Indicates the transfer of an MPDU from PHY to M...
Definition: lr-wpan-mac.cc:491
uint8_t m_srcAddrMode
Source address mode.
Definition: lr-wpan-mac.h:184
LrWpanMcpsDataConfirmStatus m_status
The status of the last MSDU transmission.
Definition: lr-wpan-mac.h:174
LrWpanAddressMode m_srcAddrMode
Source address mode.
Definition: lr-wpan-mac.h:157
uint8_t m_retransmission
The number of already used retransmission for the currently transmitted packet.
Definition: lr-wpan-mac.h:806
Callback< void, McpsDataIndicationParams, Ptr< Packet > > McpsDataIndicationCallback
This callback is called after a Mcps has successfully received a frame and wants to deliver it to the...
Definition: lr-wpan-mac.h:214
Mac64Address m_selfExt
The extended address used by this MAC.
Definition: lr-wpan-mac.h:795
uint64_t GetMacAckWaitDuration(void) const
Get the macAckWaitDuration attribute value.
Every class exported by the ns3 library is enclosed in the ns3 namespace.
address
Definition: first.py:37
LrWpanAddressMode m_dstAddrMode
Destination address mode.
Definition: lr-wpan-mac.h:158
LrWpanAddressMode
table 80 of 802.15.4
Definition: lr-wpan-mac.h:97
uint64_t m_macSuperframeOrder
The length of the active portion of the outgoing superframe, including the beacon frame...
Definition: lr-wpan-mac.h:483
TracedCallback< Ptr< const Packet > > m_macRxDropTrace
The trace source fired for packets successfully received by the device but dropped before being forwa...
Definition: lr-wpan-mac.h:694
TX_OPTION_GTS.
Definition: lr-wpan-mac.h:58
Callback< void, McpsDataConfirmParams > McpsDataConfirmCallback
This callback is called after a McpsDataRequest has been called from the higher layer.
Definition: lr-wpan-mac.h:203
void SetRxOnWhenIdle(bool rxOnWhenIdle)
Set if the receiver should be enabled when the MAC is idle.
Definition: lr-wpan-mac.cc:203
TracedCallback< Ptr< const Packet > > m_macPromiscRxTrace
The trace source fired for packets successfully received by the device immediately before being forwa...
Definition: lr-wpan-mac.h:676
bool m_macPromiscuousMode
Indicates if MAC sublayer is in receive all mode.
Definition: lr-wpan-mac.h:490
Mac16Address m_srcAddr
Source address.
Definition: lr-wpan-mac.h:186
This class can contain 16 bit addresses.
Definition: mac16-address.h:41
uint8_t m_dsn
The DSN of the received data frame.
Definition: lr-wpan-mac.h:193
LrWpanMac(void)
Default constructor.
Definition: lr-wpan-mac.cc:131
TracedCallback< Ptr< const Packet > > m_snifferTrace
A trace source that emulates a non-promiscuous protocol sniffer connected to the device.
Definition: lr-wpan-mac.h:714
void SetExtendedAddress(Mac64Address address)
Set the extended address of this MAC.
Definition: lr-wpan-mac.cc:229
uint8_t m_macMaxFrameRetries
The maximum number of retries allowed after a transmission failure.
Definition: lr-wpan-mac.h:509
uint8_t txQMsduHandle
MSDU Handle.
Definition: lr-wpan-mac.h:572
static TypeId GetTypeId(void)
Get the type ID.
Definition: lr-wpan-mac.cc:50
Ptr< LrWpanPhy > m_phy
The PHY associated with this MAC.
Definition: lr-wpan-mac.h:749
CHANNEL_ACCESS_FAILURE.
Definition: lr-wpan-mac.h:73
MAC_CSMA.
Definition: lr-wpan-mac.h:70
SequenceNumber8 m_macDsn
Sequence number added to transmitted data or MAC command frame, 00-ff.
Definition: lr-wpan-mac.h:503
An identifier for simulation events.
Definition: event-id.h:53
uint64_t m_aNumSuperframeSlots
Number of a superframe slots per superframe.
Definition: lr-wpan-mac.h:447
MAC_ACK_PENDING.
Definition: lr-wpan-mac.h:72
static const uint32_t aMinMPDUOverhead
The minimum number of octets added by the MAC sublayer to the PSDU.
Definition: lr-wpan-mac.h:236
LrWpanTxOption
Tx options.
Definition: lr-wpan-mac.h:54
void ChangeMacState(LrWpanMacState newState)
Change the current MAC state to the given new state.
Ptr< LrWpanCsmaCa > m_csmaCa
The CSMA/CA implementation used by this MAC.
Definition: lr-wpan-mac.h:754
LrWpanMacState
MAC states.
Definition: lr-wpan-mac.h:67
LrWpanAssociationStatus
table 83 of 802.15.4
Definition: lr-wpan-mac.h:110
uint8_t GetMacMaxFrameRetries(void) const
Get the macMaxFrameRetries attribute value.
TracedCallback< Ptr< const Packet > > m_macTxDequeueTrace
The trace source fired when packets are dequeued from the L3/l2 transmission queue.
Definition: lr-wpan-mac.h:643
uint16_t m_macPanId
16 bits id of PAN on which this device is operating.
Definition: lr-wpan-mac.h:497
void(* StateTracedCallback)(LrWpanMacState oldState, LrWpanMacState newState)
TracedCallback signature for LrWpanMacState change events.
Definition: lr-wpan-mac.h:559
void PlmeSetTRXStateConfirm(LrWpanPhyEnumeration status)
IEEE 802.15.4-2006 section 6.2.2.8 PLME-SET-TRX-STATE.confirm Set PHY state.
Definition: lr-wpan-mac.cc:943
LrWpanPhyEnumeration
IEEE802.15.4-2006 PHY Emumerations Table 18 in section 6.2.3.
Definition: lr-wpan-phy.h:105
void SendAck(uint8_t seqno)
Send an acknowledgment packet for the given sequence number.
Definition: lr-wpan-mac.cc:738
MCPS-DATA.request params.
Definition: lr-wpan-mac.h:146
A base class which provides memory management and object aggregation.
Definition: object.h:87
void AckWaitTimeout(void)
Handle an ACK timeout with a packet retransmission, if there are retransmission left, or a packet drop.
Definition: lr-wpan-mac.cc:791
Ptr< LrWpanPhy > GetPhy(void)
Get the underlying PHY of the MAC.
Definition: lr-wpan-mac.cc:473
Mac16Address m_shortAddress
The short address used by this MAC.
Definition: lr-wpan-mac.h:789
TX_OPTION_NONE.
Definition: lr-wpan-mac.h:56
Mac16Address GetShortAddress(void) const
Get the short address of this MAC.
Definition: lr-wpan-mac.cc:237
a unique identifier for an interface.
Definition: type-id.h:58
void SetCsmaCa(Ptr< LrWpanCsmaCa > csmaCa)
Set the CSMA/CA implementation to be used by the MAC.
Definition: lr-wpan-mac.cc:461
void SetPanId(uint16_t panId)
Set the PAN id used by this MAC.
void PlmeSetAttributeConfirm(LrWpanPhyEnumeration status, LrWpanPibAttributeIdentifier id)
IEEE 802.15.4-2006 section 6.2.2.10 PLME-SET.confirm Set attributes per definition from Table 23 in s...
Definition: lr-wpan-mac.cc:981
virtual void DoInitialize(void)
Initialize() implementation.
Definition: lr-wpan-mac.cc:160
void(* SentTracedCallback)(Ptr< const Packet > packet, uint8_t retries, uint8_t backoffs)
TracedCallback signature for sent packets.
Definition: lr-wpan-mac.h:547
MAC_SENDING.
Definition: lr-wpan-mac.h:71
uint64_t m_aBaseSlotDuration
Length of a superframe slot in symbols.
Definition: lr-wpan-mac.h:441
uint16_t m_srcPanId
Source PAN identifier.
Definition: lr-wpan-mac.h:185
MAC_IDLE.
Definition: lr-wpan-mac.h:69
void SetAssociationStatus(LrWpanAssociationStatus status)
Set the current association status.
MCPS-DATA.indication params.
Definition: lr-wpan-mac.h:182
void SetMcpsDataIndicationCallback(McpsDataIndicationCallback c)
Set the callback for the indication of an incoming data packet.
Definition: lr-wpan-mac.cc:479