doc/guides/eventdevs/dlb2.rst

   1 ..  SPDX-License-Identifier: BSD-3-Clause
   2     Copyright(c) 2020 Intel Corporation.
   3
   4 Driver for the Intel® Dynamic Load Balancer (DLB2)
   5 ==================================================
   6
   7 The DPDK dlb poll mode driver supports the Intel® Dynamic Load Balancer.
   8
   9 Prerequisites
  10 -------------
  11
  12 Follow the DPDK :ref:`Getting Started Guide for Linux <linux_gsg>` to setup
  13 the basic DPDK environment.
  14
  15 Configuration
  16 -------------
  17
  18 The DLB2 PF PMD is a user-space PMD that uses VFIO to gain direct
  19 device access. To use this operation mode, the PCIe PF device must be bound
  20 to a DPDK-compatible VFIO driver, such as vfio-pci.
  21
  22 Eventdev API Notes
  23 ------------------
  24
  25 The DLB2 provides the functions of a DPDK event device; specifically, it
  26 supports atomic, ordered, and parallel scheduling events from queues to ports.
  27 However, the DLB2 hardware is not a perfect match to the eventdev API. Some DLB2
  28 features are abstracted by the PMD such as directed ports.
  29
  30 In general the dlb PMD is designed for ease-of-use and does not require a
  31 detailed understanding of the hardware, but these details are important when
  32 writing high-performance code. This section describes the places where the
  33 eventdev API and DLB2 misalign.
  34
  35 Scheduling Domain Configuration
  36 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  37
  38 There are 32 scheduling domainis the DLB2.
  39 When one is configured, it allocates load-balanced and
  40 directed queues, ports, credits, and other hardware resources. Some
  41 resource allocations are user-controlled -- the number of queues, for example
  42 -- and others, like credit pools (one directed and one load-balanced pool per
  43 scheduling domain), are not.
  44
  45 The DLB2 is a closed system eventdev, and as such the ``nb_events_limit`` device
  46 setup argument and the per-port ``new_event_threshold`` argument apply as
  47 defined in the eventdev header file. The limit is applied to all enqueues,
  48 regardless of whether it will consume a directed or load-balanced credit.
  49
  50 Load-Balanced Queues
  51 ~~~~~~~~~~~~~~~~~~~~
  52
  53 A load-balanced queue can support atomic and ordered scheduling, or atomic and
  54 unordered scheduling, but not atomic and unordered and ordered scheduling. A
  55 queue's scheduling types are controlled by the event queue configuration.
  56
  57 If the user sets the ``RTE_EVENT_QUEUE_CFG_ALL_TYPES`` flag, the
  58 ``nb_atomic_order_sequences`` determines the supported scheduling types.
  59 With non-zero ``nb_atomic_order_sequences``, the queue is configured for atomic
  60 and ordered scheduling. In this case, ``RTE_SCHED_TYPE_PARALLEL`` scheduling is
  61 supported by scheduling those events as ordered events.  Note that when the
  62 event is dequeued, its sched_type will be ``RTE_SCHED_TYPE_ORDERED``. Else if
  63 ``nb_atomic_order_sequences`` is zero, the queue is configured for atomic and
  64 unordered scheduling. In this case, ``RTE_SCHED_TYPE_ORDERED`` is unsupported.
  65
  66 If the ``RTE_EVENT_QUEUE_CFG_ALL_TYPES`` flag is not set, schedule_type
  67 dictates the queue's scheduling type.
  68
  69 The ``nb_atomic_order_sequences`` queue configuration field sets the ordered
  70 queue's reorder buffer size.  DLB2 has 4 groups of ordered queues, where each
  71 group is configured to contain either 1 queue with 1024 reorder entries, 2
  72 queues with 512 reorder entries, and so on down to 32 queues with 32 entries.
  73
  74 When a load-balanced queue is created, the PMD will configure a new sequence
  75 number group on-demand if num_sequence_numbers does not match a pre-existing
  76 group with available reorder buffer entries. If all sequence number groups are
  77 in use, no new group will be created and queue configuration will fail. (Note
  78 that when the PMD is used with a virtual DLB2 device, it cannot change the
  79 sequence number configuration.)
  80
  81 The queue's ``nb_atomic_flows`` parameter is ignored by the DLB2 PMD, because
  82 the DLB2 does not limit the number of flows a queue can track. In the DLB2, all
  83 load-balanced queues can use the full 16-bit flow ID range.
  84
  85 Flow ID
  86 ~~~~~~~
  87
  88 The flow ID field is preserved in the event when it is scheduled in the
  89 DLB2.
  90
  91 Reconfiguration
  92 ~~~~~~~~~~~~~~~
  93
  94 The Eventdev API allows one to reconfigure a device, its ports, and its queues
  95 by first stopping the device, calling the configuration function(s), then
  96 restarting the device. The DLB2 does not support configuring an individual queue
  97 or port without first reconfiguring the entire device, however, so there are
  98 certain reconfiguration sequences that are valid in the eventdev API but not
  99 supported by the PMD.
 100
 101 Specifically, the PMD supports the following configuration sequence:
 102 1. Configure and start the device
 103 2. Stop the device
 104 3. (Optional) Reconfigure the device
 105 4. (Optional) If step 3 is run:
 106
 107    a. Setup queue(s). The reconfigured queue(s) lose their previous port links.
 108    b. The reconfigured port(s) lose their previous queue links.
 109
 110 5. (Optional, only if steps 4a and 4b are run) Link port(s) to queue(s)
 111 6. Restart the device. If the device is reconfigured in step 3 but one or more
 112    of its ports or queues are not, the PMD will apply their previous
 113    configuration (including port->queue links) at this time.
 114
 115 The PMD does not support the following configuration sequences:
 116 1. Configure and start the device
 117 2. Stop the device
 118 3. Setup queue or setup port
 119 4. Start the device
 120
 121 This sequence is not supported because the event device must be reconfigured
 122 before its ports or queues can be.
 123
 124 Atomic Inflights Allocation
 125 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 126
 127 In the last stage prior to scheduling an atomic event to a CQ, DLB2 holds the
 128 inflight event in a temporary buffer that is divided among load-balanced
 129 queues. If a queue's atomic buffer storage fills up, this can result in
 130 head-of-line-blocking. For example:
 131
 132 - An LDB queue allocated N atomic buffer entries
 133 - All N entries are filled with events from flow X, which is pinned to CQ 0.
 134
 135 Until CQ 0 releases 1+ events, no other atomic flows for that LDB queue can be
 136 scheduled. The likelihood of this case depends on the eventdev configuration,
 137 traffic behavior, event processing latency, potential for a worker to be
 138 interrupted or otherwise delayed, etc.
 139
 140 By default, the PMD allocates 16 buffer entries for each load-balanced queue,
 141 which provides an even division across all 128 queues but potentially wastes
 142 buffer space (e.g. if not all queues are used, or aren't used for atomic
 143 scheduling).
 144
 145 The PMD provides a dev arg to override the default per-queue allocation. To
 146 increase a vdev's per-queue atomic-inflight allocation to (for example) 64:
 147
 148     .. code-block:: console
 149
 150        --vdev=dlb1_event,atm_inflights=64
 151