2 * OS Abstraction Layer Extension - the APIs defined by the "extension" API
3 * are only supported by a subset of all operating systems.
5 * Copyright (C) 1999-2016, Broadcom Corporation
7 * Unless you and Broadcom execute a separate written software license
8 * agreement governing use of this software, this software is licensed to you
9 * under the terms of the GNU General Public License version 2 (the "GPL"),
10 * available at http://www.broadcom.com/licenses/GPLv2.php, with the
11 * following added to such license:
13 * As a special exception, the copyright holders of this software give you
14 * permission to link this software with independent modules, and to copy and
15 * distribute the resulting executable under terms of your choice, provided that
16 * you also meet, for each linked independent module, the terms and conditions of
17 * the license of that module. An independent module is a module which is not
18 * derived from this software. The special exception does not apply to any
19 * modifications of the software.
21 * Notwithstanding the above, under no circumstances may you combine this
22 * software in any way with any other Broadcom software provided under a license
23 * other than the GPL, without Broadcom's express prior written consent.
26 * <<Broadcom-WL-IPTag/Open:>>
28 * $Id: osl_ext.h 514727 2014-11-12 03:02:48Z $
35 /* ---- Include Files ---------------------------------------------------- */
37 #if defined(TARGETOS_symbian)
39 #include <symbian_osl_ext.h>
40 #elif defined(THREADX)
41 #include <threadx_osl_ext.h>
43 #define OSL_EXT_DISABLED
46 /* Include base operating system abstraction. */
53 /* ---- Constants and Types ---------------------------------------------- */
55 /* -----------------------------------------------------------------------
58 typedef enum osl_ext_status_t
65 #define OSL_EXT_STATUS_DECL(status) osl_ext_status_t status;
67 #define OSL_EXT_TIME_FOREVER ((osl_ext_time_ms_t)(-1))
68 typedef unsigned int osl_ext_time_ms_t;
70 typedef unsigned int osl_ext_event_bits_t;
72 typedef unsigned int osl_ext_interrupt_state_t;
74 /* -----------------------------------------------------------------------
80 OSL_EXT_TIMER_MODE_ONCE,
83 OSL_EXT_TIMER_MODE_REPEAT
85 } osl_ext_timer_mode_t;
87 /* User registered callback and parameter to invoke when timer expires. */
88 typedef void* osl_ext_timer_arg_t;
89 typedef void (*osl_ext_timer_callback)(osl_ext_timer_arg_t arg);
92 /* -----------------------------------------------------------------------
96 /* Task entry argument. */
97 typedef void* osl_ext_task_arg_t;
99 /* Task entry function. */
100 typedef void (*osl_ext_task_entry)(osl_ext_task_arg_t arg);
102 /* Abstract task priority levels. */
105 OSL_EXT_TASK_IDLE_PRIORITY,
106 OSL_EXT_TASK_LOW_PRIORITY,
107 OSL_EXT_TASK_LOW_NORMAL_PRIORITY,
108 OSL_EXT_TASK_NORMAL_PRIORITY,
109 OSL_EXT_TASK_HIGH_NORMAL_PRIORITY,
110 OSL_EXT_TASK_HIGHEST_PRIORITY,
111 OSL_EXT_TASK_TIME_CRITICAL_PRIORITY,
113 /* This must be last. */
114 OSL_EXT_TASK_NUM_PRIORITES
115 } osl_ext_task_priority_t;
118 #ifndef OSL_EXT_DISABLED
120 /* ---- Variable Externs ------------------------------------------------- */
121 /* ---- Function Prototypes ---------------------------------------------- */
124 /* --------------------------------------------------------------------------
128 /****************************************************************************
129 * Function: osl_ext_sem_create
131 * Purpose: Creates a counting semaphore object, which can subsequently be
132 * used for thread notification.
134 * Parameters: name (in) Name to assign to the semaphore (must be unique).
135 * init_cnt (in) Initial count that the semaphore should have.
136 * sem (out) Newly created semaphore.
138 * Returns: OSL_EXT_SUCCESS if the semaphore was created successfully, or an
139 * error code if the semaphore could not be created.
140 *****************************************************************************
142 osl_ext_status_t osl_ext_sem_create(char *name, int init_cnt, osl_ext_sem_t *sem);
144 /****************************************************************************
145 * Function: osl_ext_sem_delete
147 * Purpose: Destroys a previously created semaphore object.
149 * Parameters: sem (mod) Semaphore object to destroy.
151 * Returns: OSL_EXT_SUCCESS if the semaphore was deleted successfully, or an
152 * error code if the semaphore could not be created.
153 *****************************************************************************
155 osl_ext_status_t osl_ext_sem_delete(osl_ext_sem_t *sem);
157 /****************************************************************************
158 * Function: osl_ext_sem_give
160 * Purpose: Increments the count associated with the semaphore. This will
161 * cause one thread blocked on a take to wake up.
163 * Parameters: sem (mod) Semaphore object to give.
165 * Returns: OSL_EXT_SUCCESS if the semaphore was given successfully, or an
166 * error code if the semaphore could not be created.
167 *****************************************************************************
169 osl_ext_status_t osl_ext_sem_give(osl_ext_sem_t *sem);
171 /****************************************************************************
172 * Function: osl_ext_sem_take
174 * Purpose: Decrements the count associated with the semaphore. If the count
175 * is less than zero, then the calling task will become blocked until
176 * another thread does a give on the semaphore. This function will only
177 * block the calling thread for timeout_msec milliseconds, before
178 * returning with OSL_EXT_TIMEOUT.
180 * Parameters: sem (mod) Semaphore object to take.
181 * timeout_msec (in) Number of milliseconds to wait for the
182 * semaphore to enter a state where it can be
185 * Returns: OSL_EXT_SUCCESS if the semaphore was taken successfully, or an
186 * error code if the semaphore could not be created.
187 *****************************************************************************
189 osl_ext_status_t osl_ext_sem_take(osl_ext_sem_t *sem, osl_ext_time_ms_t timeout_msec);
192 /* --------------------------------------------------------------------------
196 /****************************************************************************
197 * Function: osl_ext_mutex_create
199 * Purpose: Creates a mutex object, which can subsequently be used to control
200 * mutually exclusion of resources.
202 * Parameters: name (in) Name to assign to the mutex (must be unique).
203 * mutex (out) Mutex object to initialize.
205 * Returns: OSL_EXT_SUCCESS if the mutex was created successfully, or an
206 * error code if the mutex could not be created.
207 *****************************************************************************
209 osl_ext_status_t osl_ext_mutex_create(char *name, osl_ext_mutex_t *mutex);
211 /****************************************************************************
212 * Function: osl_ext_mutex_delete
214 * Purpose: Destroys a previously created mutex object.
216 * Parameters: mutex (mod) Mutex object to destroy.
218 * Returns: OSL_EXT_SUCCESS if the mutex was deleted successfully, or an
219 * error code if the mutex could not be created.
220 *****************************************************************************
222 osl_ext_status_t osl_ext_mutex_delete(osl_ext_mutex_t *mutex);
224 /****************************************************************************
225 * Function: osl_ext_mutex_acquire
227 * Purpose: Acquires the indicated mutual exclusion object. If the object is
228 * currently acquired by another task, then this function will wait
229 * for timeout_msec milli-seconds before returning with OSL_EXT_TIMEOUT.
231 * Parameters: mutex (mod) Mutex object to acquire.
232 * timeout_msec (in) Number of milliseconds to wait for the mutex.
234 * Returns: OSL_EXT_SUCCESS if the mutex was acquired successfully, or an
235 * error code if the mutex could not be created.
236 *****************************************************************************
238 osl_ext_status_t osl_ext_mutex_acquire(osl_ext_mutex_t *mutex, osl_ext_time_ms_t timeout_msec);
240 /****************************************************************************
241 * Function: osl_ext_mutex_release
243 * Purpose: Releases the indicated mutual exclusion object. This makes it
244 * available for another task to acquire.
246 * Parameters: mutex (mod) Mutex object to release.
248 * Returns: OSL_EXT_SUCCESS if the mutex was released successfully, or an
249 * error code if the mutex could not be created.
250 *****************************************************************************
252 osl_ext_status_t osl_ext_mutex_release(osl_ext_mutex_t *mutex);
255 /* --------------------------------------------------------------------------
259 /****************************************************************************
260 * Function: osl_ext_timer_create
262 * Purpose: Creates a timer object.
264 * Parameters: name (in) Name of timer.
265 * timeout_msec (in) Invoke callback after this number of milliseconds.
266 * mode (in) One-shot or periodic timer.
267 * func (in) Callback function to invoke on timer expiry.
268 * arg (in) Argument to callback function.
269 * timer (out) Timer object to create.
271 * Note: The function callback occurs in interrupt context. The application is
272 * required to provide context switch for the callback if required.
274 * Returns: OSL_EXT_SUCCESS if the timer was created successfully, or an
275 * error code if the timer could not be created.
276 *****************************************************************************
279 osl_ext_timer_create(char *name, osl_ext_time_ms_t timeout_msec, osl_ext_timer_mode_t mode,
280 osl_ext_timer_callback func, osl_ext_timer_arg_t arg, osl_ext_timer_t *timer);
282 /****************************************************************************
283 * Function: osl_ext_timer_delete
285 * Purpose: Destroys a previously created timer object.
287 * Parameters: timer (mod) Timer object to destroy.
289 * Returns: OSL_EXT_SUCCESS if the timer was created successfully, or an
290 * error code if the timer could not be created.
291 *****************************************************************************
293 osl_ext_status_t osl_ext_timer_delete(osl_ext_timer_t *timer);
295 /****************************************************************************
296 * Function: osl_ext_timer_start
298 * Purpose: Start a previously created timer object.
300 * Parameters: timer (in) Timer object.
301 * timeout_msec (in) Invoke callback after this number of milliseconds.
302 * mode (in) One-shot or periodic timer.
304 * Returns: OSL_EXT_SUCCESS if the timer was created successfully, or an
305 * error code if the timer could not be created.
306 *****************************************************************************
309 osl_ext_timer_start(osl_ext_timer_t *timer,
310 osl_ext_time_ms_t timeout_msec, osl_ext_timer_mode_t mode);
312 /****************************************************************************
313 * Function: osl_ext_timer_stop
315 * Purpose: Stop a previously created timer object.
317 * Parameters: timer (in) Timer object.
319 * Returns: OSL_EXT_SUCCESS if the timer was created successfully, or an
320 * error code if the timer could not be created.
321 *****************************************************************************
324 osl_ext_timer_stop(osl_ext_timer_t *timer);
326 /****************************************************************************
327 * Function: osl_ext_time_get
329 * Purpose: Returns incrementing time counter.
333 * Returns: Returns incrementing time counter in msec.
334 *****************************************************************************
336 osl_ext_time_ms_t osl_ext_time_get(void);
338 /* --------------------------------------------------------------------------
342 /****************************************************************************
343 * Function: osl_ext_task_create
345 * Purpose: Create a task.
347 * Parameters: name (in) Pointer to task string descriptor.
348 * stack (in) Pointer to stack. NULL to allocate.
349 * stack_size (in) Stack size - in bytes.
350 * priority (in) Abstract task priority.
351 * func (in) A pointer to the task entry point function.
352 * arg (in) Value passed into task entry point function.
353 * task (out) Task to create.
355 * Returns: OSL_EXT_SUCCESS if the task was created successfully, or an
356 * error code if the task could not be created.
357 *****************************************************************************
360 #define osl_ext_task_create(name, stack, stack_size, priority, func, arg, task) \
361 osl_ext_task_create_ex((name), (stack), (stack_size), (priority), 0, (func), \
364 osl_ext_status_t osl_ext_task_create_ex(char* name,
365 void *stack, unsigned int stack_size, osl_ext_task_priority_t priority,
366 osl_ext_time_ms_t timslice_msec, osl_ext_task_entry func, osl_ext_task_arg_t arg,
367 osl_ext_task_t *task);
369 /****************************************************************************
370 * Function: osl_ext_task_delete
372 * Purpose: Destroy a task.
374 * Parameters: task (mod) Task to destroy.
376 * Returns: OSL_EXT_SUCCESS if the task was created successfully, or an
377 * error code if the task could not be created.
378 *****************************************************************************
380 osl_ext_status_t osl_ext_task_delete(osl_ext_task_t *task);
383 /****************************************************************************
384 * Function: osl_ext_task_is_running
386 * Purpose: Returns current running task.
390 * Returns: osl_ext_task_t of current running task.
391 *****************************************************************************
393 osl_ext_task_t *osl_ext_task_current(void);
396 /****************************************************************************
397 * Function: osl_ext_task_yield
399 * Purpose: Yield the CPU to other tasks of the same priority that are
404 * Returns: OSL_EXT_SUCCESS if successful, else error code.
405 *****************************************************************************
407 osl_ext_status_t osl_ext_task_yield(void);
410 /****************************************************************************
411 * Function: osl_ext_task_enable_stack_check
413 * Purpose: Enable task stack checking.
417 * Returns: OSL_EXT_SUCCESS if successful, else error code.
418 *****************************************************************************
420 osl_ext_status_t osl_ext_task_enable_stack_check(void);
423 /* --------------------------------------------------------------------------
427 /****************************************************************************
428 * Function: osl_ext_queue_create
430 * Purpose: Create a queue.
432 * Parameters: name (in) Name to assign to the queue (must be unique).
433 * buffer (in) Queue buffer. NULL to allocate.
434 * size (in) Size of the queue.
435 * queue (out) Newly created queue.
437 * Returns: OSL_EXT_SUCCESS if the queue was created successfully, or an
438 * error code if the queue could not be created.
439 *****************************************************************************
441 osl_ext_status_t osl_ext_queue_create(char *name,
442 void *queue_buffer, unsigned int queue_size,
443 osl_ext_queue_t *queue);
445 /****************************************************************************
446 * Function: osl_ext_queue_delete
448 * Purpose: Destroys a previously created queue object.
450 * Parameters: queue (mod) Queue object to destroy.
452 * Returns: OSL_EXT_SUCCESS if the queue was deleted successfully, or an
453 * error code if the queue could not be deleteed.
454 *****************************************************************************
456 osl_ext_status_t osl_ext_queue_delete(osl_ext_queue_t *queue);
458 /****************************************************************************
459 * Function: osl_ext_queue_send
461 * Purpose: Send/add data to the queue. This function will not block the
462 * calling thread if the queue is full.
464 * Parameters: queue (mod) Queue object.
465 * data (in) Data pointer to be queued.
467 * Returns: OSL_EXT_SUCCESS if the data was queued successfully, or an
468 * error code if the data could not be queued.
469 *****************************************************************************
471 osl_ext_status_t osl_ext_queue_send(osl_ext_queue_t *queue, void *data);
473 /****************************************************************************
474 * Function: osl_ext_queue_send_synchronous
476 * Purpose: Send/add data to the queue. This function will block the
477 * calling thread until the data is dequeued.
479 * Parameters: queue (mod) Queue object.
480 * data (in) Data pointer to be queued.
482 * Returns: OSL_EXT_SUCCESS if the data was queued successfully, or an
483 * error code if the data could not be queued.
484 *****************************************************************************
486 osl_ext_status_t osl_ext_queue_send_synchronous(osl_ext_queue_t *queue, void *data);
488 /****************************************************************************
489 * Function: osl_ext_queue_receive
491 * Purpose: Receive/remove data from the queue. This function will only
492 * block the calling thread for timeout_msec milliseconds, before
493 * returning with OSL_EXT_TIMEOUT.
495 * Parameters: queue (mod) Queue object.
496 * timeout_msec (in) Number of milliseconds to wait for the
497 * data from the queue.
498 * data (out) Data pointer received/removed from the queue.
500 * Returns: OSL_EXT_SUCCESS if the data was dequeued successfully, or an
501 * error code if the data could not be dequeued.
502 *****************************************************************************
504 osl_ext_status_t osl_ext_queue_receive(osl_ext_queue_t *queue,
505 osl_ext_time_ms_t timeout_msec, void **data);
507 /****************************************************************************
508 * Function: osl_ext_queue_count
510 * Purpose: Returns the number of items in the queue.
512 * Parameters: queue (mod) Queue object.
513 * count (out) Data pointer received/removed from the queue.
515 * Returns: OSL_EXT_SUCCESS if the count was returned successfully, or an
516 * error code if the count is invalid.
517 *****************************************************************************
519 osl_ext_status_t osl_ext_queue_count(osl_ext_queue_t *queue, int *count);
522 /* --------------------------------------------------------------------------
526 /****************************************************************************
527 * Function: osl_ext_event_create
529 * Purpose: Creates a event object, which can subsequently be used to
530 * notify and trigger tasks.
532 * Parameters: name (in) Name to assign to the event (must be unique).
533 * event (out) Event object to initialize.
535 * Returns: OSL_EXT_SUCCESS if the event was created successfully, or an
536 * error code if the event could not be created.
537 *****************************************************************************
539 osl_ext_status_t osl_ext_event_create(char *name, osl_ext_event_t *event);
541 /****************************************************************************
542 * Function: osl_ext_event_delete
544 * Purpose: Destroys a previously created event object.
546 * Parameters: event (mod) Event object to destroy.
548 * Returns: OSL_EXT_SUCCESS if the event was created successfully, or an
549 * error code if the event could not be created.
550 *****************************************************************************
552 osl_ext_status_t osl_ext_event_delete(osl_ext_event_t *event);
554 /****************************************************************************
555 * Function: osl_ext_event_get
557 * Purpose: Get event from specified event object.
559 * Parameters: event (mod) Event object to get.
560 * requested (in) Requested event to get.
561 * timeout_msec (in) Number of milliseconds to wait for the event.
562 * event_bits (out) Event bits retrieved.
564 * Returns: OSL_EXT_SUCCESS if the event was created successfully, or an
565 * error code if the event could not be created.
566 *****************************************************************************
568 osl_ext_status_t osl_ext_event_get(osl_ext_event_t *event,
569 osl_ext_event_bits_t requested, osl_ext_time_ms_t timeout_msec,
570 osl_ext_event_bits_t *event_bits);
572 /****************************************************************************
573 * Function: osl_ext_event_set
575 * Purpose: Set event of specified event object.
577 * Parameters: event (mod) Event object to set.
578 * event_bits (in) Event bits to set.
580 * Returns: OSL_EXT_SUCCESS if the event was created successfully, or an
581 * error code if the event could not be created.
582 *****************************************************************************
584 osl_ext_status_t osl_ext_event_set(osl_ext_event_t *event,
585 osl_ext_event_bits_t event_bits);
588 /* --------------------------------------------------------------------------
592 /****************************************************************************
593 * Function: osl_ext_interrupt_disable
595 * Purpose: Disable CPU interrupt.
599 * Returns: The interrupt state before disable for restoring interrupt.
600 *****************************************************************************
602 osl_ext_interrupt_state_t osl_ext_interrupt_disable(void);
605 /****************************************************************************
606 * Function: osl_ext_interrupt_restore
608 * Purpose: Restore CPU interrupt state.
610 * Parameters: state (in) Interrupt state to restore returned from
611 * osl_ext_interrupt_disable().
614 *****************************************************************************
616 void osl_ext_interrupt_restore(osl_ext_interrupt_state_t state);
620 /* ---- Constants and Types ---------------------------------------------- */
623 #define osl_ext_sem_t
624 #define OSL_EXT_SEM_DECL(sem)
627 #define osl_ext_mutex_t
628 #define OSL_EXT_MUTEX_DECL(mutex)
631 #define osl_ext_timer_t
632 #define OSL_EXT_TIMER_DECL(timer)
635 #define osl_ext_task_t void
636 #define OSL_EXT_TASK_DECL(task)
639 #define osl_ext_queue_t
640 #define OSL_EXT_QUEUE_DECL(queue)
643 #define osl_ext_event_t
644 #define OSL_EXT_EVENT_DECL(event)
646 /* ---- Variable Externs ------------------------------------------------- */
647 /* ---- Function Prototypes ---------------------------------------------- */
649 #define osl_ext_sem_create(name, init_cnt, sem) (OSL_EXT_SUCCESS)
650 #define osl_ext_sem_delete(sem) (OSL_EXT_SUCCESS)
651 #define osl_ext_sem_give(sem) (OSL_EXT_SUCCESS)
652 #define osl_ext_sem_take(sem, timeout_msec) (OSL_EXT_SUCCESS)
654 #define osl_ext_mutex_create(name, mutex) (OSL_EXT_SUCCESS)
655 #define osl_ext_mutex_delete(mutex) (OSL_EXT_SUCCESS)
656 #define osl_ext_mutex_acquire(mutex, timeout_msec) (OSL_EXT_SUCCESS)
657 #define osl_ext_mutex_release(mutex) (OSL_EXT_SUCCESS)
659 #define osl_ext_timer_create(name, timeout_msec, mode, func, arg, timer) \
661 #define osl_ext_timer_delete(timer) (OSL_EXT_SUCCESS)
662 #define osl_ext_timer_start(timer, timeout_msec, mode) (OSL_EXT_SUCCESS)
663 #define osl_ext_timer_stop(timer) (OSL_EXT_SUCCESS)
664 #define osl_ext_time_get() (0)
666 #define osl_ext_task_create(name, stack, stack_size, priority, func, arg, task) \
668 #define osl_ext_task_delete(task) (OSL_EXT_SUCCESS)
669 #define osl_ext_task_current() (NULL)
670 #define osl_ext_task_yield() (OSL_EXT_SUCCESS)
671 #define osl_ext_task_enable_stack_check() (OSL_EXT_SUCCESS)
673 #define osl_ext_queue_create(name, queue_buffer, queue_size, queue) \
675 #define osl_ext_queue_delete(queue) (OSL_EXT_SUCCESS)
676 #define osl_ext_queue_send(queue, data) (OSL_EXT_SUCCESS)
677 #define osl_ext_queue_send_synchronous(queue, data) (OSL_EXT_SUCCESS)
678 #define osl_ext_queue_receive(queue, timeout_msec, data) \
680 #define osl_ext_queue_count(queue, count) (OSL_EXT_SUCCESS)
682 #define osl_ext_event_create(name, event) (OSL_EXT_SUCCESS)
683 #define osl_ext_event_delete(event) (OSL_EXT_SUCCESS)
684 #define osl_ext_event_get(event, requested, timeout_msec, event_bits) \
686 #define osl_ext_event_set(event, event_bits) (OSL_EXT_SUCCESS)
688 #define osl_ext_interrupt_disable(void)
689 #define osl_ext_interrupt_restore(state)
691 #endif /* OSL_EXT_DISABLED */
697 #endif /* _osl_ext_h_ */