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 * This method cannot be called for non-HT modulations, because Modulation and Coding Scheme
118 * (MCS) is a concept introduced by the 802.11n amendment.
119 */
120 uint8_t GetMcsValue() const;
121 /**
122 * @returns a human-readable representation of this WifiMode
123 * instance.
124 */
125 const std::string& GetUniqueName() const;
126 /**
127 * @returns true if this mode is a mandatory mode, false
128 * otherwise.
129 */
130 bool IsMandatory() const;
131 /**
132 * @returns the UID associated to this wireless mode.
133 *
134 * Each specific wireless mode should have a different UID.
135 * For example, the 802.11b 1Mbps and the 802.11b 2Mbps modes
136 * should have different UIDs.
137 */
138 uint32_t GetUid() const;
139 /**
140 *
141 * @returns the Modulation Class (Section 9.7.8 "Modulation classes"; IEEE 802.11-2012)
142 * to which this WifiMode belongs.
143 */
145 /**
146 * @returns the rate (in bps) of the non-HT Reference Rate
147 * which corresponds to the HT MCS of this WifiMode.
148 *
149 * To convert an HT MCS to is corresponding non-HT Reference Rate
150 * use the modulation and coding rate of the HT MCS
151 * and lookup in Table 9-5 of IEEE 802.11-2012.
152 */
153 uint64_t GetNonHtReferenceRate() const;
154 /**
155 * @param mode the WifiMode
156 * @returns true if this WifiMode has a
157 * a code rate strictly higher than mode.
158 */
159 bool IsHigherCodeRate(WifiMode mode) const;
160 /**
161 * @param mode the WifiMode
162 * @returns true if this WifiMode has a
163 * a rate strictly higher than mode.
164 */
165 bool IsHigherDataRate(WifiMode mode) const;
166
167 /**
168 * Create an invalid WifiMode. Calling any method on the
169 * instance created will trigger an assert. This is useful
170 * to separate the declaration of a WifiMode variable from
171 * its initialization.
172 */
173 WifiMode();
174 /**
175 * Create a WifiMode if the given string represents a valid
176 * WifiMode name.
177 *
178 * @param name std::string of a valid WifiMode name
179 */
180 WifiMode(std::string name);
181
182 private:
183 /// allow WifiModeFactory class access
184 friend class WifiModeFactory;
185 /**
186 * Create a WifiMode from a given unique ID.
187 *
188 * @param uid unique ID
189 */
190 WifiMode(uint32_t uid);
191 uint32_t m_uid; ///< UID
192};
193
194/**
195 * Check if the two WifiModes are identical.
196 *
197 * @param a WifiMode
198 * @param b WifiMode
199 *
200 * @return true if the two WifiModes are identical,
201 * false otherwise
202 */
203bool operator==(const WifiMode& a, const WifiMode& b);
204
205/**
206 * Check if the two WifiModes are different.
207 *
208 * @param a WifiMode
209 * @param b WifiMode
210 *
211 * @return true if the two WifiModes are different,
212 * false otherwise
213 */
214bool operator!=(const WifiMode& a, const WifiMode& b);
215
216/**
217 * Compare two WifiModes
218 *
219 * @param a WifiMode
220 * @param b WifiMode
221 *
222 * @return true if a is less than b,
223 * false otherwise
224 */
225bool operator<(const WifiMode& a, const WifiMode& b);
226
227/**
228 * Serialize WifiMode to ostream (human-readable).
229 *
230 * @param os the output stream
231 * @param mode the WifiMode
232 *
233 * @return std::ostream
234 */
235std::ostream& operator<<(std::ostream& os, const WifiMode& mode);
236/**
237 * Serialize WifiMode from istream (human-readable).
238 *
239 * @param is the input stream
240 * @param mode the WifiMode
241 *
242 * @return std::istream
243 */
244std::istream& operator>>(std::istream& is, WifiMode& mode);
245
247
248/**
249 * In various parts of the code, folk are interested in maintaining a
250 * list of transmission modes. The vector class provides a good basis
251 * for this, but we here add some syntactic sugar by defining a
252 * WifiModeList type, and a corresponding iterator.
253 */
254typedef std::vector<WifiMode> WifiModeList;
255/**
256 * An iterator for WifiModeList vector.
257 */
258typedef WifiModeList::const_iterator WifiModeListIterator;
259
260/**
261 * @brief create WifiMode class instances and keep track of them.
262 *
263 * This factory ensures that each WifiMode created has a unique name
264 * and assigns to each of them a unique integer.
265 */
267{
268 public:
269 // Typedefs for callbacks used by WifiModeItem
270 /**
271 * Typedef for callback used to retrieve code rate of a WifiMode
272 * @return the code rate of the WifiMode.
273 */
275 /**
276 * Typedef for callback used to retrieve constellation size of a WifiMode
277 * @return the size of modulation constellation of the WifiMode.
278 */
280 /**
281 * Typedef for callback used to calculate PHY rate of a WifiMode
282 * from a TXVECTOR.
283 *
284 * @param txVector the TXVECTOR used for the transmission
285 * @param staId the station ID
286 * @return the physical bit rate of the signal in bps.
287 */
288 typedef Callback<uint64_t, const WifiTxVector& /* txVector */, uint16_t /* staId */>
290 /**
291 * Typedef for callback used to calculate data rate of a WifiMode
292 * from a TXVECTOR.
293 *
294 * @param txVector the TXVECTOR used for the transmission
295 * @param staId the station ID
296 * @return the data rate of the signal in bps.
297 */
298 typedef Callback<uint64_t, const WifiTxVector& /* txVector */, uint16_t /* staId */>
300 /**
301 * Typedef for callback used to calculate Non-HT Reference Rate of
302 * an MCS defined in HT or later amendment. For Non-HT modes (DSSS, OFDM,
303 * etc) this should be defined as null.
304 *
305 * @return the rate (in bps) of the non-HT Reference Rate.
306 */
308 /**
309 * Typedef for callback used to check whether a given combination is allowed
310 *
311 * @param txVector the TXVECTOR containing the combination to check
312 * @return true if combination of current WifiMode and TXVECTOR is allowed.
313 */
314 typedef Callback<bool, const WifiTxVector& /* txVector */> AllowedCallback;
315
316 /**
317 * @param uniqueName the name of the associated WifiMode. This name
318 * must be unique across _all_ instances.
319 * @param modClass the class of modulation
320 * @param isMandatory true if this WifiMode is mandatory, false otherwise.
321 * @param codeRateCallback a callback function to retrieve coding rate of
322 * this WifiMode. If convolutional coding is used for this rate
323 * then the callback returns the convolutional coding rate used. If
324 * there is no explicit convolutional coding step (e.g., for DSSS
325 * rates) then the callback should returns WIFI_CODE_RATE_UNDEFINED.
326 * @param constellationSizeCallback a callback function that returns the
327 * order of the constellation used.
328 * @param phyRateCallback a callback function to calculate the PHY rate (in
329 * bps) of this WifiMode.
330 * @param dataRateCallback a callback function to calculate the data rate
331 * (in bps) of this WifiMode.
332 * @param isAllowedCallback a callback function to check whether a
333 * specific combination of this WifiMode is allowed.
334 *
335 * @return WifiMode
336 *
337 * Create a non-HT WifiMode.
338 */
339 static WifiMode CreateWifiMode(std::string uniqueName,
340 WifiModulationClass modClass,
341 bool isMandatory,
342 CodeRateCallback codeRateCallback,
343 ConstellationSizeCallback constellationSizeCallback,
344 PhyRateCallback phyRateCallback,
345 DataRateCallback dataRateCallback,
346 AllowedCallback isAllowedCallback);
347
348 /**
349 * @param uniqueName the name of the associated WifiMode. This name
350 * must be unique across _all_ instances.
351 * @param mcsValue the MCS value
352 * @param modClass the class of modulation
353 * @param isMandatory true if this WifiMode is mandatory, false otherwise.
354 * @param codeRateCallback a callback function that returns the coding rate
355 * of this WifiMode.
356 * @param constellationSizeCallback a callback function that returns the size
357 * of modulation constellation of this WifiMode.
358 * @param phyRateCallback a callback function to calculate the PHY rate (in
359 * bps) of this WifiMode.
360 * @param dataRateCallback a callback function to calculate the data rate (in
361 * bps) of this WifiMode.
362 * @param nonHtReferenceRateCallback a callback function to calculate the rate
363 * (in bps) of the non-HT Reference Rate of this WifiMode.
364 * @param isAllowedCallback a callback function to calculate whether a given
365 * combination of is allowed for this WifiMode.
366 *
367 * @return WifiMode
368 *
369 * Create a HT or later WifiMode.
370 */
371 static WifiMode CreateWifiMcs(std::string uniqueName,
372 uint8_t mcsValue,
373 WifiModulationClass modClass,
374 bool isMandatory,
375 CodeRateCallback codeRateCallback,
376 ConstellationSizeCallback constellationSizeCallback,
377 PhyRateCallback phyRateCallback,
378 DataRateCallback dataRateCallback,
379 NonHtReferenceRateCallback nonHtReferenceRateCallback,
380 AllowedCallback isAllowedCallback);
381
382 private:
383 /// allow WifiMode class access
384 friend class WifiMode;
385 friend std::istream& operator>>(std::istream& is, WifiMode& mode);
386
387 /**
388 * Return a WifiModeFactory
389 *
390 * @return a WifiModeFactory
391 */
392 static WifiModeFactory* GetFactory();
394
395 /**
396 * This is the data associated to a unique WifiMode.
397 * The integer stored in a WifiMode is in fact an index
398 * in an array of WifiModeItem objects.
399 */
401 {
402 std::string uniqueUid; ///< unique UID
403 WifiModulationClass modClass; ///< modulation class
404 bool isMandatory; ///< flag to indicate whether this mode is mandatory
405 uint8_t mcsValue; ///< MCS value
407 GetCodeRateCallback; ///< Callback to retrieve code rate of this WifiModeItem
409 GetConstellationSizeCallback; ///< Callback to retrieve constellation size of this
410 ///< WifiModeItem
412 GetPhyRateCallback; ///< Callback to calculate PHY rate in bps of this WifiModeItem
414 GetDataRateCallback; ///< Callback to calculate data rate in bps of this WifiModeItem
416 GetNonHtReferenceRateCallback; ///< Callback to calculate non-HT reference rate of this
417 ///< WifiModeItem
419 IsAllowedCallback; ///< Callback to check whether a given combination of is allowed
420 };
421
422 /**
423 * Search and return WifiMode from a given name.
424 *
425 * @param name human-readable WifiMode
426 *
427 * @return the WifiMode
428 */
429 WifiMode Search(std::string name) const;
430 /**
431 * Allocate a WifiModeItem from a given uniqueUid.
432 *
433 * @param uniqueUid the unique UID
434 *
435 * @return the allocated UID index
436 */
437 uint32_t AllocateUid(std::string uniqueUid);
438 /**
439 * Return a WifiModeItem at the given UID index.
440 *
441 * @param uid the UID index
442 *
443 * @return WifiModeItem at the given UID
444 */
446
447 /**
448 * typedef for a vector of WifiModeItem.
449 */
450 typedef std::vector<WifiModeItem> WifiModeItemList;
452};
453
454} // namespace ns3
455
456#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:267
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:289
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:274
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:450
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:451
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:299
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:279
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:314
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:307
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:40
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:191
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:258
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:254
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:401
WifiModulationClass modClass
modulation class
Definition wifi-mode.h:403
AllowedCallback IsAllowedCallback
Callback to check whether a given combination of is allowed.
Definition wifi-mode.h:419
std::string uniqueUid
unique UID
Definition wifi-mode.h:402
bool isMandatory
flag to indicate whether this mode is mandatory
Definition wifi-mode.h:404
PhyRateCallback GetPhyRateCallback
Callback to calculate PHY rate in bps of this WifiModeItem.
Definition wifi-mode.h:412
DataRateCallback GetDataRateCallback
Callback to calculate data rate in bps of this WifiModeItem.
Definition wifi-mode.h:414
NonHtReferenceRateCallback GetNonHtReferenceRateCallback
Callback to calculate non-HT reference rate of this WifiModeItem.
Definition wifi-mode.h:416
ConstellationSizeCallback GetConstellationSizeCallback
Callback to retrieve constellation size of this WifiModeItem.
Definition wifi-mode.h:409
CodeRateCallback GetCodeRateCallback
Callback to retrieve code rate of this WifiModeItem.
Definition wifi-mode.h:407
Declaration of the following enums: