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 and Directed Ports
  51 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  52
  53 DLB2 ports come in two flavors: load-balanced and directed. The eventdev API
  54 does not have the same concept, but it has a similar one: ports and queues that
  55 are singly-linked (i.e. linked to a single queue or port, respectively).
  56
  57 The ``rte_event_dev_info_get()`` function reports the number of available
  58 event ports and queues (among other things). For the DLB2 PMD, max_event_ports
  59 and max_event_queues report the number of available load-balanced ports and
  60 queues, and max_single_link_event_port_queue_pairs reports the number of
  61 available directed ports and queues.
  62
  63 When a scheduling domain is created in ``rte_event_dev_configure()``, the user
  64 specifies ``nb_event_ports`` and ``nb_single_link_event_port_queues``, which
  65 control the total number of ports (load-balanced and directed) and the number
  66 of directed ports. Hence, the number of requested load-balanced ports is
  67 ``nb_event_ports - nb_single_link_event_ports``. The ``nb_event_queues`` field
  68 specifies the total number of queues (load-balanced and directed). The number
  69 of directed queues comes from ``nb_single_link_event_port_queues``, since
  70 directed ports and queues come in pairs.
  71
  72 When a port is setup, the ``RTE_EVENT_PORT_CFG_SINGLE_LINK`` flag determines
  73 whether it should be configured as a directed (the flag is set) or a
  74 load-balanced (the flag is unset) port. Similarly, the
  75 ``RTE_EVENT_QUEUE_CFG_SINGLE_LINK`` queue configuration flag controls
  76 whether it is a directed or load-balanced queue.
  77
  78 Load-balanced ports can only be linked to load-balanced queues, and directed
  79 ports can only be linked to directed queues. Furthermore, directed ports can
  80 only be linked to a single directed queue (and vice versa), and that link
  81 cannot change after the eventdev is started.
  82
  83 The eventdev API does not have a directed scheduling type. To support directed
  84 traffic, the dlb PMD detects when an event is being sent to a directed queue
  85 and overrides its scheduling type. Note that the originally selected scheduling
  86 type (atomic, ordered, or parallel) is not preserved, and an event's sched_type
  87 will be set to ``RTE_SCHED_TYPE_ATOMIC`` when it is dequeued from a directed
  88 port.
  89
  90 Flow ID
  91 ~~~~~~~
  92
  93 The flow ID field is preserved in the event when it is scheduled in the
  94 DLB2.
  95
  96 Reconfiguration
  97 ~~~~~~~~~~~~~~~
  98
  99 The Eventdev API allows one to reconfigure a device, its ports, and its queues
 100 by first stopping the device, calling the configuration function(s), then
 101 restarting the device. The DLB2 does not support configuring an individual queue
 102 or port without first reconfiguring the entire device, however, so there are
 103 certain reconfiguration sequences that are valid in the eventdev API but not
 104 supported by the PMD.
 105
 106 Specifically, the PMD supports the following configuration sequence:
 107 1. Configure and start the device
 108 2. Stop the device
 109 3. (Optional) Reconfigure the device
 110 4. (Optional) If step 3 is run:
 111
 112    a. Setup queue(s). The reconfigured queue(s) lose their previous port links.
 113    b. The reconfigured port(s) lose their previous queue links.
 114
 115 5. (Optional, only if steps 4a and 4b are run) Link port(s) to queue(s)
 116 6. Restart the device. If the device is reconfigured in step 3 but one or more
 117    of its ports or queues are not, the PMD will apply their previous
 118    configuration (including port->queue links) at this time.
 119
 120 The PMD does not support the following configuration sequences:
 121 1. Configure and start the device
 122 2. Stop the device
 123 3. Setup queue or setup port
 124 4. Start the device
 125
 126 This sequence is not supported because the event device must be reconfigured
 127 before its ports or queues can be.
 128
 129 Atomic Inflights Allocation
 130 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 131
 132 In the last stage prior to scheduling an atomic event to a CQ, DLB2 holds the
 133 inflight event in a temporary buffer that is divided among load-balanced
 134 queues. If a queue's atomic buffer storage fills up, this can result in
 135 head-of-line-blocking. For example:
 136
 137 - An LDB queue allocated N atomic buffer entries
 138 - All N entries are filled with events from flow X, which is pinned to CQ 0.
 139
 140 Until CQ 0 releases 1+ events, no other atomic flows for that LDB queue can be
 141 scheduled. The likelihood of this case depends on the eventdev configuration,
 142 traffic behavior, event processing latency, potential for a worker to be
 143 interrupted or otherwise delayed, etc.
 144
 145 By default, the PMD allocates 16 buffer entries for each load-balanced queue,
 146 which provides an even division across all 128 queues but potentially wastes
 147 buffer space (e.g. if not all queues are used, or aren't used for atomic
 148 scheduling).
 149
 150 The PMD provides a dev arg to override the default per-queue allocation. To
 151 increase a vdev's per-queue atomic-inflight allocation to (for example) 64:
 152
 153     .. code-block:: console
 154
 155        --vdev=dlb1_event,atm_inflights=64
 156