From patchwork Wed Dec 23 13:38:28 2015 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Ivan Khoronzhuk X-Patchwork-Id: 58979 Delivered-To: patch@linaro.org Received: by 10.112.89.199 with SMTP id bq7csp3863855lbb; Wed, 23 Dec 2015 05:38:45 -0800 (PST) X-Received: by 10.107.12.79 with SMTP id w76mr27945796ioi.131.1450877925473; Wed, 23 Dec 2015 05:38:45 -0800 (PST) Return-Path: Received: from lists.linaro.org (lists.linaro.org. [54.225.227.206]) by mx.google.com with ESMTP id sb11si17145802igb.69.2015.12.23.05.38.45; Wed, 23 Dec 2015 05:38:45 -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 B7DEE617B6; Wed, 23 Dec 2015 13:38:44 +0000 (UTC) Authentication-Results: lists.linaro.org; dkim=fail reason="verification failed; unprotected key" header.d=linaro.org header.i=@linaro.org header.b=Mxs5m26i; 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 17118617BD; Wed, 23 Dec 2015 13:38:40 +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 1A266617C0; Wed, 23 Dec 2015 13:38:38 +0000 (UTC) Received: from mail-lf0-f43.google.com (mail-lf0-f43.google.com [209.85.215.43]) by lists.linaro.org (Postfix) with ESMTPS id 28286617B6 for ; Wed, 23 Dec 2015 13:38:37 +0000 (UTC) Received: by mail-lf0-f43.google.com with SMTP id p203so148775334lfa.0 for ; Wed, 23 Dec 2015 05:38:37 -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=/yIMGvKlkAjKZ+4ejpMpEeuY5AlOudUYcEVYJGxFFSI=; b=Mxs5m26id885vZBF4XnPLChdrTNT2u+IdzTVLFduXE31kog6EaumBk9tKqo9Pzto3g 513ReBq3vXOnjSzQ/fkrd/OkCs3PmcrrUrX+4MNL5l38IxO6p8DCq/LkNiTjNBSjhrlU k9sT25prqNcwjeq0lOJNII133IKFBdRGr6jhs= 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=/yIMGvKlkAjKZ+4ejpMpEeuY5AlOudUYcEVYJGxFFSI=; b=RvCHfXizyoMQcgJR40ANNGZdpq68BpEy4BEHQ6DOW0FWk66TY64wv8srJ5wXaMJcfw Tj3oqZwQvJg9ePuR3CPA55pm+jCYw4cKZDQsZTp7pUs+zDIsq7pKgpUmYtrI9q8FwaOJ fasO58EQsxaNmWeSVagQLcbFCn1hBanNRW6GFaXc544gsNccBATNfAhL9VdrcEhG3Up1 7jcWXv74nIiPkYCHpgZCiDtZXa5KTF9cK3Hc9+ego2ALwalxA+2AxiLVzmI7rdgpngzn oJniOQ82BIS7LUw2/PYyOUYq8aAev3qw2hU0F7dYR5DXePdiiWfHT/9chCx1igmdVTB3 E11g== X-Gm-Message-State: ALoCoQkBdw1WAFq0/URm0bkOrnW7aMOaoHNnpQ4oT0c7PO91vMGlHekmsl71Qpc8lxDM9xspn1wUits7XaNurEm0SEwe0GpS3g== X-Received: by 10.25.149.139 with SMTP id x133mr8243891lfd.57.1450877916021; Wed, 23 Dec 2015 05:38:36 -0800 (PST) Received: from localhost.localdomain ([195.238.92.128]) by smtp.gmail.com with ESMTPSA id d2sm6501322lbc.11.2015.12.23.05.38.34 (version=TLS1_2 cipher=ECDHE-RSA-AES128-SHA bits=128/128); Wed, 23 Dec 2015 05:38:34 -0800 (PST) From: Ivan Khoronzhuk To: lng-odp@lists.linaro.org Date: Wed, 23 Dec 2015 15:38:28 +0200 Message-Id: <1450877908-24186-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 v4] 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" Reviewed-by: Bill Fischofer Signed-off-by: Ivan Khoronzhuk --- 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..8bc8521 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 +than 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