From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mga12.intel.com (mga12.intel.com [192.55.52.136]) by dpdk.org (Postfix) with ESMTP id 9C5212BF7 for ; Fri, 31 Aug 2018 07:45:49 +0200 (CEST) X-Amp-Result: SKIPPED(no attachment in message) X-Amp-File-Uploaded: False Received: from fmsmga006.fm.intel.com ([10.253.24.20]) by fmsmga106.fm.intel.com with ESMTP/TLS/DHE-RSA-AES256-GCM-SHA384; 30 Aug 2018 22:45:46 -0700 X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="5.53,309,1531810800"; d="scan'208";a="259572934" Received: from unknown (HELO localhost.localdomain) ([10.224.122.193]) by fmsmga006.fm.intel.com with ESMTP; 30 Aug 2018 22:44:55 -0700 From: Nikhil Rao To: jerin.jacob@caviumnetworks.com, olivier.matz@6wind.com Cc: dev@dpdk.org, Nikhil Rao Date: Fri, 31 Aug 2018 11:11:09 +0530 Message-Id: <1535694069-88757-5-git-send-email-nikhil.rao@intel.com> X-Mailer: git-send-email 1.8.3.1 In-Reply-To: <1535694069-88757-1-git-send-email-nikhil.rao@intel.com> References: <1534479652-80182-1-git-send-email-nikhil.rao@intel.com> <1535694069-88757-1-git-send-email-nikhil.rao@intel.com> Subject: [dpdk-dev] [PATCH v3 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: Fri, 31 Aug 2018 05:45:50 -0000 Add programmer's guide doc to explain the use of the Event Ethernet Tx Adapter library. Signed-off-by: Nikhil Rao --- MAINTAINERS | 1 + .../prog_guide/event_ethernet_tx_adapter.rst | 165 +++++++++++++++++++++ doc/guides/prog_guide/index.rst | 1 + 3 files changed, 167 insertions(+) create mode 100644 doc/guides/prog_guide/event_ethernet_tx_adapter.rst diff --git a/MAINTAINERS b/MAINTAINERS index 6105a56..c98faf2b7 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..af657d0 --- /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_confi`` 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. + +Enqueueing 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 -- 1.8.3.1