[PATCH v5 7/8] cyclic: Add documentation

[Stefan Roese]

Add documentation for the cyclic function infrastructure, including the
cyclic command.

Signed-off-by: Stefan Roese <sr at denx.de>
Reviewed-by: Simon Glass <sjg at chromium.org>
---
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