A Discrete-Event Network Simulator
API
Loading...
Searching...
No Matches
wifi-phy-operating-channel.h
Go to the documentation of this file.
1/*
2 * Copyright (c) 2021
3 *
4 * SPDX-License-Identifier: GPL-2.0-only
5 *
6 * Authors: Stefano Avallone <stavallo@unina.it>
7 * Sébastien Deronne <sebastien.deronne@gmail.com>
8 */
9
10#ifndef WIFI_PHY_OPERATING_CHANNEL_H
11#define WIFI_PHY_OPERATING_CHANNEL_H
12
13#include "wifi-phy-band.h"
14#include "wifi-phy-common.h"
15
16#include "ns3/he-ru.h"
17
18#include <optional>
19#include <set>
20#include <tuple>
21#include <vector>
22
23namespace ns3
24{
25
26/**
27 * A structure containing the information about a frequency channel
28 */
30{
31 /**
32 * @brief spaceship operator.
33 *
34 * @param info the frequency channel info
35 * @returns -1 if the provided channel info is located at a lower channel number, 0 if the
36 * provided channel info is identical or 1 if the provided channel info is located at a higher
37 * channel number
38 */
39 auto operator<=>(const FrequencyChannelInfo& info) const = default;
40 uint8_t number{0}; ///< the channel number
41 MHz_u frequency{0}; ///< the center frequency
42 MHz_u width{0}; ///< the channel width
44 FrequencyChannelType type{FrequencyChannelType::OFDM}; ///< the frequency channel type
45};
46
47/**
48 * @brief Stream insertion operator.
49 *
50 * @param os the stream
51 * @param info the frequency channel info
52 * @returns a reference to the stream
53 */
54std::ostream& operator<<(std::ostream& os, const FrequencyChannelInfo& info);
55
56/**
57 * @ingroup wifi
58 *
59 * Class that keeps track of all information about the current PHY operating channel.
60 */
62{
63 public:
64 /// Typedef for a const iterator pointing to a channel in the set of available channels
65 using ConstIterator = std::set<FrequencyChannelInfo>::const_iterator;
66
67 /// Comparison functor used to sort the segments by increasing frequencies
68 struct Compare
69 {
70 /**
71 * Functional operator for sorting the frequency segments.
72 *
73 * @param a const iterator pointing to the frequency channel for the first segment
74 * @param b const iterator pointing to the frequency channel for the second segment
75 * @return true if the center frequency of the first segment is lower than the center
76 * frequency of the second segment
77 */
78 bool operator()(const ConstIterator& a, const ConstIterator& b) const;
79 };
80
81 /// Typedef for a set of const iterator pointing to the segments of a channel
82 using ConstIteratorSet = std::set<ConstIterator, Compare>;
83
84 /**
85 * Create an uninitialized PHY operating channel.
86 */
88
89 /**
90 * Create a PHY operating channel from an iterator pointing to a channel in the set of available
91 * channels.
92 *
93 * @param it the iterator pointing to a channel in the set of available channels
94 */
96
97 /**
98 * Create a PHY operating channel from iterators pointing to multiple frequency segments in the
99 * set of available channels.
100 *
101 * @param its the iterators pointing to frequency segments in the set of available channels
102 */
104
105 virtual ~WifiPhyOperatingChannel();
106
107 /**
108 * Check if the given WifiPhyOperatingChannel is equivalent.
109 * Note that the primary20 channels are not compared.
110 *
111 * @param other another WifiPhyOperatingChannel
112 *
113 * @return true if the given WifiPhyOperatingChannel is equivalent,
114 * false otherwise
115 */
116 bool operator==(const WifiPhyOperatingChannel& other) const;
117
118 /**
119 * Check if the given WifiPhyOperatingChannel is different.
120 *
121 * @param other another WifiPhyOperatingChannel
122 *
123 * @return true if the given WifiPhyOperatingChannel is different,
124 * false otherwise
125 */
126 bool operator!=(const WifiPhyOperatingChannel& other) const;
127
128 static const std::set<FrequencyChannelInfo>
129 m_frequencyChannels; //!< Available frequency channels
130
131 /**
132 * Return true if a valid channel has been set, false otherwise.
133 *
134 * @return true if a valid channel has been set, false otherwise
135 */
136 bool IsSet() const;
137 /**
138 * Set the channel according to the specified parameters if a unique
139 * frequency channel matches the specified criteria, or abort the
140 * simulation otherwise.
141 * If the channel width is a multiple of 20 MHz, the primary 20 MHz channel
142 * is set to the 20 MHz subchannel with the lowest center frequency.
143 *
144 * @param segments the frequency segments
145 * @param standard the standard
146 */
147 void Set(const std::vector<FrequencyChannelInfo>& segments, WifiStandard standard);
148 /**
149 * Set the default channel of the given width and for the given standard and band.
150 * If the channel width is a multiple of 20 MHz, the primary 20 MHz channel
151 * is set to the 20 MHz subchannel with the lowest center frequency.
152 *
153 * @param width the channel width
154 * @param standard the standard
155 * @param band the PHY band
156 */
157 void SetDefault(MHz_u width, WifiStandard standard, WifiPhyBand band);
158
159 /**
160 * Get the default channel number for a given segment of the given width and for the given
161 * standard and band.
162 *
163 * @param width the channel width
164 * @param standard the standard
165 * @param band the PHY band
166 * @param previousChannelNumber the channel number of the previous (in frequency) segment (if
167 * non-contiguous operating channel is used). If there is no place for another segment that is
168 * not contiguous to that previous one (at a higher frequency), an error is thrown
169 * @return the default channel number
170 */
171 static uint8_t GetDefaultChannelNumber(
172 MHz_u width,
173 WifiStandard standard,
174 WifiPhyBand band,
175 std::optional<uint8_t> previousChannelNumber = std::nullopt);
176
177 /**
178 * Return the channel number for a given frequency segment.
179 * Segments are ordered by increasing frequencies, hence by default
180 * it returns the channel number of the segment occuping the lowest
181 * frequencies when a non-contiguous operating channel is used.
182 *
183 * @param segment the index of the frequency segment (if operating channel is non-contiguous)
184 * @return the channel number for a given frequency segment
185 */
186 uint8_t GetNumber(std::size_t segment = 0) const;
187 /**
188 * Return the center frequency for a given frequency segment.
189 * Segments are ordered by increasing frequencies, hence by default
190 * it returns the center frequency of the segment occuping the lowest
191 * frequencies when a non-contiguous operating channel is used.
192 *
193 * @param segment the index of the frequency segment (if operating channel is non-contiguous)
194 * @return the center frequency for a given frequency segment
195 */
196 MHz_u GetFrequency(std::size_t segment = 0) const;
197 /**
198 * Return the channel width for a given frequency segment.
199 * Segments are ordered by increasing frequencies, hence by default
200 * it returns the channel width of the segment occuping the lowest
201 * frequencies when a non-contiguous operating channel is used.
202 *
203 * @param segment the index of the frequency segment (if operating channel is non-contiguous)
204 * @return the channel width for a given frequency segment
205 */
206 MHz_u GetWidth(std::size_t segment = 0) const;
207 /**
208 * Return the width of the whole operating channel.
209 *
210 * @return the width of the whole operating channel
211 */
212 MHz_u GetTotalWidth() const;
213 /**
214 * Return the channel number per segment.
215 * Segments are ordered by increasing frequencies.
216 *
217 * @return the channel number per segment
218 */
219 std::vector<uint8_t> GetNumbers() const;
220 /**
221 * Return the center frequency per segment.
222 * Segments are ordered by increasing frequencies.
223 *
224 * @return the center frequency per segment
225 */
226 std::vector<MHz_u> GetFrequencies() const;
227 /**
228 * Return the channel width per segment.
229 * Segments are ordered by increasing frequencies.
230 *
231 * @return the channel width per segment
232 */
233 std::vector<MHz_u> GetWidths() const;
234 /**
235 * Return the width type of the operating channel.
236 *
237 * @return the width type of the operating channel
238 */
240 /**
241 * Return the PHY band of the operating channel
242 *
243 * @return the PHY band of the operating channel
244 */
245 WifiPhyBand GetPhyBand() const;
246 /**
247 * Return whether the operating channel is an OFDM channel.
248 *
249 * @return whether the operating channel is an OFDM channel
250 */
251 bool IsOfdm() const;
252 /**
253 * Return whether the operating channel is a DSSS channel.
254 *
255 * @return whether the operating channel is a DSSS channel
256 */
257 bool IsDsss() const;
258 /**
259 * Return whether the operating channel is an 802.11p channel.
260 *
261 * @return whether the operating channel is an 802.11p channel
262 */
263 bool Is80211p() const;
264
265 /**
266 * If the operating channel width is a multiple of 20 MHz, return the index of the
267 * primary channel of the given width within the operating channel (0 indicates
268 * the 20 MHz subchannel with the lowest center frequency). Otherwise, return 0.
269 *
270 * @param primaryChannelWidth the width of the primary channel
271 * @return the index of the requested primary channel within the operating channel
272 */
273 uint8_t GetPrimaryChannelIndex(MHz_u primaryChannelWidth) const;
274
275 /**
276 * If the operating channel width is made of a multiple of 20 MHz, return the index of the
277 * secondary channel of the given width within the operating channel (0 indicates
278 * the 20 MHz subchannel with the lowest center frequency). Otherwise, return 0.
279 *
280 * @param secondaryChannelWidth the width of the secondary channel
281 * @return the index of the requested secondary channel within the operating channel
282 */
283 uint8_t GetSecondaryChannelIndex(MHz_u secondaryChannelWidth) const;
284
285 /**
286 * Set the index of the primary 20 MHz channel (0 indicates the 20 MHz subchannel
287 * with the lowest center frequency among all segments).
288 *
289 * @param index the index of the primary 20 MHz channel
290 */
291 void SetPrimary20Index(uint8_t index);
292
293 /**
294 * Get the center frequency of the primary channel of the given width.
295 *
296 * @param primaryChannelWidth the width of the primary channel
297 * @return the center frequency of the primary channel of the given width
298 */
299 MHz_u GetPrimaryChannelCenterFrequency(MHz_u primaryChannelWidth) const;
300
301 /**
302 * Get the center frequency of the secondary channel of the given width.
303 *
304 * @param secondaryChannelWidth the width of the secondary channel
305 * @return the center frequency of the secondary channel of the given width
306 */
307 MHz_u GetSecondaryChannelCenterFrequency(MHz_u secondaryChannelWidth) const;
308
309 /**
310 * Get the channel indices of all the 20 MHz channels included in the primary
311 * channel of the given width, if such primary channel exists, or an empty set,
312 * otherwise.
313 *
314 * @param width the width of the primary channel
315 * @return the channel indices of all the 20 MHz channels included in the primary
316 * channel of the given width, if such primary channel exists, or an empty set,
317 * otherwise
318 */
319 std::set<uint8_t> GetAll20MHzChannelIndicesInPrimary(MHz_u width) const;
320 /**
321 * Get the channel indices of all the 20 MHz channels included in the secondary
322 * channel of the given width, if such secondary channel exists, or an empty set,
323 * otherwise.
324 *
325 * @param width the width of the secondary channel
326 * @return the channel indices of all the 20 MHz channels included in the secondary
327 * channel of the given width, if such secondary channel exists, or an empty set,
328 * otherwise
329 */
330 std::set<uint8_t> GetAll20MHzChannelIndicesInSecondary(MHz_u width) const;
331 /**
332 * Get the channel indices of all the 20 MHz channels included in the secondary
333 * channel corresponding to the given primary channel, if such secondary channel
334 * exists, or an empty set, otherwise.
335 *
336 * @param primaryIndices the channel indices of all the 20 MHz channels included
337 * in the primary channel
338 * @return the channel indices of all the 20 MHz channels included in the secondary
339 * channel corresponding to the given primary channel, if such secondary channel
340 * exists, or an empty set, otherwise
341 */
342 std::set<uint8_t> GetAll20MHzChannelIndicesInSecondary(
343 const std::set<uint8_t>& primaryIndices) const;
344
345 /**
346 * Find the first frequency segment matching the specified parameters.
347 *
348 * @param number the channel number (use 0 to leave it unspecified)
349 * @param frequency the channel center frequency in MHz (use 0 to leave it unspecified)
350 * @param width the channel width (use 0 to leave it unspecified)
351 * @param standard the standard (use WIFI_STANDARD_UNSPECIFIED not to check whether a
352 * channel is suitable for a specific standard)
353 * @param band the PHY band
354 * @param start an iterator pointing to the channel to start the search with
355 * @return an iterator pointing to the found channel, if any, or to past-the-end
356 * of the set of available channels
357 */
358 static ConstIterator FindFirst(uint8_t number,
359 MHz_u frequency,
360 MHz_u width,
361 WifiStandard standard,
362 WifiPhyBand band,
363 ConstIterator start = m_frequencyChannels.begin());
364
365 /**
366 * Get channel number of the primary channel
367 * @param primaryChannelWidth the width of the primary channel
368 * @param standard the standard
369 *
370 * @return channel number of the primary channel
371 */
372 uint8_t GetPrimaryChannelNumber(MHz_u primaryChannelWidth, WifiStandard standard) const;
373
374 /**
375 * Get a WifiPhyOperatingChannel object corresponding to the primary channel of the given width.
376 *
377 * @param primaryChannelWidth the width of the primary channel in MHz
378 * @return a WifiPhyOperatingChannel object corresponding to the primary channel of the given
379 * width
380 */
381 WifiPhyOperatingChannel GetPrimaryChannel(MHz_u primaryChannelWidth) const;
382
383 /**
384 * Get the channel indices of the minimum subset of 20 MHz channels containing the given RU.
385 *
386 * @param ru the given RU
387 * @param width the width of the channel to which the given RU refers to; normally,
388 * it is the width of the PPDU for which the RU is allocated
389 * @return the channel indices of the minimum subset of 20 MHz channels containing the given RU
390 */
391 std::set<uint8_t> Get20MHzIndicesCoveringRu(HeRu::RuSpec ru, MHz_u width) const;
392
393 /**
394 * Get the index of the segment that contains a given primary channel.
395 *
396 * @param primaryChannelWidth the width of the primary channel
397 * @return the index of the segment that contains the primary channel
398 */
399 uint8_t GetPrimarySegmentIndex(MHz_u primaryChannelWidth) const;
400
401 /**
402 * Get the index of the segment that contains a given secondary channel.
403 *
404 * @param secondaryChannelWidth the width of the secondary channel
405 * @return the index of the segment that contains the secondary channel
406 */
407 uint8_t GetSecondarySegmentIndex(MHz_u secondaryChannelWidth) const;
408
409 /**
410 * Get the number of frequency segments in the operating channel.
411 * This is only more than one if a non-contiguous operating channel is used.
412 *
413 * @return the number of frequency segments
414 */
415 std::size_t GetNSegments() const;
416
417 private:
418 ConstIteratorSet m_channelIts; //!< const iterators pointing to the configured frequency channel
419 uint8_t m_primary20Index; /**< index of the primary20 channel (0 indicates the 20 MHz
420 subchannel with the lowest center frequency) */
421};
422
423/**
424 * @brief Stream insertion operator.
425 *
426 * @param os the stream
427 * @param channel the operating channel
428 * @returns a reference to the stream
429 */
430std::ostream& operator<<(std::ostream& os, const WifiPhyOperatingChannel& channel);
431
432} // namespace ns3
433
434#endif /* WIFI_PHY_OPERATING_CHANNEL_H */
RU Specification.
Definition he-ru.h:57
Class that keeps track of all information about the current PHY operating channel.
MHz_u GetTotalWidth() const
Return the width of the whole operating channel.
bool IsSet() const
Return true if a valid channel has been set, false otherwise.
std::set< ConstIterator, Compare > ConstIteratorSet
Typedef for a set of const iterator pointing to the segments of a channel.
uint8_t GetNumber(std::size_t segment=0) const
Return the channel number for a given frequency segment.
bool operator==(const WifiPhyOperatingChannel &other) const
Check if the given WifiPhyOperatingChannel is equivalent.
WifiPhyOperatingChannel()
Create an uninitialized PHY operating channel.
WifiChannelWidthType GetWidthType() const
Return the width type of the operating channel.
std::set< uint8_t > Get20MHzIndicesCoveringRu(HeRu::RuSpec ru, MHz_u width) const
Get the channel indices of the minimum subset of 20 MHz channels containing the given RU.
MHz_u GetSecondaryChannelCenterFrequency(MHz_u secondaryChannelWidth) const
Get the center frequency of the secondary channel of the given width.
static const std::set< FrequencyChannelInfo > m_frequencyChannels
Available frequency channels.
std::set< FrequencyChannelInfo >::const_iterator ConstIterator
Typedef for a const iterator pointing to a channel in the set of available channels.
bool operator!=(const WifiPhyOperatingChannel &other) const
Check if the given WifiPhyOperatingChannel is different.
std::set< uint8_t > GetAll20MHzChannelIndicesInSecondary(MHz_u width) const
Get the channel indices of all the 20 MHz channels included in the secondary channel of the given wid...
bool IsDsss() const
Return whether the operating channel is a DSSS channel.
void SetPrimary20Index(uint8_t index)
Set the index of the primary 20 MHz channel (0 indicates the 20 MHz subchannel with the lowest center...
static uint8_t GetDefaultChannelNumber(MHz_u width, WifiStandard standard, WifiPhyBand band, std::optional< uint8_t > previousChannelNumber=std::nullopt)
Get the default channel number for a given segment of the given width and for the given standard and ...
uint8_t GetSecondarySegmentIndex(MHz_u secondaryChannelWidth) const
Get the index of the segment that contains a given secondary channel.
std::set< uint8_t > GetAll20MHzChannelIndicesInPrimary(MHz_u width) const
Get the channel indices of all the 20 MHz channels included in the primary channel of the given width...
uint8_t GetSecondaryChannelIndex(MHz_u secondaryChannelWidth) const
If the operating channel width is made of a multiple of 20 MHz, return the index of the secondary cha...
std::size_t GetNSegments() const
Get the number of frequency segments in the operating channel.
void Set(const std::vector< FrequencyChannelInfo > &segments, WifiStandard standard)
Set the channel according to the specified parameters if a unique frequency channel matches the speci...
void SetDefault(MHz_u width, WifiStandard standard, WifiPhyBand band)
Set the default channel of the given width and for the given standard and band.
ConstIteratorSet m_channelIts
const iterators pointing to the configured frequency channel
MHz_u GetWidth(std::size_t segment=0) const
Return the channel width for a given frequency segment.
uint8_t GetPrimaryChannelIndex(MHz_u primaryChannelWidth) const
If the operating channel width is a multiple of 20 MHz, return the index of the primary channel of th...
bool Is80211p() const
Return whether the operating channel is an 802.11p channel.
MHz_u GetPrimaryChannelCenterFrequency(MHz_u primaryChannelWidth) const
Get the center frequency of the primary channel of the given width.
std::vector< uint8_t > GetNumbers() const
Return the channel number per segment.
std::vector< MHz_u > GetFrequencies() const
Return the center frequency per segment.
bool IsOfdm() const
Return whether the operating channel is an OFDM channel.
MHz_u GetFrequency(std::size_t segment=0) const
Return the center frequency for a given frequency segment.
static ConstIterator FindFirst(uint8_t number, MHz_u frequency, MHz_u width, WifiStandard standard, WifiPhyBand band, ConstIterator start=m_frequencyChannels.begin())
Find the first frequency segment matching the specified parameters.
uint8_t m_primary20Index
index of the primary20 channel (0 indicates the 20 MHz subchannel with the lowest center frequency)
std::vector< MHz_u > GetWidths() const
Return the channel width per segment.
uint8_t GetPrimarySegmentIndex(MHz_u primaryChannelWidth) const
Get the index of the segment that contains a given primary channel.
WifiPhyBand GetPhyBand() const
Return the PHY band of the operating channel.
WifiPhyOperatingChannel GetPrimaryChannel(MHz_u primaryChannelWidth) const
Get a WifiPhyOperatingChannel object corresponding to the primary channel of the given width.
uint8_t GetPrimaryChannelNumber(MHz_u primaryChannelWidth, WifiStandard standard) const
Get channel number of the primary channel.
WifiStandard
Identifies the IEEE 802.11 specifications that a Wifi device can be configured to use.
FrequencyChannelType
Enumeration of frequency channel types.
Definition wifi-types.h:82
WifiPhyBand
Identifies the PHY band.
WifiChannelWidthType
Enumeration of the possible channel widths.
Definition wifi-types.h:22
@ WIFI_PHY_BAND_UNSPECIFIED
Unspecified.
Every class exported by the ns3 library is enclosed in the ns3 namespace.
std::ostream & operator<<(std::ostream &os, const Angles &a)
Definition angles.cc:148
A structure containing the information about a frequency channel.
uint8_t number
the channel number
auto operator<=>(const FrequencyChannelInfo &info) const =default
spaceship operator.
MHz_u frequency
the center frequency
FrequencyChannelType type
the frequency channel type
Comparison functor used to sort the segments by increasing frequencies.
bool operator()(const ConstIterator &a, const ConstIterator &b) const
Functional operator for sorting the frequency segments.
Declaration of the following enums: