PAL RTOS. This file contains the real-time OS APIs and is a part of the PAL service API. More...

#include <stdint.h>
#include <string.h>
#include "pal.h"

Data Structures
struct	pal_threadLocalStore
	Thread local store struct. More...

struct	pal_timeVal

Macros
#define	PAL_TICK_TO_MILLI_FACTOR 1000
	Wait forever define. Used for semaphores and mutexes. More...

Typedefs
typedef uintptr_t	palThreadID_t
	Primitive ID type declarations. More...

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

typedef enum palTimerType	palTimerType_t
	Timer types supported in PAL. More...

typedef void(*	palTimerFuncPtr) (void const *funcArgument)
	PAL timer function prototype. More...

typedef void(*	palThreadFuncPtr) (void const *funcArgument)
	PAL thread function prototype. More...

typedef enum pal_osPriority	palThreadPriority_t
	Thread priority levels for PAL threads - each thread must have a different priority. More...

typedef struct pal_threadLocalStore	palThreadLocalStore_t
	Thread local store struct. More...

typedef struct pal_timeVal	pal_timeVal_t

Enumerations
enum	palTimerType { palOsTimerOnce = 0, palOsTimerPeriodic = 1 }
	Timer types supported in PAL. More...

enum	pal_osPriority { PAL_osPriorityFirst = 0, PAL_osPriorityIdle = PAL_osPriorityFirst, PAL_osPriorityLow = 1, PAL_osPriorityReservedTRNG = 2, PAL_osPriorityBelowNormal = 3, PAL_osPriorityNormal = 4, PAL_osPriorityAboveNormal = 5, PAL_osPriorityReservedDNS = 6, PAL_osPriorityReservedSockets = 7, PAL_osPriorityHigh = 8, PAL_osPriorityReservedHighResTimer = 9, PAL_osPriorityRealtime = 10, PAL_osPrioritylast = PAL_osPriorityRealtime, PAL_osPriorityError = 0x84 }
	Available priorities in PAL implementation, each priority can appear only once. More...

Functions
void	pal_osReboot (void)
	Initiates a system reboot. More...

uint64_t	pal_osKernelSysTick (void)
	Get the RTOS kernel system timer counter. More...

uint64_t	pal_osKernelSysTickMicroSec (uint64_t microseconds)
	Converts a value from microseconds to kernel system ticks. More...

uint64_t	pal_osKernelSysMilliSecTick (uint64_t sysTicks)
	Converts kernel system ticks to milliseconds. More...

uint64_t	pal_osKernelSysTickFrequency (void)
	Get the system tick frequency. More...

palStatus_t	pal_osThreadCreateWithAlloc (palThreadFuncPtr function, void funcArgument, palThreadPriority_t priority, uint32_t stackSize, palThreadLocalStore_t store, palThreadID_t *threadID)
	Allocates memory for the thread stack, creates and starts the thread function inside the PAL platform wrapper function. More...

palStatus_t	pal_osThreadTerminate (palThreadID_t *threadID)
	Terminate the thread and free the data allocated for it. More...

palThreadID_t	pal_osThreadGetId (void)
	Get the ID of the current thread. More...

palStatus_t	pal_osDelay (uint32_t milliseconds)
	Wait for a specified time period in milliseconds. More...

palStatus_t	pal_osTimerCreate (palTimerFuncPtr function, void funcArgument, palTimerType_t timerType, palTimerID_t timerID)
	Create a timer. More...

palStatus_t	pal_osTimerStart (palTimerID_t timerID, uint32_t millisec)
	Start or restart a timer. More...

palStatus_t	pal_osTimerStop (palTimerID_t timerID)
	Stop a timer. More...

palStatus_t	pal_osTimerDelete (palTimerID_t *timerID)
	Delete a timer object. More...

palStatus_t	pal_osMutexCreate (palMutexID_t *mutexID)
	Create and initialize a mutex object. More...

palStatus_t	pal_osMutexWait (palMutexID_t mutexID, uint32_t millisec)
	Wait until a mutex becomes available. More...

palStatus_t	pal_osMutexRelease (palMutexID_t mutexID)
	Release a mutex that was obtained by `osMutexWait`. More...

palStatus_t	pal_osMutexDelete (palMutexID_t *mutexID)
	Delete a mutex object. More...

palStatus_t	pal_osSemaphoreCreate (uint32_t count, palSemaphoreID_t *semaphoreID)
	Create and initialize a semaphore object. More...

palStatus_t	pal_osSemaphoreWait (palSemaphoreID_t semaphoreID, uint32_t millisec, int32_t *countersAvailable)
	Wait until a semaphore token becomes available. More...

palStatus_t	pal_osSemaphoreRelease (palSemaphoreID_t semaphoreID)
	Release a semaphore token. More...

palStatus_t	pal_osSemaphoreDelete (palSemaphoreID_t *semaphoreID)
	Delete a semaphore object. More...

int32_t	pal_osAtomicIncrement (int32_t *valuePtr, int32_t increment)
	Perform an atomic increment for a signed 32-bit value. More...

palStatus_t	pal_RTOSInitialize (void *opaqueContext)

palStatus_t	pal_RTOSDestroy (void)

Detailed Description

PAL RTOS. This file contains the real-time OS APIs and is a part of the PAL service API.

Random API is also provided. as well as random API and ROT (root of trust).

Macro Definition Documentation

#define PAL_TICK_TO_MILLI_FACTOR 1000

Wait forever define. Used for semaphores and mutexes.

Typedef Documentation

typedef struct pal_timeVal pal_timeVal_t

typedef uintptr_t palMemoryPoolID_t

typedef uintptr_t palMessageQID_t

typedef uintptr_t palMutexID_t

typedef uintptr_t palSemaphoreID_t

typedef void(* palThreadFuncPtr) (void const *funcArgument)

PAL thread function prototype.

typedef uintptr_t palThreadID_t

Primitive ID type declarations.

typedef struct pal_threadLocalStore palThreadLocalStore_t

Thread local store struct.

Can be used to hold, for example, state and configurations inside the thread.

typedef enum pal_osPriority palThreadPriority_t

Thread priority levels for PAL threads - each thread must have a different priority.

typedef void(* palTimerFuncPtr) (void const *funcArgument)

PAL timer function prototype.

typedef uintptr_t palTimerID_t

typedef enum palTimerType palTimerType_t

Timer types supported in PAL.

Enumeration Type Documentation

enum pal_osPriority

Available priorities in PAL implementation, each priority can appear only once.

Enumerator
PAL_osPriorityFirst
PAL_osPriorityIdle
PAL_osPriorityLow
PAL_osPriorityReservedTRNG
PAL_osPriorityBelowNormal
PAL_osPriorityNormal
PAL_osPriorityAboveNormal
PAL_osPriorityReservedDNS	Reserved for PAL's internal use
PAL_osPriorityReservedSockets	Reserved for PAL's internal use
PAL_osPriorityHigh
PAL_osPriorityReservedHighResTimer	Reserved for PAL's internal use
PAL_osPriorityRealtime
PAL_osPrioritylast
PAL_osPriorityError

enum palTimerType

Timer types supported in PAL.

Enumerator
palOsTimerOnce	One-shot timer.
palOsTimerPeriodic	Periodic (repeating) timer.

Function Documentation

int32_t pal_osAtomicIncrement	(	int32_t *	valuePtr,
		int32_t	increment
	)

Perform an atomic increment for a signed 32-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 valuePtr after the increment operation.

palStatus_t pal_osDelay ( uint32_t milliseconds )

Wait for a specified time period in milliseconds.

Parameters

[in] milliseconds The number of milliseconds to wait before proceeding.

Returns: PAL_SUCCESS(0) in case of success, and a negative value indicating a specific error code in case of failure.

uint64_t pal_osKernelSysMilliSecTick ( uint64_t sysTicks )

Converts kernel system ticks to milliseconds.

Parameters

[in] sysTicks The number of kernel system ticks to convert into milliseconds.

Returns: Converted value in milliseconds.

uint64_t pal_osKernelSysTick ( void )

Get the RTOS kernel system timer counter.

Note: The system needs to supply a 64-bit tick counter. If only a 32-bit counter is supported, the counter wraps around very often (for example, once every 42 sec for 100Mhz).

Returns: The RTOS kernel system timer counter.

uint64_t pal_osKernelSysTickFrequency ( void )

Get the system tick frequency.

Returns: The system tick frequency.

Note: The system tick frequency MUST be more than 1KHz. In other words, there must be at least one tick per millisecond.

uint64_t pal_osKernelSysTickMicroSec ( uint64_t microseconds )

Converts a value from microseconds to kernel system ticks.

Parameters

[in] microseconds The number of microseconds to convert into system ticks.

Returns: Converted value in system ticks.

palStatus_t pal_osMutexCreate ( palMutexID_t * mutexID )

Create and initialize a mutex object.

Parameters

[out] mutexID The created mutex ID handle. In case of error, this value is NULL.

Returns: PAL_SUCCESS when the mutex was created successfully.; PAL_ERR_NO_MEMORY when there is no memory resource available to create a mutex object.

palStatus_t pal_osMutexDelete ( palMutexID_t * mutexID )

Delete a mutex object.

Parameters

[in,out] mutexID The mutex handle to delete. On success, *mutexID is changed to NULL.

Returns: PAL_SUCCESS when the mutex was deleted successfully.; PAL_ERR_RTOS_RESOURCE Failure - mutex is already released.; PAL_ERR_RTOS_PARAMETER Failure - mutex ID is invalid.; PAL_ERR_RTOS_ISR Failure - cannot be called from the interrupt service routines.

Note: After this call, the mutexID is no longer valid and cannot be used.

palStatus_t pal_osMutexRelease ( palMutexID_t mutexID )

Release a mutex that was obtained by osMutexWait.

Parameters

[in] mutexID The handle for the mutex.

Returns: PAL_SUCCESS(0) in case of success, or another negative value indicating a specific error code in case of failure.

palStatus_t pal_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 waiting for the mutex to be available. PAL_RTOS_WAIT_FOREVER can be used as a parameter.

Returns: PAL_SUCCESS(0) in case of success.; PAL_ERR_RTOS_RESOURCE Failure - mutex was not availabe but no timeout was set.; PAL_ERR_RTOS_TIMEOUT Failure - mutex was not available before timeout.; PAL_ERR_RTOS_PARAMETER Failure - mutex ID is invalid.; PAL_ERR_RTOS_ISR Failure - cannot be called from the interrupt service routines.

void pal_osReboot ( void )

Initiates a system reboot.

Applications can provide their own implementation by defining PAL_USE_APPLICATION_REBOOT and providing the implementation for pal_plat_osApplicationReboot() function.

palStatus_t pal_osSemaphoreCreate	(	uint32_t	count,
		palSemaphoreID_t *	semaphoreID
	)

Create and initialize a semaphore object.

Parameters

[in]	count	The number of available resources.
[out]	semaphoreID	The created semaphore ID handle. In case of error, this value is `NULL`.

Returns: PAL_SUCCESS when the semaphore was created successfully.; PAL_ERR_NO_MEMORY when there is no memory resource available to create a semaphore object.

palStatus_t pal_osSemaphoreDelete ( palSemaphoreID_t * semaphoreID )

Delete a semaphore object.

Parameters

[in,out] semaphoreID The semaphore handle to delete. On success, *semaphoreID is changed to NULL.

Returns: PAL_SUCCESS when the semaphore was deleted successfully.; PAL_ERR_RTOS_RESOURCE Failure - the semaphore was already released.; PAL_ERR_RTOS_PARAMETER Failure - the semaphore ID is invalid.

Note: After this call, the semaphoreID is no longer valid and cannot be used.

palStatus_t pal_osSemaphoreRelease ( palSemaphoreID_t semaphoreID )

Release a semaphore token.

Parameters

[in] semaphoreID The handle for the semaphore

Returns: PAL_SUCCESS(0) in case of success, or a negative value indicating a specific error code in case of failure.

palStatus_t pal_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, an error is returned from the function. PAL_RTOS_WAIT_FOREVER can be used.
[out]	countersAvailable	The number of semaphores available at the call if a semaphore is available. If the semaphore is not available due to timeout or error, `0` is returned. This parameter can be NULL

Returns: PAL_SUCCESS(0) in case of success.; PAL_ERR_RTOS_TIMEOUT Failure - the semaphore was not available until timeout.; PAL_ERR_RTOS_PARAMETER Failure - the semaphore ID is invalid.

palStatus_t pal_osThreadCreateWithAlloc	(	palThreadFuncPtr	function,
		void *	funcArgument,
		palThreadPriority_t	priority,
		uint32_t	stackSize,
		palThreadLocalStore_t *	store,
		palThreadID_t *	threadID
	)

Allocates memory for the thread stack, creates and starts the thread function inside the PAL platform wrapper 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, can NOT be 0.
[in]	store	MUST be `NULL` - this functionality is not supported.
[out]	threadID	The created thread ID handle. In case of error, this value is `NULL`.

Returns: PAL_SUCCESS when the thread was created successfully.

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.; Calling pal_osThreadTerminate() releases the thread stack.

palThreadID_t pal_osThreadGetId ( void )

Get the ID of the current thread.

Returns: The ID of the current thread.; PAL_MAX_UINT32 in case of error.

palStatus_t pal_osThreadTerminate ( palThreadID_t * threadID )

Terminate the thread and free the data allocated for it.

Parameters

[in] threadID The thread ID to stop and terminate.

Returns: PAL_SUCCESS(0) in case of success, and a negative value indicating a specific error code in case of failure.

Note: pal_osThreadTerminate is a non-blocking operation. It sends a cancellation request to the thread, and usually the thread exits immediately, but the system does not always guarantee this.

palStatus_t pal_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, either periodic or one-shot.
[out]	timerID	The ID handle for the created timer. In case of error, this value is `NULL`.

Returns: PAL_SUCCESS when the timer was created successfully.; PAL_ERR_NO_MEMORY when there is no memory resource available to create a timer object.

Note: The timer function runs according to the platform resources of stack-size and priority.

palStatus_t pal_osTimerDelete ( palTimerID_t * timerID )

Delete a timer object.

Parameters

[in,out] timerID The ID handle for the timer to delete. On success, *timerID is changed to NULL.

Returns: PAL_SUCCESS when timer was deleted successfully.; PAL_ERR_RTOS_PARAMETER when the timerID is incorrect.

palStatus_t pal_osTimerStart	(	palTimerID_t	timerID,
		uint32_t	millisec
	)

Start or restart a timer.

Parameters

[in]	timerID	The ID handle for the timer to start or restart.
[in]	millisec	The length of time in milliseconds to set the timer to. MUST be larger than 0.

Returns: PAL_ERR_RTOS_VALUE In case the value of millisec was 0 .; PAL_SUCCESS(0) in case of success, and a negative value indicating a specific error code in case of failure.

palStatus_t pal_osTimerStop ( palTimerID_t timerID )

Stop a timer.

Parameters

[in] timerID The ID handle for the timer to stop.

Returns: PAL_SUCCESS(0) in case of success, and a negative value indicating a specific error code in case of failure.

palStatus_t pal_RTOSDestroy ( void )

This function removes PAL from the system and can be called after pal_RTOSInitialize.

Returns: PAL_SUCCESS upon success.
PAL_ERR_NOT_INITIALIZED - if the user did not call pal_RTOSInitialize() first.

palStatus_t pal_RTOSInitialize ( void * opaqueContext )

Initialize the RTOS module for PAL. This function can be called only once before running the system. To remove PAL from the system, call pal_RTOSDestroy. After calling pal_RTOSDestroy, you can call pal_RTOSInitialize again.

Parameters

[in] opaqueContext context to be passed to the platform if needed.

Returns: PAL_SUCCESS upon success.

Documentation

Data Structures

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

Typedef Documentation

Enumeration Type Documentation

Function Documentation