A Discrete-Event Network Simulator
API
Loading...
Searching...
No Matches
wifi-mode.h
Go to the documentation of this file.
1/*
2 * Copyright (c) 2005,2006,2007 INRIA
3 *
4 * SPDX-License-Identifier: GPL-2.0-only
5 *
6 * Authors: Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
7 * Sébastien Deronne <sebastien.deronne@gmail.com>
8 */
9
10#ifndef WIFI_MODE_H
11#define WIFI_MODE_H
12
13#include "wifi-phy-common.h"
14
15#include "ns3/attribute-helper.h"
16#include "ns3/callback.h"
17
18#include <vector>
19
20namespace ns3
21{
22
23/// STA_ID to identify a single user (SU)
24static constexpr uint16_t SU_STA_ID = 65535;
25
26class WifiTxVector;
27
28/**
29 * @brief represent a single transmission mode
30 * @ingroup wifi
31 *
32 * A WifiMode is implemented by a single integer which is used
33 * to lookup in a global array the characteristics of the
34 * associated transmission mode. It is thus extremely cheap to
35 * keep a WifiMode variable around.
36 *
37 * @see attribute_WifiMode
38 */
40{
41 public:
42 /**
43 * @returns true if this <MCS, channel width, NSS> combination is allowed, false otherwise.
44 *
45 * @param channelWidth the considered channel width
46 * @param nss the considered number of streams
47 */
48 bool IsAllowed(MHz_u channelWidth, uint8_t nss) const;
49 /**
50 * @returns true if this TXVECTOR combination is allowed, false otherwise.
51 *
52 * @param txVector the const WifiTxVector& of the signal
53 */
54 bool IsAllowed(const WifiTxVector& txVector) const;
55 /**
56 *
57 * @param channelWidth the considered channel width
58 * @param guardInterval the considered guard interval duration
59 * @param nss the considered number of streams
60 *
61 * @returns the physical bit rate of this signal in bps.
62 *
63 * If a transmission mode uses 1/2 FEC, and if its
64 * data rate is 3.25Mbps, the PHY rate is 6.5Mbps
65 */
66 uint64_t GetPhyRate(MHz_u channelWidth, Time guardInterval, uint8_t nss) const;
67 /**
68 * @param txVector the const WifiTxVector& of the signal
69 * @param staId the station ID for MU (unused if SU)
70 *
71 * @returns the physical bit rate of this signal in bps.
72 *
73 * If a transmission mode uses 1/2 FEC, and if its
74 * data rate is 3.25Mbps, the PHY rate is 6.5Mbps
75 */
76 uint64_t GetPhyRate(const WifiTxVector& txVector, uint16_t staId = SU_STA_ID) const;
77 /**
78 * @param channelWidth the considered channel width
79 *
80 * @returns the physical bit rate of this non-HT signal.
81 */
82 uint64_t GetPhyRate(MHz_u channelWidth) const;
83 /**
84 *
85 * @param channelWidth the considered channel width
86 * @param guardInterval the considered guard interval duration
87 * @param nss the considered number of streams
88 *
89 * @returns the data bit rate of this signal in bps.
90 */
91 uint64_t GetDataRate(MHz_u channelWidth, Time guardInterval, uint8_t nss) const;
92 /**
93 * @param txVector the const WifiTxVector& of the signal
94 * @param staId the station ID for MU (unused if SU)
95 *
96 * @returns the data bit rate of this signal.
97 */
98 uint64_t GetDataRate(const WifiTxVector& txVector, uint16_t staId = SU_STA_ID) const;
99 /**
100 * @param channelWidth the considered channel width
101 *
102 * @returns the data bit rate of this non-HT.
103 */
104 uint64_t GetDataRate(MHz_u channelWidth) const;
105
106 /**
107 * @returns the coding rate of this transmission mode
108 */
110 /**
111 * @returns the size of the modulation constellation.
112 */
113 uint16_t GetConstellationSize() const;
114 /**
115 * @returns the MCS value.
116 */
117 uint8_t GetMcsValue() const;
118 /**
119 * @returns a human-readable representation of this WifiMode
120 * instance.
121 */
122 const std::string& GetUniqueName() const;
123 /**
124 * @returns true if this mode is a mandatory mode, false
125 * otherwise.
126 */
127 bool IsMandatory() const;
128 /**
129 * @returns the UID associated to this wireless mode.
130 *
131 * Each specific wireless mode should have a different UID.
132 * For example, the 802.11b 1Mbps and the 802.11b 2Mbps modes
133 * should have different UIDs.
134 */
135 uint32_t GetUid() const;
136 /**
137 *
138 * @returns the Modulation Class (Section 9.7.8 "Modulation classes"; IEEE 802.11-2012)
139 * to which this WifiMode belongs.
140 */
142 /**
143 * @returns the rate (in bps) of the non-HT Reference Rate
144 * which corresponds to the HT MCS of this WifiMode.
145 *
146 * To convert an HT MCS to is corresponding non-HT Reference Rate
147 * use the modulation and coding rate of the HT MCS
148 * and lookup in Table 9-5 of IEEE 802.11-2012.
149 */
150 uint64_t GetNonHtReferenceRate() const;
151 /**
152 * @param mode the WifiMode
153 * @returns true if this WifiMode has a
154 * a code rate strictly higher than mode.
155 */
156 bool IsHigherCodeRate(WifiMode mode) const;
157 /**
158 * @param mode the WifiMode
159 * @returns true if this WifiMode has a
160 * a rate strictly higher than mode.
161 */
162 bool IsHigherDataRate(WifiMode mode) const;
163
164 /**
165 * Create an invalid WifiMode. Calling any method on the
166 * instance created will trigger an assert. This is useful
167 * to separate the declaration of a WifiMode variable from
168 * its initialization.
169 */
170 WifiMode();
171 /**
172 * Create a WifiMode if the given string represents a valid
173 * WifiMode name.
174 *
175 * @param name std::string of a valid WifiMode name
176 */
177 WifiMode(std::string name);
178
179 private:
180 /// allow WifiModeFactory class access
181 friend class WifiModeFactory;
182 /**
183 * Create a WifiMode from a given unique ID.
184 *
185 * @param uid unique ID
186 */
187 WifiMode(uint32_t uid);
188 uint32_t m_uid; ///< UID
189};
190
191/**
192 * Check if the two WifiModes are identical.
193 *
194 * @param a WifiMode
195 * @param b WifiMode
196 *
197 * @return true if the two WifiModes are identical,
198 * false otherwise
199 */
200bool operator==(const WifiMode& a, const WifiMode& b);
201
202/**
203 * Check if the two WifiModes are different.
204 *
205 * @param a WifiMode
206 * @param b WifiMode
207 *
208 * @return true if the two WifiModes are different,
209 * false otherwise
210 */
211bool operator!=(const WifiMode& a, const WifiMode& b);
212
213/**
214 * Compare two WifiModes
215 *
216 * @param a WifiMode
217 * @param b WifiMode
218 *
219 * @return true if a is less than b,
220 * false otherwise
221 */
222bool operator<(const WifiMode& a, const WifiMode& b);
223
224/**
225 * Serialize WifiMode to ostream (human-readable).
226 *
227 * @param os the output stream
228 * @param mode the WifiMode
229 *
230 * @return std::ostream
231 */
232std::ostream& operator<<(std::ostream& os, const WifiMode& mode);
233/**
234 * Serialize WifiMode from istream (human-readable).
235 *
236 * @param is the input stream
237 * @param mode the WifiMode
238 *
239 * @return std::istream
240 */
241std::istream& operator>>(std::istream& is, WifiMode& mode);
242
244
245/**
246 * In various parts of the code, folk are interested in maintaining a
247 * list of transmission modes. The vector class provides a good basis
248 * for this, but we here add some syntactic sugar by defining a
249 * WifiModeList type, and a corresponding iterator.
250 */
251typedef std::vector<WifiMode> WifiModeList;
252/**
253 * An iterator for WifiModeList vector.
254 */
255typedef WifiModeList::const_iterator WifiModeListIterator;
256
257/**
258 * @brief create WifiMode class instances and keep track of them.
259 *
260 * This factory ensures that each WifiMode created has a unique name
261 * and assigns to each of them a unique integer.
262 */
264{
265 public:
266 // Typedefs for callbacks used by WifiModeItem
267 /**
268 * Typedef for callback used to retrieve code rate of a WifiMode
269 * @return the code rate of the WifiMode.
270 */
272 /**
273 * Typedef for callback used to retrieve constellation size of a WifiMode
274 * @return the size of modulation constellation of the WifiMode.
275 */
277 /**
278 * Typedef for callback used to calculate PHY rate of a WifiMode
279 * from a TXVECTOR.
280 *
281 * @param txVector the TXVECTOR used for the transmission
282 * @param staId the station ID
283 * @return the physical bit rate of the signal in bps.
284 */
285 typedef Callback<uint64_t, const WifiTxVector& /* txVector */, uint16_t /* staId */>
287 /**
288 * Typedef for callback used to calculate data rate of a WifiMode
289 * from a TXVECTOR.
290 *
291 * @param txVector the TXVECTOR used for the transmission
292 * @param staId the station ID
293 * @return the data rate of the signal in bps.
294 */
295 typedef Callback<uint64_t, const WifiTxVector& /* txVector */, uint16_t /* staId */>
297 /**
298 * Typedef for callback used to calculate Non-HT Reference Rate of
299 * an MCS defined in HT or later amendment. For Non-HT modes (DSSS, OFDM,
300 * etc) this should be defined as null.
301 *
302 * @return the rate (in bps) of the non-HT Reference Rate.
303 */
305 /**
306 * Typedef for callback used to check whether a given combination is allowed
307 *
308 * @param txVector the TXVECTOR containing the combination to check
309 * @return true if combination of current WifiMode and TXVECTOR is allowed.
310 */
311 typedef Callback<bool, const WifiTxVector& /* txVector */> AllowedCallback;
312
313 /**
314 * @param uniqueName the name of the associated WifiMode. This name
315 * must be unique across _all_ instances.
316 * @param modClass the class of modulation
317 * @param isMandatory true if this WifiMode is mandatory, false otherwise.
318 * @param codeRateCallback a callback function to retrieve coding rate of
319 * this WifiMode. If convolutional coding is used for this rate
320 * then the callback returns the convolutional coding rate used. If
321 * there is no explicit convolutional coding step (e.g., for DSSS
322 * rates) then the callback should returns WIFI_CODE_RATE_UNDEFINED.
323 * @param constellationSizeCallback a callback function that returns the
324 * order of the constellation used.
325 * @param phyRateCallback a callback function to calculate the PHY rate (in
326 * bps) of this WifiMode.
327 * @param dataRateCallback a callback function to calculate the data rate
328 * (in bps) of this WifiMode.
329 * @param isAllowedCallback a callback function to check whether a
330 * specific combination of this WifiMode is allowed.
331 *
332 * @return WifiMode
333 *
334 * Create a non-HT WifiMode.
335 */
336 static WifiMode CreateWifiMode(std::string uniqueName,
337 WifiModulationClass modClass,
338 bool isMandatory,
339 CodeRateCallback codeRateCallback,
340 ConstellationSizeCallback constellationSizeCallback,
341 PhyRateCallback phyRateCallback,
342 DataRateCallback dataRateCallback,
343 AllowedCallback isAllowedCallback);
344
345 /**
346 * @param uniqueName the name of the associated WifiMode. This name
347 * must be unique across _all_ instances.
348 * @param mcsValue the MCS value
349 * @param modClass the class of modulation
350 * @param isMandatory true if this WifiMode is mandatory, false otherwise.
351 * @param codeRateCallback a callback function that returns the coding rate
352 * of this WifiMode.
353 * @param constellationSizeCallback a callback function that returns the size
354 * of modulation constellation of this WifiMode.
355 * @param phyRateCallback a callback function to calculate the PHY rate (in
356 * bps) of this WifiMode.
357 * @param dataRateCallback a callback function to calculate the data rate (in
358 * bps) of this WifiMode.
359 * @param nonHtReferenceRateCallback a callback function to calculate the rate
360 * (in bps) of the non-HT Reference Rate of this WifiMode.
361 * @param isAllowedCallback a callback function to calculate whether a given
362 * combination of is allowed for this WifiMode.
363 *
364 * @return WifiMode
365 *
366 * Create a HT or later WifiMode.
367 */
368 static WifiMode CreateWifiMcs(std::string uniqueName,
369 uint8_t mcsValue,
370 WifiModulationClass modClass,
371 bool isMandatory,
372 CodeRateCallback codeRateCallback,
373 ConstellationSizeCallback constellationSizeCallback,
374 PhyRateCallback phyRateCallback,
375 DataRateCallback dataRateCallback,
376 NonHtReferenceRateCallback nonHtReferenceRateCallback,
377 AllowedCallback isAllowedCallback);
378
379 private:
380 /// allow WifiMode class access
381 friend class WifiMode;
382 friend std::istream& operator>>(std::istream& is, WifiMode& mode);
383
384 /**
385 * Return a WifiModeFactory
386 *
387 * @return a WifiModeFactory
388 */
389 static WifiModeFactory* GetFactory();
391
392 /**
393 * This is the data associated to a unique WifiMode.
394 * The integer stored in a WifiMode is in fact an index
395 * in an array of WifiModeItem objects.
396 */
398 {
399 std::string uniqueUid; ///< unique UID
400 WifiModulationClass modClass; ///< modulation class
401 bool isMandatory; ///< flag to indicate whether this mode is mandatory
402 uint8_t mcsValue; ///< MCS value
404 GetCodeRateCallback; ///< Callback to retrieve code rate of this WifiModeItem
406 GetConstellationSizeCallback; ///< Callback to retrieve constellation size of this
407 ///< WifiModeItem
409 GetPhyRateCallback; ///< Callback to calculate PHY rate in bps of this WifiModeItem
411 GetDataRateCallback; ///< Callback to calculate data rate in bps of this WifiModeItem
413 GetNonHtReferenceRateCallback; ///< Callback to calculate non-HT reference rate of this
414 ///< WifiModeItem
416 IsAllowedCallback; ///< Callback to check whether a given combination of is allowed
417 };
418
419 /**
420 * Search and return WifiMode from a given name.
421 *
422 * @param name human-readable WifiMode
423 *
424 * @return the WifiMode
425 */
426 WifiMode Search(std::string name) const;
427 /**
428 * Allocate a WifiModeItem from a given uniqueUid.
429 *
430 * @param uniqueUid the unique UID
431 *
432 * @return the allocated UID index
433 */
434 uint32_t AllocateUid(std::string uniqueUid);
435 /**
436 * Return a WifiModeItem at the given UID index.
437 *
438 * @param uid the UID index
439 *
440 * @return WifiModeItem at the given UID
441 */
443
444 /**
445 * typedef for a vector of WifiModeItem.
446 */
447 typedef std::vector<WifiModeItem> WifiModeItemList;
449};
450
451} // namespace ns3
452
453#endif /* WIFI_MODE_H */
Callback template class.
Definition callback.h:422
Simulation virtual time values and global simulation resolution.
Definition nstime.h:94
create WifiMode class instances and keep track of them.
Definition wifi-mode.h:264
Callback< uint64_t, const WifiTxVector &, uint16_t > PhyRateCallback
Typedef for callback used to calculate PHY rate of a WifiMode from a TXVECTOR.
Definition wifi-mode.h:286
WifiModeItem * Get(uint32_t uid)
Return a WifiModeItem at the given UID index.
Definition wifi-mode.cc:389
Callback< WifiCodeRate > CodeRateCallback
Typedef for callback used to retrieve code rate of a WifiMode.
Definition wifi-mode.h:271
static WifiMode CreateWifiMcs(std::string uniqueName, uint8_t mcsValue, WifiModulationClass modClass, bool isMandatory, CodeRateCallback codeRateCallback, ConstellationSizeCallback constellationSizeCallback, PhyRateCallback phyRateCallback, DataRateCallback dataRateCallback, NonHtReferenceRateCallback nonHtReferenceRateCallback, AllowedCallback isAllowedCallback)
Definition wifi-mode.cc:307
std::vector< WifiModeItem > WifiModeItemList
typedef for a vector of WifiModeItem.
Definition wifi-mode.h:447
uint32_t AllocateUid(std::string uniqueUid)
Allocate a WifiModeItem from a given uniqueUid.
Definition wifi-mode.cc:372
static WifiModeFactory * GetFactory()
Return a WifiModeFactory.
Definition wifi-mode.cc:396
WifiModeItemList m_itemList
item list
Definition wifi-mode.h:448
Callback< uint64_t, const WifiTxVector &, uint16_t > DataRateCallback
Typedef for callback used to calculate data rate of a WifiMode from a TXVECTOR.
Definition wifi-mode.h:296
WifiMode Search(std::string name) const
Search and return WifiMode from a given name.
Definition wifi-mode.cc:339
Callback< uint16_t > ConstellationSizeCallback
Typedef for callback used to retrieve constellation size of a WifiMode.
Definition wifi-mode.h:276
friend std::istream & operator>>(std::istream &is, WifiMode &mode)
Serialize WifiMode from istream (human-readable).
Definition wifi-mode.cc:48
Callback< bool, const WifiTxVector & > AllowedCallback
Typedef for callback used to check whether a given combination is allowed.
Definition wifi-mode.h:311
Callback< uint64_t > NonHtReferenceRateCallback
Typedef for callback used to calculate Non-HT Reference Rate of an MCS defined in HT or later amendme...
Definition wifi-mode.h:304
static WifiMode CreateWifiMode(std::string uniqueName, WifiModulationClass modClass, bool isMandatory, CodeRateCallback codeRateCallback, ConstellationSizeCallback constellationSizeCallback, PhyRateCallback phyRateCallback, DataRateCallback dataRateCallback, AllowedCallback isAllowedCallback)
Definition wifi-mode.cc:259
represent a single transmission mode
Definition wifi-mode.h:40
WifiMode()
Create an invalid WifiMode.
Definition wifi-mode.cc:237
uint32_t GetUid() const
Definition wifi-mode.cc:168
const std::string & GetUniqueName() const
Definition wifi-mode.cc:137
bool IsHigherDataRate(WifiMode mode) const
Definition wifi-mode.cc:197
uint16_t GetConstellationSize() const
Definition wifi-mode.cc:130
WifiModulationClass GetModulationClass() const
Definition wifi-mode.cc:174
uint64_t GetPhyRate(MHz_u channelWidth, Time guardInterval, uint8_t nss) const
Definition wifi-mode.cc:80
bool IsMandatory() const
Definition wifi-mode.cc:145
uint64_t GetDataRate(MHz_u channelWidth, Time guardInterval, uint8_t nss) const
Definition wifi-mode.cc:111
uint64_t GetNonHtReferenceRate() const
Definition wifi-mode.cc:181
WifiCodeRate GetCodeRate() const
Definition wifi-mode.cc:123
uint32_t m_uid
UID.
Definition wifi-mode.h:188
bool IsHigherCodeRate(WifiMode mode) const
Definition wifi-mode.cc:190
bool IsAllowed(MHz_u channelWidth, uint8_t nss) const
Definition wifi-mode.cc:57
uint8_t GetMcsValue() const
Definition wifi-mode.cc:152
This class mimics the TXVECTOR which is to be passed to the PHY in order to define the parameters whi...
#define ATTRIBUTE_HELPER_HEADER(type)
Declare the attribute value, accessor and checkers for class type
WifiModulationClass
This enumeration defines the modulation classes per (Table 10-6 "Modulation classes"; IEEE 802....
Every class exported by the ns3 library is enclosed in the ns3 namespace.
bool operator!=(Callback< R, Args... > a, Callback< R, Args... > b)
Inequality test.
Definition callback.h:658
bool operator==(const EventId &a, const EventId &b)
Definition event-id.h:155
std::ostream & operator<<(std::ostream &os, const Angles &a)
Definition angles.cc:148
WifiModeList::const_iterator WifiModeListIterator
An iterator for WifiModeList vector.
Definition wifi-mode.h:255
std::istream & operator>>(std::istream &is, Angles &a)
Definition angles.cc:172
bool operator<(const EventId &a, const EventId &b)
Definition event-id.h:168
std::vector< WifiMode > WifiModeList
In various parts of the code, folk are interested in maintaining a list of transmission modes.
Definition wifi-mode.h:251
static constexpr uint16_t SU_STA_ID
STA_ID to identify a single user (SU)
Definition wifi-mode.h:24
WifiCodeRate
These constants define the various convolutional coding rates used for the OFDM transmission modes in...
This is the data associated to a unique WifiMode.
Definition wifi-mode.h:398
WifiModulationClass modClass
modulation class
Definition wifi-mode.h:400
AllowedCallback IsAllowedCallback
Callback to check whether a given combination of is allowed.
Definition wifi-mode.h:416
std::string uniqueUid
unique UID
Definition wifi-mode.h:399
bool isMandatory
flag to indicate whether this mode is mandatory
Definition wifi-mode.h:401
PhyRateCallback GetPhyRateCallback
Callback to calculate PHY rate in bps of this WifiModeItem.
Definition wifi-mode.h:409
DataRateCallback GetDataRateCallback
Callback to calculate data rate in bps of this WifiModeItem.
Definition wifi-mode.h:411
NonHtReferenceRateCallback GetNonHtReferenceRateCallback
Callback to calculate non-HT reference rate of this WifiModeItem.
Definition wifi-mode.h:413
ConstellationSizeCallback GetConstellationSizeCallback
Callback to retrieve constellation size of this WifiModeItem.
Definition wifi-mode.h:406
CodeRateCallback GetCodeRateCallback
Callback to retrieve code rate of this WifiModeItem.
Definition wifi-mode.h:404
Declaration of the following enums: