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 74C5F1B232 for ; Thu, 11 Jan 2018 01:21:48 +0100 (CET) X-Amp-Result: SKIPPED(no attachment in message) X-Amp-File-Uploaded: False Received: from orsmga005.jf.intel.com ([10.7.209.41]) by fmsmga104.fm.intel.com with ESMTP/TLS/DHE-RSA-AES256-GCM-SHA384; 10 Jan 2018 16:21:48 -0800 X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="5.46,342,1511856000"; d="scan'208";a="192627504" Received: from txasoft-yocto.an.intel.com (HELO txasoft-yocto.an.intel.com.) ([10.123.72.111]) by orsmga005.jf.intel.com with ESMTP; 10 Jan 2018 16:21:47 -0800 From: Erik Gabriel Carrillo To: pbhagavatula@caviumnetworks.com Cc: dev@dpdk.org, jerin.jacob@caviumnetworks.com, nipun.gupta@nxp.com, hemant.agrawal@nxp.com Date: Wed, 10 Jan 2018 18:21:13 -0600 Message-Id: <1515630074-29020-23-git-send-email-erik.g.carrillo@intel.com> X-Mailer: git-send-email 1.7.10 In-Reply-To: <1515630074-29020-1-git-send-email-erik.g.carrillo@intel.com> References: <1512158458-22661-1-git-send-email-erik.g.carrillo@intel.com> <1515630074-29020-1-git-send-email-erik.g.carrillo@intel.com> Subject: [dpdk-dev] [PATCH v6 22/23] doc: add event timer adapter section to 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: Thu, 11 Jan 2018 00:21:49 -0000 Signed-off-by: Erik Gabriel Carrillo --- doc/guides/prog_guide/event_timer_adapter.rst | 301 ++++++++++++++++++++++++++ doc/guides/prog_guide/index.rst | 1 + 2 files changed, 302 insertions(+) create mode 100644 doc/guides/prog_guide/event_timer_adapter.rst diff --git a/doc/guides/prog_guide/event_timer_adapter.rst b/doc/guides/prog_guide/event_timer_adapter.rst new file mode 100644 index 0000000..47418a2 --- /dev/null +++ b/doc/guides/prog_guide/event_timer_adapter.rst @@ -0,0 +1,301 @@ +.. 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 Timer Adapter Library +================================= + +The DPDK +`Event Device library `_ +introduces an event driven programming model which presents applications with +an alternative to the polling model traditionally used in DPDK +applications. Event devices can be coupled with arbitrary components to provide +new event sources by using **event adapters**. The Event Timer Adapter is one +such adapter; it bridges event devices and timer mechanisms. + +The Event Timer Adapter library extends the event driven model +by introducing a :ref:`new type of event ` that represents +a timer expiration, and providing an API with which adapters can be created or +destroyed, and :ref:`event timers ` can be armed and canceled. + +The Event Timer Adapter library is designed to interface with hardware or +software implementations of the timer mechanism; it will query an eventdev PMD +to determine which implementation should be used. The default software +implementation manages timers using the DPDK +`Timer library `_. + +Examples of using the API are presented in the `API Overview`_ and +`Processing Timer Expiry Events`_ sections. Code samples are abstracted and +are based on the example of handling a TCP retransmission. + +.. _event_timer: + +Event Timer struct +------------------ +Event timers are timers that enqueue a timer expiration event to an event +device upon firing. + +The Event Timer Adapter API represents each event timer with a generic struct, +which contains an event and user metadata. The ``rte_event_timer`` struct is +defined in ``lib/librte_event/librte_event_timer_adapter.h``. + +.. _timer_expiry_event: + +Timer Expiry Event +~~~~~~~~~~~~~~~~~~ + +The event contained by an event timer is enqueued in the event device when the +timer expires, and the event device uses the attributes below when scheduling +it: + +* ``event_queue_id`` - Application should set this to specify an event queue to + which the timer expiry event should be enqueued +* ``event_priority`` - Application can set this to indicate the priority of the + timer expiry event in the event queue relative to other events +* ``sched_type`` - Application can set this to specify the scheduling type of + the timer expiry event +* ``flow_id`` - Application can set this to indicate which flow this timer + expiry event corresponds to +* ``op`` - Will be set to ``RTE_EVENT_OP_NEW`` by the event timer adapter +* ``event_type`` - Will be set to ``RTE_EVENT_TYPE_TIMER`` by the event timer + adapter + +Timeout Ticks +~~~~~~~~~~~~~ + +The number of ticks from now in which the timer will expire. The ticks value +has a resolution (``timer_tick_ns``) that is specified in the event timer +adapter configuration. + +User Metadata +~~~~~~~~~~~~~ + +Memory to store user specific metadata. The event timer adapter implementation +will not modify this area. + +API Overview +---------------- + +This section will introduce the reader to the event timer adapter API, showing +how to create and configure an event timer adapter and use it to manage event +timers. + +From a high level, the setup steps are: + +* rte_event_timer_adapter_create() +* rte_event_timer_adapter_start() + +And to start and stop timers: + +* rte_event_timer_arm_burst() +* rte_event_timer_cancel_burst() + +Create and Configure an Adapter Instance +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To create an event timer adapter instance, initialize an +``rte_event_timer_adapter_conf`` struct with the desired values, and pass it +to ``rte_event_timer_adapter_create()``. + +.. code-block:: c + + #define NSECPERSEC 1E9 // No of ns for 1 sec + const struct rte_event_timer_adapter_config adapter_config = { + .event_dev_id = event_dev_id, + .timer_adapter_id = 0, + .clk_src = RTE_EVENT_TIMER_WHEEL_CPU_CLK, + .timer_tick_ns = NSECPERSEC / 10, // 100 milliseconds + .max_tmo_nsec = 180 * NSECPERSEC // 2 minutes + .nb_timers = 40000, // Number of timers the adapter can hold. + .timer_adapter_flags = 0, + }; + + struct rte_event_timer_adapter *adapter = NULL; + adapter = rte_event_timer_adapter_create(&adapter_config); + + if (adapter == NULL) { ... }; + +Before creating an instance of a timer adapter, the application should create +and configure an event device along with the event ports. Based on the event +device capability, it might require creating an additional event port to be +used by the timer adapter. If required, the +``rte_event_timer_adapter_create()`` function will use a default method to +configure an event port; it will examine the current event device configuration, +determine the next available port identifier number, and create a new event +port with a default port configuration. + +If the application desires to have finer control of event port allocation +and setup, it can use the ``rte_event_timer_adapter_create_ext()`` function. +This function is passed a callback function that will be invoked if the +adapter needs to create an event port, giving the application the opportunity +to control how it is done. + +Retrieve Event Timer Adapter Contextual Information +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The event timer adapter implementation may have constraints on tick resolution +or maximum timer expiry timeout based on the given event timer adapter or +system. In this case, the implementation may adjust the tick resolution or +maximum timeout to the best possible configuration. + +Upon successful event timer adapter creation, the application can get the +configured resolution and max timeout with +``rte_event_timer_adapter_get_info()``. This function will return an +``rte_event_timer_adapter_info`` struct, which contains the following members: + +* ``min_resolution_ns`` - Minimum timer adapter tick resolution in ns. +* ``max_tmo_ns`` - Maximum timer timeout(expiry) in ns. +* ``adapter_conf`` - Configured event timer adapter attributes + +Configuring the Service Component +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If the adapter uses a service component, the application is required to map +the service to a service core before starting the adapter: + +.. code-block:: c + + uint32_t service_id; + + if (rte_event_timer_adapter_service_id_get(adapter, &service_id) == 0) + rte_service_map_lcore_set(service_id, RX_CORE_ID); + +An event timer adapter uses a service component if the event device PMD +indicates that the adapter should use a software implementation. + +Starting the Adapter Instance +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The application should call ``rte_event_timer_adapter_start()`` to start +running the event timer adapter. This function calls the start callbacks +defined by eventdev PMDs for hardware implementations or sets a service +component into the running state in the default software implementation. + +Arming Event Timers +~~~~~~~~~~~~~~~~~~~~~ + +Once an event timer adapter has been started, an application can begin to +manage event timers with it. + +The application should allocate ``struct rte_event_timer`` objects from a +mempool or huge-page backed application buffers of required size. Upon +successful allocation, the application should initialize the event timer, and +then set any of the necessary event attributes described in the +`Timer Expiry Event`_ section. In the following example, assume ``conn`` +represents a TCP connection and that ``event_timer_pool`` is a mempool that +was created previously: + +.. code-block:: c + + rte_mempool_get(event_timer_pool, (void **)&conn->evtim); + if (conn->evtim == NULL) { ... } + + rte_event_timer_init(&conn->evtim); + + /* Set up the timer event. */ + conn->evtim->ev.event_ptr = conn; + conn->evtim->ev.queue_id = event_queue_id; + ... + conn->evtim->timeout_ticks = 30; //3 sec Per RFC1122(TCP returns) + +Note that we have saved a pointer to the ``conn`` object in the timer's event +payload. This will allow us to locate the connection object again once we +dequeue the timer expiry event from the event device later. + +Now we can arm the event timer with ``rte_event_timer_arm_burst()``: + +.. code-block:: c + + ret = rte_event_timer_arm_burst(adapter, &conn->evtim, 1); + if (ret != 1) { ... } + +Multiple Event Timers with Same Expiry Value +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +In the special case that there is a set of event timers that should all expire +at the same time, the application may call +``rte_event_timer_arm_tmo_tick_burst()``, which allows the implementation to +optimize the operation if possible. + +Canceling Event Timers +~~~~~~~~~~~~~~~~~~~~~~~ + +An event timer that has been armed as described in `Arming Event Timers`_ can +be canceled by calling ``rte_event_timer_cancel_burst()``: + +.. code-block:: c + + /* Ack for the previous tcp data packet has been received.*/ + /* cancel the retransmission timer*/ + rte_event_timer_cancel_burst(wheel, &conn->timer, 1); + +Processing Timer Expiry Events +------------------------------ + +Once an event timer has successfully enqueued a timer expiry event in the event +device, the application will subsequently dequeue it from the event device. +The application can use the event payload to retrieve a pointer to the object +associated with the event timer. It can then re-arm the event timer or free the +event timer object as desired: + +.. code-block:: c + + void + event_processing_loop(...) + { + while (...) { + /* Receive events from the configured event port. */ + rte_event_dequeue_burst(event_dev_id, event_port, &ev, 1, 0); + ... + switch(ev.event_type) { + ... + case RTE_EVENT_TYPE_TIMER: + process_timer_event(ev); + ... + break; + } + } + } + + uint8_t + process_timer_event(...) + { + /* A retransmission timeout for the connection has been received. */ + conn = ev.event_ptr; + /* Retransmit last packet (e.g. TCP segment). */ + ... + /* Re-arm timer using original values. */ + rte_event_timer_arm_burst(wheel_id, &conn->timer, 1); + } + +Summary +------- + +The Event Timer Adapter library extends the DPDK event-based programming model +by representing timer expirations as events in the system and allowing +applications to use existing event processing loops to arm and cancel event +timers or handle timer expiry events. diff --git a/doc/guides/prog_guide/index.rst b/doc/guides/prog_guide/index.rst index c4beb34..9a85d18 100644 --- a/doc/guides/prog_guide/index.rst +++ b/doc/guides/prog_guide/index.rst @@ -67,6 +67,7 @@ Programmer's Guide thread_safety_dpdk_functions eventdev event_ethernet_rx_adapter + event_timer_adapter qos_framework power_man packet_classif_access_ctrl -- 2.6.4