Diff: pal/Source/PAL-Impl/Services-API/pal_rtos.h

Revision:

0:a7a43371b306

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/pal/Source/PAL-Impl/Services-API/pal_rtos.h	Sun May 14 18:40:18 2017 +0000
@@ -0,0 +1,397 @@
+/*
+* Copyright (c) 2016 ARM Limited. All rights reserved.
+* SPDX-License-Identifier: Apache-2.0
+* Licensed under the Apache License, Version 2.0 (the License); you may
+* not use this file except in compliance with the License.
+* You may obtain a copy of the License at
+*
+* http://www.apache.org/licenses/LICENSE-2.0
+*
+* Unless required by applicable law or agreed to in writing, software
+* distributed under the License is distributed on an AS IS BASIS, WITHOUT
+* WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+* See the License for the specific language governing permissions and
+* limitations under the License.
+*/
+
+
+#ifndef _PAL_RTOS_H
+#define _PAL_RTOS_H
+
+#include <stdint.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+#include "pal_macros.h"
+#include "pal_types.h"
+
+//! Wait forever define. used for Semaphores and Mutexes
+#define PAL_RTOS_WAIT_FOREVER PAL_MAX_UINT32
+
+//! Primitives IDs types declarations
+typedef uintptr_t palThreadID_t;
+typedef uintptr_t palTimerID_t;
+typedef uintptr_t palMutexID_t;
+typedef uintptr_t palSemaphoreID_t;
+typedef uintptr_t palMemoryPoolID_t;
+typedef uintptr_t palMessageQID_t;
+
+//! Timers types supported in PAL
+typedef enum  palTimerType {
+    palOsTimerOnce = 0, /*! One shot timer*/
+    palOsTimerPeriodic = 1 /*! Periodic (repeating) timer*/
+} palTimerType_t;
+
+//! PAL timer function prototype
+typedef void(*palTimerFuncPtr)(void const *funcArgument);
+
+//! PAL thread function prototype
+typedef void(*palThreadFuncPtr)(void const *funcArgument); 
+
+//! Available priorities in PAL implementation, each priority can appear only once.
+typedef enum    pal_osPriority {
+    PAL_osPriorityIdle = -3,
+    PAL_osPriorityLow = -2,
+    PAL_osPriorityBelowNormal = -1,
+    PAL_osPriorityNormal = 0,
+    PAL_osPriorityAboveNormal = +1,
+    PAL_osPriorityHigh = +2,
+    PAL_osPriorityRealtime = +3,
+    PAL_osPriorityError = 0x84
+} palThreadPriority_t; /*! Thread priority levels for PAL threads - each thread must have a different priority*/
+
+//! Thread Local Store struct.
+//! Can be used to hold: State, configurations and etc inside the thread.
+typedef struct pal_threadLocalStore{
+    void* storeData;
+} palThreadLocalStore_t;
+
+//------- system general functions
+/*! Initiates a system reboot
+*/
+void pal_osReboot(void);
+
+//------- system tick functions
+/*! Get the RTOS kernel system timer counter.
+* \note this counter will wrap around very often (e.g. once every 42 sec for 100Mhz)
+* \return the RTOS kernel system timer counter
+*/
+uint32_t pal_osKernelSysTick(void);
+
+/*! Get the RTOS kernel system timer counter.
+* \return the RTOS kernel system timer counter
+*/
+uint64_t pal_osKernelSysTick64(void);
+
+/*! Converts value from microseconds to kernel sys tick
+*
+* @param[in] microseconds the amount of microseconds to convert into system ticks
+*
+* \return converted value in system ticks
+*/
+uint64_t pal_osKernelSysTickMicroSec(uint64_t microseconds);
+
+/*! Converts value from kernel system ticks to milliseconds.
+*
+* @param[in] sysTicks the amount of kernel system ticks to convert into millieseconds
+*
+* \return converted value in system ticks
+*/
+uint64_t pal_osKernelSysMilliSecTick(uint64_t sysTicks);
+
+/*! Get the system tick frequency
+* \return the system tick frequency
+*/
+uint64_t pal_osKernelSysTickFrequency(void);
+
+/*! Creates and starts thread function.
+*
+* @param[in] function: function pointer to the thread callback function.
+* @param[in] funcArgument: argument for the thread function.
+* @param[in] priority: priotity of the thread.
+* @param[in] stackSize: the stack size of the thread can NOT be 0.
+* @param[in] stackPtr: pointer to the thread's stack can NOT be NULL.
+* @param[in] store: pointer to thread's local sotre, can be NULL.
+* @param[out] threadID: holds the created thread ID handle - zero value indecates an error.
+*
+* \return PAL_SUCCESS when thread created successfully.
+*         PAL_ERR_RTOS_PRIORITY : the given priority already used before in the system.
+*
+* \note Each thread MUST be with unique priority.
+* \note When the priority of the created thread function is higher than the current running thread, the 
+*       created thread function starts instantly and becomes the new running thread. 
+*/
+palStatus_t pal_osThreadCreate(palThreadFuncPtr function, void* funcArgument, palThreadPriority_t priority, uint32_t stackSize, uint32_t* stackPtr, palThreadLocalStore_t* store, palThreadID_t* threadID);
+
+
+/*! Terminates and free allocated data for the thread.
+*
+* @param[in] threadID: thread ID to stop and terminate.
+*
+* \return palStatus_t which will be PAL_SUCCESS(0) in case of success and another negative value indicating a specific error code in case of failure
+*         PAL_ERR_RTOS_RESOURCE: if the thread ID is not correct.
+*/
+palStatus_t pal_osThreadTerminate(palThreadID_t* threadID);
+
+/*! Get ID of the current thread
+* \return the ID of the current thread -  in case of error return PAL_MAX_UINT32
+* \note for thread with Real Time priority the function will always return PAL_MAX_UINT32
+*/
+palThreadID_t pal_osThreadGetId(void);
+
+/*! Get the storage of current thread
+* \return the storage of the current thread */
+void* pal_osThreadGetLocalStore(void);
+
+/*! Wait for a specified time period in milliseconds.
+*
+* @param[in] milliseconds the amount of milliseconds to wait before proceeding.
+*
+* \return the function returns the status in the form of palStatus_t which will be PAL_SUCCESS(0) in case of success and another negative value indicating a specific error code in case of failure
+*/
+palStatus_t pal_osDelay(uint32_t milliseconds);
+
+/*! Creates a Timer.
+*
+* @param[in] function: function pointer to the timer callback function.
+* @param[in] funcArgument: funcArgument for the timer callback function.
+* @param[in] timerType: timer type to be created - (periodic or oneShot).
+* @param[out] timerID: holds the created timer ID handle - zero value indecates an error.
+*
+* \return PAL_SUCCESS when timer created successfully.
+*         PAL_ERR_NO_MEMORY: no memory resource available to create timer object.
+*
+* \note the timer function runs according to the platform resources of stack-size and priority.
+*/
+palStatus_t pal_osTimerCreate(palTimerFuncPtr function, void* funcArgument, palTimerType_t timerType, palTimerID_t* timerID);
+
+/*! Start or restart a timer.
+*
+* @param[in] timerID the handle for the timer to start
+* @param[in] millisec the amount of time in milliseconds to set the timer to.
+*
+* \return the function returns the status in the form of palStatus_t which will be PAL_SUCCESS(0) in case of success and another negative value indicating a specific error code in case of failure
+*/
+palStatus_t pal_osTimerStart(palTimerID_t timerID, uint32_t millisec);
+
+/*! Stop a timer.
+* @param[in] timerID the handle for the timer to stop
+* \return the function returns the status in the form of palStatus_t which will be PAL_SUCCESS(0) in case of success and another negative value indicating a specific error code in case of failure
+*/
+palStatus_t pal_osTimerStop(palTimerID_t timerID);
+
+/*! Delete the timer object
+*
+* @param[inout] timerID: the handle for the timer to delete, in success:(*timerID = NULL).
+*
+* \return PAL_SUCCESS when timer deleted successfully.
+*         PAL_ERR_RTOS_PARAMETER when timerID is incorrect.
+*/
+palStatus_t pal_osTimerDelete(palTimerID_t* timerID);
+
+/*! Create and initialize Mutex object
+*
+* @param[out] mutexID: holds the created mutex ID handle - zero value indecates an error.
+*
+* \return PAL_SUCCESS when mutex created successfully.
+*         PAL_ERR_NO_MEMORY: no memory resource available to create mutex object.
+*/
+palStatus_t pal_osMutexCreate(palMutexID_t* mutexID);
+
+/*! Wait until a Mutex becomes available.
+*
+* @param[in] mutexID the handle for the mutex
+* @param[in] millisec the timeout for the waiting operation if the 
+             timeout expires before the semaphore is released and 
+             error will be returned from the function, PAL_RTOS_WAIT_FOREVER can be used.
+*
+* \return the function returns the status in the form of palStatus_t which will be PAL_SUCCESS(0) in case of success and one of the following error codes in case of failure:
+*         PAL_ERR_RTOS_RESOURCE - mutex not avaialbe but no time out set.
+*         PAL_ERR_RTOS_TIMEOUT - mutex was not available until timeout expired.
+*         PAL_ERR_RTOS_PARAMETER - mutex id is invalid
+*         PAL_ERR_RTOS_ISR - cannot be called from interrupt service routines
+*/
+palStatus_t pal_osMutexWait(palMutexID_t mutexID, uint32_t millisec);
+
+/*! Release a Mutex that was obtained by osMutexWait.
+*
+* @param[in] mutexID the handle for the mutex
+* \return the function returns the status in the form of palStatus_t which will be PAL_SUCCESS(0) in case of success and another negative value indicating a specific error code in case of failure
+*/
+palStatus_t pal_osMutexRelease(palMutexID_t mutexID);
+
+/*!Delete a Mutex object.
+*
+* @param[inout] mutexID: Mutex handle to delete, in success:(*mutexID = NULL).
+*
+* \return PAL_SUCCESS when mutex deleted successfully.
+*         PAL_ERR_RTOS_RESOURCE - mutex already released.
+*         PAL_ERR_RTOS_PARAMETER - mutex id is invalid.
+*         PAL_ERR_RTOS_ISR - cannot be called from interrupt service routines.
+* \note After this call the mutex_id is no longer valid and cannot be used.
+*/
+palStatus_t pal_osMutexDelete(palMutexID_t* mutexID);
+
+/*! Create and initialize a Semaphore object
+*
+* @param[in] count: number of available resources
+* @param[out] semaphoreID: holds the created semaphore ID handle - zero value indecates an error.
+*
+* \return PAL_SUCCESS when semaphore created successfully.
+*         PAL_ERR_NO_MEMORY: no memory resource available to create semaphore object.
+*/
+palStatus_t pal_osSemaphoreCreate(uint32_t count, palSemaphoreID_t* semaphoreID);
+
+/*! Wait until a Semaphore token becomes available.
+*
+* @param[in] semaphoreID the handle for the semaphore
+* @param[in] millisec the timeout for the waiting operation if the timeout 
+             expires before the semaphore is released and error will be 
+             returned from the function, PAL_RTOS_WAIT_FOREVER can be used.
+* @param[out] counteresAvailable the number of semaphore available at the call if semaphore is available, if semaphore was not available (timeout/error) zero is returned. 
+* \return the function returns the status in the form of palStatus_t which will be PAL_SUCCESS(0) in case of success and one of the following error codes in case of failure:
+*       PAL_ERR_RTOS_TIMEOUT - semaphore was not available until timeout expired.
+*       PAL_ERR_RTOS_PARAMETER - semaphore id is invalid.
+*/
+palStatus_t pal_osSemaphoreWait(palSemaphoreID_t semaphoreID, uint32_t millisec, int32_t* countersAvailable);
+
+/*! Release a Semaphore token.
+*
+* @param[in] semaphoreID the handle for the semaphore
+*
+* \return the function returns the status in the form of palStatus_t which will be PAL_SUCCESS(0) in case of success and another negative value indicating a specific error code in case of failure
+*/
+palStatus_t pal_osSemaphoreRelease(palSemaphoreID_t semaphoreID);
+
+/*! Delete a Semaphore object
+*
+* @param[inout] semaphoreID: Semaphore handle to delete, in success:(*semaphoreID = NULL).
+*
+* \return PAL_SUCCESS when semaphore deleted successfully.
+*         PAL_ERR_RTOS_RESOURCE - semaphore already released.
+*         PAL_ERR_RTOS_PARAMETER - semaphore id is invalid.
+* \note After this call the semaphore_id is no longer valid and cannot be used.
+*/
+palStatus_t pal_osSemaphoreDelete(palSemaphoreID_t* semaphoreID);
+
+/*! Create and initialize a memory pool.
+*
+* @param[in] blockSize: size of single block in bytes.
+* @param[in] blockCount: maximum number of blocks in memory pool.
+* @param[out] memoryPoolID: holds the created memory pool ID handle - zero value indecates an error.
+*
+* \return PAL_SUCCESS when memory pool created successfully.
+*         PAL_ERR_NO_MEMORY: no memory resource available to create memory pool object.
+*/
+palStatus_t pal_osPoolCreate(uint32_t blockSize, uint32_t blockCount, palMemoryPoolID_t* memoryPoolID);
+
+/*! Allocate a single memory block from a memory pool.
+*
+* @param[in] memoryPoolID the handle for the memory pool
+*
+* \return the function returns a pointer to a single allocated memory from the pool or NULL in case of failure.
+*/
+void* pal_osPoolAlloc(palMemoryPoolID_t memoryPoolID);
+
+/*! Allocate a single memory block from a memory pool and set memory block to zero.
+*
+* @param[in] memoryPoolID the handle for the memory pool
+*
+* \return the function returns a pointer to a single allocated memory from the pool or NULL in case of failure.
+*/
+void* pal_osPoolCAlloc(palMemoryPoolID_t memoryPoolID);
+
+/*! Return an memoryPoolID memory block back to a specific memory pool.
+*
+* @param[in] memoryPoolHandle the handle for the memory pool
+* @param[in] block the block to free
+*
+* \return the function returns the status in the form of palStatus_t which will be PAL_SUCCESS(0) in case of success and another negative value indicating a specific error code in case of failure
+*/
+palStatus_t pal_osPoolFree(palMemoryPoolID_t memoryPoolID, void* block);
+
+/*! Delete a memory pool object.
+*
+* @param[inout] memoryPoolID the handle for the memory pool, in success:(*memoryPoolID = NULL).
+*
+* \return the function returns the status in the form of palStatus_t which will be PAL_SUCCESS(0) in case of success and another negative value indicating a specific error code in case of failure
+*/
+palStatus_t pal_osPoolDestroy(palMemoryPoolID_t* memoryPoolID);
+
+
+/*! Create and initialize a message queue.
+*
+* @param[in] messageQSize: size of the message queue.
+* @param[out] memoryPoolID: holds the created memory pool ID handle - zero value indecates an error.
+*
+* \return PAL_SUCCESS when message queue created successfully.
+*         PAL_ERR_NO_MEMORY: no memory resource available to create message queue object.
+*/
+palStatus_t pal_osMessageQueueCreate(uint32_t messageQSize, palMessageQID_t* messageQID);
+
+/*! Put a Message to a Queue.
+*
+* @param[in] messageQID the handle for the memory pool
+* @param[in] info the data to send
+* @param[in] timeout timeout in milliseconds
+*
+* \return the function returns the status in the form of palStatus_t which will be PAL_SUCCESS(0) in case of success and another negative value indicating a specific error code in case of failure
+*/
+palStatus_t pal_osMessagePut(palMessageQID_t messageQID, uint32_t info, uint32_t timeout);
+
+/*! Get a Message or Wait for a Message from a Queue.
+*
+* @param[in] messageQID the handle for the memory pool
+* @param[in] timeout timeout in milliseconds
+* @param[out] event the data to send
+*
+* \return the function returns the status in the form of palStatus_t which will be PAL_SUCCESS(0) in case of success and one of the following error codes in case of failure:
+* PAL_ERR_RTOS_RESOURCE - in case semaphore was not available but not due to time out.
+* PAL_ERR_RTOS_TIMEOUT -  no message arrived during the timeout period.
+* PAL_ERR_RTOS_RESOURCE -  no message received and there was no timeout
+*/
+palStatus_t pal_osMessageGet(palMessageQID_t messageQID, uint32_t timeout, uint32_t* messageValue);
+
+/*! Delete a message queue object.
+*
+* @param[inout] messageQID the handle for the message queue, in success:(*messageQID = NULL).
+*
+* \return the function returns the status in the form of palStatus_t which will be PAL_SUCCESS(0) in case of success and another negative value indicating a specific error code in case of failure
+*/
+palStatus_t pal_osMessageQueueDestroy(palMessageQID_t* messageQID);
+
+/*! Perform an atomic increment for a signed32 bit value
+*
+* @param[in,out] valuePtr the address of the value to increment
+* @param[int] increment the amount by which to increment
+*
+* \returns the function returns the value of the valuePtr after the increment operation.
+*/
+int32_t pal_osAtomicIncrement(int32_t* valuePtr, int32_t increment);
+
+
+
+
+/*! Printf like function with prefix of function and line.
+*
+* @param[in] function name of the current function
+* @param[in] line line number to be printed
+* @param[in] format print format (just like printf)
+*
+* \returns the function returns the value of the valuePtr after the increment operation.
+*/
+void dbgPrintf( const char* function, uint32_t line, const char * format, ... );
+
+#define PAL_PRINTF( ARGS...) \
+        dbgPrintf(__FUNCTION__,__LINE__, ARGS);
+
+
+
+
+
+#ifdef __cplusplus
+}
+#endif
+#endif //_PAL_RTOS_H