A Discrete-Event Network Simulator
API
Loading...
Searching...
No Matches
wifi-utils.h
Go to the documentation of this file.
1/*
2 * Copyright (c) 2016
3 *
4 * SPDX-License-Identifier: GPL-2.0-only
5 *
6 * Author: Sébastien Deronne <sebastien.deronne@gmail.com>
7 */
8
9#ifndef WIFI_UTILS_H
10#define WIFI_UTILS_H
11
12#include "block-ack-type.h"
15#include "wifi-types.h"
16
17#include "ns3/fatal-error.h"
18#include "ns3/ptr.h"
19
20#include <list>
21#include <map>
22#include <set>
23
24namespace ns3
25{
26
27class Mac48Address;
28class WifiMacHeader;
29class Packet;
30class WifiMac;
31class WifiTxVector;
32
33enum class TriggerFrameVariant : uint8_t;
34
35/**
36 * Wifi direction. Values are those defined for the TID-to-Link Mapping Control Direction
37 * field in IEEE 802.11be D3.1 Figure 9-1002ap
38 */
39enum class WifiDirection : uint8_t
40{
42 UPLINK = 1,
44};
45
46/**
47 * @brief Stream insertion operator.
48 *
49 * @param os the stream
50 * @param direction the direction
51 * @returns a reference to the stream
52 */
53inline std::ostream&
54operator<<(std::ostream& os, const WifiDirection& direction)
55{
56 switch (direction)
57 {
59 return (os << "DOWNLINK");
61 return (os << "UPLINK");
63 return (os << "BOTH_DIRECTIONS");
64 default:
65 NS_FATAL_ERROR("Invalid direction");
66 return (os << "INVALID");
67 }
68}
69
70/// @brief IEEE 802.11-2020 9.2.4.5.2 TID subfield
71using tid_t = uint8_t;
72
73/// @brief IEEE 802.11be D7.0 Figure 9-207e—Link ID Info field format
74using linkId_t = uint8_t;
75
76/// @brief TID-indexed map of the link set to which the TID is mapped
77using WifiTidLinkMapping = std::map<tid_t, std::set<linkId_t>>;
78
79/**
80 * Convert from dBm to Watts.
81 *
82 * @param val the value in dBm
83 *
84 * @return the equivalent Watts for the given dBm
85 */
87/**
88 * Convert from dB to ratio.
89 *
90 * @param val the value in dB
91 *
92 * @return ratio in linear scale
93 */
94double DbToRatio(dB_u val);
95/**
96 * Convert from Watts to dBm.
97 *
98 * @param val the value in Watts
99 *
100 * @return the equivalent dBm for the given Watts
101 */
102dBm_u WToDbm(Watt_u val);
103/**
104 * Convert from ratio to dB.
105 *
106 * @param ratio the ratio in linear scale
107 *
108 * @return the value in dB
109 */
110dB_u RatioToDb(double ratio);
111
112/**
113 * Convert from MHz to Hz.
114 *
115 * @param val the value in MHz
116 *
117 * @return the value in Hz
118 */
119inline Hz_u
121{
122 return val * 1e6;
123}
124
125/**
126 * Convert from Hz to MHz.
127 *
128 * @param val the value in Hz
129 *
130 * @return the value in MHz
131 */
132inline MHz_u
134{
135 return val * 1e-6;
136}
137
138/**
139 * Return the number of 20 MHz subchannels covering the channel width.
140 *
141 * @param channelWidth the channel width
142 * @return the number of 20 MHz subchannels
143 */
144inline std::size_t
146{
147 NS_ASSERT(static_cast<uint16_t>(channelWidth) % 20 == 0);
148 return channelWidth / MHz_u{20};
149}
150
151/**
152 * Return the number of 20 MHz subchannels covering the channel width between a lower frequency and
153 * an upper frequency. This function should only be called when the channel width between the lower
154 * frequency and the upper frequency is a multiple of 20 MHz.
155 *
156 * @param lower the lower frequency
157 * @param upper the upper frequency
158 * @return the number of 20 MHz subchannels
159 */
160inline std::size_t
162{
163 NS_ASSERT(upper >= lower);
164 const auto width = upper - lower;
165 NS_ASSERT((static_cast<uint16_t>(width) % 20 == 0));
166 return Count20MHzSubchannels(width);
167}
168
169/**
170 * Return the total Ack size (including FCS trailer).
171 *
172 * @return the total Ack size in bytes
173 */
175/**
176 * Return the total BlockAck size (including FCS trailer).
177 *
178 * @param type the BlockAck type
179 * @return the total BlockAck size in bytes
180 */
181uint32_t GetBlockAckSize(BlockAckType type);
182/**
183 * Return the total BlockAckRequest size (including FCS trailer).
184 *
185 * @param type the BlockAckRequest type
186 * @return the total BlockAckRequest size in bytes
187 */
188uint32_t GetBlockAckRequestSize(BlockAckReqType type);
189/**
190 * Return the total MU-BAR size (including FCS trailer).
191 *
192 * @param variant the Common Info field variant of the MU-BAR
193 * @param bw the bandwidth over which the MU-BAR is transmitted
194 * @param types the list of Block Ack Request types of the individual BARs
195 * @return the total MU-BAR size in bytes
196 */
197uint32_t GetMuBarSize(TriggerFrameVariant variant,
198 MHz_u bw,
199 const std::list<BlockAckReqType>& types);
200/**
201 * Return the total RTS size (including FCS trailer).
202 *
203 * @return the total RTS size in bytes
204 */
206/**
207 * Return the total CTS size (including FCS trailer).
208 *
209 * @return the total CTS size in bytes
210 */
212
213/**
214 * @param txVector the TXVECTOR used to transmit a frame whose reception failed
215 * @return the estimated Ack TX time, based on Table 10-8 of IEEE 802.11REVme D7.0
216 */
217Time GetEstimatedAckTxTime(const WifiTxVector& txVector);
218
219/**
220 * @param seq MPDU sequence number
221 * @param winstart sequence number window start
222 * @param winsize the size of the sequence number window
223 * @returns true if in the window
224 *
225 * This method checks if the MPDU's sequence number is inside the scoreboard boundaries or not
226 */
227bool IsInWindow(uint16_t seq, uint16_t winstart, uint16_t winsize);
228/**
229 * Add FCS trailer to a packet.
230 *
231 * @param packet the packet to add a trailer to
232 */
233void AddWifiMacTrailer(Ptr<Packet> packet);
234/**
235 * Return the total size of the packet after WifiMacHeader and FCS trailer
236 * have been added.
237 *
238 * @param packet the packet to be encapsulated with WifiMacHeader and FCS trailer
239 * @param hdr the WifiMacHeader
240 * @param isAmpdu whether packet is part of an A-MPDU
241 * @return the total packet size
242 */
243uint32_t GetSize(Ptr<const Packet> packet, const WifiMacHeader* hdr, bool isAmpdu);
244
245/**
246 * Check if the given TID-to-Link Mappings are valid for a negotiation type of 1. Specifically,
247 * it is checked whether all TIDs are mapped to the same set of links.
248 *
249 * @param dlLinkMapping the given TID-to-Link Mapping for Downlink
250 * @param ulLinkMapping the given TID-to-Link Mapping for Uplink
251 * @return whether the given TID-to-Link Mappings are valid for a negotiation type of 1
252 */
254 const WifiTidLinkMapping& ulLinkMapping);
255
256/**
257 * Check whether a MAC destination address corresponds to a groupcast transmission.
258 *
259 * @param adr the MAC address
260 * @return true if the MAC address is a group address that is not a broadcast address
261 */
262bool IsGroupcast(const Mac48Address& adr);
263
264/**
265 * Return whether a given packet is transmitted using the GCR service.
266 *
267 * @param mac a pointer to the wifi MAC
268 * @param hdr the MAC header of the packet to check
269 * @return true if the packet is transmitted using the GCR service, false otherwise
270 */
271bool IsGcr(Ptr<WifiMac> mac, const WifiMacHeader& hdr);
272
273/**
274 * Get the MAC address of the individually addressed recipient to use for a given packet.
275 * If this is a groupcast packet to be transmitted with the GCR service, the GCR manager is
276 * requested to return which individually addressed recipient to use. Otherwise, it corresponds to
277 * the address1 of the MAC header.
278 *
279 * @param mac a pointer to the wifi MAC
280 * @param hdr the MAC header of the packet to check
281 * @return the MAC address of the individually addressed recipient to use
282 */
283Mac48Address GetIndividuallyAddressedRecipient(Ptr<WifiMac> mac, const WifiMacHeader& hdr);
284
285/**
286 * Get the frequency range corresponding to the given PHY band.
287 *
288 * @param band the given PHY band
289 * @return the frequency range corresponding to the given PHY band
290 */
291FrequencyRange GetFrequencyRange(WifiPhyBand band);
292
293/// Link ID for single link operations (helps tracking places where correct link
294/// ID is to be used to support multi-link operations)
295static constexpr uint8_t SINGLE_LINK_OP_ID = 0;
296
297/// Invalid link identifier
298static constexpr uint8_t WIFI_LINKID_UNDEFINED = 0xff;
299
300/// Invalid TID identifier
301static constexpr uint8_t WIFI_TID_UNDEFINED = 0xff;
302
303} // namespace ns3
304
305#endif /* WIFI_UTILS_H */
an EUI-48 address
network packets
Definition packet.h:228
Implements the IEEE 802.11 MAC header.
base class for all MAC-level wifi objects.
Definition wifi-mac.h:90
This class mimics the TXVECTOR which is to be passed to the PHY in order to define the parameters whi...
#define NS_ASSERT(condition)
At runtime, in debugging builds, if this condition is not true, the program prints the source file,...
Definition assert.h:55
#define NS_FATAL_ERROR(msg)
Report a fatal error with a message and terminate.
TriggerFrameVariant
The different variants for Common Info field and User Info field of Trigger Frames.
Every class exported by the ns3 library is enclosed in the ns3 namespace.
uint32_t GetMuBarSize(TriggerFrameVariant variant, MHz_u bw, const std::list< BlockAckReqType > &types)
Return the total MU-BAR size (including FCS trailer).
Definition wifi-utils.cc:79
FrequencyRange GetFrequencyRange(WifiPhyBand band)
Get the frequency range corresponding to the given PHY band.
static constexpr uint8_t WIFI_TID_UNDEFINED
Invalid TID identifier.
Definition wifi-utils.h:301
uint32_t GetRtsSize()
Return the total RTS size (including FCS trailer).
Definition wifi-utils.cc:98
dB_u RatioToDb(double ratio)
Convert from ratio to dB.
Definition wifi-utils.cc:45
std::ostream & operator<<(std::ostream &os, const Angles &a)
Definition angles.cc:148
double Hz_u
Hz weak type.
Definition wifi-units.h:30
MHz_u HzToMHz(Hz_u val)
Convert from Hz to MHz.
Definition wifi-utils.h:133
dBm_u WToDbm(Watt_u val)
Convert from Watts to dBm.
Definition wifi-utils.cc:38
double MHz_u
MHz weak type.
Definition wifi-units.h:31
bool IsGroupcast(const Mac48Address &adr)
Check whether a MAC destination address corresponds to a groupcast transmission.
Time GetEstimatedAckTxTime(const WifiTxVector &txVector)
std::size_t Count20MHzSubchannels(MHz_u channelWidth)
Return the number of 20 MHz subchannels covering the channel width.
Definition wifi-utils.h:145
double dBm_u
dBm weak type
Definition wifi-units.h:27
uint32_t GetBlockAckRequestSize(BlockAckReqType type)
Return the total BlockAckRequest size (including FCS trailer).
Definition wifi-utils.cc:69
static constexpr uint8_t SINGLE_LINK_OP_ID
Link ID for single link operations (helps tracking places where correct link ID is to be used to supp...
Definition wifi-utils.h:295
double DbToRatio(dB_u val)
Convert from dB to ratio.
Definition wifi-utils.cc:26
uint8_t tid_t
IEEE 802.11-2020 9.2.4.5.2 TID subfield.
Definition wifi-utils.h:71
WifiDirection
Wifi direction.
Definition wifi-utils.h:40
Watt_u DbmToW(dBm_u val)
Convert from dBm to Watts.
Definition wifi-utils.cc:32
bool TidToLinkMappingValidForNegType1(const WifiTidLinkMapping &dlLinkMapping, const WifiTidLinkMapping &ulLinkMapping)
Check if the given TID-to-Link Mappings are valid for a negotiation type of 1.
uint32_t GetBlockAckSize(BlockAckType type)
Return the total BlockAck size (including FCS trailer).
Definition wifi-utils.cc:59
void AddWifiMacTrailer(Ptr< Packet > packet)
Add FCS trailer to a packet.
std::map< tid_t, std::set< linkId_t > > WifiTidLinkMapping
TID-indexed map of the link set to which the TID is mapped.
Definition wifi-utils.h:77
static constexpr uint8_t WIFI_LINKID_UNDEFINED
Invalid link identifier.
Definition wifi-utils.h:298
Hz_u MHzToHz(MHz_u val)
Convert from MHz to Hz.
Definition wifi-utils.h:120
uint32_t GetAckSize()
Return the total Ack size (including FCS trailer).
Definition wifi-utils.cc:51
uint8_t linkId_t
IEEE 802.11be D7.0 Figure 9-207e—Link ID Info field format.
Definition wifi-utils.h:74
uint32_t GetSize(Ptr< const Packet > packet, const WifiMacHeader *hdr, bool isAmpdu)
Return the total size of the packet after WifiMacHeader and FCS trailer have been added.
bool IsGcr(Ptr< WifiMac > mac, const WifiMacHeader &hdr)
Return whether a given packet is transmitted using the GCR service.
double Watt_u
Watt weak type.
Definition wifi-units.h:25
uint32_t GetCtsSize()
Return the total CTS size (including FCS trailer).
Mac48Address GetIndividuallyAddressedRecipient(Ptr< WifiMac > mac, const WifiMacHeader &hdr)
Get the MAC address of the individually addressed recipient to use for a given packet.
double dB_u
dB weak type
Definition wifi-units.h:28
bool IsInWindow(uint16_t seq, uint16_t winstart, uint16_t winsize)
Declaration of the constants used across wifi module.