1 /**
2  * @file lv_task.c
3  * An 'lv_task'  is a void (*fp) (void* param) type function which will be called periodically.
4  * A priority (5 levels + disable) can be assigned to lv_tasks.
5  */
6 
7 #ifndef LV_TASK_H
8 #define LV_TASK_H
9 
10 #ifdef __cplusplus
11 extern "C" {
12 #endif
13 
14 /*********************
15  *      INCLUDES
16  *********************/
17 #include "../lv_conf_internal.h"
18 
19 #include <stdint.h>
20 #include <stdbool.h>
21 #include "lv_mem.h"
22 #include "lv_ll.h"
23 
24 /*********************
25  *      DEFINES
26  *********************/
27 #ifndef LV_ATTRIBUTE_TASK_HANDLER
28 #define LV_ATTRIBUTE_TASK_HANDLER
29 #endif
30 
31 #define LV_NO_TASK_READY 0xFFFFFFFF
32 /**********************
33  *      TYPEDEFS
34  **********************/
35 
36 struct _lv_task_t;
37 
38 /**
39  * Tasks execute this type type of functions.
40  */
41 typedef void (*lv_task_cb_t)(struct _lv_task_t *);
42 
43 /**
44  * Possible priorities for lv_tasks
45  */
46 enum {
47     LV_TASK_PRIO_OFF = 0,
48     LV_TASK_PRIO_LOWEST,
49     LV_TASK_PRIO_LOW,
50     LV_TASK_PRIO_MID,
51     LV_TASK_PRIO_HIGH,
52     LV_TASK_PRIO_HIGHEST,
53     _LV_TASK_PRIO_NUM,
54 };
55 typedef uint8_t lv_task_prio_t;
56 
57 /**
58  * Descriptor of a lv_task
59  */
60 typedef struct _lv_task_t {
61     uint32_t period; /**< How often the task should run */
62     uint32_t last_run; /**< Last time the task ran */
63     lv_task_cb_t task_cb; /**< Task function */
64 
65     void * user_data; /**< Custom user data */
66 
67     int32_t repeat_count; /**< 1: Task times;  -1 : infinity;  0 : stop ;  n>0: residual times */
68     uint8_t prio : 3; /**< Task priority */
69 } lv_task_t;
70 
71 /**********************
72  * GLOBAL PROTOTYPES
73  **********************/
74 
75 /**
76  * Init the lv_task module
77  */
78 void _lv_task_core_init(void);
79 
80 //! @cond Doxygen_Suppress
81 
82 /**
83  * Call it  periodically to handle lv_tasks.
84  * @return time till it needs to be run next (in ms)
85  */
86 LV_ATTRIBUTE_TASK_HANDLER uint32_t lv_task_handler(void);
87 
88 //! @endcond
89 
90 /**
91  * Create an "empty" task. It needs to initialized with at least
92  * `lv_task_set_cb` and `lv_task_set_period`
93  * @return pointer to the created task
94  */
95 lv_task_t * lv_task_create_basic(void);
96 
97 /**
98  * Create a new lv_task
99  * @param task_xcb a callback which is the task itself. It will be called periodically.
100  *                 (the 'x' in the argument name indicates that its not a fully generic function because it not follows
101  *                  the `func_name(object, callback, ...)` convention)
102  * @param period call period in ms unit
103  * @param prio priority of the task (LV_TASK_PRIO_OFF means the task is stopped)
104  * @param user_data custom parameter
105  * @return pointer to the new task
106  */
107 lv_task_t * lv_task_create(lv_task_cb_t task_xcb, uint32_t period, lv_task_prio_t prio, void * user_data);
108 
109 /**
110  * Delete a lv_task
111  * @param task pointer to task_cb created by task
112  */
113 void lv_task_del(lv_task_t * task);
114 
115 /**
116  * Set the callback the task (the function to call periodically)
117  * @param task pointer to a task
118  * @param task_cb the function to call periodically
119  */
120 void lv_task_set_cb(lv_task_t * task, lv_task_cb_t task_cb);
121 
122 /**
123  * Set new priority for a lv_task
124  * @param task pointer to a lv_task
125  * @param prio the new priority
126  */
127 void lv_task_set_prio(lv_task_t * task, lv_task_prio_t prio);
128 
129 /**
130  * Set new period for a lv_task
131  * @param task pointer to a lv_task
132  * @param period the new period
133  */
134 void lv_task_set_period(lv_task_t * task, uint32_t period);
135 
136 /**
137  * Make a lv_task ready. It will not wait its period.
138  * @param task pointer to a lv_task.
139  */
140 void lv_task_ready(lv_task_t * task);
141 
142 /**
143  * Set the number of times a task will repeat.
144  * @param task pointer to a lv_task.
145  * @param repeat_count -1 : infinity;  0 : stop ;  n>0: residual times
146  */
147 void lv_task_set_repeat_count(lv_task_t * task, int32_t repeat_count);
148 
149 /**
150  * Reset a lv_task.
151  * It will be called the previously set period milliseconds later.
152  * @param task pointer to a lv_task.
153  */
154 void lv_task_reset(lv_task_t * task);
155 
156 /**
157  * Enable or disable the whole  lv_task handling
158  * @param en: true: lv_task handling is running, false: lv_task handling is suspended
159  */
160 void lv_task_enable(bool en);
161 
162 /**
163  * Get idle percentage
164  * @return the lv_task idle in percentage
165  */
166 uint8_t lv_task_get_idle(void);
167 
168 /**
169  * Iterate through the tasks
170  * @param task NULL to start iteration or the previous return value to get the next task
171  * @return the next task or NULL if there is no more task
172  */
173 lv_task_t * lv_task_get_next(lv_task_t * task);
174 
175 /**********************
176  *      MACROS
177  **********************/
178 
179 #ifdef __cplusplus
180 } /* extern "C" */
181 #endif
182 
183 #endif
184