pal_rtos.h

00001 /*
00002 * Copyright (c) 2016 ARM Limited. All rights reserved.
00003 * SPDX-License-Identifier: Apache-2.0
00004 * Licensed under the Apache License, Version 2.0 (the License); you may
00005 * not use this file except in compliance with the License.
00006 * You may obtain a copy of the License at
00007 *
00008 * http://www.apache.org/licenses/LICENSE-2.0
00009 *
00010 * Unless required by applicable law or agreed to in writing, software
00011 * distributed under the License is distributed on an AS IS BASIS, WITHOUT
00012 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00013 * See the License for the specific language governing permissions and
00014 * limitations under the License.
00015 */
00016 
00017 
00018 #ifndef _PAL_RTOS_H
00019 #define _PAL_RTOS_H
00020 
00021 #include <stdint.h>
00022 
00023 #ifdef __cplusplus
00024 extern "C" {
00025 #endif
00026 
00027 #include "pal_macros.h"
00028 #include "pal_types.h"
00029 
00030 //! Wait forever define. used for Semaphores and Mutexes
00031 #define PAL_RTOS_WAIT_FOREVER PAL_MAX_UINT32
00032 
00033 //! Primitives IDs types declarations
00034 typedef uintptr_t palThreadID_t;
00035 typedef uintptr_t palTimerID_t;
00036 typedef uintptr_t palMutexID_t;
00037 typedef uintptr_t palSemaphoreID_t;
00038 typedef uintptr_t palMemoryPoolID_t;
00039 typedef uintptr_t palMessageQID_t;
00040 
00041 //! Timers types supported in PAL
00042 typedef enum  palTimerType {
00043     palOsTimerOnce = 0, /*! One shot timer*/
00044     palOsTimerPeriodic = 1 /*! Periodic (repeating) timer*/
00045 } palTimerType_t;
00046 
00047 //! PAL timer function prototype
00048 typedef void(*palTimerFuncPtr)(void const *funcArgument);
00049 
00050 //! PAL thread function prototype
00051 typedef void(*palThreadFuncPtr)(void const *funcArgument); 
00052 
00053 //! Available priorities in PAL implementation, each priority can appear only once.
00054 typedef enum    pal_osPriority {
00055     PAL_osPriorityIdle = -3,
00056     PAL_osPriorityLow = -2,
00057     PAL_osPriorityBelowNormal = -1,
00058     PAL_osPriorityNormal = 0,
00059     PAL_osPriorityAboveNormal = +1,
00060     PAL_osPriorityHigh = +2,
00061     PAL_osPriorityRealtime = +3,
00062     PAL_osPriorityError = 0x84
00063 } palThreadPriority_t; /*! Thread priority levels for PAL threads - each thread must have a different priority*/
00064 
00065 //! Thread Local Store struct.
00066 //! Can be used to hold: State, configurations and etc inside the thread.
00067 typedef struct pal_threadLocalStore{
00068     void* storeData;
00069 } palThreadLocalStore_t;
00070 
00071 //------- system general functions
00072 /*! Initiates a system reboot
00073 */
00074 void pal_osReboot(void);
00075 
00076 //------- system tick functions
00077 /*! Get the RTOS kernel system timer counter.
00078 * \note this counter will wrap around very often (e.g. once every 42 sec for 100Mhz)
00079 * \return the RTOS kernel system timer counter
00080 */
00081 uint32_t pal_osKernelSysTick(void);
00082 
00083 /*! Get the RTOS kernel system timer counter.
00084 * \return the RTOS kernel system timer counter
00085 */
00086 uint64_t pal_osKernelSysTick64(void);
00087 
00088 /*! Converts value from microseconds to kernel sys tick
00089 *
00090 * @param[in] microseconds the amount of microseconds to convert into system ticks
00091 *
00092 * \return converted value in system ticks
00093 */
00094 uint64_t pal_osKernelSysTickMicroSec(uint64_t microseconds);
00095 
00096 /*! Converts value from kernel system ticks to milliseconds.
00097 *
00098 * @param[in] sysTicks the amount of kernel system ticks to convert into millieseconds
00099 *
00100 * \return converted value in system ticks
00101 */
00102 uint64_t pal_osKernelSysMilliSecTick(uint64_t sysTicks);
00103 
00104 /*! Get the system tick frequency
00105 * \return the system tick frequency
00106 */
00107 uint64_t pal_osKernelSysTickFrequency(void);
00108 
00109 /*! Creates and starts thread function.
00110 *
00111 * @param[in] function: function pointer to the thread callback function.
00112 * @param[in] funcArgument: argument for the thread function.
00113 * @param[in] priority: priotity of the thread.
00114 * @param[in] stackSize: the stack size of the thread can NOT be 0.
00115 * @param[in] stackPtr: pointer to the thread's stack can NOT be NULL.
00116 * @param[in] store: pointer to thread's local sotre, can be NULL.
00117 * @param[out] threadID: holds the created thread ID handle - zero value indecates an error.
00118 *
00119 * \return PAL_SUCCESS when thread created successfully.
00120 *         PAL_ERR_RTOS_PRIORITY : the given priority already used before in the system.
00121 *
00122 * \note Each thread MUST be with unique priority.
00123 * \note When the priority of the created thread function is higher than the current running thread, the 
00124 *       created thread function starts instantly and becomes the new running thread. 
00125 */
00126 palStatus_t pal_osThreadCreate(palThreadFuncPtr function, void* funcArgument, palThreadPriority_t priority, uint32_t stackSize, uint32_t* stackPtr, palThreadLocalStore_t* store, palThreadID_t* threadID);
00127 
00128 
00129 /*! Terminates and free allocated data for the thread.
00130 *
00131 * @param[in] threadID: thread ID to stop and terminate.
00132 *
00133 * \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
00134 *         PAL_ERR_RTOS_RESOURCE: if the thread ID is not correct.
00135 */
00136 palStatus_t pal_osThreadTerminate(palThreadID_t* threadID);
00137 
00138 /*! Get ID of the current thread
00139 * \return the ID of the current thread -  in case of error return PAL_MAX_UINT32
00140 * \note for thread with Real Time priority the function will always return PAL_MAX_UINT32
00141 */
00142 palThreadID_t pal_osThreadGetId(void);
00143 
00144 /*! Get the storage of current thread
00145 * \return the storage of the current thread */
00146 void* pal_osThreadGetLocalStore(void);
00147 
00148 /*! Wait for a specified time period in milliseconds.
00149 *
00150 * @param[in] milliseconds the amount of milliseconds to wait before proceeding.
00151 *
00152 * \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
00153 */
00154 palStatus_t pal_osDelay(uint32_t milliseconds);
00155 
00156 /*! Creates a Timer.
00157 *
00158 * @param[in] function: function pointer to the timer callback function.
00159 * @param[in] funcArgument: funcArgument for the timer callback function.
00160 * @param[in] timerType: timer type to be created - (periodic or oneShot).
00161 * @param[out] timerID: holds the created timer ID handle - zero value indecates an error.
00162 *
00163 * \return PAL_SUCCESS when timer created successfully.
00164 *         PAL_ERR_NO_MEMORY: no memory resource available to create timer object.
00165 *
00166 * \note the timer function runs according to the platform resources of stack-size and priority.
00167 */
00168 palStatus_t pal_osTimerCreate(palTimerFuncPtr function, void* funcArgument, palTimerType_t timerType, palTimerID_t* timerID);
00169 
00170 /*! Start or restart a timer.
00171 *
00172 * @param[in] timerID the handle for the timer to start
00173 * @param[in] millisec the amount of time in milliseconds to set the timer to.
00174 *
00175 * \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
00176 */
00177 palStatus_t pal_osTimerStart(palTimerID_t timerID, uint32_t millisec);
00178 
00179 /*! Stop a timer.
00180 * @param[in] timerID the handle for the timer to stop
00181 * \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
00182 */
00183 palStatus_t pal_osTimerStop(palTimerID_t timerID);
00184 
00185 /*! Delete the timer object
00186 *
00187 * @param[inout] timerID: the handle for the timer to delete, in success:(*timerID = NULL).
00188 *
00189 * \return PAL_SUCCESS when timer deleted successfully.
00190 *         PAL_ERR_RTOS_PARAMETER when timerID is incorrect.
00191 */
00192 palStatus_t pal_osTimerDelete(palTimerID_t* timerID);
00193 
00194 /*! Create and initialize Mutex object
00195 *
00196 * @param[out] mutexID: holds the created mutex ID handle - zero value indecates an error.
00197 *
00198 * \return PAL_SUCCESS when mutex created successfully.
00199 *         PAL_ERR_NO_MEMORY: no memory resource available to create mutex object.
00200 */
00201 palStatus_t pal_osMutexCreate(palMutexID_t* mutexID);
00202 
00203 /*! Wait until a Mutex becomes available.
00204 *
00205 * @param[in] mutexID the handle for the mutex
00206 * @param[in] millisec the timeout for the waiting operation if the 
00207              timeout expires before the semaphore is released and 
00208              error will be returned from the function, PAL_RTOS_WAIT_FOREVER can be used.
00209 *
00210 * \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:
00211 *         PAL_ERR_RTOS_RESOURCE - mutex not avaialbe but no time out set.
00212 *         PAL_ERR_RTOS_TIMEOUT - mutex was not available until timeout expired.
00213 *         PAL_ERR_RTOS_PARAMETER - mutex id is invalid
00214 *         PAL_ERR_RTOS_ISR - cannot be called from interrupt service routines
00215 */
00216 palStatus_t pal_osMutexWait(palMutexID_t mutexID, uint32_t millisec);
00217 
00218 /*! Release a Mutex that was obtained by osMutexWait.
00219 *
00220 * @param[in] mutexID the handle for the mutex
00221 * \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
00222 */
00223 palStatus_t pal_osMutexRelease(palMutexID_t mutexID);
00224 
00225 /*!Delete a Mutex object.
00226 *
00227 * @param[inout] mutexID: Mutex handle to delete, in success:(*mutexID = NULL).
00228 *
00229 * \return PAL_SUCCESS when mutex deleted successfully.
00230 *         PAL_ERR_RTOS_RESOURCE - mutex already released.
00231 *         PAL_ERR_RTOS_PARAMETER - mutex id is invalid.
00232 *         PAL_ERR_RTOS_ISR - cannot be called from interrupt service routines.
00233 * \note After this call the mutex_id is no longer valid and cannot be used.
00234 */
00235 palStatus_t pal_osMutexDelete(palMutexID_t* mutexID);
00236 
00237 /*! Create and initialize a Semaphore object
00238 *
00239 * @param[in] count: number of available resources
00240 * @param[out] semaphoreID: holds the created semaphore ID handle - zero value indecates an error.
00241 *
00242 * \return PAL_SUCCESS when semaphore created successfully.
00243 *         PAL_ERR_NO_MEMORY: no memory resource available to create semaphore object.
00244 */
00245 palStatus_t pal_osSemaphoreCreate(uint32_t count, palSemaphoreID_t* semaphoreID);
00246 
00247 /*! Wait until a Semaphore token becomes available.
00248 *
00249 * @param[in] semaphoreID the handle for the semaphore
00250 * @param[in] millisec the timeout for the waiting operation if the timeout 
00251              expires before the semaphore is released and error will be 
00252              returned from the function, PAL_RTOS_WAIT_FOREVER can be used.
00253 * @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. 
00254 * \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:
00255 *       PAL_ERR_RTOS_TIMEOUT - semaphore was not available until timeout expired.
00256 *       PAL_ERR_RTOS_PARAMETER - semaphore id is invalid.
00257 */
00258 palStatus_t pal_osSemaphoreWait(palSemaphoreID_t semaphoreID, uint32_t millisec, int32_t* countersAvailable);
00259 
00260 /*! Release a Semaphore token.
00261 *
00262 * @param[in] semaphoreID the handle for the semaphore
00263 *
00264 * \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
00265 */
00266 palStatus_t pal_osSemaphoreRelease(palSemaphoreID_t semaphoreID);
00267 
00268 /*! Delete a Semaphore object
00269 *
00270 * @param[inout] semaphoreID: Semaphore handle to delete, in success:(*semaphoreID = NULL).
00271 *
00272 * \return PAL_SUCCESS when semaphore deleted successfully.
00273 *         PAL_ERR_RTOS_RESOURCE - semaphore already released.
00274 *         PAL_ERR_RTOS_PARAMETER - semaphore id is invalid.
00275 * \note After this call the semaphore_id is no longer valid and cannot be used.
00276 */
00277 palStatus_t pal_osSemaphoreDelete(palSemaphoreID_t* semaphoreID);
00278 
00279 /*! Create and initialize a memory pool.
00280 *
00281 * @param[in] blockSize: size of single block in bytes.
00282 * @param[in] blockCount: maximum number of blocks in memory pool.
00283 * @param[out] memoryPoolID: holds the created memory pool ID handle - zero value indecates an error.
00284 *
00285 * \return PAL_SUCCESS when memory pool created successfully.
00286 *         PAL_ERR_NO_MEMORY: no memory resource available to create memory pool object.
00287 */
00288 palStatus_t pal_osPoolCreate(uint32_t blockSize, uint32_t blockCount, palMemoryPoolID_t* memoryPoolID);
00289 
00290 /*! Allocate a single memory block from a memory pool.
00291 *
00292 * @param[in] memoryPoolID the handle for the memory pool
00293 *
00294 * \return the function returns a pointer to a single allocated memory from the pool or NULL in case of failure.
00295 */
00296 void* pal_osPoolAlloc(palMemoryPoolID_t memoryPoolID);
00297 
00298 /*! Allocate a single memory block from a memory pool and set memory block to zero.
00299 *
00300 * @param[in] memoryPoolID the handle for the memory pool
00301 *
00302 * \return the function returns a pointer to a single allocated memory from the pool or NULL in case of failure.
00303 */
00304 void* pal_osPoolCAlloc(palMemoryPoolID_t memoryPoolID);
00305 
00306 /*! Return an memoryPoolID memory block back to a specific memory pool.
00307 *
00308 * @param[in] memoryPoolHandle the handle for the memory pool
00309 * @param[in] block the block to free
00310 *
00311 * \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
00312 */
00313 palStatus_t pal_osPoolFree(palMemoryPoolID_t memoryPoolID, void* block);
00314 
00315 /*! Delete a memory pool object.
00316 *
00317 * @param[inout] memoryPoolID the handle for the memory pool, in success:(*memoryPoolID = NULL).
00318 *
00319 * \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
00320 */
00321 palStatus_t pal_osPoolDestroy(palMemoryPoolID_t* memoryPoolID);
00322 
00323 
00324 /*! Create and initialize a message queue.
00325 *
00326 * @param[in] messageQSize: size of the message queue.
00327 * @param[out] memoryPoolID: holds the created memory pool ID handle - zero value indecates an error.
00328 *
00329 * \return PAL_SUCCESS when message queue created successfully.
00330 *         PAL_ERR_NO_MEMORY: no memory resource available to create message queue object.
00331 */
00332 palStatus_t pal_osMessageQueueCreate(uint32_t messageQSize, palMessageQID_t* messageQID);
00333 
00334 /*! Put a Message to a Queue.
00335 *
00336 * @param[in] messageQID the handle for the memory pool
00337 * @param[in] info the data to send
00338 * @param[in] timeout timeout in milliseconds
00339 *
00340 * \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
00341 */
00342 palStatus_t pal_osMessagePut(palMessageQID_t messageQID, uint32_t info, uint32_t timeout);
00343 
00344 /*! Get a Message or Wait for a Message from a Queue.
00345 *
00346 * @param[in] messageQID the handle for the memory pool
00347 * @param[in] timeout timeout in milliseconds
00348 * @param[out] event the data to send
00349 *
00350 * \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:
00351 * PAL_ERR_RTOS_RESOURCE - in case semaphore was not available but not due to time out.
00352 * PAL_ERR_RTOS_TIMEOUT -  no message arrived during the timeout period.
00353 * PAL_ERR_RTOS_RESOURCE -  no message received and there was no timeout
00354 */
00355 palStatus_t pal_osMessageGet(palMessageQID_t messageQID, uint32_t timeout, uint32_t* messageValue);
00356 
00357 /*! Delete a message queue object.
00358 *
00359 * @param[inout] messageQID the handle for the message queue, in success:(*messageQID = NULL).
00360 *
00361 * \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
00362 */
00363 palStatus_t pal_osMessageQueueDestroy(palMessageQID_t* messageQID);
00364 
00365 /*! Perform an atomic increment for a signed32 bit value
00366 *
00367 * @param[in,out] valuePtr the address of the value to increment
00368 * @param[int] increment the amount by which to increment
00369 *
00370 * \returns the function returns the value of the valuePtr after the increment operation.
00371 */
00372 int32_t pal_osAtomicIncrement(int32_t* valuePtr, int32_t increment);
00373 
00374 
00375 
00376 
00377 /*! Printf like function with prefix of function and line.
00378 *
00379 * @param[in] function name of the current function
00380 * @param[in] line line number to be printed
00381 * @param[in] format print format (just like printf)
00382 *
00383 * \returns the function returns the value of the valuePtr after the increment operation.
00384 */
00385 void dbgPrintf( const char* function, uint32_t line, const char * format, ... );
00386 
00387 #define PAL_PRINTF( ARGS...) \
00388         dbgPrintf(__FUNCTION__,__LINE__, ARGS);
00389 
00390 
00391 
00392 
00393 
00394 #ifdef __cplusplus
00395 }
00396 #endif
00397 #endif //_PAL_RTOS_H