1 /*
2  * Copyright (C) 2015-2017 Alibaba Group Holding Limited
3  */
4 
5 #ifndef K_TIMER_H
6 #define K_TIMER_H
7 
8 #ifdef __cplusplus
9 extern "C" {
10 #endif
11 
12 /** @addtogroup aos_rhino timer
13  *  Timer management
14  *
15  *  @{
16  */
17 
18 /**
19  * Timer operation
20  */
21 enum {
22     TIMER_CMD_CB = 0u,
23     TIMER_CMD_START,
24     TIMER_CMD_STOP,
25     TIMER_CMD_CHG,
26     TIMER_ARG_CHG,
27     TIMER_ARG_CHG_AUTO,
28     TIMER_CMD_DEL,
29     TIMER_CMD_DYN_DEL
30 };
31 
32 /**
33  * Timer callback
34  */
35 typedef void (*timer_cb_t)(void *timer, void *arg);
36 
37 /**
38  * Timer object
39  */
40 typedef struct {
41     /**<
42      *  When the timer is active, timer_list is linked from g_timer_head,
43      *  and sort by 'match'(timeout time).
44      */
45     klist_t       timer_list;
46     klist_t      *to_head;
47     const name_t *name;
48     timer_cb_t    cb;
49     void         *timer_cb_arg;
50     tick_t        match;        /**< Expected timeout point */
51     tick_t        remain;
52     tick_t        init_count;
53     tick_t        round_ticks;  /**< Timer period */
54     void         *priv;
55     kobj_type_t   obj_type;
56     uint8_t       timer_state;  /**< TIMER_DEACTIVE or TIMER_ACTIVE */
57     uint8_t       mm_alloc_flag;
58 } ktimer_t;
59 
60 /**
61  * Describe a timer operation
62  */
63 typedef struct {
64     ktimer_t   *timer;
65     uint8_t     cb_num;         /**< TIMER_CMD_START/STOP/... */
66     tick_t      first;
67 
68     union {
69         tick_t  round;
70         void   *arg;
71     } u;
72 } k_timer_queue_cb;
73 
74 typedef enum {
75     TIMER_DEACTIVE = 0u,
76     TIMER_ACTIVE
77 } k_timer_state_t;
78 
79 /**
80  * Create a timer.
81  *
82  * @param[in]  timer     pointer to the timer (the space is provided outside, by user)
83  * @param[in]  name      name of the timer
84  * @param[in]  cb        callbak of the timer
85  * @param[in]  first     ticks of the first timer triger
86  * @param[in]  round     ticks of the timer period, 0 means one-shot timer
87  * @param[in]  arg       the argument of the callback
88  * @param[in]  auto_run  auto run or not when the timer is created
89  *
90  * @return  the operation status, RHINO_SUCCESS is OK, others is error
91  */
92 kstat_t krhino_timer_create(ktimer_t *timer, const name_t *name, timer_cb_t cb,
93                             tick_t first, tick_t round, void *arg, uint8_t auto_run);
94 
95 /**
96  * Delete a timer.
97  *
98  * @param[in]  timer  pointer to a timer
99  *
100  * @return  the operation status, RHINO_SUCCESS is OK, others is error
101  */
102 kstat_t krhino_timer_del(ktimer_t *timer);
103 
104 #if (RHINO_CONFIG_KOBJ_DYN_ALLOC > 0)
105 /**
106  * Create and malloc a timer.
107  *
108  * @param[out] timer     pointer to the timer (the space is provided inside, from heap)
109  * @param[in]  name      name of the timer
110  * @param[in]  cb        callbak of the timer
111  * @param[in]  first     ticks of the first timer triger
112  * @param[in]  round     ticks of the timer period, 0 means one-shot timer
113  * @param[in]  arg       the argument of the callback
114  * @param[in]  auto_run  auto run or not when the timer is created
115  *
116  * @return  the operation status, RHINO_SUCCESS is OK, others is error
117  */
118 kstat_t krhino_timer_dyn_create(ktimer_t **timer, const name_t *name, timer_cb_t cb,
119                                 tick_t first, tick_t round, void *arg, uint8_t auto_run);
120 /**
121  * Delete and free a timer.
122  *
123  * @param[in]  timer  pointer to a timer
124  *
125  * @return  the operation status, RHINO_SUCCESS is OK, others is error
126  */
127 kstat_t krhino_timer_dyn_del(ktimer_t *timer);
128 #endif
129 
130 /**
131  * This function will start a timer.
132  *
133  * @param[in]  timer  pointer to the timer
134  *
135  * @return  the operation status, RHINO_SUCCESS is OK, others is error
136  */
137 kstat_t krhino_timer_start(ktimer_t *timer);
138 
139 /**
140  * This function will stop a timer.
141  *
142  * @param[in]  timer  pointer to the timer
143  *
144  * @return  the operation status, RHINO_SUCCESS is OK, others is error
145  */
146 kstat_t krhino_timer_stop(ktimer_t *timer);
147 
148 /**
149  * Change attributes of a timer.
150  * @note this func should follow the sequence as timer_stop -> timer_change -> timer_start
151  *
152  * @param[in]  timer     pointer to the timer
153  * @param[in]  first     ticks of the first timer triger
154  * @param[in]  round     ticks of the timer period, 0 means one-shot timer
155  *
156  * @return  the operation status, RHINO_SUCCESS is OK, others is error
157  */
158 kstat_t krhino_timer_change(ktimer_t *timer, tick_t first, tick_t round);
159 
160 /**
161  * Change attributes of a timer without timer_stop and timer_start.
162  *
163  * @param[in]  timer     pointer to the timer
164  * @param[in]  first     ticks of the first timer triger
165  * @param[in]  round     ticks of the timer period, 0 means one-shot timer
166  *
167  * @return  the operation status, RHINO_SUCCESS is OK, others is error
168  */
169 kstat_t krhino_timer_arg_change_auto(ktimer_t *timer, void *arg);
170 
171 /**
172  * Change callback arg attributes of a timer.
173  *
174  * @param[in]  timer     pointer to the timer
175  * @param[in]  arg       timer callback arg
176  *
177  * @return  the operation status, RHINO_SUCCESS is OK, others is error
178  */
179 kstat_t krhino_timer_arg_change(ktimer_t *timer, void *arg);
180 
181 /** @} */
182 
183 #ifdef __cplusplus
184 }
185 #endif
186 
187 #endif /* K_TIMER_H */
188 
189