From patchwork Mon Dec 21 12:53:20 2015 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Ivan Khoronzhuk X-Patchwork-Id: 58814 Delivered-To: patch@linaro.org Received: by 10.112.89.199 with SMTP id bq7csp2578418lbb; Mon, 21 Dec 2015 04:53:37 -0800 (PST) X-Received: by 10.141.7.69 with SMTP id j66mr26471285qhd.2.1450702417538; Mon, 21 Dec 2015 04:53:37 -0800 (PST) Return-Path: Received: from lists.linaro.org (lists.linaro.org. [54.225.227.206]) by mx.google.com with ESMTP id s107si29287156qgd.47.2015.12.21.04.53.37; Mon, 21 Dec 2015 04:53:37 -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 CE6236172F; Mon, 21 Dec 2015 12:53:36 +0000 (UTC) Authentication-Results: lists.linaro.org; dkim=fail reason="verification failed; unprotected key" header.d=linaro.org header.i=@linaro.org header.b=T3qDtT5S; 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 7934A615EF; Mon, 21 Dec 2015 12:53:32 +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 D54886166C; Mon, 21 Dec 2015 12:53:29 +0000 (UTC) Received: from mail-lb0-f170.google.com (mail-lb0-f170.google.com [209.85.217.170]) by lists.linaro.org (Postfix) with ESMTPS id 88207615E8 for ; Mon, 21 Dec 2015 12:53:28 +0000 (UTC) Received: by mail-lb0-f170.google.com with SMTP id oh2so14558836lbb.3 for ; Mon, 21 Dec 2015 04:53:28 -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=imi+8fc0W06B4X7eAkahiuy9atwCSmhH/Zzi9klp+/Q=; b=T3qDtT5SiYEaKztMN82eFuLGdljLhaxEx1EXDTMXMVIIaxy3VAGl5wSKlVXVzdqoB+ 6cj5rJoqkNlL6x4c/9r09ry+ytL00Z8E82JU/RRLy1Gky6sTeJ1/PWjjU04743mZHiB2 M+IXkz5UcOXqKYd1bDgzcI+UwoV32tOFDcaeM= 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=imi+8fc0W06B4X7eAkahiuy9atwCSmhH/Zzi9klp+/Q=; b=cc0jEJHFns6Ei35PG2kuh7YKEklH3Qx7h9Uk93kDFa7ZzE5yTq4TiHsHp/lFNOfwBB OLYxIRKBKnDrIF0LE/6F5tNw780vUQGLhAuMzwbya2FMRjFav8Yk2tLOySmO0nj8SR+j plBfTZzjWjDY3kzYcH3hYcMGauswVMtEKgEFJk8oTl9IrgyWjeIbEVWMxBUB8ngFelfQ 5KrEvHtc5YqJIwDAILPeSEYY/Z2G9At2AjZ9XZp0V/3VLJ6anQFjNqGC6YYwyyflndqD Pvp9WFE+gBSKU5oaP3wsPgV/sY14vlWDS6ugrkpZlucFG8Ais52H045fUGzMZt6iE5OA Epbw== X-Gm-Message-State: ALoCoQlXh97pooJ7Nt/C+Q66U+VK2ke0kd6MZ4167WAlAFI+9iJwMSQpsFKZkE3255Hsecg6EjXLAklE/MtiCsYyWrSrOBEJew== X-Received: by 10.112.156.39 with SMTP id wb7mr6140025lbb.96.1450702407395; Mon, 21 Dec 2015 04:53:27 -0800 (PST) Received: from localhost.localdomain ([195.238.92.128]) by smtp.gmail.com with ESMTPSA id e2sm4919100lfb.25.2015.12.21.04.53.25 (version=TLS1_2 cipher=ECDHE-RSA-AES128-SHA bits=128/128); Mon, 21 Dec 2015 04:53:25 -0800 (PST) From: Ivan Khoronzhuk To: lng-odp@lists.linaro.org Date: Mon, 21 Dec 2015 14:53:20 +0200 Message-Id: <1450702400-21150-1-git-send-email-ivan.khoronzhuk@linaro.org> X-Mailer: git-send-email 1.9.1 X-Topics: patch Subject: [lng-odp] [lng-od] [API-NEXT PATCH v2] 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 --- 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..b11d050 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 time source. +The time API consists of two main parts: local time API and global time API. + +Local time +The local time API is supposed to be used within one thread and can be faster +then 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 supposed 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 application life cycle. +The time API includes functions to operate with time, such +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 or local or global timestamp, the +responsibility is on a user to use time operations with appropriate time type. + === 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