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"
13#include "wifi-constants.h"
14#include "wifi-types.h"
15
16#include "ns3/fatal-error.h"
17#include "ns3/ptr.h"
18
19#include <list>
20#include <map>
21#include <set>
22
23namespace ns3
24{
25
26class Mac48Address;
27class WifiMacHeader;
28class Packet;
29class WifiMac;
30class WifiTxVector;
31
32enum class TriggerFrameVariant : uint8_t;
33
34/**
35 * Wifi direction. Values are those defined for the TID-to-Link Mapping Control Direction
36 * field in IEEE 802.11be D3.1 Figure 9-1002ap
37 */
38enum class WifiDirection : uint8_t
39{
40 DOWNLINK = 0,
41 UPLINK = 1,
43};
44
45/**
46 * @brief Stream insertion operator.
47 *
48 * @param os the stream
49 * @param direction the direction
50 * @returns a reference to the stream
51 */
52inline std::ostream&
53operator<<(std::ostream& os, const WifiDirection& direction)
54{
55 switch (direction)
56 {
58 return (os << "DOWNLINK");
60 return (os << "UPLINK");
62 return (os << "BOTH_DIRECTIONS");
63 default:
64 NS_FATAL_ERROR("Invalid direction");
65 return (os << "INVALID");
66 }
67}
68
69/// @brief TID-indexed map of the link set to which the TID is mapped
70using WifiTidLinkMapping = std::map<uint8_t, std::set<uint8_t>>;
71
72/**
73 * Convert from dBm to Watts.
74 *
75 * @param val the value in dBm
76 *
77 * @return the equivalent Watts for the given dBm
78 */
80/**
81 * Convert from dB to ratio.
82 *
83 * @param val the value in dB
84 *
85 * @return ratio in linear scale
86 */
87double DbToRatio(dB_u val);
88/**
89 * Convert from Watts to dBm.
90 *
91 * @param val the value in Watts
92 *
93 * @return the equivalent dBm for the given Watts
94 */
96/**
97 * Convert from ratio to dB.
98 *
99 * @param ratio the ratio in linear scale
100 *
101 * @return the value in dB
102 */
103dB_u RatioToDb(double ratio);
104
105/**
106 * Convert from MHz to Hz.
107 *
108 * @param val the value in MHz
109 *
110 * @return the value in Hz
111 */
112inline Hz_u
114{
115 return val * 1e6;
116}
117
118/**
119 * Convert from Hz to MHz.
120 *
121 * @param val the value in Hz
122 *
123 * @return the value in MHz
124 */
125inline MHz_u
127{
128 return val * 1e-6;
129}
130
131/**
132 * Return the number of 20 MHz subchannels covering the channel width.
133 *
134 * @param channelWidth the channel width
135 * @return the number of 20 MHz subchannels
136 */
137inline std::size_t
139{
140 NS_ASSERT(static_cast<uint16_t>(channelWidth) % 20 == 0);
141 return channelWidth / MHz_u{20};
142}
143
144/**
145 * Return the number of 20 MHz subchannels covering the channel width between a lower frequency and
146 * an upper frequency. This function should only be called when the channel width between the lower
147 * frequency and the upper frequency is a multiple of 20 MHz.
148 *
149 * @param lower the lower frequency
150 * @param upper the upper frequency
151 * @return the number of 20 MHz subchannels
152 */
153inline std::size_t
155{
156 NS_ASSERT(upper >= lower);
157 const auto width = upper - lower;
158 NS_ASSERT((static_cast<uint16_t>(width) % 20 == 0));
159 return Count20MHzSubchannels(width);
160}
161
162/**
163 * Return the total Ack size (including FCS trailer).
164 *
165 * @return the total Ack size in bytes
166 */
168/**
169 * Return the total BlockAck size (including FCS trailer).
170 *
171 * @param type the BlockAck type
172 * @return the total BlockAck size in bytes
173 */
174uint32_t GetBlockAckSize(BlockAckType type);
175/**
176 * Return the total BlockAckRequest size (including FCS trailer).
177 *
178 * @param type the BlockAckRequest type
179 * @return the total BlockAckRequest size in bytes
180 */
181uint32_t GetBlockAckRequestSize(BlockAckReqType type);
182/**
183 * Return the total MU-BAR size (including FCS trailer).
184 *
185 * @param variant the Common Info field variant of the MU-BAR
186 * @param bw the bandwidth over which the MU-BAR is transmitted
187 * @param types the list of Block Ack Request types of the individual BARs
188 * @return the total MU-BAR size in bytes
189 */
190uint32_t GetMuBarSize(TriggerFrameVariant variant,
191 MHz_u bw,
192 const std::list<BlockAckReqType>& types);
193/**
194 * Return the total RTS size (including FCS trailer).
195 *
196 * @return the total RTS size in bytes
197 */
199/**
200 * Return the total CTS size (including FCS trailer).
201 *
202 * @return the total CTS size in bytes
203 */
205
206/**
207 * @param txVector the TXVECTOR used to transmit a frame whose reception failed
208 * @return the estimated Ack TX time, based on Table 10-8 of IEEE 802.11REVme D7.0
209 */
210Time GetEstimatedAckTxTime(const WifiTxVector& txVector);
211
212/**
213 * @param seq MPDU sequence number
214 * @param winstart sequence number window start
215 * @param winsize the size of the sequence number window
216 * @returns true if in the window
217 *
218 * This method checks if the MPDU's sequence number is inside the scoreboard boundaries or not
219 */
220bool IsInWindow(uint16_t seq, uint16_t winstart, uint16_t winsize);
221/**
222 * Add FCS trailer to a packet.
223 *
224 * @param packet the packet to add a trailer to
225 */
226void AddWifiMacTrailer(Ptr<Packet> packet);
227/**
228 * Return the total size of the packet after WifiMacHeader and FCS trailer
229 * have been added.
230 *
231 * @param packet the packet to be encapsulated with WifiMacHeader and FCS trailer
232 * @param hdr the WifiMacHeader
233 * @param isAmpdu whether packet is part of an A-MPDU
234 * @return the total packet size
235 */
236uint32_t GetSize(Ptr<const Packet> packet, const WifiMacHeader* hdr, bool isAmpdu);
237
238/**
239 * Check if the given TID-to-Link Mappings are valid for a negotiation type of 1. Specifically,
240 * it is checked whether all TIDs are mapped to the same set of links.
241 *
242 * @param dlLinkMapping the given TID-to-Link Mapping for Downlink
243 * @param ulLinkMapping the given TID-to-Link Mapping for Uplink
244 * @return whether the given TID-to-Link Mappings are valid for a negotiation type of 1
245 */
247 const WifiTidLinkMapping& ulLinkMapping);
248
249/**
250 * Check whether a MAC destination address corresponds to a groupcast transmission.
251 *
252 * @param adr the MAC address
253 * @return true if the MAC address is a group address that is not a broadcast address
254 */
255bool IsGroupcast(const Mac48Address& adr);
256
257/**
258 * Return whether a given packet is transmitted using the GCR service.
259 *
260 * @param mac a pointer to the wifi MAC
261 * @param hdr the MAC header of the packet to check
262 * @return true if the packet is transmitted using the GCR service, false otherwise
263 */
264bool IsGcr(Ptr<WifiMac> mac, const WifiMacHeader& hdr);
265
266/**
267 * Get the MAC address of the individually addressed recipient to use for a given packet.
268 * If this is a groupcast packet to be transmitted with the GCR service, the GCR manager is
269 * requested to return which individually addressed recipient to use. Otherwise, it corresponds to
270 * the address1 of the MAC header.
271 *
272 * @param mac a pointer to the wifi MAC
273 * @param hdr the MAC header of the packet to check
274 * @return the MAC address of the individually addressed recipient to use
275 */
276Mac48Address GetIndividuallyAddressedRecipient(Ptr<WifiMac> mac, const WifiMacHeader& hdr);
277
278/// Link ID for single link operations (helps tracking places where correct link
279/// ID is to be used to support multi-link operations)
280static constexpr uint8_t SINGLE_LINK_OP_ID = 0;
281
282/// Invalid link identifier
283static constexpr uint8_t WIFI_LINKID_UNDEFINED = 0xff;
284
285/// Invalid TID identifier
286static constexpr uint8_t WIFI_TID_UNDEFINED = 0xff;
287
288} // namespace ns3
289
290#endif /* WIFI_UTILS_H */
#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
static constexpr uint8_t WIFI_TID_UNDEFINED
Invalid TID identifier.
Definition wifi-utils.h:286
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:126
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.
std::map< uint8_t, std::set< uint8_t > > WifiTidLinkMapping
TID-indexed map of the link set to which the TID is mapped.
Definition wifi-utils.h:70
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:138
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:280
double DbToRatio(dB_u val)
Convert from dB to ratio.
Definition wifi-utils.cc:26
WifiDirection
Wifi direction.
Definition wifi-utils.h:39
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.
static constexpr uint8_t WIFI_LINKID_UNDEFINED
Invalid link identifier.
Definition wifi-utils.h:283
Hz_u MHzToHz(MHz_u val)
Convert from MHz to Hz.
Definition wifi-utils.h:113
uint32_t GetAckSize()
Return the total Ack size (including FCS trailer).
Definition wifi-utils.cc:51
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.