Diff: targets/hal/TARGET_Freescale/TARGET_KPSDK_MCUS/TARGET_KPSDK_CODE/utilities/fsl_os_abstraction.h

Revision:

168:cf9372ac0a74

Child:

169:60881100c991

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/targets/hal/TARGET_Freescale/TARGET_KPSDK_MCUS/TARGET_KPSDK_CODE/utilities/fsl_os_abstraction.h	Thu Apr 24 10:45:06 2014 +0100
@@ -0,0 +1,569 @@
+/*
+ * Copyright (c) 2013 - 2014, Freescale Semiconductor, Inc.
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without modification,
+ * are permitted provided that the following conditions are met:
+ *
+ * o Redistributions of source code must retain the above copyright notice, this list
+ *   of conditions and the following disclaimer.
+ *
+ * o Redistributions in binary form must reproduce the above copyright notice, this
+ *   list of conditions and the following disclaimer in the documentation and/or
+ *   other materials provided with the distribution.
+ *
+ * o Neither the name of Freescale Semiconductor, Inc. nor the names of its
+ *   contributors may be used to endorse or promote products derived from this
+ *   software without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+ * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+ * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR
+ * ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+ * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+ * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
+ * ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+ * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+ * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ */
+#if !defined(__FSL_OS_ABSTRACTION_H__)
+#define __FSL_OS_ABSTRACTION_H__
+
+#include <stdint.h>
+#include <stdbool.h>
+#include <stdlib.h>
+
+#if defined __CC_ARM
+#define inline      __inline
+#endif
+
+/*!
+ * @addtogroup os_abstraction
+ * @{
+ */
+
+/*! @brief Status values to be returned by functions. */
+typedef enum
+{
+    kSuccess = 0,  /*!< Functions work correctly.                   */
+    kError,        /*!< Functions work failed.                      */
+    kTimeout,      /*!< Timeout occurs while waiting for an object. */
+    kIdle          /*!< Can not get the object in non-blocking mode.*/
+}fsl_rtos_status;
+
+/*! @brief The event flags are set or not.*/
+typedef enum
+{
+    kFlagNotSet = 0, /*!< The flags checked are set.     */
+    kFlagSet         /*!< The flags checked are not set. */
+}event_status;
+
+/*! @brief The event flags are cleared automatically or manually.*/
+typedef enum
+{
+    kEventAutoClr = 0, /*!< The flags of the event will be cleared automatically. */
+    kEventManualClr    /*!< The flags of the event will be cleared manually.      */
+}event_clear_type;
+
+/* Include required header file based on RTOS selection */
+#if defined (FSL_RTOS_MQX)
+    /*! @brief Macro to set message queue copy messages to internal memory or not. */
+    #define __FSL_RTOS_MSGQ_COPY_MSG__  1
+    #include "fsl_os_abstraction_mqx.h"
+
+#elif defined (FSL_RTOS_FREE_RTOS)
+    #define __FSL_RTOS_MSGQ_COPY_MSG__  1
+    #include "fsl_os_abstraction_free_rtos.h"
+
+#elif defined (FSL_RTOS_UCOSII)
+    #define __FSL_RTOS_MSGQ_COPY_MSG__  1
+    #include "fsl_os_abstraction_ucosii.h"
+
+#elif defined (FSL_RTOS_UCOSIII)
+    #define __FSL_RTOS_MSGQ_COPY_MSG__  1
+    #include "fsl_os_abstraction_ucosiii.h"
+
+#elif defined (FSL_RTOS_CMSIS)
+    #define __FSL_RTOS_MSGQ_COPY_MSG__  0
+    #include "fsl_os_abstraction_cmsis.h"
+
+#elif defined (FSL_RTOS_MBED)
+    #define __FSL_RTOS_MSGQ_COPY_MSG__  1
+    #include "fsl_os_abstraction_mbed.h"
+
+#else
+    #define __FSL_RTOS_MSGQ_COPY_MSG__  1
+    #include "fsl_os_abstraction_bm.h"
+#endif
+
+/*******************************************************************************
+ * API
+ ******************************************************************************/
+
+#if defined(__cplusplus)
+extern "C" {
+#endif
+
+/*!
+ * @name Synchronization
+ * @{
+ */
+
+/*!
+ * @brief Initialize a synchronization object to a given state.
+ *
+ * @param obj The sync object to initialize.
+ * @param initValue The initial value the object will be set to.
+ * 
+ * @retval kSuccess The object was successfully created.
+ * @retval kError Invalid parameter or no more objects can be created.
+ */
+fsl_rtos_status sync_create(sync_object_t *obj, uint8_t initValue);
+
+/*!
+ * @brief Wait for the synchronization object.
+ *
+ * This function checks the sync object's counting value, if it is
+ * positive, decreases it and returns kSuccess, otherwise, timeout will be
+ * used for wait.
+ *
+ * @param obj Pointer to the synchronization object.
+ * @param timeout The maximum number of milliseconds to wait for the object to be signalled.
+ *      Pass the #kSyncWaitForever constant to wait indefinitely for someone to signal the object.
+ *      A value of 0 should not be passed to this function. Instead, use sync_poll for
+ *      a non blocking check.
+ *
+ * @retval kSuccess The object was signalled.
+ * @retval kTimeout A timeout occurred.
+ * @retval kError An incorrect parameter was passed.
+ * @retval kIdle The object has not been signalled.
+ *
+ * @note There could be only one process waiting for the object at the same time.
+ */
+fsl_rtos_status sync_wait(sync_object_t *obj, uint32_t timeout);
+
+/*!
+ * @brief Checks a synchronization object's status.
+ *
+ * This function is used to poll a sync object's status.
+ * If the sync object's counting value is positive, decrease it and return
+ * kSuccess. If the object's counting value is 0, the function will
+ * return kIdle immediately
+ *
+ * @param obj The synchronization object.
+ *
+ * @retval kSuccess The object was signalled.
+ * @retval kIdle The object was not signalled.
+ * @retval kError An incorrect parameter was passed.
+ */
+fsl_rtos_status sync_poll(sync_object_t *obj);
+
+/*!
+ * @brief Signal for someone waiting on the synchronization object to wake up.
+ *
+ * This function should not be called from an ISR.
+ *
+ * @param obj The synchronization object to signal.
+ * 
+ * @retval kSuccess The object was successfully signaled.
+ * @retval kError The object can not be signaled or invalid parameter.
+ */
+fsl_rtos_status sync_signal(sync_object_t *obj);
+
+/*!
+ * @brief Signal for someone waiting on the synchronization object to wake up.
+ *
+ * This function should only be called from an ISR.
+ *
+ * @param obj The synchronization object to signal.
+ * 
+ * @retval kSuccess The object was successfully signaled.
+ * @retval kError The object can not be signaled or invalid parameter.
+ */
+fsl_rtos_status sync_signal_from_isr(sync_object_t *obj);
+
+/*!
+ * @brief Destroy a previously created synchronization object.
+ *
+ * @param obj The synchronization object to destroy.
+ * 
+ * @retval kSuccess The object was successfully destroyed.
+ * @retval kError Object destruction failed.
+ */
+fsl_rtos_status sync_destroy(sync_object_t *obj);
+
+/* @} */
+
+/*!
+ * @name Resource locking
+ * @{
+ */
+
+/*!
+ * @brief Initialize a locking object.
+ *
+ * @param obj The lock object to initialize.
+ *
+ * @retval kSuccess The lock is created successfully.
+ * @retval kError Tke lock creation failed.
+ */
+fsl_rtos_status lock_create(lock_object_t *obj);
+
+/*!
+ * @brief Wait for the object to be unlocked and lock it.
+ *
+ * This function will wait for some time or wait forever if could not get the lock.
+ *
+ * @param obj The locking object.
+ * @param timeout The maximum number of milliseconds to wait for the mutex.
+ *      Pass the #kSyncWaitForever constant to wait indefinitely for someone to unlock the object.
+ *      A value of 0 should not be passed to this function. Instead, use lock_poll for a non
+ *      blocking check.
+ *
+ * @retval kSuccess The lock was obtained.
+ * @retval kTimeout A timeout occurred.
+ * @retval kError An incorrect parameter was passed.
+ */
+fsl_rtos_status lock_wait(lock_object_t *obj, uint32_t timeout);
+
+/*!
+ * @brief Checks if a locking object can be locked and locks it if possible.
+ *
+ * This function returns instantly if could not get the lock.
+ *
+ * @param obj The locking object.
+ *
+ * @retval kSuccess The lock was obtained.
+ * @retval kIdle The lock could not be obtained.
+ * @retval kError An incorrect parameter was passed.
+ *
+ * @note There could be only one process waiting for the object at the same time.
+ * For RTOSes, wait for a lock recursively by one task is not supported.
+ *
+ */
+fsl_rtos_status lock_poll(lock_object_t *obj);
+
+/*!
+ * @brief Unlock a previously locked object.
+ *
+ * @param obj The locking object to unlock.
+ * 
+ * @retval kSuccess The object was successfully unlocked.
+ * @retval kError The object can not be unlocked or invalid parameter.
+ */
+fsl_rtos_status lock_release(lock_object_t *obj);
+
+/*!
+ * @brief Destroy a previously created locking object.
+ *
+ * @param obj The locking object to destroy.
+ * 
+ * @retval kSuccess The object was successfully destroyed.
+ * @retval kError Object destruction failed.
+ */
+fsl_rtos_status lock_destroy(lock_object_t *obj);
+
+/* @} */
+
+/*!
+ * @name Event signaling
+ * @{
+ */
+
+/*!
+ * @brief Initializes the event object.
+ *
+ * When the object is created, the flags is 0.
+ *
+ * @param obj Pointer to the event object to initialize.
+ * @param clearType The event is auto-clear or manual-clear.
+ *
+ * @retval kSuccess The object was successfully created.
+ * @retval kError Incorrect parameter or no more objects can be created.
+ */
+fsl_rtos_status event_create(event_object_t *obj, event_clear_type clearType);
+
+/*!
+ * @brief Wait for any event flags to be set.
+ *
+ * This function will wait for some time or wait forever if no flags are set. Any flags set
+ * will wake up the function.
+ *
+ * @param obj The event object.
+ * @param timeout The maximum number of milliseconds to wait for the event.
+ *      Pass the #kSyncWaitForever constant to wait indefinitely. A value of 0 should not be passed 
+ *      to this function.
+ * @param setFlags Pointer to receive the flags that were set.
+ *
+ * @retval kSuccess An event was set.
+ * @retval kTimeout A timeout occurred.
+ * @retval kError An incorrect parameter was passed.
+ */
+fsl_rtos_status event_wait(event_object_t *obj, uint32_t timeout, event_group_t *setFlags);
+
+/*!
+ * @brief Set one or more event flags of an event object.
+ *
+ * This function should not be called from an ISR.
+ *
+ * @param obj The event object.
+ * @param flags Event flags to be set.
+ *
+ * @retval kSuccess The flags were successfully set.
+ * @retval kError An incorrect parameter was passed.
+ *
+ * @note There could be only one process waiting for the event.
+ *
+ */
+fsl_rtos_status event_set(event_object_t *obj, event_group_t flags);
+
+/*!
+ * @brief Set one or more event flags of an event object.
+ *
+ * This function should only be called from an ISR.
+ *
+ * @param obj The event object.
+ * @param flags Event flags to be set.
+ *
+ * @retval kSuccess The flags were successfully set.
+ * @retval kError An incorrect parameter was passed.
+ */
+fsl_rtos_status event_set_from_isr(event_object_t *obj, event_group_t flags);
+
+/*!
+ * @brief Clear one or more events of an event object.
+ *
+ * This function should not be called from an ISR.
+ *
+ * @param obj The event object.
+ * @param flags Event flags to be clear.
+ *
+ * @retval kSuccess The flags were successfully cleared.
+ * @retval kError An incorrect parameter was passed.
+ */
+fsl_rtos_status event_clear(event_object_t *obj, event_group_t flags);
+
+/*!
+ * @brief Check the flags are set or not.
+ *
+ * @param obj The event object.
+ * @param flag The flag to check.
+ *
+ * @retval kFlagsSet The flags checked are set.
+ * @retval kFlagsNotSet The flags checked are not set or got an error.
+ */
+event_status event_check_flags(event_object_t *obj, event_group_t flag);
+
+/*!
+ * @brief Destroy a previously created event object.
+ *
+ * @param obj The event object to destroy.
+ * 
+ * @retval kSuccess The object was successfully destroyed.
+ * @retval kError Event destruction failed.
+ */
+fsl_rtos_status event_destroy(event_object_t *obj);
+/* @} */
+
+/*!
+ * @name Thread management
+ * @{
+ */
+
+/*!
+ * @brief Create a task.
+ *
+ * This function is wrapped by the macro task_create. Generally, this function is for
+ * internal use only, applications must use FSL_RTOS_TASK_DEFINE to define resources for
+ * task statically then use task_create to create task. If applications have prepare
+ * the resouces for task dynamically, they can use this function to create the task.
+ *
+ * @param task The task function.
+ * @param name The name of this task.
+ * @param stackSize The stack size in byte.
+ * @param stackMem Pointer to the stack. For bare metal, MQX and FreeRTOS, this could be NULL.
+ * @param priority Initial priority of the task.
+ * @param param Pointer to be passed to the task when it is created.
+ * @param usesFloat This task will use float register or not.
+ * @param handler Pointer to the task handler.
+ *
+ * @retval kSuccess The task was successfully created.
+ * @retval kError The task could not be created.
+ *
+ * @note Different tasks can not use the same task function.
+ */
+fsl_rtos_status __task_create(task_t task, uint8_t *name, uint16_t stackSize,
+                              task_stack_t *stackMem, uint16_t priority,
+                              void *param, bool usesFloat, task_handler_t *handler);
+
+/*!
+ * @brief Destroy a previously created task.
+ * @note Depending on the RTOS, task resources may or may not be automatically freed,
+ *       and this function may not return if the current task is destroyed.
+ *
+ * @param handler The handler of the task to destroy. Returned by the task_create function.
+ * 
+ * @retval kSuccess The task was successfully destroyed.
+ * @retval kError Task destruction failed or invalid parameter.
+ */
+fsl_rtos_status task_destroy(task_handler_t handler);
+/* @} */
+
+/*!
+ * @name Message queues
+ * @{
+ */
+
+/*!
+ * @brief Initialize the message queue.
+ *
+ * This function will initialize the message queue that declared previously.
+ * Here is an example demonstrating how to use:
+   @code
+   msg_queue_handler_t handler;
+   MSG_QUEUE_DECLARE(my_message, msg_num, msg_size);
+   handler = msg_queue_create(&my_message, msg_num, msg_size);
+   @endcode
+ *
+ * @param queue The queue declared through the MSG_QUEUE_DECLARE macro.
+ * @param number The number of elements in the queue.
+ * @param size Size of every elements in words.
+ * 
+ * @retval Handler to access the queue for put and get operations. If message queue
+ *         created failed, return 0.
+ */
+msg_queue_handler_t msg_queue_create(msg_queue_t *queue, uint16_t number, uint16_t size);
+
+/*!
+ * @brief Introduce an element at the tail of the queue.
+ *
+ * @param handler Queue handler returned by the msg_queue_create function.
+ * @param item Pointer to the element to be introduced in the queue.
+ * 
+ * @retval kSuccess Element successfully introduced in the queue.
+ * @retval kError The queue was full or an invalid parameter was passed.
+ */
+fsl_rtos_status msg_queue_put(msg_queue_handler_t handler, msg_queue_item_t item);
+
+/*!
+ * @brief Read and remove an element at the head of the queue.
+ *
+ * @param handler Queue handler returned by the msg_queue_create function.
+ * @param item Pointer to store a pointer to the element of the queue.
+ * @param timeout In case the queue is empty, the number of milliseconds to
+ *        wait for an element to be introduced into the queue. Use 0 to return
+ *        immediately or #kSyncWaitForever to wait indefinitely.
+ * 
+ * @retval kSuccess Element successfully obtained from the queue.
+ * @retval kTimeout If a timeout was specified, the queue remained empty after timeout.
+ * @retval kError The queue was empty or the handler was invalid.
+ * @retval kIdle The queue was empty and the timeout has not expired.
+ *
+ * @note There should be only one process waiting on the queue.
+ */
+fsl_rtos_status msg_queue_get(msg_queue_handler_t handler,
+                              msg_queue_item_t   *item,
+                              uint32_t            timeout);
+
+/*!
+ * @brief Discards all elements in the queue and leaves the queue empty.
+ *
+ * @param handler Queue handler returned by the msg_queue_create function.
+ * 
+ * @retval kSuccess Queue successfully emptied.
+ * @retval kError Emptying queue failed.
+ */
+fsl_rtos_status msg_queue_flush(msg_queue_handler_t handler);
+
+/*!
+ * @brief Destroy a previously created queue.
+ *
+ * @param handler Queue handler returned by the msg_queue_create function.
+ * 
+ * @retval kSuccess The queue was successfully destroyed.
+ * @retval kError Message queue destruction failed.
+ */
+fsl_rtos_status msg_queue_destroy(msg_queue_handler_t handler);
+
+/* @} */
+
+#ifndef FSL_RTOS_MBED
+/*!
+ * @name Memory Management
+ * @{
+ */
+
+/*!
+ * @brief Reserves the requested amount of memory in bytes.
+ *
+ * @param size Amount of bytes to reserve.
+ *
+ * @retval Pointer to the reserved memory. NULL if memory could not be allocated.
+ */
+void * mem_allocate(size_t size);
+
+/*!
+ * @brief Reserves the requested amount of memory in bytes and initializes it to 0.
+ *
+ * @param size Amount of bytes to reserve.
+ *
+ * @retval Pointer to the reserved memory. NULL if memory could not be allocated.
+ */
+void * mem_allocate_zero(size_t size);
+
+/*!
+ * @brief Releases the memory previously reserved.
+ *
+ * @param ptr Pointer to the start of the memory block previously reserved.
+ *
+ * @retval kSuccess Memory correctly released.
+ */
+fsl_rtos_status mem_free(void *ptr);
+#endif
+
+/* @} */
+
+/*!
+ * @name Time management
+ * @{
+ */
+
+/*!
+ * @brief Delays execution for a number of milliseconds.
+ *
+ * @param delay The time in milliseconds to wait.
+ */
+void time_delay(uint32_t delay);
+
+/* @} */
+
+/*!
+ * @name Interrupt management
+ * @{
+ */
+
+/*!
+ * @brief Install interrupt handler.
+ *
+ * @param irqNumber IRQ number of the interrupt.
+ * @param handler The interrupt handler to install.
+ *
+ * @retval kSuccess Handler is installed successfully.
+ * @retval kSuccess Handler could not be installed.
+ */
+fsl_rtos_status interrupt_handler_register(int32_t irqNumber, void (*handler)(void));
+
+/* @} */
+
+#if defined(__cplusplus)
+}
+#endif
+
+/*! @}*/
+
+#endif /* __FSL_OS_ABSTRACTION_H__ */
+/*******************************************************************************
+ * EOF
+ ******************************************************************************/
+