From mboxrd@z Thu Jan 1 00:00:00 1970 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) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=CAVIUMNETWORKS.onmicrosoft.com; s=selector1-cavium-com; h=From:Date:Subject:Message-ID:Content-Type:MIME-Version; bh=l7izxLD6oEssk0dmzcpvSS0yxqrc1lVDBrgLK0U5dF0=; b=IQmvSad8BC/D8UACG1w3bY6WKwO3a7aZL0LJ5HkjIs6VzOweu01NbLnaMrylwQbRo6cW7xLHVpEkzvzJwPUVnoTyQk8Q6jVsK34yePYCS7D9UmAqTdibmEwhsVMnY+exQmbGqKS3B0iFYO0f9QGtjJfzJdk6JT9uyUY8n3KNkRQ= Authentication-Results: spf=none (sender IP is ) smtp.mailfrom=Jerin.JacobKollanukkaran@cavium.com; Received: from jerin (106.200.241.70) by SN2PR07MB2527.namprd07.prod.outlook.com (2603:10b6:804:6::27) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384_P256) id 15.20.567.14; Mon, 12 Mar 2018 11:21:29 +0000 Date: Mon, 12 Mar 2018 16:51:07 +0530 From: Jerin Jacob To: Erik Gabriel Carrillo Cc: pbhagavatula@caviumnetworks.com, dev@dpdk.org, nipun.gupta@nxp.com, hemant.agrawal@nxp.com 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 Content-Disposition: inline In-Reply-To: <1520546046-6973-7-git-send-email-erik.g.carrillo@intel.com> User-Agent: Mutt/1.9.4 (2018-02-28) X-Originating-IP: [106.200.241.70] X-ClientProxiedBy: MAXPR0101CA0011.INDPRD01.PROD.OUTLOOK.COM (2603:1096:a00:c::21) To SN2PR07MB2527.namprd07.prod.outlook.com (2603:10b6:804:6::27) X-MS-PublicTrafficType: Email X-MS-Office365-Filtering-Correlation-Id: bca59914-402f-42f3-9a8e-08d5880b68be X-Microsoft-Antispam: UriScan:; BCL:0; PCL:0; RULEID:(7020095)(4652020)(5600026)(4604075)(4534165)(4627221)(201703031133081)(201702281549075)(2017052603328)(7153060)(7193020); SRVR:SN2PR07MB2527; X-Microsoft-Exchange-Diagnostics: 1; SN2PR07MB2527; 3:+JmDTjrs4nCIhMCijsYyax/VS6G2yBREXwowVoEZGZcLJk09ZWNX+oQDCJdJsl/9Pb9AU5JIs4DiV1m9s8vnQZgfxRYo1cKwOPDsaGviXnzMGMkrfwFskW7sLAoLYJamU5jyJBSbRqPUc7piUNXsnPhhC1d15NKA0/ZqDrYofKtpKuVrcbhpK/Ft3UA2WtzTHu5GYF46WEDH9B+vin95bUMUwksnYF0Ge5XK8yhe8U/sbDbp+Vi0207/FALT49Yu; 25:pA+tj0PUWUw+qUZFqRUaGn8Zrd4T5zVYhnm2rN0v26+qZQin1UgjP1bJbg+d3u2II2CwBHpFDVKKYJLtjql5grs21Um9EamgX5dr5vlBDBsLdzyM/t9+ouQnSiqXcihwX36x5//9h/7RyIJagIL9nc8VRcIisL1aSvOu7vaI56aO6z/nnF9tSN2qAk4WVND92L8zMHGCu1nLIGCbLLDvA1yj6kfaI9p9goWgrhgIwvqTxfmtZ8nx6RvqSms/mzrutgBsJ8xsQpPgiKd9eikTL3Ub+xP978pu6ufF48/Bdcdlh00bYV7veRNeo82YQvoSt7whri02uNkoi1qtwgTaQw==; 31:3oh+fWLHSgghD4cU6N0I6Sp9wDXulWxcCfRmJIh731LEWOxWapwlGsTTUVDTbMMmr2zctZntUifle//rYPwZlTS6064lif77D+/j52jRr4KvhS4ulh6NMe6rOMlo7QZ0bdeNQEkk9jlTO68VjrQgie6aPGHQ3gMtqfF7mdgm2F4MsGvEUN+kCrGHf1Lj+iQtRcnYElalCRixSlMV+xVx5IfmJCxo2zhk4Oj9QvKtdLw= X-MS-TrafficTypeDiagnostic: SN2PR07MB2527: X-Microsoft-Exchange-Diagnostics: 1; SN2PR07MB2527; 20:oXu5TMWmYnkiRSElL//KbvIcXd0cWLaI8k7cjY9J10vw6ooUuZTnFl7E97ATw8sTE6SxBmzhGkdaOxq/g4J8Hj7uxQd1tdfXrhSt2TrI40dkYKl1zX1eUqTApfnYk8VvnriGuDvM0YfoMz/x8qRz6JFyd06IABieS72ghFPWR1pD6zGIXni91Rk56h978+QSHpbMAr4Rw8dyVHQEuAlf7z/3cv5/HlPKJZe3AU3qbgqIf4zQYJMIRxSI1pRLldIXXiDf8QImvvbZvA0e6HQE0UH4QLeGyFQ5EQO6Tas/A97/xOTvm0y44bv3wzQXf7hYZmHQGvare55ONGh2oNNFz741iH5NIFvK3q4JooCSB80lW29Q/tmfVeppDL5h+/ELslEmCjqFvD/9mE6mIvf9WDhbtVi9pa10uNcFZkFMacNsiTqz9qSMI1dhxcEJqeRCFZwQyhQfjfCxXiYUfJVzR5xAkCywTbKWeZE7zT/4epbdSxIlz/1jRNz6kB+kqSzkCkFASMvLftmsrN9OlHE0/DWlF9EwNXtYysItDhHPNn5ej+ZU6rFE3ZadjFrS3a1RD1LDogciteT0+mtvlovK9f8KJKPn+V7G47j9sUiUNhU= X-Microsoft-Antispam-PRVS: X-Exchange-Antispam-Report-Test: UriScan:(278428928389397)(185117386973197)(228905959029699); X-Exchange-Antispam-Report-CFA-Test: BCL:0; PCL:0; RULEID:(8211001083)(6040522)(2401047)(8121501046)(5005006)(93006095)(3002001)(3231220)(944501244)(52105095)(10201501046)(6041310)(20161123562045)(201703131423095)(201702281528075)(20161123555045)(201703061421075)(201703061406153)(20161123558120)(20161123560045)(20161123564045)(6072148)(201708071742011); SRVR:SN2PR07MB2527; BCL:0; PCL:0; RULEID:; SRVR:SN2PR07MB2527; X-Microsoft-Exchange-Diagnostics: 1; SN2PR07MB2527; 4:aFAsEFrySoYhT1VONMCZmaY19q7KaOI6Pi/Ulwwh047Q0VZRaOBL67HTksFQ82MFqcsUAy8b5uNOdC2I7lsOXWwjOrkAV0ZCEy9s5NIu4+fgP4mzJrxovgREmDlUZN4ReA7jUuyMogSVlnwT/+fU3cupoROjzF+Wi6pw/IL110IKfkq4q1w/0YlRn13dI9fAaC9/d09IHfA3gFeetuQujMfjD0n13P3lWzISY6Q+waJA6rgaYtwmf0otj+jEdQTkcZP2ppT7Kp5lSLVSyFOlotHz6qnJCnh7O9yaQAYSR/2kdF4QcsxeAstp6yNY9hhq14GVRMuDDt7sD3aPGS9+XbgN+SwmJ/rccoLi+XRlVYgU9AeORkCv0Grm5x0ck4jM X-Forefront-PRVS: 06098A2863 X-Forefront-Antispam-Report: SFV:NSPM; SFS:(10009020)(366004)(346002)(39380400002)(39850400004)(396003)(376002)(189003)(13464003)(199004)(68736007)(50466002)(33896004)(97736004)(52116002)(76176011)(47776003)(229853002)(66066001)(9686003)(105586002)(81156014)(55016002)(42882007)(25786009)(6306002)(81166006)(8676002)(478600001)(53936002)(8936002)(8656006)(6496006)(1076002)(6246003)(53376002)(6116002)(72206003)(23726003)(33716001)(5660300001)(3846002)(16586007)(33656002)(316002)(4326008)(58126008)(2906002)(305945005)(59450400001)(16526019)(7736002)(5009440100003)(6666003)(186003)(2950100002)(6916009)(26005)(106356001)(386003)(18370500001); DIR:OUT; SFP:1101; SCL:1; SRVR:SN2PR07MB2527; H:jerin; FPR:; SPF:None; PTR:InfoNoRecords; MX:1; A:1; LANG:en; Received-SPF: None (protection.outlook.com: cavium.com does not designate permitted sender hosts) X-Microsoft-Exchange-Diagnostics: =?us-ascii?Q?1; SN2PR07MB2527; 23:Gtl25UmRUKeSnqa6GqvzRX0JMi0/rMrlpM3hmVXB4?= =?us-ascii?Q?gXDLo02Bv0nnHDpZuTiFQaiNYIURmMfa0GOOcHCrM69qINK4K4pBmolUIOGK?= =?us-ascii?Q?f2SrMd0ByjImegN12UmKsRZURcwuUJiyBokUcicDVBgjsQUMAo9+fz1nwqOI?= =?us-ascii?Q?7TrsQgHtU/w2D7vzg9uJvIgg1fZeC6Fo7Y6m3kmXFpXPSUCkC7GCPfYuET0F?= =?us-ascii?Q?X43bGEOmRCyWqdJLC0EDA4eW81SMT48I11NXZqXXU4UYBMebYW2g8Og5z4/J?= =?us-ascii?Q?V9YSKcdyTFBSI2niaVjASICix2J2LmacVlbjGCfNszBULLCbJqLRPst2Mo7+?= =?us-ascii?Q?kXK/TCmDdp5+vwgFRg88U1qKnoRQpRTy474yOJsPiV8TH2cE23MfusA8hpbL?= =?us-ascii?Q?RCcGAT6O4hyONzBVixf+zYfDX/iGN+xJG+Xw++8425YLsYdKqsAIqDEPLJKy?= =?us-ascii?Q?+LFJbfcT7CvQ37SsgorqEOTJSgwxcyx/c2/edlwyxQsdQzLch3KAT25rWjk4?= =?us-ascii?Q?wQpO9B9Kwy171sZgWRyKPacu/OHqyqysW7zkFQlUcvxSm4GiBoQLcRRR2Ykq?= =?us-ascii?Q?GGcAJOOf21GH6A93y21zoLLOtJy8CwfRqOnUjJn/LbrhxJXiCXWcK/PFfGfP?= =?us-ascii?Q?3rJqi3YiPexXQyxSHDLW6O3VccqpIcc4mfp8nUrcCtzuHB/s+5kcn3q/GyEp?= =?us-ascii?Q?GVnLBXBKU6N2bTAEsCTMKe8KjkUCiEWIuYIiuOUvylTsYraJ3EUDM/+R3IRx?= =?us-ascii?Q?sEr6AsnGhq2cc6hqOu4DPDv5HDcS8sgJbZz3vr1jiz9gc8uDlJWefEXXYatx?= =?us-ascii?Q?19pLnyPl11lvDmkhaydIxG67VargeyLf1wzBL0kSor1oF1GN6Ox7JJcS/1EQ?= =?us-ascii?Q?QzCHL7YKIAuGI6JK865kkhW3Xn0R8jW/msU4Sjine+CGYg9QrBWBvG1KlS22?= =?us-ascii?Q?tUpWMMPB8bGbk30XRKwdOO2fC2VBJTuft75U9XuxwsxKFazyCStLlUNdr+dB?= =?us-ascii?Q?9WTCc9b77uAg3ZK2kwmfs78ecH5DUgC3QFRzGAtcqdzIdN/tUmyDL5jLxm/v?= =?us-ascii?Q?+TlPi+b5mWM6AX9JGBednsTRur2mQBIcDNLMrgZp5A/jcKIjf3pAw5YrjRA1?= =?us-ascii?Q?Z9ANnhxU69cD6S0pyvZ3D7mGu5gb0bO8+Xzkf/7uDLlCvmYCn6aajyYCwht9?= =?us-ascii?Q?dEKLkSuVWf3ggFFotfZU3EVamNd1ljjxYBeonaXfDVXsm/tfVOnas2Uv1XBQ?= =?us-ascii?Q?36nMc0GnKdUfWQ6lWHqm+5LlbFfGjNRgdZKUVisEATtbWKun0Q58804ZeUbs?= =?us-ascii?Q?Edfnpy79M5Ju55K62eKrhx9nFXqAzwWKFKhTK+snuE569U8Tv5AftywLCCvR?= =?us-ascii?Q?gpXLtQx5g42SrU0RmR3neb4uO0=3D?= X-Microsoft-Antispam-Message-Info: fDJ5GOgP9Saksvo3zzseIpIqb8SlLKJWqZdPw0+p6rpJFoGl5HcSXqTyMz0+npnRfWzG05dVkYdN4ptOWC894bzP/qeMbetvRnGnABRDQzkImTRmCGZGvOm825AC84kDRdmPjOA8NNh+p5Ruswham52DgYfsEHKzKcD9kpGajx8RK1U/FAbcDVRZ0kp4Go11 X-Microsoft-Exchange-Diagnostics: 1; SN2PR07MB2527; 6:FadHDGG9iT2MwvBuvrafYW0646o3IZCIi5iCoAcLvYRFabZsx31K6bZuMKWYIRPrjnHEBpgdE+8AZQdmNIUA4CUzKTPnQMaDe/pwXmqxh6VMXr6Hq1DqMkipI7NSSTDEVJtL64CSrhKNrxhsuRdNZHvFPEPg3WgXw76mJ2tqL2IQg+TzwQD2OBhM61wmNhO8w/CVjipPEMveGAEArgsQHKlkKfauqDjFdmJQl/KSSEFPDdXpIsva5zxnPUpbVWqXnzcT0w+qUdHJccqtzbZpGmF9WqOO7KHSZa3UNfCkqEFHN7+rx+IbYfLIt14jg4Y9RXVQ0lootm075UA0Fwa+UVraCHAWZ8UJjqpm/F5/1Go=; 5:uJbm+YxZDyZY3rmbSug7cK22pcwsiPqilQQZGEgCb6o6f1NKkxTOtzokrySY66kcEbxbM7aQ4JMg9IYsnkxXu96escq4cA8qLc5UszmiywqSQt5fpjAdmrPBhfC+WCGyNE8+WaNaiWZdFcGljzTpwyi002godlyPfHTl4pFZTiQ=; 24:GIAPZWaPtHNwh7fNO+REILXKiukPRXi8HPc6WMyadk4oHMrKQcwr+dsxICnp9RdZTE5LnL9dvBG6ImjAxoam9P9LphzRYjWAutkUQISKigw=; 7:IaTlKhAtfskiKuF5TCVbDE0bpDkBE+rRbg/WVz/KW2qSSLqbDaFTym9T9rtixG0VP1/4CsG/E8bURA43K+ZpghJXOr+ekda+4C6/Dycg4II+4O4SayIpIASZ/A4+EpDVrYd9APduMuIrs4Y34eSGaNLlTK+7DOE2eIWNrzq6zGpio60FxiNqjjXGmnot4iCgV3e2KjD7a/a+31a0Oqj05gMlkbuUstCSdIhDQGvgv9O0Mmrxpd26Wm5XTNJpAZzG SpamDiagnosticOutput: 1:99 SpamDiagnosticMetadata: NSPM X-OriginatorOrg: caviumnetworks.com X-MS-Exchange-CrossTenant-OriginalArrivalTime: 12 Mar 2018 11:21:29.6132 (UTC) X-MS-Exchange-CrossTenant-Network-Message-Id: bca59914-402f-42f3-9a8e-08d5880b68be X-MS-Exchange-CrossTenant-FromEntityHeader: Hosted X-MS-Exchange-CrossTenant-Id: 711e4ccf-2e9b-4bcf-a551-4094005b6194 X-MS-Exchange-Transport-CrossTenantHeadersStamped: SN2PR07MB2527 Subject: Re: [dpdk-dev] [PATCH v7 6/7] 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: Mon, 12 Mar 2018 11:21:35 -0000 -----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 >