-----Original Message----- > Date: Thu, 8 Mar 2018 15:54:05 -0600 > From: Erik Gabriel Carrillo <erik.g.carri...@intel.com> > To: pbhagavat...@caviumnetworks.com > CC: dev@dpdk.org, jerin.ja...@caviumnetworks.com, nipun.gu...@nxp.com, > hemant.agra...@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 <erik.g.carri...@intel.com> > Signed-off-by: Jerin Jacob <jerin.ja...@caviumnetworks.com> > Signed-off-by: Pavan Nikhilesh <pbhagavat...@caviumnetworks.com> > --- > 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 <http://dpdk.org/doc/guides/prog_guide/eventdev.html>`_ > +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 <timer_expiry_event>` that > represents > +a timer expiration, and providing an API with which adapters can be created > or > +destroyed, and :ref:`event timers <event_timer>` 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 <http://dpdk.org/doc/guides/prog_guide/timer_lib.html>`_. > + > +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 <jerin.ja...@caviumnetworks.com> > -- > 2.6.4 >