A Discrete-Event Network Simulator
API
Loading...
Searching...
No Matches
tcp-rate-ops.h
Go to the documentation of this file.
1/*
2 * Copyright (c) 2018 Natale Patriciello <natale.patriciello@gmail.com>
3 *
4 * SPDX-License-Identifier: GPL-2.0-only
5 *
6 */
7#ifndef TCP_RATE_OPS_H
8#define TCP_RATE_OPS_H
9
10#include "tcp-tx-item.h"
11
12#include "ns3/data-rate.h"
13#include "ns3/object.h"
14#include "ns3/traced-callback.h"
15#include "ns3/traced-value.h"
16
17namespace ns3
18{
19
20/**
21 * \brief Interface for all operations that involve a Rate monitoring for TCP.
22 *
23 * The interface is meant to take information to generate rate information
24 * valid for congestion avoidance algorithm such as BBR.
25 *
26 * Please take a look to the TcpRateLinux class for an example.
27 */
28class TcpRateOps : public Object
29{
30 public:
31 struct TcpRateSample;
32 struct TcpRateConnection;
33
34 /**
35 * Get the type ID.
36 * \brief Get the type ID.
37 * \return the object TypeId
38 */
39 static TypeId GetTypeId();
40 /**
41 * \brief Put the rate information inside the sent skb
42 *
43 * Snapshot the current delivery information in the skb, to generate
44 * a rate sample later when the skb is (s)acked in SkbDelivered ().
45 *
46 * \param skb The SKB sent
47 * \param isStartOfTransmission true if this is a start of transmission
48 * (i.e., in_flight == 0)
49 */
50 virtual void SkbSent(TcpTxItem* skb, bool isStartOfTransmission) = 0;
51
52 /**
53 * \brief Update the Rate information after an item is received
54 *
55 * When an skb is sacked or acked, we fill in the rate sample with the (prior)
56 * delivery information when the skb was last transmitted.
57 *
58 * If an ACK (s)acks multiple skbs (e.g., stretched-acks), this function is
59 * called multiple times. We favor the information from the most recently
60 * sent skb, i.e., the skb with the highest prior_delivered count.
61 *
62 * \param skb The SKB delivered ((s)ACKed)
63 */
64 virtual void SkbDelivered(TcpTxItem* skb) = 0;
65
66 /**
67 * \brief If a gap is detected between sends, it means we are app-limited.
68 * TODO What the Linux kernel is setting in tp->app_limited?
69 * https://elixir.bootlin.com/linux/latest/source/net/ipv4/tcp_rate.c#L177
70 *
71 * \param cWnd Congestion Window
72 * \param in_flight In Flight size (in bytes)
73 * \param segmentSize Segment size
74 * \param tailSeq Tail Sequence
75 * \param nextTx NextTx
76 * \param lostOut Number of lost bytes
77 * \param retransOut Number of retransmitted bytes
78 */
79 virtual void CalculateAppLimited(uint32_t cWnd,
80 uint32_t in_flight,
82 const SequenceNumber32& tailSeq,
83 const SequenceNumber32& nextTx,
84 const uint32_t lostOut,
85 const uint32_t retransOut) = 0;
86
87 /**
88 *
89 * \brief Generate a TcpRateSample to feed a congestion avoidance algorithm.
90 *
91 * This function will be called after an ACK (or a SACK) is received. The
92 * (S)ACK carries some implicit information, such as how many segments have been
93 * lost or delivered. These values will be this function input.
94 *
95 * \param delivered number of delivered segments (e.g., receiving a cumulative
96 * ACK means having more than 1 segment delivered) relative to the most recent
97 * (S)ACK received
98 * \param lost number of segments that we detected as lost after the reception
99 * of the most recent (S)ACK
100 * \param priorInFlight number of segments previously considered in flight
101 * \param is_sack_reneg Is SACK reneged?
102 * \param minRtt Minimum RTT so far
103 * \return The TcpRateSample that will be used for CA
104 */
105 virtual const TcpRateSample& GenerateSample(uint32_t delivered,
106 uint32_t lost,
107 bool is_sack_reneg,
108 uint32_t priorInFlight,
109 const Time& minRtt) = 0;
110
111 /**
112 * \return The information about the rate connection
113 *
114 */
116
117 /**
118 * \brief Rate Sample structure
119 *
120 * A rate sample measures the number of (original/retransmitted) data
121 * packets delivered "delivered" over an interval of time "interval_us".
122 * The tcp_rate code fills in the rate sample, and congestion
123 * control modules that define a cong_control function to run at the end
124 * of ACK processing can optionally chose to consult this sample when
125 * setting cwnd and pacing rate.
126 * A sample is invalid if "delivered" or "interval_us" is negative.
127 */
129 {
130 DataRate m_deliveryRate{DataRate("0bps")}; //!< The delivery rate sample
131 bool m_isAppLimited{false}; //!< Indicates whether the rate sample is application-limited
132 Time m_interval{Seconds(0.0)}; //!< The length of the sampling interval
134 0}; //!< The amount of data marked as delivered over the sampling interval
135 uint32_t m_priorDelivered{0}; //!< The delivered count of the most recent packet delivered
136 Time m_priorTime{Seconds(0.0)}; //!< The delivered time of the most recent packet delivered
138 Seconds(0.0)}; //!< Send time interval calculated from the most recent packet delivered
140 Seconds(0.0)}; //!< ACK time interval calculated from the most recent packet delivered
142 0}; //!< The amount of data marked as lost from the most recent ack received
143 uint32_t m_priorInFlight{0}; //!< The value if bytes in flight prior to last received ack
144 uint32_t m_ackedSacked{0}; //!< The amount of data acked and sacked in the last received ack
145
146 /**
147 * \brief Is the sample valid?
148 * \return true if the sample is valid, false otherwise.
149 */
150 bool IsValid() const
151 {
152 return (m_priorTime != Seconds(0.0) || m_interval != Seconds(0.0));
153 }
154 };
155
156 /**
157 * \brief Information about the connection rate
158 *
159 * In this struct, the values are for the entire connection, and not just
160 * for an interval of time
161 */
163 {
164 uint64_t m_delivered{0}; //!< The total amount of data in bytes delivered so far
165 Time m_deliveredTime{Seconds(0)}; //!< Simulator time when m_delivered was last updated
167 Seconds(0)}; //!< The send time of the packet that was most recently marked as delivered
169 0}; //!< The index of the last transmitted packet marked as application-limited
170 uint32_t m_txItemDelivered{0}; //!< The value of delivered when the acked item was sent
172 0}; //!< The amount of data delivered considered to calculate delivery rate.
174 Seconds(0)}; //!< The value of interval considered to calculate delivery rate.
175 bool m_rateAppLimited{false}; //!< Was sample was taken when data is app limited?
176 };
177};
178
179/**
180 * \brief Linux management and generation of Rate information for TCP
181 *
182 * This class is inspired by what Linux is performing in tcp_rate.c
183 */
185{
186 public:
187 /**
188 * Get the type ID.
189 * \brief Get the type ID.
190 * \return the object TypeId
191 */
192 static TypeId GetTypeId();
193
194 ~TcpRateLinux() override
195 {
196 }
197
198 void SkbSent(TcpTxItem* skb, bool isStartOfTransmission) override;
199 void SkbDelivered(TcpTxItem* skb) override;
201 uint32_t in_flight,
203 const SequenceNumber32& tailSeq,
204 const SequenceNumber32& nextTx,
205 const uint32_t lostOut,
206 const uint32_t retransOut) override;
207 const TcpRateSample& GenerateSample(uint32_t delivered,
208 uint32_t lost,
209 bool is_sack_reneg,
210 uint32_t priorInFlight,
211 const Time& minRtt) override;
212
214 {
215 return m_rate;
216 }
217
218 /**
219 * TracedCallback signature for tcp rate update events.
220 *
221 * The callback will be fired each time the rate is updated.
222 *
223 * \param [in] rate The rate information.
224 */
225 typedef void (*TcpRateUpdated)(const TcpRateConnection& rate);
226
227 /**
228 * TracedCallback signature for tcp rate sample update events.
229 *
230 * The callback will be fired each time the rate sample is updated.
231 *
232 * \param [in] sample The rate sample that will be passed to congestion control
233 * algorithms.
234 */
235 typedef void (*TcpRateSampleUpdated)(const TcpRateSample& sample);
236
237 private:
238 // Rate sample related variables
239 TcpRateConnection m_rate; //!< Rate information
240 TcpRateSample m_rateSample; //!< Rate sample (continuously updated)
241
244};
245
246/**
247 * \brief Output operator.
248 * \param os The output stream.
249 * \param sample the TcpRateLinux::TcpRateSample to print.
250 * \returns The output stream.
251 */
252std::ostream& operator<<(std::ostream& os, const TcpRateOps::TcpRateSample& sample);
253
254/**
255 * \brief Output operator.
256 * \param os The output stream.
257 * \param rate the TcpRateLinux::TcpRateConnection to print.
258 * \returns The output stream.
259 */
260std::ostream& operator<<(std::ostream& os, const TcpRateOps::TcpRateConnection& rate);
261
262/**
263 * Comparison operator
264 * \param lhs left operand
265 * \param rhs right operand
266 * \return true if the operands are equal
267 */
269
270/**
271 * Comparison operator
272 * \param lhs left operand
273 * \param rhs right operand
274 * \return true if the operands are equal
275 */
278
279} // namespace ns3
280
281#endif /* TCP_RATE_OPS_H */
Class for representing data rates.
Definition data-rate.h:78
A base class which provides memory management and object aggregation.
Definition object.h:78
Linux management and generation of Rate information for TCP.
TracedCallback< const TcpRateConnection & > m_rateTrace
Rate trace.
void(* TcpRateSampleUpdated)(const TcpRateSample &sample)
TracedCallback signature for tcp rate sample update events.
void SkbDelivered(TcpTxItem *skb) override
Update the Rate information after an item is received.
const TcpRateConnection & GetConnectionRate() override
TracedCallback< const TcpRateSample & > m_rateSampleTrace
Rate Sample trace.
TcpRateSample m_rateSample
Rate sample (continuously updated)
void(* TcpRateUpdated)(const TcpRateConnection &rate)
TracedCallback signature for tcp rate update events.
TcpRateConnection m_rate
Rate information.
void SkbSent(TcpTxItem *skb, bool isStartOfTransmission) override
Put the rate information inside the sent skb.
const TcpRateSample & GenerateSample(uint32_t delivered, uint32_t lost, bool is_sack_reneg, uint32_t priorInFlight, const Time &minRtt) override
Generate a TcpRateSample to feed a congestion avoidance algorithm.
static TypeId GetTypeId()
Get the type ID.
~TcpRateLinux() override
void CalculateAppLimited(uint32_t cWnd, uint32_t in_flight, uint32_t segmentSize, const SequenceNumber32 &tailSeq, const SequenceNumber32 &nextTx, const uint32_t lostOut, const uint32_t retransOut) override
If a gap is detected between sends, it means we are app-limited.
Interface for all operations that involve a Rate monitoring for TCP.
static TypeId GetTypeId()
Get the type ID.
virtual const TcpRateSample & GenerateSample(uint32_t delivered, uint32_t lost, bool is_sack_reneg, uint32_t priorInFlight, const Time &minRtt)=0
Generate a TcpRateSample to feed a congestion avoidance algorithm.
virtual void SkbSent(TcpTxItem *skb, bool isStartOfTransmission)=0
Put the rate information inside the sent skb.
virtual void CalculateAppLimited(uint32_t cWnd, uint32_t in_flight, uint32_t segmentSize, const SequenceNumber32 &tailSeq, const SequenceNumber32 &nextTx, const uint32_t lostOut, const uint32_t retransOut)=0
If a gap is detected between sends, it means we are app-limited.
virtual const TcpRateConnection & GetConnectionRate()=0
virtual void SkbDelivered(TcpTxItem *skb)=0
Update the Rate information after an item is received.
Item that encloses the application packet and some flags for it.
Definition tcp-tx-item.h:22
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
uint32_t segmentSize
Time Seconds(double value)
Construct a Time in the indicated unit.
Definition nstime.h:1308
Every class exported by the ns3 library is enclosed in the ns3 namespace.
bool operator==(const EventId &a, const EventId &b)
Definition event-id.h:155
std::ostream & operator<<(std::ostream &os, const Angles &a)
Definition angles.cc:148
Information about the connection rate.
uint32_t m_txItemDelivered
The value of delivered when the acked item was sent.
Time m_deliveredTime
Simulator time when m_delivered was last updated.
int32_t m_rateDelivered
The amount of data delivered considered to calculate delivery rate.
uint64_t m_delivered
The total amount of data in bytes delivered so far.
uint32_t m_appLimited
The index of the last transmitted packet marked as application-limited.
bool m_rateAppLimited
Was sample was taken when data is app limited?
Time m_firstSentTime
The send time of the packet that was most recently marked as delivered.
Time m_rateInterval
The value of interval considered to calculate delivery rate.
Rate Sample structure.
Time m_ackElapsed
ACK time interval calculated from the most recent packet delivered.
bool IsValid() const
Is the sample valid?
bool m_isAppLimited
Indicates whether the rate sample is application-limited.
uint32_t m_ackedSacked
The amount of data acked and sacked in the last received ack.
DataRate m_deliveryRate
The delivery rate sample.
uint32_t m_priorInFlight
The value if bytes in flight prior to last received ack.
Time m_sendElapsed
Send time interval calculated from the most recent packet delivered.
Time m_interval
The length of the sampling interval.
uint32_t m_priorDelivered
The delivered count of the most recent packet delivered.
int32_t m_delivered
The amount of data marked as delivered over the sampling interval.
uint32_t m_bytesLoss
The amount of data marked as lost from the most recent ack received.
Time m_priorTime
The delivered time of the most recent packet delivered.