PAL RTOS. This file contains the real-time OS APIs and is a part of the PAL service API. It provides thread, timers, semaphores, mutexes and memory pool management APIs. Random API and ROT (root of trust) are also provided. More...

Data Structures
struct	pal_threadLocalStore
	Thread local store struct. More...
Typedefs
typedef uintptr_t	palThreadID_t
	Primitive ID type declarations.
typedef enum palTimerType	palTimerType_t
	Timer types supported in PAL.
typedef enum palDeviceKeyType	palDevKeyType_t
	Device key types supported in PAL.
typedef void(*	palTimerFuncPtr )(void const *funcArgument)
	PAL timer function prototype.
typedef void(*	palThreadFuncPtr )(void const *funcArgument)
	PAL thread function prototype.
typedef enum pal_osPriority	palThreadPriority_t
	Available priorities in PAL implementation, each priority can appear only once.
typedef struct pal_threadLocalStore	palThreadLocalStore_t
	Thread local store struct.
Enumerations
enum	palTimerType { , palOsTimerPeriodic = 1 }
	Timer types supported in PAL. More...
enum	palDeviceKeyType { , palOsStorageSignatureKey128Bit = 1, palOsStorageHmacSha256 = 2 }
	Device key types supported in PAL. More...
enum	pal_osPriority { , PAL_osPriorityReservedSockets = 7, PAL_osPriorityHigh = 8 , PAL_osPriorityRealtime = 10 }
	Available priorities in PAL implementation, each priority can appear only once. More...
Functions
void	pal_osReboot (void)
uint64_t	pal_osKernelSysTick (void)
uint64_t	pal_osKernelSysTickMicroSec (uint64_t microseconds)
uint64_t	pal_osKernelSysMilliSecTick (uint64_t sysTicks)
uint64_t	pal_osKernelSysTickFrequency (void)
uint64_t	pal_osGetTime (void)
palStatus_t	pal_osSetTime (uint64_t seconds)
	Set the current system time by accepting seconds since January 1st 1970 UTC+0.
palStatus_t	pal_initTime (void)
	Initialization the time module After boot, the time in RAM will be initialized with the max value between RTC and SOTP SAVED_TIME. If no RTC is present, RTC time is zero. After initialization the time module will start counting ticks. The answer to get_time should be calculated by the sum of the initial value (RTC or SOTP) + the number of ticks converted into seconds.
palStatus_t	pal_osSetWeakTime (uint64_t setTimeInSeconds)
	save weak time according to design Time Forward (a) set the time (in RAM) unconditionally. Save the new time in SOTP if the change (between new time and current time in RAM) is greater than 24 hours. Set the time to RTC if the change is greater than 100 seconds. This limitation is to avoid multiple writes to the SOTP and RTC and not related to security. Time Forward (b) If (a) did not happen, save the time into SOTP if new time is greater from SAVED_TIME by a week (604800 seconds). Time Backwards set the device time on the device (RAM) and save the time in SOTP only if the change (between new time and current time in RAM) is smaller than 3 minutes for each day lapsed from the last change done via pal_osWeakSetTime. RTC is never set backwards by pal_osWeakSetTime().
palStatus_t	pal_osSetStrongTime (uint64_t setTimeInSeconds)
	save strong time according to design Set the time (in RAM) unconditionally. Save in SOTP or/and RTC the new time under the following conditions: • Time forward – if time difference between current time in SOTP (not device time) and new time is greater than a day • Time backward – if time difference between current time and new time is greater than one minute. If the time is saved in SOTP (forward or backwards), the record LAST_TIME_BACK must be saved.
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).
palStatus_t	pal_osThreadTerminate (palThreadID_t *threadID)
palThreadID_t	pal_osThreadGetId (void)
palStatus_t	pal_osDelay (uint32_t milliseconds)
palStatus_t	pal_osTimerCreate (palTimerFuncPtr function, void funcArgument, palTimerType_t timerType, palTimerID_t timerID)
palStatus_t	pal_osTimerStart (palTimerID_t timerID, uint32_t millisec)
palStatus_t	pal_osTimerStop (palTimerID_t timerID)
palStatus_t	pal_osTimerDelete (palTimerID_t *timerID)
palStatus_t	pal_osMutexCreate (palMutexID_t *mutexID)
palStatus_t	pal_osMutexWait (palMutexID_t mutexID, uint32_t millisec)
palStatus_t	pal_osMutexRelease (palMutexID_t mutexID)
palStatus_t	pal_osMutexDelete (palMutexID_t *mutexID)
palStatus_t	pal_osSemaphoreCreate (uint32_t count, palSemaphoreID_t *semaphoreID)
palStatus_t	pal_osSemaphoreWait (palSemaphoreID_t semaphoreID, uint32_t millisec, int32_t *countersAvailable)
palStatus_t	pal_osSemaphoreRelease (palSemaphoreID_t semaphoreID)
palStatus_t	pal_osSemaphoreDelete (palSemaphoreID_t *semaphoreID)
int32_t	pal_osAtomicIncrement (int32_t *valuePtr, int32_t increment)
palStatus_t	pal_osRandomBuffer (uint8_t *randomBuf, size_t bufSizeBytes)
palStatus_t	pal_osGetDeviceKey (palDevKeyType_t keyType, uint8_t *key, size_t keyLenBytes)
palStatus_t	pal_RTOSInitialize (void *opaqueContext)
palStatus_t	pal_RTOSDestroy (void)
palStatus_t	pal_osRandom32bit (uint32_t *random)

Detailed Description

PAL RTOS. This file contains the real-time OS APIs and is a part of the PAL service API. It provides thread, timers, semaphores, mutexes and memory pool management APIs. Random API and ROT (root of trust) are also provided.

Definition in file pal_rtos.h.

Typedef Documentation

typedef enum palDeviceKeyType palDevKeyType_t

Device key types supported in PAL.

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

PAL thread function prototype.

Definition at line 73 of file pal_rtos.h.

typedef uintptr_t palThreadID_t

Primitive ID type declarations.

Definition at line 47 of file pal_rtos.h.

typedef struct pal_threadLocalStore palThreadLocalStore_t

Thread local store struct.

Thread priority levels for PAL threads - each thread must have a different priority. Can be used to hold for example state and configurations inside the thread.

typedef enum pal_osPriority palThreadPriority_t

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

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

PAL timer function prototype.

Definition at line 70 of file pal_rtos.h.

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_osPriorityReservedSockets	Reserved for PAL's internal use
PAL_osPriorityHigh	Reserved for PAL's internal use
PAL_osPriorityRealtime	Reserved for PAL's internal use

Definition at line 76 of file pal_rtos.h.

enum palDeviceKeyType

Device key types supported in PAL.

Enumerator:

palOsStorageSignatureKey128Bit	128bit storage encryption key derived from RoT.
palOsStorageHmacSha256	128bit storage signature key derived from RoT.

Definition at line 63 of file pal_rtos.h.

enum palTimerType

Timer types supported in PAL.

Enumerator:

palOsTimerPeriodic

One shot timer.

Definition at line 55 of file pal_rtos.h.

Function Documentation

palStatus_t pal_initTime ( void )

Initialization the time module After boot, the time in RAM will be initialized with the max value between RTC and SOTP SAVED_TIME. If no RTC is present, RTC time is zero. After initialization the time module will start counting ticks. The answer to get_time should be calculated by the sum of the initial value (RTC or SOTP) + the number of ticks converted into seconds.

Returns:: PAL_SUCCESS when initialization succeed.

Note:

Definition at line 709 of file pal_rtos.c.

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.

Definition at line 364 of file pal_rtos.c.

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.

Definition at line 256 of file pal_rtos.c.

palStatus_t pal_osGetDeviceKey	(	palDevKeyType_t	keyType,
		uint8_t *	key,
		size_t	keyLenBytes
	)

Return a device unique key derived from the root of trust.

Parameters:

[in]	keyType	The type of key to derive.
[in,out]	key	A 128-bit OR 256-bit buffer to hold the derived key, size is defined according to the `keyType`.
[in]	keyLenBytes	The size of buffer to hold the 128-bit OR 256-bit key.

Returns:: PAL_SUCCESS in case of success and one of the following error codes in case of failure:
PAL_ERR_GET_DEV_KEY - an error in key derivation.

Definition at line 635 of file pal_rtos.c.

uint64_t pal_osGetTime ( void )

Get the system time.

Returns:: The system 64-bit counter indicating the current system time in seconds on success. Zero value when the time is not set in the system.

Note:: If the delta between secure time value previously set in the system and current system time is greater than PAL_LAST_SAVED_TIME_LATENCY_SEC then secure time value will be overridden with current system time

Definition at line 381 of file pal_rtos.c.

uint64_t pal_osKernelSysMilliSecTick ( uint64_t sysTicks )

Converts value from kernel system ticks to milliseconds.

Parameters:

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

Returns:: Converted value in system milliseconds.

Definition at line 212 of file pal_rtos.c.

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.

Definition at line 188 of file pal_rtos.c.

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 (at least one tick per millisecond).

Definition at line 224 of file pal_rtos.c.

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.

Definition at line 205 of file pal_rtos.c.

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.

Definition at line 299 of file pal_rtos.c.

palStatus_t pal_osMutexDelete ( palMutexID_t * mutexID )

Delete a mutex object.

Parameters:

inout] mutexID The mutex handle to delete. In success, `*mutexID` = NULL.

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

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

Definition at line 323 of file pal_rtos.c.

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 and another negative value indicating a specific error code in case of failure.

Definition at line 315 of file pal_rtos.c.

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

Returns:: PAL_SUCCESS(0) in case of success or one of the following error codes in case of failure:
PAL_ERR_RTOS_RESOURCE - mutex was not availabe but no timeout was set.
PAL_ERR_RTOS_TIMEOUT - mutex was not available until the timeout.
PAL_ERR_RTOS_PARAMETER - mutex ID is invalid.
PAL_ERR_RTOS_ISR - cannot be called from the interrupt service routines.

Definition at line 307 of file pal_rtos.c.

palStatus_t pal_osRandom32bit ( uint32_t * random )

Generate a 32-bit random number.

Parameters:

[out] random A 32-bit buffer to hold the generated number.

Note:: `pal_init()` MUST be called before this function.

Returns:: PAL_SUCCESS on success, a negative value indicating a specific error code in case of failure.

Definition at line 599 of file pal_rtos.c.

palStatus_t pal_osRandomBuffer	(	uint8_t *	randomBuf,
		size_t	bufSizeBytes
	)

Generate random number into given buffer with given size in bytes.

Parameters:

[out]	randomBuf	A buffer to hold the generated number.
[in]	bufSizeBytes	The size of the buffer and the size of the required random number to generate.

Note:: `pal_init()` MUST be called before this function

Returns:: PAL_SUCCESS on success, a negative value indicating a specific error code in case of failure.

Definition at line 468 of file pal_rtos.c.

void pal_osReboot ( void )

Initiates a system reboot. Application can provide their own implementation by defining PAL_USE_APPLICATION_REBOOT and providing implementation for pal_plat_osApplicationReboot() function.

Definition at line 163 of file pal_rtos.c.

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.

Definition at line 331 of file pal_rtos.c.

palStatus_t pal_osSemaphoreDelete ( palSemaphoreID_t * semaphoreID )

Delete a semaphore object.

Parameters:

inout] semaphoreID The semaphore handle to delete. In success, `*semaphoreID` = NULL.

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

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

Definition at line 355 of file pal_rtos.c.

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 and a negative value indicating a specific error code in case of failure.

Definition at line 347 of file pal_rtos.c.

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 and 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 (timeout/error) zero is returned. This parameter can be NULL

Returns:: PAL_SUCCESS(0) in case of success and one of the following error codes in case of failure:
PAL_ERR_RTOS_TIMEOUT - the semaphore was not available until timeout.
PAL_ERR_RTOS_PARAMETER - the semaphore ID is invalid.

Definition at line 339 of file pal_rtos.c.

palStatus_t pal_osSetStrongTime ( uint64_t setTimeInSeconds )

save strong time according to design Set the time (in RAM) unconditionally. Save in SOTP or/and RTC the new time under the following conditions: • Time forward – if time difference between current time in SOTP (not device time) and new time is greater than a day • Time backward – if time difference between current time and new time is greater than one minute. If the time is saved in SOTP (forward or backwards), the record LAST_TIME_BACK must be saved.

Parameters:

[in] uint64_t setTimeInSeconds - Seconds from January 1st 1970 UTC+0.

Returns:: PAL_SUCCESS when set strong succeed.

Note:: The limitations are aimed to reduce the number of write operations to the SOTP and not related to security. This function will be called when receiving time from a server that is completely trusted.

Definition at line 763 of file pal_rtos.c.

palStatus_t pal_osSetTime ( uint64_t seconds )

Set the current system time by accepting seconds since January 1st 1970 UTC+0.

Parameters:

[in] seconds Seconds from January 1st 1970 UTC+0.

Returns:: PAL_SUCCESS when the time was set successfully.
PAL_ERR_INVALID_TIME when there is a failure setting the system time.

Definition at line 408 of file pal_rtos.c.

palStatus_t pal_osSetWeakTime ( uint64_t setTimeInSeconds )

save weak time according to design Time Forward (a) set the time (in RAM) unconditionally. Save the new time in SOTP if the change (between new time and current time in RAM) is greater than 24 hours. Set the time to RTC if the change is greater than 100 seconds. This limitation is to avoid multiple writes to the SOTP and RTC and not related to security. Time Forward (b) If (a) did not happen, save the time into SOTP if new time is greater from SAVED_TIME by a week (604800 seconds). Time Backwards set the device time on the device (RAM) and save the time in SOTP only if the change (between new time and current time in RAM) is smaller than 3 minutes for each day lapsed from the last change done via pal_osWeakSetTime. RTC is never set backwards by pal_osWeakSetTime().

Parameters:

[in] uint64_t setTimeInSeconds Seconds from January 1st 1970 UTC+0.

Returns:: PAL_SUCCESS when set weak succeed.

Note:: To implement this, when the new time is saved in SOTP by the function pal_osWeakSetTime two records with different types must be saved in SOTP:; 1.- The new time (the same record as in factory setup); 2.- The time this action was performed, in order to enforce the 24 hours limitation. Record LAST_TIME_BACK.

Definition at line 904 of file pal_rtos.c.

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.

Definition at line 231 of file pal_rtos.c.

palThreadID_t pal_osThreadGetId ( void )

Get the ID of the current thread.

Returns:: The ID of the current thread. In case of error, return PAL_MAX_UINT32.

Definition at line 250 of file pal_rtos.c.

palStatus_t pal_osThreadTerminate ( palThreadID_t * threadID )

Terminate and free allocated data for the thread.

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, pal_osThreadTerminate sends cancellation request to the thread, usually the thread exits immediately, but the system does not always guarantee this

Definition at line 243 of file pal_rtos.c.

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, periodic or oneShot.
[out]	timerID	The created timer ID handle. 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.

Definition at line 263 of file pal_rtos.c.

palStatus_t pal_osTimerDelete ( palTimerID_t * timerID )

Delete the timer object.

Parameters:

inout] timerID The handle for the timer to delete. In success, `*timerID` = NULL.

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

Definition at line 291 of file pal_rtos.c.

palStatus_t pal_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 amount of time in milliseconds to set the timer to. MUST be larger than 0. In case of 0 value, the error PAL_ERR_RTOS_VALUE is returned.

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

Definition at line 271 of file pal_rtos.c.

palStatus_t pal_osTimerStop ( palTimerID_t timerID )

Stop a timer.

Parameters:

[in] timerID The 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.

Definition at line 283 of file pal_rtos.c.

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.

Definition at line 127 of file pal_rtos.c.

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.

Definition at line 100 of file pal_rtos.c.

Type:	Program
Mbed OS support:	Mbed OS
Created:	25 Oct 2018
Imports:	1
Forks:	0
Commits:	5
Dependents:	0
Dependencies:	1
Followers:	1

pal_rtos.h File Reference

Data Structures

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

Enumeration Type Documentation

Function Documentation

Repository toolbox

Repository details

Important Information for this Arm website

pal_rtos.h File Reference

Data Structures

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

Enumeration Type Documentation

Function Documentation

Repository toolbox

Repository details

Important Information for this Arm website

Access Warning