include/cyclic.h

   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_drv - Cyclic driver internal data
  19  *
  20  * @cyclic_list: Cylic list node
  21  * @cyclic_ready: Flag if cyclic infrastructure is ready
  22  * @cyclic_running: Flag if cyclic infrastructure is running
  23  */
  24 struct cyclic_drv {
  25         struct list_head cyclic_list;
  26         bool cyclic_ready;
  27         bool cyclic_running;
  28 };
  29
  30 /**
  31  * struct cyclic_info - Information about cyclic execution function
  32  *
  33  * @func: Function to call periodically
  34  * @ctx: Context pointer to get passed to this function
  35  * @name: Name of the cyclic function, e.g. shown in the commands
  36  * @delay_ns: Delay is ns after which this function shall get executed
  37  * @start_time_us: Start time in us, when this function started its execution
  38  * @cpu_time_us: Total CPU time of this function
  39  * @run_cnt: Counter of executions occurances
  40  * @next_call: Next time in us, when the function shall be executed again
  41  * @list: List node
  42  * @already_warned: Flag that we've warned about exceeding CPU time usage
  43  */
  44 struct cyclic_info {
  45         void (*func)(void *ctx);
  46         void *ctx;
  47         char *name;
  48         uint64_t delay_us;
  49         uint64_t start_time_us;
  50         uint64_t cpu_time_us;
  51         uint64_t run_cnt;
  52         uint64_t next_call;
  53         struct list_head list;
  54         bool already_warned;
  55 };
  56
  57 /** Function type for cyclic functions */
  58 typedef void (*cyclic_func_t)(void *ctx);
  59
  60 #if defined(CONFIG_CYCLIC)
  61 /**
  62  * cyclic_register - Register a new cyclic function
  63  *
  64  * @func: Function to call periodically
  65  * @delay_us: Delay is us after which this function shall get executed
  66  * @name: Cyclic function name/id
  67  * @ctx: Context to pass to the function
  68  * @return: pointer to cyclic_struct if OK, NULL on error
  69  */
  70 struct cyclic_info *cyclic_register(cyclic_func_t func, uint64_t delay_us,
  71                                     const char *name, void *ctx);
  72
  73 /**
  74  * cyclic_unregister - Unregister a cyclic function
  75  *
  76  * @cyclic: Pointer to cyclic_struct of the function that shall be removed
  77  * @return: 0 if OK, -ve on error
  78  */
  79 int cyclic_unregister(struct cyclic_info *cyclic);
  80
  81 /**
  82  * cyclic_init() - Set up cyclic functions
  83  *
  84  * Init a list of cyclic functions, so that these can be added as needed
  85  */
  86 int cyclic_init(void);
  87
  88 /**
  89  * cyclic_uninit() - Clean up cyclic functions
  90  *
  91  * This removes all cyclic functions
  92  */
  93 int cyclic_uninit(void);
  94
  95 /**
  96  * cyclic_get_list() - Get cyclic list pointer
  97  *
  98  * Return the cyclic list pointer
  99  *
 100  * @return: pointer to cyclic_list
 101  */
 102 struct list_head *cyclic_get_list(void);
 103
 104 /**
 105  * cyclic_run() - Interate over all registered cyclic functions
 106  *
 107  * Interate over all registered cyclic functions and if the it's function
 108  * needs to be executed, then call into these registered functions.
 109  */
 110 void cyclic_run(void);
 111
 112 /**
 113  * schedule() - Schedule all potentially waiting tasks
 114  *
 115  * Basically a wrapper for cyclic_run(), pontentially enhanced by some
 116  * other parts, that need to get handled periodically.
 117  */
 118 void schedule(void);
 119 #else
 120 static inline struct cyclic_info *cyclic_register(cyclic_func_t func,
 121                                                   uint64_t delay_us,
 122                                                   const char *name,
 123                                                   void *ctx)
 124 {
 125         return NULL;
 126 }
 127
 128 static inline int cyclic_unregister(struct cyclic_info *cyclic)
 129 {
 130         return 0;
 131 }
 132
 133 static inline void cyclic_run(void)
 134 {
 135 }
 136
 137 static inline void schedule(void)
 138 {
 139 }
 140
 141 static inline int cyclic_init(void)
 142 {
 143         return 0;
 144 }
 145
 146 static inline int cyclic_uninit(void)
 147 {
 148         return 0;
 149 }
 150 #endif
 151
 152 #endif