meh
Fork of mbed by
Diff: TARGET_K64F/TARGET_Freescale/TARGET_KPSDK_MCUS/TARGET_KPSDK_CODE/utilities/fsl_os_abstraction.h
- Revision:
- 83:8a40adfe8776
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/TARGET_K64F/TARGET_Freescale/TARGET_KPSDK_MCUS/TARGET_KPSDK_CODE/utilities/fsl_os_abstraction.h Mon Apr 28 17:39:05 2014 +0100 @@ -0,0 +1,572 @@ +/* + * 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; + +// Temporary "fix", until the proper macros are integrated in the on-line build system +#define FSL_RTOS_MBED + +/* 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 + ******************************************************************************/ +