A Discrete-Event Network Simulator
API
Loading...
Searching...
No Matches
qos-utils.h
Go to the documentation of this file.
1/*
2 * Copyright (c) 2009 MIRKO BANCHI
3 *
4 * SPDX-License-Identifier: GPL-2.0-only
5 *
6 * Author: Mirko Banchi <mk.banchi@gmail.com>
7 */
8
9#ifndef QOS_UTILS_H
10#define QOS_UTILS_H
11
12#include "ns3/fatal-error.h"
13#include "ns3/ptr.h"
14#include "ns3/wifi-export.h"
15
16#include <map>
17
18namespace ns3
19{
20
21class Packet;
22class WifiMacHeader;
23class QueueItem;
24class Mac48Address;
25
26typedef std::pair<Mac48Address, uint8_t> WifiAddressTidPair; //!< (MAC address, TID) pair
27
28/**
29 * Function object to compute the hash of a (MAC address, TID) pair
30 */
32{
33 /**
34 * Functional operator for (MAC address, TID) hash computation.
35 *
36 * @param addressTidPair the (MAC address, TID) pair
37 * @return the hash
38 */
39 std::size_t operator()(const WifiAddressTidPair& addressTidPair) const;
40};
41
42/**
43 * Function object to compute the hash of a MAC address
44 */
46{
47 /**
48 * Functional operator for MAC address hash computation.
49 *
50 * @param address the MAC address
51 * @return the hash
52 */
53 std::size_t operator()(const Mac48Address& address) const;
54};
55
56/**
57 * @ingroup wifi
58 * This enumeration defines the Access Categories as an enumeration
59 * with values corresponding to the AC index (ACI) values specified
60 * (Table 8-104 "ACI-to-AC coding"; IEEE 802.11-2012).
61 */
62enum AcIndex : uint8_t
63{
64 /** Best Effort */
65 AC_BE = 0,
66 /** Background */
67 AC_BK = 1,
68 /** Video */
69 AC_VI = 2,
70 /** Voice */
71 AC_VO = 3,
72 /** Non-QoS */
74 /** Beacon queue */
76 /** Total number of ACs */
78};
79
80/**
81 * @brief Stream insertion operator.
82 *
83 * @param os the stream
84 * @param acIndex the AC index
85 * @returns a reference to the stream
86 */
87inline std::ostream&
88operator<<(std::ostream& os, const AcIndex& acIndex)
89{
90 switch (acIndex)
91 {
92 case AC_BE:
93 return (os << "AC BE");
94 case AC_BK:
95 return (os << "AC BK");
96 case AC_VI:
97 return (os << "AC VI");
98 case AC_VO:
99 return (os << "AC VO");
100 case AC_BE_NQOS:
101 return (os << "AC BE NQOS");
102 case AC_BEACON:
103 return (os << "AC BEACON");
104 case AC_UNDEF:
105 return (os << "AC Undefined");
106 default:
107 NS_FATAL_ERROR("Unknown AC index");
108 return (os << "Unknown");
109 }
110}
111
112/**
113 * @ingroup wifi
114 * This class stores the pair of TIDs of an Access Category.
115 */
117{
118 public:
119 /**
120 * Constructor.
121 *
122 * @param lowTid the TID with lower priority
123 * @param highTid the TID with higher priority
124 */
125 WifiAc(uint8_t lowTid, uint8_t highTid);
126 /**
127 * Get the TID with lower priority
128 *
129 * @return the TID with lower priority
130 */
131 uint8_t GetLowTid() const;
132 /**
133 * Get the TID with higher priority
134 *
135 * @return the TID with higher priority
136 */
137 uint8_t GetHighTid() const;
138 /**
139 * Given a TID belonging to this Access Category, get the other TID of this AC.
140 *
141 * @param tid a TID belonging to this AC
142 * @return the other TID belonging to this AC
143 */
144 uint8_t GetOtherTid(uint8_t tid) const;
145
146 private:
147 uint8_t m_lowTid; //!< the TID with lower priority
148 uint8_t m_highTid; //!< the TID with higher priority
149};
150
151/**
152 * @ingroup wifi
153 * Operator> overload returning true if the AC on the left has higher priority
154 * than the AC on the right.
155 *
156 * @param left the AC on the left of operator>
157 * @param right the AC on the right of operator>
158 * @return true if the AC on the left has higher priority than the AC on the right
159 */
160bool operator>(AcIndex left, AcIndex right);
161
162/**
163 * @ingroup wifi
164 * Operator>= overload returning true if the AC on the left has higher or the same
165 * priority than the AC on the right.
166 *
167 * @param left the AC on the left of operator>=
168 * @param right the AC on the right of operator>=
169 * @return true if the AC on the left has higher or the same priority than the AC on the right
170 */
171bool operator>=(AcIndex left, AcIndex right);
172
173/**
174 * @ingroup wifi
175 * Operator< overload returning true if the AC on the left has lower priority
176 * than the AC on the right.
177 *
178 * @param left the AC on the left of operator<
179 * @param right the AC on the right of operator<
180 * @return true if the AC on the left has lower priority than the AC on the right
181 */
182bool operator<(AcIndex left, AcIndex right);
183
184/**
185 * @ingroup wifi
186 * Operator<= overload returning true if the AC on the left has lower or the same
187 * priority than the AC on the right.
188 *
189 * @param left the AC on the left of operator<=
190 * @param right the AC on the right of operator<=
191 * @return true if the AC on the left has lower or the same priority than the AC on the right
192 */
193bool operator<=(AcIndex left, AcIndex right);
194
195/**
196 * Map containing the four ACs in increasing order of priority (according to
197 * Table 10-1 "UP-to-AC Mappings" of 802.11-2016)
198 */
199WIFI_EXPORT extern const std::map<AcIndex, WifiAc> wifiAcList;
200
201/**
202 * @ingroup wifi
203 * Maps TID (Traffic ID) to Access classes.
204 * For more details see (Table 9-1 "UP-to-AC mapping"; IEEE 802.11-2012).
205 *
206 * @param tid the Traffic ID to be mapped to Access class
207 * @return the access class for the given TID
208 */
209AcIndex QosUtilsMapTidToAc(uint8_t tid);
210
211/**
212 * @ingroup wifi
213 * Next function is useful to correctly sort buffered packets under block ack.
214 * When an BAR is received from originator station, completed "old"
215 * (see section 9.10.3 in IEEE 802.11e) packets must be forwarded up before "new" packets.
216 *
217 * @param seqControl the sequence control field
218 * @param endSequence the sequence number ending the acknowledgment window
219 *
220 * @return a unique integer for the given sequence control and end sequence
221 */
222uint32_t QosUtilsMapSeqControlToUniqueInteger(uint16_t seqControl, uint16_t endSequence);
223
224/**
225 * @ingroup wifi
226 * This function checks if packet with sequence number <i>seqNumber</i> is an "old" packet.
227 * The sequence number space is considered divided into two parts, one of which is "old" and
228 * one of which is "new" by means of a boundary created by adding half the sequence number
229 * range to the starting sequence number <i>startingSeq</i>. So this function works fine also
230 * when <i>seqNumber</i> is smaller than <i>startingSeq</i> and <i>startingSeq</i> + 2048 is greater
231 * than 4096 because all comparison are circular modulo 2^12. The following are possible scenarios:
232 *
233 * ----- = old packets
234 * +++++ = new packets
235 *
236 * CASE A:
237 *
238 * 0 4095
239 * |++++++|----------------|++++++|
240 * ^ ^
241 * | endSeq | startingSeq
242 *
243 *
244 * CASE B:
245 *
246 * 0 4095
247 * |------|++++++++++++++++|-----|
248 * ^ ^
249 * | startingSeq | endSeq
250 *
251 * Here in the examples endSeq is the sequenceNumber of the "last" new packet.
252 * So this function, when specified a starting sequence and a sequence number, returns true
253 * if that packet (with sequence number <i>numberSeq</i>)) belongs to the section of the
254 * sequence number space marked with '-' characters. The function returns false otherwise.
255 *
256 * @param startingSeq the starting sequence number
257 * @param seqNumber the sequence number to be checked
258 *
259 * @return true if the packet is old, false otherwise
260 */
261bool QosUtilsIsOldPacket(uint16_t startingSeq, uint16_t seqNumber);
262
263/**
264 * @ingroup wifi
265 * This function is useful to get traffic id of different packet types.
266 *
267 * @param packet packet to check
268 * @param hdr 802.11 header for packet to check
269 * @return the TID of different packet types
270 */
271uint8_t GetTid(Ptr<const Packet> packet, const WifiMacHeader hdr);
272
273/**
274 * @ingroup wifi
275 * @brief Determine the TX queue for a given packet
276 * @param item the packet
277 * @returns the access category
278 *
279 * Modeled after the Linux function ieee80211_select_queue (net/mac80211/wme.c).
280 * A SocketPriority tag is attached to the packet (or the existing one is
281 * replaced) to carry the user priority, which is set to the three most
282 * significant bits of the DS field (TOS field in case of IPv4 and Traffic
283 * Class field in case of IPv6). The Access Category corresponding to the
284 * user priority according to the QosUtilsMapTidToAc function is returned.
285 *
286 * The following table shows the mapping for the Diffserv Per Hop Behaviors.
287 *
288 * PHB | TOS (binary) | UP | Access Category
289 * -----|--------------|-----|-----------------
290 * EF | 101110xx | 5 | AC_VI
291 * AF11 | 001010xx | 1 | AC_BK
292 * AF21 | 010010xx | 2 | AC_BK
293 * AF31 | 011010xx | 3 | AC_BE
294 * AF41 | 100010xx | 4 | AC_VI
295 * AF12 | 001100xx | 1 | AC_BK
296 * AF22 | 010100xx | 2 | AC_BK
297 * AF32 | 011100xx | 3 | AC_BE
298 * AF42 | 100100xx | 4 | AC_VI
299 * AF13 | 001110xx | 1 | AC_BK
300 * AF23 | 010110xx | 2 | AC_BK
301 * AF33 | 011110xx | 3 | AC_BE
302 * AF43 | 100110xx | 4 | AC_VI
303 * CS0 | 000000xx | 0 | AC_BE
304 * CS1 | 001000xx | 1 | AC_BK
305 * CS2 | 010000xx | 2 | AC_BK
306 * CS3 | 011000xx | 3 | AC_BE
307 * CS4 | 100000xx | 4 | AC_VI
308 * CS5 | 101000xx | 5 | AC_VI
309 * CS6 | 110000xx | 6 | AC_VO
310 * CS7 | 111000xx | 7 | AC_VO
311 *
312 * This method is called by the traffic control layer before enqueuing a
313 * packet in the queue disc, if a queue disc is installed on the outgoing
314 * device, or passing a packet to the device, otherwise.
315 */
317
318} // namespace ns3
319
320#endif /* QOS_UTILS_H */
an EUI-48 address
network packets
Definition packet.h:228
Smart pointer class similar to boost::intrusive_ptr.
Definition ptr.h:67
Base class to represent items of packet Queues.
Definition queue-item.h:36
WifiAc(uint8_t lowTid, uint8_t highTid)
Constructor.
Definition qos-utils.cc:43
uint8_t GetOtherTid(uint8_t tid) const
Given a TID belonging to this Access Category, get the other TID of this AC.
Definition qos-utils.cc:62
uint8_t m_highTid
the TID with higher priority
Definition qos-utils.h:148
uint8_t GetHighTid() const
Get the TID with higher priority.
Definition qos-utils.cc:56
uint8_t GetLowTid() const
Get the TID with lower priority.
Definition qos-utils.cc:50
uint8_t m_lowTid
the TID with lower priority
Definition qos-utils.h:147
Implements the IEEE 802.11 MAC header.
#define NS_FATAL_ERROR(msg)
Report a fatal error with a message and terminate.
bool operator>=(const int64x64_t &lhs, const int64x64_t &rhs)
Greater or equal operator.
Definition int64x64.h:162
bool operator<=(const int64x64_t &lhs, const int64x64_t &rhs)
Less or equal operator.
Definition int64x64.h:149
bool operator>(const Length &left, const Length &right)
Check if left has a value greater than right.
Definition length.cc:410
AcIndex QosUtilsMapTidToAc(uint8_t tid)
Maps TID (Traffic ID) to Access classes.
Definition qos-utils.cc:123
bool QosUtilsIsOldPacket(uint16_t startingSeq, uint16_t seqNumber)
This function checks if packet with sequence number seqNumber is an "old" packet.
Definition qos-utils.cc:156
uint32_t QosUtilsMapSeqControlToUniqueInteger(uint16_t seqControl, uint16_t endSequence)
Next function is useful to correctly sort buffered packets under block ack.
Definition qos-utils.cc:145
uint8_t GetTid(Ptr< const Packet > packet, const WifiMacHeader hdr)
This function is useful to get traffic id of different packet types.
Definition qos-utils.cc:165
AcIndex
This enumeration defines the Access Categories as an enumeration with values corresponding to the AC ...
Definition qos-utils.h:63
uint8_t SelectQueueByDSField(Ptr< QueueItem > item)
Determine the TX queue for a given packet.
Definition qos-utils.cc:227
@ AC_BE_NQOS
Non-QoS.
Definition qos-utils.h:73
@ AC_BE
Best Effort.
Definition qos-utils.h:65
@ AC_VO
Voice.
Definition qos-utils.h:71
@ AC_VI
Video.
Definition qos-utils.h:69
@ AC_BK
Background.
Definition qos-utils.h:67
@ AC_UNDEF
Total number of ACs.
Definition qos-utils.h:77
@ AC_BEACON
Beacon queue.
Definition qos-utils.h:75
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
bool operator<(const EventId &a, const EventId &b)
Definition event-id.h:168
std::pair< Mac48Address, uint8_t > WifiAddressTidPair
(MAC address, TID) pair
Definition qos-utils.h:26
const std::map< AcIndex, WifiAc > wifiAcList
Map containing the four ACs in increasing order of priority (according to Table 10-1 "UP-to-AC Mappin...
Definition qos-utils.cc:115
Function object to compute the hash of a MAC address.
Definition qos-utils.h:46
std::size_t operator()(const Mac48Address &address) const
Functional operator for MAC address hash computation.
Definition qos-utils.cc:34
Function object to compute the hash of a (MAC address, TID) pair.
Definition qos-utils.h:32
std::size_t operator()(const WifiAddressTidPair &addressTidPair) const
Functional operator for (MAC address, TID) hash computation.
Definition qos-utils.cc:23