From 01ac5aa89cf568c69590555c6af94e5099ed2e21 Mon Sep 17 00:00:00 2001 From: Daipu Date: Sat, 23 Mar 2019 19:03:52 +0530 Subject: [PATCH] traffic-control: Add COBALT documentation --- src/traffic-control/doc/cobalt.rst | 137 +++++++++++++++++++++++++++++ 1 file changed, 137 insertions(+) create mode 100644 src/traffic-control/doc/cobalt.rst diff --git a/src/traffic-control/doc/cobalt.rst b/src/traffic-control/doc/cobalt.rst new file mode 100644 index 000000000..10e968ab3 --- /dev/null +++ b/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 ``_. + +[Kath17] Controlled Delay Active Queue Management (draft-ietf-aqm-fq-codel-07) +Available online at ``_. + +[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" +