A Discrete-Event Network Simulator
API
Loading...
Searching...
No Matches
phy-entity.h
Go to the documentation of this file.
1/*
2 * Copyright (c) 2020 Orange Labs
3 *
4 * SPDX-License-Identifier: GPL-2.0-only
5 *
6 * Authors: Rediet <getachew.redieteab@orange.com>
7 * Sébastien Deronne <sebastien.deronne@gmail.com> (for logic ported from wifi-phy and
8 * spectrum-wifi-phy)
9 * Mathieu Lacage <mathieu.lacage@sophia.inria.fr> (for logic ported from wifi-phy)
10 */
11
12#ifndef PHY_ENTITY_H
13#define PHY_ENTITY_H
14
15#include "wifi-phy-band.h"
17#include "wifi-phy.h"
18#include "wifi-ppdu.h"
19#include "wifi-tx-vector.h"
20#include "wifi-types.h"
21
22#include "ns3/event-id.h"
23#include "ns3/nstime.h"
24#include "ns3/simple-ref-count.h"
25#include "ns3/wifi-export.h"
26
27#include <list>
28#include <map>
29#include <optional>
30#include <tuple>
31#include <utility>
32
33/**
34 * @file
35 * @ingroup wifi
36 * Declaration of:
37 * - ns3::PhyEntity class
38 * - ns3::SignalNoiseDbm, ns3::MpduInfo, and ns3::RxSignalInfo structs
39 * - ns3::RxPowerWattPerChannelBand typedef
40 */
41
42namespace ns3
43{
44
45/**
46 * A map of the received power for each band
47 */
48using RxPowerWattPerChannelBand = std::map<WifiSpectrumBandInfo, Watt_u>;
49
50class WifiMpdu;
51class WifiPhy;
53class Event;
55class WifiPsdu;
56class WifiPpdu;
57
58/**
59 * @brief Abstract class for PHY entities
60 * @ingroup wifi
61 *
62 * This class enables to have a unique set of APIs
63 * to be used by each PHY entity, corresponding to
64 * the different amendments of the IEEE 802.11 standard.
65 */
66class WIFI_EXPORT PhyEntity
67{
68 public:
69 /**
70 * Action to perform in case of RX failure.
71 */
73 {
74 DROP = 0, //!< drop PPDU and set CCA_BUSY
75 ABORT, //!< abort reception of PPDU
76 IGNORE //!< ignore the reception
77 };
78
79 /**
80 * Status of the reception of the PPDU field.
81 */
83 {
84 bool isSuccess{true}; //!< outcome (\c true if success) of the reception
87 DROP}; //!< action to perform in case of failure \see PhyRxFailureAction
88
89 /**
90 * Constructor setting outcome of reception.
91 *
92 * @param s \c true if success
93 */
95 : isSuccess(s)
96 {
97 }
98
99 /**
100 * Constructor.
101 *
102 * @param s \c true if success
103 * @param r reason of failure
104 * @param a action to perform in case of failure
105 */
112 };
113
114 /**
115 * Destructor for PHY entity
116 */
117 virtual ~PhyEntity();
118
119 /**
120 * Set the WifiPhy owning this PHY entity.
121 *
122 * @param wifiPhy the WifiPhy owning this PHY entity
123 */
124 void SetOwner(Ptr<WifiPhy> wifiPhy);
125
126 /**
127 * Check if the WifiMode is supported.
128 *
129 * @param mode the WifiMode to check
130 * @return true if the WifiMode is supported,
131 * false otherwise
132 */
133 virtual bool IsModeSupported(WifiMode mode) const;
134 /**
135 * @return the number of WifiModes supported by this entity
136 */
137 virtual uint8_t GetNumModes() const;
138
139 /**
140 * Get the WifiMode corresponding to the given MCS index.
141 *
142 * @param index the index of the MCS
143 * @return the WifiMode corresponding to the MCS index
144 *
145 * This method should be used only for HtPhy and child classes.
146 */
147 virtual WifiMode GetMcs(uint8_t index) const;
148 /**
149 * Check if the WifiMode corresponding to the given MCS index is supported.
150 *
151 * @param index the index of the MCS
152 * @return true if the WifiMode corresponding to the MCS index is supported,
153 * false otherwise
154 *
155 * Will return false for non-MCS modes.
156 */
157 virtual bool IsMcsSupported(uint8_t index) const;
158 /**
159 * Check if the WifiModes handled by this PHY are MCSs.
160 *
161 * @return true if the handled WifiModes are MCSs,
162 * false if they are non-MCS modes
163 */
164 virtual bool HandlesMcsModes() const;
165
166 /**
167 * Get the WifiMode for the SIG field specified by the PPDU field.
168 *
169 * @param field the PPDU field
170 * @param txVector the transmission parameters
171 *
172 * @return the WifiMode used for the SIG field
173 */
174 virtual WifiMode GetSigMode(WifiPpduField field, const WifiTxVector& txVector) const;
175
176 /**
177 * @brief Return a const iterator to the first WifiMode
178 *
179 * @return a const iterator to the first WifiMode.
180 */
181 std::list<WifiMode>::const_iterator begin() const;
182 /**
183 * @brief Return a const iterator to past-the-last WifiMode
184 *
185 * @return a const iterator to past-the-last WifiMode.
186 */
187 std::list<WifiMode>::const_iterator end() const;
188
189 /**
190 * Return the field following the provided one.
191 *
192 * @param currentField the considered PPDU field
193 * @param preamble the preamble indicating the PPDU format
194 * @return the PPDU field following the reference one
195 */
196 WifiPpduField GetNextField(WifiPpduField currentField, WifiPreamble preamble) const;
197
198 /**
199 * Get the duration of the PPDU field (or group of fields)
200 * used by this entity for the given transmission parameters.
201 *
202 * @param field the PPDU field (or group of fields)
203 * @param txVector the transmission parameters
204 *
205 * @return the duration of the PPDU field
206 */
207 virtual Time GetDuration(WifiPpduField field, const WifiTxVector& txVector) const;
208 /**
209 * @param txVector the transmission parameters
210 *
211 * @return the total duration of the PHY preamble and PHY header.
212 */
213 Time CalculatePhyPreambleAndHeaderDuration(const WifiTxVector& txVector) const;
214
215 /**
216 * @param size the number of bytes in the packet to send
217 * @param txVector the TXVECTOR used for the transmission of this packet
218 * @param band the frequency band
219 * @param mpdutype the type of the MPDU as defined in WifiPhy::MpduType.
220 * @param incFlag this flag is used to indicate that the variables need to be update or not
221 * This function is called a couple of times for the same packet so variables should not be
222 * increased each time.
223 * @param totalAmpduSize the total size of the previously transmitted MPDUs for the concerned
224 * A-MPDU. If incFlag is set, this parameter will be updated.
225 * @param totalAmpduNumSymbols the number of symbols previously transmitted for the MPDUs in the
226 * concerned A-MPDU, used for the computation of the number of symbols needed for the last MPDU.
227 * If incFlag is set, this parameter will be updated.
228 * @param staId the STA-ID of the PSDU (only used for MU PPDUs)
229 *
230 * @return the duration of the PSDU
231 */
233 const WifiTxVector& txVector,
234 WifiPhyBand band,
235 MpduType mpdutype,
236 bool incFlag,
237 uint32_t& totalAmpduSize,
238 double& totalAmpduNumSymbols,
239 uint16_t staId) const = 0;
240
241 /**
242 * Get a WifiConstPsduMap from a PSDU and the TXVECTOR to use to send the PSDU.
243 * The STA-ID value is properly determined based on whether the given PSDU has
244 * to be transmitted as a DL or UL frame.
245 *
246 * @param psdu the given PSDU
247 * @param txVector the TXVECTOR to use to send the PSDU
248 * @return a WifiConstPsduMap built from the given PSDU and the given TXVECTOR
249 */
251 const WifiTxVector& txVector) const;
252
253 /**
254 * Get the maximum PSDU size in bytes.
255 *
256 * @return the maximum PSDU size in bytes
257 */
258 virtual uint32_t GetMaxPsduSize() const = 0;
259
260 /**
261 * Return a map of PHY header chunk information per PPDU field.
262 * This map will contain the PPDU fields that are actually present based
263 * on the \p txVector information.
264 *
265 * @param txVector the transmission parameters
266 * @param ppduStart the time at which the PPDU started
267 * @return the list of preamble sections
268 *
269 * @see PhyHeaderSections
270 */
271 PhyHeaderSections GetPhyHeaderSections(const WifiTxVector& txVector, Time ppduStart) const;
272
273 /**
274 * Build amendment-specific PPDU.
275 *
276 * @param psdus the PHY payloads (PSDUs)
277 * @param txVector the TXVECTOR that was used for the PPDU
278 * @param ppduDuration the transmission duration of the PPDU
279 *
280 * @return the amendment-specific WifiPpdu
281 */
282 virtual Ptr<WifiPpdu> BuildPpdu(const WifiConstPsduMap& psdus,
283 const WifiTxVector& txVector,
284 Time ppduDuration);
285
286 /**
287 * Get the duration of the PPDU up to (but excluding) the given field.
288 *
289 * @param field the considered PPDU field
290 * @param txVector the transmission parameters
291 * @return the duration from the beginning of the PPDU up to the field
292 */
293 Time GetDurationUpToField(WifiPpduField field, const WifiTxVector& txVector) const;
294 /**
295 * Get the remaining duration of the PPDU after the end of the given field.
296 *
297 * @param field the considered PPDU field
298 * @param ppdu the received PPDU
299 * @return the remaining duration of the PPDU after the end of to the field
300 */
302
303 /**
304 * Get the PSDU addressed to that PHY in a PPDU (useful for MU PPDU).
305 *
306 * @param ppdu the PPDU to extract the PSDU from
307 * @return the PSDU addressed to that PHY
308 */
310
311 /**
312 * Start receiving the PHY preamble of a PPDU (i.e. the first bit of the preamble has arrived).
313 *
314 * This method triggers the start of the preamble detection period (\see
315 * StartPreambleDetectionPeriod) if the PHY can process the PPDU.
316 *
317 * @param ppdu the arriving PPDU
318 * @param rxPowersW the receive power in W per band
319 * @param rxDuration the duration of the PPDU
320 */
322 RxPowerWattPerChannelBand& rxPowersW,
323 Time rxDuration);
324 /**
325 * Start receiving a given field.
326 *
327 * This method will call the DoStartReceiveField.
328 * EndReceiveField is also scheduled after the duration of the field
329 * (except for the special case of preambles \see DoStartReceivePreamble).
330 * The PHY is kept in CCA busy during the reception of the field (except for
331 * data field which should be in RX).
332 *
333 * @param field the starting PPDU field
334 * @param event the event holding incoming PPDU's information
335 */
336 void StartReceiveField(WifiPpduField field, Ptr<Event> event);
337 /**
338 * End receiving a given field.
339 *
340 * This method will call the DoEndReceiveField to obtain the outcome of the reception.
341 * In case of success, reception of the next field is triggered.
342 * In case of failure, the indications in the returned \see PhyFieldRxStatus
343 * are performed.
344 *
345 * @param field the ending PPDU field
346 * @param event the event holding incoming PPDU's information
347 */
348 void EndReceiveField(WifiPpduField field, Ptr<Event> event);
349
350 /**
351 * The last symbol of the PPDU has arrived.
352 *
353 * @param event the event holding incoming PPDU's information
354 */
355 void EndReceivePayload(Ptr<Event> event);
356
357 /**
358 * Reset PHY at the end of the PPDU under reception after it has failed the PHY header.
359 *
360 * @param event the event holding incoming PPDU's information
361 */
362 void ResetReceive(Ptr<Event> event);
363
364 /**
365 * Cancel and clear all running events.
366 */
367 virtual void CancelAllEvents();
368 /**
369 * Cancel all end preamble detection events.
370 */
372
373 /// @copydoc WifiPhy::GetTimeToPreambleDetectionEnd
374 virtual std::optional<Time> GetTimeToPreambleDetectionEnd() const;
375
376 /// @copydoc WifiPhy::GetTimeToMacHdrEnd
377 virtual std::optional<Time> GetTimeToMacHdrEnd(uint16_t staId) const;
378
379 /**
380 * Return the STA ID that has been assigned to the station this PHY belongs to.
381 * This is typically called for MU PPDUs, in order to pick the correct PSDU.
382 *
383 * @param ppdu the PPDU for which the STA ID is requested
384 * @return the STA ID
385 */
386 virtual uint16_t GetStaId(const Ptr<const WifiPpdu> ppdu) const;
387
388 /**
389 * Determine whether the PHY shall issue a PHY-RXSTART.indication primitive in response to a
390 * given PPDU.
391 *
392 * @param ppdu the PPDU
393 * @return true if the PHY shall issue a PHY-RXSTART.indication primitive in response to a PPDU,
394 * false otherwise
395 */
396 virtual bool CanStartRx(Ptr<const WifiPpdu> ppdu) const;
397
398 /**
399 * Check if PHY state should move to CCA busy state based on current
400 * state of interference tracker.
401 *
402 * @param ppdu the incoming PPDU or nullptr for any signal
403 */
404 virtual void SwitchMaybeToCcaBusy(const Ptr<const WifiPpdu> ppdu);
405 /**
406 * Notify PHY state helper to switch to CCA busy state,
407 *
408 * @param ppdu the incoming PPDU or nullptr for any signal
409 * @param duration the duration of the CCA state
410 * @param channelType the channel type for which the CCA busy state is reported.
411 */
412 virtual void NotifyCcaBusy(const Ptr<const WifiPpdu> ppdu,
413 Time duration,
414 WifiChannelListType channelType);
415 /**
416 * This function is called by SpectrumWifiPhy to send
417 * the PPDU while performing amendment-specific actions.
418 * @see SpectrumWifiPhy::StartTx
419 *
420 * @param ppdu the PPDU to send
421 */
422 virtual void StartTx(Ptr<const WifiPpdu> ppdu);
423
424 /**
425 * This function prepares most of the WifiSpectrumSignalParameters
426 * parameters and invokes SpectrumWifiPhy's Transmit method.
427 * @see SpectrumWifiPhy::Transmit
428 *
429 * @param txDuration the duration of the transmission
430 * @param ppdu the PPDU to send
431 * @param txPower the total TX power
432 * @param txPowerSpectrum the TX PSD
433 * @param type the type of transmission (for logging)
434 */
435 void Transmit(Time txDuration,
437 dBm_u txPower,
438 Ptr<SpectrumValue> txPowerSpectrum,
439 const std::string& type);
440
441 /**
442 * @param psduMap the PSDU(s) to transmit indexed by STA-ID
443 * @param txVector the TXVECTOR used for the transmission of the PPDU
444 * @param band the frequency band being used
445 *
446 * @return the total amount of time this PHY will stay busy for the transmission of the PPDU
447 */
448 virtual Time CalculateTxDuration(const WifiConstPsduMap& psduMap,
449 const WifiTxVector& txVector,
450 WifiPhyBand band) const;
451 /**
452 * Return the CCA threshold for a given channel type.
453 * If the channel type is not provided, the default CCA threshold is returned.
454 *
455 * @param ppdu the PPDU that is being received
456 * @param channelType the channel type
457 * @return the CCA threshold
458 */
459 virtual dBm_u GetCcaThreshold(const Ptr<const WifiPpdu> ppdu,
460 WifiChannelListType channelType) const;
461
462 /**
463 * The WifiPpdu from the TX PHY is received by each RX PHY attached to the same channel.
464 * By default and for performance reasons, all RX PHYs will work on the same WifiPpdu instance
465 * from TX instead of a copy of it. Child classes can change that behavior and do a copy and/or
466 * change the content of the parameters stored in WifiPpdu.
467 *
468 * @param ppdu the WifiPpdu transmitted by the TX PHY
469 * @return the WifiPpdu to be used by the RX PHY
470 */
472
473 /**
474 * Obtain the next UID for the PPDU to transmit.
475 * Note that the global UID counter could be incremented.
476 *
477 * @param txVector the transmission parameters
478 * @return the UID to use for the PPDU to transmit
479 */
480 virtual uint64_t ObtainNextUid(const WifiTxVector& txVector);
481
482 /**
483 * Obtain the maximum time between two PPDUs with the same UID to consider they are identical
484 * and their power can be added construtively.
485 *
486 * @param txVector the TXVECTOR used for the transmission of the PPDUs
487 * @return the maximum time between two PPDUs with the same UID to decode them
488 */
489 virtual Time GetMaxDelayPpduSameUid(const WifiTxVector& txVector);
490
491 protected:
492 /**
493 * A map of PPDU field elements per preamble type.
494 * This corresponds to the different PPDU formats introduced by each amendment.
495 */
496 typedef std::map<WifiPreamble, std::vector<WifiPpduField>> PpduFormats;
497
498 /**
499 * A pair to hold modulation information: code rate and constellation size.
500 */
501 typedef std::pair<WifiCodeRate, uint16_t> CodeRateConstellationSizePair;
502
503 /**
504 * A modulation lookup table using unique name of modulation as key.
505 */
506 typedef std::map<std::string, CodeRateConstellationSizePair> ModulationLookupTable;
507
508 /**
509 * Return the PPDU formats of the PHY.
510 *
511 * @return the PPDU formats of the PHY
512 */
513 virtual const PpduFormats& GetPpduFormats() const = 0;
514
515 /**
516 * Start receiving a given field, perform amendment-specific actions, and
517 * signify if it is supported.
518 *
519 * @param field the starting PPDU field
520 * @param event the event holding incoming PPDU's information
521 * @return \c true if the field is supported, \c false otherwise
522 */
523 virtual bool DoStartReceiveField(WifiPpduField field, Ptr<Event> event);
524 /**
525 * End receiving a given field, perform amendment-specific actions, and
526 * provide the status of the reception.
527 *
528 * @param field the ending PPDU field
529 * @param event the event holding incoming PPDU's information
530 * @return status of the reception of the PPDU field
531 */
533
534 /**
535 * Get the event corresponding to the incoming PPDU.
536 *
537 * We store all incoming preamble events, perform amendment-specific actions,
538 * and a decision is made at the end of the preamble detection window.
539 *
540 * @param ppdu the incoming PPDU
541 * @param rxPowersW the receive power in W per band
542 * @return the event holding the incoming PPDU's information
543 */
545 /**
546 * End receiving the preamble, perform amendment-specific actions, and
547 * provide the status of the reception.
548 *
549 * @param event the event holding incoming PPDU's information
550 * @return status of the reception of the preamble
551 */
553 /**
554 * Start the preamble detection period.
555 *
556 * @param event the event holding incoming PPDU's information
557 */
559 /**
560 * End the preamble detection period.
561 *
562 * The PHY will focus on the strongest PPDU and drop others.
563 * In addition, in case of successful detection, the end of the
564 * preamble reception is triggered (\see DoEndReceivePreamble).
565 *
566 * @param event the event holding incoming PPDU's information
567 */
569
570 /**
571 * Start receiving the PSDU (i.e. the first symbol of the PSDU has arrived).
572 *
573 * @param event the event holding incoming PPDU's information
574 */
576
577 /**
578 * Start receiving the PSDU (i.e. the first symbol of the PSDU has arrived)
579 * and perform amendment-specific actions.
580 *
581 * @param event the event holding incoming PPDU's information
582 * @return the payload duration
583 */
585
586 /**
587 * Perform amendment-specific actions before resetting PHY at
588 * the end of the PPDU under reception after it has failed the PHY header.
589 *
590 * @param event the event holding incoming PPDU's information
591 */
592 virtual void DoResetReceive(Ptr<Event> event);
593
594 /**
595 * Perform amendment-specific actions before aborting the
596 * current reception.
597 *
598 * @param reason the reason the reception is aborted
599 */
601
602 /**
603 * Checks if the signaled configuration (excluding bandwidth)
604 * is supported by the PHY.
605 *
606 * @param ppdu the received PPDU
607 * @return \c true if supported, \c false otherwise
608 */
609 virtual bool IsConfigSupported(Ptr<const WifiPpdu> ppdu) const;
610
611 /**
612 * Drop the PPDU and the corresponding preamble detection event, but keep CCA busy
613 * state after the completion of the currently processed event.
614 *
615 * @param ppdu the incoming PPDU
616 * @param reason the reason the PPDU is dropped
617 * @param endRx the end of the incoming PPDU's reception
618 */
620
621 /**
622 * Erase the event corresponding to the PPDU from the list of preamble events,
623 * but consider it as noise after the completion of the current event.
624 *
625 * @param ppdu the incoming PPDU
626 * @param rxDuration the duration of the PPDU
627 */
628 void ErasePreambleEvent(Ptr<const WifiPpdu> ppdu, Time rxDuration);
629
630 /**
631 * Get the reception status for the provided MPDU and notify.
632 *
633 * @param mpdu the arriving MPDU
634 * @param event the event holding incoming PPDU's information
635 * @param staId the station ID of the PSDU (only used for MU)
636 * @param relativeMpduStart the relative start time of the MPDU within the A-MPDU.
637 * 0 for normal MPDUs
638 * @param mpduDuration the duration of the MPDU
639 *
640 * @return information on MPDU reception: status, signal power (dBm), and noise power (in dBm)
641 */
642 std::pair<bool, SignalNoiseDbm> GetReceptionStatus(Ptr<WifiMpdu> mpdu,
643 Ptr<Event> event,
644 uint16_t staId,
645 Time relativeMpduStart,
646 Time mpduDuration);
647 /**
648 * The last symbol of an MPDU in an A-MPDU has arrived.
649 *
650 * @param event the event holding incoming PPDU's information
651 * @param mpdu the arriving MPDU
652 * @param mpduIndex the index of the MPDU within the A-MPDU
653 * @param relativeStart the relative start time of the MPDU within the A-MPDU.
654 * @param mpduDuration the duration of the MPDU
655 */
656 void EndOfMpdu(Ptr<Event> event,
657 Ptr<WifiMpdu> mpdu,
658 size_t mpduIndex,
659 Time relativeStart,
660 Time mpduDuration);
661
662 /**
663 * Schedule end of MPDUs events.
664 *
665 * @param event the event holding incoming PPDU's information
666 */
667 void ScheduleEndOfMpdus(Ptr<Event> event);
668
669 /**
670 * Perform amendment-specific actions when the payload is successfully received.
671 *
672 * @param psdu the successfully received PSDU
673 * @param rxSignalInfo the info on the received signal (\see RxSignalInfo)
674 * @param txVector TXVECTOR of the PSDU
675 * @param staId the station ID of the PSDU (only used for MU)
676 * @param statusPerMpdu reception status per MPDU
677 */
678 virtual void RxPayloadSucceeded(Ptr<const WifiPsdu> psdu,
679 RxSignalInfo rxSignalInfo,
680 const WifiTxVector& txVector,
681 uint16_t staId,
682 const std::vector<bool>& statusPerMpdu);
683 /**
684 * Perform amendment-specific actions when the payload is unsuccessfuly received.
685 *
686 * @param psdu the PSDU that we failed to received
687 * @param snr the SNR of the received PSDU in linear scale
688 * @param txVector TXVECTOR of the PSDU
689 */
690 virtual void RxPayloadFailed(Ptr<const WifiPsdu> psdu,
691 double snr,
692 const WifiTxVector& txVector);
693
694 /**
695 * Perform amendment-specific actions at the end of the reception of
696 * the payload.
697 *
698 * @param ppdu the incoming PPDU
699 */
700 virtual void DoEndReceivePayload(Ptr<const WifiPpdu> ppdu);
701
702 /**
703 * Get the channel width and band to use (will be overloaded by child classes).
704 *
705 * @param txVector the transmission parameters
706 * @param staId the station ID of the PSDU
707 * @return a pair of channel width and band
708 */
709 virtual std::pair<MHz_u, WifiSpectrumBandInfo> GetChannelWidthAndBand(
710 const WifiTxVector& txVector,
711 uint16_t staId) const;
712
713 /**
714 * Abort the current reception.
715 *
716 * @param reason the reason the reception is aborted
717 */
719
720 /**
721 * Obtain a random value from the WifiPhy's generator.
722 * Wrapper used by child classes.
723 *
724 * @return a uniform random value
725 */
726 double GetRandomValue() const;
727 /**
728 * Obtain the SNR and PER of the PPDU field from the WifiPhy's InterferenceHelper class.
729 * Wrapper used by child classes.
730 *
731 * @param field the PPDU field
732 * @param event the event holding incoming PPDU's information
733 * @return the SNR and PER
734 */
736 /**
737 * Obtain the received power for a given band.
738 * Wrapper used by child classes.
739 *
740 * @param event the event holding incoming PPDU's information
741 * @return the received power for the event over a given band
742 */
744 /**
745 * Get the pointer to the current event (stored in WifiPhy).
746 * Wrapper used by child classes.
747 *
748 * @return the pointer to the current event
749 */
751 /**
752 * Get the map of current preamble events (stored in WifiPhy).
753 * Wrapper used by child classes.
754 *
755 * @return the reference to the map of current preamble events
756 */
757 const std::map<std::pair<uint64_t, WifiPreamble>, Ptr<Event>>& GetCurrentPreambleEvents() const;
758 /**
759 * Add an entry to the map of current preamble events (stored in WifiPhy).
760 * Wrapper used by child classes.
761 *
762 * @param event the event holding incoming PPDU's information
763 */
764 void AddPreambleEvent(Ptr<Event> event);
765
766 /**
767 * Create an event using WifiPhy's InterferenceHelper class.
768 * Wrapper used by child classes.
769 *
770 * @param ppdu the PPDU
771 * @param duration the PPDU duration
772 * @param rxPower received power per band (W)
773 * @param isStartHePortionRxing flag whether the event corresponds to the start of the OFDMA
774 * payload reception (only used for UL-OFDMA)
775 * @return the created event
776 */
778 Time duration,
780 bool isStartHePortionRxing = false);
781 /**
782 * Handle reception of a PPDU that carries the same content of another PPDU.
783 * This is typically called upon reception of preambles of HE MU PPDUs or reception
784 * of non-HT duplicate control frames that carries the exact same content sent from different
785 * STAs. If the delay between the PPDU and the first PPDU carrying the same content is small
786 * enough, PPDU can be decoded and its power is added constructively, and the TXVECTOR is
787 * updated accordingly. Otherwise, a new interference event is created and PPDU is dropped by
788 * the PHY.
789 *
790 * @param event the event of the ongoing reception
791 * @param ppdu the newly received PPDU (UL MU or non-HT duplicate)
792 * @param rxPower the received power (W) per band of the newly received PPDU
793 */
794 virtual void HandleRxPpduWithSameContent(Ptr<Event> event,
797
798 /**
799 * Notify WifiPhy's InterferenceHelper of the end of the reception,
800 * clear maps and end of MPDU event, and eventually reset WifiPhy.
801 *
802 * @param reset whether to reset WifiPhy
803 */
804 void NotifyInterferenceRxEndAndClear(bool reset);
805
806 /**
807 * @param txPower power to spread across the bands
808 * @param ppdu the PPDU that will be transmitted
809 * @return Pointer to SpectrumValue
810 *
811 * This is a helper function to create the right TX PSD corresponding
812 * to the amendment of this PHY.
813 */
815 Ptr<const WifiPpdu> ppdu) const = 0;
816
817 /**
818 * Fire the trace indicating that the PHY is starting to receive the payload of a PPDU.
819 *
820 * @param txVector the TXVECTOR used to transmit the PPDU
821 * @param payloadDuration the TX duration of the PPDU payload
822 */
823 void NotifyPayloadBegin(const WifiTxVector& txVector, const Time& payloadDuration);
824
825 /**
826 * If the operating channel width is a multiple of 20 MHz, return the info
827 * corresponding to the primary channel of the given
828 * bandwidth (which must be a multiple of 20 MHz and not exceed the operating
829 * channel width). Otherwise, this call is equivalent to GetBand with
830 * <i>bandIndex</i> equal to zero.
831 *
832 * @param bandWidth the width of the band to be returned
833 *
834 * @return the info corresponding to the band
835 */
837 /**
838 * If the channel bonding is used, return the info corresponding to
839 * the secondary channel of the given bandwidth (which must be a multiple of 20 MHz
840 * and not exceed the operating channel width).
841 *
842 * @param bandWidth the width of the band to be returned
843 *
844 * @return the info corresponding to the band
845 */
847
848 /**
849 * Return the channel width used to measure the RSSI.
850 *
851 * @param ppdu the PPDU that is being received
852 * @return the channel width used for RSSI measurement
853 */
855
856 /**
857 * Return the channel width used in the reception spectrum model.
858 *
859 * @param txVector the TXVECTOR of the PPDU that is being received
860 * @return the channel width used for RxSpectrumModel
861 */
862 virtual MHz_u GetRxChannelWidth(const WifiTxVector& txVector) const;
863
864 /**
865 * Return the delay until CCA busy is ended for a given sensitivity threshold and a given band.
866 *
867 * @param threshold the CCA sensitivity threshold
868 * @param band identify the requested band
869 * @return the delay until CCA busy is ended
870 */
871 Time GetDelayUntilCcaEnd(dBm_u threshold, const WifiSpectrumBandInfo& band);
872
873 /**
874 * @param currentChannelWidth channel width of the current transmission
875 * @return the width of the guard band
876 *
877 * Wrapper method used by child classes for PSD generation.
878 * Note that this method is necessary for testing UL OFDMA.
879 */
880 MHz_u GetGuardBandwidth(MHz_u currentChannelWidth) const;
881 /**
882 * @return a tuple containing the minimum rejection for the inner band,
883 * the minimum rejection for the outer band, and
884 * the maximum rejection for the outer band
885 * for the transmit spectrum mask.
886 *
887 * Wrapper method used by child classes for PSD generation.
888 */
889 std::tuple<dBr_u, dBr_u, dBr_u> GetTxMaskRejectionParams() const;
890
892 std::optional<std::pair<Time, WifiChannelListType>>; //!< CCA end time and its corresponding
893 //!< channel list type (can be
894 //!< std::nullopt if IDLE)
895
896 /**
897 * Get CCA end time and its corresponding channel list type when a new signal has been received
898 * by the PHY.
899 *
900 * @param ppdu the incoming PPDU or nullptr for any signal
901 * @return CCA end time and its corresponding channel list type when a new signal has been
902 * received by the PHY, or std::nullopt if all channel list types are IDLE.
903 */
905
906 Ptr<WifiPhy> m_wifiPhy; //!< Pointer to the owning WifiPhy
907 Ptr<WifiPhyStateHelper> m_state; //!< Pointer to WifiPhyStateHelper of the WifiPhy (to make it
908 //!< reachable for child classes)
909
910 std::list<WifiMode> m_modeList; //!< the list of supported modes
911
912 std::vector<EventId> m_endPreambleDetectionEvents; //!< the end of preamble detection events
913 std::vector<EventId> m_endOfMpduEvents; //!< the end of MPDU events (only used for A-MPDUs)
914 std::map<uint16_t, std::vector<EventId>>
915 m_endOfMacHdrEvents; //!< STA_ID-indexed map of the RX end of MAC header events
916
917 std::vector<EventId>
918 m_endRxPayloadEvents; //!< the end of receive events (only one unless UL MU reception)
919
920 /**
921 * A pair of a UID and STA_ID
922 */
923 typedef std::pair<uint64_t /* UID */, uint16_t /* STA-ID */> UidStaIdPair;
924
925 std::map<UidStaIdPair, std::vector<bool>>
926 m_statusPerMpduMap; //!< Map of the current reception status per MPDU that is filled in as
927 //!< long as MPDUs are being processed by the PHY in case of an A-MPDU
928 std::map<UidStaIdPair, SignalNoiseDbm>
929 m_signalNoiseMap; //!< Map of the latest signal power and noise power in dBm (noise power
930 //!< includes the noise figure)
931
932 static uint64_t m_globalPpduUid; //!< Global counter of the PPDU UID
933};
934
935/**
936 * @brief Stream insertion operator.
937 *
938 * @param os the stream
939 * @param action the action to perform in case of failure
940 * @returns a reference to the stream
941 */
942std::ostream& operator<<(std::ostream& os, const PhyEntity::PhyRxFailureAction& action);
943/**
944 * @brief Stream insertion operator.
945 *
946 * @param os the stream
947 * @param status the status of the reception of a PPDU field
948 * @returns a reference to the stream
949 */
950std::ostream& operator<<(std::ostream& os, const PhyEntity::PhyFieldRxStatus& status);
951
952} // namespace ns3
953
954#endif /* PHY_ENTITY_H */
handles interference calculations
handles interference calculations
Abstract class for PHY entities.
Definition phy-entity.h:67
void NotifyPayloadBegin(const WifiTxVector &txVector, const Time &payloadDuration)
Fire the trace indicating that the PHY is starting to receive the payload of a PPDU.
virtual void HandleRxPpduWithSameContent(Ptr< Event > event, Ptr< const WifiPpdu > ppdu, RxPowerWattPerChannelBand &rxPower)
Handle reception of a PPDU that carries the same content of another PPDU.
void DropPreambleEvent(Ptr< const WifiPpdu > ppdu, WifiPhyRxfailureReason reason, Time endRx)
Drop the PPDU and the corresponding preamble detection event, but keep CCA busy state after the compl...
void EndOfMpdu(Ptr< Event > event, Ptr< WifiMpdu > mpdu, size_t mpduIndex, Time relativeStart, Time mpduDuration)
The last symbol of an MPDU in an A-MPDU has arrived.
MHz_u GetGuardBandwidth(MHz_u currentChannelWidth) const
virtual void RxPayloadSucceeded(Ptr< const WifiPsdu > psdu, RxSignalInfo rxSignalInfo, const WifiTxVector &txVector, uint16_t staId, const std::vector< bool > &statusPerMpdu)
Perform amendment-specific actions when the payload is successfully received.
virtual PhyFieldRxStatus DoEndReceivePreamble(Ptr< Event > event)
End receiving the preamble, perform amendment-specific actions, and provide the status of the recepti...
Ptr< WifiPhyStateHelper > m_state
Pointer to WifiPhyStateHelper of the WifiPhy (to make it reachable for child classes)
Definition phy-entity.h:907
virtual void RxPayloadFailed(Ptr< const WifiPsdu > psdu, double snr, const WifiTxVector &txVector)
Perform amendment-specific actions when the payload is unsuccessfuly received.
void EndPreambleDetectionPeriod(Ptr< Event > event)
End the preamble detection period.
virtual void NotifyCcaBusy(const Ptr< const WifiPpdu > ppdu, Time duration, WifiChannelListType channelType)
Notify PHY state helper to switch to CCA busy state,.
virtual Ptr< WifiPpdu > BuildPpdu(const WifiConstPsduMap &psdus, const WifiTxVector &txVector, Time ppduDuration)
Build amendment-specific PPDU.
virtual uint64_t ObtainNextUid(const WifiTxVector &txVector)
Obtain the next UID for the PPDU to transmit.
virtual Time DoStartReceivePayload(Ptr< Event > event)
Start receiving the PSDU (i.e.
virtual void StartReceivePreamble(Ptr< const WifiPpdu > ppdu, RxPowerWattPerChannelBand &rxPowersW, Time rxDuration)
Start receiving the PHY preamble of a PPDU (i.e.
virtual std::optional< Time > GetTimeToPreambleDetectionEnd() const
Get the remaining time to preamble detection period to elapse, if preamble detection is ongoing.
virtual Time GetPayloadDuration(uint32_t size, const WifiTxVector &txVector, WifiPhyBand band, MpduType mpdutype, bool incFlag, uint32_t &totalAmpduSize, double &totalAmpduNumSymbols, uint16_t staId) const =0
std::pair< WifiCodeRate, uint16_t > CodeRateConstellationSizePair
A pair to hold modulation information: code rate and constellation size.
Definition phy-entity.h:501
void Transmit(Time txDuration, Ptr< const WifiPpdu > ppdu, dBm_u txPower, Ptr< SpectrumValue > txPowerSpectrum, const std::string &type)
This function prepares most of the WifiSpectrumSignalParameters parameters and invokes SpectrumWifiPh...
const std::map< std::pair< uint64_t, WifiPreamble >, Ptr< Event > > & GetCurrentPreambleEvents() const
Get the map of current preamble events (stored in WifiPhy).
std::map< UidStaIdPair, SignalNoiseDbm > m_signalNoiseMap
Map of the latest signal power and noise power in dBm (noise power includes the noise figure)
Definition phy-entity.h:929
Watt_u GetRxPowerForPpdu(Ptr< Event > event) const
Obtain the received power for a given band.
Ptr< WifiPhy > m_wifiPhy
Pointer to the owning WifiPhy.
Definition phy-entity.h:906
std::pair< bool, SignalNoiseDbm > GetReceptionStatus(Ptr< WifiMpdu > mpdu, Ptr< Event > event, uint16_t staId, Time relativeMpduStart, Time mpduDuration)
Get the reception status for the provided MPDU and notify.
std::map< std::string, CodeRateConstellationSizePair > ModulationLookupTable
A modulation lookup table using unique name of modulation as key.
Definition phy-entity.h:506
std::optional< std::pair< Time, WifiChannelListType > > CcaIndication
CCA end time and its corresponding channel list type (can be std::nullopt if IDLE)
Definition phy-entity.h:891
std::vector< EventId > m_endOfMpduEvents
the end of MPDU events (only used for A-MPDUs)
Definition phy-entity.h:913
virtual MHz_u GetRxChannelWidth(const WifiTxVector &txVector) const
Return the channel width used in the reception spectrum model.
virtual const PpduFormats & GetPpduFormats() const =0
Return the PPDU formats of the PHY.
virtual bool DoStartReceiveField(WifiPpduField field, Ptr< Event > event)
Start receiving a given field, perform amendment-specific actions, and signify if it is supported.
virtual void CancelAllEvents()
Cancel and clear all running events.
virtual uint32_t GetMaxPsduSize() const =0
Get the maximum PSDU size in bytes.
virtual Time CalculateTxDuration(const WifiConstPsduMap &psduMap, const WifiTxVector &txVector, WifiPhyBand band) const
virtual void DoAbortCurrentReception(WifiPhyRxfailureReason reason)
Perform amendment-specific actions before aborting the current reception.
void AbortCurrentReception(WifiPhyRxfailureReason reason)
Abort the current reception.
void EndReceivePayload(Ptr< Event > event)
The last symbol of the PPDU has arrived.
std::map< WifiPreamble, std::vector< WifiPpduField > > PpduFormats
A map of PPDU field elements per preamble type.
Definition phy-entity.h:496
virtual std::pair< MHz_u, WifiSpectrumBandInfo > GetChannelWidthAndBand(const WifiTxVector &txVector, uint16_t staId) const
Get the channel width and band to use (will be overloaded by child classes).
static uint64_t m_globalPpduUid
Global counter of the PPDU UID.
Definition phy-entity.h:932
virtual Ptr< SpectrumValue > GetTxPowerSpectralDensity(Watt_u txPower, Ptr< const WifiPpdu > ppdu) const =0
void StartReceivePayload(Ptr< Event > event)
Start receiving the PSDU (i.e.
std::vector< EventId > m_endRxPayloadEvents
the end of receive events (only one unless UL MU reception)
Definition phy-entity.h:918
virtual void DoResetReceive(Ptr< Event > event)
Perform amendment-specific actions before resetting PHY at the end of the PPDU under reception after ...
void EndReceiveField(WifiPpduField field, Ptr< Event > event)
End receiving a given field.
virtual Ptr< Event > DoGetEvent(Ptr< const WifiPpdu > ppdu, RxPowerWattPerChannelBand &rxPowersW)
Get the event corresponding to the incoming PPDU.
WifiSpectrumBandInfo GetPrimaryBand(MHz_u bandWidth) const
If the operating channel width is a multiple of 20 MHz, return the info corresponding to the primary ...
void CancelRunningEndPreambleDetectionEvents()
Cancel all end preamble detection events.
Time GetDelayUntilCcaEnd(dBm_u threshold, const WifiSpectrumBandInfo &band)
Return the delay until CCA busy is ended for a given sensitivity threshold and a given band.
virtual void SwitchMaybeToCcaBusy(const Ptr< const WifiPpdu > ppdu)
Check if PHY state should move to CCA busy state based on current state of interference tracker.
void NotifyInterferenceRxEndAndClear(bool reset)
Notify WifiPhy's InterferenceHelper of the end of the reception, clear maps and end of MPDU event,...
void StartPreambleDetectionPeriod(Ptr< Event > event)
Start the preamble detection period.
Time GetDurationUpToField(WifiPpduField field, const WifiTxVector &txVector) const
Get the duration of the PPDU up to (but excluding) the given field.
std::map< UidStaIdPair, std::vector< bool > > m_statusPerMpduMap
Map of the current reception status per MPDU that is filled in as long as MPDUs are being processed b...
Definition phy-entity.h:926
virtual bool CanStartRx(Ptr< const WifiPpdu > ppdu) const
Determine whether the PHY shall issue a PHY-RXSTART.indication primitive in response to a given PPDU.
virtual void StartTx(Ptr< const WifiPpdu > ppdu)
This function is called by SpectrumWifiPhy to send the PPDU while performing amendment-specific actio...
SnrPer GetPhyHeaderSnrPer(WifiPpduField field, Ptr< Event > event) const
Obtain the SNR and PER of the PPDU field from the WifiPhy's InterferenceHelper class.
virtual dBm_u GetCcaThreshold(const Ptr< const WifiPpdu > ppdu, WifiChannelListType channelType) const
Return the CCA threshold for a given channel type.
Time GetRemainingDurationAfterField(Ptr< const WifiPpdu > ppdu, WifiPpduField field) const
Get the remaining duration of the PPDU after the end of the given field.
virtual uint16_t GetStaId(const Ptr< const WifiPpdu > ppdu) const
Return the STA ID that has been assigned to the station this PHY belongs to.
void StartReceiveField(WifiPpduField field, Ptr< Event > event)
Start receiving a given field.
void ResetReceive(Ptr< Event > event)
Reset PHY at the end of the PPDU under reception after it has failed the PHY header.
PhyHeaderSections GetPhyHeaderSections(const WifiTxVector &txVector, Time ppduStart) const
Return a map of PHY header chunk information per PPDU field.
virtual CcaIndication GetCcaIndication(const Ptr< const WifiPpdu > ppdu)
Get CCA end time and its corresponding channel list type when a new signal has been received by the P...
std::list< WifiMode > m_modeList
the list of supported modes
Definition phy-entity.h:910
virtual Time GetMaxDelayPpduSameUid(const WifiTxVector &txVector)
Obtain the maximum time between two PPDUs with the same UID to consider they are identical and their ...
std::pair< uint64_t, uint16_t > UidStaIdPair
A pair of a UID and STA_ID.
Definition phy-entity.h:923
Ptr< const Event > GetCurrentEvent() const
Get the pointer to the current event (stored in WifiPhy).
double GetRandomValue() const
Obtain a random value from the WifiPhy's generator.
std::vector< EventId > m_endPreambleDetectionEvents
the end of preamble detection events
Definition phy-entity.h:912
virtual std::optional< Time > GetTimeToMacHdrEnd(uint16_t staId) const
Get the remaining time to the end of the MAC header reception of the next MPDU being received from th...
virtual Ptr< const WifiPsdu > GetAddressedPsduInPpdu(Ptr< const WifiPpdu > ppdu) const
Get the PSDU addressed to that PHY in a PPDU (useful for MU PPDU).
void ErasePreambleEvent(Ptr< const WifiPpdu > ppdu, Time rxDuration)
Erase the event corresponding to the PPDU from the list of preamble events, but consider it as noise ...
virtual Ptr< const WifiPpdu > GetRxPpduFromTxPpdu(Ptr< const WifiPpdu > ppdu)
The WifiPpdu from the TX PHY is received by each RX PHY attached to the same channel.
void AddPreambleEvent(Ptr< Event > event)
Add an entry to the map of current preamble events (stored in WifiPhy).
virtual void DoEndReceivePayload(Ptr< const WifiPpdu > ppdu)
Perform amendment-specific actions at the end of the reception of the payload.
std::tuple< dBr_u, dBr_u, dBr_u > GetTxMaskRejectionParams() const
virtual MHz_u GetMeasurementChannelWidth(const Ptr< const WifiPpdu > ppdu) const =0
Return the channel width used to measure the RSSI.
virtual WifiConstPsduMap GetWifiConstPsduMap(Ptr< const WifiPsdu > psdu, const WifiTxVector &txVector) const
Get a WifiConstPsduMap from a PSDU and the TXVECTOR to use to send the PSDU.
virtual bool IsConfigSupported(Ptr< const WifiPpdu > ppdu) const
Checks if the signaled configuration (excluding bandwidth) is supported by the PHY.
Ptr< Event > CreateInterferenceEvent(Ptr< const WifiPpdu > ppdu, Time duration, RxPowerWattPerChannelBand &rxPower, bool isStartHePortionRxing=false)
Create an event using WifiPhy's InterferenceHelper class.
PhyRxFailureAction
Action to perform in case of RX failure.
Definition phy-entity.h:73
@ DROP
drop PPDU and set CCA_BUSY
Definition phy-entity.h:74
@ IGNORE
ignore the reception
Definition phy-entity.h:76
@ ABORT
abort reception of PPDU
Definition phy-entity.h:75
WifiSpectrumBandInfo GetSecondaryBand(MHz_u bandWidth) const
If the channel bonding is used, return the info corresponding to the secondary channel of the given b...
virtual PhyFieldRxStatus DoEndReceiveField(WifiPpduField field, Ptr< Event > event)
End receiving a given field, perform amendment-specific actions, and provide the status of the recept...
std::map< uint16_t, std::vector< EventId > > m_endOfMacHdrEvents
STA_ID-indexed map of the RX end of MAC header events.
Definition phy-entity.h:915
void ScheduleEndOfMpdus(Ptr< Event > event)
Schedule end of MPDUs events.
Smart pointer class similar to boost::intrusive_ptr.
Definition ptr.h:67
Simulation virtual time values and global simulation resolution.
Definition nstime.h:96
represent a single transmission mode
Definition wifi-mode.h:38
WifiMpdu stores a (const) packet along with a MAC header.
Definition wifi-mpdu.h:51
802.11 PHY layer model
Definition wifi-phy.h:62
This objects implements the PHY state machine of the Wifi device.
WifiPpdu stores a preamble, a modulation class, PHY headers and a PSDU.
Definition wifi-ppdu.h:47
WifiPsdu stores an MPDU, S-MPDU or A-MPDU, by keeping header(s) and payload(s) separate for each cons...
Definition wifi-psdu.h:33
This class mimics the TXVECTOR which is to be passed to the PHY in order to define the parameters whi...
WifiPhyRxfailureReason
Enumeration of the possible reception failure reasons.
WifiPreamble
The type of preamble to be used by an IEEE 802.11 transmission.
WifiPhyBand
Identifies the PHY band.
WifiChannelListType
Enumeration of the possible channel-list parameter elements defined in Table 8-5 of IEEE 802....
WifiPpduField
The type of PPDU field (grouped for convenience)
MpduType
The type of an MPDU.
Definition wifi-types.h:48
Every class exported by the ns3 library is enclosed in the ns3 namespace.
std::map< WifiSpectrumBandInfo, Watt_u > RxPowerWattPerChannelBand
A map of the received power for each band.
std::ostream & operator<<(std::ostream &os, const Angles &a)
Definition angles.cc:148
std::map< WifiPpduField, PhyHeaderChunkInfo > PhyHeaderSections
A map of PhyHeaderChunkInfo elements per PPDU field.
double MHz_u
MHz weak type.
Definition wifi-units.h:31
double dBm_u
dBm weak type
Definition wifi-units.h:27
std::unordered_map< uint16_t, Ptr< const WifiPsdu > > WifiConstPsduMap
Map of const PSDUs indexed by STA-ID.
Definition wifi-ppdu.h:38
double Watt_u
Watt weak type.
Definition wifi-units.h:25
Status of the reception of the PPDU field.
Definition phy-entity.h:83
WifiPhyRxfailureReason reason
failure reason
Definition phy-entity.h:85
PhyRxFailureAction actionIfFailure
action to perform in case of failure
Definition phy-entity.h:86
PhyFieldRxStatus(bool s, WifiPhyRxfailureReason r, PhyRxFailureAction a)
Constructor.
Definition phy-entity.h:106
PhyFieldRxStatus(bool s)
Constructor setting outcome of reception.
Definition phy-entity.h:94
bool isSuccess
outcome (true if success) of the reception
Definition phy-entity.h:84
RxSignalInfo structure containing info on the received signal.
Definition wifi-types.h:79
A struct for both SNR and PER.
WifiSpectrumBandInfo structure containing info about a spectrum band.
Declaration of ns3::WifiPpdu class and ns3::WifiConstPsduMap.