1.. SPDX-License-Identifier: BSD-3-Clause 2 Copyright(c) 2017 Intel Corporation. 3 4OPDL Eventdev Poll Mode Driver 5================================== 6 7The OPDL (Ordered Packet Distribution Library) eventdev is a specific\ 8implementation of the eventdev API. It is particularly suited to packet\ 9processing workloads that have high throughput and low latency requirements.\ 10All packets follow the same path through the device. The order in which\ 11packets follow is determined by the order in which queues are set up.\ 12Events are left on the ring until they are transmitted. As a result packets\ 13do not go out of order 14 15 16Features 17-------- 18 19The OPDL eventdev implements a subset of features of the eventdev API; 20 21Queues 22 * Atomic 23 * Ordered (Parallel is supported as parallel is a subset of Ordered) 24 * Single-Link 25 26Ports 27 * Load balanced (for Atomic, Ordered, Parallel queues) 28 * Single Link (for single-link queues) 29 30 31Configuration and Options 32------------------------- 33 34The software eventdev is a vdev device, and as such can be created from the 35application 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 42Example: 43 44.. code-block:: console 45 46 ./your_eventdev_application --vdev="event_opdl0" 47 48 49Single Port Queue 50~~~~~~~~~~~~~~~~~ 51 52It is possible to create a Single Port Queue ``RTE_EVENT_QUEUE_CFG_SINGLE_LINK``. 53Packets dequeued from this queue do not need to be re-enqueued (as is the 54case with an ordered queue). The purpose of this queue is to allow for 55asynchronous handling of packets in the middle of a pipeline. Ordered 56queues in the middle of a pipeline cannot delete packets. 57 58 59Queue Dependencies 60~~~~~~~~~~~~~~~~~~ 61 62As stated the order in which packets travel through queues is static in 63nature. They go through the queues in the order the queues are setup at 64initialisation ``rte_event_queue_setup()``. For example if an application 65sets up 3 queues, Q0, Q1, Q2 and has 3 associated ports P0, P1, P2 and 66P3 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 82Limitations 83----------- 84 85The opdl implementation has a number of limitations. These limitations are 86due to the static nature of the underlying queues. It is because of this 87that the implementation can achieve such high throughput and low latency 88 89The following list is a comprehensive outline of the what is supported and 90the 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 118Validation & Statistics 119~~~~~~~~~~~~~~~~~~~~~~~ 120 121Validation 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 127If validation is turned on every packet (as opposed to just the first in 128each burst), is validated to have come from the right queue. Statistics 129are also produced in this mode. The statistics are available through the 130eventdev 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 137