PAL
A Platform Abstraction Layer connects the mbed-client with the underlying platform.
Macros | Typedefs | Functions
pal_plat_rtos.c File Reference
#include "pal_types.h"
#include "pal_rtos.h"
#include "pal_plat_rtos.h"
#include "pal_errors.h"
#include "stdlib.h"
#include "string.h"
#include "cmsis_os.h"
#include "critical.h"

Macros

#define PAL_RTOS_TRANSLATE_CMSIS_ERROR_CODE(cmsisCode)   ((int32_t)(cmsisCode + PAL_ERR_RTOS_ERROR_BASE))
 
#define PAL_RTOS_MEMORY_POOL_SIZE(blockSize, blockCount)   (sizeof(uint32_t)*(3+((blockSize+3)/4)*(blockCount)))
 the size of the memory to allocate was taken from CMSIS header (cmsis_os.h) More...
 
#define PAL_RTOS_MESSAGE_Q_SIZE(messageQSize)   (sizeof(uint32_t)*(4 + messageQSize))
 the size of the memory to allocate was taken from CMSIS header (cmsis_os.h) More...
 
#define PAL_TIMER_DATA_SIZE   6
 
#define PAL_MUTEX_DATA_SIZE   4
 
#define PAL_SEMAPHORE_DATA_SIZE   2
 
#define PAL_NUM_OF_THREAD_INSTANCES   1
 
#define PAL_TICK_TO_MILLI_FACTOR   1000
 

Typedefs

typedef struct palThreadFuncWrapper palThreadFuncWrapper_t
 
typedef struct palThread palThread_t
 Thread structure. More...
 
typedef struct palTimer palTimer_t
 Timer structure. More...
 
typedef struct palMutex palMutex_t
 Mutex structure. More...
 
typedef struct palSemaphore palSemaphore_t
 Semaphore structure. More...
 
typedef struct palMemPool palMemoryPool_t
 Memoey Pool structure. More...
 
typedef struct palMessageQ palMessageQ_t
 Message Queue structure. More...
 

Functions

void NVIC_SystemReset (void)
 
void pal_plat_osReboot ()
 
palStatus_t pal_plat_RTOSInitialize (void *opaqueContext)
 
void pal_plat_RTOSDestroy (void)
 
palStatus_t pal_plat_osDelay (uint32_t milliseconds)
 
uint32_t pal_plat_osKernelSysTick ()
 
uint64_t pal_plat_osKernelSysTickMicroSec (uint64_t microseconds)
 
uint64_t pal_plat_osKernelSysMilliSecTick (uint64_t sysTicks)
 
uint64_t pal_plat_osKernelSysTickFrequency ()
 
palStatus_t pal_plat_osThreadCreate (palThreadFuncPtr function, void *funcArgument, palThreadPriority_t priority, uint32_t stackSize, uint32_t *stackPtr, palThreadLocalStore_t *store, palThreadID_t *threadID)
 
palThreadID_t pal_plat_osThreadGetId ()
 
palStatus_t pal_plat_osThreadTerminate (palThreadID_t *threadID)
 
void * pal_plat_osThreadGetLocalStore ()
 
palStatus_t pal_plat_osTimerCreate (palTimerFuncPtr function, void *funcArgument, palTimerType_t timerType, palTimerID_t *timerID)
 
palStatus_t pal_plat_osTimerStart (palTimerID_t timerID, uint32_t millisec)
 
palStatus_t pal_plat_osTimerStop (palTimerID_t timerID)
 
palStatus_t pal_plat_osTimerDelete (palTimerID_t *timerID)
 
palStatus_t pal_plat_osMutexCreate (palMutexID_t *mutexID)
 
palStatus_t pal_plat_osMutexWait (palMutexID_t mutexID, uint32_t millisec)
 
palStatus_t pal_plat_osMutexRelease (palMutexID_t mutexID)
 
palStatus_t pal_plat_osMutexDelete (palMutexID_t *mutexID)
 
palStatus_t pal_plat_osSemaphoreCreate (uint32_t count, palSemaphoreID_t *semaphoreID)
 
palStatus_t pal_plat_osSemaphoreWait (palSemaphoreID_t semaphoreID, uint32_t millisec, int32_t *countersAvailable)
 
palStatus_t pal_plat_osSemaphoreRelease (palSemaphoreID_t semaphoreID)
 
palStatus_t pal_plat_osSemaphoreDelete (palSemaphoreID_t *semaphoreID)
 
palStatus_t pal_plat_osPoolCreate (uint32_t blockSize, uint32_t blockCount, palMemoryPoolID_t *memoryPoolID)
 
void * pal_plat_osPoolAlloc (palMemoryPoolID_t memoryPoolID)
 
void * pal_plat_osPoolCAlloc (palMemoryPoolID_t memoryPoolID)
 
palStatus_t pal_plat_osPoolFree (palMemoryPoolID_t memoryPoolID, void *block)
 
palStatus_t pal_plat_osPoolDestroy (palMemoryPoolID_t *memoryPoolID)
 
palStatus_t pal_plat_osMessageQueueCreate (uint32_t messageQSize, palMessageQID_t *messageQID)
 
palStatus_t pal_plat_osMessagePut (palMessageQID_t messageQID, uint32_t info, uint32_t timeout)
 
palStatus_t pal_plat_osMessageGet (palMessageQID_t messageQID, uint32_t timeout, uint32_t *messageValue)
 
palStatus_t pal_plat_osMessageQueueDestroy (palMessageQID_t *messageQID)
 
int32_t pal_plat_osAtomicIncrement (int32_t *valuePtr, int32_t increment)
 

Macro Definition Documentation

#define PAL_MUTEX_DATA_SIZE   4
#define PAL_NUM_OF_THREAD_INSTANCES   1
#define PAL_RTOS_MEMORY_POOL_SIZE (   blockSize,
  blockCount 
)    (sizeof(uint32_t)*(3+((blockSize+3)/4)*(blockCount)))

the size of the memory to allocate was taken from CMSIS header (cmsis_os.h)

#define PAL_RTOS_MESSAGE_Q_SIZE (   messageQSize)    (sizeof(uint32_t)*(4 + messageQSize))

the size of the memory to allocate was taken from CMSIS header (cmsis_os.h)

#define PAL_RTOS_TRANSLATE_CMSIS_ERROR_CODE (   cmsisCode)    ((int32_t)(cmsisCode + PAL_ERR_RTOS_ERROR_BASE))
#define PAL_SEMAPHORE_DATA_SIZE   2
#define PAL_TICK_TO_MILLI_FACTOR   1000
#define PAL_TIMER_DATA_SIZE   6

This definitions should be under #ifdef for different CORTEX-X processors. The current vaules are for cortex-M these are the sizes of the internal data array in definitions arrays

Typedef Documentation

typedef struct palMemPool palMemoryPool_t

Memoey Pool structure.

typedef struct palMessageQ palMessageQ_t

Message Queue structure.

typedef struct palMutex palMutex_t

Mutex structure.

typedef struct palSemaphore palSemaphore_t

Semaphore structure.

typedef struct palThread palThread_t

Thread structure.

typedef struct palThreadFuncWrapper palThreadFuncWrapper_t
typedef struct palTimer palTimer_t

Timer structure.

Function Documentation

void NVIC_SystemReset ( void  )
int32_t pal_plat_osAtomicIncrement ( int32_t *  valuePtr,
int32_t  increment 
)

Perform an atomic increment for a signed32 bit value.

Parameters
[in,out]valuePtrThe address of the value to increment.
[in]incrementThe number by which to increment.
Returns
The value of the valuePtr after the increment operation.
palStatus_t pal_plat_osDelay ( uint32_t  milliseconds)

Wait for a specified period of time in milliseconds.

Parameters
[in]millisecondsThe number of milliseconds to wait before proceeding.
Returns
The status in the form of palStatus_t; PAL_SUCCESS(0) in case of success, a negative value indicating a specific error code in case of failure.
uint64_t pal_plat_osKernelSysMilliSecTick ( uint64_t  sysTicks)

Convert the value from kernel system ticks to milliseconds.

Parameters
[in]sysTicksThe number of kernel system ticks to convert into millieseconds.
Returns
The converted value in system ticks.
uint32_t pal_plat_osKernelSysTick ( )

Get the RTOS kernel system timer counter.

Returns
The RTOS kernel system timer counter.
Note
The required tick counter is the OS (platform) kernel system tick counter.
This counter wraps around very often (for example, once every 42 sec for 100Mhz).
uint64_t pal_plat_osKernelSysTickFrequency ( void  )

Get the system tick frequency.

Returns
The system tick frequency.
uint64_t pal_plat_osKernelSysTickMicroSec ( uint64_t  microseconds)

Convert the value from microseconds to kernel sys ticks. This is the same as CMSIS macro osKernelSysTickMicroSec.

palStatus_t pal_plat_osMessageGet ( palMessageQID_t  messageQID,
uint32_t  timeout,
uint32_t *  messageValue 
)

Get a message or wait for a message from a queue.

Parameters
[in]messageQIDThe handle for the message queue.
[in]timeoutThe timeout in milliseconds.
[out]messageValueThe data to send.
Returns
The status in the form of palStatus_t; PAL_SUCCESS(0) in case of success, one of the following error codes in case of failure: PAL_ERR_RTOS_RESOURCE - Semaphore was not available but not due to timeout. 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_plat_osMessagePut ( palMessageQID_t  messageQID,
uint32_t  info,
uint32_t  timeout 
)

Put a message to a queue.

Parameters
[in]messageQIDThe handle for the message queue.
[in]infoThe data to send.
[in]timeoutThe timeout in milliseconds.
Returns
The status in the form of palStatus_t; PAL_SUCCESS(0) in case of success, a negative value indicating a specific error code in case of failure.
palStatus_t pal_plat_osMessageQueueCreate ( uint32_t  messageQSize,
palMessageQID_t messageQID 
)

Create and initialize a message queue.

Parameters
[in]messageQSizeThe size of the message queue.
[out]messageQIDThe ID of the created message queue, zero value indicates an error.
Returns
PAL_SUCCESS when the message queue was created successfully, a specific error in case of failure. PAL_ERR_NO_MEMORY: no memory resource available to create message queue object.
Note
the create function MUST not wait for platform resources and it should return "PAL_ERR_RTOS_RESOURCE", unless the platform API is blocking.
palStatus_t pal_plat_osMessageQueueDestroy ( palMessageQID_t messageQID)

Delete a message queue object.

Parameters
[in,out]messageQIDThe handle for the message queue. In success, *messageQID = NULL.
Returns
The status in the form of palStatus_t; PAL_SUCCESS(0) in case of success, a negative value indicating a specific error code in case of failure.
palStatus_t pal_plat_osMutexCreate ( palMutexID_t mutexID)

Create and initialize a mutex object.

Parameters
[out]mutexIDThe created mutex ID handle, zero value indicates an error.
Returns
PAL_SUCCESS when the mutex was created successfully, a specific error in case of failure. PAL_ERR_NO_MEMORY: no memory resource available to create mutex object.
Note
the create function MUST not wait for platform resources and it should return "PAL_ERR_RTOS_RESOURCE", unless the platform API is blocking.
palStatus_t pal_plat_osMutexDelete ( palMutexID_t mutexID)

Delete a mutex object.

Parameters
[in,out]mutexIDThe ID of the mutex to delete. In success, *mutexID = NULL.
Returns
PAL_SUCCESS when the mutex was deleted successfully, one of the following error codes in case of failure: 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, mutex_id is no longer valid and cannot be used.
palStatus_t pal_plat_osMutexRelease ( palMutexID_t  mutexID)

Release a mutex that was obtained by osMutexWait.

Parameters
[in]mutexIDThe handle for the mutex.
Returns
The status in the form of palStatus_t; PAL_SUCCESS(0) in case of success, a negative value indicating a specific error code in case of failure.
palStatus_t pal_plat_osMutexWait ( palMutexID_t  mutexID,
uint32_t  millisec 
)

Wait until a mutex becomes available.

Parameters
[in]mutexIDThe handle for the mutex.
[in]millisecThe timeout for the waiting operation if the timeout expires before the semaphore is released and an error is returned from the function.
Returns
The status in the form of palStatus_t; PAL_SUCCESS(0) in case of success, one of the following error codes in case of failure: PAL_ERR_RTOS_RESOURCE - Mutex not available but no timeout 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.
void* pal_plat_osPoolAlloc ( palMemoryPoolID_t  memoryPoolID)

Allocate a single memory block from a memory pool.

Parameters
[in]memoryPoolIDThe handle for the memory pool.
Returns
A pointer to a single allocated memory from the pool, NULL in case of failure.
void* pal_plat_osPoolCAlloc ( palMemoryPoolID_t  memoryPoolID)

Allocate a single memory block from a memory pool and set memory block to zero.

Parameters
[in]memoryPoolIDThe handle for the memory pool.
Returns
A pointer to a single allocated memory from the pool, NULL in case of failure.
palStatus_t pal_plat_osPoolCreate ( uint32_t  blockSize,
uint32_t  blockCount,
palMemoryPoolID_t memoryPoolID 
)

Create and initialize a memory pool.

Parameters
[in]blockSizeThe size of a single block in bytes.
[in]blockCountThe maximum number of blocks in the memory pool.
[out]memoryPoolIDThe ID of the created memory pool, zero value indicates an error.
Returns
PAL_SUCCESS when the memory pool was created successfully, a specific error in case of failure. PAL_ERR_NO_MEMORY: no memory resource available to create memory pool object.
Note
the create function MUST not wait for platform resources and it should return "PAL_ERR_RTOS_RESOURCE", unless the platform API is blocking.
palStatus_t pal_plat_osPoolDestroy ( palMemoryPoolID_t memoryPoolID)

Delete a memory pool object.

Parameters
[in,out]memoryPoolIDThe handle for the memory pool. In success, *memoryPoolID = NULL.
Returns
The status in the form of palStatus_t; PAL_SUCCESS(0) in case of success, a negative value indicating a specific error code in case of failure.
palStatus_t pal_plat_osPoolFree ( palMemoryPoolID_t  memoryPoolID,
void *  block 
)

Return the memoryPoolID of the memory block back to a specific memory pool.

Parameters
[in]memoryPoolIDThe handle for the memory pool.
[in]blockThe block to be freed.
Returns
The status in the form of palStatus_t; PAL_SUCCESS(0) in case of success, a negative value indicating a specific error code in case of failure.
void pal_plat_osReboot ( void  )

Initiate a system reboot.

palStatus_t pal_plat_osSemaphoreCreate ( uint32_t  count,
palSemaphoreID_t semaphoreID 
)

Create and initialize a semaphore object.

Parameters
[in]countThe number of available resources.
[out]semaphoreIDThe ID of the created semaphore, zero value indicates an error.
Returns
PAL_SUCCESS when the semaphore was created successfully, a specific error in case of failure. PAL_ERR_NO_MEMORY: no memory resource available to create semaphore object.
Note
the create function MUST not wait for platform resources and it should return "PAL_ERR_RTOS_RESOURCE", unless the platform API is blocking.
palStatus_t pal_plat_osSemaphoreDelete ( palSemaphoreID_t semaphoreID)

Delete a semaphore object.

Parameters
[in,out]semaphoreIDThe ID of the semaphore to delete. In success, *semaphoreID = NULL.
Returns
PAL_SUCCESS when the semaphore was deleted successfully, one of the following error codes in case of failure: 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_plat_osSemaphoreRelease ( palSemaphoreID_t  semaphoreID)

Release a semaphore token.

Parameters
[in]semaphoreIDThe handle for the semaphore.
Returns
The status in the form of palStatus_t; PAL_SUCCESS(0) in case of success, a negative value indicating a specific error code in case of failure.
palStatus_t pal_plat_osSemaphoreWait ( palSemaphoreID_t  semaphoreID,
uint32_t  millisec,
int32_t *  countersAvailable 
)

Wait until a semaphore token becomes available.

Parameters
[in]semaphoreIDThe handle for the semaphore.
[in]millisecThe timeout for the waiting operation if the timeout expires before the semaphore is released and an error is returned from the function.
[out]countersAvailableThe number of semaphores available, if semaphores are not available (timeout/error) zero is returned.
Returns
The status in the form of palStatus_t; PAL_SUCCESS(0) in case of success, 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_plat_osThreadCreate ( palThreadFuncPtr  function,
void *  funcArgument,
palThreadPriority_t  priority,
uint32_t  stackSize,
uint32_t *  stackPtr,
palThreadLocalStore_t store,
palThreadID_t threadID 
)

Create and start a thread function.

Parameters
[in]functionA function pointer to the thread callback function.
[in]funcArgumentAn argument for the thread function.
[in]priorityThe priority of the thread.
[in]stackSizeThe stack size of the thread.
[in]stackPtrA pointer to the thread's stack.
[in]storeA pointer to thread's local store, can be NULL.
[out]threadIDThe created thread ID handle, zero indicates an error.
Returns
The ID of the created thread, in case of error return zero.
Note
Each thread MUST have a unique priority.
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.
the create function MUST not wait for platform resources and it should return "PAL_ERR_RTOS_RESOURCE", unless the platform API is blocking.
palThreadID_t pal_plat_osThreadGetId ( )

Get the ID of the current thread.

Returns
The ID of the current thread, in case of error return PAL_MAX_UINT32.
Note
For a thread with real time priority, the function always returns PAL_MAX_UINT32.
void* pal_plat_osThreadGetLocalStore ( )

Get the storage of the current thread.

Returns
The storage of the current thread.
palStatus_t pal_plat_osThreadTerminate ( palThreadID_t threadID)

Terminate and free allocated data for the thread.

Parameters
[in]threadIDThe ID of the thread to stop and terminate.
Returns
palStatus_t; PAL_SUCCESS(0) in case of success, a negative value indicating a specific error code in case of failure.
palStatus_t pal_plat_osTimerCreate ( palTimerFuncPtr  function,
void *  funcArgument,
palTimerType_t  timerType,
palTimerID_t timerID 
)

Create a timer.

Parameters
[in]functionA function pointer to the timer callback function.
[in]funcArgumentAn argument for the timer callback function.
[in]timerTypeThe timer type to be created, periodic or oneShot.
[out]timerIDThe ID of the created timer, zero value indicates an error.
Returns
PAL_SUCCESS when the timer was created successfully. A specific error in case of failure. PAL_ERR_NO_MEMORY: no memory resource available to create timer object.
Note
the timer callback function runs according to the platform resources of stack-size and priority.
the create function MUST not wait for platform resources and it should return "PAL_ERR_RTOS_RESOURCE", unless the platform API is blocking.
palStatus_t pal_plat_osTimerDelete ( palTimerID_t timerID)

Delete the timer object

Parameters
[in,out]timerIDThe handle for the timer to delete. In success, *timerID = NULL.
Returns
PAL_SUCCESS when the timer was deleted successfully, PAL_ERR_RTOS_PARAMETER when the timerID is incorrect.
palStatus_t pal_plat_osTimerStart ( palTimerID_t  timerID,
uint32_t  millisec 
)

Start or restart a timer.

Parameters
[in]timerIDThe handle for the timer to start.
[in]millisecThe time in milliseconds to set the timer to.
Returns
The status in the form of palStatus_t; PAL_SUCCESS(0) in case of success, a negative value indicating a specific error code in case of failure.
palStatus_t pal_plat_osTimerStop ( palTimerID_t  timerID)

Stop a timer.

Parameters
[in]timerIDThe handle for the timer to stop.
Returns
The status in the form of palStatus_t; PAL_SUCCESS(0) in case of success, a negative value indicating a specific error code in case of failure.
void pal_plat_RTOSDestroy ( void  )

De-Initialize thread objects.

palStatus_t pal_plat_RTOSInitialize ( void *  opaqueContext)

Initialize all data structures (semaphores, mutexes, memory pools, message queues) at system initialization. In case of a failure in any of the initializations, the function returns with an error and stops the rest of the initializations.

Parameters
[in]opaqueContextThe context passed to the initialization (not required for generic CMSIS, pass NULL in this case).
Returns
PAL_SUCCESS(0) in case of success, PAL_ERR_CREATION_FAILED in case of failure.