[dpdk-dev,v7,6/7] doc: add event timer adapter section to programmer's guide

Message ID 1520546046-6973-7-git-send-email-erik.g.carrillo@intel.com (mailing list archive)
State Superseded, archived
Delegated to: Jerin Jacob
Headers

Checks

Context Check Description
ci/checkpatch success coding style OK
ci/Intel-compilation fail Compilation issues

Commit Message

Carrillo, Erik G March 8, 2018, 9:54 p.m. UTC
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
  

Comments

Jerin Jacob March 12, 2018, 11:21 a.m. UTC | #1
-----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
>
  
Carrillo, Erik G March 12, 2018, 10:02 p.m. UTC | #2
Hi Jerin,

> -----Original Message-----
> From: Jerin Jacob [mailto:jerin.jacob@caviumnetworks.com]
> Sent: Monday, March 12, 2018 6:21 AM
> To: Carrillo, Erik G <erik.g.carrillo@intel.com>
> Cc: pbhagavatula@caviumnetworks.com; dev@dpdk.org;
> nipun.gupta@nxp.com; hemant.agrawal@nxp.com
> Subject: Re: [PATCH v7 6/7] doc: add event timer adapter section to
> programmer's guide
> 
> -----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>
> > ---

<... snipped ...>

> > +
> > +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_.
> 

Sounds good.

> > +
> > +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.
> 

Currently, it's undefined.

> Can we say?
> "NULL value is allowed, in which case adapter set the event_ptr to struct
> rte_event_timer *
> 

I like that idea; it would be a convenient touch.  I'll look at making this  update.

> > +	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.

<... snipped ...>

> 
> Overall, it looks good. With above changes
> 
> Acked-by: Jerin Jacob <jerin.jacob@caviumnetworks.com>
> 
> 
> > --
> > 2.6.4
> >

Thanks for the suggestions,
Gabriel
  

Patch

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.
+
+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_init()
+* 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 in 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,
+                .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 its 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, EVTIM_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 entry points
+defined by eventdev PMDs for hardware implementations or puts a service
+component into the running state in the 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 expiry 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(adapter, &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 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