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