traffic-control: Add COBALT documentation

src/traffic-control/doc/cobalt.rst

@@ -0,0 +1,137 @@
+.. include:: replace.txt
+
+
+Cobalt queue disc
+-----------------
+
+This chapter describes the COBALT (CoDel BLUE Alternate) ([Cake16]_) queue disc 
+implementation in |ns3|.
+
+COBALT queue disc is an integral component of CAKE smart queue management system.
+It is a combination of the CoDel ([Kath17]_) and BLUE ([BLUE02]_) Active Queue
+Management algorithms.
+
+
+Model Description
+*****************
+
+The source code for the COBALT model is located in the directory
+``src/traffic-control/model`` and consists of 2 files: `cobalt-queue-disc.h` and
+`cobalt-queue-disc.cc` defining a CobaltQueueDisc class and a helper
+CobaltTimestampTag class. The code was ported to |ns3| by Vignesh Kanan,
+Harsh Lara, Shefali Gupta, Jendaipou Palmei and Mohit P. Tahiliani based on 
+the Linux kernel code.
+
+Stefano Avallone and Pasquale Imputato helped in verifying the correctness of 
+COBALT model in |ns3| by comparing the results obtained from it to those obtained
+from the Linux model of COBALT. A detailed comparison of ns-3 model of COBALT with
+Linux model of COBALT is provided in ([Cobalt19]_).
+
+* class :cpp:class:`CobaltQueueDisc`: This class implements the main Cobalt algorithm:
+
+  * ``CobaltQueueDisc::DoEnqueue ()``: This routine tags a packet with the
+current time before pushing it into the queue.  The timestamp tag is used by
+``CobaltQueue::DoDequeue()`` to compute the packet's sojourn time.  If the
+queue is full upon the packet arrival, this routine will drop the packet and
+record the number of drops due to queue overflow, which is stored in
+`m_stats.qLimDrop`.
+
+  * ``CobaltQueueDisc::ShouldDrop ()``: This routine is
+``CobaltQueueDisc::DoDequeue()``'s helper routine that determines whether a
+packet should be dropped or not based on its sojourn time.  If the sojourn time
+goes above `m_target` and remains above continuously for at least `m_interval`,
+the routine returns ``true`` indicating that it is OK to drop the packet.
+``Otherwise, it returns ``false``. This routine decides if a packet should be
+dropped based on the dropping state of CoDel and drop probability of BLUE.
+The idea is to have both algorithms running in parallel and their effectiveness
+is decided by their respective parameters (Pdrop of BLUE and dropping state of
+CoDel). If either of them decide to drop the packet, the packet is dropped.
+
+  * ``CobaltQueueDisc::DoDequeue ()``: This routine performs the actual packet
+``drop based on ``CobaltQueueDisc::ShouldDrop ()``'s return value and schedules
+the next drop. Cobalt will decrease BLUE's drop probability if the queue is
+empty. This will ensure that the queue does not underflow. Otherwise Cobalt will
+take the next packet from the queue and calculate its drop state by running
+CoDel and BLUE in parallel till there are none left to drop.
+
+* class :cpp:class:`CobaltTimestampTag`: This class implements the timestamp
+tagging for a packet.  This tag is used to compute the packet's sojourn time
+(the difference between the time the packet is dequeued and the time it is
+pushed into the queue). 
+
+
+
+References
+==========
+
+[Cake16] Linux implementation of Cobalt as a part of the cake framework.
+Available online at `<https://github.com/dtaht/sch_cake/blob/master/cobalt.c>`_.
+
+[Kath17] Controlled Delay Active Queue Management (draft-ietf-aqm-fq-codel-07)
+Available online at `<https://tools.ietf.org/html/draft-ietf-aqm-codel-07>`_.
+
+[BLUE02] Feng, W. C., Shin, K. G., Kandlur, D. D., & Saha, D. (2002). The BLUE
+Active Queue Management Algorithms. IEEE/ACM Transactions on Networking (ToN),
+10(4), 513-528.
+
+[Cobalt19] Jendaipou Palmei, Shefali Gupta, Pasquale Imputato, Jonathan Morton,
+Mohit P. Tahiliani, Stefano Avallone and Dave Taht (2019). Design and Evaluation
+of COBALT Queue Discipline. IEEE International Symposium on Local and
+Metropolitan Area Networks (LANMAN), July 2019.
+
+
+Attributes
+==========
+
+The key attributes that the CobaltQueue Disc class holds include the following:
+
+* ``MaxSize:`` The maximum number of packets/bytes accepted by this queue disc.
+* ``MinBytes:`` The Cobalt algorithm minbytes parameter. The default value is
+1500 bytes.
+* ``Interval:`` The sliding-minimum window. The default value is 100 ms.
+* ``Target:`` The Cobalt algorithm target queue delay. The default value is
+5 ms.
+* ``Pdrop:`` Value of drop probability.
+* ``Increment:`` Increment value of drop probability. Default value is 1./256 .
+* ``Decrement:`` Decrement value of drop probability. Default value is 1./4096 .
+* ``Count:`` Cobalt count.
+* ``DropState:`` Dropping state of Cobalt. Default value is false.
+* ``Sojourn:`` Per packet time spent in the queue.
+* ``DropNext:`` Time until next packet drop.
+
+Examples
+========
+
+An example program named `cobalt-vs-codel.cc` is located in
+``src/traffic-control/examples``. Use the following command to run the program.
+
+::
+
+   $ ./waf --run cobalt-vs-codel
+
+
+Validation
+**********
+
+The COBALT model is tested using :cpp:class:`CobaltQueueDiscTestSuite` class
+defined in `src/traffic-control/test/cobalt-queue-test-suite.cc`.
+The suite includes 2 test cases:
+
+* Test 1: Simple enqueue/dequeue with no drops.
+* Test 2: Change of BLUE's drop probability upon queue full
+(Activation of Blue).
+
+The test suite can be run using the following commands:
+
+::
+
+  $ ./waf configure --enable-examples --enable-tests
+  $ ./waf build
+  $ ./test.py -s cobalt-queue-disc
+
+or
+
+::
+
+  $ NS_LOG="CobaltQueueDisc" ./waf --run "test-runner --suite=cobalt-queue-disc"
+