A Discrete-Event Network Simulator
API
Loading...
Searching...
No Matches
emlsr-manager.h
Go to the documentation of this file.
1/*
2 * Copyright (c) 2023 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 EMLSR_MANAGER_H
10#define EMLSR_MANAGER_H
11
12#include "ns3/ctrl-headers.h"
13#include "ns3/mac48-address.h"
14#include "ns3/object.h"
15#include "ns3/sta-wifi-mac.h"
16#include "ns3/wifi-phy-operating-channel.h"
17
18#include <map>
19#include <memory>
20#include <optional>
21#include <set>
22#include <string_view>
23#include <utility>
24
26
27namespace ns3
28{
29
30class EhtFrameExchangeManager;
31class MgtEmlOmn;
32class WifiMpdu;
33
34/**
35 * @ingroup wifi
36 * Base struct for EMLSR Main PHY switch traces.
37 */
39{
40 virtual ~EmlsrMainPhySwitchTrace() = default;
41
42 /// @return the name of this instance
43 virtual std::string_view GetName() const = 0;
44
45 /// @return a pointer to the clone of this object
46 virtual std::shared_ptr<EmlsrMainPhySwitchTrace> Clone() const = 0;
47
48 std::optional<uint8_t> fromLinkId; //!< ID of the link the main PHY is moving from (if any)
49 uint8_t toLinkId{WIFI_LINKID_UNDEFINED}; //!< ID of the link the main PHY is moving to
50};
51
52/**
53 * Implementation for the EMLSR Main PHY switch trace base struct. Child structs are inherited
54 * from this implementation according to the CRTP idiom and must define a static string_view
55 * member containing the name of the child.
56 */
57template <class T>
59{
60 /// @copydoc ns3::EmlsrMainPhySwitchTrace::GetName
61 std::string_view GetName() const override
62 {
63 return T::m_name;
64 }
65
66 /// @copydoc ns3::EmlsrMainPhySwitchTrace::Clone
67 std::shared_ptr<EmlsrMainPhySwitchTrace> Clone() const override
68 {
69 return std::shared_ptr<EmlsrMainPhySwitchTrace>(new T(static_cast<const T&>(*this)));
70 }
71};
72
73/**
74 * @ingroup wifi
75 *
76 * EmlsrManager is an abstract base class defining the API that EHT non-AP MLDs
77 * with EMLSR activated can use to handle the operations on the EMLSR links
78 */
79class EmlsrManager : public Object
80{
81 /// Allow test cases to access private members
82 friend class ::EmlsrCcaBusyTest;
83
84 public:
85 /**
86 * @brief Get the type ID.
87 * @return the object TypeId
88 */
89 static TypeId GetTypeId();
91 ~EmlsrManager() override;
92
93 /**
94 * Set the wifi MAC. Note that it must be the MAC of an EHT non-AP MLD.
95 *
96 * @param mac the wifi MAC
97 */
99
100 /**
101 * Set the Transition Timeout advertised by the associated AP with EMLSR activated.
102 *
103 * @param timeout the advertised Transition Timeout
104 */
106
107 /**
108 * @return the Transition Timeout, if advertised by the associated AP
109 */
110 std::optional<Time> GetTransitionTimeout() const;
111
112 /**
113 * Set the duration of the MediumSyncDelay timer.
114 *
115 * @param duration the duration of the MediumSyncDelay timer
116 */
117 void SetMediumSyncDuration(Time duration);
118
119 /**
120 * @return the duration of the MediumSyncDelay timer
121 */
123
124 /**
125 * Set the Medium Synchronization OFDM ED threshold (dBm) to use while the MediumSyncDelay
126 * timer is running.
127 *
128 * @param threshold the threshold in dBm (ranges from -72 to -62 dBm)
129 */
130 void SetMediumSyncOfdmEdThreshold(int8_t threshold);
131
132 /**
133 * @return the Medium Synchronization OFDM ED threshold (dBm) to use while the MediumSyncDelay
134 * timer is running.
135 */
137
138 /**
139 * Set the maximum number of TXOPs a non-AP STA is allowed to attempt to initiate while
140 * the MediumSyncDelay timer is running. No value indicates no limit.
141 *
142 * @param nTxops the maximum number of TXOPs a non-AP STA is allowed to attempt to
143 * initiate while the MediumSyncDelay timer is running
144 */
145 void SetMediumSyncMaxNTxops(std::optional<uint8_t> nTxops);
146
147 /**
148 * @return the maximum number of TXOPs a non-AP STA is allowed to attempt to initiate while
149 * the MediumSyncDelay timer is running. No value indicates no limit.
150 */
151 std::optional<uint8_t> GetMediumSyncMaxNTxops() const;
152
153 /**
154 * @return the ID of main PHY (position in the vector of PHYs held by WifiNetDevice)
155 */
156 uint8_t GetMainPhyId() const;
157
158 /**
159 * Take actions to enable EMLSR mode on the given set of links, if non-empty, or
160 * disable EMLSR mode, otherwise.
161 *
162 * @param linkIds the IDs of the links on which EMLSR mode should be enabled
163 * (empty to disable EMLSR mode)
164 */
165 void SetEmlsrLinks(const std::set<uint8_t>& linkIds);
166
167 /**
168 * @return the set of links on which EMLSR mode is enabled
169 */
170 const std::set<uint8_t>& GetEmlsrLinks() const;
171
172 /**
173 * Set the member variable indicating whether the state of the CAM should be reset when
174 * the main PHY switches channel and operates on the link associated with the CAM.
175 *
176 * @param enable whether the CAM state should be reset
177 */
178 void SetCamStateReset(bool enable);
179
180 /**
181 * @return the value of the member variable indicating whether the state of the CAM should be
182 * reset when the main PHY switches channel and operates on the link associated with the CAM.
183 */
184 bool GetCamStateReset() const;
185
186 /**
187 * Notify that an UL TXOP is gained on the given link by the given AC. This method has to
188 * determine whether to start the UL TXOP or release the channel.
189 *
190 * @param linkId the ID of the given link
191 * @param aci the index of the given AC
192 * @return a pair consisting of a boolean value indicating whether the UL TXOP can be started
193 * and a Time value indicating the delay after which the EMLSR client must restart
194 * channel access (if needed) in case the UL TXOP is not started
195 */
196 std::pair<bool, Time> GetDelayUntilAccessRequest(uint8_t linkId, AcIndex aci);
197
198 /**
199 * Set the member variable indicating whether Aux PHYs are capable of transmitting PPDUs.
200 *
201 * @param capable whether Aux PHYs are capable of transmitting PPDUs
202 */
203 void SetAuxPhyTxCapable(bool capable);
204
205 /**
206 * @return whether Aux PHYs are capable of transmitting PPDUs
207 */
208 bool GetAuxPhyTxCapable() const;
209
210 /**
211 * Set the member variable indicating whether in-device interference is such that a PHY cannot
212 * decode anything and cannot decrease the backoff counter when another PHY is transmitting.
213 *
214 * @param enable whether in-device interference is such that a PHY cannot decode anything
215 * and cannot decrease the backoff counter when another PHY is transmitting
216 */
217 void SetInDeviceInterference(bool enable);
218
219 /**
220 * @return whether in-device interference is such that a PHY cannot decode anything and cannot
221 * decrease the backoff counter when another PHY is transmitting
222 */
223 bool GetInDeviceInterference() const;
224
225 /**
226 * Notify the reception of a management frame addressed to us.
227 *
228 * @param mpdu the received MPDU
229 * @param linkId the ID of the link over which the MPDU was received
230 */
231 void NotifyMgtFrameReceived(Ptr<const WifiMpdu> mpdu, uint8_t linkId);
232
233 /**
234 * Notify the start of a DL TXOP on the given link.
235 *
236 * @param linkId the ID of the given link
237 */
238 void NotifyDlTxopStart(uint8_t linkId);
239
240 /**
241 * Notify the start of an UL TXOP on the given link
242 *
243 * @param linkId the ID of the given link
244 */
245 void NotifyUlTxopStart(uint8_t linkId);
246
247 /**
248 * Notify that RTS transmission is starting on the given link.
249 *
250 * @param linkId the ID of the given link
251 * @param rts the RTS being transmitted
252 * @param txVector the TXVECTOR used to transmit the RTS
253 */
254 virtual void NotifyRtsSent(uint8_t linkId,
256 const WifiTxVector& txVector);
257
258 /**
259 * Notify that protection (if required) is completed and data frame exchange can start
260 * on the given link.
261 *
262 * @param linkId the ID of the given link
263 */
264 void NotifyProtectionCompleted(uint8_t linkId);
265
266 /**
267 * Notify the end of a TXOP on the given link.
268 *
269 * @param linkId the ID of the given link
270 * @param edca the EDCAF that carried out the TXOP, in case of UL TXOP, or a null pointer,
271 * in case of DL TXOP
272 */
273 void NotifyTxopEnd(uint8_t linkId, Ptr<QosTxop> edca = nullptr);
274
275 /**
276 * Notify that an STA affiliated with the EMLSR client is causing in-device interference
277 * for the given amount of time.
278 *
279 * @param linkId the ID of the link on which the STA is operating
280 * @param duration the duration of the in-device interference
281 */
282 virtual void NotifyInDeviceInterferenceStart(uint8_t linkId, Time duration);
283
284 /**
285 * Check whether the MediumSyncDelay timer is running for the STA operating on the given link.
286 * If so, returns the time elapsed since the timer started.
287 *
288 * @param linkId the ID of the given link
289 * @return the time elapsed since the MediumSyncDelay timer started, if this timer is running
290 * for the STA operating on the given link
291 */
292 std::optional<Time> GetElapsedMediumSyncDelayTimer(uint8_t linkId) const;
293
294 /**
295 * Cancel the MediumSyncDelay timer associated with the given link and take the appropriate
296 * actions. This function must not be called when the MediumSyncDelay timer is not running
297 * on the given link.
298 *
299 * @param linkId the ID of the link associated with the MediumSyncDelay timer to cancel
300 */
301 void CancelMediumSyncDelayTimer(uint8_t linkId);
302
303 /**
304 * Decrement the counter indicating the number of TXOP attempts left while the MediumSyncDelay
305 * timer is running. This function must not be called when the MediumSyncDelay timer is not
306 * running on the given link.
307 *
308 * @param linkId the ID of the link on which a new TXOP attempt may be carried out
309 */
310 void DecrementMediumSyncDelayNTxops(uint8_t linkId);
311
312 /**
313 * Reset the counter indicating the number of TXOP attempts left while the MediumSyncDelay
314 * timer is running, so as to remove the limit on the number of attempts that can be made
315 * while the MediumSyncDelay timer is running. This function is normally called when a TXOP
316 * attempt is successful. This function must not be called when the MediumSyncDelay timer is
317 * not running on the given link.
318 *
319 * @param linkId the ID of the link for which the counter of the TXOP attempts is reset
320 */
321 void ResetMediumSyncDelayNTxops(uint8_t linkId);
322
323 /**
324 * Return whether no more TXOP attempt is allowed on the given link. This function must not
325 * be called when the MediumSyncDelay timer is not running on the given link.
326 *
327 * @param linkId the ID of the link on which a new TXOP attempt may be carried out
328 * @return whether no more TXOP attempt on the given link is allowed
329 */
330 bool MediumSyncDelayNTxopsExceeded(uint8_t linkId);
331
332 /**
333 * Check whether a PPDU that may be an ICF is being received on the given link. If so, return
334 * true along with the time to wait to know more information about the PPDU being received.
335 * Otherwise, return false.
336 *
337 * @param linkId the ID of the given link
338 * @return a pair indicating whether a PPDU that may be an ICF is being received on the link
339 */
340 std::pair<bool, Time> CheckPossiblyReceivingIcf(uint8_t linkId) const;
341
342 /**
343 * This method is called when an aux PHY has completed reception of an ICF to determine whether
344 * there is any reason preventing the main PHY from switching link and be on the aux PHY link
345 * by the time the ICF reception is completed to take over the DL TXOP.
346 *
347 * @param linkId the ID of the link on which ICF has been received
348 * @return the reason, if any, preventing the main PHY from switching link
349 */
350 virtual std::optional<WifiIcfDrop> CheckMainPhyTakesOverDlTxop(uint8_t linkId) const;
351
352 protected:
353 void DoDispose() override;
354
355 /**
356 * Allow subclasses to take actions when the MAC is set.
357 *
358 * @param mac the wifi MAC
359 */
360 virtual void DoSetWifiMac(Ptr<StaWifiMac> mac);
361
362 /**
363 * @return the MAC of the non-AP MLD managed by this EMLSR Manager.
364 */
366
367 /**
368 * @param linkId the ID of the given link
369 * @return the EHT FrameExchangeManager attached to the non-AP STA operating on the given link
370 */
371 Ptr<EhtFrameExchangeManager> GetEhtFem(uint8_t linkId) const;
372
373 /**
374 * @return the ID of the link on which the EML Operating Mode Notification frame has to be sent
375 */
376 virtual uint8_t GetLinkToSendEmlOmn() = 0;
377
378 /**
379 * A previous EML Operating Mode Notification frame was dropped. Ask the subclass whether
380 * the frame needs to be re-sent on the given link (if any).
381 *
382 * @param mpdu the dropped MPDU that includes the EML Operating Mode Notification frame
383 * @return the ID of the link over which to re-send the frame, if needed
384 */
385 virtual std::optional<uint8_t> ResendNotification(Ptr<const WifiMpdu> mpdu) = 0;
386
387 /**
388 * @param linkId the ID of the given link
389 * @return the operating channel the main PHY must switch to in order to operate
390 * on the given link
391 */
392 const WifiPhyOperatingChannel& GetChannelForMainPhy(uint8_t linkId) const;
393
394 /**
395 * @param linkId the ID of the given link
396 * @return the operating channel an aux PHY must switch to in order to operate
397 * on the given link
398 */
399 const WifiPhyOperatingChannel& GetChannelForAuxPhy(uint8_t linkId) const;
400
401 /**
402 * Switch channel on the Main PHY so that it operates on the given link.
403 *
404 * @param linkId the ID of the link on which the main PHY has to operate
405 * @param noSwitchDelay whether switching delay should be zero
406 * @param requestAccess whether channel access should be requested on the link on which the
407 * main PHY is moving onto
408 * @param traceInfo information to pass to the main PHY switch traced callback (the fromLinkId
409 * and toLinkId fields are set by this function)
410 */
411 void SwitchMainPhy(uint8_t linkId,
412 bool noSwitchDelay,
413 bool requestAccess,
414 EmlsrMainPhySwitchTrace&& traceInfo);
415
416 static constexpr bool REQUEST_ACCESS = true; //!< request channel access when PHY switch ends
417 static constexpr bool DONT_REQUEST_ACCESS =
418 false; //!< do not request channel access when PHY switch ends
419
420 /**
421 * Switch channel on the Aux PHY operating on the given current link so that it operates
422 * on the given next link.
423 *
424 * @param auxPhy the Aux PHY
425 * @param currLinkId the ID of the link on which the aux PHY is currently operating
426 * @param nextLinkId the ID of the link on which the aux PHY will be operating
427 */
428 void SwitchAuxPhy(Ptr<WifiPhy> auxPhy, uint8_t currLinkId, uint8_t nextLinkId);
429
430 /**
431 * Callback connected to the EmlsrLinkSwitch trace source of StaWifiMac.
432 *
433 * @param linkId the ID of the link which the PHY is connected to/disconnected from
434 * @param phy a pointer to the PHY that is connected to/disconnected from the given link
435 * @param connected true if the PHY is connected, false if the PHY is disconnected
436 */
437 virtual void EmlsrLinkSwitchCallback(uint8_t linkId, Ptr<WifiPhy> phy, bool connected);
438
439 /**
440 * Set the CCA ED threshold (if needed) on the given PHY that is switching channel to
441 * operate on the given link.
442 *
443 * @param phy the given PHY
444 * @param linkId the ID of the given link
445 */
446 void SetCcaEdThresholdOnLinkSwitch(Ptr<WifiPhy> phy, uint8_t linkId);
447
448 /**
449 * @return the EML Operating Mode Notification to send
450 */
452
453 /**
454 * Subclasses have to provide an implementation for this method, that is called by the base
455 * class when the EMLSR client gets channel access on the given link. This method has to
456 * check possible reasons to give up the TXOP that apply to both main PHY and aux PHYs.
457 *
458 * @param linkId the ID of the given link
459 * @return a pair consisting of a boolean value indicating whether the UL TXOP can be started
460 * and a Time value indicating the delay after which the EMLSR client must restart
461 * channel access (if needed) in case the UL TXOP is not started
462 */
463 virtual std::pair<bool, Time> DoGetDelayUntilAccessRequest(uint8_t linkId) = 0;
464
465 /**
466 * Subclasses have to provide an implementation for this method, that is called by the base
467 * class when the given AC of the EMLSR client gets channel access on the given link, on which
468 * an aux PHY that is not TX capable is operating. This method has to request the main PHY to
469 * switch to the given link to take over the TXOP, unless it is decided to give up the TXOP.
470 *
471 * @param linkId the ID of the given link
472 * @param aci the index of the given AC
473 */
474 virtual void SwitchMainPhyIfTxopGainedByAuxPhy(uint8_t linkId, AcIndex aci) = 0;
475
476 /**
477 * Subclasses have to provide an implementation for this method, that is called by the base
478 * class when the EMLSR client gets channel access on the given link, on which an aux PHY that
479 * is TX capable is operating. This method has to request the main PHY to switch to the
480 * given link to take over the TXOP, if possible, or determine the delay after which the
481 * EMLSR client restarts channel access on the given link, otherwise.
482 *
483 * @param linkId the ID of the given link
484 * @return a pair consisting of a boolean value indicating whether the UL TXOP can be started
485 * and a Time value indicating the delay after which the EMLSR client must restart
486 * channel access (if needed) in case the UL TXOP is not started
487 */
488 virtual std::pair<bool, Time> GetDelayUnlessMainPhyTakesOverUlTxop(uint8_t linkId) = 0;
489
490 /**
491 * Set sleep state or awake state for all aux PHYs.
492 *
493 * @param sleep set sleep state, if true, or awake state, otherwise
494 */
495 void SetSleepStateForAllAuxPhys(bool sleep);
496
497 /**
498 * Cancel all pending events to put aux PHYs into sleep/awake state.
499 */
501
502 /// Store information about a main PHY switch.
504 {
505 Time start; //!< start of channel switching
506 bool disconnected{false}; //!< true if the main PHY is not connected to any link, i.e., it
507 //!< is switching or waiting to be connected to a link
508 uint8_t from{}; //!< ID of the link which the main PHY is/has been leaving
509 uint8_t to{}; //!< ID of the link which the main PHY is moving to
510 std::string reason; //!< the reason for switching the main PHY
511 };
512
513 Time m_emlsrPaddingDelay; //!< EMLSR Padding delay
514 Time m_emlsrTransitionDelay; //!< EMLSR Transition delay
515 uint8_t m_mainPhyId; //!< ID of main PHY (position in the vector of PHYs held by WifiNetDevice)
516 MHz_u m_auxPhyMaxWidth; //!< max channel width supported by aux PHYs
517 WifiModulationClass m_auxPhyMaxModClass; //!< max modulation class supported by aux PHYs
518 bool m_auxPhyTxCapable; //!< whether Aux PHYs are capable of transmitting PPDUs
519 bool m_auxPhyToSleep; //!< whether Aux PHYs should be put into sleep mode while the Main PHY
520 //!< is carrying out a (DL or UL) TXOP
521 bool m_useNotifiedMacHdr; //!< whether to use the information about the MAC header of
522 //!< the MPDU being received (if notified by the PHY)
523 std::map<uint8_t, EventId> m_auxPhyToSleepEvents; //!< PHY ID-indexed map of events scheduled to
524 //!< put an Aux PHY to sleep
525 std::map<uint8_t, Time> m_startSleep; //!< PHY ID-indexed map of last time sleep mode started
526 std::map<uint8_t, EventId> m_ulMainPhySwitch; //!< link ID-indexed map of timers started when
527 //!< an aux PHY gains an UL TXOP and schedules
528 //!< a channel switch for the main PHY
529 MainPhySwitchInfo m_mainPhySwitchInfo; //!< main PHY switch info
530
531 private:
532 /**
533 * Set the ID of main PHY (position in the vector of PHYs held by WifiNetDevice). This
534 * method cannot be called during or after initialization.
535 *
536 * @param mainPhyId the ID of the main PHY
537 */
538 void SetMainPhyId(uint8_t mainPhyId);
539
540 /**
541 * Compute the operating channels that the main PHY and the aux PHY(s) must switch to in order
542 * to operate on each of the setup links. The operating channels may be different due to
543 * limited channel width capabilities of the aux PHY(s). This method shall be called upon
544 * completion of ML setup.
545 */
547
548 /**
549 * Send an EML Operating Mode Notification frame.
550 */
551 void SendEmlOmn();
552
553 /**
554 * Start the MediumSyncDelay timer and take the appropriate actions.
555 *
556 * @param linkId the ID of the link on which medium synchronization was lost
557 */
558 void StartMediumSyncDelayTimer(uint8_t linkId);
559
560 /**
561 * Take the appropriate actions when the MediumSyncDelay timer expires or is cancelled.
562 *
563 * @param linkId the ID of the link associated with the MediumSyncDelay timer to cancel
564 */
565 void MediumSyncDelayTimerExpired(uint8_t linkId);
566
567 /**
568 * Notify the subclass of the reception of a management frame addressed to us.
569 *
570 * @param mpdu the received MPDU
571 * @param linkId the ID of the link over which the MPDU was received
572 */
573 virtual void DoNotifyMgtFrameReceived(Ptr<const WifiMpdu> mpdu, uint8_t linkId) = 0;
574
575 /**
576 * Notify the subclass of the reception of an initial Control frame on the given link.
577 *
578 * @param linkId the ID of the link on which the initial Control frame was received
579 */
580 virtual void DoNotifyDlTxopStart(uint8_t linkId) = 0;
581
582 /**
583 * Notify the subclass of the start of an UL TXOP on the given link
584 *
585 * @param linkId the ID of the given link
586 */
587 virtual void DoNotifyUlTxopStart(uint8_t linkId) = 0;
588
589 /**
590 * Notify the subclass that protection (if required) is completed and data frame exchange can
591 * start on the given link.
592 *
593 * @param linkId the ID of the given link
594 */
595 virtual void DoNotifyProtectionCompleted(uint8_t linkId) = 0;
596
597 /**
598 * Notify the subclass of the end of a TXOP on the given link.
599 *
600 * @param linkId the ID of the given link
601 * @param edca the EDCAF that carried out the TXOP, in case of UL TXOP, or a null pointer,
602 * in case of DL TXOP
603 */
604 virtual void DoNotifyTxopEnd(uint8_t linkId, Ptr<QosTxop> edca) = 0;
605
606 /**
607 * Notify the acknowledgment of the given MPDU.
608 *
609 * @param mpdu the acknowledged MPDU
610 */
611 void TxOk(Ptr<const WifiMpdu> mpdu);
612
613 /**
614 * Notify that the given MPDU has been discarded for the given reason.
615 *
616 * @param reason the reason why the MPDU was dropped
617 * @param mpdu the dropped MPDU
618 */
620
621 /**
622 * This method is called to make an EMLSR mode change effective after the transition
623 * delay has elapsed or a notification response has been received from the AP.
624 */
625 void ChangeEmlsrMode();
626
627 /**
628 * Adjust the operating channel of all the aux PHYs to meet the constraint on the maximum
629 * channel width supported by aux PHYs.
630 */
632
633 /**
634 * Notify subclass that EMLSR mode changed.
635 */
636 virtual void NotifyEmlsrModeChanged() = 0;
637
638 /**
639 * Notify subclass that the main PHY is switching channel to operate on another link.
640 *
641 * @param currLinkId the ID of the link on which the main PHY is operating (if any)
642 * @param nextLinkId the ID of the link on which the main PHY will be operating
643 * @param auxPhy the aux PHY operating on the link on which the main PHY will be operating
644 * @param duration the channel switch duration
645 */
646 virtual void NotifyMainPhySwitch(std::optional<uint8_t> currLinkId,
647 uint8_t nextLinkId,
648 Ptr<WifiPhy> auxPhy,
649 Time duration) = 0;
650
651 /**
652 * Information about the status of the MediumSyncDelay timer associated with a link.
653 */
655 {
656 EventId timer; //!< the MediumSyncDelay timer
657 std::optional<uint8_t> msdNTxopsLeft; //!< number of TXOP attempts left while the
658 //!< MediumSyncDelay timer is running
659 };
660
661 /**
662 * TracedCallback signature for main PHY switch events.
663 *
664 * @param info the information associated with the main PHY switch event
665 */
666 typedef void (*MainPhySwitchCallback)(const EmlsrMainPhySwitchTrace& info);
667
668 /// TracedCallback for main PHY switch events typedef
670
671 MainPhySwitchTracedCallback m_mainPhySwitchTrace; //!< main PHY switch trace source
672
673 Ptr<StaWifiMac> m_staMac; //!< the MAC of the managed non-AP MLD
674 std::optional<Time> m_emlsrTransitionTimeout; /**< Transition timeout advertised by APs with
675 EMLSR activated */
676 Time m_mediumSyncDuration; //!< duration of the MediumSyncDelay timer
677 int8_t m_msdOfdmEdThreshold; //!< MediumSyncDelay OFDM ED threshold
678 std::optional<uint8_t> m_msdMaxNTxops; //!< MediumSyncDelay max number of TXOPs
679
680 std::map<uint8_t, MediumSyncDelayStatus>
681 m_mediumSyncDelayStatus; //!< the status of MediumSyncDelay timers (link ID-indexed)
682 std::map<Ptr<WifiPhy>, dBm_u> m_prevCcaEdThreshold; //!< the CCA sensitivity threshold
683 //!< to restore once the MediumSyncDelay
684 //!< timer expires or the PHY moves to a
685 //!< link on which the timer is not running
686
687 std::set<uint8_t> m_emlsrLinks; //!< ID of the EMLSR links (empty if EMLSR mode is disabled)
688 std::optional<std::set<uint8_t>> m_nextEmlsrLinks; /**< ID of the links that will become the
689 EMLSR links when the pending
690 notification frame is acknowledged */
691 Time m_lastAdvPaddingDelay; //!< last advertised padding delay
692 Time m_lastAdvTransitionDelay; //!< last advertised transition delay
693 EventId m_transitionTimeoutEvent; /**< Timer started after the successful transmission of an
694 EML Operating Mode Notification frame */
695 bool m_resetCamState; //!< whether to reset the state of CAM when main PHY switches channel
696 bool m_inDeviceInterference; //!< whether in-device interference is such that a PHY cannot
697 //!< decode anything and cannot decrease the backoff counter
698 //!< when another PHY is transmitting
699 std::map<uint8_t, WifiPhyOperatingChannel>
700 m_mainPhyChannels; //!< link ID-indexed map of operating channels for the main PHY
701 std::map<uint8_t, WifiPhyOperatingChannel>
702 m_auxPhyChannels; //!< link ID-indexed map of operating channels for the aux PHYs
703 std::map<uint8_t, Time>
704 m_noPhySince; //!< link ID-indexed map of the time since no PHY is operating on the link
705};
706
707/**
708 * Struct to trace that main PHY switched to start a DL TXOP after that an aux PHY received an ICF.
709 */
711 : public EmlsrMainPhySwitchTraceImpl<EmlsrDlTxopIcfReceivedByAuxPhyTrace>
712{
713 static constexpr std::string_view m_name = "DlTxopIcfReceivedByAuxPhy"; //!< trace name
714};
715
716/**
717 * Struct to trace that main PHY switched to start an UL TXOP after that an aux PHY transmitted an
718 * RTS.
719 */
721 : public EmlsrMainPhySwitchTraceImpl<EmlsrUlTxopRtsSentByAuxPhyTrace>
722{
723 static constexpr std::string_view m_name = "UlTxopRtsSentByAuxPhy"; //!< trace name
724};
725
726/**
727 * Struct to trace that main PHY switched when a (DL or UL) TXOP ended.
728 *
729 * This trace is called when aux PHYs do not switch link and the main PHY switches back to the
730 * preferred link when a TXOP carried out on another link ends.
731 */
732struct EmlsrTxopEndedTrace : public EmlsrMainPhySwitchTraceImpl<EmlsrTxopEndedTrace>
733{
734 static constexpr std::string_view m_name = "TxopEnded"; //!< trace name
735};
736
737/**
738 * Struct to trace that main PHY started switching after a CTS timeout occurred on the link on
739 * which an RTS was transmitted to start an UL TXOP. Provides the time elapsed since the
740 * CTS timeout occurred.
741 *
742 * |-- main PHY switch --|
743 * |----- to link 1 -----|
744 * ┌───────────┐
745 * │ CTS │
746 * ────────────────────────┬───────────┬───┴X──────────┴─────────────────────────────
747 * [link 1] │ RTS │ │-elapsed-│
748 * └───────────┘ │-- time--|-- main PHY switch --|
749 * │ |- to preferred link -|
750 * CTS timeout
751 *
752 * Normally, this trace is called when aux PHYs do not switch links, because the main PHY has to
753 * return to the preferred link upon CTS timeout, because a TXOP did not start. In some cases, the
754 * main PHY may be switching when CTS timeout occurs; this happens when an aux PHY that is TX
755 * capable transmits an RTS and the main PHY starts switching to the aux PHY link (the start time
756 * of the main PHY switch is computed such that the main PHY switch ends slightly after the
757 * reception of the CTS). In such a case, the main PHY completes the current link switch and then
758 * it starts switching to return back to the preferred link.
759 *
760 * Note that the Advanced EMLSR manager may allow a main PHY switch to be interrupted. If this
761 * option is enabled and the main PHY is switching when CTS timeout occurs, the previous switch is
762 * interrupted and the main PHY starts switching to the previous link (in this case, the time
763 * elapsed since the CTS timeout occurred is zero). This holds true for both the case aux PHYs do
764 * not switch link and the case aux PHYs switch link.
765 */
767 : public EmlsrMainPhySwitchTraceImpl<EmlsrCtsAfterRtsTimeoutTrace>
768{
769 static constexpr std::string_view m_name = "CtsAfterRtsTimeout"; //!< trace name
770
771 Time sinceCtsTimeout; //!< time elapsed since CTS timeout occurred
772
773 /**
774 * Constructor provided because this struct is not an aggregate (it has a base struct), hence
775 * we cannot use designated initializers.
776 *
777 * @param elapsed the value for the sinceCtsTimeout field
778 */
780 : sinceCtsTimeout(elapsed)
781 {
782 }
783};
784
785/**
786 * Struct to trace that main PHY switched to operate on a link on which an aux PHY that is not
787 * TX capable has gained or is expected to shortly gain a TXOP.
788 */
790 : public EmlsrMainPhySwitchTraceImpl<EmlsrUlTxopAuxPhyNotTxCapableTrace>
791{
792 static constexpr std::string_view m_name = "UlTxopAuxPhyNotTxCapable"; //!< trace name
793
794 AcIndex acIndex; //!< Access category of TXOP on aux PHY
795 Time remTime; //!< Remaining time to complete backoff countdown on the aux PHY link
796 Time remNav; //!< the remaining NAV on main PHY link when main PHY is requested to switch
797
798 /**
799 * Constructor provided because this struct is not an aggregate (it has a base struct), hence
800 * we cannot use designated initializers.
801 *
802 * @param aci the value for the acIndex field
803 * @param delay the value for the remTime field
804 * @param navLeft the value for the remNav field
805 */
806 EmlsrUlTxopAuxPhyNotTxCapableTrace(AcIndex aci, const Time& delay, const Time& navLeft)
807 : acIndex(aci),
808 remTime(delay),
809 remNav(navLeft)
810 {
811 }
812};
813
814} // namespace ns3
815
816#endif /* EMLSR_MANAGER_H */
Test CCA busy notifications on EMLSR clients.
EmlsrManager is an abstract base class defining the API that EHT non-AP MLDs with EMLSR activated can...
void SendEmlOmn()
Send an EML Operating Mode Notification frame.
Time GetMediumSyncDuration() const
void ComputeOperatingChannels()
Compute the operating channels that the main PHY and the aux PHY(s) must switch to in order to operat...
void(* MainPhySwitchCallback)(const EmlsrMainPhySwitchTrace &info)
TracedCallback signature for main PHY switch events.
void SwitchMainPhy(uint8_t linkId, bool noSwitchDelay, bool requestAccess, EmlsrMainPhySwitchTrace &&traceInfo)
Switch channel on the Main PHY so that it operates on the given link.
std::map< uint8_t, Time > m_startSleep
PHY ID-indexed map of last time sleep mode started.
void NotifyProtectionCompleted(uint8_t linkId)
Notify that protection (if required) is completed and data frame exchange can start on the given link...
void SetTransitionTimeout(Time timeout)
Set the Transition Timeout advertised by the associated AP with EMLSR activated.
void CancelMediumSyncDelayTimer(uint8_t linkId)
Cancel the MediumSyncDelay timer associated with the given link and take the appropriate actions.
bool m_useNotifiedMacHdr
whether to use the information about the MAC header of the MPDU being received (if notified by the PH...
bool m_auxPhyTxCapable
whether Aux PHYs are capable of transmitting PPDUs
virtual void DoNotifyTxopEnd(uint8_t linkId, Ptr< QosTxop > edca)=0
Notify the subclass of the end of a TXOP on the given link.
bool MediumSyncDelayNTxopsExceeded(uint8_t linkId)
Return whether no more TXOP attempt is allowed on the given link.
std::optional< Time > GetTransitionTimeout() const
void ChangeEmlsrMode()
This method is called to make an EMLSR mode change effective after the transition delay has elapsed o...
std::pair< bool, Time > GetDelayUntilAccessRequest(uint8_t linkId, AcIndex aci)
Notify that an UL TXOP is gained on the given link by the given AC.
virtual std::pair< bool, Time > DoGetDelayUntilAccessRequest(uint8_t linkId)=0
Subclasses have to provide an implementation for this method, that is called by the base class when t...
Ptr< EhtFrameExchangeManager > GetEhtFem(uint8_t linkId) const
void TxDropped(WifiMacDropReason reason, Ptr< const WifiMpdu > mpdu)
Notify that the given MPDU has been discarded for the given reason.
void NotifyUlTxopStart(uint8_t linkId)
Notify the start of an UL TXOP on the given link.
void TxOk(Ptr< const WifiMpdu > mpdu)
Notify the acknowledgment of the given MPDU.
void MediumSyncDelayTimerExpired(uint8_t linkId)
Take the appropriate actions when the MediumSyncDelay timer expires or is cancelled.
std::map< uint8_t, EventId > m_ulMainPhySwitch
link ID-indexed map of timers started when an aux PHY gains an UL TXOP and schedules a channel switch...
bool m_inDeviceInterference
whether in-device interference is such that a PHY cannot decode anything and cannot decrease the back...
bool GetCamStateReset() const
void SetEmlsrLinks(const std::set< uint8_t > &linkIds)
Take actions to enable EMLSR mode on the given set of links, if non-empty, or disable EMLSR mode,...
void SetMediumSyncOfdmEdThreshold(int8_t threshold)
Set the Medium Synchronization OFDM ED threshold (dBm) to use while the MediumSyncDelay timer is runn...
uint8_t m_mainPhyId
ID of main PHY (position in the vector of PHYs held by WifiNetDevice)
int8_t GetMediumSyncOfdmEdThreshold() const
std::map< uint8_t, EventId > m_auxPhyToSleepEvents
PHY ID-indexed map of events scheduled to put an Aux PHY to sleep.
std::map< uint8_t, MediumSyncDelayStatus > m_mediumSyncDelayStatus
the status of MediumSyncDelay timers (link ID-indexed)
bool m_auxPhyToSleep
whether Aux PHYs should be put into sleep mode while the Main PHY is carrying out a (DL or UL) TXOP
virtual std::pair< bool, Time > GetDelayUnlessMainPhyTakesOverUlTxop(uint8_t linkId)=0
Subclasses have to provide an implementation for this method, that is called by the base class when t...
virtual void SwitchMainPhyIfTxopGainedByAuxPhy(uint8_t linkId, AcIndex aci)=0
Subclasses have to provide an implementation for this method, that is called by the base class when t...
void NotifyDlTxopStart(uint8_t linkId)
Notify the start of a DL TXOP on the given link.
void NotifyMgtFrameReceived(Ptr< const WifiMpdu > mpdu, uint8_t linkId)
Notify the reception of a management frame addressed to us.
virtual uint8_t GetLinkToSendEmlOmn()=0
std::map< uint8_t, WifiPhyOperatingChannel > m_auxPhyChannels
link ID-indexed map of operating channels for the aux PHYs
virtual void DoNotifyUlTxopStart(uint8_t linkId)=0
Notify the subclass of the start of an UL TXOP on the given link.
Ptr< StaWifiMac > m_staMac
the MAC of the managed non-AP MLD
virtual void DoNotifyMgtFrameReceived(Ptr< const WifiMpdu > mpdu, uint8_t linkId)=0
Notify the subclass of the reception of a management frame addressed to us.
Time m_emlsrPaddingDelay
EMLSR Padding delay.
bool GetInDeviceInterference() const
virtual void NotifyMainPhySwitch(std::optional< uint8_t > currLinkId, uint8_t nextLinkId, Ptr< WifiPhy > auxPhy, Time duration)=0
Notify subclass that the main PHY is switching channel to operate on another link.
MHz_u m_auxPhyMaxWidth
max channel width supported by aux PHYs
virtual void NotifyInDeviceInterferenceStart(uint8_t linkId, Time duration)
Notify that an STA affiliated with the EMLSR client is causing in-device interference for the given a...
void SetMediumSyncMaxNTxops(std::optional< uint8_t > nTxops)
Set the maximum number of TXOPs a non-AP STA is allowed to attempt to initiate while the MediumSyncDe...
Time m_emlsrTransitionDelay
EMLSR Transition delay.
void SetWifiMac(Ptr< StaWifiMac > mac)
Set the wifi MAC.
void DecrementMediumSyncDelayNTxops(uint8_t linkId)
Decrement the counter indicating the number of TXOP attempts left while the MediumSyncDelay timer is ...
bool GetAuxPhyTxCapable() const
const std::set< uint8_t > & GetEmlsrLinks() const
MainPhySwitchTracedCallback m_mainPhySwitchTrace
main PHY switch trace source
void CancelAllSleepEvents()
Cancel all pending events to put aux PHYs into sleep/awake state.
Time m_mediumSyncDuration
duration of the MediumSyncDelay timer
void NotifyTxopEnd(uint8_t linkId, Ptr< QosTxop > edca=nullptr)
Notify the end of a TXOP on the given link.
std::optional< Time > m_emlsrTransitionTimeout
Transition timeout advertised by APs with EMLSR activated.
void SwitchAuxPhy(Ptr< WifiPhy > auxPhy, uint8_t currLinkId, uint8_t nextLinkId)
Switch channel on the Aux PHY operating on the given current link so that it operates on the given ne...
std::map< Ptr< WifiPhy >, dBm_u > m_prevCcaEdThreshold
the CCA sensitivity threshold to restore once the MediumSyncDelay timer expires or the PHY moves to a...
void ResetMediumSyncDelayNTxops(uint8_t linkId)
Reset the counter indicating the number of TXOP attempts left while the MediumSyncDelay timer is runn...
std::optional< Time > GetElapsedMediumSyncDelayTimer(uint8_t linkId) const
Check whether the MediumSyncDelay timer is running for the STA operating on the given link.
virtual void DoSetWifiMac(Ptr< StaWifiMac > mac)
Allow subclasses to take actions when the MAC is set.
std::map< uint8_t, Time > m_noPhySince
link ID-indexed map of the time since no PHY is operating on the link
void SetAuxPhyTxCapable(bool capable)
Set the member variable indicating whether Aux PHYs are capable of transmitting PPDUs.
virtual std::optional< WifiIcfDrop > CheckMainPhyTakesOverDlTxop(uint8_t linkId) const
This method is called when an aux PHY has completed reception of an ICF to determine whether there is...
std::optional< std::set< uint8_t > > m_nextEmlsrLinks
ID of the links that will become the EMLSR links when the pending notification frame is acknowledged.
void SetCcaEdThresholdOnLinkSwitch(Ptr< WifiPhy > phy, uint8_t linkId)
Set the CCA ED threshold (if needed) on the given PHY that is switching channel to operate on the giv...
virtual void NotifyEmlsrModeChanged()=0
Notify subclass that EMLSR mode changed.
void SetMainPhyId(uint8_t mainPhyId)
Set the ID of main PHY (position in the vector of PHYs held by WifiNetDevice).
virtual void EmlsrLinkSwitchCallback(uint8_t linkId, Ptr< WifiPhy > phy, bool connected)
Callback connected to the EmlsrLinkSwitch trace source of StaWifiMac.
const WifiPhyOperatingChannel & GetChannelForMainPhy(uint8_t linkId) const
~EmlsrManager() override
void ApplyMaxChannelWidthAndModClassOnAuxPhys()
Adjust the operating channel of all the aux PHYs to meet the constraint on the maximum channel width ...
void SetMediumSyncDuration(Time duration)
Set the duration of the MediumSyncDelay timer.
Time m_lastAdvTransitionDelay
last advertised transition delay
MainPhySwitchInfo m_mainPhySwitchInfo
main PHY switch info
virtual void DoNotifyDlTxopStart(uint8_t linkId)=0
Notify the subclass of the reception of an initial Control frame on the given link.
static constexpr bool REQUEST_ACCESS
request channel access when PHY switch ends
static constexpr bool DONT_REQUEST_ACCESS
do not request channel access when PHY switch ends
void DoDispose() override
Destructor implementation.
void StartMediumSyncDelayTimer(uint8_t linkId)
Start the MediumSyncDelay timer and take the appropriate actions.
int8_t m_msdOfdmEdThreshold
MediumSyncDelay OFDM ED threshold.
virtual void DoNotifyProtectionCompleted(uint8_t linkId)=0
Notify the subclass that protection (if required) is completed and data frame exchange can start on t...
std::map< uint8_t, WifiPhyOperatingChannel > m_mainPhyChannels
link ID-indexed map of operating channels for the main PHY
std::optional< uint8_t > m_msdMaxNTxops
MediumSyncDelay max number of TXOPs.
virtual std::optional< uint8_t > ResendNotification(Ptr< const WifiMpdu > mpdu)=0
A previous EML Operating Mode Notification frame was dropped.
Ptr< StaWifiMac > GetStaMac() const
Time m_lastAdvPaddingDelay
last advertised padding delay
WifiModulationClass m_auxPhyMaxModClass
max modulation class supported by aux PHYs
uint8_t GetMainPhyId() const
std::optional< uint8_t > GetMediumSyncMaxNTxops() const
void SetCamStateReset(bool enable)
Set the member variable indicating whether the state of the CAM should be reset when the main PHY swi...
virtual void NotifyRtsSent(uint8_t linkId, Ptr< const WifiPsdu > rts, const WifiTxVector &txVector)
Notify that RTS transmission is starting on the given link.
EventId m_transitionTimeoutEvent
Timer started after the successful transmission of an EML Operating Mode Notification frame.
void SetInDeviceInterference(bool enable)
Set the member variable indicating whether in-device interference is such that a PHY cannot decode an...
const WifiPhyOperatingChannel & GetChannelForAuxPhy(uint8_t linkId) const
bool m_resetCamState
whether to reset the state of CAM when main PHY switches channel
static TypeId GetTypeId()
Get the type ID.
std::pair< bool, Time > CheckPossiblyReceivingIcf(uint8_t linkId) const
Check whether a PPDU that may be an ICF is being received on the given link.
std::set< uint8_t > m_emlsrLinks
ID of the EMLSR links (empty if EMLSR mode is disabled)
void SetSleepStateForAllAuxPhys(bool sleep)
Set sleep state or awake state for all aux PHYs.
An identifier for simulation events.
Definition event-id.h:45
Implement the header for Action frames of type EML Operating Mode Notification.
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
Class that keeps track of all information about the current PHY operating channel.
This class mimics the TXVECTOR which is to be passed to the PHY in order to define the parameters whi...
WifiMacDropReason
The reason why an MPDU was dropped.
Definition wifi-mac.h:71
WifiModulationClass
This enumeration defines the modulation classes per (Table 10-6 "Modulation classes"; IEEE 802....
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.
static constexpr uint8_t WIFI_LINKID_UNDEFINED
Invalid link identifier.
Definition wifi-utils.h:283
ns3::Time timeout
Struct to trace that main PHY started switching after a CTS timeout occurred on the link on which an ...
EmlsrCtsAfterRtsTimeoutTrace(const Time &elapsed)
Constructor provided because this struct is not an aggregate (it has a base struct),...
static constexpr std::string_view m_name
trace name
Time sinceCtsTimeout
time elapsed since CTS timeout occurred
Struct to trace that main PHY switched to start a DL TXOP after that an aux PHY received an ICF.
static constexpr std::string_view m_name
trace name
Base struct for EMLSR Main PHY switch traces.
virtual ~EmlsrMainPhySwitchTrace()=default
uint8_t toLinkId
ID of the link the main PHY is moving to.
std::optional< uint8_t > fromLinkId
ID of the link the main PHY is moving from (if any)
virtual std::string_view GetName() const =0
virtual std::shared_ptr< EmlsrMainPhySwitchTrace > Clone() const =0
Implementation for the EMLSR Main PHY switch trace base struct.
std::string_view GetName() const override
std::shared_ptr< EmlsrMainPhySwitchTrace > Clone() const override
Store information about a main PHY switch.
std::string reason
the reason for switching the main PHY
uint8_t from
ID of the link which the main PHY is/has been leaving.
Time start
start of channel switching
uint8_t to
ID of the link which the main PHY is moving to.
bool disconnected
true if the main PHY is not connected to any link, i.e., it is switching or waiting to be connected t...
Information about the status of the MediumSyncDelay timer associated with a link.
std::optional< uint8_t > msdNTxopsLeft
number of TXOP attempts left while the MediumSyncDelay timer is running
EventId timer
the MediumSyncDelay timer
Struct to trace that main PHY switched when a (DL or UL) TXOP ended.
static constexpr std::string_view m_name
trace name
Struct to trace that main PHY switched to operate on a link on which an aux PHY that is not TX capabl...
Time remTime
Remaining time to complete backoff countdown on the aux PHY link.
EmlsrUlTxopAuxPhyNotTxCapableTrace(AcIndex aci, const Time &delay, const Time &navLeft)
Constructor provided because this struct is not an aggregate (it has a base struct),...
static constexpr std::string_view m_name
trace name
AcIndex acIndex
Access category of TXOP on aux PHY.
Time remNav
the remaining NAV on main PHY link when main PHY is requested to switch
Struct to trace that main PHY switched to start an UL TXOP after that an aux PHY transmitted an RTS.
static constexpr std::string_view m_name
trace name