From patchwork Mon Feb 13 22:47:53 2017 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Bill Fischofer X-Patchwork-Id: 93914 Delivered-To: patch@linaro.org Received: by 10.140.20.99 with SMTP id 90csp1304605qgi; Mon, 13 Feb 2017 14:48:07 -0800 (PST) X-Received: by 10.200.34.146 with SMTP id f18mr25789671qta.39.1487026087716; Mon, 13 Feb 2017 14:48:07 -0800 (PST) Return-Path: Received: from lists.linaro.org (lists.linaro.org. [54.225.227.206]) by mx.google.com with ESMTP id i67si8278251qkf.334.2017.02.13.14.48.07; Mon, 13 Feb 2017 14:48:07 -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; dmarc=pass (p=NONE sp=NONE dis=NONE) header.from=linaro.org Received: by lists.linaro.org (Postfix, from userid 109) id F32C762DD4; Mon, 13 Feb 2017 22:48:06 +0000 (UTC) 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=-1.9 required=5.0 tests=BAYES_00, RCVD_IN_DNSWL_NONE, RCVD_IN_MSPIKE_H3, RCVD_IN_MSPIKE_WL, 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 8F9CC62C24; Mon, 13 Feb 2017 22:48:01 +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 F074262D3D; Mon, 13 Feb 2017 22:47:59 +0000 (UTC) Received: from mail-ot0-f172.google.com (mail-ot0-f172.google.com [74.125.82.172]) by lists.linaro.org (Postfix) with ESMTPS id A41A462C22 for ; Mon, 13 Feb 2017 22:47:58 +0000 (UTC) Received: by mail-ot0-f172.google.com with SMTP id f9so80177685otd.1 for ; Mon, 13 Feb 2017 14:47:58 -0800 (PST) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:date:message-id; bh=t7s4GkRfBcEJSudLp5RviqlEnXRb5ql0ojWqwhQcJn8=; b=ArDVm1ajuUMFlHEa0EHMVIg8IOZ35erZlXlLu82Wh8eE1dfOwkEuU553HnJHFIPOqs lXJxcjR4JjSku9YlYYF1udzjPzY81lFFeuc3ZBfaSpTv/xKwNGwtpGpvtREqbNBPjVhA UR3bLEVSaf+B/Kr3Iyo49KIBjoSfnz4xjyZhr1F4n6YZb0DXuJeGDPJQ24q8rU97vZ57 44BM9hSt83qhqE75ImW0zti7qflKvSb47105pzq/TPxm5co9XkUeKzZ0T96LYGvXJ7j1 C4l42GgV1zMex0pKSi2/kl1LsA3KqT9PC4hQ3kzLlj4xKGNZ9WaUZnqSZWfLsObyK+3v TxFg== X-Gm-Message-State: AMke39n+BUh3CFpjOua8HIDM4IDoHNFyrzWC93Xzdb3n39MYIGl3nOTFA83Gt/2JA3RLwJgKME0= X-Received: by 10.157.60.99 with SMTP id j32mr13320311ote.70.1487026078072; Mon, 13 Feb 2017 14:47:58 -0800 (PST) Received: from localhost.localdomain (cpe-70-121-83-241.austin.res.rr.com. [70.121.83.241]) by smtp.gmail.com with ESMTPSA id 205sm5181779oid.4.2017.02.13.14.47.56 (version=TLS1_2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Mon, 13 Feb 2017 14:47:57 -0800 (PST) From: Bill Fischofer To: lng-odp@lists.linaro.org Date: Mon, 13 Feb 2017 16:47:53 -0600 Message-Id: <20170213224753.15361-1-bill.fischofer@linaro.org> X-Mailer: git-send-email 2.11.0.295.gd7dffce Subject: [lng-odp] [PATCH] doc: userguide: add portability and usage info for odp time apis 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: , Errors-To: lng-odp-bounces@lists.linaro.org Sender: "lng-odp" Clarify and expand on portability and performance considerations regarding the use of the ODP time APIs in fulfillment of JIRA issue https://projects.linaro.org/browse/ODP-575 Signed-off-by: Bill Fischofer --- doc/users-guide/users-guide.adoc | 32 +++++++++++++++++++++----------- 1 file changed, 21 insertions(+), 11 deletions(-) -- 2.11.0.295.gd7dffce diff --git a/doc/users-guide/users-guide.adoc b/doc/users-guide/users-guide.adoc index 41c57d1c..05bade8c 100755 --- a/doc/users-guide/users-guide.adoc +++ b/doc/users-guide/users-guide.adoc @@ -362,31 +362,41 @@ 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. +application and presents a convenient way to get access to an +implementation-defined 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()`. +The local time API is designed to be used within one thread and obtaining +local time may be more efficient in some implementations than global +time. Local time stamps are local to the calling thread and should not be +shared with other threads, as local time is not guaranteed to be consistent +between 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()`. +So, global time stamps may safely 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. +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. +during which a thread potentially busy loops the entire wait time. The `odp_time_t` opaque type represents local or global timestamps. +==== Portability Considerations +The ODP Time APIs are designed to permit high-precision relative time +measurement within an ODP application. No attempt is made to correlate an +`odp_time_t` object with "wall time" or any other external time reference. +As defined by the ODP specification, `odp_time_t` values are required to +be unique over a span of at least 10 years. Most implementations will choose +to implement time values using 64-bit values, whose wrap times exceed 500 +years, making wrapping concerns not relevant to ODP applications. + === 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