Re: [PATCH v7 6/7] doc: add event timer adapter section to programmer's guide

[Jerin Jacob <jerin.jacob@caviumnetworks.com>]

-----Original Message-----
> Date: Thu, 8 Mar 2018 15:54:05 -0600
> From: Erik Gabriel Carrillo <erik.g.carrillo@intel.com>
> 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 <erik.g.carrillo@intel.com>
> Signed-off-by: Jerin Jacob <jerin.jacob@caviumnetworks.com>
> Signed-off-by: Pavan Nikhilesh <pbhagavatula@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.jacob@caviumnetworks.com>


> -- 
> 2.6.4
>