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