blob: 893c269099a58af8b27c5b2b4044160f86dd3bec [file] [log] [blame]
Stefan Roese4736bec2022-09-02 13:57:53 +02001.. SPDX-License-Identifier: GPL-2.0+
2
3Cyclic functions
4================
5
6The cyclic function execution infrastruture provides a way to periodically
7execute code, e.g. every 100ms. Examples for such functions might be LED
8blinking etc. The functions that are hooked into this cyclic list should
9be small timewise as otherwise the execution of the other code that relies
10on a high frequent polling (e.g. UART rx char ready check) might be
Weizhao Ouyang6cc9c3d2023-10-07 10:52:36 +000011delayed too much. To detect cyclic functions with an excessive execution
12time, the Kconfig option `CONFIG_CYCLIC_MAX_CPU_TIME_US` was introduced.
13It defines the maximum allowable execution time for such a cyclic function. The
14first time the execution of a cyclic function exceeds this interval, a warning
15will be displayed indicating the problem to the user.
Stefan Roese4736bec2022-09-02 13:57:53 +020016
17Registering a cyclic function
18-----------------------------
19
20To register a cyclic function, use something like this::
21
Rasmus Villemoesea36ada2024-05-21 10:46:52 +020022 struct donkey {
23 struct cyclic_info cyclic;
24 void (*say)(const char *s);
25 };
26
27 static void cyclic_demo(struct cyclic_info *c)
Stefan Roese4736bec2022-09-02 13:57:53 +020028 {
Rasmus Villemoesea36ada2024-05-21 10:46:52 +020029 struct donkey *donkey = container_of(c, struct donkey, cyclic);
30
31 donkey->say("Are we there yet?");
Stefan Roese4736bec2022-09-02 13:57:53 +020032 }
Rasmus Villemoesea36ada2024-05-21 10:46:52 +020033
34 int donkey_init(void)
Stefan Roese4736bec2022-09-02 13:57:53 +020035 {
Rasmus Villemoesea36ada2024-05-21 10:46:52 +020036 struct donkey *donkey;
37
38 /* Initialize donkey ... */
39
Stefan Roese4736bec2022-09-02 13:57:53 +020040 /* Register demo cyclic function */
Rasmus Villemoesea36ada2024-05-21 10:46:52 +020041 cyclic_register(&donkey->cyclic, cyclic_demo, 10 * 1000, "cyclic_demo");
Stefan Roese4736bec2022-09-02 13:57:53 +020042
43 return 0;
44 }
45
46This will register the function `cyclic_demo()` to be periodically
47executed all 10ms.
48
49How is this cyclic functionality integrated / executed?
50--------------------------------------------------------
51
52The cyclic infrastructure integrates the main function responsible for
53calling all registered cyclic functions cyclic_run() into the common
54WATCHDOG_RESET macro. This guarantees that cyclic_run() is executed
55very often, which is necessary for the cyclic functions to get scheduled
56and executed at their configured periods.