1/* SPDX-License-Identifier: GPL-2.0+ */
2/*
3 * A general-purpose cyclic execution infrastructure, to allow "small"
4 * (run-time wise) functions to be executed at a specified frequency.
5 * Things like LED blinking or watchdog triggering are examples for such
6 * tasks.
7 *
8 * Copyright (C) 2022 Stefan Roese <sr@denx.de>
9 */
10
11#ifndef __cyclic_h
12#define __cyclic_h
13
14#include <linux/list.h>
15#include <asm/types.h>
16
17/**
18 * struct cyclic_info - Information about cyclic execution function
19 *
20 * @func: Function to call periodically
21 * @ctx: Context pointer to get passed to this function
22 * @name: Name of the cyclic function, e.g. shown in the commands
23 * @delay_ns: Delay is ns after which this function shall get executed
24 * @start_time_us: Start time in us, when this function started its execution
25 * @cpu_time_us: Total CPU time of this function
26 * @run_cnt: Counter of executions occurances
27 * @next_call: Next time in us, when the function shall be executed again
28 * @list: List node
29 * @already_warned: Flag that we've warned about exceeding CPU time usage
30 */
31struct cyclic_info {
32	void (*func)(void *ctx);
33	void *ctx;
34	char *name;
35	uint64_t delay_us;
36	uint64_t start_time_us;
37	uint64_t cpu_time_us;
38	uint64_t run_cnt;
39	uint64_t next_call;
40	struct hlist_node list;
41	bool already_warned;
42};
43
44/** Function type for cyclic functions */
45typedef void (*cyclic_func_t)(void *ctx);
46
47#if defined(CONFIG_CYCLIC)
48/**
49 * cyclic_register - Register a new cyclic function
50 *
51 * @func: Function to call periodically
52 * @delay_us: Delay is us after which this function shall get executed
53 * @name: Cyclic function name/id
54 * @ctx: Context to pass to the function
55 * @return: pointer to cyclic_struct if OK, NULL on error
56 */
57struct cyclic_info *cyclic_register(cyclic_func_t func, uint64_t delay_us,
58				    const char *name, void *ctx);
59
60/**
61 * cyclic_unregister - Unregister a cyclic function
62 *
63 * @cyclic: Pointer to cyclic_struct of the function that shall be removed
64 * @return: 0 if OK, -ve on error
65 */
66int cyclic_unregister(struct cyclic_info *cyclic);
67
68/**
69 * cyclic_unregister_all() - Clean up cyclic functions
70 *
71 * This removes all cyclic functions
72 */
73int cyclic_unregister_all(void);
74
75/**
76 * cyclic_get_list() - Get cyclic list pointer
77 *
78 * Return the cyclic list pointer
79 *
80 * @return: pointer to cyclic_list
81 */
82struct hlist_head *cyclic_get_list(void);
83
84/**
85 * cyclic_run() - Interate over all registered cyclic functions
86 *
87 * Interate over all registered cyclic functions and if the it's function
88 * needs to be executed, then call into these registered functions.
89 */
90void cyclic_run(void);
91
92/**
93 * schedule() - Schedule all potentially waiting tasks
94 *
95 * Basically a wrapper for cyclic_run(), pontentially enhanced by some
96 * other parts, that need to get handled periodically.
97 */
98void schedule(void);
99#else
100static inline struct cyclic_info *cyclic_register(cyclic_func_t func,
101						  uint64_t delay_us,
102						  const char *name,
103						  void *ctx)
104{
105	return NULL;
106}
107
108static inline int cyclic_unregister(struct cyclic_info *cyclic)
109{
110	return 0;
111}
112
113static inline void cyclic_run(void)
114{
115}
116
117static inline void schedule(void)
118{
119}
120
121static inline int cyclic_unregister_all(void)
122{
123	return 0;
124}
125#endif
126
127#endif
128