Simple interface for Mbed Cloud Client
Embed:
(wiki syntax)
Show/hide line numbers
pal_rtos.h
Go to the documentation of this file.
00001 /******************************************************************************* 00002 * Copyright 2016, 2017 ARM Ltd. 00003 * 00004 * Licensed under the Apache License, Version 2.0 (the "License"); 00005 * you may not use this file except in compliance with the License. 00006 * You may obtain a copy of the License at 00007 * 00008 * http://www.apache.org/licenses/LICENSE-2.0 00009 * 00010 * Unless required by applicable law or agreed to in writing, software 00011 * distributed under the License is distributed on an "AS IS" BASIS, 00012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 00013 * See the License for the specific language governing permissions and 00014 * limitations under the License. 00015 *******************************************************************************/ 00016 00017 00018 #ifndef _PAL_RTOS_H 00019 #define _PAL_RTOS_H 00020 00021 #ifndef _PAL_H 00022 #error "Please do not include this file directly, use pal.h instead" 00023 #endif 00024 00025 #include <stdint.h> 00026 #include <string.h> //memcpy 00027 00028 00029 #ifdef __cplusplus 00030 extern "C" { 00031 #endif 00032 00033 #include "pal.h" //added for PAL_INITIAL_RANDOM_SIZE value 00034 00035 /*! \file pal_rtos.h 00036 * \brief PAL RTOS. 00037 * This file contains the real-time OS APIs and is a part of the PAL service API. 00038 * It provides thread, timers, semaphores, mutexes and memory pool management APIs. 00039 * Random API and ROT (root of trust) are also provided. 00040 */ 00041 00042 00043 //! Wait forever define. Used for semaphores and mutexes. 00044 #define PAL_TICK_TO_MILLI_FACTOR 1000 00045 00046 //! Primitive ID type declarations. 00047 typedef uintptr_t palThreadID_t; 00048 typedef uintptr_t palTimerID_t; 00049 typedef uintptr_t palMutexID_t; 00050 typedef uintptr_t palSemaphoreID_t; 00051 typedef uintptr_t palMemoryPoolID_t; 00052 typedef uintptr_t palMessageQID_t; 00053 00054 //! Timer types supported in PAL. 00055 typedef enum palTimerType { 00056 palOsTimerOnce = 0, /*! One shot timer. */ 00057 palOsTimerPeriodic = 1 /*! Periodic (repeating) timer. */ 00058 } palTimerType_t; 00059 00060 00061 00062 //! Device key types supported in PAL. 00063 typedef enum palDeviceKeyType { 00064 palOsStorageEncryptionKey128Bit = 0, /*! 128bit storage encryption key derived from RoT. */ 00065 palOsStorageSignatureKey128Bit = 1, /*! 128bit storage signature key derived from RoT. */ 00066 palOsStorageHmacSha256 = 2 00067 } palDevKeyType_t; 00068 00069 //! PAL timer function prototype. 00070 typedef void(*palTimerFuncPtr)(void const *funcArgument); 00071 00072 //! PAL thread function prototype. 00073 typedef void(*palThreadFuncPtr)(void const *funcArgument); 00074 00075 //! Available priorities in PAL implementation, each priority can appear only once. 00076 typedef enum pal_osPriority { 00077 PAL_osPriorityFirst = 0, 00078 PAL_osPriorityIdle = PAL_osPriorityFirst, 00079 PAL_osPriorityLow = 1, 00080 PAL_osPriorityReservedTRNG = 2, 00081 PAL_osPriorityBelowNormal = 3, 00082 PAL_osPriorityNormal = 4, 00083 PAL_osPriorityAboveNormal = 5, 00084 PAL_osPriorityReservedDNS = 6, /*! Reserved for PAL's internal use */ 00085 PAL_osPriorityReservedSockets = 7, /*! Reserved for PAL's internal use */ 00086 PAL_osPriorityHigh = 8, 00087 PAL_osPriorityReservedHighResTimer = 9, /*! Reserved for PAL's internal use */ 00088 PAL_osPriorityRealtime = 10, 00089 PAL_osPrioritylast = PAL_osPriorityRealtime , 00090 PAL_osPriorityError = 0x84 00091 } palThreadPriority_t; /*! Thread priority levels for PAL threads - each thread must have a different priority. */ 00092 00093 //! Thread local store struct. 00094 //! Can be used to hold for example state and configurations inside the thread. 00095 typedef struct pal_threadLocalStore{ 00096 void* storeData; 00097 } palThreadLocalStore_t; 00098 00099 typedef struct pal_timeVal{ 00100 int32_t pal_tv_sec; /*! Seconds. */ 00101 int32_t pal_tv_usec; /*! Microseconds. */ 00102 } pal_timeVal_t; 00103 00104 00105 //------- system general functions 00106 /*! Initiates a system reboot. 00107 */ 00108 void pal_osReboot(void); 00109 00110 //------- system tick functions 00111 /*! Get the RTOS kernel system timer counter. 00112 * \note The system needs to supply a 64-bit tick counter. If only a 32-bit counter is supported, 00113 * \note the counter wraps around very often (for example, once every 42 sec for 100Mhz). 00114 * \return The RTOS kernel system timer counter. 00115 */ 00116 uint64_t pal_osKernelSysTick(void); 00117 00118 00119 /*! Converts a value from microseconds to kernel system ticks. 00120 * 00121 * @param[in] microseconds The number of microseconds to convert into system ticks. 00122 * 00123 * \return Converted value in system ticks. 00124 */ 00125 uint64_t pal_osKernelSysTickMicroSec(uint64_t microseconds); 00126 00127 /*! Converts value from kernel system ticks to milliseconds. 00128 * 00129 * @param[in] sysTicks The number of kernel system ticks to convert into milliseconds. 00130 * 00131 * \return Converted value in system milliseconds. 00132 */ 00133 uint64_t pal_osKernelSysMilliSecTick(uint64_t sysTicks); 00134 00135 /*! Get the system tick frequency. 00136 * \return The system tick frequency. 00137 * 00138 * \note The system tick frequency MUST be more than 1KHz (at least one tick per millisecond). 00139 */ 00140 uint64_t pal_osKernelSysTickFrequency(void); 00141 00142 00143 /*! Get the system time. 00144 * \return The system 64-bit counter indicating the current system time in seconds on success. 00145 * Zero value when the time is not set in the system. 00146 * \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 00147 * then secure time value will be overridden with current system time 00148 */ 00149 uint64_t pal_osGetTime(void); 00150 00151 /*! \brief Set the current system time by accepting seconds since January 1st 1970 UTC+0. 00152 * 00153 * @param[in] seconds Seconds from January 1st 1970 UTC+0. 00154 * 00155 * \return PAL_SUCCESS when the time was set successfully. \n 00156 * PAL_ERR_INVALID_TIME when there is a failure setting the system time. 00157 */ 00158 palStatus_t pal_osSetTime(uint64_t seconds); 00159 00160 /*! \brief Initialization the time module 00161 * 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. 00162 * After initialization the time module will start counting ticks. 00163 * 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. 00164 * 00165 * \return PAL_SUCCESS when initialization succeed. \n 00166 * 00167 * \note 00168 */ 00169 palStatus_t pal_initTime(void); 00170 00171 /*! \brief save weak time according to design 00172 * Time Forward (a) 00173 * 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. 00174 * 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. 00175 * Time Forward (b) 00176 * If (a) did not happen, save the time into SOTP if new time is greater from SAVED_TIME by a week (604800 seconds). 00177 * Time Backwards 00178 * set the device time on the device (RAM) and save the time in SOTP only if the change 00179 * (between new time and current time in RAM) is smaller than 3 minutes for each day lapsed from the last change 00180 * done via pal_osWeakSetTime. RTC is never set backwards by pal_osWeakSetTime(). 00181 * 00182 * @param[in] uint64_t setTimeInSeconds Seconds from January 1st 1970 UTC+0. 00183 * 00184 * \return PAL_SUCCESS when set weak succeed. \n 00185 * 00186 * \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: 00187 * \note 1.- The new time (the same record as in factory setup) 00188 * \note 2.- The time this action was performed, in order to enforce the 24 hours limitation. Record LAST_TIME_BACK. 00189 */ 00190 palStatus_t pal_osSetWeakTime(uint64_t setTimeInSeconds); 00191 00192 /*! \brief save strong time according to design 00193 * Set the time (in RAM) unconditionally. Save in SOTP or/and RTC the new time under the following conditions: 00194 • Time forward – if time difference between current time in SOTP (not device time) and new time is greater than a day 00195 • Time backward – if time difference between current time and new time is greater than one minute. 00196 * If the time is saved in SOTP (forward or backwards), the record LAST_TIME_BACK must be saved. 00197 * 00198 ** @param[in] uint64_t setTimeInSeconds - Seconds from January 1st 1970 UTC+0. 00199 ** 00200 * \return PAL_SUCCESS when set strong succeed. \n 00201 * 00202 * \note The limitations are aimed to reduce the number of write operations to the SOTP and not related to security. 00203 * This function will be called when receiving time from a server that is completely trusted. 00204 */ 00205 palStatus_t pal_osSetStrongTime(uint64_t setTimeInSeconds); 00206 00207 /*! \brief Allocates memory for the thread stack, creates and starts the thread function (inside the PAL platform wrapper function). 00208 * 00209 * @param[in] function A function pointer to the thread callback function. 00210 * @param[in] funcArgument An argument for the thread function. 00211 * @param[in] priority The priority of the thread. 00212 * @param[in] stackSize The stack size of the thread, can NOT be 0. 00213 * @param[in] store A pointer to thread's local store, can be NULL. 00214 * @param[out] threadID: The created thread ID handle. In case of error, this value is NULL. 00215 * 00216 * \return PAL_SUCCESS when the thread was created successfully. \n 00217 * PAL_ERR_RTOS_PRIORITY when the given priority is already used in the system. 00218 * 00219 * \note Each thread MUST have a unique priority. 00220 * \note When the priority of the created thread function is higher than the current running thread, the 00221 * created thread function starts instantly and becomes the new running thread. 00222 * \note Calling \c pal_osThreadTerminate() releases the thread stack. 00223 */ 00224 palStatus_t pal_osThreadCreateWithAlloc(palThreadFuncPtr function, void* funcArgument, palThreadPriority_t priority, uint32_t stackSize, palThreadLocalStore_t* store, palThreadID_t* threadID); 00225 00226 /*! Terminate and free allocated data for the thread. 00227 * 00228 * @param[in] threadID The thread ID to stop and terminate. 00229 * 00230 * \return PAL_SUCCESS(0) in case of success and a negative value indicating a specific error code in case of failure. \n 00231 * PAL_ERR_RTOS_RESOURCE if the thread ID is not correct. 00232 * \note pal_osThreadTerminate is a non blocking operation, pal_osThreadTerminate sends cancellation request to the thread, 00233 * usually the thread exits immediately, but the system does not always guarantee this 00234 */ 00235 palStatus_t pal_osThreadTerminate(palThreadID_t* threadID); 00236 00237 /*! Get the ID of the current thread. 00238 * \return The ID of the current thread. In case of error, return PAL_MAX_UINT32. 00239 * \note For a thread with real time priority, the function always returns PAL_MAX_UINT32. 00240 */ 00241 palThreadID_t pal_osThreadGetId(void); 00242 00243 /*! Get the storage of the current thread. 00244 * \return The storage of the current thread. 00245 */ 00246 palThreadLocalStore_t* pal_osThreadGetLocalStore(void); 00247 00248 /*! Wait for a specified time period in milliseconds. 00249 * 00250 * @param[in] milliseconds The number of milliseconds to wait before proceeding. 00251 * 00252 * \return PAL_SUCCESS(0) in case of success and a negative value indicating a specific error code in case of failure. 00253 */ 00254 palStatus_t pal_osDelay(uint32_t milliseconds); 00255 00256 /*! Create a timer. 00257 * 00258 * @param[in] function A function pointer to the timer callback function. 00259 * @param[in] funcArgument An argument for the timer callback function. 00260 * @param[in] timerType The timer type to be created, periodic or oneShot. 00261 * @param[out] timerID The created timer ID handle. In case of error, this value is NULL. 00262 * 00263 * \return PAL_SUCCESS when the timer was created successfully. \n 00264 * PAL_ERR_NO_MEMORY when there is no memory resource available to create a timer object. 00265 * 00266 * \note The timer function runs according to the platform resources of stack-size and priority. 00267 */ 00268 palStatus_t pal_osTimerCreate(palTimerFuncPtr function, void* funcArgument, palTimerType_t timerType, palTimerID_t* timerID); 00269 00270 /*! Start or restart a timer. 00271 * 00272 * @param[in] timerID The handle for the timer to start. 00273 * @param[in] millisec The amount of time in milliseconds to set the timer to. MUST be larger than 0. 00274 * In case of 0 value, the error PAL_ERR_RTOS_VALUE is returned. 00275 * 00276 * \return PAL_SUCCESS(0) in case of success and a negative value indicating a specific error code in case of failure. 00277 */ 00278 palStatus_t pal_osTimerStart(palTimerID_t timerID, uint32_t millisec); 00279 00280 /*! Stop a timer. 00281 * @param[in] timerID The handle for the timer to stop. 00282 * \return PAL_SUCCESS(0) in case of success and a negative value indicating a specific error code in case of failure. 00283 */ 00284 palStatus_t pal_osTimerStop(palTimerID_t timerID); 00285 00286 /*! Delete the timer object. 00287 * 00288 * @param[inout] timerID The handle for the timer to delete. In success, `*timerID` = NULL. 00289 * 00290 * \return PAL_SUCCESS when timer was deleted successfully. \n 00291 * PAL_ERR_RTOS_PARAMETER when the `timerID` is incorrect. 00292 */ 00293 palStatus_t pal_osTimerDelete(palTimerID_t* timerID); 00294 00295 /*! Create and initialize a mutex object. 00296 * 00297 * @param[out] mutexID The created mutex ID handle. In case of error, this value is NULL. 00298 * 00299 * \return PAL_SUCCESS when the mutex was created successfully. \n 00300 * PAL_ERR_NO_MEMORY when there is no memory resource available to create a mutex object. 00301 */ 00302 palStatus_t pal_osMutexCreate(palMutexID_t* mutexID); 00303 00304 /*! Wait until a mutex becomes available. 00305 * 00306 * @param[in] mutexID The handle for the mutex. 00307 * @param[in] millisec The timeout for waiting to the mutex to be available. PAL_RTOS_WAIT_FOREVER can be used as a parameter. 00308 * 00309 * \return PAL_SUCCESS(0) in case of success or one of the following error codes in case of failure: \n 00310 * PAL_ERR_RTOS_RESOURCE - mutex was not availabe but no timeout was set. \n 00311 * PAL_ERR_RTOS_TIMEOUT - mutex was not available until the timeout. \n 00312 * PAL_ERR_RTOS_PARAMETER - mutex ID is invalid. \n 00313 * PAL_ERR_RTOS_ISR - cannot be called from the interrupt service routines. 00314 */ 00315 palStatus_t pal_osMutexWait(palMutexID_t mutexID, uint32_t millisec); 00316 00317 /*! Release a mutex that was obtained by `osMutexWait`. 00318 * 00319 * @param[in] mutexID The handle for the mutex. 00320 * \return PAL_SUCCESS(0) in case of success and another negative value indicating a specific error code in case of failure. 00321 */ 00322 palStatus_t pal_osMutexRelease(palMutexID_t mutexID); 00323 00324 /*!Delete a mutex object. 00325 * 00326 * @param[inout] mutexID The mutex handle to delete. In success, `*mutexID` = NULL. 00327 * 00328 * \return PAL_SUCCESS when the mutex was deleted successfully. \n 00329 * PAL_ERR_RTOS_RESOURCE - mutex is already released. \n 00330 * PAL_ERR_RTOS_PARAMETER - mutex ID is invalid. \n 00331 * PAL_ERR_RTOS_ISR - cannot be called from the interrupt service routines. \n 00332 * \note After this call, the `mutex_id` is no longer valid and cannot be used. 00333 */ 00334 palStatus_t pal_osMutexDelete(palMutexID_t* mutexID); 00335 00336 /*! Create and initialize a semaphore object. 00337 * 00338 * @param[in] count The number of available resources. 00339 * @param[out] semaphoreID The created semaphore ID handle. In case of error, this value is NULL. 00340 * 00341 * \return PAL_SUCCESS when the semaphore was created successfully. \n 00342 * PAL_ERR_NO_MEMORY when there is no memory resource available to create a semaphore object. 00343 */ 00344 palStatus_t pal_osSemaphoreCreate(uint32_t count, palSemaphoreID_t* semaphoreID); 00345 00346 /*! Wait until a semaphore token becomes available. 00347 * 00348 * @param[in] semaphoreID The handle for the semaphore. 00349 * @param[in] millisec The timeout for the waiting operation if the timeout 00350 expires before the semaphore is released and error is 00351 returned from the function. PAL_RTOS_WAIT_FOREVER can be used. 00352 * @param[out] countersAvailable The number of semaphores available at the call if a 00353 semaphore is available. If the semaphore is not available (timeout/error) zero is returned. This parameter can be NULL 00354 * \return PAL_SUCCESS(0) in case of success and one of the following error codes in case of failure: \n 00355 * PAL_ERR_RTOS_TIMEOUT - the semaphore was not available until timeout. \n 00356 * PAL_ERR_RTOS_PARAMETER - the semaphore ID is invalid. 00357 */ 00358 palStatus_t pal_osSemaphoreWait(palSemaphoreID_t semaphoreID, uint32_t millisec, int32_t* countersAvailable); 00359 00360 /*! Release a semaphore token. 00361 * 00362 * @param[in] semaphoreID The handle for the semaphore 00363 * 00364 * \return PAL_SUCCESS(0) in case of success and a negative value indicating a specific error code in case of failure. 00365 */ 00366 palStatus_t pal_osSemaphoreRelease(palSemaphoreID_t semaphoreID); 00367 00368 /*! Delete a semaphore object. 00369 * 00370 * @param[inout] semaphoreID The semaphore handle to delete. In success, `*semaphoreID` = NULL. 00371 * 00372 * \return PAL_SUCCESS when the semaphore was deleted successfully. \n 00373 * PAL_ERR_RTOS_RESOURCE - the semaphore was already released. \n 00374 * PAL_ERR_RTOS_PARAMETER - the semaphore ID is invalid. 00375 * \note After this call, the `semaphore_id` is no longer valid and cannot be used. 00376 */ 00377 palStatus_t pal_osSemaphoreDelete(palSemaphoreID_t* semaphoreID); 00378 00379 /*! Perform an atomic increment for a signed 32-bit value. 00380 * 00381 * @param[in,out] valuePtr The address of the value to increment. 00382 * @param[in] increment The number by which to increment. 00383 * 00384 * \return The value of `valuePtr` after the increment operation. 00385 */ 00386 int32_t pal_osAtomicIncrement(int32_t* valuePtr, int32_t increment); 00387 00388 00389 /*! Generate random number into given buffer with given size in bytes. 00390 * 00391 * @param[out] randomBuf A buffer to hold the generated number. 00392 * @param[in] bufSizeBytes The size of the buffer and the size of the required random number to generate. 00393 * 00394 \note `pal_init()` MUST be called before this function 00395 \return PAL_SUCCESS on success, a negative value indicating a specific error code in case of failure. 00396 */ 00397 palStatus_t pal_osRandomBuffer(uint8_t *randomBuf, size_t bufSizeBytes); 00398 00399 00400 /*! Return a device unique key derived from the root of trust. 00401 * 00402 * @param[in] keyType The type of key to derive. 00403 * @param[in,out] key A 128-bit OR 256-bit buffer to hold the derived key, size is defined according to the `keyType`. 00404 * @param[in] keyLenBytes The size of buffer to hold the 128-bit OR 256-bit key. 00405 * \return PAL_SUCCESS in case of success and one of the following error codes in case of failure: \n 00406 * PAL_ERR_GET_DEV_KEY - an error in key derivation. 00407 */ 00408 palStatus_t pal_osGetDeviceKey(palDevKeyType_t keyType, uint8_t *key, size_t keyLenBytes); 00409 00410 00411 /*! Initialize the RTOS module for PAL. 00412 * This function can be called only once before running the system. 00413 * To remove PAL from the system, call `pal_RTOSDestroy`. 00414 * After calling `pal_RTOSDestroy`, you can call `pal_RTOSInitialize` again. 00415 * 00416 * @param[in] opaqueContext: context to be passed to the platform if needed. 00417 * 00418 * \return PAL_SUCCESS upon success. 00419 */ 00420 palStatus_t pal_RTOSInitialize(void* opaqueContext); 00421 00422 00423 /*! This function removes PAL from the system and can be called after `pal_RTOSInitialize`. 00424 ** 00425 * \return PAL_SUCCESS upon success. \n 00426 * PAL_ERR_NOT_INITIALIZED - if the user did not call `pal_RTOSInitialize()` first. 00427 */ 00428 palStatus_t pal_RTOSDestroy(void); 00429 00430 /*! Generate a 32-bit random number. 00431 * 00432 * @param[out] random A 32-bit buffer to hold the generated number. 00433 * 00434 \note `pal_init()` MUST be called before this function. 00435 \return PAL_SUCCESS on success, a negative value indicating a specific error code in case of failure. 00436 */ 00437 palStatus_t pal_osRandom32bit(uint32_t *random); 00438 00439 00440 #ifdef __cplusplus 00441 } 00442 #endif 00443 #endif //_PAL_RTOS_H
Generated on Tue Jul 12 2022 19:01:36 by 1.7.2