[dpdk-dev] [RFC PATCH v5 4/5] doc/guides/prog_guide: added PIE

["Liguzinski, WojciechX" <wojciechx.liguzinski@intel.com>]

Added PIE related information to documentation.

Signed-off-by: Liguzinski, WojciechX <wojciechx.liguzinski@intel.com>
---
 doc/guides/prog_guide/glossary.rst           |  3 +
 doc/guides/prog_guide/qos_framework.rst      | 60 +++++++++++++++++---
 doc/guides/prog_guide/traffic_management.rst | 13 ++++-
 3 files changed, 66 insertions(+), 10 deletions(-)

diff --git a/doc/guides/prog_guide/glossary.rst b/doc/guides/prog_guide/glossary.rst
index 7044a7df2a..fb0910ba5b 100644
--- a/doc/guides/prog_guide/glossary.rst
+++ b/doc/guides/prog_guide/glossary.rst
@@ -158,6 +158,9 @@ PCI
 PHY
    An abbreviation for the physical layer of the OSI model.
 
+PIE
+   Proportional Integral Controller Enhanced (RFC8033)
+
 pktmbuf
    An *mbuf* carrying a network packet.
 
diff --git a/doc/guides/prog_guide/qos_framework.rst b/doc/guides/prog_guide/qos_framework.rst
index 3b8a1184b0..7c8450181d 100644
--- a/doc/guides/prog_guide/qos_framework.rst
+++ b/doc/guides/prog_guide/qos_framework.rst
@@ -56,7 +56,8 @@ A functional description of each block is provided in the following table.
    |   |                        |                                                                                |
    +---+------------------------+--------------------------------------------------------------------------------+
    | 7 | Dropper                | Congestion management using the Random Early Detection (RED) algorithm         |
-   |   |                        | (specified by the Sally Floyd - Van Jacobson paper) or Weighted RED (WRED).    |
+   |   |                        | (specified by the Sally Floyd - Van Jacobson paper) or Weighted RED (WRED)     |
+   |   |                        | or Proportional Integral Controller Enhanced (PIE).                            |
    |   |                        | Drop packets based on the current scheduler queue load level and packet        |
    |   |                        | priority. When congestion is experienced, lower priority packets are dropped   |
    |   |                        | first.                                                                         |
@@ -421,7 +422,7 @@ No input packet can be part of more than one pipeline stage at a given time.
 The congestion management scheme implemented by the enqueue pipeline described above is very basic:
 packets are enqueued until a specific queue becomes full,
 then all the packets destined to the same queue are dropped until packets are consumed (by the dequeue operation).
-This can be improved by enabling RED/WRED as part of the enqueue pipeline which looks at the queue occupancy and
+This can be improved by enabling RED/WRED or PIE as part of the enqueue pipeline which looks at the queue occupancy and
 packet priority in order to yield the enqueue/drop decision for a specific packet
 (as opposed to enqueuing all packets / dropping all packets indiscriminately).
 
@@ -1155,13 +1156,13 @@ If the number of queues is small,
 then the performance of the port scheduler for the same level of active traffic is expected to be worse than
 the performance of a small set of message passing queues.
 
-.. _Dropper:
+.. _Droppers:
 
-Dropper
+Droppers
 -------
 
 The purpose of the DPDK dropper is to drop packets arriving at a packet scheduler to avoid congestion.
-The dropper supports the Random Early Detection (RED),
+The dropper supports the Proportional Integral Controller Enhanced (PIE), Random Early Detection (RED),
 Weighted Random Early Detection (WRED) and tail drop algorithms.
 :numref:`figure_blk_diag_dropper` illustrates how the dropper integrates with the scheduler.
 The DPDK currently does not support congestion management
@@ -1174,9 +1175,13 @@ so the dropper provides the only method for congestion avoidance.
    High-level Block Diagram of the DPDK Dropper
 
 
-The dropper uses the Random Early Detection (RED) congestion avoidance algorithm as documented in the reference publication.
-The purpose of the RED algorithm is to monitor a packet queue,
+The dropper uses one of two congestion avoidance algorithms:
+   - the Random Early Detection (RED) as documented in the reference publication.
+   - the Proportional Integral Controller Enhanced (PIE) as documented in RFC8033 publication.
+
+The purpose of the RED/PIE algorithm is to monitor a packet queue,
 determine the current congestion level in the queue and decide whether an arriving packet should be enqueued or dropped.
+
 The RED algorithm uses an Exponential Weighted Moving Average (EWMA) filter to compute average queue size which
 gives an indication of the current congestion level in the queue.
 
@@ -1192,7 +1197,7 @@ This occurs when a packet queue has reached maximum capacity and cannot store an
 In this situation, all arriving packets are dropped.
 
 The flow through the dropper is illustrated in :numref:`figure_flow_tru_droppper`.
-The RED/WRED algorithm is exercised first and tail drop second.
+The RED/WRED/PIE algorithm is exercised first and tail drop second.
 
 .. _figure_flow_tru_droppper:
 
@@ -1200,6 +1205,16 @@ The RED/WRED algorithm is exercised first and tail drop second.
 
    Flow Through the Dropper
 
+The PIE algorithm periodically updates the drop probability based on the latency samples.
+The current latency sample but also analyze whether the latency is trending up or down.
+This is the classical Proportional Integral (PI) controller method, which is known for
+eliminating steady-state errors.
+
+When a congestion period ends, we might be left with a high drop probability with light
+packet arrivals. Hence, the PIE algorithm includes a mechanism by which the drop probability
+decays exponentially (rather than linearly) when the system is not congested.
+This would help the drop probability converge to 0 more quickly, while the PI controller ensures
+that it would eventually reach zero.
 
 The use cases supported by the dropper are:
 
@@ -1253,6 +1268,35 @@ to a mark probability of 1/10 (that is, 1 in 10 packets will be dropped).
 The EWMA filter weight parameter is specified as an inverse log value,
 for example, a filter weight parameter value of 9 corresponds to a filter weight of 1/29.
 
+A PIE configuration contains the parameters given in :numref:`table_qos_16a`.
+
+.. _table_qos_16a:
+
+.. table:: PIE Configuration Parameters
+
+   +--------------------------+---------+---------+------------------+
+   | Parameter                | Minimum | Maximum | Default          |
+   |                          |         |         |                  |
+   +==========================+=========+=========+==================+
+   | Queue delay reference    | 1       | uint16  | 15               |
+   | Latency Target Value     |         |         |                  |
+   | Unit: ms                 |         |         |                  |
+   +--------------------------+---------+---------+------------------+
+   | Max Burst Allowance      | 1       | uint16  | 150              |
+   | Unit: ms                 |         |         |                  |
+   +--------------------------+---------+---------+------------------+
+   | Tail Drop Threshold      | 1       | uint16  | 64               |
+   | Unit: bytes              |         |         |                  |
+   +--------------------------+---------+---------+------------------+
+   | Period to calculate      | 1       | uint16  | 15               |
+   | drop probability         |         |         |                  |
+   | Unit: ms                 |         |         |                  |
+   +--------------------------+---------+---------+------------------+
+
+The meaning of these parameters is explained in more detail in the next sections.
+The format of these parameters as specified to the dropper module API.
+They could made self calculated for fine tuning, within the apps.
+
 .. _Enqueue_Operation:
 
 Enqueue Operation
diff --git a/doc/guides/prog_guide/traffic_management.rst b/doc/guides/prog_guide/traffic_management.rst
index 05b34d93a5..c356791a45 100644
--- a/doc/guides/prog_guide/traffic_management.rst
+++ b/doc/guides/prog_guide/traffic_management.rst
@@ -22,6 +22,7 @@ Main features:
   shared (by multiple nodes) shapers
 * Congestion management for hierarchy leaf nodes: algorithms of tail drop, head
   drop, WRED, private (per node) and shared (by multiple nodes) WRED contexts
+  and PIE.
 * Packet marking: IEEE 802.1q (VLAN DEI), IETF RFC 3168 (IPv4/IPv6 ECN for TCP
   and SCTP), IETF RFC 2597 (IPv4 / IPv6 DSCP)
 
@@ -103,8 +104,9 @@ Congestion Management
 Congestion management is used to control the admission of packets into a packet
 queue or group of packet queues on congestion. The congestion management
 algorithms that are supported are: Tail Drop, Head Drop and Weighted Random
-Early Detection (WRED). They are made available for every leaf node in the
-hierarchy, subject to the specific implementation supporting them.
+Early Detection (WRED), Proportional Integral Controller Enhanced (PIE).
+They are made available for every leaf node in the hierarchy, subject to
+the specific implementation supporting them.
 On request of writing a new packet into the current queue while the queue is
 full, the Tail Drop algorithm drops the new packet while leaving the queue
 unmodified, as opposed to the Head Drop* algorithm, which drops the packet
@@ -128,6 +130,13 @@ The configuration of WRED private and shared contexts is done through the
 definition of WRED profiles. Any WRED profile can be used by one or several
 WRED contexts (either private or shared).
 
+The Proportional Integral Controller Enhanced (PIE) algorithm works by proactively
+dropping packets randomly. Calculated drop probability is updated periodically,
+based on latency measured and desired and whether the queuing latency is currently
+trending up or down. Queuing latency can be obtained using direct measurement or
+on estimations calculated from the queue length and dequeue rate. The random drop
+is triggered by a packet's arrival before enqueuing into a queue.
+
 
 Packet Marking
 --------------
-- 
2.25.1