From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mga04.intel.com (mga04.intel.com [192.55.52.120]) by dpdk.org (Postfix) with ESMTP id 496D41B14B for ; Thu, 20 Sep 2018 19:42:40 +0200 (CEST) X-Amp-Result: SKIPPED(no attachment in message) X-Amp-File-Uploaded: False Received: from orsmga006.jf.intel.com ([10.7.209.51]) by fmsmga104.fm.intel.com with ESMTP/TLS/DHE-RSA-AES256-GCM-SHA384; 20 Sep 2018 10:42:39 -0700 X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="5.54,281,1534834800"; d="scan'208";a="75970150" Received: from unknown (HELO localhost.localdomain.localdomain) ([10.224.122.193]) by orsmga006.jf.intel.com with ESMTP; 20 Sep 2018 10:42:33 -0700 From: Nikhil Rao To: jerin.jacob@caviumnetworks.com, olivier.matz@6wind.com, marko.kovacevic@intel.com, john.mcnamara@intel.com Cc: dev@dpdk.org, Nikhil Rao Date: Thu, 20 Sep 2018 23:11:16 +0530 Message-Id: <1537465276-77264-5-git-send-email-nikhil.rao@intel.com> X-Mailer: git-send-email 1.8.3.1 In-Reply-To: <1537465276-77264-1-git-send-email-nikhil.rao@intel.com> References: <1535694069-88757-1-git-send-email-nikhil.rao@intel.com> <1537465276-77264-1-git-send-email-nikhil.rao@intel.com> Subject: [dpdk-dev] [PATCH v4 5/5] doc: add event eth Tx adapter guide X-BeenThere: dev@dpdk.org X-Mailman-Version: 2.1.15 Precedence: list List-Id: DPDK patches and discussions List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Thu, 20 Sep 2018 17:42:41 -0000 Add programmer's guide doc to explain the use of the Event Ethernet Tx Adapter library. Signed-off-by: Nikhil Rao Acked-by: Jerin Jacob --- 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 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 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