Merge branch '2022-09-13-add-support-for-cyclic-function-execution' into next

To quote the author:
This patchset adds the basic infrastructure to periodically execute
code, e.g. all 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. This patch also adds the Kconfig option
CONFIG_CYCLIC_MAX_CPU_TIME_US, 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.

How is this cyclic functionality executed?
This patchset 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.

This cyclic infrastructure will be used by a board specific function on
the NIC23 MIPS Octeon board, which needs to check periodically, if a
PCIe FLR has occurred.

Ideas how to continue:
One idea is to rename WATCHDOG_RESET to something like SCHEDULE and
move the watchdog_reset call into this cyclic infrastructure as well.
Or to perhaps move the shell UART RX ready polling to a cyclic
function.

It's also possible to extend the "cyclic" command, to support the
creation of periodically executed shell commands (for testing etc).

2 files changed, 51 insertions, 0 deletions

diff --git a/doc/develop/cyclic.rst b/doc/develop/cyclic.rst
new file mode 100644
index 00000000000..43bedacb9f8
--- /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 f7ee09db246..ce6b38e5762 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