pal_plat_rtos.h

00001 /*
00002 * Copyright (c) 2016 ARM Limited. All rights reserved.
00003 * SPDX-License-Identifier: Apache-2.0
00004 * Licensed under the Apache License, Version 2.0 (the License); you may
00005 * 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, WITHOUT
00012 * 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_rtos.h"
00026 #include "pal_configuration.h"
00027 #include "pal_types.h"
00028 
00029 /*! \file pal_plat_rtos.h
00030 *  \brief PAL RTOS - platform.
00031 *   This file contains the real-time OS APIs that need to be implemented in the platform layer.
00032 */
00033 
00034 #if PAL_UNIQUE_THREAD_PRIORITY
00035 //! This array holds a counter for each thread priority.
00036 //! If the counter is more than 1, it means that more than 
00037 //! one thread has the same priority and this is a forbidden
00038 //! situation. The mapping between the priorities and the index
00039 //! in the array is as follow:
00040 //!
00041 //! PAL_osPriorityIdle --> g_palThreadPriorities[0]
00042 //! PAL_osPriorityLow --> g_palThreadPriorities[1]
00043 //! PAL_osPriorityBelowNormal --> g_palThreadPriorities[2]
00044 //! PAL_osPriorityNormal --> g_palThreadPriorities[3]
00045 //! PAL_osPriorityAboveNormal --> g_palThreadPriorities[4]
00046 //! PAL_osPriorityHigh --> g_palThreadPriorities[5]
00047 //! PAL_osPriorityRealtime --> g_palThreadPriorities[6]
00048 
00049 //! An array of PAL thread priorities. The size of the array is defined in the Service API (`pal_configuration.h`) by PAL_MAX_NUMBER_OF_THREADS.
00050 extern uint32_t g_palThreadPriorities[PAL_NUMBER_OF_THREADS_PRIORITIES];
00051 extern palMutexID_t g_palThreadInitMutex ;
00052 
00053 #define PRIORITY_INDEX_OFFSET 3
00054 #endif //PAL_UNIQUE_THREAD_PRIORITY
00055 
00056 #define PAL_SHA256_DEVICE_KEY_SIZE_IN_BYTES 32
00057 #define PAL_DEVICE_KEY_SIZE_IN_BYTES 16
00058 #define PAL_DEVICE_KEY_SIZE_IN_BITS (PAL_DEVICE_KEY_SIZE_IN_BYTES * 8)
00059 
00060 /*! Initiate a system reboot.
00061 */
00062 void pal_plat_osReboot (void);
00063 
00064 /*! Initialize all data structures (semaphores, mutexes, memory pools, message queues) at system initialization.
00065 *   In case of a failure in any of the initializations, the function returns an error and stops the rest of the initializations.
00066 * @param[in] opaqueContext The context passed to the initialization (not required for generic CMSIS, pass NULL in this case).
00067 * \return PAL_SUCCESS(0) in case of success, PAL_ERR_CREATION_FAILED in case of failure.
00068 */
00069 palStatus_t pal_plat_RTOSInitialize (void* opaqueContext);
00070 
00071 /*! De-initialize thread objects.
00072 */
00073 palStatus_t pal_plat_RTOSDestroy (void);
00074 
00075 /*! Get the RTOS kernel system timer counter.
00076 *
00077 * \return The RTOS kernel system timer counter.
00078 *
00079 * \note The required tick counter is the OS (platform) kernel system tick counter.
00080 * \note If the platform supports 64-bit tick counter, please implement it. If the platform supports only 32 bit, note
00081 *       that this counter wraps around very often (for example, once every 42 sec for 100Mhz).
00082 */
00083 uint64_t pal_plat_osKernelSysTick (void);
00084 
00085 /*! Convert the value from microseconds to kernel sys ticks.
00086 * This is the same as CMSIS macro `osKernelSysTickMicroSec`.
00087 */
00088 uint64_t pal_plat_osKernelSysTickMicroSec (uint64_t microseconds);
00089 
00090 /*! Get the system tick frequency.
00091 * \return The system tick frequency.
00092 *
00093 * \note The system tick frequency MUST be more than 1KHz (at least one tick per millisecond).
00094 */
00095 uint64_t pal_plat_osKernelSysTickFrequency (void);
00096 
00097 /*! Create and start a thread function.
00098 *
00099 * @param[in] function A function pointer to the thread callback function.
00100 * @param[in] funcArgument An argument for the thread function.
00101 * @param[in] priority The priority of the thread.
00102 * @param[in] stackSize The stack size of the thread.
00103 * @param[in] stackPtr A pointer to the thread's stack.
00104 * @param[in] store A pointer to thread's local store, can be NULL.
00105 * @param[out] threadID The created thread ID handle, zero indicates an error.
00106 *
00107 * \return The ID of the created thread. In case of error, returns zero.
00108 * \note Each thread MUST have a unique priority.
00109 * \note When the priority of the created thread function is higher than the current running thread, the 
00110 *       created thread function starts instantly and becomes the new running thread. 
00111 * \note The create function MUST not wait for platform resources and it should return PAL_ERR_RTOS_RESOURCE, unless the platform API is blocking.
00112 */
00113 palStatus_t pal_plat_osThreadCreate (palThreadFuncPtr function, void* funcArgument, palThreadPriority_t priority, uint32_t stackSize, uint32_t* stackPtr, palThreadLocalStore_t* store, palThreadID_t* threadID);
00114 
00115 /*! Terminate and free allocated data for the thread.
00116 *
00117 * @param[in] threadID The ID of the thread to stop and terminate.
00118 *
00119 * \return PAL_SUCCESS(0) in case of success. A negative value indicating a specific error code in case of failure.
00120 */
00121 palStatus_t pal_plat_osThreadTerminate (palThreadID_t* threadID);
00122 
00123 /*! Get the ID of the current thread.
00124 * \return The ID of the current thread. In case of error, returns PAL_MAX_UINT32.
00125 * \note For a thread with real time priority, the function always returns PAL_MAX_UINT32.
00126 */
00127 palThreadID_t pal_plat_osThreadGetId (void);
00128 
00129 /*! Get the storage of the current thread.
00130 * \return The storage of the current thread.
00131 */
00132 palThreadLocalStore_t* pal_plat_osThreadGetLocalStore (void);
00133 
00134 /*! Wait for a specified period of time in milliseconds.
00135 *
00136 * @param[in] milliseconds The number of milliseconds to wait before proceeding.
00137 *
00138 * \return PAL_SUCCESS(0) in case of success. A negative value indicating a specific error code in case of failure.
00139 */
00140 palStatus_t pal_plat_osDelay (uint32_t milliseconds);
00141 
00142 /*! Create a timer.
00143 *
00144 * @param[in] function A function pointer to the timer callback function.
00145 * @param[in] funcArgument An argument for the timer callback function.
00146 * @param[in] timerType The timer type to be created, periodic or `oneShot`.
00147 * @param[out] timerID The ID of the created timer. Zero value indicates an error.
00148 *
00149 * \return PAL_SUCCESS when the timer was created successfully. A specific error in case of failure. \n
00150 *         PAL_ERR_NO_MEMORY: No memory resource available to create a timer object.
00151 *
00152 * \note The timer callback function runs according to the platform resources of stack size and priority.
00153 * \note The create function MUST not wait for platform resources and it should return PAL_ERR_RTOS_RESOURCE, unless the platform API is blocking.
00154 */
00155 palStatus_t pal_plat_osTimerCreate (palTimerFuncPtr function, void* funcArgument, palTimerType_t timerType, palTimerID_t* timerID);
00156 
00157 /*! Start or restart a timer.
00158 *
00159 * @param[in] timerID The handle for the timer to start.
00160 * @param[in] millisec: The time in milliseconds to set the timer to, MUST be larger than 0.
00161 *                      In case the value is 0, the error PAL_ERR_RTOS_VALUE will be returned.
00162 *
00163 * \return PAL_SUCCESS(0) in case of success. A negative value indicating a specific error code in case of failure.
00164 */
00165 palStatus_t pal_plat_osTimerStart (palTimerID_t timerID, uint32_t millisec);
00166 
00167 /*! Stop a timer.
00168 *
00169 * @param[in] timerID The handle for the timer to stop.
00170 *
00171 * \return PAL_SUCCESS(0) in case of success. A negative value indicating a specific error code in case of failure.
00172 */
00173 palStatus_t pal_plat_osTimerStop (palTimerID_t timerID);
00174 
00175 /*! Delete the timer object.
00176 *
00177 * @param[inout] timerID The handle for the timer to delete. In success, `*timerID` = NULL.
00178 *
00179 * \return PAL_SUCCESS when the timer was deleted successfully. PAL_ERR_RTOS_PARAMETER when the `timerID` is incorrect.
00180 * \note In case of a running timer, `pal_platosTimerDelete()` MUST stop the timer before deletion.
00181 */
00182 palStatus_t pal_plat_osTimerDelete (palTimerID_t* timerID);
00183 
00184 /*! Create and initialize a mutex object.
00185 *
00186 * @param[out] mutexID The created mutex ID handle, zero value indicates an error.
00187 *
00188 * \return PAL_SUCCESS when the mutex was created successfully, a specific error in case of failure. \n
00189 *         PAL_ERR_NO_MEMORY when there is no memory resource available to create a mutex object.
00190 * \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.
00191 *        By default, the mutex is created with a recursive flag set.
00192 */
00193 palStatus_t pal_plat_osMutexCreate (palMutexID_t* mutexID);
00194 
00195 /*! Wait until a mutex becomes available.
00196 *
00197 * @param[in] mutexID The handle for the mutex.
00198 * @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.
00199 *
00200 * \return PAL_SUCCESS(0) in case of success. One of the following error codes in case of failure: \n
00201 *         - PAL_ERR_RTOS_RESOURCE - Mutex not available but no timeout set. \n
00202 *         - PAL_ERR_RTOS_TIMEOUT - Mutex was not available until timeout expired. \n
00203 *         - PAL_ERR_RTOS_PARAMETER - The mutex ID is invalid. \n
00204 *         - PAL_ERR_RTOS_ISR - Cannot be called from interrupt service routines.
00205 */
00206 palStatus_t pal_plat_osMutexWait (palMutexID_t mutexID, uint32_t millisec);
00207 
00208 /*! Release a mutex that was obtained by `osMutexWait`.
00209 *
00210 * @param[in] mutexID The handle for the mutex.
00211 *
00212 * \return PAL_SUCCESS(0) in case of success. A negative value indicating a specific error code in case of failure.
00213 */
00214 palStatus_t pal_plat_osMutexRelease (palMutexID_t mutexID);
00215 
00216 /*! Delete a mutex object.
00217 *
00218 * @param[inout] mutexID The ID of the mutex to delete. In success, `*mutexID` = NULL.
00219 *
00220 * \return PAL_SUCCESS when the mutex was deleted successfully, one of the following error codes in case of failure: \n
00221 *         - PAL_ERR_RTOS_RESOURCE - Mutex already released. \n
00222 *         - PAL_ERR_RTOS_PARAMETER - Mutex ID is invalid. \n
00223 *         - PAL_ERR_RTOS_ISR - Cannot be called from interrupt service routines.
00224 * \note After this call, `mutex_id` is no longer valid and cannot be used.
00225 */
00226 palStatus_t pal_plat_osMutexDelete (palMutexID_t* mutexID);
00227 
00228 /*! Create and initialize a semaphore object.
00229 *
00230 * @param[in] count The number of available resources.
00231 * @param[out] semaphoreID The ID of the created semaphore, zero value indicates an error.
00232 *
00233 * \return PAL_SUCCESS when the semaphore was created successfully, a specific error in case of failure. \n
00234 *         PAL_ERR_NO_MEMORY: No memory resource available to create a semaphore object.
00235 * \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.
00236 */
00237 palStatus_t pal_plat_osSemaphoreCreate (uint32_t count, palSemaphoreID_t* semaphoreID);
00238 
00239 /*! Wait until a semaphore token becomes available.
00240 *
00241 * @param[in] semaphoreID The handle for the semaphore.
00242 * @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.
00243 * @param[out] countersAvailable The number of semaphores available. If semaphores are not available (timeout/error) zero is returned. 
00244 * \return PAL_SUCCESS(0) in case of success. One of the following error codes in case of failure: \n
00245 *       - PAL_ERR_RTOS_TIMEOUT - Semaphore was not available until timeout expired. \n
00246 *       - PAL_ERR_RTOS_PARAMETER - Semaphore ID is invalid.
00247 */
00248 palStatus_t pal_plat_osSemaphoreWait (palSemaphoreID_t semaphoreID, uint32_t millisec, int32_t* countersAvailable);
00249 
00250 /*! Release a semaphore token.
00251 *
00252 * @param[in] semaphoreID The handle for the semaphore.
00253 *
00254 * \return PAL_SUCCESS(0) in case of success. A negative value indicating a specific error code in case of failure.
00255 */
00256 palStatus_t pal_plat_osSemaphoreRelease (palSemaphoreID_t semaphoreID);
00257 
00258 /*! Delete a semaphore object.
00259 *
00260 * @param[inout] semaphoreID: The ID of the semaphore to delete. In success, `*semaphoreID` = NULL.
00261 *
00262 * \return PAL_SUCCESS when the semaphore was deleted successfully. One of the following error codes in case of failure: \n
00263 *         PAL_ERR_RTOS_RESOURCE - Semaphore already released. \n
00264 *         PAL_ERR_RTOS_PARAMETER - Semaphore ID is invalid.
00265 * \note After this call, the `semaphore_id` is no longer valid and cannot be used.
00266 */
00267 palStatus_t pal_plat_osSemaphoreDelete (palSemaphoreID_t* semaphoreID);
00268 
00269 /*! Create and initialize a memory pool.
00270 *
00271 * @param[in] blockSize The size of a single block in bytes.
00272 * @param[in] blockCount The maximum number of blocks in the memory pool.
00273 * @param[out] memoryPoolID The ID of the created memory pool. Zero value indicates an error.
00274 *
00275 * \return PAL_SUCCESS when the memory pool was created successfully. A specific error in case of failure. \n
00276 *         PAL_ERR_NO_MEMORY when no memory resource is available to create a memory pool object.
00277 * \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.
00278 */
00279 palStatus_t pal_plat_osPoolCreate (uint32_t blockSize, uint32_t blockCount, palMemoryPoolID_t* memoryPoolID);
00280 
00281 /*! Allocate a single memory block from a memory pool.
00282 *
00283 * @param[in] memoryPoolID The handle for the memory pool.
00284 *
00285 * \return A pointer to a single allocated memory from the pool, NULL in case of failure.
00286 */
00287 void* pal_plat_osPoolAlloc (palMemoryPoolID_t memoryPoolID);
00288 
00289 /*! Allocate a single memory block from a memory pool and set the memory block to zero.
00290 *
00291 * @param[in] memoryPoolID The handle for the memory pool.
00292 *
00293 * \return A pointer to a single allocated memory from the pool, NULL in case of failure.
00294 */
00295 void* pal_plat_osPoolCAlloc (palMemoryPoolID_t memoryPoolID);
00296 
00297 /*! Return the memoryPoolID of the memory block back to a specific memory pool.
00298 *
00299 * @param[in] memoryPoolID The handle for the memory pool.
00300 * @param[in] block The block to be freed.
00301 *
00302 * \return PAL_SUCCESS(0) in case of success. A negative value indicating a specific error code in case of failure.
00303 */
00304 palStatus_t pal_plat_osPoolFree (palMemoryPoolID_t memoryPoolID, void* block);
00305 
00306 /*! Delete a memory pool object.
00307 *
00308 * @param[inout] memoryPoolID The handle for the memory pool. In success, `*memoryPoolID` = NULL.
00309 *
00310 * \return PAL_SUCCESS(0) in case of success. A negative value indicating a specific error code in case of failure.
00311 */
00312 palStatus_t pal_plat_osPoolDestroy (palMemoryPoolID_t* memoryPoolID);
00313 
00314 /*! Create and initialize a message queue.
00315 *
00316 * @param[in] messageQCount The size of the message queue.
00317 * @param[out] messageQID The ID of the created message queue, zero value indicates an error.
00318 *
00319 * \return PAL_SUCCESS when the message queue was created successfully. A specific error in case of failure. \n
00320 *         PAL_ERR_NO_MEMORY when there is no memory resource available to create a message queue object.
00321 * \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.
00322 */
00323 palStatus_t pal_plat_osMessageQueueCreate (uint32_t messageQCount, palMessageQID_t* messageQID);
00324 
00325 /*! Put a message to a queue.
00326 *
00327 * @param[in] messageQID The handle for the message queue.
00328 * @param[in] info The data to send.
00329 * @param[in] timeout The timeout in milliseconds.
00330 *
00331 * \return PAL_SUCCESS(0) in case of success. A negative value indicating a specific error code in case of failure.
00332 */
00333 palStatus_t pal_plat_osMessagePut (palMessageQID_t messageQID, uint32_t info, uint32_t timeout);
00334 
00335 /*! Get a message or wait for a message from a queue.
00336 *
00337 * @param[in] messageQID The handle for the message queue.
00338 * @param[in] timeout The timeout in milliseconds.
00339 * @param[out] messageValue The data to send.
00340 *
00341 * \return PAL_SUCCESS(0) in case of success. One of the following error codes in case of failure: \n
00342 * - PAL_ERR_RTOS_RESOURCE - Semaphore was not available but not due to timeout. \n
00343 * - PAL_ERR_RTOS_TIMEOUT -  No message arrived during the timeout period. \n
00344 * - PAL_ERR_RTOS_RESOURCE -  No message received and there was no timeout.
00345 */
00346 palStatus_t pal_plat_osMessageGet (palMessageQID_t messageQID, uint32_t timeout, uint32_t* messageValue);
00347 
00348 /*! Delete a message queue object.
00349 *
00350 * @param[inout] messageQID The handle for the message queue. In success, `*messageQID` = NULL.
00351 *
00352 * \return PAL_SUCCESS(0) in case of success. A negative value indicating a specific error code in case of failure.
00353 */
00354 palStatus_t pal_plat_osMessageQueueDestroy (palMessageQID_t* messageQID);
00355 
00356 /*! Perform an atomic increment for a signed32 bit value.
00357 *
00358 * @param[in,out] valuePtr The address of the value to increment.
00359 * @param[in] increment The number by which to increment.
00360 *
00361 * \returns The value of the `valuePtr` after the increment operation.
00362 */
00363 int32_t pal_plat_osAtomicIncrement (int32_t* valuePtr, int32_t increment);
00364 
00365 /*! Perform allocation from the heap according to the OS specification.
00366 *
00367 * @param[in] len The length of the buffer to be allocated.
00368 *
00369 * \returns `void *`. The pointer of the malloc received from the OS if NULL error occurred
00370 */
00371 void *pal_plat_malloc (size_t len);
00372 
00373 /*! Free memory back to the OS heap.
00374 *
00375 * @param[in] *buffer A pointer to the buffer that should be free.
00376 *
00377 * \returns `void`
00378 */
00379  void pal_plat_free (void * buffer);
00380 
00381 /*! Generate a random number into the given buffer with the given size in bytes.
00382 *
00383 * @param[out] randomBuf A buffer to hold the generated number.
00384 * @param[in] bufSizeBytes The size of the buffer and the size of the required random number to generate.
00385 *
00386 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00387 */
00388 palStatus_t pal_plat_osRandomBuffer (uint8_t *randomBuf, size_t bufSizeBytes);
00389 
00390 
00391 /*! Retrieve platform Root of Trust certificate
00392 *
00393 * @param[in,out] *keyBuf A pointer to the buffer that holds the RoT.
00394 * @param[in] keyLenBytes The size of the buffer to hold the 128 bit key, must be at least 16 bytes.
00395 * The buffer needs to be able to hold 16 bytes of data.
00396 *
00397 * \return PAL_SUCCESS(0) in case of success. A negative value indicating a specific error code in case of failure.
00398 */
00399 
00400 palStatus_t pal_plat_osGetRoT128Bit (uint8_t *keyBuf, size_t keyLenBytes);
00401 
00402 #ifdef __cplusplus
00403 }
00404 #endif
00405 #endif //_PAL_COMMON_H