From: Liang Ma <liang.j.ma@intel.com>
To: jerin.jacob@caviumnetworks.com
Cc: dev@dpdk.org, harry.van.haaren@intel.com,
bruce.richardson@intel.com, deepak.k.jain@intel.com,
john.geary@intel.com, peter.mccarthy@intel.com, seanbh@gmail.com
Subject: [dpdk-dev] [PATCH v5 12/12] doc: add eventdev opdl PMD guide
Date: Tue, 9 Jan 2018 12:20:23 +0000 [thread overview]
Message-ID: <1515500423-107720-13-git-send-email-liang.j.ma@intel.com> (raw)
In-Reply-To: <1515500423-107720-1-git-send-email-liang.j.ma@intel.com>
Add the description about opdl pmd
Signed-off-by: Liang Ma <liang.j.ma@intel.com>
Signed-off-by: Peter Mccarthy <peter.mccarthy@intel.com>
---
doc/guides/eventdevs/index.rst | 1 +
doc/guides/eventdevs/opdl.rst | 162 +++++++++++++++++++++++++++++++++++++++++
2 files changed, 163 insertions(+)
create mode 100644 doc/guides/eventdevs/opdl.rst
diff --git a/doc/guides/eventdevs/index.rst b/doc/guides/eventdevs/index.rst
index ba2048c..07a41bc 100644
--- a/doc/guides/eventdevs/index.rst
+++ b/doc/guides/eventdevs/index.rst
@@ -40,3 +40,4 @@ application trough the eventdev API.
dpaa2
sw
octeontx
+ opdl
diff --git a/doc/guides/eventdevs/opdl.rst b/doc/guides/eventdevs/opdl.rst
new file mode 100644
index 0000000..4922eaa
--- /dev/null
+++ b/doc/guides/eventdevs/opdl.rst
@@ -0,0 +1,162 @@
+.. BSD LICENSE
+ Copyright(c) 2017 Intel Corporation. All rights reserved.
+
+ Redistribution and use in source and binary forms, with or without
+ modification, are permitted provided that the following conditions
+ are met:
+
+ * Redistributions of source code must retain the above copyright
+ notice, this list of conditions and the following disclaimer.
+ * Redistributions in binary form must reproduce the above copyright
+ notice, this list of conditions and the following disclaimer in
+ the documentation and/or other materials provided with the
+ distribution.
+ * Neither the name of Intel Corporation nor the names of its
+ contributors may be used to endorse or promote products derived
+ from this software without specific prior written permission.
+
+ THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+ "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+ LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+ A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+ OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+ SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+ LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+ DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+ THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+ (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+OPDL Eventdev Poll Mode Driver
+==================================
+
+The OPDL (Ordered Packet Distribution Library) eventdev is a specific\
+implementation of the eventdev API. It is particularly suited to packet\
+processing workloads that have high throughput and low latency requirements.\
+All packets follow the same path through the device. The order in which\
+packets follow is determinted by the order in which queues are set up.\
+Events are left on the ring until they are transmitted. As a result packets\
+do not go out of order
+
+
+Features
+--------
+
+The OPDL eventdev implements a subset of features of the eventdev API;
+
+Queues
+ * Atomic
+ * Ordered (Parallel is supported as parallel is a subset of Ordered)
+ * Single-Link
+
+Ports
+ * Load balanced (for Atomic, Ordered, Parallel queues)
+ * Single Link (for single-link queues)
+
+
+Configuration and Options
+-------------------------
+
+The 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_opdl0")`` from the application
+
+* Use ``--vdev="event_opdl0"`` in the EAL options, which will call
+ rte_vdev_init() internally
+
+Example:
+
+.. code-block:: console
+
+ ./your_eventdev_application --vdev="event_opdl0"
+
+
+Single Port Queue
+~~~~~~~~~~~~~~~~~
+
+It is possible to create a Single Port Queue ``RTE_EVENT_QUEUE_CFG_SINGLE_LINK``.
+Packets dequeued from this queue do not need to be re-enqueued (as is the
+case with an ordered queue). The purpose of this queue is to allow for
+asynchronous handling of packets in the middle of a pipeline. Ordered
+queues in the middle of a pipeline cannot delete packets.
+
+
+Queue Dependencies
+~~~~~~~~~~~~~~~~~~
+
+As stated the order in which packets travel through queues is static in
+nature. They go through the queues in the order the queues are setup at
+initialisation ``rte_event_queue_setup()``. For example if an application
+sets up 3 queues, Q0, Q1, Q2 and has 3 assoicated ports P0, P1, P2 and
+P3 then packets must be
+
+ * Enqueued onto Q0 (typically through P0), then
+
+ * Dequeued from Q0 (typically through P1), then
+
+ * Enqueued onto Q1 (also through P1), then
+
+ * Dequeued from Q2 (typically through P2), then
+
+ * Enqueued onto Q3 (also through P2), then
+
+ * Dequeued from Q3 (typically through P3) and then transmitted on the relevant \
+ eth port
+
+
+Limitations
+-----------
+
+The opdl implementation has a number of limitations. These limitations are
+due to the static nature of the underlying queues. It is because of this
+that the implementation can achieve such high throughput and low latency
+
+The following list is a comprehensive outline of the what is supported and
+the limitations / restrictions imposed by the opdl pmd
+
+ - The order in which packets moved between queues is static and fixed \
+ (dynamic scheduling is not supported).
+
+ - NEW, RELEASE are not explicitly supported. RX (first enqueue) implicitly \
+ adds NEW event types, and TX (last dequeue) implicitly does RELEASE event types.
+
+ - All packets follow the same path through device queues.
+
+ - Flows within queues are NOT supported.
+
+ - Event priority is NOT supported.
+
+ - Once the device is stopped all inflight events are lost. Applications should \
+ clear all inflight events before stopping it.
+
+ - Each port can only be associated with one queue.
+
+ - Each queue can have multiple ports associated with it.
+
+ - Each worker core has to dequeue the maximum burst size for that port.
+
+ - For performance, the rte_event flow_id should not be updated once packet\
+ is enqueued on RX.
+
+
+
+Validation & Statistics
+~~~~~~~~~~~~~~~~~~~~~~~
+
+Validation can be turned on through a command line parameter
+
+.. code-block:: console
+
+ --vdev="event_opdl0,do_validation=1,self_test=1"
+
+If validation is turned on every packet (as opposed to just the first in
+each burst), is validated to have come from the right queue. Statistics
+are also produced in this mode. The statistics are available through the
+eventdev xstats API. Statistics are per port as follows:
+
+ - claim_pkts_requested
+ - claim_pkts_granted
+ - claim_non_empty
+ - claim_empty
+ - total_cycles
--
2.7.5
next prev parent reply other threads:[~2018-01-09 12:20 UTC|newest]
Thread overview: 64+ messages / expand[flat|nested] mbox.gz Atom feed top
2017-12-22 11:23 [dpdk-dev] [RFC v4 PATCH 0/8] event: eventdev OPDL PMD Liang Ma
2017-12-22 11:23 ` [dpdk-dev] [PATCH v4 1/8] event/opdl: add the opdl ring infrastructure library Liang Ma
2017-12-22 16:02 ` Sean Harte
2018-01-08 6:46 ` Jerin Jacob
2018-01-08 11:19 ` Liang, Ma
2018-01-08 11:23 ` Jerin Jacob
2017-12-22 11:23 ` [dpdk-dev] [PATCH v4 2/8] event/opdl: add the opdl pmd main body and helper function Liang Ma
2017-12-22 11:23 ` [dpdk-dev] [PATCH v4 3/8] eventdev/opdl: opdl eventdev pmd unit test function Liang Ma
2017-12-22 11:23 ` [dpdk-dev] [PATCH v4 4/8] lib/librte_eventdev: extend the eventdev capability flags Liang Ma
2018-01-08 6:32 ` Jerin Jacob
2017-12-22 11:23 ` [dpdk-dev] [PATCH v4 5/8] event/*: apply the three new capability flags for sw/dppa2/octeontx Liang Ma
2017-12-22 11:23 ` [dpdk-dev] [PATCH v4 6/8] maintainers: add the opdl pmd maintainer information Liang Ma
2017-12-23 15:05 ` Thomas Monjalon
2017-12-22 11:23 ` [dpdk-dev] [PATCH v4 7/8] doc:update 18.02 release notes Liang Ma
2017-12-22 11:23 ` [dpdk-dev] [PATCH v4 8/8] doc: add eventdev opdl pmd docuement Liang Ma
2017-12-23 15:06 ` [dpdk-dev] [RFC v4 PATCH 0/8] event: eventdev OPDL PMD Thomas Monjalon
2018-01-09 12:20 ` [dpdk-dev] [RFC v5 PATCH 00/12] " Liang Ma
2018-01-09 12:20 ` [dpdk-dev] [PATCH v5 01/12] event/opdl: add the opdl ring infrastructure library Liang Ma
2018-01-09 12:20 ` [dpdk-dev] [PATCH v5 02/12] event/opdl: add opdl PMD main body and helper function Liang Ma
2018-01-09 12:20 ` [dpdk-dev] [PATCH v5 03/12] event/opdl: add event queue config get/set support Liang Ma
2018-01-09 12:20 ` [dpdk-dev] [PATCH v5 04/12] event/opdl: add event port " Liang Ma
2018-01-09 12:20 ` [dpdk-dev] [PATCH v5 05/12] event/opdl: add eventdev enqueue/dequeue support Liang Ma
2018-01-09 12:20 ` [dpdk-dev] [PATCH v5 06/12] event/opdl: opdl eventdev PMD unit test function Liang Ma
2018-01-09 12:20 ` [dpdk-dev] [PATCH v5 07/12] lib/librte_eventdev: extend the eventdev capability flags Liang Ma
2018-01-09 12:27 ` Jerin Jacob
2018-01-09 12:20 ` [dpdk-dev] [PATCH v5 08/12] event/dpaa2: apply the three new " Liang Ma
2018-01-09 12:20 ` [dpdk-dev] [PATCH v5 09/12] event/octeontx: " Liang Ma
2018-01-09 12:20 ` [dpdk-dev] [PATCH v5 10/12] event/sw: " Liang Ma
2018-01-09 12:20 ` [dpdk-dev] [PATCH v5 11/12] doc: update 18.02 release notes and maintainers info Liang Ma
2018-01-09 12:20 ` Liang Ma [this message]
2018-01-09 14:18 ` [dpdk-dev] [RFC v6 PATCH 00/12] event: eventdev OPDL PMD Liang Ma
2018-01-09 14:18 ` [dpdk-dev] [PATCH v6 01/12] event/opdl: add the opdl ring infrastructure library Liang Ma
2018-01-10 10:00 ` Sean Harte
2018-01-09 14:18 ` [dpdk-dev] [PATCH v6 02/12] event/opdl: add opdl PMD main body and helper function Liang Ma
2018-01-09 14:18 ` [dpdk-dev] [PATCH v6 03/12] event/opdl: add event queue config get/set support Liang Ma
2018-01-09 14:18 ` [dpdk-dev] [PATCH v6 04/12] event/opdl: add event port " Liang Ma
2018-01-09 14:18 ` [dpdk-dev] [PATCH v6 05/12] event/opdl: add eventdev enqueue/dequeue support Liang Ma
2018-01-09 14:18 ` [dpdk-dev] [PATCH v6 06/12] event/opdl: opdl eventdev PMD unit test function Liang Ma
2018-01-09 14:18 ` [dpdk-dev] [PATCH v6 07/12] event/opdl: extend the eventdev capability flags Liang Ma
2018-01-09 14:18 ` [dpdk-dev] [PATCH v6 08/12] event/dpaa2: apply the three new " Liang Ma
2018-01-09 14:18 ` [dpdk-dev] [PATCH v6 09/12] event/octeontx: " Liang Ma
2018-01-09 14:18 ` [dpdk-dev] [PATCH v6 10/12] event/sw: " Liang Ma
2018-01-09 14:19 ` [dpdk-dev] [PATCH v6 11/12] doc: update 18.02 release notes and maintainers info Liang Ma
2018-01-10 10:38 ` Kovacevic, Marko
2018-01-09 14:19 ` [dpdk-dev] [PATCH v6 12/12] doc: add eventdev opdl PMD guide Liang Ma
2018-01-09 17:13 ` [dpdk-dev] [RFC v6 PATCH 00/12] event: eventdev OPDL PMD Van Haaren, Harry
2018-01-10 14:45 ` [dpdk-dev] [RFC v7 " Liang Ma
2018-01-10 14:46 ` [dpdk-dev] [PATCH v7 01/12] event/opdl: add the opdl ring infrastructure library Liang Ma
2018-01-10 14:46 ` [dpdk-dev] [PATCH v7 02/12] event/opdl: add opdl PMD main body and helper function Liang Ma
2018-01-10 14:46 ` [dpdk-dev] [PATCH v7 03/12] event/opdl: add event queue config get/set support Liang Ma
2018-01-10 14:46 ` [dpdk-dev] [PATCH v7 04/12] event/opdl: add event port " Liang Ma
2018-01-10 14:46 ` [dpdk-dev] [PATCH v7 05/12] event/opdl: add eventdev enqueue/dequeue support Liang Ma
2018-01-10 14:46 ` [dpdk-dev] [PATCH v7 06/12] event/opdl: opdl eventdev PMD unit test function Liang Ma
2018-01-10 14:46 ` [dpdk-dev] [PATCH v7 07/12] event/opdl: extend the eventdev capability flags Liang Ma
2018-01-10 14:46 ` [dpdk-dev] [PATCH v7 08/12] event/dpaa2: apply the three new " Liang Ma
2018-01-10 14:46 ` [dpdk-dev] [PATCH v7 09/12] event/octeontx: " Liang Ma
2018-01-10 14:46 ` [dpdk-dev] [PATCH v7 10/12] event/sw: " Liang Ma
2018-01-10 14:46 ` [dpdk-dev] [PATCH v7 11/12] doc: update 18.02 release notes and maintainers info Liang Ma
2018-01-10 15:01 ` Kovacevic, Marko
2018-01-10 14:46 ` [dpdk-dev] [PATCH v7 12/12] doc: add eventdev opdl PMD guide Liang Ma
2018-01-10 15:01 ` Jerin Jacob
2018-01-10 15:08 ` Liang, Ma
2018-01-10 18:17 ` Jerin Jacob
2018-01-10 15:04 ` Kovacevic, Marko
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=1515500423-107720-13-git-send-email-liang.j.ma@intel.com \
--to=liang.j.ma@intel.com \
--cc=bruce.richardson@intel.com \
--cc=deepak.k.jain@intel.com \
--cc=dev@dpdk.org \
--cc=harry.van.haaren@intel.com \
--cc=jerin.jacob@caviumnetworks.com \
--cc=john.geary@intel.com \
--cc=peter.mccarthy@intel.com \
--cc=seanbh@gmail.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).