From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mga03.intel.com (mga03.intel.com [134.134.136.65]) by dpdk.org (Postfix) with ESMTP id 92B201B61B for ; Wed, 18 Oct 2017 11:18:28 +0200 (CEST) Received: from fmsmga003.fm.intel.com ([10.253.24.29]) by orsmga103.jf.intel.com with ESMTP/TLS/DHE-RSA-AES256-GCM-SHA384; 18 Oct 2017 02:18:27 -0700 X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="5.43,395,1503385200"; d="scan'208";a="911049493" Received: from unknown (HELO localhost.iind.intel.com) ([10.224.122.216]) by FMSMGA003.fm.intel.com with ESMTP; 18 Oct 2017 02:18:25 -0700 From: Nikhil Rao To: jerin.jacob@caviumnetworks.com Cc: dev@dpdk.org Date: Wed, 18 Oct 2017 14:45:41 +0530 Message-Id: <1508318141-11256-1-git-send-email-nikhil.rao@intel.com> X-Mailer: git-send-email 2.7.4 Subject: [dpdk-dev] [PATCH] doc: add event eth Rx adapter programmer's 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: Wed, 18 Oct 2017 09:18:29 -0000 Add programmer's guide doc to explain the use of the Event Ethernet Rx Adapter library. Signed-off-by: Nikhil Rao --- .../prog_guide/event_ethernet_rx_adapter.rst | 160 +++++++++++++++++++++ doc/guides/prog_guide/index.rst | 1 + 2 files changed, 161 insertions(+) create mode 100644 doc/guides/prog_guide/event_ethernet_rx_adapter.rst diff --git a/doc/guides/prog_guide/event_ethernet_rx_adapter.rst b/doc/guides/prog_guide/event_ethernet_rx_adapter.rst new file mode 100644 index 0000000..1bd4ac7 --- /dev/null +++ b/doc/guides/prog_guide/event_ethernet_rx_adapter.rst @@ -0,0 +1,160 @@ +.. 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. + +Event Ethernet Rx Adapter Library +================================= + +The DPDK Eventdev API allows the application to use an event driven programming +model for packet processing. In this model, the application polls an event device +port for receiving events that reference packets instead of polling Rx queues of +ethdev ports. Packet transfer between ethdev and the event device can be +supported in hardware or require a software thread to receive packets from the +ethdev port using ethdev poll mode APIs and enqueue these as events to the event +device using the eventdev API. Both transfer mechanisms may be present on the same +platform depending on the particular combination of the ethdev and the event device. + +The Event Ethernet Rx Adapter library is intended for the application code to configure +both transfer mechanisms using a common API. + +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 Rx queues +that are either polled by a SW thread or linked using hardware support. Finally +the adapter is started. + +For SW based packet transfers from ethdev to eventdev, the the adapter uses a +DPDK service function and the application is also required to assign a core to the +service function. + +Creating an Adapter Instance +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +An adapter instance is created using rte_event_eth_rx_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. + +.. code-block:: c + + int err; + uint8_t dev_id; + struct rte_event_dev_info dev_info; + struct rte_event_port_conf rx_p_conf; + + err = rte_event_dev_info_get(id, &dev_info); + + rx_p_conf.new_event_threshold = dev_info.max_num_events; + rx_p_conf.dequeue_depth = dev_info.max_event_port_dequeue_depth; + rx_p_conf.enqueue_depth = dev_info.max_event_port_enqueue_depth; + err = rte_event_eth_rx_adapter_create(id, dev_id, &rx_p_conf); + +If the application desires to have finer control of eventdev port allocation and +setup, it can use the rte_event_eth_rx_adapter_create_ext() function. The +rte_event_eth_rx_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_rx_adapter_conf structure passed to it. + +Querying Adapter Capabilties +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The rte_event_eth_rx_adapter_caps_get() function allows +the application to query the adapter capabilities for an eventdev and ethdev +combination. For e.g, if the RTE_EVENT_ETH_RX_ADAPTER_CAP_OVERRIDE_FLOW_ID is +set, the application can override the adapter generated flow ID in the event +using rx_queue_flags field in struct rte_event_eth_rx_adapter_queue_conf which +is a passed as a parameter to the rte_event_eth_rx_adapter_queue_add() function. + +Adding Rx Queues to the Adapter Instance +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Ethdev Rx queues are added to the instance using the +rte_event_eth_rx_adapter_queue_add() function. Configuration for the Rx queue is +passed in using a struct rte_event_eth_rx_adapter_queue_conf parameter. Event +information for packets from this Rx queue is encoded in the ''ev'' field of +struct rte_event_eth_rx_adapter_queue_conf. The servicing_weight member of +the struct rte_event_eth_rx_adapter_queue_conf is the relative polling +frequency of the Rx queue and is applicable when the adapter uses a service +core function. + +.. code-block:: c + + err = rte_event_eth_rx_adapter_caps_get(dev_id, eth_dev_id, &cap); + + ev.queue_id = 0; + ev.sched_type = RTE_SCHED_TYPE_ATOMIC; + ev.priority = 0; + + queue_config.rx_queue_flags = 0; + if (cap & RTE_EVENT_ETH_RX_ADAPTER_CAP_OVERRIDE_FLOW_ID) { + ev.flow_id = 1; + queue_config.rx_queue_flags = + RTE_EVENT_ETH_RX_ADAPTER_QUEUE_FLOW_ID_VALID; + } + queue_config.ev = ev; + queue_config.servicing_weight = 1; + + err = rte_event_eth_rx_adapter_queue_add(id, + eth_dev_id, + 0, &queue_config); + +Configuring the Service Function +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If the adapter uses a service function, the application is required to assign +a service core to the service function as show below. + +.. code-block:: c + + uint32_t service_id; + + if (rte_event_eth_rx_adapter_service_id_get(0, &service_id) == 0) + rte_service_map_lcore_set(service_id, RX_CORE_ID); + + +Starting the Adapter Instance +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The application calls rte_event_eth_rx_adapter_start() to start the adapter. +This function calls the start callbacks of the eventdev PMDs for hardware based +eventdev-ethdev connections and rte_service_run_state_set() to enable the +service function if one exists. + +Getting Adapter Statistics +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The rte_event_eth_rx_adapter_stats_get() function reports counters defined in struct +rte_event_eth_rx_adapter_stats. The received packet and +enqueued event counts are a sum of the counts from the eventdev PMD callbacks if the callback is +supported, and the counts maintained by the service function, if one exists. The +service function also maintains a count of cycles for which it was not able to +enqueue to the event device. diff --git a/doc/guides/prog_guide/index.rst b/doc/guides/prog_guide/index.rst index b5ad6b8..95fd727 100644 --- a/doc/guides/prog_guide/index.rst +++ b/doc/guides/prog_guide/index.rst @@ -63,6 +63,7 @@ Programmer's Guide kernel_nic_interface thread_safety_dpdk_functions eventdev + event_ethernet_rx_adapter qos_framework power_man packet_classif_access_ctrl -- 2.7.4