Added PIE related information to documentation.
Signed-off-by: Liguzinski, WojciechX <wojciechx.liguzin...@intel.com>
---
doc/guides/prog_guide/glossary.rst | 3 +
doc/guides/prog_guide/qos_framework.rst | 64 +++++++++++++++++---
doc/guides/prog_guide/traffic_management.rst | 13 +++-
3 files changed, 68 insertions(+), 12 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..7c37b78804 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
@@ -1396,7 +1440,7 @@ As can be seen, the floating-point implementation
achieved the worst performance
| Method
| Relative Performance |
|
| |
+====================================================================================+======================+
- | Current dropper method (see :ref:`Section 23.3.2.1.3 <Dropper>`)
| 100% |
+ | Current dropper method (see :ref:`Section 23.3.2.1.3 <Droppers>`)
| 100% |
|
| |
+------------------------------------------------------------------------------------+----------------------+
| Fixed-point method with small (512B) look-up table
| 148% |
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
