doc/guides/eventdevs/opdl.rst

   1 ..  BSD LICENSE
   2     Copyright(c) 2017 Intel Corporation. All rights reserved.
   3
   4 OPDL Eventdev Poll Mode Driver
   5 ==================================
   6
   7 The OPDL (Ordered Packet Distribution Library) eventdev is a specific\
   8 implementation of the eventdev API. It is particularly suited to packet\
   9 processing workloads that have high throughput and low latency requirements.\
  10 All packets follow the same path through the device. The order in which\
  11 packets  follow is determinted by the order in which queues are set up.\
  12 Events are left on the ring until they are transmitted. As a result packets\
  13 do not go out of order
  14
  15
  16 Features
  17 --------
  18
  19 The OPDL  eventdev implements a subset of features of the eventdev API;
  20
  21 Queues
  22  * Atomic
  23  * Ordered (Parallel is supported as parallel is a subset of Ordered)
  24  * Single-Link
  25
  26 Ports
  27  * Load balanced (for Atomic, Ordered, Parallel queues)
  28  * Single Link (for single-link queues)
  29
  30
  31 Configuration and Options
  32 -------------------------
  33
  34 The software eventdev is a vdev device, and as such can be created from the
  35 application code, or from the EAL command line:
  36
  37 * Call ``rte_vdev_init("event_opdl0")`` from the application
  38
  39 * Use ``--vdev="event_opdl0"`` in the EAL options, which will call
  40   rte_vdev_init() internally
  41
  42 Example:
  43
  44 .. code-block:: console
  45
  46     ./your_eventdev_application --vdev="event_opdl0"
  47
  48
  49 Single Port Queue
  50 ~~~~~~~~~~~~~~~~~
  51
  52 It is possible to create a Single Port Queue ``RTE_EVENT_QUEUE_CFG_SINGLE_LINK``.
  53 Packets dequeued from this queue do not need to be re-enqueued (as is the
  54 case with an ordered queue). The purpose of this queue is to allow for
  55 asynchronous handling of packets in the middle of a pipeline. Ordered
  56 queues in the middle of a pipeline cannot delete packets.
  57
  58
  59 Queue Dependencies
  60 ~~~~~~~~~~~~~~~~~~
  61
  62 As stated the order in which packets travel through queues is static in
  63 nature. They go through the queues in the order the queues are setup at
  64 initialisation ``rte_event_queue_setup()``. For example if an application
  65 sets up 3 queues, Q0, Q1, Q2 and has 3 associated ports P0, P1, P2 and
  66 P3 then packets must be
  67
  68  * Enqueued onto Q0 (typically through P0), then
  69
  70  * Dequeued from Q0 (typically through P1), then
  71
  72  * Enqueued onto Q1 (also through P1), then
  73
  74  * Dequeued from Q2 (typically through P2),  then
  75
  76  * Enqueued onto Q3 (also through P2), then
  77
  78  * Dequeued from Q3 (typically through P3) and then transmitted on the relevant \
  79    eth port
  80
  81
  82 Limitations
  83 -----------
  84
  85 The opdl implementation has a number of limitations. These limitations are
  86 due to the static nature of the underlying queues. It is because of this
  87 that the implementation can achieve such high throughput and low latency
  88
  89 The following list is a comprehensive outline of the what is supported and
  90 the limitations / restrictions imposed by the opdl pmd
  91
  92  - The order in which packets moved between queues is static and fixed \
  93    (dynamic scheduling is not supported).
  94
  95  - NEW, RELEASE are not explicitly supported. RX (first enqueue) implicitly \
  96    adds NEW event types, and TX (last dequeue) implicitly does RELEASE event types.
  97
  98  - All packets follow the same path through device queues.
  99
 100  - Flows within queues are NOT supported.
 101
 102  - Event priority is NOT supported.
 103
 104  - Once the device is stopped all inflight events are lost. Applications should \
 105    clear all inflight events before stopping it.
 106
 107  - Each port can only be associated with one queue.
 108
 109  - Each queue can have multiple ports associated with it.
 110
 111  - Each worker core has to dequeue the maximum burst size for that port.
 112
 113  - For performance, the rte_event flow_id should not be updated once packet\
 114    is enqueued on RX.
 115
 116
 117
 118 Validation & Statistics
 119 ~~~~~~~~~~~~~~~~~~~~~~~
 120
 121 Validation can be turned on through a command line parameter
 122
 123 .. code-block:: console
 124
 125     --vdev="event_opdl0,do_validation=1,self_test=1"
 126
 127 If validation is turned on every packet (as opposed to just the first in
 128 each burst), is validated to have come from the right queue. Statistics
 129 are also produced in this mode. The statistics are available through the
 130 eventdev xstats API. Statistics are per port as follows:
 131
 132  - claim_pkts_requested
 133  - claim_pkts_granted
 134  - claim_non_empty
 135  - claim_empty
 136  - total_cycles