A Discrete-Event Network Simulator
API
Loading...
Searching...
No Matches
peer-management-protocol.h
Go to the documentation of this file.
1/*
2 * Copyright (c) 2008,2009 IITP RAS
3 *
4 * SPDX-License-Identifier: GPL-2.0-only
5 *
6 * Authors: Kirill Andreev <andreev@iitp.ru>
7 * Aleksey Kovalenko <kovalenko@iitp.ru>
8 */
9
10#ifndef DOT11S_PEER_MAN_H
11#define DOT11S_PEER_MAN_H
12
15#include "peer-link.h"
16
17#include "ns3/event-id.h"
18#include "ns3/mac48-address.h"
19#include "ns3/net-device.h"
20#include "ns3/nstime.h"
21#include "ns3/traced-value.h"
22
23#include <map>
24
25namespace ns3
26{
27class MeshPointDevice;
28class UniformRandomVariable;
29
30namespace dot11s
31{
32class PeerManagementProtocolMac;
33class PeerLink;
34class IeMeshId;
35class IePeerManagement;
36class IeConfiguration;
37
38/**
39 * \ingroup dot11s
40 *
41 * \brief 802.11s Peer Management Protocol model
42 */
44{
45 public:
47 ~PeerManagementProtocol() override;
48
49 // Delete copy constructor and assignment operator to avoid misuse
52
53 /**
54 * \brief Get the type ID.
55 * \return the object TypeId
56 */
57 static TypeId GetTypeId();
58 void DoDispose() override;
59 /**
60 * \brief Install PMP on given mesh point.
61 * \param mp the MeshPointDevice to install onto
62 * \return true if successful
63 *
64 * Installing protocol causes installation of its interface MAC plugins.
65 *
66 * Also MP aggregates all installed protocols, PMP protocol can be accessed
67 * via MeshPointDevice::GetObject<PeerManagementProtocol>();
68 */
70 /**
71 * \brief Methods that handle beacon sending/receiving procedure.
72 *
73 * \name This methods interact with MAC_layer plug-in
74 */
75 ///@{
76 /**
77 * \brief When we are sending a beacon - we fill beacon timing
78 * element
79 * \return IeBeaconTiming is a beacon timing element that should be present in beacon
80 * \param interface is a interface sending a beacon
81 */
83 /**
84 * \brief To initiate peer link we must notify about received beacon
85 * \param interface the interface where a beacon was received from
86 * \param peerAddress address of station, which sent a beacon
87 * \param beaconInterval beacon interval (needed by beacon loss counter)
88 * \param beaconTiming beacon timing element (needed by BCA)
89 */
90 void ReceiveBeacon(uint32_t interface,
91 Mac48Address peerAddress,
92 Time beaconInterval,
93 Ptr<IeBeaconTiming> beaconTiming);
94 ///@}
95
96 /**
97 * \name Methods that handle Peer link management frames interaction:
98 */
99 ///@{
100 /**
101 * Deliver Peer link management information to the protocol-part
102 * \param interface is a interface ID of a given MAC (interfaceID rather than MAC address,
103 * because many interfaces may have the same MAC)
104 * \param peerAddress is address of peer
105 * \param peerMeshPointAddress is address of peer mesh point device (equal to peer address when
106 * only one interface)
107 * \param aid is association ID, which peer has assigned to us
108 * \param peerManagementElement is peer link management element
109 * \param meshConfig is mesh configuration element taken from the peer management frame
110 */
111 void ReceivePeerLinkFrame(uint32_t interface,
112 Mac48Address peerAddress,
113 Mac48Address peerMeshPointAddress,
114 uint16_t aid,
115 IePeerManagement peerManagementElement,
116 IeConfiguration meshConfig);
117 /**
118 * \brief Cancels peer link due to broken configuration (Mesh ID or Supported
119 * rates)
120 * \param interface interface of the link to cancel
121 * \param peerAddress peer address of the link to cancel
122 */
123 void ConfigurationMismatch(uint32_t interface, Mac48Address peerAddress);
124 /**
125 * \brief Cancels peer link due to successive transmission failures
126 * \param interface interface of the link to cancel
127 * \param peerAddress peer address of the link to cancel
128 */
129 void TransmissionFailure(uint32_t interface, const Mac48Address peerAddress);
130 /**
131 * \brief resets transmission failure statistics
132 * \param interface interface of the link to reset
133 * \param peerAddress peer address of the link to reset
134 */
135 void TransmissionSuccess(uint32_t interface, const Mac48Address peerAddress);
136 /**
137 * \brief Checks if there is established link
138 * \param interface interface of the link to check
139 * \param peerAddress peer address of the link to check
140 * \return true if the link is active
141 */
142 bool IsActiveLink(uint32_t interface, Mac48Address peerAddress);
143 ///@}
144
145 /// \name Interface to other protocols (MLME)
146 ///@{
147 /**
148 * Set peer link status change callback
149 * \param cb the callback
150 */
152 /**
153 * Find active peer link by my interface and peer interface MAC
154 * \param interface interface of the link to find
155 * \param peerAddress peer address of the link to find
156 * \return The peer link (null if not found)
157 */
158 Ptr<PeerLink> FindPeerLink(uint32_t interface, Mac48Address peerAddress);
159 /**
160 * Get list of all active peer links
161 * \return a list of all the active peer links
162 */
163 std::vector<Ptr<PeerLink>> GetPeerLinks() const;
164 /**
165 * Get list of active peers of my given interface
166 * \param interface the interface
167 * \return a list of all the active peer links on an interface
168 */
169 std::vector<Mac48Address> GetPeers(uint32_t interface) const;
170 /**
171 * Get mesh point address. \todo this used by plugins only. Now MAC plugins can ask MP address
172 * directly from main MAC
173 *
174 * \return Mac48Address
175 */
177 /**
178 * Get number of links
179 * \returns the number of links
180 */
181 uint8_t GetNumberOfLinks() const;
182 /**
183 * Set mesh ID to a string value
184 * \param s the mesh ID string value
185 */
186 void SetMeshId(std::string s);
187 /**
188 * Get mesh ID information element
189 * \returns the mesh ID information element
190 */
191 Ptr<IeMeshId> GetMeshId() const;
192 /**
193 * Enable or disable beacon collision avoidance
194 * \param enable true to enable beacon collision avoidance
195 */
196 void SetBeaconCollisionAvoidance(bool enable);
197 /**
198 * Get beacon collision avoidance
199 * \returns the beacon collision avoidance flag
200 */
201 bool GetBeaconCollisionAvoidance() const;
202 /**
203 * Notify about beacon send event, needed to schedule BCA
204 * \param interface the interface to use
205 * \param beaconInterval the beacon interval
206 */
207 void NotifyBeaconSent(uint32_t interface, Time beaconInterval);
208 ///@}
209
210 /**
211 * \brief Report statistics
212 * \param os the output stream
213 */
214 void Report(std::ostream& os) const;
215 /// Reset statistics function
216 void ResetStats();
217 /**
218 * Assign a fixed random variable stream number to the random variables
219 * used by this model. Return the number of streams (possibly zero) that
220 * have been assigned.
221 *
222 * \param stream first stream index to use
223 * \return the number of stream indices assigned by this model
224 */
225 int64_t AssignStreams(int64_t stream);
226
227 /**
228 * TracedCallback signature for link open/close events.
229 *
230 * \param [in] src MAC address of source interface.
231 * \param [in] dst MAC address of destination interface.
232 */
234
235 private:
236 void DoInitialize() override;
237
238 // Private structures
239 /// Keeps information about beacon of peer station: beacon interval, association ID, last time
240 /// we have received a beacon
242 {
243 uint16_t aid; ///< Assoc ID
244 Time referenceTbtt; ///< When one of my station's beacons was put into a beacon queue;
245 Time beaconInterval; ///< Beacon interval of my station;
246 };
247
248 /// We keep a vector of pointers to PeerLink class. This vector
249 /// keeps all peer links at a given interface.
250 typedef std::vector<Ptr<PeerLink>> PeerLinksOnInterface;
251 /// This map keeps all peer links.
252 typedef std::map<uint32_t, PeerLinksOnInterface> PeerLinksMap;
253 /// This map keeps relationship between peer address and its beacon information
254 typedef std::map<Mac48Address, BeaconInfo> BeaconsOnInterface;
255 /// \brief This map keeps beacon information on all interfaces
256 typedef std::map<uint32_t, BeaconsOnInterface> BeaconInfoMap;
257 /// \brief this vector keeps pointers to MAC-plugins
258 typedef std::map<uint32_t, Ptr<PeerManagementProtocolMac>> PeerManagementProtocolMacMap;
259
260 /**
261 * Initiate link function
262 *
263 * \param interface the interface to use
264 * \param peerAddress the peer address
265 * \param peerMeshPointAddress the peer mesh point address
266 * \returns the peer link
267 */
269 Mac48Address peerAddress,
270 Mac48Address peerMeshPointAddress);
271 /**
272 * \brief External peer-chooser
273 * \param interface the interface to use
274 * \param peerAddress the peer address
275 * \returns true is should send an open
276 */
277 bool ShouldSendOpen(uint32_t interface, Mac48Address peerAddress) const;
278 /**
279 * \brief External peer-chooser
280 * \param interface the interface to use
281 * \param peerAddress the peer address
282 * \param reasonCode reason code
283 * \returns true is should send an open
284 */
285 bool ShouldAcceptOpen(uint32_t interface,
286 Mac48Address peerAddress,
287 PmpReasonCode& reasonCode) const;
288 /**
289 * \brief Indicates changes in peer links
290 * \param interface the interface
291 * \param peerAddress the peer address
292 * \param peerMeshPointAddress the peer mesh point address
293 * \param ostate old state
294 * \param nstate new state
295 */
296 void PeerLinkStatus(uint32_t interface,
297 Mac48Address peerAddress,
298 Mac48Address peerMeshPointAddress,
299 PeerLink::PeerState ostate,
300 PeerLink::PeerState nstate);
301 /**
302 * \brief BCA
303 * \param interface interface
304 */
305 void CheckBeaconCollisions(uint32_t interface);
306 /**
307 * Shift own beacon function
308 * \param interface interface
309 */
310 void ShiftOwnBeacon(uint32_t interface);
311 /**
312 * \brief Time<-->TU converters:
313 * \param x TU
314 * \return Time
315 */
316 Time TuToTime(int x);
317 /**
318 * \brief Time<-->TU converters:
319 * \param x Time
320 * \return TU
321 */
322 int TimeToTu(Time x);
323
324 /**
325 * Aux. method to register open links
326 * \param peerMp peer mesh point address
327 * \param peerIface peer address
328 * \param myIface my address
329 * \param interface interface
330 */
331 void NotifyLinkOpen(Mac48Address peerMp,
332 Mac48Address peerIface,
333 Mac48Address myIface,
334 uint32_t interface);
335 /**
336 * Aux. method to register closed links
337 * \param peerMp peer mesh point address
338 * \param peerIface peer address
339 * \param myIface my address
340 * \param interface interface
341 */
342 void NotifyLinkClose(Mac48Address peerMp,
343 Mac48Address peerIface,
344 Mac48Address myIface,
345 uint32_t interface);
346
347 private:
351
352 uint16_t m_lastAssocId; ///< last associated ID
353 uint16_t m_lastLocalLinkId; ///< last local link ID
354 uint8_t m_maxNumberOfPeerLinks; ///< maimum number of peer links
355 /// Flag which enables BCA
357 /// Beacon can be shifted at [-m_maxBeaconShift; +m_maxBeaconShift] TUs
359 /// Last beacon at each interface
360 std::map<uint32_t, Time> m_lastBeacon;
361 /// Beacon interval at each interface
362 std::map<uint32_t, Time> m_beaconInterval;
363
364 /**
365 * \name Peer Links
366 */
368 /**
369 * \brief Callback to notify about peer link changes:
370 * Mac48Address is peer address of mesh point,
371 * Mac48Address is peer address of interface,
372 * uint32_t - interface ID,
373 * bool is status - true when new link has appeared, false - when link was closed,
374 */
376
377 /// Simple link open/close trace source type. Addresses are: src interface, dst interface
379 /// LinkOpen trace source
381 /// LinkClose trace source
383
384 /// Statistics structure
386 {
387 uint16_t linksTotal; ///< total links
388 uint16_t linksOpened; ///< opened links
389 uint16_t linksClosed; ///< links closed
390
391 /**
392 * Constructor
393 *
394 * \param t
395 */
396 Statistics(uint16_t t = 0);
397 /**
398 * Print function
399 * \param os the output stream to print to
400 */
401 void Print(std::ostream& os) const;
402 };
403
404 Statistics m_stats; ///< statistics
405
406 /// Add randomness to beacon shift
408};
409
410} // namespace dot11s
411} // namespace ns3
412#endif
Callback template class.
Definition callback.h:422
an EUI-48 address
A base class which provides memory management and object aggregation.
Definition object.h:78
Smart pointer class similar to boost::intrusive_ptr.
Simulation virtual time values and global simulation resolution.
Definition nstime.h:94
Forward calls to a chain of Callback.
a unique identifier for an interface.
Definition type-id.h:48
Describes Mesh Configuration Element see 7.3.2.86 of 802.11s draft 3.0.
according to IEEE 802.11 - 2012
802.11s Peer Management Protocol model
void ReceivePeerLinkFrame(uint32_t interface, Mac48Address peerAddress, Mac48Address peerMeshPointAddress, uint16_t aid, IePeerManagement peerManagementElement, IeConfiguration meshConfig)
Deliver Peer link management information to the protocol-part.
void DoDispose() override
Destructor implementation.
bool GetBeaconCollisionAvoidance() const
Get beacon collision avoidance.
std::map< Mac48Address, BeaconInfo > BeaconsOnInterface
This map keeps relationship between peer address and its beacon information.
bool ShouldSendOpen(uint32_t interface, Mac48Address peerAddress) const
External peer-chooser.
Callback< void, Mac48Address, Mac48Address, uint32_t, bool > m_peerStatusCallback
Callback to notify about peer link changes: Mac48Address is peer address of mesh point,...
void SetMeshId(std::string s)
Set mesh ID to a string value.
uint8_t m_maxNumberOfPeerLinks
maimum number of peer links
int TimeToTu(Time x)
Time<-->TU converters:
void Report(std::ostream &os) const
Report statistics.
void TransmissionFailure(uint32_t interface, const Mac48Address peerAddress)
Cancels peer link due to successive transmission failures.
uint16_t m_maxBeaconShift
Beacon can be shifted at [-m_maxBeaconShift; +m_maxBeaconShift] TUs.
void(* LinkOpenCloseTracedCallback)(Mac48Address src, const Mac48Address dst)
TracedCallback signature for link open/close events.
std::map< uint32_t, Ptr< PeerManagementProtocolMac > > PeerManagementProtocolMacMap
this vector keeps pointers to MAC-plugins
LinkEventCallback m_linkOpenTraceSrc
LinkOpen trace source.
void TransmissionSuccess(uint32_t interface, const Mac48Address peerAddress)
resets transmission failure statistics
bool ShouldAcceptOpen(uint32_t interface, Mac48Address peerAddress, PmpReasonCode &reasonCode) const
External peer-chooser.
std::vector< Ptr< PeerLink > > GetPeerLinks() const
Get list of all active peer links.
void ReceiveBeacon(uint32_t interface, Mac48Address peerAddress, Time beaconInterval, Ptr< IeBeaconTiming > beaconTiming)
To initiate peer link we must notify about received beacon.
void NotifyLinkClose(Mac48Address peerMp, Mac48Address peerIface, Mac48Address myIface, uint32_t interface)
Aux.
std::map< uint32_t, BeaconsOnInterface > BeaconInfoMap
This map keeps beacon information on all interfaces.
PeerManagementProtocol(const PeerManagementProtocol &)=delete
Ptr< PeerLink > InitiateLink(uint32_t interface, Mac48Address peerAddress, Mac48Address peerMeshPointAddress)
Initiate link function.
void DoInitialize() override
Initialize() implementation.
Ptr< IeMeshId > GetMeshId() const
Get mesh ID information element.
std::map< uint32_t, PeerLinksOnInterface > PeerLinksMap
This map keeps all peer links.
void SetPeerLinkStatusCallback(Callback< void, Mac48Address, Mac48Address, uint32_t, bool > cb)
Set peer link status change callback.
uint8_t GetNumberOfLinks() const
Get number of links.
static TypeId GetTypeId()
Get the type ID.
std::map< uint32_t, Time > m_lastBeacon
Last beacon at each interface.
bool Install(Ptr< MeshPointDevice > mp)
Install PMP on given mesh point.
PeerManagementProtocolMacMap m_plugins
plugins
int64_t AssignStreams(int64_t stream)
Assign a fixed random variable stream number to the random variables used by this model.
std::map< uint32_t, Time > m_beaconInterval
Beacon interval at each interface.
void NotifyBeaconSent(uint32_t interface, Time beaconInterval)
Notify about beacon send event, needed to schedule BCA.
void ShiftOwnBeacon(uint32_t interface)
Shift own beacon function.
std::vector< Ptr< PeerLink > > PeerLinksOnInterface
We keep a vector of pointers to PeerLink class.
void ConfigurationMismatch(uint32_t interface, Mac48Address peerAddress)
Cancels peer link due to broken configuration (Mesh ID or Supported rates)
PeerLinksMap m_peerLinks
Simple link open/close trace source type. Addresses are: src interface, dst interface.
Ptr< UniformRandomVariable > m_beaconShift
Add randomness to beacon shift.
void PeerLinkStatus(uint32_t interface, Mac48Address peerAddress, Mac48Address peerMeshPointAddress, PeerLink::PeerState ostate, PeerLink::PeerState nstate)
Indicates changes in peer links.
bool IsActiveLink(uint32_t interface, Mac48Address peerAddress)
Checks if there is established link.
std::vector< Mac48Address > GetPeers(uint32_t interface) const
Get list of active peers of my given interface.
LinkEventCallback m_linkCloseTraceSrc
LinkClose trace source.
TracedCallback< Mac48Address, Mac48Address > LinkEventCallback
Simple link open/close trace source type. Addresses are: src interface, dst interface.
void CheckBeaconCollisions(uint32_t interface)
BCA.
Ptr< IeBeaconTiming > GetBeaconTimingElement(uint32_t interface)
When we are sending a beacon - we fill beacon timing element.
Mac48Address GetAddress()
Get mesh point address.
Ptr< PeerLink > FindPeerLink(uint32_t interface, Mac48Address peerAddress)
Find active peer link by my interface and peer interface MAC.
Time TuToTime(int x)
Time<-->TU converters:
void NotifyLinkOpen(Mac48Address peerMp, Mac48Address peerIface, Mac48Address myIface, uint32_t interface)
Aux.
void ResetStats()
Reset statistics function.
PeerManagementProtocol & operator=(const PeerManagementProtocol &)=delete
void SetBeaconCollisionAvoidance(bool enable)
Enable or disable beacon collision avoidance.
PmpReasonCode
Codes used by 802.11s Peer Management Protocol.
Every class exported by the ns3 library is enclosed in the ns3 namespace.
Keeps information about beacon of peer station: beacon interval, association ID, last time we have re...
Time referenceTbtt
When one of my station's beacons was put into a beacon queue;.
void Print(std::ostream &os) const
Print function.