From 055c52583a2794da8ba1e85a48cce3832372b12f Mon Sep 17 00:00:00 2001 From: Luca Boccassi Date: Wed, 8 Nov 2017 14:15:11 +0000 Subject: New upstream version 17.11-rc3 Change-Id: I6a5baa40612fe0c20f30b5fa773a6cbbac63a685 Signed-off-by: Luca Boccassi --- .../prog_guide/event_ethernet_rx_adapter.rst | 168 +++++++++++++++++++++ 1 file changed, 168 insertions(+) create mode 100644 doc/guides/prog_guide/event_ethernet_rx_adapter.rst (limited to '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 00000000..4e722219 --- /dev/null +++ b/doc/guides/prog_guide/event_ethernet_rx_adapter.rst @@ -0,0 +1,168 @@ +.. 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. A capability API allows +the eventdev PMD to advertise features supported for a given ethdev and allows +the application to perform configuration as per supported features. + +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 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. + +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 + + ev.queue_id = 0; + ev.sched_type = RTE_SCHED_TYPE_ATOMIC; + ev.priority = 0; + + queue_config.rx_queue_flags = 0; + queue_config.ev = ev; + queue_config.servicing_weight = 1; + + err = rte_event_eth_rx_adapter_queue_add(id, + eth_dev_id, + 0, &queue_config); + +Querying Adapter Capabilities +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +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 passed as a parameter to the ``rte_event_eth_rx_adapter_queue_add()`` +function. + +.. code-block:: c + + err = rte_event_eth_rx_adapter_caps_get(dev_id, eth_dev_id, &cap); + + 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; + } + +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. -- cgit 1.2.3-korg