PAL A Platform Abstraction Layer connects the mbed-client with the underlying platform.

- Main Page
- Data Structures
- Files

- File List
- Globals

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] | valuePtr | The address of the value to increment.
  [in] | increment | The 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] | milliseconds | The 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] | sysTicks | The 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] | messageQID | The handle for the message queue.
  [in] | timeout | The timeout in milliseconds.
  [out] | messageValue | The 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] | messageQID | The handle for the message queue.
  [in] | info | The data to send.
  [in] | timeout | The 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] | messageQSize | The size of the message queue.
  [out] | messageQID | The 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] | messageQID | The 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] | mutexID | The 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] | mutexID | The 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] | mutexID | The 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] | mutexID | The handle for the mutex.
  [in] | millisec | The 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] | memoryPoolID | The 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] | memoryPoolID | The 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] | blockSize | The size of a single block in bytes.
  [in] | blockCount | The maximum number of blocks in the memory pool.
  [out] | memoryPoolID | The 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] | memoryPoolID | The 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] | memoryPoolID | The handle for the memory pool.
  [in] | block | The 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] | count | The number of available resources.
  [out] | semaphoreID | The 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] | semaphoreID | The 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] | semaphoreID | The 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] | semaphoreID | The handle for the semaphore.
  [in] | millisec | The timeout for the waiting operation if the timeout expires before the semaphore is released and an error is returned from the function.
  [out] | countersAvailable | The 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] | function | A function pointer to the thread callback function.
  [in] | funcArgument | An argument for the thread function.
  [in] | priority | The priority of the thread.
  [in] | stackSize | The stack size of the thread.
  [in] | stackPtr | A pointer to the thread's stack.
  [in] | store | A pointer to thread's local store, can be NULL.
  [out] | threadID | The 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] | threadID | The 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] | function | A function pointer to the timer callback function.
  [in] | funcArgument | An argument for the timer callback function.
  [in] | timerType | The timer type to be created, periodic or oneShot.
  [out] | timerID | The 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] | timerID | The 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] | timerID | The handle for the timer to start.
  [in] | millisec | The 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] | timerID | The 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] | opaqueContext | The 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.