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