A Discrete-Event Network Simulator
API
Loading...
Searching...
No Matches
wifi-phy-state-helper.h
Go to the documentation of this file.
1/*
2 * Copyright (c) 2005,2006 INRIA
3 *
4 * SPDX-License-Identifier: GPL-2.0-only
5 *
6 * Author: Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
7 */
8
9#ifndef WIFI_PHY_STATE_HELPER_H
10#define WIFI_PHY_STATE_HELPER_H
11
12#include "phy-entity.h"
13#include "wifi-phy-common.h"
14#include "wifi-phy-state.h"
15#include "wifi-ppdu.h"
16
17#include "ns3/callback.h"
18#include "ns3/nstime.h"
19#include "ns3/object.h"
20#include "ns3/traced-callback.h"
21
22#include <algorithm>
23#include <list>
24#include <memory>
25#include <vector>
26
27namespace ns3
28{
29
30class WifiPhyListener;
31class WifiTxVector;
32class WifiMode;
33class Packet;
34class WifiPsdu;
35struct RxSignalInfo;
36
37/**
38 * Callback if PSDU successfully received (i.e. if aggregate,
39 * it means that at least one MPDU of the A-MPDU was received,
40 * considering that the per-MPDU reception status is also provided).
41 *
42 * arg1: PSDU received successfully
43 * arg2: info on the received signal (\see RxSignalInfo)
44 * arg3: TXVECTOR of PSDU
45 * arg4: vector of per-MPDU status of reception.
46 */
47typedef Callback<void,
48 Ptr<const WifiPsdu>,
49 RxSignalInfo,
50 const WifiTxVector&,
51 const std::vector<bool>&>
53/**
54 * Callback if PSDU unsuccessfuly received
55 *
56 * arg1: PSDU received unsuccessfuly
57 */
59
60/**
61 * @ingroup wifi
62 *
63 * This objects implements the PHY state machine of the Wifi device.
64 */
66{
67 public:
68 /**
69 * @brief Get the type ID.
70 * @return the object TypeId
71 */
72 static TypeId GetTypeId();
73
75
76 /**
77 * Set a callback for a successful reception.
78 *
79 * @param callback the RxOkCallback to set
80 */
82 /**
83 * Set a callback for a failed reception.
84 *
85 * @param callback the RxErrorCallback to set
86 */
88 /**
89 * Register WifiPhyListener to this WifiPhyStateHelper.
90 *
91 * @param listener the WifiPhyListener to register
92 */
93 void RegisterListener(const std::shared_ptr<WifiPhyListener>& listener);
94 /**
95 * Remove WifiPhyListener from this WifiPhyStateHelper.
96 *
97 * @param listener the WifiPhyListener to unregister
98 */
99 void UnregisterListener(const std::shared_ptr<WifiPhyListener>& listener);
100 /**
101 * Return the current state of WifiPhy.
102 *
103 * @return the current state of WifiPhy
104 */
105 WifiPhyState GetState() const;
106 /**
107 * Check whether the current state is CCA busy.
108 *
109 * @return true if the current state is CCA busy, false otherwise
110 */
111 bool IsStateCcaBusy() const;
112 /**
113 * Check whether the current state is IDLE.
114 *
115 * @return true if the current state is IDLE, false otherwise
116 */
117 bool IsStateIdle() const;
118 /**
119 * Check whether the current state is RX.
120 *
121 * @return true if the current state is RX, false otherwise
122 */
123 bool IsStateRx() const;
124 /**
125 * Check whether the current state is TX.
126 *
127 * @return true if the current state is TX, false otherwise
128 */
129 bool IsStateTx() const;
130 /**
131 * Check whether the current state is SWITCHING.
132 *
133 * @return true if the current state is SWITCHING, false otherwise
134 */
135 bool IsStateSwitching() const;
136 /**
137 * Check whether the current state is SLEEP.
138 *
139 * @return true if the current state is SLEEP, false otherwise
140 */
141 bool IsStateSleep() const;
142 /**
143 * Check whether the current state is OFF.
144 *
145 * @return true if the current state is OFF, false otherwise
146 */
147 bool IsStateOff() const;
148 /**
149 * Return the time before the state is back to IDLE.
150 *
151 * @return the delay before the state is back to IDLE
152 */
153 Time GetDelayUntilIdle() const;
154 /**
155 * Return the time the last RX start.
156 *
157 * @return the time the last RX start.
158 */
159 Time GetLastRxStartTime() const;
160 /**
161 * Return the time the last RX end.
162 *
163 * @return the time the last RX end.
164 */
165 Time GetLastRxEndTime() const;
166
167 /**
168 * @param states a set of PHY states
169 * @return the last time the PHY has been in any of the given states
170 */
171 Time GetLastTime(std::initializer_list<WifiPhyState> states) const;
172
173 /**
174 * Switch state to TX for the given duration.
175 *
176 * @param txDuration the duration of the PPDU to transmit
177 * @param psdus the PSDUs in the transmitted PPDU (only one unless it is a MU PPDU)
178 * @param txPower the nominal TX power
179 * @param txVector the TX vector for the transmission
180 */
181 void SwitchToTx(Time txDuration,
182 const WifiConstPsduMap& psdus,
183 dBm_u txPower,
184 const WifiTxVector& txVector);
185 /**
186 * Switch state to RX for the given duration.
187 *
188 * @param rxDuration the duration of the RX
189 */
190 void SwitchToRx(Time rxDuration);
191 /**
192 * Switch state to channel switching for the given duration.
193 *
194 * @param switchingDuration the duration of required to switch the channel
195 */
196 void SwitchToChannelSwitching(Time switchingDuration);
197 /**
198 * Notify the reception of an MPDU included in an A-MPDU.
199 *
200 * @param psdu the successfully received PSDU
201 * @param rxSignalInfo the info on the received signal (\see RxSignalInfo)
202 * @param txVector TXVECTOR of the PSDU
203 */
205 RxSignalInfo rxSignalInfo,
206 const WifiTxVector& txVector);
207 /**
208 * Handle the successful reception of a PSDU.
209 *
210 * @param psdu the successfully received PSDU
211 * @param rxSignalInfo the info on the received signal (\see RxSignalInfo)
212 * @param txVector TXVECTOR of the PSDU
213 * @param staId the station ID of the PSDU (only used for MU)
214 * @param statusPerMpdu reception status per MPDU
215 */
217 RxSignalInfo rxSignalInfo,
218 const WifiTxVector& txVector,
219 uint16_t staId,
220 const std::vector<bool>& statusPerMpdu);
221 /**
222 * Handle the unsuccessful reception of a PSDU.
223 *
224 * @param psdu the PSDU that we failed to received
225 * @param snr the SNR of the received PSDU in linear scale
226 */
227 void NotifyRxPsduFailed(Ptr<const WifiPsdu> psdu, double snr);
228
229 /**
230 * Handle the outcome of a reception of a PPDU.
231 *
232 * @param ppdu the received PPDU
233 * @param rxSignalInfo the info on the received signal (\see RxSignalInfo)
234 * @param txVector TXVECTOR of the PSDU
235 * @param staId the station ID of the PSDU (only used for MU)
236 * @param statusPerMpdu reception status per MPDU
237 */
239 RxSignalInfo rxSignalInfo,
240 const WifiTxVector& txVector,
241 uint16_t staId,
242 const std::vector<bool>& statusPerMpdu);
243 /**
244 * Switch from RX after the reception was successful.
245 */
246 void SwitchFromRxEndOk();
247 /**
248 * Switch from RX after the reception failed.
249 *
250 * @param txVector the TXVECTOR used for transmission of failed frame
251 */
252 void SwitchFromRxEndError(const WifiTxVector& txVector);
253 /**
254 * Abort current reception following a CCA reset request.
255 * @param operatingWidth the channel width the PHY is operating on
256 */
257 void SwitchFromRxAbort(MHz_u operatingWidth);
258 /**
259 * Switch to CCA busy.
260 *
261 * @param duration the duration of the CCA state
262 * @param channelType the channel type for which the CCA busy state is reported.
263 * @param per20MhzDurations vector that indicates for how long each 20 MHz subchannel
264 * (corresponding to the index of the element in the vector) is busy and where a zero
265 * duration indicates that the subchannel is idle. The vector is non-empty if the PHY supports
266 * 802.11ax or later and if the operational channel width is larger than 20 MHz.
267 */
268 void SwitchMaybeToCcaBusy(Time duration,
269 WifiChannelListType channelType,
270 const std::vector<Time>& per20MhzDurations);
271 /**
272 * Switch to sleep mode.
273 */
274 void SwitchToSleep();
275 /**
276 * Switch from sleep mode.
277 */
278 void SwitchFromSleep();
279 /**
280 * Switch to off mode.
281 */
282 void SwitchToOff();
283 /**
284 * Switch from off mode.
285 */
286 void SwitchFromOff();
287
288 /**
289 * TracedCallback signature for state changes.
290 *
291 * @param [in] start Time when the \pname{state} started.
292 * @param [in] duration Amount of time we've been in (or will be in)
293 * the \pname{state}.
294 * @param [in] state The state.
295 */
296 typedef void (*StateTracedCallback)(Time start, Time duration, WifiPhyState state);
297
298 /**
299 * TracedCallback signature for receive end OK event.
300 *
301 * @param [in] packet The received packet.
302 * @param [in] snr The SNR of the received packet in linear scale.
303 * @param [in] mode The transmission mode of the packet.
304 * @param [in] preamble The preamble of the packet.
305 */
306 typedef void (*RxOkTracedCallback)(Ptr<const Packet> packet,
307 double snr,
308 WifiMode mode,
309 WifiPreamble preamble);
310
311 /**
312 * TracedCallback signature for the outcome of a received packet.
313 *
314 * @param [in] ppdu The received PPDU (Physical Layer Protocol Data Unit).
315 * @param [in] signalInfo Information about the received signal, including its power and other
316 * characteristics.
317 * @param [in] txVector The transmission vector used for the packet, detailing
318 * the transmission parameters.
319 * @param [in] outcomes A vector of boolean values indicating the
320 * success or failure of receiving individual MPDUs within the PSDU.
321 */
323 RxSignalInfo signalInfo,
324 const WifiTxVector& txVector,
325 const std::vector<bool>& outcomes);
326
327 /**
328 * TracedCallback signature for receive end error event.
329 *
330 * @param [in] packet The received packet.
331 * @param [in] snr The SNR of the received packet in linear scale.
332 */
333 typedef void (*RxEndErrorTracedCallback)(Ptr<const Packet> packet, double snr);
334
335 /**
336 * TracedCallback signature for transmit event.
337 *
338 * @param [in] packet The received packet.
339 * @param [in] mode The transmission mode of the packet.
340 * @param [in] preamble The preamble of the packet.
341 * @param [in] power The transmit power level.
342 */
343 typedef void (*TxTracedCallback)(Ptr<const Packet> packet,
344 WifiMode mode,
345 WifiPreamble preamble,
346 uint8_t power);
347
348 /**
349 * Notify all WifiPhyListener objects of the given PHY event.
350 *
351 * @tparam FUNC \deduced Member function type
352 * @tparam Ts \deduced Function argument types
353 * @param f the member function to invoke
354 * @param args arguments to pass to the member function
355 */
356 template <typename FUNC, typename... Ts>
357 void NotifyListeners(FUNC f, Ts&&... args);
358
359 private:
360 /**
361 * typedef for a list of WifiPhyListeners. We use weak pointers so that unregistering a
362 * listener is not necessary to delete a listener (reference count is not incremented by
363 * weak pointers).
364 */
365 typedef std::list<std::weak_ptr<WifiPhyListener>> Listeners;
366
367 /**
368 * Log the idle and CCA busy states.
369 */
371
372 /**
373 * Switch the state from RX.
374 */
375 void DoSwitchFromRx();
376
377 /**
378 * The trace source fired when state is changed.
379 */
381
382 NS_LOG_TEMPLATE_DECLARE; //!< the log component
383 bool m_sleeping; ///< sleeping
384 bool m_isOff; ///< switched off
385 Time m_endTx; ///< end transmit
386 Time m_endRx; ///< end receive
387 Time m_endCcaBusy; ///< end CCA busy
388 Time m_endSwitching; ///< end switching
389 Time m_endSleep; ///< end sleep
390 Time m_endOff; ///< end off
391 Time m_endIdle; ///< end idle
392 Time m_startTx; ///< start transmit
393 Time m_startRx; ///< start receive
394 Time m_startCcaBusy; ///< start CCA busy
395 Time m_startSwitching; ///< start switching
396 Time m_startSleep; ///< start sleep
397 Time m_startOff; ///< start off
398 Time m_previousStateChangeTime; ///< previous state change time
399
400 Listeners m_listeners; ///< listeners
402 m_rxOkTrace; ///< receive OK trace callback
403 TracedCallback<Ptr<const WifiPpdu>, RxSignalInfo, const WifiTxVector&, const std::vector<bool>&>
404 m_rxOutcomeTrace; ///< receive OK trace callback
405 TracedCallback<Ptr<const Packet>, double> m_rxErrorTrace; ///< receive error trace callback
407 m_txTrace; ///< transmit trace callback
408 RxOkCallback m_rxOkCallback; ///< receive OK callback
409 RxErrorCallback m_rxErrorCallback; ///< receive error callback
410};
411
412} // namespace ns3
413
414/***************************************************************
415 * Implementation of the templates declared above.
416 ***************************************************************/
417
418namespace ns3
419{
420
421template <typename FUNC, typename... Ts>
422void
424{
425 NS_LOG_FUNCTION(this);
426 // In some cases (e.g., when notifying an EMLSR client of a link switch), a notification
427 // to a PHY listener involves the addition and/or removal of a PHY listener, thus modifying
428 // the list we are iterating over. This is dangerous, so ensure that we iterate over a copy
429 // of the list of PHY listeners. The copied list contains shared pointers to the PHY listeners
430 // to prevent them from being deleted.
431 std::list<std::shared_ptr<WifiPhyListener>> listeners;
432 std::transform(m_listeners.cbegin(),
433 m_listeners.cend(),
434 std::back_inserter(listeners),
435 [](auto&& listener) { return listener.lock(); });
436
437 for (const auto& listener : listeners)
438 {
439 if (listener)
440 {
441 std::invoke(f, listener, std::forward<Ts>(args)...);
442 }
443 }
444}
445
446} // namespace ns3
447
448#endif /* WIFI_PHY_STATE_HELPER_H */
Callback template class.
Definition callback.h:422
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
Forward calls to a chain of Callback.
a unique identifier for an interface.
Definition type-id.h:49
represent a single transmission mode
Definition wifi-mode.h:40
This objects implements the PHY state machine of the Wifi device.
void NotifyRxPpduOutcome(Ptr< const WifiPpdu > ppdu, RxSignalInfo rxSignalInfo, const WifiTxVector &txVector, uint16_t staId, const std::vector< bool > &statusPerMpdu)
Handle the outcome of a reception of a PPDU.
bool IsStateSwitching() const
Check whether the current state is SWITCHING.
void(* TxTracedCallback)(Ptr< const Packet > packet, WifiMode mode, WifiPreamble preamble, uint8_t power)
TracedCallback signature for transmit event.
void SwitchToRx(Time rxDuration)
Switch state to RX for the given duration.
bool IsStateCcaBusy() const
Check whether the current state is CCA busy.
Time GetDelayUntilIdle() const
Return the time before the state is back to IDLE.
bool IsStateIdle() const
Check whether the current state is IDLE.
Time GetLastRxStartTime() const
Return the time the last RX start.
void SwitchFromRxEndError(const WifiTxVector &txVector)
Switch from RX after the reception failed.
void(* StateTracedCallback)(Time start, Time duration, WifiPhyState state)
TracedCallback signature for state changes.
void DoSwitchFromRx()
Switch the state from RX.
void SwitchToTx(Time txDuration, const WifiConstPsduMap &psdus, dBm_u txPower, const WifiTxVector &txVector)
Switch state to TX for the given duration.
void SwitchFromRxEndOk()
Switch from RX after the reception was successful.
Time m_previousStateChangeTime
previous state change time
void SwitchToChannelSwitching(Time switchingDuration)
Switch state to channel switching for the given duration.
void SwitchToOff()
Switch to off mode.
TracedCallback< Ptr< const WifiPpdu >, RxSignalInfo, const WifiTxVector &, const std::vector< bool > & > m_rxOutcomeTrace
receive OK trace callback
void NotifyRxMpdu(Ptr< const WifiPsdu > psdu, RxSignalInfo rxSignalInfo, const WifiTxVector &txVector)
Notify the reception of an MPDU included in an A-MPDU.
TracedCallback< Ptr< const Packet >, WifiMode, WifiPreamble, uint8_t > m_txTrace
transmit trace callback
Time m_startSwitching
start switching
void UnregisterListener(const std::shared_ptr< WifiPhyListener > &listener)
Remove WifiPhyListener from this WifiPhyStateHelper.
TracedCallback< Time, Time, WifiPhyState > m_stateLogger
The trace source fired when state is changed.
void NotifyListeners(FUNC f, Ts &&... args)
Notify all WifiPhyListener objects of the given PHY event.
void LogPreviousIdleAndCcaBusyStates()
Log the idle and CCA busy states.
void(* RxOutcomeTracedCallback)(Ptr< const WifiPpdu > ppdu, RxSignalInfo signalInfo, const WifiTxVector &txVector, const std::vector< bool > &outcomes)
TracedCallback signature for the outcome of a received packet.
static TypeId GetTypeId()
Get the type ID.
RxOkCallback m_rxOkCallback
receive OK callback
TracedCallback< Ptr< const Packet >, double, WifiMode, WifiPreamble > m_rxOkTrace
receive OK trace callback
void NotifyRxPsduFailed(Ptr< const WifiPsdu > psdu, double snr)
Handle the unsuccessful reception of a PSDU.
bool IsStateOff() const
Check whether the current state is OFF.
void(* RxEndErrorTracedCallback)(Ptr< const Packet > packet, double snr)
TracedCallback signature for receive end error event.
void(* RxOkTracedCallback)(Ptr< const Packet > packet, double snr, WifiMode mode, WifiPreamble preamble)
TracedCallback signature for receive end OK event.
WifiPhyState GetState() const
Return the current state of WifiPhy.
NS_LOG_TEMPLATE_DECLARE
the log component
RxErrorCallback m_rxErrorCallback
receive error callback
void SwitchToSleep()
Switch to sleep mode.
void SwitchMaybeToCcaBusy(Time duration, WifiChannelListType channelType, const std::vector< Time > &per20MhzDurations)
Switch to CCA busy.
TracedCallback< Ptr< const Packet >, double > m_rxErrorTrace
receive error trace callback
bool IsStateTx() const
Check whether the current state is TX.
void SwitchFromOff()
Switch from off mode.
Time m_startCcaBusy
start CCA busy
Time GetLastTime(std::initializer_list< WifiPhyState > states) const
void SwitchFromRxAbort(MHz_u operatingWidth)
Abort current reception following a CCA reset request.
Time GetLastRxEndTime() const
Return the time the last RX end.
void SetReceiveOkCallback(RxOkCallback callback)
Set a callback for a successful reception.
void SwitchFromSleep()
Switch from sleep mode.
bool IsStateSleep() const
Check whether the current state is SLEEP.
bool IsStateRx() const
Check whether the current state is RX.
std::list< std::weak_ptr< WifiPhyListener > > Listeners
typedef for a list of WifiPhyListeners.
void SetReceiveErrorCallback(RxErrorCallback callback)
Set a callback for a failed reception.
void NotifyRxPsduSucceeded(Ptr< const WifiPsdu > psdu, RxSignalInfo rxSignalInfo, const WifiTxVector &txVector, uint16_t staId, const std::vector< bool > &statusPerMpdu)
Handle the successful reception of a PSDU.
void RegisterListener(const std::shared_ptr< WifiPhyListener > &listener)
Register WifiPhyListener to this WifiPhyStateHelper.
This class mimics the TXVECTOR which is to be passed to the PHY in order to define the parameters whi...
#define NS_LOG_FUNCTION(parameters)
If log level LOG_FUNCTION is enabled, this macro will output all input parameters separated by ",...
WifiPreamble
The type of preamble to be used by an IEEE 802.11 transmission.
WifiChannelListType
Enumeration of the possible channel-list parameter elements defined in Table 8-5 of IEEE 802....
Every class exported by the ns3 library is enclosed in the ns3 namespace.
Callback< void, Ptr< const WifiPsdu > > RxErrorCallback
Callback if PSDU unsuccessfuly received.
WifiPhyState
The state of the PHY layer.
Callback< void, Ptr< const WifiPsdu >, RxSignalInfo, const WifiTxVector &, const std::vector< bool > & > RxOkCallback
Callback if PSDU successfully received (i.e.
std::unordered_map< uint16_t, Ptr< const WifiPsdu > > WifiConstPsduMap
Map of const PSDUs indexed by STA-ID.
Definition wifi-ppdu.h:38
Declaration of:
RxSignalInfo structure containing info on the received signal.
Definition wifi-types.h:78
Declaration of the following enums:
Declaration of ns3::WifiPpdu class and ns3::WifiConstPsduMap.