Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from phobos.denx.de (phobos.denx.de [85.214.62.61]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by smtp.lore.kernel.org (Postfix) with ESMTPS id F3390C25B08 for ; Wed, 17 Aug 2022 07:54:14 +0000 (UTC) Received: from h2850616.stratoserver.net (localhost [IPv6:::1]) by phobos.denx.de (Postfix) with ESMTP id 5F642849EF; Wed, 17 Aug 2022 09:53:15 +0200 (CEST) Authentication-Results: phobos.denx.de; dmarc=none (p=none dis=none) header.from=denx.de Authentication-Results: phobos.denx.de; spf=pass smtp.mailfrom=u-boot-bounces@lists.denx.de DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=denx.de; s=phobos-20191101; t=1660722796; bh=mXP15MLu9j/c/bsGWDrmM5rt7cTCSLGK2YD9r/c4eb0=; h=From:To:Cc:Subject:Date:In-Reply-To:References:List-Id: List-Unsubscribe:List-Archive:List-Post:List-Help:List-Subscribe: From; b=O37FL8hO9EPVrSXWYa6NzjFnGatxNycCvOiq4Axxca6MqHzT3W5HlHOs0RCrTBahq 27o/sGqhM/esEJK3jY8xJTX/hLr6ZLIbWIBuRcjYz47fI5qr7YTCXeDLOMuydiAeAz zYEKcTf/7M+MKUZDf++iCCjT3gaPk7izOHA6Qk3PeZHSsXjDlWCLR1MVudBm1rlL3f 7NteEAuPbdsAg5NH82fM9nIKn/FaVZFlpRqK46m+Us6pe5lO6agORi3gzrgSkWdrPp uSfQx5t/+4a0YKynFpBo5sp3T+PLiv2MJkfT84TERofhl3JGCafMQKZmuDPkRJC2En +YCrTz2HRUGhg== Received: by phobos.denx.de (Postfix, from userid 109) id D9D6480212; Wed, 17 Aug 2022 09:52:54 +0200 (CEST) Received: from mout-u-107.mailbox.org (mout-u-107.mailbox.org [IPv6:2001:67c:2050:101:465::107]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) (No client certificate requested) by phobos.denx.de (Postfix) with ESMTPS id 625A784988 for ; Wed, 17 Aug 2022 09:52:49 +0200 (CEST) Authentication-Results: phobos.denx.de; dmarc=none (p=none dis=none) header.from=denx.de Authentication-Results: phobos.denx.de; spf=fail smtp.mailfrom=sr@denx.de Received: from smtp1.mailbox.org (smtp1.mailbox.org [10.196.197.1]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange ECDHE (P-384) server-signature RSA-PSS (4096 bits) server-digest SHA256) (No client certificate requested) by mout-u-107.mailbox.org (Postfix) with ESMTPS id 4M70cH37Tcz9sjR; Wed, 17 Aug 2022 09:52:47 +0200 (CEST) From: Stefan Roese To: u-boot@lists.denx.de Cc: trini@konsulko.com, sjg@chromium.org, cchavva@marvell.com, awilliams@marvell.com Subject: [PATCH v5 7/8] cyclic: Add documentation Date: Wed, 17 Aug 2022 09:52:42 +0200 Message-Id: <20220817075243.3242445-8-sr@denx.de> In-Reply-To: <20220817075243.3242445-1-sr@denx.de> References: <20220817075243.3242445-1-sr@denx.de> MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-BeenThere: u-boot@lists.denx.de X-Mailman-Version: 2.1.39 Precedence: list List-Id: U-Boot discussion List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: u-boot-bounces@lists.denx.de Sender: "U-Boot" X-Virus-Scanned: clamav-milter 0.103.6 at phobos.denx.de X-Virus-Status: Clean Add documentation for the cyclic function infrastructure, including the cyclic command. Signed-off-by: Stefan Roese Reviewed-by: Simon Glass --- v5: - No change v4: - Minor spelling fix - Added Simon's RB tag v3: - New patch doc/develop/cyclic.rst | 50 ++++++++++++++++++++++++++++++++++++++++ doc/develop/index.rst | 1 + doc/usage/cmd/cyclic.rst | 45 ++++++++++++++++++++++++++++++++++++ doc/usage/index.rst | 1 + 4 files changed, 97 insertions(+) create mode 100644 doc/develop/cyclic.rst create mode 100644 doc/usage/cmd/cyclic.rst diff --git a/doc/develop/cyclic.rst b/doc/develop/cyclic.rst new file mode 100644 index 000000000000..43bedacb9f88 --- /dev/null +++ b/doc/develop/cyclic.rst @@ -0,0 +1,50 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +Cyclic functions +================ + +The cyclic function execution infrastruture provides a way to periodically +execute code, e.g. every 100ms. Examples for such functions might be LED +blinking etc. The functions that are hooked into this cyclic list should +be small timewise as otherwise the execution of the other code that relies +on a high frequent polling (e.g. UART rx char ready check) might be +delayed too much. To detect cyclic functions with a too long execution +time, the Kconfig option `CONFIG_CYCLIC_MAX_CPU_TIME_US` is introduced, +which configures the max allowed time for such a cyclic function. If it's +execution time exceeds this time, this cyclic function will get removed +from the cyclic list. + +Registering a cyclic function +----------------------------- + +To register a cyclic function, use something like this:: + + static void cyclic_demo(void *ctx) + { + /* Just a small dummy delay here */ + udelay(10); + } + + int board_init(void) + { + struct cyclic_info *cyclic; + + /* Register demo cyclic function */ + cyclic = cyclic_register(cyclic_demo, 10 * 1000, "cyclic_demo", NULL); + if (!cyclic) + printf("Registering of cyclic_demo failed\n"); + + return 0; + } + +This will register the function `cyclic_demo()` to be periodically +executed all 10ms. + +How is this cyclic functionality integrated / executed? +-------------------------------------------------------- + +The cyclic infrastructure integrates the main function responsible for +calling all registered cyclic functions cyclic_run() into the common +WATCHDOG_RESET macro. This guarantees that cyclic_run() is executed +very often, which is necessary for the cyclic functions to get scheduled +and executed at their configured periods. diff --git a/doc/develop/index.rst b/doc/develop/index.rst index f7ee09db2467..ce6b38e57629 100644 --- a/doc/develop/index.rst +++ b/doc/develop/index.rst @@ -27,6 +27,7 @@ Implementation ci_testing commands config_binding + cyclic devicetree/index distro driver-model/index diff --git a/doc/usage/cmd/cyclic.rst b/doc/usage/cmd/cyclic.rst new file mode 100644 index 000000000000..3085cc7204c0 --- /dev/null +++ b/doc/usage/cmd/cyclic.rst @@ -0,0 +1,45 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +cyclic command +============== + +Synopsis +-------- + +:: + + cyclic list + +Description +----------- + +The cyclic list command provides a list of the currently registered +cyclic functions. + +This shows the following information: + +Function + Function name + +cpu-time + Total time spent in this cyclic function. + +Frequency + Frequency of execution of this function, e.g. 100 times/s for a + pediod of 10ms. + + +See :doc:`../../develop/cyclic` for more information on cyclic functions. + +Example +------- + +:: + + => cyclic list + function: cyclic_demo, cpu-time: 52906 us, frequency: 99.20 times/s + +Configuration +------------- + +The cyclic command is only available if CONFIG_CMD_CYCLIC=y. diff --git a/doc/usage/index.rst b/doc/usage/index.rst index 28f9683a3e6f..1a0665ec1b78 100644 --- a/doc/usage/index.rst +++ b/doc/usage/index.rst @@ -33,6 +33,7 @@ Shell commands cmd/bootz cmd/cbsysinfo cmd/conitrace + cmd/cyclic cmd/dm cmd/echo cmd/env -- 2.37.2