From mboxrd@z Thu Jan 1 00:00:00 1970 From: Jerin Jacob Subject: Re: [PATCH v7 6/7] doc: add event timer adapter section to programmer's guide Date: Mon, 12 Mar 2018 16:51:07 +0530 Message-ID: <20180312112105.GA23858@jerin> References: <1515630074-29020-1-git-send-email-erik.g.carrillo@intel.com> <1520546046-6973-1-git-send-email-erik.g.carrillo@intel.com> <1520546046-6973-7-git-send-email-erik.g.carrillo@intel.com> Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii Cc: pbhagavatula@caviumnetworks.com, dev@dpdk.org, nipun.gupta@nxp.com, hemant.agrawal@nxp.com To: Erik Gabriel Carrillo Return-path: Received: from NAM03-CO1-obe.outbound.protection.outlook.com (mail-co1nam03on0086.outbound.protection.outlook.com [104.47.40.86]) by dpdk.org (Postfix) with ESMTP id 26FDE255 for ; Mon, 12 Mar 2018 12:21:35 +0100 (CET) Content-Disposition: inline In-Reply-To: <1520546046-6973-7-git-send-email-erik.g.carrillo@intel.com> List-Id: DPDK patches and discussions List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: dev-bounces@dpdk.org Sender: "dev" -----Original Message----- > Date: Thu, 8 Mar 2018 15:54:05 -0600 > From: Erik Gabriel Carrillo > To: pbhagavatula@caviumnetworks.com > CC: dev@dpdk.org, jerin.jacob@caviumnetworks.com, nipun.gupta@nxp.com, > hemant.agrawal@nxp.com > Subject: [PATCH v7 6/7] doc: add event timer adapter section to > programmer's guide > X-Mailer: git-send-email 1.7.10 > > Signed-off-by: Erik Gabriel Carrillo > Signed-off-by: Jerin Jacob > Signed-off-by: Pavan Nikhilesh > --- > doc/guides/prog_guide/event_timer_adapter.rst | 277 ++++++++++++++++++++++++++ > doc/guides/prog_guide/index.rst | 1 + > 2 files changed, 278 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..423b91d > --- /dev/null > +++ b/doc/guides/prog_guide/event_timer_adapter.rst > @@ -0,0 +1,277 @@ > +.. SPDX-License-Identifier: BSD-3-Clause > + Copyright(c) 2017 Intel Corporation. All rights reserved. > + > +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. I think, it better to change to _timer expiry_ from _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: > + > +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 expiry event. */ > + conn->evtim->ev.event_ptr = conn; Not specific to this specific example, What would be the default behaviour if application does not set ev.event_ptr value. Can we say? "NULL value is allowed, in which case adapter set the event_ptr to struct rte_event_timer * > + 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. > + > +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); s/wheel_id/adapter_id > + } > + > +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 bbbe789..589c05d 100644 > --- a/doc/guides/prog_guide/index.rst > +++ b/doc/guides/prog_guide/index.rst > @@ -42,6 +42,7 @@ Programmer's Guide > thread_safety_dpdk_functions > eventdev > event_ethernet_rx_adapter > + event_timer_adapter > qos_framework > power_man > packet_classif_access_ctrl Overall, it looks good. With above changes Acked-by: Jerin Jacob > -- > 2.6.4 >