1 /*
2 * Copyright (c) 2020 HiSilicon (Shanghai) Technologies CO., LIMITED.
3 * Licensed under the Apache License, Version 2.0 (the "License");
4 * you may not use this file except in compliance with the License.
5 * You may obtain a copy of the License at
6 *
7 * http://www.apache.org/licenses/LICENSE-2.0
8 *
9 * Unless required by applicable law or agreed to in writing, software
10 * distributed under the License is distributed on an "AS IS" BASIS,
11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 * See the License for the specific language governing permissions and
13 * limitations under the License.
14 */
15 /**
16 * @defgroup timer Timer
17 * @ingroup linux
18 */
19
20 #ifndef _LINUX_TIMER_H
21 #define _LINUX_TIMER_H
22
23 #include "linux/kernel.h"
24 #include "los_spinlock.h"
25
26 #ifdef __cplusplus
27 extern "C" {
28 #endif /* __cplusplus */
29
30 typedef unsigned long ULONG;
31
32 typedef struct timer_list {
33 ULONG expires; /**< Timing duration of the timer. */
34 VOID (*function)(struct timer_list *); /**< Callback function that handles timer timeout. */
35 UINT16 timerid; /**< Timer ID. */
36 UINT32 flag; /**< Indicates whether the timer is valid. */
37 #define TIMER_VALID 0xABCDDCBA
38 #define TIMER_UNVALID 0xDCBAABCD
39 BOOL created; /**< Not used. */
40 SPIN_LOCK_S lock; /**< Private spinlock. */
41 } timer_list_t;
42
43 /* This API is not provided externally. */
timer_pending(const timer_list_t * timer)44 static inline int timer_pending(const timer_list_t *timer)
45 {
46 return 0;
47 }
48
49 /**
50 * @ingroup timer
51 * @brief Initialize a timer.
52 *
53 * @par Description:
54 * This API is used to initialize a timer.
55 *
56 * @attention
57 * <ul>
58 * <li>The parameter timer must be valid, otherwise, the system would be abnormal.</li>
59 * </ul>
60 *
61 * @param timer [IN] timer handle.
62 *
63 * @retval None.
64 * @par Dependency:
65 * <ul><li>timer.h: the header file that contains the API declaration.</li></ul>
66 * @see None.
67 */
68 extern void init_timer(timer_list_t *timer);
69
70 /**
71 * @ingroup timer
72 * @brief Statically defines and initializes a timer.
73 *
74 * @par Description:
75 * This API is used to statically define and initialize a timer.
76 *
77 * @attention
78 * <ul>
79 * <li>The parameter timer must be valid, otherwise, the system would be abnormal.</li>
80 * </ul>
81 *
82 * @param timerName [IN] the name of the rtimer to be defined.
83 * @param func [IN] callback function that handles timer timeout.
84 *
85 * @retval None.
86 * @par Dependency:
87 * <ul><li>timer.h: the header file that contains the API declaration.</li></ul>
88 * @see None.
89 */
90 #define DEFINE_TIMER(timerName, func) \
91 timer_list_t timerName = {.expires = 0, \
92 .function = (func), \
93 .timerid = 0, \
94 .flag = TIMER_UNVALID, \
95 .created = FALSE, \
96 SPIN_LOCK_INITIALIZER("linux_timer_spinlock")}
97
98 /**
99 * @ingroup timer
100 * @brief Initialize a timer.
101 *
102 * @par Description:
103 * This API is used to initialize a timer.
104 *
105 * @attention
106 * <ul>
107 * <li>The parameter timer must be valid, otherwise, the system would be abnormal.</li>
108 * </ul>
109 *
110 * @param timer [IN] timer handle.
111 * @param function [IN] callback function that handles timer timeout.
112 * @param flags [IN] Indicates whether the timer is valid.
113 *
114 * @retval None.
115 * @par Dependency:
116 * <ul><li>timer.h: the header file that contains the API declaration.</li></ul>
117 * @see None.
118 */
119 extern void timer_setup(struct timer_list *timer, VOID (*function)(struct timer_list *), UINT32 flags);
120
121 /**
122 * @ingroup timer
123 * @brief create a timer and start it.
124 *
125 * @par Description:
126 * This API is used to create a timer and start it.
127 *
128 * @attention
129 * <ul>
130 * <li>The parameter timer must be valid, otherwise, the system would be abnormal. </li>
131 * <li>Please make sure the domain expires, function, data, timerid inside of timer is valid, otherwise,
132 * create timer would failure. Please refer to LOS_SwtmrCreate() for details.</li>
133 * <li>Do not forget to initialize the structure with 'init_timer()'
134 * before calling this function at the first time.</li>
135 * </ul>
136 *
137 * @param timer [IN] timer handle.
138 * The value range of timer->expires is [0, 0xFFFFFFFF].
139 *
140 * @retval None.
141 * @par Dependency:
142 * <ul><li>timer.h: the header file that contains the API declaration.</li></ul>
143 * @see None.
144 */
145 extern void add_timer(timer_list_t *timer);
146
147 /**
148 * @ingroup timer
149 * @brief delete a timer.
150 *
151 * @par Description:
152 * This API is used to delete a timer.
153 *
154 * @attention
155 * <ul>
156 * <li>The parameter timer must be valid, otherwise, the system would be abnormal. </li>
157 * <li>Please make sure the domain timerid is valid, otherwise, delete timer would be failed.</li>
158 * </ul>
159 *
160 * @param timer [IN] timer handle.
161 *
162 * @retval #0 Delete an inactive timer or delete an active timer failure.
163 * @retval #1 Delete an active timer successful.
164 * @par Dependency:
165 * <ul><li>timer.h: the header file that contains the API declaration.</li></ul>
166 * @see None.
167 */
168 extern int del_timer(timer_list_t *timer);
169
170 /**
171 * @ingroup timer
172 * @brief delete a timer(as same as del_timer()).
173 *
174 * @par Description:
175 * This API is used to delete a timer.
176 *
177 * @attention
178 * <ul>
179 * <li>The parameter t must be valid, otherwise, the system would be abnormal. </li>
180 * <li>Please make sure the domain timerid is valid, otherwise, delete timer would be failed.</li>
181 * </ul>
182 *
183 * @param timer [IN] timer handle.
184 *
185 * @retval #0 Delete an inactive timer or delete an active timer failure.
186 * @retval #1 Delete an active timer successful.
187 * @par Dependency:
188 * <ul><li>timer.h: the header file that contains the API declaration.</li></ul>
189 * @see None.
190 */
191 #define del_timer_sync(t) del_timer(t)
192
193 /**
194 * @ingroup timer
195 * @brief modifity a timer.
196 *
197 * @par Description:
198 * This API is used to modifity a timer. It takes effect only if the timer is in using.
199 * Actually, the specified timer would be deleted and then added again,
200 * so you can refer to add_timer() for details about the input parameters.
201 *
202 * @attention
203 * <ul>
204 * <li>The parameter timer must be valid, otherwise, the system would be abnormal. </li>
205 * <li>The parameter expires must not be 0, otherwise, modify timer would be failed. </li>
206 * <li>Please make sure the domain expires, function, data, timerid inside of timer is valid,
207 * otherwise, create timer would fail. Please refer to LOS_SwtmrCreate() for details.</li>
208 * </ul>
209 *
210 * @param timer [IN] timer handle.
211 * @param expires [IN] Timing duration of the software timer to be created (unit: milisecond).
212 *
213 * @retval None.
214 * @par Dependency:
215 * <ul><li>timer.h: the header file that contains the API declaration.</li></ul>
216 * @see None.
217 */
218 extern int mod_timer(timer_list_t *timer, ULONG expires);
219
220 /**
221 * @ingroup timer
222 * @brief Gets the address of the container structure.
223 *
224 * @par Description:
225 * This API gets the address of the structure.
226 * @attention
227 * None.
228 *
229 * @param ptr [IN] The pointer to the structure.
230 * @param paramTimer [IN] Input parameter of the callback function.
231 * @param structTimer [IN] The name of the #paramTimer in the structure.
232 *
233 * @retval The pointer to the address of the container structure.
234 * @par Dependency:
235 * <ul><li>timer.h: the header file that contains the API declaration.</li></ul>
236 * @see None.
237 */
238 #define from_timer(retPointer, paramTimer, structTimer) container_of(paramTimer, typeof(*retPointer), structTimer)
239
240 #ifdef __cplusplus
241 }
242 #endif /* __cplusplus */
243
244 #endif /* _LINUX_TIMER_H */
245