2 * Copyright (c) 2013 - 2014, Freescale Semiconductor, Inc.
5 * Redistribution and use in source and binary forms, with or without modification,
6 * are permitted provided that the following conditions are met:
8 * o Redistributions of source code must retain the above copyright notice, this list
9 * of conditions and the following disclaimer.
11 * o Redistributions in binary form must reproduce the above copyright notice, this
12 * list of conditions and the following disclaimer in the documentation and/or
13 * other materials provided with the distribution.
15 * o Neither the name of Freescale Semiconductor, Inc. nor the names of its
16 * contributors may be used to endorse or promote products derived from this
17 * software without specific prior written permission.
19 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
20 * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
21 * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
22 * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR
23 * ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
24 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
25 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
26 * ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
27 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
28 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
30 #if !defined(__FSL_OS_ABSTRACTION_H__)
31 #define __FSL_OS_ABSTRACTION_H__
38 #define inline __inline
42 * @addtogroup os_abstraction
46 /*! @brief Status values to be returned by functions. */
49 kSuccess
= 0, /*!< Functions work correctly. */
50 kError
, /*!< Functions work failed. */
51 kTimeout
, /*!< Timeout occurs while waiting for an object. */
52 kIdle
/*!< Can not get the object in non-blocking mode.*/
55 /*! @brief The event flags are set or not.*/
58 kFlagNotSet
= 0, /*!< The flags checked are set. */
59 kFlagSet
/*!< The flags checked are not set. */
62 /*! @brief The event flags are cleared automatically or manually.*/
65 kEventAutoClr
= 0, /*!< The flags of the event will be cleared automatically. */
66 kEventManualClr
/*!< The flags of the event will be cleared manually. */
69 // Temporary "fix", until the proper macros are integrated in the on-line build system
72 /* Include required header file based on RTOS selection */
73 #if defined (FSL_RTOS_MQX)
74 /*! @brief Macro to set message queue copy messages to internal memory or not. */
75 #define __FSL_RTOS_MSGQ_COPY_MSG__ 1
76 #include "fsl_os_abstraction_mqx.h"
78 #elif defined (FSL_RTOS_FREE_RTOS)
79 #define __FSL_RTOS_MSGQ_COPY_MSG__ 1
80 #include "fsl_os_abstraction_free_rtos.h"
82 #elif defined (FSL_RTOS_UCOSII)
83 #define __FSL_RTOS_MSGQ_COPY_MSG__ 1
84 #include "fsl_os_abstraction_ucosii.h"
86 #elif defined (FSL_RTOS_UCOSIII)
87 #define __FSL_RTOS_MSGQ_COPY_MSG__ 1
88 #include "fsl_os_abstraction_ucosiii.h"
90 #elif defined (FSL_RTOS_CMSIS)
91 #define __FSL_RTOS_MSGQ_COPY_MSG__ 0
92 #include "fsl_os_abstraction_cmsis.h"
94 #elif defined (FSL_RTOS_MBED)
95 #define __FSL_RTOS_MSGQ_COPY_MSG__ 1
96 #include "fsl_os_abstraction_mbed.h"
99 #define __FSL_RTOS_MSGQ_COPY_MSG__ 1
100 #include "fsl_os_abstraction_bm.h"
103 /*******************************************************************************
105 ******************************************************************************/
107 #if defined(__cplusplus)
112 * @name Synchronization
117 * @brief Initialize a synchronization object to a given state.
119 * @param obj The sync object to initialize.
120 * @param initValue The initial value the object will be set to.
122 * @retval kSuccess The object was successfully created.
123 * @retval kError Invalid parameter or no more objects can be created.
125 fsl_rtos_status
sync_create(sync_object_t
*obj
, uint8_t initValue
);
128 * @brief Wait for the synchronization object.
130 * This function checks the sync object's counting value, if it is
131 * positive, decreases it and returns kSuccess, otherwise, timeout will be
134 * @param obj Pointer to the synchronization object.
135 * @param timeout The maximum number of milliseconds to wait for the object to be signalled.
136 * Pass the #kSyncWaitForever constant to wait indefinitely for someone to signal the object.
137 * A value of 0 should not be passed to this function. Instead, use sync_poll for
138 * a non blocking check.
140 * @retval kSuccess The object was signalled.
141 * @retval kTimeout A timeout occurred.
142 * @retval kError An incorrect parameter was passed.
143 * @retval kIdle The object has not been signalled.
145 * @note There could be only one process waiting for the object at the same time.
147 fsl_rtos_status
sync_wait(sync_object_t
*obj
, uint32_t timeout
);
150 * @brief Checks a synchronization object's status.
152 * This function is used to poll a sync object's status.
153 * If the sync object's counting value is positive, decrease it and return
154 * kSuccess. If the object's counting value is 0, the function will
155 * return kIdle immediately
157 * @param obj The synchronization object.
159 * @retval kSuccess The object was signalled.
160 * @retval kIdle The object was not signalled.
161 * @retval kError An incorrect parameter was passed.
163 fsl_rtos_status
sync_poll(sync_object_t
*obj
);
166 * @brief Signal for someone waiting on the synchronization object to wake up.
168 * This function should not be called from an ISR.
170 * @param obj The synchronization object to signal.
172 * @retval kSuccess The object was successfully signaled.
173 * @retval kError The object can not be signaled or invalid parameter.
175 fsl_rtos_status
sync_signal(sync_object_t
*obj
);
178 * @brief Signal for someone waiting on the synchronization object to wake up.
180 * This function should only be called from an ISR.
182 * @param obj The synchronization object to signal.
184 * @retval kSuccess The object was successfully signaled.
185 * @retval kError The object can not be signaled or invalid parameter.
187 fsl_rtos_status
sync_signal_from_isr(sync_object_t
*obj
);
190 * @brief Destroy a previously created synchronization object.
192 * @param obj The synchronization object to destroy.
194 * @retval kSuccess The object was successfully destroyed.
195 * @retval kError Object destruction failed.
197 fsl_rtos_status
sync_destroy(sync_object_t
*obj
);
202 * @name Resource locking
207 * @brief Initialize a locking object.
209 * @param obj The lock object to initialize.
211 * @retval kSuccess The lock is created successfully.
212 * @retval kError Tke lock creation failed.
214 fsl_rtos_status
lock_create(lock_object_t
*obj
);
217 * @brief Wait for the object to be unlocked and lock it.
219 * This function will wait for some time or wait forever if could not get the lock.
221 * @param obj The locking object.
222 * @param timeout The maximum number of milliseconds to wait for the mutex.
223 * Pass the #kSyncWaitForever constant to wait indefinitely for someone to unlock the object.
224 * A value of 0 should not be passed to this function. Instead, use lock_poll for a non
227 * @retval kSuccess The lock was obtained.
228 * @retval kTimeout A timeout occurred.
229 * @retval kError An incorrect parameter was passed.
231 fsl_rtos_status
lock_wait(lock_object_t
*obj
, uint32_t timeout
);
234 * @brief Checks if a locking object can be locked and locks it if possible.
236 * This function returns instantly if could not get the lock.
238 * @param obj The locking object.
240 * @retval kSuccess The lock was obtained.
241 * @retval kIdle The lock could not be obtained.
242 * @retval kError An incorrect parameter was passed.
244 * @note There could be only one process waiting for the object at the same time.
245 * For RTOSes, wait for a lock recursively by one task is not supported.
248 fsl_rtos_status
lock_poll(lock_object_t
*obj
);
251 * @brief Unlock a previously locked object.
253 * @param obj The locking object to unlock.
255 * @retval kSuccess The object was successfully unlocked.
256 * @retval kError The object can not be unlocked or invalid parameter.
258 fsl_rtos_status
lock_release(lock_object_t
*obj
);
261 * @brief Destroy a previously created locking object.
263 * @param obj The locking object to destroy.
265 * @retval kSuccess The object was successfully destroyed.
266 * @retval kError Object destruction failed.
268 fsl_rtos_status
lock_destroy(lock_object_t
*obj
);
273 * @name Event signaling
278 * @brief Initializes the event object.
280 * When the object is created, the flags is 0.
282 * @param obj Pointer to the event object to initialize.
283 * @param clearType The event is auto-clear or manual-clear.
285 * @retval kSuccess The object was successfully created.
286 * @retval kError Incorrect parameter or no more objects can be created.
288 fsl_rtos_status
event_create(event_object_t
*obj
, event_clear_type clearType
);
291 * @brief Wait for any event flags to be set.
293 * This function will wait for some time or wait forever if no flags are set. Any flags set
294 * will wake up the function.
296 * @param obj The event object.
297 * @param timeout The maximum number of milliseconds to wait for the event.
298 * Pass the #kSyncWaitForever constant to wait indefinitely. A value of 0 should not be passed
300 * @param setFlags Pointer to receive the flags that were set.
302 * @retval kSuccess An event was set.
303 * @retval kTimeout A timeout occurred.
304 * @retval kError An incorrect parameter was passed.
306 fsl_rtos_status
event_wait(event_object_t
*obj
, uint32_t timeout
, event_group_t
*setFlags
);
309 * @brief Set one or more event flags of an event object.
311 * This function should not be called from an ISR.
313 * @param obj The event object.
314 * @param flags Event flags to be set.
316 * @retval kSuccess The flags were successfully set.
317 * @retval kError An incorrect parameter was passed.
319 * @note There could be only one process waiting for the event.
322 fsl_rtos_status
event_set(event_object_t
*obj
, event_group_t flags
);
325 * @brief Set one or more event flags of an event object.
327 * This function should only be called from an ISR.
329 * @param obj The event object.
330 * @param flags Event flags to be set.
332 * @retval kSuccess The flags were successfully set.
333 * @retval kError An incorrect parameter was passed.
335 fsl_rtos_status
event_set_from_isr(event_object_t
*obj
, event_group_t flags
);
338 * @brief Clear one or more events of an event object.
340 * This function should not be called from an ISR.
342 * @param obj The event object.
343 * @param flags Event flags to be clear.
345 * @retval kSuccess The flags were successfully cleared.
346 * @retval kError An incorrect parameter was passed.
348 fsl_rtos_status
event_clear(event_object_t
*obj
, event_group_t flags
);
351 * @brief Check the flags are set or not.
353 * @param obj The event object.
354 * @param flag The flag to check.
356 * @retval kFlagsSet The flags checked are set.
357 * @retval kFlagsNotSet The flags checked are not set or got an error.
359 event_status
event_check_flags(event_object_t
*obj
, event_group_t flag
);
362 * @brief Destroy a previously created event object.
364 * @param obj The event object to destroy.
366 * @retval kSuccess The object was successfully destroyed.
367 * @retval kError Event destruction failed.
369 fsl_rtos_status
event_destroy(event_object_t
*obj
);
373 * @name Thread management
378 * @brief Create a task.
380 * This function is wrapped by the macro task_create. Generally, this function is for
381 * internal use only, applications must use FSL_RTOS_TASK_DEFINE to define resources for
382 * task statically then use task_create to create task. If applications have prepare
383 * the resouces for task dynamically, they can use this function to create the task.
385 * @param task The task function.
386 * @param name The name of this task.
387 * @param stackSize The stack size in byte.
388 * @param stackMem Pointer to the stack. For bare metal, MQX and FreeRTOS, this could be NULL.
389 * @param priority Initial priority of the task.
390 * @param param Pointer to be passed to the task when it is created.
391 * @param usesFloat This task will use float register or not.
392 * @param handler Pointer to the task handler.
394 * @retval kSuccess The task was successfully created.
395 * @retval kError The task could not be created.
397 * @note Different tasks can not use the same task function.
399 fsl_rtos_status
__task_create(task_t task
, uint8_t *name
, uint16_t stackSize
,
400 task_stack_t
*stackMem
, uint16_t priority
,
401 void *param
, bool usesFloat
, task_handler_t
*handler
);
404 * @brief Destroy a previously created task.
405 * @note Depending on the RTOS, task resources may or may not be automatically freed,
406 * and this function may not return if the current task is destroyed.
408 * @param handler The handler of the task to destroy. Returned by the task_create function.
410 * @retval kSuccess The task was successfully destroyed.
411 * @retval kError Task destruction failed or invalid parameter.
413 fsl_rtos_status
task_destroy(task_handler_t handler
);
417 * @name Message queues
422 * @brief Initialize the message queue.
424 * This function will initialize the message queue that declared previously.
425 * Here is an example demonstrating how to use:
427 msg_queue_handler_t handler;
428 MSG_QUEUE_DECLARE(my_message, msg_num, msg_size);
429 handler = msg_queue_create(&my_message, msg_num, msg_size);
432 * @param queue The queue declared through the MSG_QUEUE_DECLARE macro.
433 * @param number The number of elements in the queue.
434 * @param size Size of every elements in words.
436 * @retval Handler to access the queue for put and get operations. If message queue
437 * created failed, return 0.
439 msg_queue_handler_t
msg_queue_create(msg_queue_t
*queue
, uint16_t number
, uint16_t size
);
442 * @brief Introduce an element at the tail of the queue.
444 * @param handler Queue handler returned by the msg_queue_create function.
445 * @param item Pointer to the element to be introduced in the queue.
447 * @retval kSuccess Element successfully introduced in the queue.
448 * @retval kError The queue was full or an invalid parameter was passed.
450 fsl_rtos_status
msg_queue_put(msg_queue_handler_t handler
, msg_queue_item_t item
);
453 * @brief Read and remove an element at the head of the queue.
455 * @param handler Queue handler returned by the msg_queue_create function.
456 * @param item Pointer to store a pointer to the element of the queue.
457 * @param timeout In case the queue is empty, the number of milliseconds to
458 * wait for an element to be introduced into the queue. Use 0 to return
459 * immediately or #kSyncWaitForever to wait indefinitely.
461 * @retval kSuccess Element successfully obtained from the queue.
462 * @retval kTimeout If a timeout was specified, the queue remained empty after timeout.
463 * @retval kError The queue was empty or the handler was invalid.
464 * @retval kIdle The queue was empty and the timeout has not expired.
466 * @note There should be only one process waiting on the queue.
468 fsl_rtos_status
msg_queue_get(msg_queue_handler_t handler
,
469 msg_queue_item_t
*item
,
473 * @brief Discards all elements in the queue and leaves the queue empty.
475 * @param handler Queue handler returned by the msg_queue_create function.
477 * @retval kSuccess Queue successfully emptied.
478 * @retval kError Emptying queue failed.
480 fsl_rtos_status
msg_queue_flush(msg_queue_handler_t handler
);
483 * @brief Destroy a previously created queue.
485 * @param handler Queue handler returned by the msg_queue_create function.
487 * @retval kSuccess The queue was successfully destroyed.
488 * @retval kError Message queue destruction failed.
490 fsl_rtos_status
msg_queue_destroy(msg_queue_handler_t handler
);
494 #ifndef FSL_RTOS_MBED
496 * @name Memory Management
501 * @brief Reserves the requested amount of memory in bytes.
503 * @param size Amount of bytes to reserve.
505 * @retval Pointer to the reserved memory. NULL if memory could not be allocated.
507 void * mem_allocate(size_t size
);
510 * @brief Reserves the requested amount of memory in bytes and initializes it to 0.
512 * @param size Amount of bytes to reserve.
514 * @retval Pointer to the reserved memory. NULL if memory could not be allocated.
516 void * mem_allocate_zero(size_t size
);
519 * @brief Releases the memory previously reserved.
521 * @param ptr Pointer to the start of the memory block previously reserved.
523 * @retval kSuccess Memory correctly released.
525 fsl_rtos_status
mem_free(void *ptr
);
531 * @name Time management
536 * @brief Delays execution for a number of milliseconds.
538 * @param delay The time in milliseconds to wait.
540 void time_delay(uint32_t delay
);
545 * @name Interrupt management
550 * @brief Install interrupt handler.
552 * @param irqNumber IRQ number of the interrupt.
553 * @param handler The interrupt handler to install.
555 * @retval kSuccess Handler is installed successfully.
556 * @retval kSuccess Handler could not be installed.
558 fsl_rtos_status
interrupt_handler_register(int32_t irqNumber
, void (*handler
)(void));
562 #if defined(__cplusplus)
568 #endif /* __FSL_OS_ABSTRACTION_H__ */
569 /*******************************************************************************
571 ******************************************************************************/