From patchwork Wed Dec 23 12:32:01 2015 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Ivan Khoronzhuk X-Patchwork-Id: 58977 Delivered-To: patch@linaro.org Received: by 10.112.89.199 with SMTP id bq7csp3827441lbb; Wed, 23 Dec 2015 04:32:31 -0800 (PST) X-Received: by 10.55.80.68 with SMTP id e65mr40101633qkb.46.1450873940397; Wed, 23 Dec 2015 04:32:20 -0800 (PST) Return-Path: Received: from lists.linaro.org (lists.linaro.org. [54.225.227.206]) by mx.google.com with ESMTP id u67si39727148qgd.34.2015.12.23.04.32.19; Wed, 23 Dec 2015 04:32:20 -0800 (PST) Received-SPF: pass (google.com: domain of lng-odp-bounces@lists.linaro.org designates 54.225.227.206 as permitted sender) client-ip=54.225.227.206; Authentication-Results: mx.google.com; spf=pass (google.com: domain of lng-odp-bounces@lists.linaro.org designates 54.225.227.206 as permitted sender) smtp.mailfrom=lng-odp-bounces@lists.linaro.org; dkim=neutral (body hash did not verify) header.i=@linaro.org Received: by lists.linaro.org (Postfix, from userid 109) id 9AFBD61105; Wed, 23 Dec 2015 12:32:19 +0000 (UTC) Authentication-Results: lists.linaro.org; dkim=fail reason="verification failed; unprotected key" header.d=linaro.org header.i=@linaro.org header.b=Fjc3+0Ph; dkim-adsp=none (unprotected policy); dkim-atps=neutral X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on ip-10-142-244-252 X-Spam-Level: X-Spam-Status: No, score=-2.5 required=5.0 tests=BAYES_00,DKIM_SIGNED, RCVD_IN_DNSWL_LOW, RCVD_IN_MSPIKE_H3, RCVD_IN_MSPIKE_WL, T_DKIM_INVALID, URIBL_BLOCKED autolearn=disabled version=3.4.0 Received: from [127.0.0.1] (localhost [127.0.0.1]) by lists.linaro.org (Postfix) with ESMTP id 0D97D6173B; Wed, 23 Dec 2015 12:32:15 +0000 (UTC) X-Original-To: lng-odp@lists.linaro.org Delivered-To: lng-odp@lists.linaro.org Received: by lists.linaro.org (Postfix, from userid 109) id A989A6178D; Wed, 23 Dec 2015 12:32:12 +0000 (UTC) Received: from mail-lb0-f178.google.com (mail-lb0-f178.google.com [209.85.217.178]) by lists.linaro.org (Postfix) with ESMTPS id 7631A61105 for ; Wed, 23 Dec 2015 12:32:10 +0000 (UTC) Received: by mail-lb0-f178.google.com with SMTP id pv2so60005644lbb.1 for ; Wed, 23 Dec 2015 04:32:10 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; h=from:to:cc:subject:date:message-id; bh=0Rc8AmDvNP7JIyPj/QDwd56bDeAjndCxWcivBITRggM=; b=Fjc3+0PhumK6rveSeq8Bi4pWXFA8Zf82W3Kxl2bsH27j/uR5ktd0eydMMbnMUxSz+n 9/2YONwXtQCl/ddgUllTJX01s6a/atZpc9TzHDK6C764l+uj5jnPfuSk3v4t7O4hVms1 ldrt0FTiSKuNP/LxI8J5A4RvAoMsVc2XCvX+A= X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20130820; h=x-gm-message-state:from:to:cc:subject:date:message-id; bh=0Rc8AmDvNP7JIyPj/QDwd56bDeAjndCxWcivBITRggM=; b=jkxB4rXdSkNM0b7LPB6hM//HzBRLreOvcilupko9LjZOtN4gJbxBEGKBugGIbkN6Nr JUFzz79R8RENqtuYPxlphIGBtXRsQo3Ba4mviv2s2PK6sfxE4DxclC/5OW51ynP9XDmZ wN3qm+YxomzpcLI8j52qecf2Ch2xDsP7KxbZy8NztuSc1uO5h8LL5yVryApMOjZkUpUn 4EZ8FYR7NgI7TY/7GlHGVGJFuUCEI+wahVcgTTTATY2b+Uv/GRt7DmUpDThmBgy5JxqQ zUiur/c9V6wyKLmKmcbm3C2J+mZL3VjAWpFjlb7Lu9aDK6MHgg+WiicsXZJJyKNDKIkE 8V5g== X-Gm-Message-State: ALoCoQnxaMknnEXGEhelDqPJ6cD1mhMzXk/ash4J/VWmh7k3WDaK0s1oacXB1UlsYgl8TyjnGU7e6FP6GpDo9PcIbpk4JqHO2g== X-Received: by 10.112.54.193 with SMTP id l1mr10033349lbp.58.1450873929280; Wed, 23 Dec 2015 04:32:09 -0800 (PST) Received: from localhost.localdomain ([195.238.92.128]) by smtp.gmail.com with ESMTPSA id k64sm753443lfi.23.2015.12.23.04.32.07 (version=TLS1_2 cipher=ECDHE-RSA-AES128-SHA bits=128/128); Wed, 23 Dec 2015 04:32:07 -0800 (PST) From: Ivan Khoronzhuk To: lng-odp@lists.linaro.org Date: Wed, 23 Dec 2015 14:32:01 +0200 Message-Id: <1450873921-16505-1-git-send-email-ivan.khoronzhuk@linaro.org> X-Mailer: git-send-email 1.9.1 X-Topics: patch Subject: [lng-odp] [API-NEXT PATCH v3] doc/users-guide: add time API section X-BeenThere: lng-odp@lists.linaro.org X-Mailman-Version: 2.1.16 Precedence: list List-Id: "The OpenDataPlane \(ODP\) List" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , MIME-Version: 1.0 Errors-To: lng-odp-bounces@lists.linaro.org Sender: "lng-odp" Signed-off-by: Ivan Khoronzhuk Reviewed-by: Bill Fischofer --- doc/users-guide/users-guide.adoc | 29 ++++++++++++++++++++++++++++- 1 file changed, 28 insertions(+), 1 deletion(-) diff --git a/doc/users-guide/users-guide.adoc b/doc/users-guide/users-guide.adoc index 7ec7957..e8465d0 100644 --- a/doc/users-guide/users-guide.adoc +++ b/doc/users-guide/users-guide.adoc @@ -197,7 +197,7 @@ precise syntax and semantics of each API. ODP programs are built around several conceptual structures that every application programmer needs to be familiar with to use ODP effectively. The main ODP concepts are: -Thread, Event, Queue, Pool, Shared Memory, Buffer, Packet, PktIO, Timer, +Thread, Event, Queue, Pool, Shared Memory, Buffer, Packet, PktIO, Time, Timer, and Synchronizer. === Thread @@ -305,6 +305,33 @@ or may represent a device attached via a PCIE or other bus. PktIOs are represented by handles of abstract type +odp_pktio_t+. +=== Time +The time API is used to measure time intervals and track time flow of an +application and presents a convenient way to get access to a time source. +The time API consists of two main parts: local time API and global time API. + +==== Local time +The local time API is designed to be used within one thread and can be faster +then the global time API. The local time API cannot be used between threads as +time consistency is not guaranteed, and in some cases that's enough. +So, local time stamps are local to the calling thread and must not be shared +with other threads. Current local time can be read with +odp_time_local()+. + +==== Global time +The global time API is designed to be used for tracking time between threads. +So, global time stamps can be shared between threads. Current global time can +be read with +odp_time_global()+. + +Both, local and global time is not wrapped during the application life cycle. +The time API includes functions to operate with time, such as +odp_time_diff()+, ++odp_time_sum()+, +odp_time_cmp()+, conversion functions like ++odp_time_to_ns()+, +odp_time_local_from_ns()+, +odp_time_global_from_ns()+. +To get rate of time source +odp_time_local_res()+, +odp_time_global_res()+ +are used. To wait, +odp_time_wait_ns()+ and +odp_time_wait_until()+ are used, +during witch a thread potentially busy loop the entire wait time. + +The +odp_time_t+ opaque type represents local or global timestamps. + === Timer Timers are how ODP applications measure and respond to the passage of time. Timers are drawn from specialized pools called timer pools that have their