pal_plat_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_PLAT_RTOS_H
00019 #define _PAL_PLAT_RTOS_H
00020 
00021 #ifdef __cplusplus
00022 extern "C" {
00023 #endif
00024 
00025 #include "pal.h"
00026     
00027 
00028 /*! \file pal_plat_rtos.h
00029 *  \brief PAL RTOS - platform.
00030 *   This file contains the real-time OS APIs that need to be implemented in the platform layer.
00031 */
00032 
00033 //! Type for holding platform specific (thread) data used exclusively by the platform, see pal_plat_osThreadDataInitialize for more information
00034 typedef void* palThreadPortData;
00035 
00036 //! PAL thread structure
00037 typedef struct palThreadData
00038 {
00039     palThreadID_t palThreadID; /*! generated thread id - platform should not modify this value */
00040     palThreadID_t osThreadID ; /*! the 'real' platform specific thread id - platform should not modify this value */
00041     palThreadLocalStore_t* store ; /*! pointer to thread local store - platform should not modify this value */
00042     palThreadPriority_t palPriority ; /*! pal thread priority - platform should not modify this value */
00043     int16_t osPriority ; /*! the 'real' platform specific thread priority - platform should not modify this value */
00044     uint32_t stackSize ; /*! thread stack size - platform should not modify this value */
00045     palThreadFuncPtr userFunction ; /*! the user function to be invoked - platform should not modify this value */
00046     void* userFunctionArg ; /*! the user argument to be passed to the userFunction - platform should not modify this value */
00047     palThreadPortData portData ; /*! platform specific data - platform may modify this value, used exclusively by the platform */
00048 } palThreadData_t;
00049 
00050 //! PAL thread bridge function prototype
00051 typedef void(*palThreadServiceBridgeFuncPtr)(palThreadData_t* threadData);
00052 
00053 //! PAL thread bridge structure - used by the platform thread to give control of the thread back to the service, see pal_plat_osThreadRun for more information
00054 typedef struct palThreadServiceBridge
00055 {
00056     palThreadServiceBridgeFuncPtr function; /*! function pointer which points back to the service */
00057     palThreadData_t* threadData ; /*! pointer to palThreadData_t associated with the thread */
00058 } palThreadServiceBridge_t;
00059 
00060 //! Total number of thread priorities
00061 #define PAL_NUMBER_OF_THREAD_PRIORITIES (PAL_osPrioritylast + 1)
00062 
00063 #define PAL_SHA256_DEVICE_KEY_SIZE_IN_BYTES 32
00064 #define PAL_DEVICE_KEY_SIZE_IN_BITS (128)
00065 #define PAL_DEVICE_KEY_SIZE_IN_BYTES (PAL_DEVICE_KEY_SIZE_IN_BITS / 8)
00066 
00067 
00068 /*! Initiate a system reboot.
00069 */
00070 void pal_plat_osReboot (void);
00071 
00072 /*! Initialize all data structures (semaphores, mutexes, memory pools, message queues) at system initialization.
00073 *   In case of a failure in any of the initializations, the function returns an error and stops the rest of the initializations.
00074 * @param[in] opaqueContext The context passed to the initialization (not required for generic CMSIS, pass NULL in this case).
00075 * \return PAL_SUCCESS(0) in case of success, PAL_ERR_CREATION_FAILED in case of failure.
00076 */
00077 palStatus_t pal_plat_RTOSInitialize (void* opaqueContext);
00078 
00079 /*! De-initialize thread objects.
00080 */
00081 palStatus_t pal_plat_RTOSDestroy (void);
00082 
00083 /*! Get the RTOS kernel system timer counter.
00084 *
00085 * \return The RTOS kernel system timer counter.
00086 *
00087 * \note The required tick counter is the OS (platform) kernel system tick counter.
00088 * \note If the platform supports 64-bit tick counter, please implement it. If the platform supports only 32 bit, note
00089 *       that this counter wraps around very often (for example, once every 42 sec for 100Mhz).
00090 */
00091 uint64_t pal_plat_osKernelSysTick (void);
00092 
00093 /*! Convert the value from microseconds to kernel sys ticks.
00094 * This is the same as CMSIS macro `osKernelSysTickMicroSec`.
00095 */
00096 uint64_t pal_plat_osKernelSysTickMicroSec (uint64_t microseconds);
00097 
00098 /*! Get the system tick frequency.
00099 * \return The system tick frequency.
00100 *
00101 * \note The system tick frequency MUST be more than 1KHz (at least one tick per millisecond).
00102 */
00103 uint64_t pal_plat_osKernelSysTickFrequency (void);
00104 
00105 /*! Translate from palThreadPriority_t to platform specific priority.
00106 *
00107 @param[in] priority PAL priority to be translated.
00108 *
00109 * \return value representing the platform specific thread priority.
00110 */
00111 int16_t pal_plat_osThreadTranslatePriority (palThreadPriority_t priority);
00112 
00113 /*! Allocate platform specific data for the thread.
00114 *
00115 * @param[out] portData A pointer to a palThreadPortData type containing (optional) platform specific data about the thread.
00116 * @param[in] priority Platform specific thread priority (post-translation).
00117 * @param[in] stackSize Thread stack size.
00118 *
00119 * \return PAL_SUCCESS(0) in case of success. A negative value indicating a specific error code in case of failure.
00120 *
00121 * \note portData is used exclusively by the platform, the service layer has no use for this and all it does is keep 
00122 *       the pointer as part of the palThreadData_t structure. If the platform does not have any allocations to be done then just return PAL_SUCCESS(0)
00123 */
00124 palStatus_t pal_plat_osThreadDataInitialize (palThreadPortData* portData, int16_t priority, uint32_t stackSize);
00125 
00126 /*! Create and run the thread.
00127 *
00128 * @param[in] bridge A pointer to a palThreadServiceBridge_t structure which contains the function pointer and data which must be invoked from the created thread function.
00129 * @param[out] osThreadID Platform specific thread id associated with the created thread.
00130 *
00131 * \return PAL_SUCCESS(0) in case of success. A negative value indicating a specific error code in case of failure.
00132 *
00133 * \note From within the created thread function the plaform MUST execute "bridge->function(bridge->threadData);". This is the liaison between the platform and the service 
00134 *       which gives the control back to the service. It is recommended (if possible) to pass the bridge pointer as an argument (or as part of an argument) to the
00135 *       platfrom specific thread function.
00136 */
00137 palStatus_t pal_plat_osThreadRun (palThreadServiceBridge_t* bridge, palThreadID_t* osThreadID);
00138 
00139 /*! Free any allocated data for the thread.
00140 *
00141 * @param[in] threadData A pointer to a palThreadData_t structure containing information about the thread.
00142 *
00143 * \return PAL_SUCCESS(0) in case of success. A negative value indicating a specific error code in case of failure.
00144 *
00145 * \note If this function is called then pal_plat_osThreadTerminate will not be called, so clean up all allocated resources (if any).
00146 * \note This function is called from within the thread's context after the user function has been invoked and only if the thread hasn't been terminated.
00147 */
00148 palStatus_t pal_plat_osThreadDataCleanup (palThreadData_t* threadData);
00149 
00150 /*! Terminate and free allocated data for the thread.
00151 *
00152 * @param[in] threadData A pointer to a palThreadData_t structure containing information about the thread.
00153 *
00154 * \return PAL_SUCCESS(0) in case of success. A negative value indicating a specific error code in case of failure.
00155 *
00156 * \note If this function is called then pal_plat_osThreadDataCleanup will not be called, so clean up all allocated resources.
00157 */
00158 palStatus_t pal_plat_osThreadTerminate (palThreadData_t* threadData);
00159 
00160 /*! Get the ID of the current thread.
00161 * \return The ID of the current thread. In case of error, returns PAL_MAX_UINT32.
00162 * \note For a thread with real time priority, the function always returns PAL_MAX_UINT32.
00163 */
00164 palThreadID_t pal_plat_osThreadGetId (void);
00165 
00166 /*! Wait for a specified period of time in milliseconds.
00167 *
00168 * @param[in] milliseconds The number of milliseconds to wait before proceeding.
00169 *
00170 * \return PAL_SUCCESS(0) in case of success. A negative value indicating a specific error code in case of failure.
00171 */
00172 palStatus_t pal_plat_osDelay (uint32_t milliseconds);
00173 
00174 /*! Create a timer.
00175 *
00176 * @param[in] function A function pointer to the timer callback function.
00177 * @param[in] funcArgument An argument for the timer callback function.
00178 * @param[in] timerType The timer type to be created, periodic or `oneShot`.
00179 * @param[out] timerID The ID of the created timer. Zero value indicates an error.
00180 *
00181 * \return PAL_SUCCESS when the timer was created successfully. A specific error in case of failure. \n
00182 *         PAL_ERR_NO_MEMORY: No memory resource available to create a timer object.
00183 *
00184 * \note The timer callback function runs according to the platform resources of stack size and priority.
00185 * \note The create function MUST not wait for platform resources and it should return PAL_ERR_RTOS_RESOURCE, unless the platform API is blocking.
00186 */
00187 palStatus_t pal_plat_osTimerCreate (palTimerFuncPtr function, void* funcArgument, palTimerType_t timerType, palTimerID_t* timerID);
00188 
00189 /*! Start or restart a timer.
00190 *
00191 * @param[in] timerID The handle for the timer to start.
00192 * @param[in] millisec: The time in milliseconds to set the timer to, MUST be larger than 0.
00193 *                      In case the value is 0, the error PAL_ERR_RTOS_VALUE will be returned.
00194 *
00195 * \return PAL_SUCCESS(0) in case of success. A negative value indicating a specific error code in case of failure.
00196 */
00197 palStatus_t pal_plat_osTimerStart (palTimerID_t timerID, uint32_t millisec);
00198 
00199 /*! Stop a timer.
00200 *
00201 * @param[in] timerID The handle for the timer to stop.
00202 *
00203 * \return PAL_SUCCESS(0) in case of success. A negative value indicating a specific error code in case of failure.
00204 */
00205 palStatus_t pal_plat_osTimerStop (palTimerID_t timerID);
00206 
00207 /*! Delete the timer object.
00208 *
00209 * @param[inout] timerID The handle for the timer to delete. In success, `*timerID` = NULL.
00210 *
00211 * \return PAL_SUCCESS when the timer was deleted successfully. PAL_ERR_RTOS_PARAMETER when the `timerID` is incorrect.
00212 * \note In case of a running timer, `pal_platosTimerDelete()` MUST stop the timer before deletion.
00213 */
00214 palStatus_t pal_plat_osTimerDelete (palTimerID_t* timerID);
00215 
00216 /*! Create and initialize a mutex object.
00217 *
00218 * @param[out] mutexID The created mutex ID handle, zero value indicates an error.
00219 *
00220 * \return PAL_SUCCESS when the mutex was created successfully, a specific error in case of failure. \n
00221 *         PAL_ERR_NO_MEMORY when there is no memory resource available to create a mutex object.
00222 * \note The create function MUST NOT wait for the platform resources and it should return PAL_ERR_RTOS_RESOURCE, unless the platform API is blocking.
00223 *        By default, the mutex is created with a recursive flag set.
00224 */
00225 palStatus_t pal_plat_osMutexCreate (palMutexID_t* mutexID);
00226 
00227 /*! Wait until a mutex becomes available.
00228 *
00229 * @param[in] mutexID The handle for the mutex.
00230 * @param[in] millisec The timeout for the waiting operation if the timeout expires before the semaphore is released and an error is returned from the function.
00231 *
00232 * \return PAL_SUCCESS(0) in case of success. One of the following error codes in case of failure: \n
00233 *         - PAL_ERR_RTOS_RESOURCE - Mutex not available but no timeout set. \n
00234 *         - PAL_ERR_RTOS_TIMEOUT - Mutex was not available until timeout expired. \n
00235 *         - PAL_ERR_RTOS_PARAMETER - The mutex ID is invalid. \n
00236 *         - PAL_ERR_RTOS_ISR - Cannot be called from interrupt service routines.
00237 */
00238 palStatus_t pal_plat_osMutexWait (palMutexID_t mutexID, uint32_t millisec);
00239 
00240 /*! Release a mutex that was obtained by `osMutexWait`.
00241 *
00242 * @param[in] mutexID The handle for the mutex.
00243 *
00244 * \return PAL_SUCCESS(0) in case of success. A negative value indicating a specific error code in case of failure.
00245 */
00246 palStatus_t pal_plat_osMutexRelease (palMutexID_t mutexID);
00247 
00248 /*! Delete a mutex object.
00249 *
00250 * @param[inout] mutexID The ID of the mutex to delete. In success, `*mutexID` = NULL.
00251 *
00252 * \return PAL_SUCCESS when the mutex was deleted successfully, one of the following error codes in case of failure: \n
00253 *         - PAL_ERR_RTOS_RESOURCE - Mutex already released. \n
00254 *         - PAL_ERR_RTOS_PARAMETER - Mutex ID is invalid. \n
00255 *         - PAL_ERR_RTOS_ISR - Cannot be called from interrupt service routines.
00256 * \note After this call, `mutex_id` is no longer valid and cannot be used.
00257 */
00258 palStatus_t pal_plat_osMutexDelete (palMutexID_t* mutexID);
00259 
00260 /*! Create and initialize a semaphore object.
00261 *
00262 * @param[in] count The number of available resources.
00263 * @param[out] semaphoreID The ID of the created semaphore, zero value indicates an error.
00264 *
00265 * \return PAL_SUCCESS when the semaphore was created successfully, a specific error in case of failure. \n
00266 *         PAL_ERR_NO_MEMORY: No memory resource available to create a semaphore object.
00267 * \note The create function MUST not wait for the platform resources and it should return PAL_ERR_RTOS_RESOURCE, unless the platform API is blocking.
00268 */
00269 palStatus_t pal_plat_osSemaphoreCreate (uint32_t count, palSemaphoreID_t* semaphoreID);
00270 
00271 /*! Wait until a semaphore token becomes available.
00272 *
00273 * @param[in] semaphoreID The handle for the semaphore.
00274 * @param[in] millisec The timeout for the waiting operation if the timeout expires before the semaphore is released and an error is returned from the function.
00275 * @param[out] countersAvailable The number of semaphores available. If semaphores are not available (timeout/error) zero is returned. 
00276 * \return PAL_SUCCESS(0) in case of success. One of the following error codes in case of failure: \n
00277 *       - PAL_ERR_RTOS_TIMEOUT - Semaphore was not available until timeout expired. \n
00278 *       - PAL_ERR_RTOS_PARAMETER - Semaphore ID is invalid.
00279 */
00280 palStatus_t pal_plat_osSemaphoreWait (palSemaphoreID_t semaphoreID, uint32_t millisec, int32_t* countersAvailable);
00281 
00282 /*! Release a semaphore token.
00283 *
00284 * @param[in] semaphoreID The handle for the semaphore.
00285 *
00286 * \return PAL_SUCCESS(0) in case of success. A negative value indicating a specific error code in case of failure.
00287 */
00288 palStatus_t pal_plat_osSemaphoreRelease (palSemaphoreID_t semaphoreID);
00289 
00290 /*! Delete a semaphore object.
00291 *
00292 * @param[inout] semaphoreID: The ID of the semaphore to delete. In success, `*semaphoreID` = NULL.
00293 *
00294 * \return PAL_SUCCESS when the semaphore was deleted successfully. One of the following error codes in case of failure: \n
00295 *         PAL_ERR_RTOS_RESOURCE - Semaphore already released. \n
00296 *         PAL_ERR_RTOS_PARAMETER - Semaphore ID is invalid.
00297 * \note After this call, the `semaphore_id` is no longer valid and cannot be used.
00298 */
00299 palStatus_t pal_plat_osSemaphoreDelete (palSemaphoreID_t* semaphoreID);
00300 
00301 
00302 /*! Perform an atomic increment for a signed32 bit value.
00303 *
00304 * @param[in,out] valuePtr The address of the value to increment.
00305 * @param[in] increment The number by which to increment.
00306 *
00307 * \returns The value of the `valuePtr` after the increment operation.
00308 */
00309 int32_t pal_plat_osAtomicIncrement (int32_t* valuePtr, int32_t increment);
00310 
00311 /*! Perform allocation from the heap according to the OS specification.
00312 *
00313 * @param[in] len The length of the buffer to be allocated.
00314 *
00315 * \returns `void *`. The pointer of the malloc received from the OS if NULL error occurred
00316 */
00317 void *pal_plat_malloc (size_t len);
00318 
00319 /*! Free memory back to the OS heap.
00320 *
00321 * @param[in] *buffer A pointer to the buffer that should be free.
00322 *
00323 * \returns `void`
00324 */
00325  void pal_plat_free (void * buffer);
00326 
00327 /*! Generate a random number into the given buffer with the given size in bytes.
00328 *
00329 * @param[out] randomBuf A buffer to hold the generated number.
00330 * @param[in] bufSizeBytes The size of the buffer and the size of the required random number to generate.
00331 * @param[out] actualRandomSizeBytes The actual size of the written random data to the output buffer.
00332 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00333 \note In case the platform was able to provide random data with non-zero size and less than `bufSizeBytes`the function must return `PAL_ERR_RTOS_TRNG_PARTIAL_DATA`
00334 */
00335 palStatus_t pal_plat_osRandomBuffer (uint8_t *randomBuf, size_t bufSizeBytes, size_t* actualRandomSizeBytes);
00336 
00337 
00338 /*! Retrieve platform Root of Trust certificate
00339 *
00340 * @param[in,out] *keyBuf A pointer to the buffer that holds the RoT.
00341 * @param[in] keyLenBytes The size of the buffer to hold the 128 bit key, must be at least 16 bytes.
00342 * The buffer needs to be able to hold 16 bytes of data.
00343 *
00344 * \return PAL_SUCCESS(0) in case of success. A negative value indicating a specific error code in case of failure.
00345 */
00346 
00347 palStatus_t pal_plat_osGetRoTFromHW (uint8_t *keyBuf, size_t keyLenBytes);
00348 
00349 /*! \brief  This function calls the platform layer and sets the new RTC to the H/W
00350 *
00351 * @param[in] uint64_t rtcSetTime the new RTC time
00352 *
00353 * \return PAL_SUCCESS when the RTC return correctly
00354 *
00355 */
00356 palStatus_t pal_plat_osSetRtcTime(uint64_t rtcSetTime);
00357 
00358 /*! \brief This function gets the RTC from the platform
00359 *
00360 * @param[out] uint64_t * rtcGetTime - Holds the RTC value
00361 *
00362 * \return PAL_SUCCESS when the RTC return correctly
00363 *
00364 */
00365 palStatus_t pal_plat_osGetRtcTime(uint64_t *rtcGetTime);
00366 
00367 
00368 /*! \brief This function DeInitialize the RTC module
00369 *
00370 * \return PAL_SUCCESS when the success or error upon failing
00371 *
00372 */
00373 palStatus_t pal_plat_rtcDeInit(void);
00374 
00375 
00376 /*! \brief This function initialize the RTC module
00377 *
00378 * \return PAL_SUCCESS when the success or error upon failing
00379 *
00380 */
00381 palStatus_t pal_plat_rtcInit(void);
00382 
00383 #ifdef __cplusplus
00384 }
00385 #endif
00386 #endif //_PAL_COMMON_H