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 Load-Balanced Queues
  86 ~~~~~~~~~~~~~~~~~~~~
  87
  88 A load-balanced queue can support atomic and ordered scheduling, or atomic and
  89 unordered scheduling, but not atomic and unordered and ordered scheduling. A
  90 queue's scheduling types are controlled by the event queue configuration.
  91
  92 If the user sets the ``RTE_EVENT_QUEUE_CFG_ALL_TYPES`` flag, the
  93 ``nb_atomic_order_sequences`` determines the supported scheduling types.
  94 With non-zero ``nb_atomic_order_sequences``, the queue is configured for atomic
  95 and ordered scheduling. In this case, ``RTE_SCHED_TYPE_PARALLEL`` scheduling is
  96 supported by scheduling those events as ordered events.  Note that when the
  97 event is dequeued, its sched_type will be ``RTE_SCHED_TYPE_ORDERED``. Else if
  98 ``nb_atomic_order_sequences`` is zero, the queue is configured for atomic and
  99 unordered scheduling. In this case, ``RTE_SCHED_TYPE_ORDERED`` is unsupported.
 100
 101 If the ``RTE_EVENT_QUEUE_CFG_ALL_TYPES`` flag is not set, schedule_type
 102 dictates the queue's scheduling type.
 103
 104 The ``nb_atomic_order_sequences`` queue configuration field sets the ordered
 105 queue's reorder buffer size.  DLB2 has 4 groups of ordered queues, where each
 106 group is configured to contain either 1 queue with 1024 reorder entries, 2
 107 queues with 512 reorder entries, and so on down to 32 queues with 32 entries.
 108
 109 When a load-balanced queue is created, the PMD will configure a new sequence
 110 number group on-demand if num_sequence_numbers does not match a pre-existing
 111 group with available reorder buffer entries. If all sequence number groups are
 112 in use, no new group will be created and queue configuration will fail. (Note
 113 that when the PMD is used with a virtual DLB2 device, it cannot change the
 114 sequence number configuration.)
 115
 116 The queue's ``nb_atomic_flows`` parameter is ignored by the DLB2 PMD, because
 117 the DLB2 does not limit the number of flows a queue can track. In the DLB2, all
 118 load-balanced queues can use the full 16-bit flow ID range.
 119
 120 Load-balanced and Directed Ports
 121 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 122
 123 DLB2 ports come in two flavors: load-balanced and directed. The eventdev API
 124 does not have the same concept, but it has a similar one: ports and queues that
 125 are singly-linked (i.e. linked to a single queue or port, respectively).
 126
 127 The ``rte_event_dev_info_get()`` function reports the number of available
 128 event ports and queues (among other things). For the DLB2 PMD, max_event_ports
 129 and max_event_queues report the number of available load-balanced ports and
 130 queues, and max_single_link_event_port_queue_pairs reports the number of
 131 available directed ports and queues.
 132
 133 When a scheduling domain is created in ``rte_event_dev_configure()``, the user
 134 specifies ``nb_event_ports`` and ``nb_single_link_event_port_queues``, which
 135 control the total number of ports (load-balanced and directed) and the number
 136 of directed ports. Hence, the number of requested load-balanced ports is
 137 ``nb_event_ports - nb_single_link_event_ports``. The ``nb_event_queues`` field
 138 specifies the total number of queues (load-balanced and directed). The number
 139 of directed queues comes from ``nb_single_link_event_port_queues``, since
 140 directed ports and queues come in pairs.
 141
 142 When a port is setup, the ``RTE_EVENT_PORT_CFG_SINGLE_LINK`` flag determines
 143 whether it should be configured as a directed (the flag is set) or a
 144 load-balanced (the flag is unset) port. Similarly, the
 145 ``RTE_EVENT_QUEUE_CFG_SINGLE_LINK`` queue configuration flag controls
 146 whether it is a directed or load-balanced queue.
 147
 148 Load-balanced ports can only be linked to load-balanced queues, and directed
 149 ports can only be linked to directed queues. Furthermore, directed ports can
 150 only be linked to a single directed queue (and vice versa), and that link
 151 cannot change after the eventdev is started.
 152
 153 The eventdev API does not have a directed scheduling type. To support directed
 154 traffic, the dlb PMD detects when an event is being sent to a directed queue
 155 and overrides its scheduling type. Note that the originally selected scheduling
 156 type (atomic, ordered, or parallel) is not preserved, and an event's sched_type
 157 will be set to ``RTE_SCHED_TYPE_ATOMIC`` when it is dequeued from a directed
 158 port.
 159
 160 Flow ID
 161 ~~~~~~~
 162
 163 The flow ID field is preserved in the event when it is scheduled in the
 164 DLB2.
 165
 166 Reconfiguration
 167 ~~~~~~~~~~~~~~~
 168
 169 The Eventdev API allows one to reconfigure a device, its ports, and its queues
 170 by first stopping the device, calling the configuration function(s), then
 171 restarting the device. The DLB2 does not support configuring an individual queue
 172 or port without first reconfiguring the entire device, however, so there are
 173 certain reconfiguration sequences that are valid in the eventdev API but not
 174 supported by the PMD.
 175
 176 Specifically, the PMD supports the following configuration sequence:
 177 1. Configure and start the device
 178 2. Stop the device
 179 3. (Optional) Reconfigure the device
 180 4. (Optional) If step 3 is run:
 181
 182    a. Setup queue(s). The reconfigured queue(s) lose their previous port links.
 183    b. The reconfigured port(s) lose their previous queue links.
 184
 185 5. (Optional, only if steps 4a and 4b are run) Link port(s) to queue(s)
 186 6. Restart the device. If the device is reconfigured in step 3 but one or more
 187    of its ports or queues are not, the PMD will apply their previous
 188    configuration (including port->queue links) at this time.
 189
 190 The PMD does not support the following configuration sequences:
 191 1. Configure and start the device
 192 2. Stop the device
 193 3. Setup queue or setup port
 194 4. Start the device
 195
 196 This sequence is not supported because the event device must be reconfigured
 197 before its ports or queues can be.
 198
 199 Atomic Inflights Allocation
 200 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 201
 202 In the last stage prior to scheduling an atomic event to a CQ, DLB2 holds the
 203 inflight event in a temporary buffer that is divided among load-balanced
 204 queues. If a queue's atomic buffer storage fills up, this can result in
 205 head-of-line-blocking. For example:
 206
 207 - An LDB queue allocated N atomic buffer entries
 208 - All N entries are filled with events from flow X, which is pinned to CQ 0.
 209
 210 Until CQ 0 releases 1+ events, no other atomic flows for that LDB queue can be
 211 scheduled. The likelihood of this case depends on the eventdev configuration,
 212 traffic behavior, event processing latency, potential for a worker to be
 213 interrupted or otherwise delayed, etc.
 214
 215 By default, the PMD allocates 16 buffer entries for each load-balanced queue,
 216 which provides an even division across all 128 queues but potentially wastes
 217 buffer space (e.g. if not all queues are used, or aren't used for atomic
 218 scheduling).
 219
 220 The PMD provides a dev arg to override the default per-queue allocation. To
 221 increase a vdev's per-queue atomic-inflight allocation to (for example) 64:
 222
 223     .. code-block:: console
 224
 225        --vdev=dlb1_event,atm_inflights=64
 226