doc/guides/eventdevs/sw.rst

   1 ..  BSD LICENSE
   2     Copyright(c) 2017 Intel Corporation. All rights reserved.
   3
   4     Redistribution and use in source and binary forms, with or without
   5     modification, are permitted provided that the following conditions
   6     are met:
   7
   8     * Redistributions of source code must retain the above copyright
   9     notice, this list of conditions and the following disclaimer.
  10     * Redistributions in binary form must reproduce the above copyright
  11     notice, this list of conditions and the following disclaimer in
  12     the documentation and/or other materials provided with the
  13     distribution.
  14     * Neither the name of Intel Corporation nor the names of its
  15     contributors may be used to endorse or promote products derived
  16     from this software without specific prior written permission.
  17
  18     THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  19     "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  20     LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  21     A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  22     OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  23     SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  24     LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  25     DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  26     THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  27     (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  28     OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  29
  30 Software Eventdev Poll Mode Driver
  31 ==================================
  32
  33 The software eventdev is an implementation of the eventdev API, that provides a
  34 wide range of the eventdev features. The eventdev relies on a CPU core to
  35 perform event scheduling.
  36
  37
  38 Features
  39 --------
  40
  41 The software eventdev implements many features in the eventdev API;
  42
  43 Queues
  44  * Atomic
  45  * Ordered
  46  * Parallel
  47  * Single-Link
  48
  49 Ports
  50  * Load balanced (for Atomic, Ordered, Parallel queues)
  51  * Single Link (for single-link queues)
  52
  53 Event Priorities
  54  * Each event has a priority, which can be used to provide basic QoS
  55
  56
  57 Configuration and Options
  58 -------------------------
  59
  60 The software eventdev is a vdev device, and as such can be created from the
  61 application code, or from the EAL command line:
  62
  63 * Call ``rte_vdev_init("event_sw0")`` from the application
  64
  65 * Use ``--vdev="event_sw0"`` in the EAL options, which will call
  66   rte_vdev_init() internally
  67
  68 Example:
  69
  70 .. code-block:: console
  71
  72     ./your_eventdev_application --vdev="event_sw0"
  73
  74
  75 Scheduling Quanta
  76 ~~~~~~~~~~~~~~~~~
  77
  78 The scheduling quanta sets the number of events that the device attempts to
  79 schedule before returning to the application from the ``rte_event_schedule()``
  80 function. Note that is a *hint* only, and that fewer or more events may be
  81 scheduled in a given iteration.
  82
  83 The scheduling quanta can be set using a string argument to the vdev
  84 create call:
  85
  86 .. code-block:: console
  87
  88     --vdev="event_sw0,sched_quanta=64"
  89
  90
  91 Credit Quanta
  92 ~~~~~~~~~~~~~
  93
  94 The credit quanta is the number of credits that a port will fetch at a time from
  95 the instance's credit pool. Higher numbers will cause less overhead in the
  96 atomic credit fetch code, however it also reduces the overall number of credits
  97 in the system faster. A balanced number (eg 32) ensures that only small numbers
  98 of credits are pre-allocated at a time, while also mitigating performance impact
  99 of the atomics.
 100
 101 Experimentation with higher values may provide minor performance improvements,
 102 at the cost of the whole system having less credits. On the other hand,
 103 reducing the quanta may cause measurable performance impact but provide the
 104 system with a higher number of credits at all times.
 105
 106 A value of 32 seems a good balance however your specific application may
 107 benefit from a higher or reduced quanta size, experimentation is required to
 108 verify possible gains.
 109
 110 .. code-block:: console
 111
 112     --vdev="event_sw0,credit_quanta=64"
 113
 114
 115 Limitations
 116 -----------
 117
 118 The software eventdev implementation has a few limitations. The reason for
 119 these limitations is usually that the performance impact of supporting the
 120 feature would be significant.
 121
 122
 123 "All Types" Queues
 124 ~~~~~~~~~~~~~~~~~~
 125
 126 The software eventdev does not support creating queues that handle all types of
 127 traffic. An eventdev with this capability allows enqueueing Atomic, Ordered and
 128 Parallel traffic to the same queue, but scheduling each of them appropriately.
 129
 130 The reason to not allow Atomic, Ordered and Parallel event types in the
 131 same queue is that it causes excessive branching in the code to enqueue packets
 132 to the queue, causing a significant performance impact.
 133
 134 The ``RTE_EVENT_DEV_CAP_QUEUE_ALL_TYPES`` flag is not set in the
 135 ``event_dev_cap`` field of the ``rte_event_dev_info`` struct for the software
 136 eventdev.
 137
 138 Distributed Scheduler
 139 ~~~~~~~~~~~~~~~~~~~~~
 140
 141 The software eventdev is a centralized scheduler, requiring the
 142 ``rte_event_schedule()`` function to be called by a CPU core to perform the
 143 required event distribution. This is not really a limitation but rather a
 144 design decision.
 145
 146 The ``RTE_EVENT_DEV_CAP_DISTRIBUTED_SCHED`` flag is not set in the
 147 ``event_dev_cap`` field of the ``rte_event_dev_info`` struct for the software
 148 eventdev.
 149
 150 Dequeue Timeout
 151 ~~~~~~~~~~~~~~~
 152
 153 The eventdev API supports a timeout when dequeuing packets using the
 154 ``rte_event_dequeue_burst`` function.
 155 This allows a core to wait for an event to arrive, or until ``timeout`` number
 156 of ticks have passed. Timeout ticks is not supported by the software eventdev
 157 for performance reasons.