Mistake on this page? Email us
pal_plat_rtos.h File Reference

PAL RTOS - platform. This file contains the real-time OS APIs that need to be implemented in the platform layer. More...

#include "pal.h"

Go to the source code of this file.

Functions

void pal_plat_osReboot (void)
 Initiate a system reboot. More...
 
void pal_plat_osApplicationReboot (void)
 Application provided implementation to replace default pal_osReboot() functionality. More...
 
palStatus_t pal_plat_RTOSInitialize (void *opaqueContext)
 Initialize all data structures (semaphores, mutexes, memory pools, message queues) at system initialization. More...
 
palStatus_t pal_plat_RTOSDestroy (void)
 De-initialize thread objects. More...
 
uint64_t pal_plat_osKernelSysTick (void)
 Get the RTOS kernel system timer counter. More...
 
uint64_t pal_plat_osKernelSysTickMicroSec (uint64_t microseconds)
 Convert the value from microseconds to kernel system ticks. More...
 
uint64_t pal_plat_osKernelSysTickFrequency (void)
 Get the system tick frequency. More...
 
palStatus_t pal_plat_osThreadCreate (palThreadFuncPtr function, void *funcArgument, palThreadPriority_t priority, uint32_t stackSize, palThreadID_t *threadID)
 Create and run the thread. More...
 
palStatus_t pal_plat_osThreadTerminate (palThreadID_t *threadID)
 Terminate and free allocated data for the thread. More...
 
palThreadID_t pal_plat_osThreadGetId (void)
 Get the ID of the current thread. More...
 
palStatus_t pal_plat_osDelay (uint32_t milliseconds)
 Wait for a specified period of time in milliseconds. More...
 
palStatus_t pal_plat_osTimerCreate (palTimerFuncPtr function, void *funcArgument, palTimerType_t timerType, palTimerID_t *timerID)
 Create a timer. More...
 
palStatus_t pal_plat_osTimerStart (palTimerID_t timerID, uint32_t millisec)
 Start or restart a timer. More...
 
palStatus_t pal_plat_osTimerStop (palTimerID_t timerID)
 Stop a timer. More...
 
palStatus_t pal_plat_osTimerDelete (palTimerID_t *timerID)
 Delete the timer object. More...
 
palStatus_t pal_plat_osMutexCreate (palMutexID_t *mutexID)
 Create and initialize a mutex object. More...
 
palStatus_t pal_plat_osMutexWait (palMutexID_t mutexID, uint32_t millisec)
 Wait until a mutex becomes available. More...
 
palStatus_t pal_plat_osMutexRelease (palMutexID_t mutexID)
 Release a mutex that was obtained by osMutexWait. More...
 
palStatus_t pal_plat_osMutexDelete (palMutexID_t *mutexID)
 Delete a mutex object. More...
 
palStatus_t pal_plat_osSemaphoreCreate (uint32_t count, palSemaphoreID_t *semaphoreID)
 Create and initialize a semaphore object. More...
 
palStatus_t pal_plat_osSemaphoreWait (palSemaphoreID_t semaphoreID, uint32_t millisec, int32_t *countersAvailable)
 Wait until a semaphore token becomes available. More...
 
palStatus_t pal_plat_osSemaphoreRelease (palSemaphoreID_t semaphoreID)
 Release a semaphore token. More...
 
palStatus_t pal_plat_osSemaphoreDelete (palSemaphoreID_t *semaphoreID)
 Delete a semaphore object. More...
 
int32_t pal_plat_osAtomicIncrement (int32_t *valuePtr, int32_t increment)
 Perform an atomic increment for a signed 32-bit value. More...
 
void * pal_plat_malloc (size_t len)
 Perform allocation from the heap according to the OS specification. More...
 
void pal_plat_free (void *buffer)
 Free memory back to the OS heap. More...
 
palStatus_t pal_plat_osGetRoTFromHW (uint8_t *keyBuf, size_t keyLenBytes)
 Retrieve platform Root of Trust (RoT) certificate. More...
 
palStatus_t pal_plat_osSetRtcTime (uint64_t rtcSetTime)
 This function calls the platform layer and sets the new real-time clock (RTC) to the hardware. More...
 
palStatus_t pal_plat_osGetRtcTime (uint64_t *rtcGetTime)
 This function gets the real-time clock (RTC) from the platform. More...
 
palStatus_t pal_plat_rtcDeInit (void)
 This function deinitializes the realt-time clock (RTC) module. More...
 
palStatus_t pal_plat_rtcInit (void)
 This function initializes the real-time clock (RTC) module. More...
 

Detailed Description

PAL RTOS - platform. This file contains the real-time OS APIs that need to be implemented in the platform layer.

Function Documentation

void pal_plat_free ( void *  buffer)

Free memory back to the OS heap.

Parameters
[in]bufferA pointer to the buffer that should be freed.
Returns
void
void* pal_plat_malloc ( size_t  len)

Perform allocation from the heap according to the OS specification.

Parameters
[in]lenThe length of the buffer to be allocated in bytes.
Returns
void *, or the pointer of the malloc received from the OS if NULL error occurred
void pal_plat_osApplicationReboot ( void  )

Application provided implementation to replace default pal_osReboot() functionality.

int32_t pal_plat_osAtomicIncrement ( int32_t *  valuePtr,
int32_t  increment 
)

Perform an atomic increment for a signed 32-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
PAL_SUCCESS(0) in case of success. A negative value indicating a specific error code in case of failure.
palStatus_t pal_plat_osGetRoTFromHW ( uint8_t *  keyBuf,
size_t  keyLenBytes 
)

Retrieve platform Root of Trust (RoT) certificate.

Parameters
[in,out]keyBufA pointer to the buffer that holds the RoT.
[in]keyLenBytesThe size of the buffer to hold the 128 bit key, must be at least 16 bytes.
Returns
PAL_SUCCESS(0) in case of success. A negative value indicating a specific error code in case of failure.
palStatus_t pal_plat_osGetRtcTime ( uint64_t *  rtcGetTime)

This function gets the real-time clock (RTC) from the platform.

Parameters
[out]rtcGetTime- Holds the RTC value
Returns
PAL_SUCCESS when the RTC is returned correctly
uint64_t pal_plat_osKernelSysTick ( void  )

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.
If the platform supports 64-bit tick counter, please implement it. If the platform supports only 32 bit, note that this counter wraps around very often, once every 42 sec for 100Mhz, for example.
uint64_t pal_plat_osKernelSysTickFrequency ( void  )

Get the system tick frequency.

Returns
The system tick frequency.
Note
The system tick frequency MUST be more than 1KHz, so at least one tick per millisecond.
uint64_t pal_plat_osKernelSysTickMicroSec ( uint64_t  microseconds)

Convert the value from microseconds to kernel system ticks.

This is the same as CMSIS macro osKernelSysTickMicroSec.

Parameters
microsecondsThe value in microseconds to be converted to kernel system ticks.
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 when there is no memory resource available to create a mutex object.
Note
The create function MUST NOT wait for the platform resources and it should return PAL_ERR_RTOS_RESOURCE, unless the platform API is blocking.
By default, the mutex is created with a recursive flag set.
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, mutexID 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
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 mutex is released, an error is returned from the function.
Returns
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 - The mutex ID is invalid.
  • PAL_ERR_RTOS_ISR - Cannot be called from interrupt service routines.
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 a semaphore object.
Note
The create function MUST not wait for the 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. On 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 semaphoreID 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
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, an error is returned from the function.
[out]countersAvailableThe number of semaphores available. If semaphores are not available due to timeout or error, zero is returned.
Returns
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_osSetRtcTime ( uint64_t  rtcSetTime)

This function calls the platform layer and sets the new real-time clock (RTC) to the hardware.

Parameters
[in]rtcSetTimethe new RTC time
Returns
PAL_SUCCESS when the RTC is returned correctly.
palStatus_t pal_plat_osThreadCreate ( palThreadFuncPtr  function,
void *  funcArgument,
palThreadPriority_t  priority,
uint32_t  stackSize,
palThreadID_t threadID 
)

Create and run the thread.

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 bytes, can NOT be 0.
[out]threadIDThe created thread ID handle. In case of error, this value is NULL.
Returns
PAL_SUCCESS(0) in case of success. A negative value indicating a specific error code in case of failure.
palThreadID_t pal_plat_osThreadGetId ( void  )

Get the ID of the current thread.

Returns
The ID of the current thread. In case of error, returns PAL_MAX_UINT32.
palStatus_t pal_plat_osThreadTerminate ( palThreadID_t threadID)

Terminate and free allocated data for the thread.

Parameters
[in]threadIDA pointer to a palThreadData_t structure containing information about the thread.
Returns
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 a 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. on success, timerID = NULL.
Returns
PAL_SUCCESS when the timer was deleted successfully. PAL_ERR_RTOS_PARAMETER when the timerID is incorrect.
Note
In case of a running timer, pal_plat_osTimerDelete() MUST stop the timer before deletion.
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, MUST be larger than 0. In case the value is 0, the error PAL_ERR_RTOS_VALUE will be returned.
Returns
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
PAL_SUCCESS(0) in case of success. A negative value indicating a specific error code in case of failure.
palStatus_t pal_plat_rtcDeInit ( void  )

This function deinitializes the realt-time clock (RTC) module.

Returns
PAL_SUCCESS when the success or error upon failing
palStatus_t pal_plat_rtcInit ( void  )

This function initializes the real-time clock (RTC) module.

Returns
PAL_SUCCESS when the success or error upon failing
palStatus_t 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 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.