doc/guides/eventdevs/sw.rst

   1 ..  SPDX-License-Identifier: BSD-3-Clause
   2     Copyright(c) 2017 Intel Corporation.
   3
   4 Software Eventdev Poll Mode Driver
   5 ==================================
   6
   7 The software eventdev is an implementation of the eventdev API, that provides a
   8 wide range of the eventdev features. The eventdev relies on a CPU core to
   9 perform event scheduling. This PMD can use the service core library to run the
  10 scheduling function, allowing an application to utilize the power of service
  11 cores to multiplex other work on the same core if required.
  12
  13
  14 Features
  15 --------
  16
  17 The software eventdev implements many features in the eventdev API;
  18
  19 Queues
  20  * Atomic
  21  * Ordered
  22  * Parallel
  23  * Single-Link
  24
  25 Ports
  26  * Load balanced (for Atomic, Ordered, Parallel queues)
  27  * Single Link (for single-link queues)
  28
  29 Event Priorities
  30  * Each event has a priority, which can be used to provide basic QoS
  31
  32
  33 Configuration and Options
  34 -------------------------
  35
  36 The software eventdev is a vdev device, and as such can be created from the
  37 application code, or from the EAL command line:
  38
  39 * Call ``rte_vdev_init("event_sw0")`` from the application
  40
  41 * Use ``--vdev="event_sw0"`` in the EAL options, which will call
  42   rte_vdev_init() internally
  43
  44 Example:
  45
  46 .. code-block:: console
  47
  48     ./your_eventdev_application --vdev="event_sw0"
  49
  50
  51 Scheduling Quanta
  52 ~~~~~~~~~~~~~~~~~
  53
  54 The scheduling quanta sets the number of events that the device attempts to
  55 schedule in a single schedule call performed by the service core. Note that
  56 is a *hint* only, and that fewer or more events may be scheduled in a given
  57 iteration.
  58
  59 The scheduling quanta can be set using a string argument to the vdev
  60 create call:
  61
  62 .. code-block:: console
  63
  64     --vdev="event_sw0,sched_quanta=64"
  65
  66
  67 Credit Quanta
  68 ~~~~~~~~~~~~~
  69
  70 The credit quanta is the number of credits that a port will fetch at a time from
  71 the instance's credit pool. Higher numbers will cause less overhead in the
  72 atomic credit fetch code, however it also reduces the overall number of credits
  73 in the system faster. A balanced number (e.g. 32) ensures that only small numbers
  74 of credits are pre-allocated at a time, while also mitigating performance impact
  75 of the atomics.
  76
  77 Experimentation with higher values may provide minor performance improvements,
  78 at the cost of the whole system having less credits. On the other hand,
  79 reducing the quanta may cause measurable performance impact but provide the
  80 system with a higher number of credits at all times.
  81
  82 A value of 32 seems a good balance however your specific application may
  83 benefit from a higher or reduced quanta size, experimentation is required to
  84 verify possible gains.
  85
  86 .. code-block:: console
  87
  88     --vdev="event_sw0,credit_quanta=64"
  89
  90
  91 Limitations
  92 -----------
  93
  94 The software eventdev implementation has a few limitations. The reason for
  95 these limitations is usually that the performance impact of supporting the
  96 feature would be significant.
  97
  98
  99 "All Types" Queues
 100 ~~~~~~~~~~~~~~~~~~
 101
 102 The software eventdev does not support creating queues that handle all types of
 103 traffic. An eventdev with this capability allows enqueuing Atomic, Ordered and
 104 Parallel traffic to the same queue, but scheduling each of them appropriately.
 105
 106 The reason to not allow Atomic, Ordered and Parallel event types in the
 107 same queue is that it causes excessive branching in the code to enqueue packets
 108 to the queue, causing a significant performance impact.
 109
 110 The ``RTE_EVENT_DEV_CAP_QUEUE_ALL_TYPES`` flag is not set in the
 111 ``event_dev_cap`` field of the ``rte_event_dev_info`` struct for the software
 112 eventdev.
 113
 114 Distributed Scheduler
 115 ~~~~~~~~~~~~~~~~~~~~~
 116
 117 The software eventdev is a centralized scheduler, requiring a service core to
 118 perform the required event distribution. This is not really a limitation but
 119 rather a design decision.
 120
 121 The ``RTE_EVENT_DEV_CAP_DISTRIBUTED_SCHED`` flag is not set in the
 122 ``event_dev_cap`` field of the ``rte_event_dev_info`` struct for the software
 123 eventdev.
 124
 125 Dequeue Timeout
 126 ~~~~~~~~~~~~~~~
 127
 128 The eventdev API supports a timeout when dequeuing packets using the
 129 ``rte_event_dequeue_burst`` function.
 130 This allows a core to wait for an event to arrive, or until ``timeout`` number
 131 of ticks have passed. Timeout ticks is not supported by the software eventdev
 132 for performance reasons.