From mboxrd@z Thu Jan 1 00:00:00 1970 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 9A299ECAAD5 for ; Fri, 2 Sep 2022 11:59:18 +0000 (UTC) Received: from h2850616.stratoserver.net (localhost [IPv6:::1]) by phobos.denx.de (Postfix) with ESMTP id A689184AA7; Fri, 2 Sep 2022 13:58:21 +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=1662119901; bh=GUrJyk+oaAxpUHKCLzZ3I7EBohvfr9o3AhaidooxVyA=; h=From:To:Cc:Subject:Date:In-Reply-To:References:List-Id: List-Unsubscribe:List-Archive:List-Post:List-Help:List-Subscribe: From; b=gZlEIa7ztwhWFGkRmugeoVHBjLXjR9IYAI4akw6py+KXU/1C4LwlBKi9beP3ldUQ/ vqnGPRACgWf1PLZcr+VGrAEMxmd/3nysAyS5wdVAaWQ2tCBIVT1nM3LYd61r0i79Hk Xc5jmOJgbrTwjHbNAgFpwudIft0uefFQbXtC4paFz9B8eg63RE59rV9IoMT4IKeScc deugt5n2+zRIWBzF91K1jeLObPGKr1WD5ADyaUnGwvBbwNxbpPCd5X4vNmj93ALr3R 7dsAC9H8Rsqhe+2M8oF+zS6Sekd9qaxlyYuWYhFNh8vFUWiqUR3+WT3C+Z+jd8rpjW tfGQwc4KNRjpw== Received: by phobos.denx.de (Postfix, from userid 109) id BCD1C84A8C; Fri, 2 Sep 2022 13:58:06 +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 4296C83E13 for ; Fri, 2 Sep 2022 13:58:00 +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 [IPv6:2001:67c:2050:b231:465::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 4MJxHp1l7Vz9sTW; Fri, 2 Sep 2022 13:57:58 +0200 (CEST) From: Stefan Roese To: u-boot@lists.denx.de Cc: trini@konsulko.com, sjg@chromium.org, awilliams@marvell.com, cchavva@marvell.com Subject: [PATCH v6 7/8] cyclic: Add documentation Date: Fri, 2 Sep 2022 13:57:53 +0200 Message-Id: <20220902115754.1280789-8-sr@denx.de> In-Reply-To: <20220902115754.1280789-1-sr@denx.de> References: <20220902115754.1280789-1-sr@denx.de> MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Rspamd-Queue-Id: 4MJxHp1l7Vz9sTW 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 --- v6: - No change 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.3