Simple interface for Mbed Cloud Client
pal_rtos.h File Reference
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...
Go to the source code of this file.
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) |
palThreadLocalStore_t * | pal_osThreadGetLocalStore (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.
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 1122 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 775 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 667 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 1048 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 792 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 268 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 244 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 280 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 261 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 710 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 734 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 726 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 718 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 1012 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 880 of file pal_rtos.c.
void pal_osReboot | ( | void | ) |
Initiates a system reboot.
Definition at line 228 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 742 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 766 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 758 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 750 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 1176 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 819 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 1317 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 A pointer to thread's local store, can be NULL. [out] threadID,: The created thread ID handle. In case of error, this value is NULL.
- Returns:
- PAL_SUCCESS when the thread was created successfully.
PAL_ERR_RTOS_PRIORITY when the given priority is already used in the system.
- 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.
-
Calling
pal_osThreadTerminate()
releases the thread stack.
Definition at line 559 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.
- Note:
- For a thread with real time priority, the function always returns PAL_MAX_UINT32.
Definition at line 607 of file pal_rtos.c.
palThreadLocalStore_t* pal_osThreadGetLocalStore | ( | void | ) |
Get the storage of the current thread.
- Returns:
- The storage of the current thread.
Definition at line 637 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.
PAL_ERR_RTOS_RESOURCE if the thread ID is not correct.
- 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 565 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 674 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 702 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 682 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 694 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 171 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 128 of file pal_rtos.c.
Generated on Tue Jul 12 2022 19:01:38 by 1.7.2