1
2 #ifndef _OSA_H_
3 #define _OSA_H_
4
5 #include <wifi_config_default.h>
6 #include "fsl_os_abstraction.h"
7 #include <osa_zephyr.h>
8 #include <wmerrno.h>
9 #include <wm_utils.h>
10
11 /*** Timer Management ***/
12 /** Create timer
13 *
14 * This function creates a timer.
15 *
16 * @param[in] timerHandle Pointer to the timer handle
17 * @param[in] ticks Period in ticks
18 * @param[in] call_back Timer expire callback function
19 * @param[in] cb_arg Timer callback data
20 * @param[in] reload Reload Options, valid values include \ref KOSA_TimerOnce
21 * or \ref KOSA_TimerPeriodic.
22 * @param[in] activate Activate Options, valid values include \ref
23 * OSA_TIMER_AUTO_ACTIVATE or \ref OSA_TIMER_NO_ACTIVATE
24 *
25 * @return KOSA_StatusSuccess if timer created successfully
26 * @return KOSA_StatusError if timer creation fails
27 */
28 osa_status_t OSA_TimerCreate(osa_timer_handle_t timerHandle,
29 osa_timer_tick ticks,
30 void (*call_back)(osa_timer_arg_t),
31 void *cb_arg,
32 osa_timer_t reload,
33 osa_timer_activate_t activate);
34
35 /** Activate timer
36 *
37 * This function activates (or starts) a timer that was previously created using
38 * OSA_TimerCreate(). If the timer had already started and was already in the
39 * active state, then this call is equivalent to OSA_TimerReset().
40 *
41 * @param[in] timerHandle Pointer to a timer handle
42 *
43 * @return KOSA_StatusSuccess if timer activated successfully
44 * @return KOSA_StatusError if timer activation fails
45 *
46 */
47 osa_status_t OSA_TimerActivate(osa_timer_handle_t timerHandle);
48
49 /** Change timer period
50 *
51 * This function changes the period of a timer that was previously created using
52 * OSA_TimerCreate(). This function changes the period of an active or dormant
53 * state timer.
54 *
55 * @param[in] timerHandle Pointer to a timer handle
56 * @param[in] ntime Time in ticks after which the timer will expire
57 * @param[in] block_time This option is currently not supported
58 *
59 * @return KOSA_StatusSuccess if timer change successfully
60 * @return KOSA_StatusError if timer change fails
61 */
62 osa_status_t OSA_TimerChange(osa_timer_handle_t timerHandle, osa_timer_tick ntime, osa_timer_tick block_time);
63
64 /** Check the timer active state
65 *
66 * This function checks if the timer is in the active or dormant state. A timer
67 * is in the dormant state if (a) it has been created but not started, or (b) it
68 * has expired and a one-shot timer.
69 *
70 * @param [in] timerHandle Pointer to a timer handle
71 *
72 * @return true if timer is active
73 * @return false if time is not active
74 */
75 bool OSA_TimerIsRunning(osa_timer_handle_t timerHandle);
76
77 /**
78 * Get the timer context
79 *
80 * This function helps to retrieve the timer context i.e. 'cb_arg' passed
81 * to OSA_TimerCreate().
82 *
83 * @param[in] timer_t Pointer to timer handle. The timer handle is received
84 * in the timer callback.
85 *
86 * @return The timer context i.e. the callback argument passed to
87 * OSA_TimerCreate().
88 */
89 void *OSA_TimerGetContext(osa_timer_handle_t timerHandle);
90
91 /** Reset timer
92 *
93 * This function resets a timer that was previously created using using
94 * OSA_TimerCreate(). If the timer had already been started and was already in
95 * the active state, then this call will cause the timer to re-evaluate its
96 * expiry time so that it is relative to when OSA_TimerReset() was called. If
97 * the timer was in the dormant state then this call behaves in the same way as
98 * OSA_TimerActivate().
99 *
100 * @param[in] timerHandle Pointer to a timer handle
101 *
102 * @return KOSA_StatusSuccess if timer reset successfully
103 * @return KOSA_StatusError if timer reset fails
104 */
105 osa_status_t OSA_TimerReset(osa_timer_handle_t timerHandle);
106
107 /** Deactivate timer
108 *
109 * This function deactivates (or stops) a timer that was previously started.
110 *
111 * @param [in] timerHandle handle populated by OSA_TimerCreate().
112 *
113 * @return KOSA_StatusSuccess if timer deactivate successfully
114 * @return KOSA_StatusError if timer deactivate fails
115 */
116 osa_status_t OSA_TimerDeactivate(osa_timer_handle_t timerHandle);
117
118 /** Destroy timer
119 *
120 * This function deletes a timer.
121 *
122 * @param[in] timerHandle Pointer to a timer handle
123 *
124 * @return KOSA_StatusSuccess if timer destroy successfully
125 * @return KOSA_StatusError if timer destroy fails
126 */
127 osa_status_t OSA_TimerDestroy(osa_timer_handle_t timerHandle);
128
129 /*
130 * Reader Writer Locks
131 * This is a generic implementation of reader writer locks
132 * which is reader priority.
133 * Not only it provides mutual exclusion but also synchronization.
134 * Six APIs are exposed to user which include.
135 * -# Create a reader writer lock
136 * -# Delete a reader writer lock
137 * -# Reader lock
138 * -# Reader unlock
139 * -# Writer lock
140 * -# Writer unlock
141 * The locking operation is timeout based.
142 * Caller can give a timeout from 0 (no wait) to
143 * infinite (wait forever)
144 */
145
146 typedef struct _rw_lock osa_rw_lock_t;
147 /** This is prototype of reader callback */
148 typedef int (*cb_fn)(osa_rw_lock_t *plock, unsigned int wait_time);
149
150 struct _rw_lock
151 {
152 /** Mutex for reader mutual exclusion */
153 OSA_MUTEX_HANDLE_DEFINE(reader_mutex);
154 /** Mutex for write mutual exclusion */
155 OSA_MUTEX_HANDLE_DEFINE(write_mutex);
156 /** Lock which when held by reader,
157 * writer cannot enter critical section
158 */
159 OSA_SEMAPHORE_HANDLE_DEFINE(rw_lock);
160 /** Function being called when first reader gets
161 * the lock
162 */
163 cb_fn reader_cb;
164 /** Counter to maintain number of readers
165 * in critical section
166 */
167 unsigned int reader_count;
168 };
169
170 int OSA_RWLockCreateWithCB(osa_rw_lock_t *plock, const char *mutex_name, const char *lock_name, cb_fn r_fn);
171
172 /** Create reader-writer lock
173 *
174 * This function creates a reader-writer lock.
175 *
176 * @param[in] lock Pointer to a reader-writer lock handle
177 * @param[in] mutex_name Name of the mutex
178 * @param[in] lock_name Name of the lock
179 *
180 * @return WM_SUCCESS on success
181 * @return -WM_FAIL on error
182 */
183 int OSA_RWLockCreate(osa_rw_lock_t *plock, const char *mutex_name, const char *lock_name);
184
185 /** Delete a reader-write lock
186 *
187 * This function deletes a reader-writer lock.
188 *
189 * @param[in] lock Pointer to the reader-writer lock handle
190 *
191 */
192 void OSA_RWLockDestroy(osa_rw_lock_t *lock);
193
194 /** Acquire writer lock
195 *
196 * This function acquires a writer lock. While readers can acquire the lock on a
197 * sharing basis, writers acquire the lock in an exclusive manner.
198 *
199 * @param[in] lock Pointer to the reader-writer lock handle
200 * @param[in] wait_time The maximum amount of time, in OS ticks, the task should
201 * block waiting for the lock to be acquired. The special values \ref
202 * osaWaitForever_c and \ref osaWaitNone_c are provided to respectively wait
203 * infinitely or return immediately.
204 *
205 * @return WM_SUCCESS on success
206 * @return -WM_FAIL on error
207 *
208 */
209 int OSA_RWLockWriteLock(osa_rw_lock_t *lock, unsigned int wait_time);
210
211 /** Release writer lock
212 *
213 * This function releases a writer lock previously acquired using
214 * OSA_RWLockWriteLock().
215 *
216 * @param[in] lock Pointer to the reader-writer lock handle
217 */
218 void OSA_RWLockWriteUnlock(osa_rw_lock_t *lock);
219
220 /** Acquire reader lock
221 *
222 * This function acquires a reader lock. While readers can acquire the lock on a
223 * sharing basis, writers acquire the lock in an exclusive manner.
224 *
225 * @param[in] lock pointer to the reader-writer lock handle
226 * @param[in] wait_time The maximum amount of time, in OS ticks, the task should
227 * block waiting for the lock to be acquired. The special values \ref
228 * osaWaitForever_c and \ref osaWaitNone_c are provided to respectively wait
229 * infinitely or return immediately.
230 *
231 * @return WM_SUCCESS on success
232 * @return -WM_FAIL on error
233 *
234 */
235 int OSA_RWLockReadLock(osa_rw_lock_t *lock, unsigned int wait_time);
236
237 /** Release reader lock
238 *
239 * This function releases a reader lock previously acquired using
240 * OSA_RWLockReadLock().
241 *
242 * @param[in] lock pointer to the reader-writer lock handle
243 *
244 * @return WM_SUCCESS if unlock operation successful.
245 * @return -WM_FAIL if unlock operation failed.
246 */
247 int OSA_RWLockReadUnlock(osa_rw_lock_t *lock);
248
249 /*** Tick function */
250 #define MAX_CUSTOM_HOOKS 4U
251
252 extern void (*g_osa_tick_hooks[MAX_CUSTOM_HOOKS])(void);
253 extern void (*g_osa_idle_hooks[MAX_CUSTOM_HOOKS])(void);
254
255 /** Setup idle function
256 *
257 * This function sets up a callback function which will be called whenever the
258 * system enters the idle thread context.
259 *
260 * @param[in] func The callback function
261 *
262 * @return WM_SUCCESS on success
263 * @return -WM_FAIL on error
264 */
265 int OSA_SetupIdleFunction(void (*func)(void));
266
267 /** Setup tick function
268 *
269 * This function sets up a callback function which will be called on every
270 * SysTick interrupt.
271 *
272 * @param[in] func The callback function
273 *
274 * @return WM_SUCCESS on success
275 * @return -WM_FAIL on error
276 */
277 int OSA_SetupTickFunction(void (*func)(void));
278
279 /** Remove idle function
280 *
281 * This function removes an idle callback function that was registered
282 * previously using OSA_SetupIdleFunction().
283 *
284 * @param[in] func The callback function
285 *
286 * @return WM_SUCCESS on success
287 * @return -WM_FAIL on error
288 */
289 int OSA_RemoveIdleFunction(void (*func)(void));
290
291 /** Remove tick function
292 *
293 * This function removes a tick callback function that was registered
294 * previously using OSA_SetupTickFunction().
295 *
296 * @param[in] func Callback function
297 * @return WM_SUCCESS on success
298 * @return -WM_FAIL on error
299 */
300 int OSA_RemoveTickFunction(void (*func)(void));
301
302 /* Init value for rand generator seed */
303 extern uint32_t wm_rand_seed;
304
305 /** This function initialize the seed for rand generator
306 * @return a uint32_t random numer
307 */
OSA_Srand(uint32_t seed)308 static inline void OSA_Srand(uint32_t seed)
309 {
310 wm_rand_seed = seed;
311 }
312
313 /** This function generate a random number
314 * @return a uint32_t random numer
315 */
OSA_Rand()316 static inline uint32_t OSA_Rand()
317 {
318 if (wm_rand_seed == -1)
319 OSA_Srand(OSA_TimeGetMsec());
320 wm_rand_seed = (uint32_t)((((uint64_t)wm_rand_seed * 279470273UL) % 4294967291UL) & 0xFFFFFFFFUL);
321 return wm_rand_seed;
322 }
323
324 /** This function generate a random number in a range
325 * @param [in] low range low
326 * @param [in] high range high
327 * @return a uint32_t random numer
328 */
OSA_RandRange(uint32_t low,uint32_t high)329 static inline uint32_t OSA_RandRange(uint32_t low, uint32_t high)
330 {
331 uint32_t tmp;
332 if (low == high)
333 return low;
334 if (low > high)
335 {
336 tmp = low;
337 low = high;
338 high = tmp;
339 }
340 return (low + OSA_Rand() % (high - low));
341 }
342
343 /** Suspend the given thread
344 *
345 * - The function OSA_ThreadSelfComplete() will \b permanently suspend the
346 * given thread. Passing NULL will suspend the current thread. This
347 * function never returns.
348 * - The thread continues to consume system resources. To delete the thread
349 * the function OSA_TaskDestroy() needs to be called separately.
350 *
351 * @param[in] taskHandle Pointer to thread handle
352 */
353 void OSA_ThreadSelfComplete(osa_task_handle_t taskHandle);
354
355 /** Return the number of messages stored in queue.
356 *
357 * @param[in] msgqHandle Pointer to handle of the queue to be queried.
358 *
359 * @returns Number of items in the queue
360 */
361 uint32_t OSA_MsgQWaiting(osa_msgq_handle_t msgqHandle);
362
363 #endif /* ! _OSA_H_ */
364
