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_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  */
  31 struct 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 */
  45 typedef 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  */
  57 struct 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  */
  66 int cyclic_unregister(struct cyclic_info *cyclic);
  67
  68 /**
  69  * cyclic_unregister_all() - Clean up cyclic functions
  70  *
  71  * This removes all cyclic functions
  72  */
  73 int 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  */
  82 struct 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  */
  90 void 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  */
  98 void schedule(void);
  99 #else
 100 static 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
 108 static inline int cyclic_unregister(struct cyclic_info *cyclic)
 109 {
 110         return 0;
 111 }
 112
 113 static inline void cyclic_run(void)
 114 {
 115 }
 116
 117 static inline void schedule(void)
 118 {
 119 }
 120
 121 static inline int cyclic_unregister_all(void)
 122 {
 123         return 0;
 124 }
 125 #endif
 126
 127 #endif