DPDK patches and discussions
 help / color / mirror / Atom feed
From: Nikhil Rao <nikhil.rao@intel.com>
To: jerin.jacob@caviumnetworks.com, olivier.matz@6wind.com,
	marko.kovacevic@intel.com, john.mcnamara@intel.com
Cc: dev@dpdk.org, Nikhil Rao <nikhil.rao@intel.com>
Subject: [dpdk-dev] [PATCH v4 5/5] doc: add event eth Tx adapter guide
Date: Thu, 20 Sep 2018 23:11:16 +0530	[thread overview]
Message-ID: <1537465276-77264-5-git-send-email-nikhil.rao@intel.com> (raw)
In-Reply-To: <1537465276-77264-1-git-send-email-nikhil.rao@intel.com>

Add programmer's guide doc to explain the use of the
Event Ethernet Tx Adapter library.

Signed-off-by: Nikhil Rao <nikhil.rao@intel.com>
Acked-by: Jerin Jacob <jerin.jacob@caviumnetworks.com>
---
 MAINTAINERS                                        |   1 +
 .../prog_guide/event_ethernet_tx_adapter.rst       | 165 +++++++++++++++++++++
 doc/guides/prog_guide/index.rst                    |   1 +
 doc/guides/rel_notes/release_18_11.rst             |   8 +
 4 files changed, 175 insertions(+)
 create mode 100644 doc/guides/prog_guide/event_ethernet_tx_adapter.rst

diff --git a/MAINTAINERS b/MAINTAINERS
index 93699ba..6f6755c 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -396,6 +396,7 @@ M: Nikhil Rao <nikhil.rao@intel.com>
 T: git://dpdk.org/next/dpdk-next-eventdev
 F: lib/librte_eventdev/*eth_tx_adapter*
 F: test/test/test_event_eth_tx_adapter.c
+F: doc/guides/prog_guide/event_ethernet_tx_adapter.rst
 
 Raw device API - EXPERIMENTAL
 M: Shreyansh Jain <shreyansh.jain@nxp.com>
diff --git a/doc/guides/prog_guide/event_ethernet_tx_adapter.rst b/doc/guides/prog_guide/event_ethernet_tx_adapter.rst
new file mode 100644
index 0000000..192f9e1
--- /dev/null
+++ b/doc/guides/prog_guide/event_ethernet_tx_adapter.rst
@@ -0,0 +1,165 @@
+..  SPDX-License-Identifier: BSD-3-Clause
+    Copyright(c) 2017 Intel Corporation.
+
+Event Ethernet Tx Adapter Library
+=================================
+
+The DPDK Eventdev API allows the application to use an event driven programming
+model for packet processing in which the event device distributes events
+referencing packets to the application cores in a dynamic load balanced fashion
+while handling atomicity and packet ordering. Event adapters provide the interface
+between the ethernet, crypto and timer devices and the event device. Event adapter
+APIs enable common application code by abstracting PMD specific capabilities.
+The Event ethernet Tx adapter provides configuration and data path APIs for the
+transmit stage of the application allowing the same application code to use eventdev
+PMD support or in its absence, a common implementation.
+
+In the common implementation, the application enqueues mbufs to the adapter
+which runs as a rte_service function. The service function dequeues events
+from its event port and transmits the mbufs referenced by these events.
+
+
+API Walk-through
+----------------
+
+This section will introduce the reader to the adapter API. The
+application has to first instantiate an adapter which is associated with
+a single eventdev, next the adapter instance is configured with Tx queues,
+finally the adapter is started and the application can start enqueuing mbufs
+to it.
+
+Creating an Adapter Instance
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+An adapter instance is created using ``rte_event_eth_tx_adapter_create()``. This
+function is passed the event device to be associated with the adapter and port
+configuration for the adapter to setup an event port if the adapter needs to use
+a service function.
+
+If the application desires to have finer control of eventdev port configuration,
+it can use the ``rte_event_eth_tx_adapter_create_ext()`` function. The
+``rte_event_eth_tx_adapter_create_ext()`` function is passed a callback function.
+The callback function is invoked if the adapter needs to use a service function
+and needs to create an event port for it. The callback is expected to fill the
+``struct rte_event_eth_tx_adapter_conf`` structure passed to it.
+
+.. code-block:: c
+
+        struct rte_event_dev_info dev_info;
+        struct rte_event_port_conf tx_p_conf = {0};
+
+        err = rte_event_dev_info_get(id, &dev_info);
+
+        tx_p_conf.new_event_threshold = dev_info.max_num_events;
+        tx_p_conf.dequeue_depth = dev_info.max_event_port_dequeue_depth;
+        tx_p_conf.enqueue_depth = dev_info.max_event_port_enqueue_depth;
+
+        err = rte_event_eth_tx_adapter_create(id, dev_id, &tx_p_conf);
+
+Adding Tx Queues to the Adapter Instance
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Ethdev Tx queues are added to the instance using the
+``rte_event_eth_tx_adapter_queue_add()`` function. A queue value
+of -1 is used to indicate all queues within a device.
+
+.. code-block:: c
+
+        int err = rte_event_eth_tx_adapter_queue_add(id,
+						     eth_dev_id,
+						     q);
+
+Querying Adapter Capabilities
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The ``rte_event_eth_tx_adapter_caps_get()`` function allows
+the application to query the adapter capabilities for an eventdev and ethdev
+combination. Currently, the only capability flag defined is
+``RTE_EVENT_ETH_TX_ADAPTER_CAP_INTERNAL_PORT``, the application can
+query this flag to determine if a service function is associated with the
+adapter and retrieve its service identifier using the
+``rte_event_eth_tx_adapter_service_id_get()`` API.
+
+
+.. code-block:: c
+
+        int err = rte_event_eth_tx_adapter_caps_get(dev_id, eth_dev_id, &cap);
+
+        if (!(cap & RTE_EVENT_ETH_TX_ADAPTER_CAP_INTERNAL_PORT))
+                err = rte_event_eth_tx_adapter_service_id_get(id, &service_id);
+
+Linking a Queue to the Adapter's Event Port
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If the adapter uses a service function as described in the previous section, the
+application is required to link a queue to the adapter's event port. The adapter's
+event port can be obtained using the ``rte_event_eth_tx_adapter_event_port_get()``
+function. The queue can be configured with the ``RTE_EVENT_QUEUE_CFG_SINGLE_LINK``
+since it is linked to a single event port.
+
+Configuring the Service Function
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If the adapter uses a service function, the application can assign
+a service core to the service function as shown below.
+
+.. code-block:: c
+
+        if (rte_event_eth_tx_adapter_service_id_get(id, &service_id) == 0)
+                rte_service_map_lcore_set(service_id, TX_CORE_ID);
+
+Starting the Adapter Instance
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The application calls ``rte_event_eth_tx_adapter_start()`` to start the adapter.
+This function calls the start callback of the eventdev PMD if supported,
+and the ``rte_service_run_state_set()`` to enable the service function if one exists.
+
+Enqueuing Packets to the Adapter
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The application needs to notify the adapter about the transmit port and queue used
+to send the packet. The transmit port is set in the ``struct rte mbuf::port`` field
+and the transmit queue is set using the ``rte_event_eth_tx_adapter_txq_set()``
+function.
+
+If the eventdev PMD supports the ``RTE_EVENT_ETH_TX_ADAPTER_CAP_INTERNAL_PORT``
+capability for a given ethernet device, the application should use the
+``rte_event_eth_tx_adapter_enqueue()`` function to enqueue packets to the adapter.
+
+If the adapter uses a service function for the ethernet device then the application
+should use the ``rte_event_enqueue_burst()`` function.
+
+.. code-block:: c
+
+	struct rte_event event;
+
+	if (cap & RTE_EVENT_ETH_TX_ADAPTER_CAP_INTERNAL_PORT) {
+
+		event.mbuf = m;
+
+		m->port = tx_port;
+		rte_event_eth_tx_adapter_txq_set(m, tx_queue_id);
+
+		rte_event_eth_tx_adapter_enqueue(dev_id, ev_port, &event, 1);
+	} else {
+
+		event.queue_id = qid; /* event queue linked to adapter port */
+		event.op = RTE_EVENT_OP_NEW;
+		event.event_type = RTE_EVENT_TYPE_CPU;
+		event.sched_type = RTE_SCHED_TYPE_ATOMIC;
+		event.mbuf = m;
+
+		m->port = tx_port;
+		rte_event_eth_tx_adapter_txq_set(m, tx_queue_id);
+
+		rte_event_enqueue_burst(dev_id, ev_port, &event, 1);
+	}
+
+Getting Adapter Statistics
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The  ``rte_event_eth_tx_adapter_stats_get()`` function reports counters defined
+in struct ``rte_event_eth_tx_adapter_stats``. The counter values are the sum of
+the counts from the eventdev PMD callback if the callback is supported, and
+the counts maintained by the service function, if one exists.
diff --git a/doc/guides/prog_guide/index.rst b/doc/guides/prog_guide/index.rst
index 3b920e5..c81d9c5 100644
--- a/doc/guides/prog_guide/index.rst
+++ b/doc/guides/prog_guide/index.rst
@@ -44,6 +44,7 @@ Programmer's Guide
     thread_safety_dpdk_functions
     eventdev
     event_ethernet_rx_adapter
+    event_ethernet_tx_adapter
     event_timer_adapter
     event_crypto_adapter
     qos_framework
diff --git a/doc/guides/rel_notes/release_18_11.rst b/doc/guides/rel_notes/release_18_11.rst
index 97daad1..7f2636a 100644
--- a/doc/guides/rel_notes/release_18_11.rst
+++ b/doc/guides/rel_notes/release_18_11.rst
@@ -67,6 +67,14 @@ New Features
   SR-IOV option in Hyper-V and Azure. This is an alternative to the previous
   vdev_netvsc, tap, and failsafe drivers combination.
 
+* **Added Event Ethernet Tx Adapter.**
+
+  Added event ethernet Tx adapter library that  provides configuration and
+  data path APIs for the ethernet transmit stage of an event driven packet
+  processing application. These APIs abstract the implementation of the
+  transmit stage and allow the application to use eventdev PMD support or
+  a common implementation.
+
 * **Added Distributed Software Eventdev PMD.**
 
   Added the new Distributed Software Event Device (DSW), which is a
-- 
1.8.3.1

  parent reply	other threads:[~2018-09-20 17:42 UTC|newest]

Thread overview: 27+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2018-08-17  4:20 [dpdk-dev] [PATCH v2 1/4] eventdev: add eth Tx adapter APIs Nikhil Rao
2018-08-17  4:20 ` [dpdk-dev] [PATCH v2 2/4] eventdev: add caps API and PMD callbacks for eth Tx adapter Nikhil Rao
2018-08-19 10:45   ` Jerin Jacob
2018-08-21  8:52     ` Rao, Nikhil
2018-08-21  9:11       ` Jerin Jacob
2018-08-22 13:34         ` Rao, Nikhil
2018-08-17  4:20 ` [dpdk-dev] [PATCH v2 3/4] eventdev: add eth Tx adapter implementation Nikhil Rao
2018-08-17  4:20 ` [dpdk-dev] [PATCH v2 4/4] eventdev: add auto test for eth Tx adapter Nikhil Rao
2018-08-17 11:55   ` Pavan Nikhilesh
2018-08-22 16:13     ` Rao, Nikhil
2018-08-22 16:23       ` Pavan Nikhilesh
2018-08-23  1:48         ` Rao, Nikhil
2018-08-19 10:19 ` [dpdk-dev] [PATCH v2 1/4] eventdev: add eth Tx adapter APIs Jerin Jacob
2018-08-31  5:41 ` [dpdk-dev] [PATCH v3 1/5] " Nikhil Rao
2018-08-31  5:41   ` [dpdk-dev] [PATCH v3 2/5] eventdev: add caps API and PMD callbacks for eth Tx adapter Nikhil Rao
2018-08-31  5:41   ` [dpdk-dev] [PATCH v3 3/5] eventdev: add eth Tx adapter implementation Nikhil Rao
2018-08-31  5:41   ` [dpdk-dev] [PATCH v3 4/5] eventdev: add auto test for eth Tx adapter Nikhil Rao
2018-09-17 14:00     ` Jerin Jacob
2018-08-31  5:41   ` [dpdk-dev] [PATCH v3 5/5] doc: add event eth Tx adapter guide Nikhil Rao
2018-09-17 13:56     ` Jerin Jacob
2018-09-20 17:41   ` [dpdk-dev] [PATCH v4 1/5] eventdev: add eth Tx adapter APIs Nikhil Rao
2018-09-20 17:41     ` [dpdk-dev] [PATCH v4 2/5] eventdev: add caps API and PMD callbacks for eth Tx adapter Nikhil Rao
2018-09-20 17:41     ` [dpdk-dev] [PATCH v4 3/5] eventdev: add eth Tx adapter implementation Nikhil Rao
2018-09-20 17:41     ` [dpdk-dev] [PATCH v4 4/5] eventdev: add auto test for eth Tx adapter Nikhil Rao
2018-09-20 17:41     ` Nikhil Rao [this message]
2018-09-21  5:04     ` [dpdk-dev] [PATCH v4 1/5] eventdev: add eth Tx adapter APIs Jerin Jacob
2018-09-28 10:05     ` Jerin Jacob

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=1537465276-77264-5-git-send-email-nikhil.rao@intel.com \
    --to=nikhil.rao@intel.com \
    --cc=dev@dpdk.org \
    --cc=jerin.jacob@caviumnetworks.com \
    --cc=john.mcnamara@intel.com \
    --cc=marko.kovacevic@intel.com \
    --cc=olivier.matz@6wind.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).