[dpdk-dev] [PATCH v4 10/10] event/dsw: include DSW event device documentation

["Mattias Rönnblom" <mattias.ronnblom@ericsson.com>]

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 <mattias.ronnblom@ericsson.com>
---
 MAINTAINERS                            |  5 ++
 doc/guides/eventdevs/dsw.rst           | 96 ++++++++++++++++++++++++++
 doc/guides/eventdevs/index.rst         |  1 +
 doc/guides/rel_notes/release_18_11.rst |  8 +++
 4 files changed, 110 insertions(+)
 create mode 100644 doc/guides/eventdevs/dsw.rst

diff --git a/MAINTAINERS b/MAINTAINERS
index 9fd258fad..cbfa7e106 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -919,6 +919,11 @@ F: doc/guides/eventdevs/sw.rst
 F: examples/eventdev_pipeline/
 F: doc/guides/sample_app_ug/eventdev_pipeline.rst
 
+Distributed Software Eventdev PMD
+M: Mattias Rönnblom <mattias.ronnblom@ericsson.com>
+F: drivers/event/dsw/
+F: doc/guides/eventdevs/dsw.rst
+
 Software OPDL Eventdev PMD
 M: Liang Ma <liang.j.ma@intel.com>
 M: Peter Mccarthy <peter.mccarthy@intel.com>
diff --git a/doc/guides/eventdevs/dsw.rst b/doc/guides/eventdevs/dsw.rst
new file mode 100644
index 000000000..6653f501c
--- /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 18ec8e462..984eea5f4 100644
--- a/doc/guides/eventdevs/index.rst
+++ b/doc/guides/eventdevs/index.rst
@@ -14,5 +14,6 @@ application trough the eventdev API.
     dpaa
     dpaa2
     sw
+    dsw
     octeontx
     opdl
diff --git a/doc/guides/rel_notes/release_18_11.rst b/doc/guides/rel_notes/release_18_11.rst
index 3ae6b3f58..9c6b1fd0b 100644
--- a/doc/guides/rel_notes/release_18_11.rst
+++ b/doc/guides/rel_notes/release_18_11.rst
@@ -54,6 +54,14 @@ New Features
      Also, make sure to start the actual text at the margin.
      =========================================================
 
+* **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.
+
 
 API Changes
 -----------
-- 
2.17.1