A Discrete-Event Network Simulator
API
Loading...
Searching...
No Matches
multi-user-scheduler.h
Go to the documentation of this file.
1/*
2 * Copyright (c) 2020 Universita' degli Studi di Napoli Federico II
3 *
4 * SPDX-License-Identifier: GPL-2.0-only
5 *
6 * Author: Stefano Avallone <stavallo@unina.it>
7 */
8
9#ifndef MULTI_USER_SCHEDULER_H
10#define MULTI_USER_SCHEDULER_H
11
12#include "he-ru.h"
13
14#include "ns3/ap-wifi-mac.h"
15#include "ns3/ctrl-headers.h"
16#include "ns3/object.h"
17#include "ns3/wifi-remote-station-manager.h"
18#include "ns3/wifi-tx-parameters.h"
19
20#include <functional>
21#include <unordered_map>
22#include <vector>
23
24namespace ns3
25{
26
27class HeFrameExchangeManager;
28
29/**
30 * @ingroup wifi
31 *
32 * MultiUserScheduler is an abstract base class defining the API that APs
33 * supporting at least VHT can use to determine the format of their next transmission.
34 * VHT APs can only transmit DL MU PPDUs by using MU-MIMO, while HE APs can
35 * transmit both DL MU PPDUs and UL MU PPDUs by using OFDMA in addition to MU-MIMO.
36 *
37 * However, given that DL MU-MIMO is not yet supported, a MultiUserScheduler can
38 * only be aggregated to HE APs.
39 */
41{
42 public:
43 /**
44 * @brief Get the type ID.
45 * @return the object TypeId
46 */
47 static TypeId GetTypeId();
49 ~MultiUserScheduler() override;
50
51 /// Enumeration of the possible transmission formats
59
60 /// Information to be provided in case of DL MU transmission
61 struct DlMuInfo
62 {
63 WifiPsduMap psduMap; //!< the DL MU PPDU to transmit
64 WifiTxParameters txParams; //!< the transmission parameters
65 };
66
67 /// Information to be provided in case of UL MU transmission
68 struct UlMuInfo
69 {
70 CtrlTriggerHeader trigger; //!< the Trigger Frame used to solicit TB PPDUs
71 WifiMacHeader macHdr; //!< the MAC header for the Trigger Frame
72 WifiTxParameters txParams; //!< the transmission parameters for the Trigger Frame
73 };
74
75 /**
76 * Notify the Multi-user Scheduler that the given AC of the AP gained channel
77 * access. The Multi-user Scheduler determines the format of the next transmission.
78 *
79 * @param edca the EDCAF which has been granted the opportunity to transmit
80 * @param availableTime the amount of time allowed for the frame exchange. Pass
81 * Time::Min() in case the TXOP limit is null
82 * @param initialFrame true if the frame being transmitted is the initial frame
83 * of the TXOP. This is used to determine whether the TXOP
84 * limit can be exceeded
85 * @param allowedWidth the allowed width for the next transmission
86 * @param linkId the ID of the link over which channel access was gained
87 * @return the format of the next transmission
88 */
90 Time availableTime,
91 bool initialFrame,
92 MHz_u allowedWidth,
93 uint8_t linkId);
94
95 /**
96 * Get the information required to perform a DL MU transmission on the given link. Note
97 * that this method can only be called if GetTxFormat returns DL_MU_TX on the given link.
98 *
99 * @param linkId the ID of the given link
100 * @return the information required to perform a DL MU transmission
101 */
102 DlMuInfo& GetDlMuInfo(uint8_t linkId);
103
104 /**
105 * Get the information required to solicit an UL MU transmission on the given link. Note
106 * that this method can only be called if GetTxFormat returns UL_MU_TX on the given link.
107 *
108 * @param linkId the ID of the given link
109 * @return the information required to solicit an UL MU transmission
110 */
111 UlMuInfo& GetUlMuInfo(uint8_t linkId);
112
113 /**
114 * This method is called when a protection mechanism for an MU transmission is completed and
115 * gives the MU scheduler the opportunity to modify the MU PPDU or the TX parameters before
116 * the actual MU transmission.
117 *
118 * @param linkId ID of the link on which protection was completed
119 * @param psduMap the PSDU map to be transmitted
120 * @param txParams the TX parameters for the MU transmission
121 */
122 void NotifyProtectionCompleted(uint8_t linkId,
123 WifiPsduMap& psduMap,
124 WifiTxParameters& txParams);
125
126 /**
127 * When the TXOP limit is zero and the TXOP continues a SIFS after receiving a response to a
128 * BSRP TF, the Duration/ID field of the BSRP TF should be extended to reserve the medium
129 * for the frame exchange following the BSRP TF. This method is intended to return the estimated
130 * duration of the frame exchange following the BSRP TF (including the SIFS after the responses
131 * to the BSRP TF). Specifically, the base class method simply returns the default duration of
132 * TB PPDUs solicited via a Basic Trigger Frame. Subclasses can override this method to return
133 * a more accurate estimate of the time required by the following frame exchange.
134 *
135 * This method should only be called when the MU scheduler has determined that a BSRP TF has
136 * to be sent on the given link.
137 *
138 * @param linkId the ID of the given link
139 * @return the estimated duration of the frame exchange following the BSRP TF
140 */
141 virtual Time GetExtraTimeForBsrpTfDurationId(uint8_t linkId) const;
142
143 /**
144 * Set the duration of the interval between two consecutive requests for channel
145 * access made by the MultiUserScheduler.
146 *
147 * @param interval the duration of the interval between two consecutive requests
148 * for channel access
149 */
150 void SetAccessReqInterval(Time interval);
151
152 /**
153 * @return the duration of the interval between two consecutive requests for channel access
154 */
156
157 protected:
158 /**
159 * Get the station manager attached to the AP on the given link.
160 *
161 * @param linkId the ID of the given link
162 * @return the station manager attached to the AP on the given link
163 */
165
166 /**
167 * Get the HE Frame Exchange Manager attached to the AP on the given link.
168 *
169 * @param linkId the ID of the given link
170 * @return the HE Frame Exchange Manager attached to the AP on the given link
171 */
172 Ptr<HeFrameExchangeManager> GetHeFem(uint8_t linkId) const;
173
174 /**
175 * Get an MPDU containing the given Trigger Frame.
176 *
177 * @param trigger the given Trigger Frame
178 * @param linkId the ID of the link on which the Trigger Frame has to be sent
179 * @return an MPDU containing the given Trigger Frame
180 */
181 Ptr<WifiMpdu> GetTriggerFrame(const CtrlTriggerHeader& trigger, uint8_t linkId) const;
182
183 /**
184 * Update the given Trigger Frame after protection is completed on the given link.
185 *
186 * @param linkId the ID of the given link
187 * @param trigger the given Trigger Frame
188 * @param txParams the TX parameters for the UL MU transmission
189 */
190 virtual void UpdateTriggerFrameAfterProtection(uint8_t linkId,
191 CtrlTriggerHeader& trigger,
192 WifiTxParameters& txParams) const {};
193
194 /**
195 * Update the given PSDU map after protection is completed on the given link.
196 *
197 * @param linkId the ID of the given link
198 * @param psduMap the given PSDU map
199 * @param txParams the TX parameters for the DL MU transmission
200 */
201 virtual void UpdateDlMuAfterProtection(uint8_t linkId,
202 WifiPsduMap& psduMap,
203 WifiTxParameters& txParams) const {};
204
205 /**
206 * Remove the User Info fields for which the given predicate is true from the given Trigger
207 * Frame.
208 *
209 * @param linkId the ID of the link on which the Trigger Frame has to be sent
210 * @param trigger the given Trigger Frame
211 * @param txParams the TX parameters for the UL MU transmission
212 * @param predicate the given predicate (input parameters are link ID and device link address)
213 */
214 void RemoveRecipientsFromTf(uint8_t linkId,
215 CtrlTriggerHeader& trigger,
216 WifiTxParameters& txParams,
217 std::function<bool(uint8_t, Mac48Address)> predicate) const;
218
219 /**
220 * Remove PSDUs for which the given predicate is true from the given PSDU map. Entries in the
221 * TXVECTOR corresponding to such PSDUs are also removed.
222 *
223 * @param linkId the ID of the link on which the PSDU map has to be sent
224 * @param psduMap the given PSDU map
225 * @param txParams the TX parameters for the DL MU transmission
226 * @param predicate the given predicate (input parameters are link ID and device link address)
227 */
228 void RemoveRecipientsFromDlMu(uint8_t linkId,
229 WifiPsduMap& psduMap,
230 WifiTxParameters& txParams,
231 std::function<bool(uint8_t, Mac48Address)> predicate) const;
232
233 /**
234 * Get the format of the last transmission on the given link, as determined by
235 * the last call to NotifyAccessGranted that did not return NO_TX.
236 *
237 * @param linkId the ID of the given link
238 * @return the format of the last transmission on the given link
239 */
240 TxFormat GetLastTxFormat(uint8_t linkId) const;
241
242 /**
243 * Get the maximum size in bytes among the A-MPDUs containing QoS Null frames
244 * and solicited by the given (BSRP) Trigger Frame. For each station addressed
245 * by the Trigger Frame, the expected response is an A-MPDU containing as many
246 * QoS Null frames as the number of TIDs for which a BlockAck agreement has
247 * been established between the station and the AP.
248 *
249 * @param trigger the given Trigger Frame
250 * @return the maximum size in bytes among the A-MPDUs containing QoS Null frames
251 * and solicited by the given Trigger Frame
252 */
254
255 void DoDispose() override;
256 void NotifyNewAggregate() override;
257 void DoInitialize() override;
258
259 Ptr<ApWifiMac> m_apMac; //!< the AP wifi MAC
260 Ptr<QosTxop> m_edca; //!< the AC that gained channel access
261 Time m_availableTime; //!< the time available for frame exchange
262 bool m_initialFrame; //!< true if a TXOP is being started
263 MHz_u m_allowedWidth; //!< the allowed width for the current transmission
264 uint8_t m_linkId; //!< the ID of the link over which channel access has been granted
265 Time m_defaultTbPpduDuration; //!< the default duration of TB PPDUs solicited by Basic TFs
266
267 const std::function<bool(uint8_t, Mac48Address)>
268 m_isUnprotectedEmlsrClient; //!< predicate returning true if the device with the given
269 //!< (link) address is an EMLSR client that is not protected on
270 //!< the given link
271
272 private:
273 /**
274 * Set the wifi MAC. Note that it must be the MAC of an HE AP.
275 *
276 * @param mac the AP wifi MAC
277 */
278 void SetWifiMac(Ptr<ApWifiMac> mac);
279
280 /**
281 * Perform actions required on expiration of the channel access request timer associated with
282 * the given link, such as requesting channel access (if not requested already) and restarting
283 * the channel access request timer.
284 *
285 * @param linkId the ID of the given link
286 */
287 void AccessReqTimeout(uint8_t linkId);
288
289 /**
290 * Select the format of the next transmission.
291 *
292 * @return the format of the next transmission
293 */
295
296 /**
297 * Compute the information required to perform a DL MU transmission.
298 *
299 * @return the information required to perform a DL MU transmission
300 */
302
303 /**
304 * Prepare the information required to solicit an UL MU transmission.
305 *
306 * @return the information required to solicit an UL MU transmission
307 */
309
310 /**
311 * Ensure that the Trigger Frame returned in case of UL MU transmission is
312 * correct. Currently, this method sets the CS Required, the AP Tx Power and
313 * the UL Target Receive Power subfields.
314 */
315 void CheckTriggerFrame();
316
317 /**
318 * Type for the information about the last transmission
319 */
321 {
322 TxFormat lastTxFormat{NO_TX}; ///< the format of last transmission
323 DlMuInfo dlInfo; ///< information required to perform a DL MU transmission
324 UlMuInfo ulInfo; ///< information required to solicit an UL MU transmission
325 };
326
327 std::map<uint8_t, LastTxInfo> m_lastTxInfo; ///< Information about the last transmission
328 std::vector<EventId>
329 m_accessReqTimers; ///< the per-link timer controlling additional channel access requests
330 Time m_accessReqInterval; ///< duration of the interval between channel access requests
331 AcIndex m_accessReqAc; ///< AC we request channel access for
332 bool m_restartTimerUponAccess; ///< whether the channel access timer has to be restarted
333 ///< upon channel access
334};
335
336} // namespace ns3
337
338#endif /* MULTI_USER_SCHEDULER_H */
Headers for Trigger frames.
an EUI-48 address
MultiUserScheduler is an abstract base class defining the API that APs supporting at least VHT can us...
bool m_initialFrame
true if a TXOP is being started
void NotifyNewAggregate() override
Notify all Objects aggregated to this one of a new Object being aggregated.
void DoInitialize() override
Initialize() implementation.
Ptr< ApWifiMac > m_apMac
the AP wifi MAC
std::vector< EventId > m_accessReqTimers
the per-link timer controlling additional channel access requests
void CheckTriggerFrame()
Ensure that the Trigger Frame returned in case of UL MU transmission is correct.
static TypeId GetTypeId()
Get the type ID.
Time m_availableTime
the time available for frame exchange
void RemoveRecipientsFromTf(uint8_t linkId, CtrlTriggerHeader &trigger, WifiTxParameters &txParams, std::function< bool(uint8_t, Mac48Address)> predicate) const
Remove the User Info fields for which the given predicate is true from the given Trigger Frame.
Ptr< WifiRemoteStationManager > GetWifiRemoteStationManager(uint8_t linkId) const
Get the station manager attached to the AP on the given link.
UlMuInfo & GetUlMuInfo(uint8_t linkId)
Get the information required to solicit an UL MU transmission on the given link.
uint8_t m_linkId
the ID of the link over which channel access has been granted
virtual TxFormat SelectTxFormat()=0
Select the format of the next transmission.
void SetAccessReqInterval(Time interval)
Set the duration of the interval between two consecutive requests for channel access made by the Mult...
uint32_t GetMaxSizeOfQosNullAmpdu(const CtrlTriggerHeader &trigger) const
Get the maximum size in bytes among the A-MPDUs containing QoS Null frames and solicited by the given...
virtual void UpdateTriggerFrameAfterProtection(uint8_t linkId, CtrlTriggerHeader &trigger, WifiTxParameters &txParams) const
Update the given Trigger Frame after protection is completed on the given link.
bool m_restartTimerUponAccess
whether the channel access timer has to be restarted upon channel access
const std::function< bool(uint8_t, Mac48Address)> m_isUnprotectedEmlsrClient
predicate returning true if the device with the given (link) address is an EMLSR client that is not p...
virtual DlMuInfo ComputeDlMuInfo()=0
Compute the information required to perform a DL MU transmission.
Ptr< QosTxop > m_edca
the AC that gained channel access
void NotifyProtectionCompleted(uint8_t linkId, WifiPsduMap &psduMap, WifiTxParameters &txParams)
This method is called when a protection mechanism for an MU transmission is completed and gives the M...
virtual UlMuInfo ComputeUlMuInfo()=0
Prepare the information required to solicit an UL MU transmission.
Time m_defaultTbPpduDuration
the default duration of TB PPDUs solicited by Basic TFs
TxFormat GetLastTxFormat(uint8_t linkId) const
Get the format of the last transmission on the given link, as determined by the last call to NotifyAc...
void DoDispose() override
Destructor implementation.
Ptr< WifiMpdu > GetTriggerFrame(const CtrlTriggerHeader &trigger, uint8_t linkId) const
Get an MPDU containing the given Trigger Frame.
AcIndex m_accessReqAc
AC we request channel access for.
DlMuInfo & GetDlMuInfo(uint8_t linkId)
Get the information required to perform a DL MU transmission on the given link.
MHz_u m_allowedWidth
the allowed width for the current transmission
Ptr< HeFrameExchangeManager > GetHeFem(uint8_t linkId) const
Get the HE Frame Exchange Manager attached to the AP on the given link.
Time m_accessReqInterval
duration of the interval between channel access requests
TxFormat NotifyAccessGranted(Ptr< QosTxop > edca, Time availableTime, bool initialFrame, MHz_u allowedWidth, uint8_t linkId)
Notify the Multi-user Scheduler that the given AC of the AP gained channel access.
void SetWifiMac(Ptr< ApWifiMac > mac)
Set the wifi MAC.
virtual Time GetExtraTimeForBsrpTfDurationId(uint8_t linkId) const
When the TXOP limit is zero and the TXOP continues a SIFS after receiving a response to a BSRP TF,...
TxFormat
Enumeration of the possible transmission formats.
virtual void UpdateDlMuAfterProtection(uint8_t linkId, WifiPsduMap &psduMap, WifiTxParameters &txParams) const
Update the given PSDU map after protection is completed on the given link.
std::map< uint8_t, LastTxInfo > m_lastTxInfo
Information about the last transmission.
void RemoveRecipientsFromDlMu(uint8_t linkId, WifiPsduMap &psduMap, WifiTxParameters &txParams, std::function< bool(uint8_t, Mac48Address)> predicate) const
Remove PSDUs for which the given predicate is true from the given PSDU map.
void AccessReqTimeout(uint8_t linkId)
Perform actions required on expiration of the channel access request timer associated with the given ...
A base class which provides memory management and object aggregation.
Definition object.h:78
Smart pointer class similar to boost::intrusive_ptr.
Simulation virtual time values and global simulation resolution.
Definition nstime.h:94
a unique identifier for an interface.
Definition type-id.h:49
Implements the IEEE 802.11 MAC header.
This class stores the TX parameters (TX vector, protection mechanism, acknowledgment mechanism,...
AcIndex
This enumeration defines the Access Categories as an enumeration with values corresponding to the AC ...
Definition qos-utils.h:62
Every class exported by the ns3 library is enclosed in the ns3 namespace.
std::unordered_map< uint16_t, Ptr< WifiPsdu > > WifiPsduMap
Map of PSDUs indexed by STA-ID.
Definition wifi-mac.h:78
Information to be provided in case of DL MU transmission.
WifiTxParameters txParams
the transmission parameters
WifiPsduMap psduMap
the DL MU PPDU to transmit
Type for the information about the last transmission.
TxFormat lastTxFormat
the format of last transmission
UlMuInfo ulInfo
information required to solicit an UL MU transmission
DlMuInfo dlInfo
information required to perform a DL MU transmission
Information to be provided in case of UL MU transmission.
WifiTxParameters txParams
the transmission parameters for the Trigger Frame
CtrlTriggerHeader trigger
the Trigger Frame used to solicit TB PPDUs
WifiMacHeader macHdr
the MAC header for the Trigger Frame