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