pal_rtos.h

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 * Application can provide their own implementation by defining PAL_USE_APPLICATION_REBOOT and
00108 * providing implementation for pal_plat_osApplicationReboot() function.
00109 */
00110 void pal_osReboot(void);
00111 
00112 //------- system tick functions
00113 /*! Get the RTOS kernel system timer counter.
00114 * \note The system needs to supply a 64-bit tick counter. If only a 32-bit counter is supported,
00115 * \note the counter wraps around very often (for example, once every 42 sec for 100Mhz).
00116 * \return The RTOS kernel system timer counter.
00117 */
00118 uint64_t pal_osKernelSysTick(void);
00119 
00120 
00121 /*! Converts a value from microseconds to kernel system ticks.
00122 *
00123 * @param[in] microseconds The number of microseconds to convert into system ticks.
00124 *
00125 * \return Converted value in system ticks.
00126 */
00127 uint64_t pal_osKernelSysTickMicroSec(uint64_t microseconds);
00128 
00129 /*! Converts value from kernel system ticks to milliseconds.
00130 *
00131 * @param[in] sysTicks The number of kernel system ticks to convert into milliseconds.
00132 *
00133 * \return Converted value in system milliseconds.
00134 */
00135 uint64_t pal_osKernelSysMilliSecTick(uint64_t sysTicks);
00136 
00137 /*! Get the system tick frequency.
00138 * \return The system tick frequency.
00139 *
00140 * \note The system tick frequency MUST be more than 1KHz (at least one tick per millisecond).
00141 */
00142 uint64_t pal_osKernelSysTickFrequency(void);
00143 
00144 
00145 /*! Get the system time.
00146 * \return The system 64-bit counter indicating the current system time in seconds on success.
00147 *         Zero value when the time is not set in the system.
00148 * \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
00149 * then secure time value will be overridden with current system time
00150 */
00151 uint64_t pal_osGetTime(void);
00152 
00153 /*! \brief Set the current system time by accepting seconds since January 1st 1970 UTC+0.
00154 *
00155 * @param[in] seconds Seconds from January 1st 1970 UTC+0.
00156 *
00157 * \return PAL_SUCCESS when the time was set successfully. \n
00158 *         PAL_ERR_INVALID_TIME when there is a failure setting the system time.
00159 */
00160 palStatus_t pal_osSetTime(uint64_t seconds);
00161 
00162 /*! \brief  Initialization the time module
00163 *   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.
00164 *   After initialization the time module will start counting ticks.
00165 *   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.
00166 *
00167 * \return PAL_SUCCESS when initialization succeed. \n
00168 *
00169 * \note
00170 */
00171 palStatus_t pal_initTime(void);
00172 
00173 /*! \brief save weak time according to design
00174 *   Time Forward (a)
00175 *   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.
00176 *   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.
00177 *   Time Forward (b)
00178 *   If (a) did not happen, save the time into SOTP if new time is greater from SAVED_TIME by a week (604800 seconds).
00179 *   Time Backwards
00180 *   set the device time on the device (RAM) and save the time in SOTP only if the change
00181 *   (between new time and current time in RAM) is smaller than 3 minutes for each day lapsed from the last change
00182 *   done via pal_osWeakSetTime. RTC is never set backwards by pal_osWeakSetTime().
00183 *
00184 * @param[in] uint64_t setTimeInSeconds  Seconds from January 1st 1970 UTC+0.
00185 *
00186 * \return PAL_SUCCESS when set weak  succeed. \n
00187 *
00188 * \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:
00189 * \note 1.- The new time (the same record as in factory setup)
00190 * \note 2.- The time this action was performed, in order to enforce the 24 hours limitation. Record LAST_TIME_BACK.
00191 */
00192 palStatus_t pal_osSetWeakTime(uint64_t setTimeInSeconds);
00193 
00194 /*! \brief save strong time according to design
00195 *   Set the time (in RAM) unconditionally. Save in SOTP or/and RTC the new time under the following conditions:
00196 • Time forward – if time difference between current time in SOTP (not device time) and new time is greater than a day
00197 • Time backward – if time difference between current time and new time is greater than one minute.
00198 *   If the time is saved in SOTP (forward or backwards), the record LAST_TIME_BACK must be saved.
00199 *
00200 ** @param[in] uint64_t setTimeInSeconds - Seconds from January 1st 1970 UTC+0.
00201 **
00202 * \return PAL_SUCCESS when set strong succeed. \n
00203 *
00204 * \note   The limitations are aimed to reduce the number of write operations to the SOTP and not related to security.
00205 *   This function will be called when receiving time from a server that is completely trusted.
00206 */
00207 palStatus_t pal_osSetStrongTime(uint64_t setTimeInSeconds);
00208 
00209 /*! \brief Allocates memory for the thread stack, creates and starts the thread function (inside the PAL platform wrapper function).
00210 *
00211 * @param[in] function A function pointer to the thread callback function.
00212 * @param[in] funcArgument An argument for the thread function.
00213 * @param[in] priority The priority of the thread.
00214 * @param[in] stackSize The stack size of the thread, can NOT be 0.
00215 * @param[in] store MUST be NULL - this functionality is not supported.
00216 * @param[out] threadID: The created thread ID handle. In case of error, this value is NULL.
00217 *
00218 * \return PAL_SUCCESS when the thread was created successfully. \n
00219 *
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 *
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 */
00240 palThreadID_t pal_osThreadGetId(void);
00241 
00242 /*! Wait for a specified time period in milliseconds.
00243 *
00244 * @param[in] milliseconds The number of milliseconds to wait before proceeding.
00245 *
00246 * \return PAL_SUCCESS(0) in case of success and a negative value indicating a specific error code in case of failure.
00247 */
00248 palStatus_t pal_osDelay(uint32_t milliseconds);
00249 
00250 /*! Create a timer.
00251 *
00252 * @param[in] function A function pointer to the timer callback function.
00253 * @param[in] funcArgument An argument for the timer callback function.
00254 * @param[in] timerType The timer type to be created, periodic or oneShot.
00255 * @param[out] timerID The created timer ID handle. In case of error, this value is NULL.
00256 *
00257 * \return PAL_SUCCESS when the timer was created successfully. \n
00258 *         PAL_ERR_NO_MEMORY when there is no memory resource available to create a timer object.
00259 *
00260 * \note The timer function runs according to the platform resources of stack-size and priority.
00261 */
00262 palStatus_t pal_osTimerCreate(palTimerFuncPtr function, void* funcArgument, palTimerType_t timerType, palTimerID_t* timerID);
00263 
00264 /*! Start or restart a timer.
00265 *
00266 * @param[in] timerID The handle for the timer to start.
00267 * @param[in] millisec The amount of time in milliseconds to set the timer to. MUST be larger than 0.
00268 *                      In case of 0 value, the error PAL_ERR_RTOS_VALUE is returned.
00269 *
00270 * \return PAL_SUCCESS(0) in case of success and a negative value indicating a specific error code in case of failure.
00271 */
00272 palStatus_t pal_osTimerStart(palTimerID_t timerID, uint32_t millisec);
00273 
00274 /*! Stop a timer.
00275 * @param[in] timerID The handle for the timer to stop.
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_osTimerStop(palTimerID_t timerID);
00279 
00280 /*! Delete the timer object.
00281 *
00282 * @param[inout] timerID The handle for the timer to delete. In success, `*timerID` = NULL.
00283 *
00284 * \return PAL_SUCCESS when timer was deleted successfully. \n
00285 *         PAL_ERR_RTOS_PARAMETER when the `timerID` is incorrect.
00286 */
00287 palStatus_t pal_osTimerDelete(palTimerID_t* timerID);
00288 
00289 /*! Create and initialize a mutex object.
00290 *
00291 * @param[out] mutexID The created mutex ID handle. In case of error, this value is NULL.
00292 *
00293 * \return PAL_SUCCESS when the mutex was created successfully. \n
00294 *         PAL_ERR_NO_MEMORY when there is no memory resource available to create a mutex object.
00295 */
00296 palStatus_t pal_osMutexCreate(palMutexID_t* mutexID);
00297 
00298 /*! Wait until a mutex becomes available.
00299 *
00300 * @param[in] mutexID The handle for the mutex.
00301 * @param[in] millisec The timeout for waiting to the mutex to be available. PAL_RTOS_WAIT_FOREVER can be used as a parameter.
00302 *
00303 * \return PAL_SUCCESS(0) in case of success or one of the following error codes in case of failure: \n
00304 *         PAL_ERR_RTOS_RESOURCE - mutex was not availabe but no timeout was set. \n
00305 *         PAL_ERR_RTOS_TIMEOUT - mutex was not available until the timeout. \n
00306 *         PAL_ERR_RTOS_PARAMETER - mutex ID is invalid. \n
00307 *         PAL_ERR_RTOS_ISR - cannot be called from the interrupt service routines.
00308 */
00309 palStatus_t pal_osMutexWait(palMutexID_t mutexID, uint32_t millisec);
00310 
00311 /*! Release a mutex that was obtained by `osMutexWait`.
00312 *
00313 * @param[in] mutexID The handle for the mutex.
00314 * \return PAL_SUCCESS(0) in case of success and another negative value indicating a specific error code in case of failure.
00315 */
00316 palStatus_t pal_osMutexRelease(palMutexID_t mutexID);
00317 
00318 /*!Delete a mutex object.
00319 *
00320 * @param[inout] mutexID The mutex handle to delete. In success, `*mutexID` = NULL.
00321 *
00322 * \return PAL_SUCCESS when the mutex was deleted successfully. \n
00323 *         PAL_ERR_RTOS_RESOURCE - mutex is already released. \n
00324 *         PAL_ERR_RTOS_PARAMETER - mutex ID is invalid. \n
00325 *         PAL_ERR_RTOS_ISR - cannot be called from the interrupt service routines. \n
00326 * \note After this call, the `mutex_id` is no longer valid and cannot be used.
00327 */
00328 palStatus_t pal_osMutexDelete(palMutexID_t* mutexID);
00329 
00330 /*! Create and initialize a semaphore object.
00331 *
00332 * @param[in] count The number of available resources.
00333 * @param[out] semaphoreID The created semaphore ID handle. In case of error, this value is NULL.
00334 *
00335 * \return PAL_SUCCESS when the semaphore was created successfully. \n
00336 *         PAL_ERR_NO_MEMORY when there is no memory resource available to create a semaphore object.
00337 */
00338 palStatus_t pal_osSemaphoreCreate(uint32_t count, palSemaphoreID_t* semaphoreID);
00339 
00340 /*! Wait until a semaphore token becomes available.
00341 *
00342 * @param[in] semaphoreID The handle for the semaphore.
00343 * @param[in] millisec The timeout for the waiting operation if the timeout 
00344                        expires before the semaphore is released and error is 
00345                        returned from the function. PAL_RTOS_WAIT_FOREVER can be used.
00346 * @param[out] countersAvailable The number of semaphores available at the call if a
00347                                   semaphore is available. If the semaphore is not available (timeout/error) zero is returned. This parameter can be NULL 
00348 * \return PAL_SUCCESS(0) in case of success and one of the following error codes in case of failure: \n
00349 *       PAL_ERR_RTOS_TIMEOUT - the semaphore was not available until timeout. \n
00350 *       PAL_ERR_RTOS_PARAMETER - the semaphore ID is invalid.
00351 */
00352 palStatus_t pal_osSemaphoreWait(palSemaphoreID_t semaphoreID, uint32_t millisec, int32_t* countersAvailable);
00353 
00354 /*! Release a semaphore token.
00355 *
00356 * @param[in] semaphoreID The handle for the semaphore
00357 *
00358 * \return PAL_SUCCESS(0) in case of success and a negative value indicating a specific error code in case of failure.
00359 */
00360 palStatus_t pal_osSemaphoreRelease(palSemaphoreID_t semaphoreID);
00361 
00362 /*! Delete a semaphore object.
00363 *
00364 * @param[inout] semaphoreID The semaphore handle to delete. In success, `*semaphoreID` = NULL.
00365 *
00366 * \return PAL_SUCCESS when the semaphore was deleted successfully. \n
00367 *         PAL_ERR_RTOS_RESOURCE - the semaphore was already released. \n
00368 *         PAL_ERR_RTOS_PARAMETER - the semaphore ID is invalid.
00369 * \note After this call, the `semaphore_id` is no longer valid and cannot be used.
00370 */
00371 palStatus_t pal_osSemaphoreDelete(palSemaphoreID_t* semaphoreID);
00372 
00373 /*! Perform an atomic increment for a signed 32-bit value.
00374 *
00375 * @param[in,out] valuePtr The address of the value to increment.
00376 * @param[in] increment The number by which to increment.
00377 *
00378 * \return The value of `valuePtr` after the increment operation.
00379 */
00380 int32_t pal_osAtomicIncrement(int32_t* valuePtr, int32_t increment);
00381 
00382 
00383 /*! Generate random number into given buffer with given size in bytes.
00384 *
00385 * @param[out] randomBuf A buffer to hold the generated number.
00386 * @param[in] bufSizeBytes The size of the buffer and the size of the required random number to generate.
00387 *
00388 \note `pal_init()` MUST be called before this function
00389 \return PAL_SUCCESS on success, a negative value indicating a specific error code in case of failure.
00390 */
00391 palStatus_t pal_osRandomBuffer(uint8_t *randomBuf, size_t bufSizeBytes);
00392 
00393 
00394 /*! Return a device unique key derived from the root of trust.
00395 *
00396 * @param[in] keyType The type of key to derive.
00397 * @param[in,out] key A 128-bit OR 256-bit buffer to hold the derived key, size is defined according to the `keyType`.
00398 * @param[in] keyLenBytes The size of buffer to hold the 128-bit OR 256-bit key.
00399 * \return PAL_SUCCESS in case of success and one of the following error codes in case of failure: \n
00400 * PAL_ERR_GET_DEV_KEY - an error in key derivation.
00401 */
00402 palStatus_t pal_osGetDeviceKey(palDevKeyType_t keyType, uint8_t *key, size_t keyLenBytes);
00403 
00404 
00405 /*! Initialize the RTOS module for PAL.
00406  * This function can be called only once before running the system.
00407  * To remove PAL from the system, call `pal_RTOSDestroy`.
00408  * After calling `pal_RTOSDestroy`, you can call `pal_RTOSInitialize` again.
00409 *
00410 * @param[in] opaqueContext: context to be passed to the platform if needed.
00411 *
00412 * \return PAL_SUCCESS upon success.
00413 */
00414 palStatus_t pal_RTOSInitialize(void* opaqueContext);
00415 
00416 
00417 /*! This function removes PAL from the system and can be called after `pal_RTOSInitialize`.
00418 **
00419 * \return PAL_SUCCESS upon success. \n
00420 *         PAL_ERR_NOT_INITIALIZED - if the user did not call `pal_RTOSInitialize()` first.
00421 */
00422 palStatus_t pal_RTOSDestroy(void);
00423 
00424 /*! Generate a 32-bit random number.
00425 *
00426 * @param[out] random A 32-bit buffer to hold the generated number.
00427 *
00428 \note `pal_init()` MUST be called before this function.
00429 \return PAL_SUCCESS on success, a negative value indicating a specific error code in case of failure.
00430 */
00431 palStatus_t pal_osRandom32bit(uint32_t *random);
00432 
00433 
00434 #ifdef __cplusplus
00435 }
00436 #endif
00437 #endif //_PAL_RTOS_H