From 46ea5781be2e630665056cbb2a456e7428febc0b Mon Sep 17 00:00:00 2001 From: =?utf8?q?Mattias=20R=C3=B6nnblom?= Date: Tue, 18 Sep 2018 14:45:14 +0200 Subject: [PATCH] event/dsw: add documentation MIME-Version: 1.0 Content-Type: text/plain; charset=utf8 Content-Transfer-Encoding: 8bit The DSW event device is documented in DPDK Programmer's Guide. The MAINTAINERS file and the 18.11 release notes are updated. Signed-off-by: Mattias Rönnblom Acked-by: Jerin Jacob --- MAINTAINERS | 1 + doc/guides/eventdevs/dsw.rst | 96 ++++++++++++++++++++++++++ doc/guides/eventdevs/index.rst | 1 + doc/guides/rel_notes/release_18_11.rst | 8 +++ 4 files changed, 106 insertions(+) create mode 100644 doc/guides/eventdevs/dsw.rst diff --git a/MAINTAINERS b/MAINTAINERS index 51010a2c04..e3b3eb7c5a 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -924,6 +924,7 @@ F: doc/guides/sample_app_ug/eventdev_pipeline.rst Distributed Software Eventdev PMD M: Mattias Rönnblom F: drivers/event/dsw/ +F: doc/guides/eventdevs/dsw.rst Software OPDL Eventdev PMD M: Liang Ma diff --git a/doc/guides/eventdevs/dsw.rst b/doc/guides/eventdevs/dsw.rst new file mode 100644 index 0000000000..6653f501c1 --- /dev/null +++ b/doc/guides/eventdevs/dsw.rst @@ -0,0 +1,96 @@ +.. SPDX-License-Identifier: BSD-3-Clause + Copyright(c) 2018 Ericsson AB + +Distributed Software Eventdev Poll Mode Driver +============================================== + +The distributed software event device is an eventdev driver which +distributes the task of scheduling events among all the eventdev ports +and the lcore threads using them. + +Features +-------- + +Queues + * Atomic + * Parallel + * Single-Link + +Ports + * Load balanced (for Atomic, Ordered, Parallel queues) + * Single Link (for single-link queues) + +Configuration and Options +------------------------- + +The distributed software eventdev is a vdev device, and as such can be +created from the application code, or from the EAL command line: + +* Call ``rte_vdev_init("event_dsw0")`` from the application + +* Use ``--vdev="event_dsw0"`` in the EAL options, which will call + rte_vdev_init() internally + +Example: + +.. code-block:: console + + ./your_eventdev_application --vdev="event_dsw0" + +Limitations +----------- + +Unattended Ports +~~~~~~~~~~~~~~~~ + +The distributed software eventdev uses an internal signaling schema +between the ports to achieve load balancing. In order for this to +work, the application must perform enqueue and/or dequeue operations +on all ports. + +Producer-only ports which currently have no events to enqueue should +periodically call rte_event_enqueue_burst() with a zero-sized burst. + +Ports left unattended for longer periods of time will prevent load +balancing, and also cause traffic interruptions on the flows which +are in the process of being migrated. + +Output Buffering +~~~~~~~~~~~~~~~~ + +For efficiency reasons, the distributed software eventdev might not +send enqueued events immediately to the destination port, but instead +store them in an internal buffer in the source port. + +In case no more events are enqueued on a port with buffered events, +these events will be sent after the application has performed a number +of enqueue and/or dequeue operations. + +For explicit flushing, an application may call +rte_event_enqueue_burst() with a zero-sized burst. + + +Priorities +~~~~~~~~~~ + +The distributed software eventdev does not support event priorities. + +Ordered Queues +~~~~~~~~~~~~~~ + +The distributed software eventdev does not support the ordered queue type. + + +"All Types" Queues +~~~~~~~~~~~~~~~~~~ + +The distributed software eventdev does not support queues of type +RTE_EVENT_QUEUE_CFG_ALL_TYPES, which allow both atomic, ordered, and +parallel events on the same queue. + +Dynamic Link/Unlink +~~~~~~~~~~~~~~~~~~~ + +The distributed software eventdev does not support calls to +rte_event_port_link() or rte_event_port_unlink() after +rte_event_dev_start() has been called. diff --git a/doc/guides/eventdevs/index.rst b/doc/guides/eventdevs/index.rst index 18ec8e4620..f7382dc8a3 100644 --- a/doc/guides/eventdevs/index.rst +++ b/doc/guides/eventdevs/index.rst @@ -13,6 +13,7 @@ application trough the eventdev API. dpaa dpaa2 + dsw sw octeontx opdl diff --git a/doc/guides/rel_notes/release_18_11.rst b/doc/guides/rel_notes/release_18_11.rst index 276e4ee92c..0e4be3a891 100644 --- a/doc/guides/rel_notes/release_18_11.rst +++ b/doc/guides/rel_notes/release_18_11.rst @@ -81,6 +81,14 @@ New Features * Support for runtime Rx and Tx queues setup. * Support multicast MAC address set. +* **Added Distributed Software Eventdev PMD.** + + Added the new Distributed Software Event Device (DSW), which is a + pure-software eventdev driver distributing the work of scheduling + among all eventdev ports and the lcores using them. DSW, compared to + the SW eventdev PMD, sacrifices load balancing performance to + gain better event scheduling throughput and scalability. + * **Added ability to switch queue deferred start flag on testpmd app.** Added a console command to testpmd app, giving ability to switch -- 2.20.1