From patchwork Wed Jul 12 13:38:07 2017 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Michael Tokarev X-Patchwork-Id: 107508 Delivered-To: patch@linaro.org Received: by 10.140.101.44 with SMTP id t41csp838674qge; Wed, 12 Jul 2017 06:51:16 -0700 (PDT) X-Received: by 10.55.167.211 with SMTP id q202mr6708999qke.77.1499867476575; Wed, 12 Jul 2017 06:51:16 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1499867476; cv=none; d=google.com; s=arc-20160816; b=BhYMzBuL2UqSRY8fkiQS/RdHduq3Yv6LitcxZxEa5sebzElhyW5tv4wwGBFD1fsdT1 vmGZcsSQWE6PCjOewSprVAxMH+Z+XGpdjriJyjUToGD23yfSKVzFO/sDdEU25ehvlhbu 560Z8X2RPvGE+Kd9B0tmgLPcSHRnuA5I/dZKEP/5boDKiK4m9oT70K569YTcYRJzJRxX jbWLXwUqH6CdHZ/iFcjmvlUhHDFz06rYMvrDaJ6BIe0WzdDvwIfwzg60xIn76ijq8Z5R cYg1Nbe/ZhA1fDRdFZhty+GZ3nBLM65x1/cBq4Xp48XBVo922VkLhVczi2Dz4mCyZbzl HKWQ== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=sender:errors-to:cc:list-subscribe:list-help:list-post:list-archive :list-unsubscribe:list-id:precedence:subject :content-transfer-encoding:mime-version:references:in-reply-to :references:in-reply-to:message-id:date:to:from :arc-authentication-results; bh=5iW8o2pd9INYztYV2a1HbCzxmHJggMOrXHKccOcMT9U=; b=dRUXEgfb5KMztzKrJFc1G5ENOqnvCgMlGeBmsFHEZ4sMgHsloDK8BragUOj88FexQp g3mrECZN+g1y7cdTLDxk/hL+2alMQELBdU7W5TLdBnBminIbpWW0WcXTrRqe6Sk31wSr 8lUaWfrEK3+dg7Ue5fyFvCWBQRN5i8PK7h6ly/0vOyKwWrlwnRnxv5dQTpWJP55fiJDD luaezI0B5Mm/DHPDfluR7pbacd5xtlepytxzgHXDQ28eA9Ir4iP2AywAy4Pd8rGUUdJI VzIbHU3bFSoCcfp252qEpxoEWeohJGLU9XPHbYm6Bq3a7fw4q7ArW21it976mj3IWDKk w7jw== ARC-Authentication-Results: i=1; mx.google.com; spf=pass (google.com: domain of qemu-devel-bounces+patch=linaro.org@nongnu.org designates 208.118.235.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+patch=linaro.org@nongnu.org Return-Path: Received: from lists.gnu.org (lists.gnu.org. [208.118.235.17]) by mx.google.com with ESMTPS id m8si2331955qtg.273.2017.07.12.06.51.16 for (version=TLS1 cipher=AES128-SHA bits=128/128); Wed, 12 Jul 2017 06:51:16 -0700 (PDT) Received-SPF: pass (google.com: domain of qemu-devel-bounces+patch=linaro.org@nongnu.org designates 208.118.235.17 as permitted sender) client-ip=208.118.235.17; Authentication-Results: mx.google.com; spf=pass (google.com: domain of qemu-devel-bounces+patch=linaro.org@nongnu.org designates 208.118.235.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+patch=linaro.org@nongnu.org Received: from localhost ([::1]:53222 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1dVI2r-00023w-Q6 for patch@linaro.org; Wed, 12 Jul 2017 09:51:13 -0400 Received: from eggs.gnu.org ([2001:4830:134:3::10]:35712) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1dVHyP-0006kk-L2 for qemu-devel@nongnu.org; Wed, 12 Jul 2017 09:46:39 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1dVHyL-0003Pl-IC for qemu-devel@nongnu.org; Wed, 12 Jul 2017 09:46:37 -0400 Received: from isrv.corpit.ru ([86.62.121.231]:60401) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1dVHyL-0003Ny-49; Wed, 12 Jul 2017 09:46:33 -0400 Received: from tsrv.tls.msk.ru (tsrv.tls.msk.ru [192.168.177.2]) by isrv.corpit.ru (Postfix) with ESMTP id 29B7B40F67; Wed, 12 Jul 2017 16:46:31 +0300 (MSK) Received: from tls.msk.ru (mjt.vpn.tls.msk.ru [192.168.177.99]) by tsrv.tls.msk.ru (Postfix) with SMTP id A534EAEB; Wed, 12 Jul 2017 16:38:14 +0300 (MSK) Received: (nullmailer pid 29053 invoked by uid 1000); Wed, 12 Jul 2017 13:38:12 -0000 From: Michael Tokarev To: qemu-devel@nongnu.org Date: Wed, 12 Jul 2017 16:38:07 +0300 Message-Id: X-Mailer: git-send-email 2.11.0 In-Reply-To: References: In-Reply-To: References: MIME-Version: 1.0 X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] [fuzzy] X-Received-From: 86.62.121.231 Subject: [Qemu-devel] [PULL 11/13] include/hw/ptimer.h: Add documentation comments X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.21 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: qemu-trivial@nongnu.org, Peter Maydell , Michael Tokarev Errors-To: qemu-devel-bounces+patch=linaro.org@nongnu.org Sender: "Qemu-devel" From: Peter Maydell Add documentation comments describing the public API of the ptimer countdown timer. Signed-off-by: Peter Maydell Reviewed-by: Philippe Mathieu-Daudé Signed-off-by: Michael Tokarev --- include/hw/ptimer.h | 120 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 120 insertions(+) -- 2.11.0 diff --git a/include/hw/ptimer.h b/include/hw/ptimer.h index eafc3f0a86..fc4ef5cc1d 100644 --- a/include/hw/ptimer.h +++ b/include/hw/ptimer.h @@ -12,6 +12,20 @@ #include "qemu/timer.h" #include "migration/vmstate.h" +/* The ptimer API implements a simple periodic countdown timer. + * The countdown timer has a value (which can be read and written via + * ptimer_get_count() and ptimer_set_count()). When it is enabled + * using ptimer_run(), the value will count downwards at the frequency + * which has been configured using ptimer_set_period() or ptimer_set_freq(). + * When it reaches zero it will trigger a QEMU bottom half handler, and + * can be set to either reload itself from a specified limit value + * and keep counting down, or to stop (as a one-shot timer). + * + * Forgetting to set the period/frequency (or setting it to zero) is a + * bug in the QEMU device and will cause warning messages to be printed + * to stderr when the guest attempts to enable the timer. + */ + /* The default ptimer policy retains backward compatibility with the legacy * timers. Custom policies are adjusting the default one. Consider providing * a correct policy for your timer. @@ -59,15 +73,121 @@ typedef struct ptimer_state ptimer_state; typedef void (*ptimer_cb)(void *opaque); +/** + * ptimer_init - Allocate and return a new ptimer + * @bh: QEMU bottom half which is run on timer expiry + * @policy: PTIMER_POLICY_* bits specifying behaviour + * + * The ptimer returned must be freed using ptimer_free(). + * The ptimer takes ownership of @bh and will delete it + * when the ptimer is eventually freed. + */ ptimer_state *ptimer_init(QEMUBH *bh, uint8_t policy_mask); + +/** + * ptimer_free - Free a ptimer + * @s: timer to free + * + * Free a ptimer created using ptimer_init() (including + * deleting the bottom half which it is using). + */ void ptimer_free(ptimer_state *s); + +/** + * ptimer_set_period - Set counter increment interval in nanoseconds + * @s: ptimer to configure + * @period: period of the counter in nanoseconds + * + * Note that if your counter behaviour is specified as having a + * particular frequency rather than a period then ptimer_set_freq() + * may be more appropriate. + */ void ptimer_set_period(ptimer_state *s, int64_t period); + +/** + * ptimer_set_freq - Set counter frequency in Hz + * @s: ptimer to configure + * @freq: counter frequency in Hz + * + * This does the same thing as ptimer_set_period(), so you only + * need to call one of them. If the counter behaviour is specified + * as setting the frequency then this function is more appropriate, + * because it allows specifying an effective period which is + * precise to fractions of a nanosecond, avoiding rounding errors. + */ void ptimer_set_freq(ptimer_state *s, uint32_t freq); + +/** + * ptimer_get_limit - Get the configured limit of the ptimer + * @s: ptimer to query + * + * This function returns the current limit (reload) value + * of the down-counter; that is, the value which it will be + * reset to when it hits zero. + * + * Generally timer devices using ptimers should be able to keep + * their reload register state inside the ptimer using the get + * and set limit functions rather than needing to also track it + * in their own state structure. + */ uint64_t ptimer_get_limit(ptimer_state *s); + +/** + * ptimer_set_limit - Set the limit of the ptimer + * @s: ptimer + * @limit: initial countdown value + * @reload: if nonzero, then reset the counter to the new limit + * + * Set the limit value of the down-counter. The @reload flag can + * be used to emulate the behaviour of timers which immediately + * reload the counter when their reload register is written to. + */ void ptimer_set_limit(ptimer_state *s, uint64_t limit, int reload); + +/** + * ptimer_get_count - Get the current value of the ptimer + * @s: ptimer + * + * Return the current value of the down-counter. This will + * return the correct value whether the counter is enabled or + * disabled. + */ uint64_t ptimer_get_count(ptimer_state *s); + +/** + * ptimer_set_count - Set the current value of the ptimer + * @s: ptimer + * @count: count value to set + * + * Set the value of the down-counter. If the counter is currently + * enabled this will arrange for a timer callback at the appropriate + * point in the future. + */ void ptimer_set_count(ptimer_state *s, uint64_t count); + +/** + * ptimer_run - Start a ptimer counting + * @s: ptimer + * @oneshot: non-zero if this timer should only count down once + * + * Start a ptimer counting down; when it reaches zero the bottom half + * passed to ptimer_init() will be invoked. If the @oneshot argument is zero, + * the counter value will then be reloaded from the limit and it will + * start counting down again. If @oneshot is non-zero, then the counter + * will disable itself when it reaches zero. + */ void ptimer_run(ptimer_state *s, int oneshot); + +/** + * ptimer_stop - Stop a ptimer counting + * @s: ptimer + * + * Pause a timer (the count stays at its current value until ptimer_run() + * is called to start it counting again). + * + * Note that this can cause it to "lose" time, even if it is immediately + * restarted. + */ void ptimer_stop(ptimer_state *s); extern const VMStateDescription vmstate_ptimer;