doc/guides/eventdevs/dsw.rst

   1 ..  SPDX-License-Identifier: BSD-3-Clause
   2     Copyright(c) 2018 Ericsson AB
   3
   4 Distributed Software Eventdev Poll Mode Driver
   5 ==============================================
   6
   7 The distributed software event device is an eventdev driver which
   8 distributes the task of scheduling events among all the eventdev ports
   9 and the lcore threads using them.
  10
  11 Features
  12 --------
  13
  14 Queues
  15  * Atomic
  16  * Parallel
  17  * Single-Link
  18
  19 Ports
  20  * Load balanced (for Atomic, Ordered, Parallel queues)
  21  * Single Link (for single-link queues)
  22
  23 Configuration and Options
  24 -------------------------
  25
  26 The distributed software eventdev is a vdev device, and as such can be
  27 created from the application code, or from the EAL command line:
  28
  29 * Call ``rte_vdev_init("event_dsw0")`` from the application
  30
  31 * Use ``--vdev="event_dsw0"`` in the EAL options, which will call
  32   rte_vdev_init() internally
  33
  34 Example:
  35
  36 .. code-block:: console
  37
  38     ./your_eventdev_application --vdev="event_dsw0"
  39
  40 Limitations
  41 -----------
  42
  43 Port Maintenance
  44 ~~~~~~~~~~~~~~~~
  45
  46 The distributed software eventdev uses an internal signaling scheme
  47 between the ports to achieve load balancing. Therefore, it sets the
  48 ``RTE_EVENT_DEV_CAP_REQUIRES_MAINT`` flag.
  49
  50 During periods when the application thread using a particular port is
  51 neither attempting to enqueue nor to dequeue events, it must
  52 repeatedly call rte_event_maintain() on that port.
  53
  54 Ports left unmaintained for long periods of time will prevent load
  55 balancing and cause traffic interruptions on flows which are in the
  56 process of being migrated.
  57
  58 Output Buffering
  59 ~~~~~~~~~~~~~~~~
  60
  61 For efficiency reasons, the distributed software eventdev might not
  62 send enqueued events immediately to the destination port, but instead
  63 store them in an internal buffer in the source port.
  64
  65 In case no more events are enqueued on a port with buffered events,
  66 these events will be sent after the application has performed a number
  67 of enqueue and/or dequeue operations.
  68
  69 To immediately flush a port's output buffer, an application may call
  70 rte_event_maintain() with op set to ``RTE_EVENT_DEV_MAINT_OP_FLUSH``.
  71
  72 Repeated calls to rte_event_maintain() will also flush the output
  73 buffers.
  74
  75
  76 Priorities
  77 ~~~~~~~~~~
  78
  79 The distributed software eventdev does not support event priorities.
  80
  81 Ordered Queues
  82 ~~~~~~~~~~~~~~
  83
  84 The distributed software eventdev does not support the ordered queue type.
  85
  86
  87 "All Types" Queues
  88 ~~~~~~~~~~~~~~~~~~
  89
  90 The distributed software eventdev does not support queues of type
  91 RTE_EVENT_QUEUE_CFG_ALL_TYPES, which allow both atomic, ordered, and
  92 parallel events on the same queue.
  93
  94 Dynamic Link/Unlink
  95 ~~~~~~~~~~~~~~~~~~~
  96
  97 The distributed software eventdev does not support calls to
  98 rte_event_port_link() or rte_event_port_unlink() after
  99 rte_event_dev_start() has been called.