From ea745ff59e760dcc0fc4ac929e2ae8979595c8aa Mon Sep 17 00:00:00 2001 From: Vivek Jain Date: Sat, 19 Jun 2021 17:14:27 +0000 Subject: [PATCH] tcp: fix BBR doxygen warnings --- src/internet/model/tcp-bbr.h | 17 ++-- src/internet/model/windowed-filter.h | 115 +++++++++++++++++++++------ src/internet/test/tcp-bbr-test.cc | 37 +++++++-- 3 files changed, 132 insertions(+), 37 deletions(-) diff --git a/src/internet/model/tcp-bbr.h b/src/internet/model/tcp-bbr.h index fee091312..827fabc9b 100644 --- a/src/internet/model/tcp-bbr.h +++ b/src/internet/model/tcp-bbr.h @@ -63,20 +63,22 @@ public: */ TcpBbr (const TcpBbr &sock); - /* BBR has the following modes for deciding how fast to send: */ + /** + * \brief BBR has the following 4 modes for deciding how fast to send: + */ typedef enum { - BBR_STARTUP, /* ramp up sending rate rapidly to fill pipe */ - BBR_DRAIN, /* drain any queue created during startup */ - BBR_PROBE_BW, /* discover, share bw: pace around estimated bw */ - BBR_PROBE_RTT, /* cut inflight to min to probe min_rtt */ + BBR_STARTUP, /**< Ramp up sending rate rapidly to fill pipe */ + BBR_DRAIN, /**< Drain any queue created during startup */ + BBR_PROBE_BW, /**< Discover, share bw: pace around estimated bw */ + BBR_PROBE_RTT, /**< Cut inflight to min to probe min_rtt */ } BbrMode_t; typedef WindowedFilter, uint32_t, uint32_t> - MaxBandwidthFilter_t; + MaxBandwidthFilter_t; //!< Definition of max bandwidth filter. /** * \brief Literal names of BBR mode for use in log messages @@ -139,6 +141,7 @@ protected: /** * \brief This method handles the steps related to the ProbeRTT state * \param tcb the socket state. + * \param rs rate sample. */ void CheckProbeRTT (Ptr tcb, const TcpRateOps::TcpRateSample &rs); @@ -202,6 +205,7 @@ protected: * \brief Estimates the target value for congestion window * \param tcb the socket state. * \param gain cwnd gain. + * \return returns congestion window based on max bandwidth and min RTT. */ uint32_t InFlight (Ptr tcb, double gain); @@ -239,6 +243,7 @@ protected: * \brief Modulates congestion window in CA_RECOVERY. * \param tcb the socket state. * \param rs rate sample. + * \return true if congestion window is updated in CA_RECOVERY. */ bool ModulateCwndForRecovery (Ptr tcb, const TcpRateOps::TcpRateSample &rs); diff --git a/src/internet/model/windowed-filter.h b/src/internet/model/windowed-filter.h index 2b94ec237..b8420ff2f 100644 --- a/src/internet/model/windowed-filter.h +++ b/src/internet/model/windowed-filter.h @@ -65,12 +65,21 @@ #define WINDOWED_FILTER_H_ namespace ns3 { -// Compares two values and returns true if the first is less than or equal -// to the second. +/** + * \brief Compares two values + * \param T type of the measurement that is being filtered. + */ template struct MinFilter { public: + /** + * \brief Compares two values + * + * \param lhs left hand value + * \param rhs right hand value + * \return returns true if the first is less than or equal to the second. + */ bool operator() (const T& lhs, const T& rhs) const { if (rhs == 0 || lhs == 0) @@ -80,12 +89,21 @@ public: return lhs <= rhs; } }; -// Compares two values and returns true if the first is greater than or equal -// to the second. +/** + * \brief Compares two values + * \param T type of the measurement that is being filtered. + */ template struct MaxFilter { public: + /** + * \brief Compares two values + * + * \param lhs left hand value + * \param rhs right hand value + * \return returns true if the first is greater than or equal to the second. + */ bool operator() (const T& lhs, const T& rhs) const { if (rhs == 0 || lhs == 0) @@ -95,30 +113,40 @@ public: return lhs >= rhs; } }; -// Use the following to construct a windowed filter object of type T. -// For example, a min filter using QuicTime as the time type: -// WindowedFilter, QuicTime, QuicTime::Delta> ObjectName; -// A max filter using 64-bit integers as the time type: -// WindowedFilter, uint64_t, int64_t> ObjectName; -// Specifically, this template takes four arguments: -// 1. T -- type of the measurement that is being filtered. -// 2. Compare -- MinFilter or MaxFilter, depending on the type of filter -// desired. -// 3. TimeT -- the type used to represent timestamps. -// 4. TimeDeltaT -- the type used to represent continuous time intervals between -// two timestamps. Has to be the type of (a - b) if both |a| and |b| are -// of type TimeT. +/** + * \brief Construct a windowed filter + * + * Use the following to construct a windowed filter object of type T. + * For example, a min filter using QuicTime as the time type: + * WindowedFilter, QuicTime, QuicTime::Delta> ObjectName; + * max filter using 64-bit integers as the time type: + * WindowedFilter, uint64_t, int64_t> ObjectName; + * + * \param T -- type of the measurement that is being filtered. + * \param Compare -- MinFilter or MaxFilter, depending on the type of filter desired. + * \param TimeT -- the type used to represent timestamps. + * \param TimeDeltaT -- the type used to represent continuous time intervals between + * two timestamps. Has to be the type of (a - b) if both |a| and |b| are + * of type TimeT. + */ template class WindowedFilter { public: + /** + * \brief contructor + */ WindowedFilter () { } - // |windowLength| is the period after which a best estimate expires. - // |zeroValue| is used as the uninitialized value for objects of T. - // Importantly, |zeroValue| should be an invalid value for a true sample. + /** + * \brief contructor + * \param windowLength is the period after which a best estimate expires. + * \param zeroValue is used as the uninitialized value for objects of T. Importantly, + * zeroValue should be an invalid value for a true sample. + * \param zeroTime is the time of instance record time. + */ WindowedFilter (TimeDeltaT windowLength, T zeroValue, TimeT zeroTime) : m_windowLength (windowLength), m_zeroValue (zeroValue), @@ -128,13 +156,21 @@ public: Sample (m_zeroValue, zeroTime), Sample (m_zeroValue, zeroTime) } {} - // Changes the window length. Does not update any current samples. + /** + * \brief Changes the window length. Does not update any current samples. + * \param windowLength is the period after which a best estimate expires. + */ void SetWindowLength (TimeDeltaT windowLength) { m_windowLength = windowLength; } - // Updates best estimates with |sample|, and expires and updates best - // estimates as necessary. + /** + * \brief Updates best estimates with |sample|, and expires and updates best + * estimates as necessary. + * + * \param new_sample update new sample. + * \param new_time record time of the new sample. + */ void Update (T new_sample, TimeT new_time) { // Reset all estimates if they have not yet been initialized, if new sample @@ -191,35 +227,62 @@ public: } } - // Resets all estimates to new sample. + /** + * \brief Resets all estimates to new sample. + * \param new_sample update new sample. + * \param new_time record time of the new sample. + */ void Reset (T new_sample, TimeT new_time) { m_samples[0] = m_samples[1] = m_samples[2] = Sample (new_sample, new_time); } + /** + * \brief Returns Max/Min value so far among the windowed samples. + * \return returns Best (max/min) value so far among the windowed samples. + */ T GetBest () const { return m_samples[0].sample; } + /** + * \brief Returns second Max/Min value so far among the windowed samples. + * \return returns second Best (max/min) value so far among the windowed samples. + */ T GetSecondBest () const { return m_samples[1].sample; } + /** + * \brief Returns third Max/Min value so far among the windowed samples. + * \return returns third Best (max/min) value so far among the windowed samples. + */ T GetThirdBest () const { return m_samples[2].sample; } + /** + * \brief sample. + */ struct Sample { - T sample; - TimeT time; + T sample; //!< recorded sample. + TimeT time; //!< time when the sample was recorded. + /** + * \brief constructor + */ Sample () { } + /** + * \brief constructor + * \param init_sample value of sample. + * \param init_time time when the sample was recorded.. + */ Sample (T init_sample, TimeT init_time) : sample (init_sample), time (init_time) diff --git a/src/internet/test/tcp-bbr-test.cc b/src/internet/test/tcp-bbr-test.cc index e9e78d457..c68221656 100644 --- a/src/internet/test/tcp-bbr-test.cc +++ b/src/internet/test/tcp-bbr-test.cc @@ -37,12 +37,20 @@ NS_LOG_COMPONENT_DEFINE ("TcpBbrTestSuite"); class TcpBbrPacingEnableTest : public TestCase { public: + /** + * \brief constructor + * \param pacing pacing configuration + * \param name description of the test + */ TcpBbrPacingEnableTest (bool pacing, const std::string &name); private: virtual void DoRun (void); + /** + * \brief Execute the test. + */ void ExecuteTest (void); - bool m_pacing; + bool m_pacing; //!< Initial pacing configuration. }; TcpBbrPacingEnableTest::TcpBbrPacingEnableTest (bool pacing, const std::string &name) @@ -78,13 +86,22 @@ TcpBbrPacingEnableTest::ExecuteTest () class TcpBbrCheckGainValuesTest : public TestCase { public: + /** + * \brief constructor + * \param state BBR state/mode under test + * \param highGain value of pacing and cwnd gain + * \param name description of the test + */ TcpBbrCheckGainValuesTest (TcpBbr::BbrMode_t state, double highGain, const std::string &name); private: virtual void DoRun (void); + /** + * \brief Execute the test. + */ void ExecuteTest (void); - TcpBbr::BbrMode_t m_mode; - double m_highGain; + TcpBbr::BbrMode_t m_mode; //!< BBR mode under test + double m_highGain; //!< Value of BBR high gain }; TcpBbrCheckGainValuesTest::TcpBbrCheckGainValuesTest (TcpBbr::BbrMode_t state, @@ -154,9 +171,18 @@ TcpBbrCheckGainValuesTest::ExecuteTest () NS_TEST_ASSERT_MSG_EQ (actualCwndGain, desiredCwndGain, "BBR has not updated into desired cwnd gain"); } -static class TcpBbrTestSuite : public TestSuite +/** + * \ingroup internet-test + * \ingroup tests + * + * \brief TCP BBR TestSuite + */ +class TcpBbrTestSuite : public TestSuite { public: + /** + * \brief constructor + */ TcpBbrTestSuite () : TestSuite ("tcp-bbr-test", UNIT) { AddTestCase (new TcpBbrPacingEnableTest (true, "BBR must keep pacing feature on"), TestCase::QUICK); @@ -171,6 +197,7 @@ public: AddTestCase (new TcpBbrCheckGainValuesTest (TcpBbr::BBR_PROBE_RTT, 4, "BBR should enter to BBR_PROBE_RTT phase and set cwnd and pacing gain accordingly"), TestCase::QUICK); } -} g_tcpBbrTest; +}; +static TcpBbrTestSuite g_tcpBbrTest; //!< static variable for test initialization }