From 04747b113c1912fe889b124a26813d50c0986ef3 Mon Sep 17 00:00:00 2001
From: Bhaskar Kataria <bhaskar.k7920@gmail.com>
Date: Mon, 1 Jun 2020 23:13:07 +0530
Subject: [PATCH] traffic-control: Update PIE doc with tests for RFC features,
 RELEASE_NOTES and CHANGES.html

---
 CHANGES.html                                |  2 ++
 RELEASE_NOTES                               |  4 ++++
 src/traffic-control/doc/pie.rst             | 20 +++++++++++++-------
 src/traffic-control/model/pie-queue-disc.cc |  6 +++---
 4 files changed, 22 insertions(+), 10 deletions(-)

diff --git a/CHANGES.html b/CHANGES.html
index 56737ac22..e3b421b60 100644
--- a/CHANGES.html
+++ b/CHANGES.html
@@ -55,6 +55,7 @@ us a note on ns-developers mailing list.</p>
 <h2>New API:</h2>
 <ul>
 <li>A new TCP congestion control, <b>TcpLinuxReno</b>, has been added.</li>
+<li>Added, to <b>PIE queue disc</b>, <b>queue delay calculation using timestamp</b> feature (Linux default behavior), <b>cap drop adjustment</b> feature (Section 5.5 of RFC 8033), <b>ECN</b> (Section 5.1 of RFC 8033) and <b>derandomization</b> feature (Section 5.4 of RFC 8033).</li>
 </ul>
 <h2>Changes to existing API:</h2>
 <ul>
@@ -69,6 +70,7 @@ us a note on ns-developers mailing list.</p>
 <ul>
 <li>Support for <b>RIFS</b> has been dropped from wifi. RIFS has been obsoleted by the 802.11 standard and support for it was not implemented according to the standard.</li>
 <li>The behavior of <b>TcpPrrRecovery</b> algorithm was aligned to that of Linux.</b>
+<li> <b>PIE</b> queue disc now uses <b>Timestamp</b> for queue delay calculation as default instead of <b>Dequeue Rate Estimator</b></li>
 </ul>
 
 <hr>
diff --git a/RELEASE_NOTES b/RELEASE_NOTES
index 8f39c298a..5072994d4 100644
--- a/RELEASE_NOTES
+++ b/RELEASE_NOTES
@@ -17,6 +17,10 @@ New user-visible features
 - (build system) Added "--enable-asserts" and "--enable-logs" to waf configure,
    to selectively enable asserts and/or logs in release and optimized builds.
 - (tcp) Added TcpLinuxReno congestion control (aligns with Linux 'reno' congestion control).
+- (traffic-control) Added, to PIE queue disc, queue delay calculation using
+  timestamp feature (Linux default behavior), cap drop adjustment feature
+  (Section 5.5 of RFC 8033), ECN (Section 5.1 of RFC 8033) and derandomization
+  feature (Section 5.4 of RFC 8033).
 
 Bugs fixed
 ----------
diff --git a/src/traffic-control/doc/pie.rst b/src/traffic-control/doc/pie.rst
index 3142f3b52..ec44245b1 100644
--- a/src/traffic-control/doc/pie.rst
+++ b/src/traffic-control/doc/pie.rst
@@ -20,9 +20,7 @@ and consists of 2 files `pie-queue-disc.h` and `pie-queue-disc.cc` defining a Pi
 class. The code was ported to |ns3| by Mohit P. Tahiliani, Shravya K. S. and Smriti Murali
 based on ns-2 code implemented by Preethi Natarajan, Rong Pan, Chiara Piglione, Greg White
 and Takashi Hayakawa. The implementation was aligned with RFC 8033 by Vivek Jain and Mohit
-P. Tahiliani after ns-3.32 release, and additional unit test cases were added for the same
-by Bhaskar Kataria during his GSoC 2020 project.
-
+P. Tahiliani for the ns-3.32 release, with additional unit test cases contributed by Bhaskar Kataria.
 
 * class :cpp:class:`PieQueueDisc`: This class implements the main PIE algorithm:
 
@@ -32,7 +30,7 @@ by Bhaskar Kataria during his GSoC 2020 project.
 
   * ``PieQueueDisc::CalculateP ()``: This routine is called at a regular interval of `m_tUpdate` and updates the drop probability, which is required by ``PieQueueDisc::DropEarly()``
 
-  * ``PieQueueDisc::DoDequeue ()``: This routine calulates `m_qDelay` using timestamp by default or optionally with `UseDqRateEstimator` enabled calculates the average departure rate which is required for updating the drop probability in ``PieQueueDisc::CalculateP ()``. From ns-3.32 onwards, the default approach to calculate queue delay has been changed to use timestamps.
+  * ``PieQueueDisc::DoDequeue ()``: This routine calculates queue delay using timestamps (by default) or, optionally with the `UseDequeRateEstimator` attribute enabled, calculates the average departure rate to estimate queue delay. A queue delay estimate required for updating the drop probability in ``PieQueueDisc::CalculateP ()``. Starting with the ns-3.32 release, the default approach to calculate queue delay has been changed to use timestamps.
 
 References
 ==========
@@ -76,12 +74,12 @@ command-line options):
    $ ./waf --run "pie-example --PrintHelp"
    $ ./waf --run "pie-example --writePcap=1" 
 
-The expected output from the previous commands are 10 .pcap files.
+The expected output from the previous commands are ten .pcap files.
 
 Validation
 **********
 
-The PIE model is tested using :cpp:class:`PieQueueDiscTestSuite` class defined in `src/traffic-control/test/pie-queue-test-suite.cc`. The suite includes 5 test cases:
+The PIE model is tested using :cpp:class:`PieQueueDiscTestSuite` class defined in `src/traffic-control/test/pie-queue-test-suite.cc`. The suite includes the following test cases:
 
 * Test 1: simple enqueue/dequeue with defaults, no drops
 * Test 2: more data with defaults, unforced drops but no forced drops
@@ -89,6 +87,14 @@ The PIE model is tested using :cpp:class:`PieQueueDiscTestSuite` class defined i
 * Test 4: same as test 2, but with reduced dequeue rate
 * Test 5: same dequeue rate as test 4, but with higher Tupdate
 * Test 6: same as test 2, but with UseDequeueRateEstimator enabled
+* Test 7: test with CapDropAdjustment disabled
+* Test 8: test with CapDropAdjustment enabled
+* Test 9: PIE queue disc is ECN enabled, but packets are not ECN capable
+* Test 10: Packets are ECN capable, but PIE queue disc is not ECN enabled
+* Test 11: Packets and PIE queue disc both are ECN capable
+* Test 12: test with Derandomization enabled
+* Test 13: same as test 11 but with accumulated drop probability set below the low threshold
+* Test 14: same as test 12 but with accumulated drop probability set above the high threshold
 
 The test suite can be run using the following commands: 
 
@@ -98,7 +104,7 @@ The test suite can be run using the following commands:
   $ ./waf build
   $ ./test.py -s pie-queue-disc
 
-or  
+or alternatively (to see logging statements in a debug build):  
 
 .. sourcecode:: bash
 
diff --git a/src/traffic-control/model/pie-queue-disc.cc b/src/traffic-control/model/pie-queue-disc.cc
index 939b8fac3..cc00d4cbf 100644
--- a/src/traffic-control/model/pie-queue-disc.cc
+++ b/src/traffic-control/model/pie-queue-disc.cc
@@ -63,7 +63,7 @@ TypeId PieQueueDisc::GetTypeId (void)
                    MakeDoubleChecker<double> ())
     .AddAttribute ("Tupdate",
                    "Time period to calculate drop probability",
-                   TimeValue (Seconds (0.015)),
+                   TimeValue (MilliSeconds (15)),
                    MakeTimeAccessor (&PieQueueDisc::m_tUpdate),
                    MakeTimeChecker ())
     .AddAttribute ("Supdate",
@@ -84,12 +84,12 @@ TypeId PieQueueDisc::GetTypeId (void)
                    MakeUintegerChecker<uint32_t> ())
     .AddAttribute ("QueueDelayReference",
                    "Desired queue delay",
-                   TimeValue (Seconds (0.015)),
+                   TimeValue (MilliSeconds (15)),
                    MakeTimeAccessor (&PieQueueDisc::m_qDelayRef),
                    MakeTimeChecker ())
     .AddAttribute ("MaxBurstAllowance",
                    "Current max burst allowance before random drop",
-                   TimeValue (Seconds (0.15)),
+                   TimeValue (MilliSeconds (15)),
                    MakeTimeAccessor (&PieQueueDisc::m_maxBurst),
                    MakeTimeChecker ())
     .AddAttribute ("UseDequeueRateEstimator",