| Message ID | 20220805142610.375427-9-sr@denx.de |
|---|---|
| State | Superseded |
| Delegated to: | Tom Rini |
| Headers | show |
| Series | Add support for cyclic function execution infrastruture | expand |
Hi Stefan, On Fri, 5 Aug 2022 at 08:26, Stefan Roese <sr@denx.de> wrote: > > Add documentation for the cyclic function infrastructure, including the > cyclic command. > > Signed-off-by: Stefan Roese <sr@denx.de> > --- > 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 Reviewed-by: Simon Glass <sjg@chromium.org> > > diff --git a/doc/develop/cyclic.rst b/doc/develop/cyclic.rst > new file mode 100644 > index 000000000000..f9cb2668b84c > --- /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. all 100ms. Examples for such functions might be LED s/all/every/ ? > +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. [..] Regards, SImon
Hi Simon. On 05.08.22 18:48, Simon Glass wrote: > Hi Stefan, > > On Fri, 5 Aug 2022 at 08:26, Stefan Roese <sr@denx.de> wrote: >> >> Add documentation for the cyclic function infrastructure, including the >> cyclic command. >> >> Signed-off-by: Stefan Roese <sr@denx.de> >> --- >> 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 > > Reviewed-by: Simon Glass <sjg@chromium.org> > >> >> diff --git a/doc/develop/cyclic.rst b/doc/develop/cyclic.rst >> new file mode 100644 >> index 000000000000..f9cb2668b84c >> --- /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. all 100ms. Examples for such functions might be LED > > s/all/every/ ? Thanks, changed in the next version. Thanks, Stefan >> +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. > > [..] > > Regards, > SImon Viele Grüße, Stefan Roese
diff --git a/doc/develop/cyclic.rst b/doc/develop/cyclic.rst new file mode 100644 index 000000000000..f9cb2668b84c --- /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. 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. 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_struct *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 7c41e3f1b6e5..a2679ecc1b88 100644 --- a/doc/develop/index.rst +++ b/doc/develop/index.rst @@ -26,6 +26,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 16a3db5c0009..8adb151b6cc3 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
Add documentation for the cyclic function infrastructure, including the cyclic command. Signed-off-by: Stefan Roese <sr@denx.de> --- 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