A Discrete-Event Network Simulator
API
Loading...
Searching...
No Matches
minstrel-wifi-manager.h
Go to the documentation of this file.
1/*
2 * Copyright (c) 2009 Duy Nguyen
3 *
4 * SPDX-License-Identifier: GPL-2.0-only
5 *
6 * Authors: Duy Nguyen <duy@soe.ucsc.edu>
7 * Matías Richart <mrichart@fing.edu.uy>
8 */
9
10#ifndef MINSTREL_WIFI_MANAGER_H
11#define MINSTREL_WIFI_MANAGER_H
12
13#include "ns3/traced-value.h"
14#include "ns3/wifi-remote-station-manager.h"
15
16#include <fstream>
17#include <map>
18
19namespace ns3
20{
21
22class UniformRandomVariable;
23
24/**
25 * A struct to contain all information related to a data rate
26 */
28{
29 /**
30 * Perfect transmission time calculation, or frame calculation
31 * Given a bit rate and a packet length n bytes
32 */
34
35 uint32_t retryCount; ///< retry limit
36 uint32_t adjustedRetryCount; ///< adjust the retry limit for this rate
37 uint32_t numRateAttempt; ///< how many number of attempts so far
38 uint32_t numRateSuccess; ///< number of successful packets
39 uint32_t prob; ///< (# packets success)/(# total packets)
40 /**
41 * EWMA calculation
42 * ewma_prob =[prob *(100 - ewma_level) + (ewma_prob_old * ewma_level)]/100
43 */
45 uint32_t throughput; ///< throughput of a rate in bps
46
47 uint32_t prevNumRateAttempt; //!< Number of transmission attempts with previous rate.
48 uint32_t prevNumRateSuccess; //!< Number of successful frames transmitted with previous rate.
49 uint64_t successHist; //!< Aggregate of all transmission successes.
50 uint64_t attemptHist; //!< Aggregate of all transmission attempts.
51
52 uint8_t numSamplesSkipped; //!< number of samples skipped
53 int sampleLimit; //!< sample limit
54};
55
56/**
57 * Data structure for a Minstrel Rate table
58 * A vector of a struct RateInfo
59 */
60typedef std::vector<RateInfo> MinstrelRate;
61/**
62 * Data structure for a Sample Rate table
63 * A vector of a vector uint8_t
64 */
65typedef std::vector<std::vector<uint8_t>> SampleRate;
66
67/**
68 * \brief hold per-remote-station state for Minstrel Wifi manager.
69 *
70 * This struct extends from WifiRemoteStation struct to hold additional
71 * information required by the Minstrel Wifi manager
72 */
74{
75 Time m_nextStatsUpdate; ///< 10 times every second
76
77 /**
78 * To keep track of the current position in the our random sample table
79 * going row by row from 1st column until the 10th column(Minstrel defines 10)
80 * then we wrap back to the row 1 column 1.
81 * note: there are many other ways to do this.
82 */
83 uint8_t m_col; ///< column index
84 uint8_t m_index; ///< vector index
85 uint16_t m_maxTpRate; ///< the current throughput rate in bps
86 uint16_t m_maxTpRate2; ///< second highest throughput rate in bps
87 uint16_t m_maxProbRate; ///< rate with highest probability of success in bps
88 uint8_t m_nModes; ///< number of modes supported
89 int m_totalPacketsCount; ///< total number of packets as of now
90 int m_samplePacketsCount; ///< how many packets we have sample so far
91 int m_numSamplesDeferred; ///< number samples deferred
92 bool m_isSampling; ///< a flag to indicate we are currently sampling
93 uint16_t m_sampleRate; ///< current sample rate in bps
94 bool m_sampleDeferred; ///< a flag to indicate sample rate is on the second stage
95 uint32_t m_shortRetry; ///< short retries such as control packets
96 uint32_t m_longRetry; ///< long retries such as data packets
97 uint32_t m_retry; ///< total retries short + long
98 uint16_t m_txrate; ///< current transmit rate in bps
99 bool m_initialized; ///< for initializing tables
100 MinstrelRate m_minstrelTable; ///< minstrel table
101 SampleRate m_sampleTable; ///< sample table
102 std::ofstream m_statsFile; ///< stats file
103};
104
105/**
106 * \brief Implementation of Minstrel Rate Control Algorithm
107 * \ingroup wifi
108 *
109 * Minstrel is a rate control algorithm implemented in MadWifi and Linux.
110 * The basic principle is to probe the environment and adapt the rate
111 * based on statistics collected on the probability of successful
112 * transmission. The algorithm adapts the rate to the highest rate
113 * that it considers successful, and spends a fraction of its time
114 * doing 'look around' by trying other rates.
115 *
116 * Minstrel is appropriate for non-HT configurations; for HT (i.e. 802.11n
117 * or higher), users should use MinstrelHtWifiManager instead.
118 * Minstrel will error exit if the user tries to configure it with a
119 * Wi-Fi MAC that supports 802.11n or higher.
120 *
121 * Some notes on this implementation follow. The implementation has
122 * been adapted to bring it closer to the Linux implementation.
123 * For each rate, a new parameter samplesSkipped is added. This parameter
124 * is intended to solve an issue regarding the sampling of low rates when
125 * a high rate is working well, which leads to outdated statistics.
126 * This change makes throughput a bit lower in simple, stable scenarios,
127 * but may help in dynamic scenarios to react faster and more accurately
128 * to changes.
129 *
130 * Related to the previous, the logic for deciding when to sample random
131 * rates is as follows. When a sample rate is deferred to the second MRR
132 * chain stage, a new parameter (numSamplesDeferred) is increased. This
133 * parameters is used (jointly with sampleCount) to compare current
134 * sample count with the lookaround rate.
135 *
136 * Also related with sampling, another parameter sampleLimit is added.
137 * This parameter limits the number of times a very low or very high
138 * probability rate is sampled, avoiding to try a poorly working sample
139 * rate too often.
140 *
141 * When updating the EWMA probability of a rate for the first time, it does
142 * not apply EWMA but instead assigns the entire probability.
143 * Since the EWMA probability is initialized to zero, this generates
144 * a more accurate EWMA.
145 */
147{
148 public:
149 /**
150 * \brief Get the type ID.
151 * \return the object TypeId
152 */
153 static TypeId GetTypeId();
155 ~MinstrelWifiManager() override;
156
157 void SetupPhy(const Ptr<WifiPhy> phy) override;
158 void SetupMac(const Ptr<WifiMac> mac) override;
159 int64_t AssignStreams(int64_t stream) override;
160
161 /**
162 * Update the rate.
163 *
164 * \param station the station object
165 */
167
168 /**
169 * Update the Minstrel Table.
170 *
171 * \param station the station object
172 */
174
175 /**
176 * Find a rate to use from Minstrel Table.
177 *
178 * \param station the station object
179 * \returns the rate in bps
180 */
181 uint16_t FindRate(MinstrelWifiRemoteStation* station);
182
183 /**
184 * Get data transmit vector.
185 *
186 * \param station the station object
187 * \returns WifiTxVector
188 */
190
191 /**
192 * Get RTS transmit vector.
193 *
194 * \param station the station object
195 * \returns WifiTxVector
196 */
198
199 /**
200 * Get the number of retries.
201 *
202 * \param station the station object
203 * \returns the number of retries
204 */
206
207 /**
208 * Update packet counters.
209 *
210 * \param station the station object
211 */
213
214 /**
215 * Update the number of retries and reset accordingly.
216 *
217 * \param station the station object
218 */
220
221 /**
222 * Check for initializations.
223 *
224 * \param station the station object
225 */
227
228 /**
229 * Initialize Sample Table.
230 *
231 * \param station the station object
232 */
234
235 private:
236 void DoInitialize() override;
237 WifiRemoteStation* DoCreateStation() const override;
238 void DoReportRxOk(WifiRemoteStation* station, double rxSnr, WifiMode txMode) override;
239 void DoReportRtsFailed(WifiRemoteStation* station) override;
240 void DoReportDataFailed(WifiRemoteStation* station) override;
241 void DoReportRtsOk(WifiRemoteStation* station,
242 double ctsSnr,
243 WifiMode ctsMode,
244 double rtsSnr) override;
245 void DoReportDataOk(WifiRemoteStation* station,
246 double ackSnr,
247 WifiMode ackMode,
248 double dataSnr,
249 MHz_u dataChannelWidth,
250 uint8_t dataNss) override;
251 void DoReportFinalRtsFailed(WifiRemoteStation* station) override;
252 void DoReportFinalDataFailed(WifiRemoteStation* station) override;
253 WifiTxVector DoGetDataTxVector(WifiRemoteStation* station, MHz_u allowedWidth) override;
255
257 Ptr<const Packet> packet,
258 bool normally) override;
259
260 /**
261 * Estimate the TxTime of a packet with a given mode.
262 *
263 * \param mode Wi-Fi mode
264 * \returns the transmission time
265 */
266 Time GetCalcTxTime(WifiMode mode) const;
267 /**
268 * Add transmission time for the given mode to an internal list.
269 *
270 * \param mode Wi-Fi mode
271 * \param t transmission time
272 */
273 void AddCalcTxTime(WifiMode mode, Time t);
274
275 /**
276 * Initialize Minstrel Table.
277 *
278 * \param station the station object
279 */
280 void RateInit(MinstrelWifiRemoteStation* station);
281
282 /**
283 * Get the next sample from Sample Table.
284 *
285 * \param station the station object
286 * \returns the next sample
287 */
288 uint16_t GetNextSample(MinstrelWifiRemoteStation* station);
289
290 /**
291 * Estimate the time to transmit the given packet with the given number of retries.
292 * This function is "roughly" the function "calc_usecs_unicast_packet" in minstrel.c
293 * in the madwifi implementation.
294 *
295 * The basic idea is that, we try to estimate the "average" time used to transmit the
296 * packet for the given number of retries while also accounting for the 802.11 congestion
297 * window change. The original code in the madwifi seems to estimate the number of backoff
298 * slots as the half of the current CW size.
299 *
300 * There are four main parts:
301 * - wait for DIFS (sense idle channel)
302 * - Ack timeouts
303 * - Data transmission
304 * - backoffs according to CW
305 *
306 * \param dataTransmissionTime the data transmission time
307 * \param shortRetries short retries
308 * \param longRetries long retries
309 * \returns the unicast packet time
310 */
311 Time CalculateTimeUnicastPacket(Time dataTransmissionTime,
312 uint32_t shortRetries,
313 uint32_t longRetries);
314
315 /**
316 * Print Sample Table.
317 *
318 * \param station the station object
319 */
320 void PrintSampleTable(MinstrelWifiRemoteStation* station) const;
321
322 /**
323 * Print Minstrel Table.
324 *
325 * \param station the station object
326 */
328
329 /**
330 * typedef for a vector of a pair of Time, WifiMode.
331 * Essentially a map from WifiMode to its corresponding transmission time
332 * to transmit a reference packet.
333 */
334 typedef std::map<WifiMode, Time> TxTime;
335
336 TxTime m_calcTxTime; ///< to hold all the calculated TxTime for all modes
337 Time m_updateStats; ///< how frequent do we calculate the stats
338 uint8_t m_lookAroundRate; ///< the % to try other rates than our current rate
339 uint8_t m_ewmaLevel; ///< exponential weighted moving average
340 uint8_t m_sampleCol; ///< number of sample columns
341 uint32_t m_pktLen; ///< packet length used to calculate mode TxTime
342 bool m_printStats; ///< whether statistics table should be printed.
343 bool m_printSamples; ///< whether samples table should be printed.
344
345 /// Provides uniform random variables.
347
348 TracedValue<uint64_t> m_currentRate; //!< Trace rate changes
349};
350
351} // namespace ns3
352
353#endif /* MINSTREL_WIFI_MANAGER_H */
Implementation of Minstrel Rate Control Algorithm.
WifiRemoteStation * DoCreateStation() const override
WifiTxVector DoGetRtsTxVector(WifiRemoteStation *station) override
WifiTxVector DoGetDataTxVector(WifiRemoteStation *station, MHz_u allowedWidth) override
uint8_t m_lookAroundRate
the % to try other rates than our current rate
void DoReportDataOk(WifiRemoteStation *station, double ackSnr, WifiMode ackMode, double dataSnr, MHz_u dataChannelWidth, uint8_t dataNss) override
This method is a pure virtual method that must be implemented by the sub-class.
void PrintSampleTable(MinstrelWifiRemoteStation *station) const
Print Sample Table.
void AddCalcTxTime(WifiMode mode, Time t)
Add transmission time for the given mode to an internal list.
void RateInit(MinstrelWifiRemoteStation *station)
Initialize Minstrel Table.
uint32_t m_pktLen
packet length used to calculate mode TxTime
void DoReportFinalDataFailed(WifiRemoteStation *station) override
This method is a pure virtual method that must be implemented by the sub-class.
void DoInitialize() override
Initialize() implementation.
void UpdateStats(MinstrelWifiRemoteStation *station)
Update the Minstrel Table.
void CheckInit(MinstrelWifiRemoteStation *station)
Check for initializations.
static TypeId GetTypeId()
Get the type ID.
Ptr< UniformRandomVariable > m_uniformRandomVariable
Provides uniform random variables.
TxTime m_calcTxTime
to hold all the calculated TxTime for all modes
bool m_printSamples
whether samples table should be printed.
void DoReportDataFailed(WifiRemoteStation *station) override
This method is a pure virtual method that must be implemented by the sub-class.
bool m_printStats
whether statistics table should be printed.
WifiTxVector GetRtsTxVector(MinstrelWifiRemoteStation *station)
Get RTS transmit vector.
uint8_t m_sampleCol
number of sample columns
void DoReportFinalRtsFailed(WifiRemoteStation *station) override
This method is a pure virtual method that must be implemented by the sub-class.
void SetupMac(const Ptr< WifiMac > mac) override
Set up MAC associated with this device since it is the object that knows the full set of timing param...
uint16_t FindRate(MinstrelWifiRemoteStation *station)
Find a rate to use from Minstrel Table.
Time GetCalcTxTime(WifiMode mode) const
Estimate the TxTime of a packet with a given mode.
Time CalculateTimeUnicastPacket(Time dataTransmissionTime, uint32_t shortRetries, uint32_t longRetries)
Estimate the time to transmit the given packet with the given number of retries.
void DoReportRtsOk(WifiRemoteStation *station, double ctsSnr, WifiMode ctsMode, double rtsSnr) override
This method is a pure virtual method that must be implemented by the sub-class.
void InitSampleTable(MinstrelWifiRemoteStation *station)
Initialize Sample Table.
TracedValue< uint64_t > m_currentRate
Trace rate changes.
Time m_updateStats
how frequent do we calculate the stats
bool DoNeedRetransmission(WifiRemoteStation *st, Ptr< const Packet > packet, bool normally) override
std::map< WifiMode, Time > TxTime
typedef for a vector of a pair of Time, WifiMode.
void UpdatePacketCounters(MinstrelWifiRemoteStation *station)
Update packet counters.
void UpdateRate(MinstrelWifiRemoteStation *station)
Update the rate.
void PrintTable(MinstrelWifiRemoteStation *station)
Print Minstrel Table.
uint16_t GetNextSample(MinstrelWifiRemoteStation *station)
Get the next sample from Sample Table.
int64_t AssignStreams(int64_t stream) override
Assign a fixed random variable stream number to the random variables used by this model.
void DoReportRtsFailed(WifiRemoteStation *station) override
This method is a pure virtual method that must be implemented by the sub-class.
void DoReportRxOk(WifiRemoteStation *station, double rxSnr, WifiMode txMode) override
This method is a pure virtual method that must be implemented by the sub-class.
uint8_t m_ewmaLevel
exponential weighted moving average
void SetupPhy(const Ptr< WifiPhy > phy) override
Set up PHY associated with this device since it is the object that knows the full set of transmit rat...
uint32_t CountRetries(MinstrelWifiRemoteStation *station)
Get the number of retries.
void UpdateRetry(MinstrelWifiRemoteStation *station)
Update the number of retries and reset accordingly.
WifiTxVector GetDataTxVector(MinstrelWifiRemoteStation *station)
Get data transmit vector.
Smart pointer class similar to boost::intrusive_ptr.
Simulation virtual time values and global simulation resolution.
Definition nstime.h:94
Trace classes with value semantics.
a unique identifier for an interface.
Definition type-id.h:48
represent a single transmission mode
Definition wifi-mode.h:40
hold a list of per-remote-station state.
This class mimics the TXVECTOR which is to be passed to the PHY in order to define the parameters whi...
Every class exported by the ns3 library is enclosed in the ns3 namespace.
std::vector< RateInfo > MinstrelRate
Data structure for a Minstrel Rate table A vector of a struct RateInfo.
std::vector< std::vector< uint8_t > > SampleRate
Data structure for a Sample Rate table A vector of a vector uint8_t.
hold per-remote-station state for Minstrel Wifi manager.
uint16_t m_maxTpRate2
second highest throughput rate in bps
Time m_nextStatsUpdate
10 times every second
bool m_initialized
for initializing tables
uint16_t m_sampleRate
current sample rate in bps
int m_numSamplesDeferred
number samples deferred
uint16_t m_txrate
current transmit rate in bps
int m_totalPacketsCount
total number of packets as of now
bool m_isSampling
a flag to indicate we are currently sampling
MinstrelRate m_minstrelTable
minstrel table
uint32_t m_shortRetry
short retries such as control packets
uint32_t m_retry
total retries short + long
uint16_t m_maxTpRate
the current throughput rate in bps
bool m_sampleDeferred
a flag to indicate sample rate is on the second stage
uint8_t m_nModes
number of modes supported
int m_samplePacketsCount
how many packets we have sample so far
uint8_t m_col
To keep track of the current position in the our random sample table going row by row from 1st column...
uint32_t m_longRetry
long retries such as data packets
uint16_t m_maxProbRate
rate with highest probability of success in bps
A struct to contain all information related to a data rate.
uint8_t numSamplesSkipped
number of samples skipped
uint32_t ewmaProb
EWMA calculation ewma_prob =[prob *(100 - ewma_level) + (ewma_prob_old * ewma_level)]/100.
uint32_t numRateSuccess
number of successful packets
uint32_t adjustedRetryCount
adjust the retry limit for this rate
uint32_t prevNumRateSuccess
Number of successful frames transmitted with previous rate.
int sampleLimit
sample limit
uint32_t prob
(# packets success)/(# total packets)
uint32_t retryCount
retry limit
Time perfectTxTime
Perfect transmission time calculation, or frame calculation Given a bit rate and a packet length n by...
uint64_t successHist
Aggregate of all transmission successes.
uint32_t throughput
throughput of a rate in bps
uint32_t prevNumRateAttempt
Number of transmission attempts with previous rate.
uint32_t numRateAttempt
how many number of attempts so far
uint64_t attemptHist
Aggregate of all transmission attempts.
hold per-remote-station state.