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 57109C2BB41 for ; Tue, 16 Aug 2022 10:30:02 +0000 (UTC) Received: from h2850616.stratoserver.net (localhost [IPv6:::1]) by phobos.denx.de (Postfix) with ESMTP id 0BE4F84A0A; Tue, 16 Aug 2022 12:28:57 +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=1660645737; bh=rVP+MUCuirC22oAnPPK1+21y9oylBhgpSoFFerKk9mM=; h=From:To:Cc:Subject:Date:In-Reply-To:References:List-Id: List-Unsubscribe:List-Archive:List-Post:List-Help:List-Subscribe: From; b=rFVMAaZizlQsRpbFK9IFUDjsbLPLDMxUCL1UhIvMSC6Xiv9ZcIVTHw2fEYTeL1bZB xl2bcAEIKgullxVq4/NL2JdYo3Lhngv8TLuNH7inBjZijxrJkA8R0mVDZp7dc7How1 +eFjpW3+gWmnzjM55fLw01XcvS0/dn6G/53za28YKfcRfJa1UexQAyDYbG9mrC0PQH 79X7yCYwOVlDk87tR97fxCAu4FcsUa4KJ+YvfCrIKXG5Nt98uL54ewuTxSXC9bY6CL hQ5sdVBFhm08eLpwT8/Gw/tec6LILsvgjy/jSPXZJZDZRXOrdbcYUCNWAG74gKe0YB ecMZ5W6CfIxmQ== Received: by phobos.denx.de (Postfix, from userid 109) id 7E180849BA; Tue, 16 Aug 2022 12:28:42 +0200 (CEST) Received: from mout-u-107.mailbox.org (mout-u-107.mailbox.org [80.241.59.207]) (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 E675D84541 for ; Tue, 16 Aug 2022 12:28:37 +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 smtp2.mailbox.org (smtp2.mailbox.org [10.196.197.2]) (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 4M6S6G601kz9sRJ; Tue, 16 Aug 2022 12:28:22 +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 v4 8/9] cyclic: Add documentation Date: Tue, 16 Aug 2022 12:28:15 +0200 Message-Id: <20220816102816.2938010-9-sr@denx.de> In-Reply-To: <20220816102816.2938010-1-sr@denx.de> References: <20220816102816.2938010-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 --- 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