doc/guides/eventdevs/dlb.rst

   1 ..  SPDX-License-Identifier: BSD-3-Clause
   2     Copyright(c) 2020 Intel Corporation.
   3
   4 Driver for the Intel® Dynamic Load Balancer (DLB)
   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 DLB 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 DLB 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 DLB hardware is not a perfect match to the eventdev API. Some DLB
  28 features are abstracted by the PMD (e.g. directed ports), some are only
  29 accessible as vdev command-line parameters, and certain eventdev features are
  30 not supported (e.g. the event flow ID is not maintained during scheduling).
  31
  32 In general the dlb PMD is designed for ease-of-use and does not require a
  33 detailed understanding of the hardware, but these details are important when
  34 writing high-performance code. This section describes the places where the
  35 eventdev API and DLB misalign.
  36
  37 Scheduling Domain Configuration
  38 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  39
  40 There are 32 scheduling domainis the DLB.
  41 When one is configured, it allocates load-balanced and
  42 directed queues, ports, credits, and other hardware resources. Some
  43 resource allocations are user-controlled -- the number of queues, for example
  44 -- and others, like credit pools (one directed and one load-balanced pool per
  45 scheduling domain), are not.
  46
  47 The DLB is a closed system eventdev, and as such the ``nb_events_limit`` device
  48 setup argument and the per-port ``new_event_threshold`` argument apply as
  49 defined in the eventdev header file. The limit is applied to all enqueues,
  50 regardless of whether it will consume a directed or load-balanced credit.
  51
  52 Reconfiguration
  53 ~~~~~~~~~~~~~~~
  54
  55 The Eventdev API allows one to reconfigure a device, its ports, and its queues
  56 by first stopping the device, calling the configuration function(s), then
  57 restarting the device. The DLB does not support configuring an individual queue
  58 or port without first reconfiguring the entire device, however, so there are
  59 certain reconfiguration sequences that are valid in the eventdev API but not
  60 supported by the PMD.
  61
  62 Specifically, the PMD supports the following configuration sequence:
  63 1. Configure and start the device
  64 2. Stop the device
  65 3. (Optional) Reconfigure the device
  66 4. (Optional) If step 3 is run:
  67
  68    a. Setup queue(s). The reconfigured queue(s) lose their previous port links.
  69    b. The reconfigured port(s) lose their previous queue links.
  70
  71 5. (Optional, only if steps 4a and 4b are run) Link port(s) to queue(s)
  72 6. Restart the device. If the device is reconfigured in step 3 but one or more
  73    of its ports or queues are not, the PMD will apply their previous
  74    configuration (including port->queue links) at this time.
  75
  76 The PMD does not support the following configuration sequences:
  77 1. Configure and start the device
  78 2. Stop the device
  79 3. Setup queue or setup port
  80 4. Start the device
  81
  82 This sequence is not supported because the event device must be reconfigured
  83 before its ports or queues can be.
  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.  DLB 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 DLB device, it cannot change the
 114 sequence number configuration.)
 115
 116 The queue's ``nb_atomic_flows`` parameter is ignored by the DLB PMD, because
 117 the DLB does not limit the number of flows a queue can track. In the DLB, all
 118 load-balanced queues can use the full 16-bit flow ID range.
 119