[dpdk-dev] [PATCH v3 24/26] doc/dlb2: update documentation for v2.5

[Timothy McDaniel <timothy.mcdaniel@intel.com>]

Update the dlb documentation for v2.5. Notable differences include
the new cobined credit scheme. Also cleaned up a couple of sections,
and removed a duplicate section.

Signed-off-by: Timothy McDaniel <timothy.mcdaniel@intel.com>
---
 doc/guides/eventdevs/dlb2.rst | 75 +++++++++++++----------------------
 1 file changed, 27 insertions(+), 48 deletions(-)

diff --git a/doc/guides/eventdevs/dlb2.rst b/doc/guides/eventdevs/dlb2.rst
index 94d2c77ff..94e46ea7d 100644
--- a/doc/guides/eventdevs/dlb2.rst
+++ b/doc/guides/eventdevs/dlb2.rst
@@ -4,7 +4,8 @@
 Driver for the Intel® Dynamic Load Balancer (DLB2)
 ==================================================
 
-The DPDK dlb poll mode driver supports the Intel® Dynamic Load Balancer.
+The DPDK dlb poll mode driver supports the Intel® Dynamic Load Balancer,
+hardware versions 2.0 and 2.5.
 
 Prerequisites
 -------------
@@ -35,7 +36,7 @@ eventdev API and DLB2 misalign.
 Scheduling Domain Configuration
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-There are 32 scheduling domainis the DLB2.
+DLB2 supports 32 scheduling domains.
 When one is configured, it allocates load-balanced and
 directed queues, ports, credits, and other hardware resources. Some
 resource allocations are user-controlled -- the number of queues, for example
@@ -67,42 +68,7 @@ If the ``RTE_EVENT_QUEUE_CFG_ALL_TYPES`` flag is not set, schedule_type
 dictates the queue's scheduling type.
 
 The ``nb_atomic_order_sequences`` queue configuration field sets the ordered
-queue's reorder buffer size.  DLB2 has 4 groups of ordered queues, where each
-group is configured to contain either 1 queue with 1024 reorder entries, 2
-queues with 512 reorder entries, and so on down to 32 queues with 32 entries.
-
-When a load-balanced queue is created, the PMD will configure a new sequence
-number group on-demand if num_sequence_numbers does not match a pre-existing
-group with available reorder buffer entries. If all sequence number groups are
-in use, no new group will be created and queue configuration will fail. (Note
-that when the PMD is used with a virtual DLB2 device, it cannot change the
-sequence number configuration.)
-
-The queue's ``nb_atomic_flows`` parameter is ignored by the DLB2 PMD, because
-the DLB2 does not limit the number of flows a queue can track. In the DLB2, all
-load-balanced queues can use the full 16-bit flow ID range.
-
-Load-Balanced Queues
-~~~~~~~~~~~~~~~~~~~~
-
-A load-balanced queue can support atomic and ordered scheduling, or atomic and
-unordered scheduling, but not atomic and unordered and ordered scheduling. A
-queue's scheduling types are controlled by the event queue configuration.
-
-If the user sets the ``RTE_EVENT_QUEUE_CFG_ALL_TYPES`` flag, the
-``nb_atomic_order_sequences`` determines the supported scheduling types.
-With non-zero ``nb_atomic_order_sequences``, the queue is configured for atomic
-and ordered scheduling. In this case, ``RTE_SCHED_TYPE_PARALLEL`` scheduling is
-supported by scheduling those events as ordered events.  Note that when the
-event is dequeued, its sched_type will be ``RTE_SCHED_TYPE_ORDERED``. Else if
-``nb_atomic_order_sequences`` is zero, the queue is configured for atomic and
-unordered scheduling. In this case, ``RTE_SCHED_TYPE_ORDERED`` is unsupported.
-
-If the ``RTE_EVENT_QUEUE_CFG_ALL_TYPES`` flag is not set, schedule_type
-dictates the queue's scheduling type.
-
-The ``nb_atomic_order_sequences`` queue configuration field sets the ordered
-queue's reorder buffer size.  DLB2 has 4 groups of ordered queues, where each
+queue's reorder buffer size.  DLB2 has 2 groups of ordered queues, where each
 group is configured to contain either 1 queue with 1024 reorder entries, 2
 queues with 512 reorder entries, and so on down to 32 queues with 32 entries.
 
@@ -157,6 +123,11 @@ type (atomic, ordered, or parallel) is not preserved, and an event's sched_type
 will be set to ``RTE_SCHED_TYPE_ATOMIC`` when it is dequeued from a directed
 port.
 
+Finally, even though all 3 event types are supported on the same QID by
+converting unordered events to ordered, such use should be discouraged as much
+as possible, since mixing types on the same queue uses valuable reorder
+resources, and orders events which do not require ordering.
+
 Flow ID
 ~~~~~~~
 
@@ -169,13 +140,15 @@ Hardware Credits
 DLB2 uses a hardware credit scheme to prevent software from overflowing hardware
 event storage, with each unit of storage represented by a credit. A port spends
 a credit to enqueue an event, and hardware refills the ports with credits as the
-events are scheduled to ports. Refills come from credit pools, and each port is
-a member of a load-balanced credit pool and a directed credit pool. The
-load-balanced credits are used to enqueue to load-balanced queues, and directed
-credits are used for directed queues.
+events are scheduled to ports. Refills come from credit pools.
 
-A DLB2 eventdev contains one load-balanced and one directed credit pool. These
-pools' sizes are controlled by the nb_events_limit field in struct
+For DLB v2.5, there is a single credit pool used for both load balanced and
+directed traffic.
+
+For DLB v2.0, each port is a member of both a load-balanced credit pool and a
+directed credit pool. The load-balanced credits are used to enqueue to
+load-balanced queues, and directed credits are used for directed queues.
+These pools' sizes are controlled by the nb_events_limit field in struct
 rte_event_dev_config. The load-balanced pool is sized to contain
 nb_events_limit credits, and the directed pool is sized to contain
 nb_events_limit/4 credits. The directed pool size can be overridden with the
@@ -276,10 +249,16 @@ The DLB2 supports event priority and per-port queue service priority, as
 described in the eventdev header file. The DLB2 does not support 'global' event
 queue priority established at queue creation time.
 
-DLB2 supports 8 event and queue service priority levels. For both priority
-types, the PMD uses the upper three bits of the priority field to determine the
-DLB2 priority, discarding the 5 least significant bits. The 5 least significant
-event priority bits are not preserved when an event is enqueued.
+DLB2 supports 4 event and queue service priority levels. For both priority types,
+the PMD uses the upper three bits of the priority field to determine the DLB2
+priority, discarding the 5 least significant bits. But least significant bit out
+of 3 priority bits is effectively ignored for binning into 4 priorities. The
+discarded 5 least significant event priority bits are not preserved when an event
+is enqueued.
+
+Note that event priority only works within the same event type.
+When atomic and ordered or unordered events are enqueued to same QID, priority
+across the types is always equal, and both types are served in a round robin manner.
 
 Reconfiguration
 ~~~~~~~~~~~~~~~
-- 
2.23.0