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;
29
30namespace dot11s
31{
33class PeerLink;
34class IeMeshId;
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
Virtual net device modeling mesh point.
Object()
Constructor.
Definition object.cc:96
Smart pointer class similar to boost::intrusive_ptr.
Definition ptr.h:66
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:49
The uniform distribution Random Number Generator (RNG).
Describes Mesh Configuration Element see 7.3.2.86 of 802.11s draft 3.0.
a IEEE 802.11 Mesh ID element (Section 8.4.2.101 of IEEE 802.11-2012)
according to IEEE 802.11 - 2012
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.
This is plugin to Mesh WiFi MAC, which implements the interface to dot11s peer management protocol: i...
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.