pal_rtos.h

00001 // ----------------------------------------------------------------------------
00002 // Copyright 2016-2019 ARM Ltd.
00003 //
00004 // SPDX-License-Identifier: Apache-2.0
00005 //
00006 // Licensed under the Apache License, Version 2.0 (the "License");
00007 // you may not use this file except in compliance with the License.
00008 // You may obtain a copy of the License at
00009 //
00010 //     http://www.apache.org/licenses/LICENSE-2.0
00011 //
00012 // Unless required by applicable law or agreed to in writing, software
00013 // distributed under the License is distributed on an "AS IS" BASIS,
00014 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00015 // See the License for the specific language governing permissions and
00016 // limitations under the License.
00017 // ----------------------------------------------------------------------------
00018 
00019 #ifndef _PAL_RTOS_H
00020 #define _PAL_RTOS_H
00021 
00022 #ifndef _PAL_H
00023     #error "Please do not include this file directly, use pal.h instead"
00024 #endif
00025 
00026 #include <stdint.h>
00027 #include <string.h> //memcpy
00028 
00029 
00030 #ifdef __cplusplus
00031 extern "C" {
00032 #endif
00033 
00034 #include "pal.h" //added for PAL_INITIAL_RANDOM_SIZE value
00035 
00036 /*! \file pal_rtos.h
00037  *  \brief PAL RTOS.
00038  *  This file contains the real-time OS APIs and is a part of the PAL service API.
00039  *
00040 *   Random API is also provided.  
00041  *   as well as random API and ROT (root of trust).
00042  */
00043 
00044 
00045 //! Wait forever define. Used for semaphores and mutexes.
00046 #define PAL_TICK_TO_MILLI_FACTOR 1000
00047 
00048 //! Primitive ID type declarations.
00049 typedef uintptr_t palThreadID_t;
00050 typedef uintptr_t palTimerID_t;
00051 typedef uintptr_t palMutexID_t;
00052 typedef uintptr_t palSemaphoreID_t;
00053 typedef uintptr_t palMemoryPoolID_t;
00054 typedef uintptr_t palMessageQID_t;
00055 
00056 //! Timer types supported in PAL.
00057 typedef enum  palTimerType {
00058     palOsTimerOnce  = 0, /*!< One-shot timer. */
00059     palOsTimerPeriodic  = 1 /*!< Periodic (repeating) timer. */
00060 } palTimerType_t;
00061 
00062 
00063 //! PAL timer function prototype.
00064 typedef void(*palTimerFuncPtr)(void const *funcArgument);
00065 
00066 //! PAL thread function prototype.
00067 typedef void(*palThreadFuncPtr)(void const *funcArgument);
00068 
00069 //! \enum pal_osPriority Available priorities in PAL implementation, each priority can appear only once.
00070 typedef enum pal_osPriority {
00071     PAL_osPriorityFirst = 0,
00072     PAL_osPriorityIdle = PAL_osPriorityFirst,
00073     PAL_osPriorityLow = 1,
00074     PAL_osPriorityReservedTRNG = 2,
00075     PAL_osPriorityBelowNormal = 3,
00076     PAL_osPriorityNormal = 4,
00077     PAL_osPriorityAboveNormal = 5,
00078     PAL_osPriorityReservedDNS  = 6, /*!< Reserved for PAL's internal use */
00079     PAL_osPriorityReservedSockets  = 7, /*!< Reserved for PAL's internal use */
00080     PAL_osPriorityHigh = 8,
00081     PAL_osPriorityReservedHighResTimer  = 9, /*!< Reserved for PAL's internal use */
00082     PAL_osPriorityRealtime = 10,
00083     PAL_osPrioritylast = PAL_osPriorityRealtime,
00084     PAL_osPriorityError = 0x84
00085 } palThreadPriority_t; /*!< \brief Thread priority levels for PAL threads - each thread must have a different priority. */
00086 
00087 //! \brief Thread local store struct.
00088 //!
00089 //! Can be used to hold, for example, state and configurations inside the thread.
00090 typedef struct pal_threadLocalStore{
00091     void* storeData;
00092 } palThreadLocalStore_t;
00093 
00094 typedef struct pal_timeVal{
00095     int32_t    pal_tv_sec;      /*!< \brief Seconds. */
00096     int32_t    pal_tv_usec;     /*!< \brief Microseconds. */
00097 } pal_timeVal_t;
00098 
00099 
00100 //------- system general functions
00101 /*! \brief Initiates a system reboot.
00102 *
00103 * Applications can provide their own implementation by defining PAL_USE_APPLICATION_REBOOT and
00104 * providing the implementation for \c pal_plat_osApplicationReboot() function.
00105 */
00106 void pal_osReboot(void);
00107 
00108 //------- system tick functions
00109 /*! \brief Get the RTOS kernel system timer counter.
00110 * \note The system needs to supply a 64-bit tick counter. If only a 32-bit counter is supported,
00111 *       the counter wraps around very often (for example, once every 42 sec for 100Mhz).
00112 * \return The RTOS kernel system timer counter.
00113 */
00114 uint64_t pal_osKernelSysTick(void);
00115 
00116 
00117 /*! \brief Converts a value from microseconds to kernel system ticks.
00118 *
00119 * @param[in] microseconds The number of microseconds to convert into system ticks.
00120 *
00121 * \return Converted value in system ticks.
00122 */
00123 uint64_t pal_osKernelSysTickMicroSec(uint64_t microseconds);
00124 
00125 /*! \brief Converts kernel system ticks to milliseconds.
00126 *
00127 * @param[in] sysTicks The number of kernel system ticks to convert into milliseconds.
00128 *
00129 * \return Converted value in milliseconds.
00130 */
00131 uint64_t pal_osKernelSysMilliSecTick(uint64_t sysTicks);
00132 
00133 /*! \brief Get the system tick frequency.
00134 * \return The system tick frequency.
00135 *
00136 * \note The system tick frequency MUST be more than 1KHz. In other words, there must be at least one tick per millisecond.
00137 */
00138 uint64_t pal_osKernelSysTickFrequency(void);
00139 
00140 /*! \brief Allocates memory for the thread stack, creates and starts the thread function inside the PAL platform wrapper function.
00141 *
00142 * @param[in] function A function pointer to the thread callback function.
00143 * @param[in] funcArgument An argument for the thread function.
00144 * @param[in] priority The priority of the thread.
00145 * @param[in] stackSize The stack size of the thread, can NOT be 0.
00146 * @param[in] store \b MUST be `NULL` - this functionality is not supported.
00147 * @param[out] threadID: The created thread ID handle. In case of error, this value is `NULL`.
00148 *
00149 * \return PAL_SUCCESS when the thread was created successfully.
00150 *
00151 * \note When the priority of the created thread function is higher than the current running thread, the
00152 *       created thread function starts instantly and becomes the new running thread.
00153 * \note Calling \c pal_osThreadTerminate() releases the thread stack.
00154 */
00155 palStatus_t pal_osThreadCreateWithAlloc(palThreadFuncPtr function, void* funcArgument, palThreadPriority_t priority, uint32_t stackSize, palThreadLocalStore_t* store, palThreadID_t* threadID);
00156 
00157 /*! \brief Terminate the thread and free the data allocated for it.
00158 *
00159 * @param[in] threadID The thread ID to stop and terminate.
00160 *
00161 * \return PAL_SUCCESS(0) in case of success, and a negative value indicating a specific error code in case of failure.
00162 *
00163 * \note  \c pal_osThreadTerminate is a non-blocking operation. It sends a cancellation request to the thread,
00164 *        and usually the thread exits immediately, but the system does not always guarantee this.
00165 */
00166 palStatus_t pal_osThreadTerminate(palThreadID_t* threadID);
00167 
00168 /*! \brief Get the ID of the current thread.
00169 * \return The ID of the current thread.
00170 * \return PAL_MAX_UINT32 in case of error.
00171 */
00172 palThreadID_t pal_osThreadGetId(void);
00173 
00174 /*! \brief Wait for a specified time period in milliseconds.
00175 *
00176 * @param[in] milliseconds The number of milliseconds to wait before proceeding.
00177 *
00178 * \return PAL_SUCCESS(0) in case of success, and a negative value indicating a specific error code in case of failure.
00179 */
00180 palStatus_t pal_osDelay(uint32_t milliseconds);
00181 
00182 /*! \brief Create a timer.
00183 *
00184 * @param[in] function A function pointer to the timer callback function.
00185 * @param[in] funcArgument An argument for the timer callback function.
00186 * @param[in] timerType The timer type to be created, either periodic or one-shot.
00187 * @param[out] timerID The ID handle for the created timer. In case of error, this value is `NULL`.
00188 *
00189 * \return PAL_SUCCESS when the timer was created successfully.
00190 * \return PAL_ERR_NO_MEMORY when there is no memory resource available to create a timer object.
00191 *
00192 * \note The timer function runs according to the platform resources of stack-size and priority.
00193 */
00194 palStatus_t pal_osTimerCreate(palTimerFuncPtr function, void* funcArgument, palTimerType_t timerType, palTimerID_t* timerID);
00195 
00196 /*! \brief Start or restart a timer.
00197 *
00198 * @param[in] timerID The ID handle for the timer to start or restart.
00199 * @param[in] millisec The length of time in milliseconds to set the timer to. MUST be larger than 0.
00200 *
00201 * \return PAL_ERR_RTOS_VALUE In case the value of \c millisec was \c 0 .
00202 * \return PAL_SUCCESS(0) in case of success, and a negative value indicating a specific error code in case of failure.
00203 */
00204 palStatus_t pal_osTimerStart(palTimerID_t timerID, uint32_t millisec);
00205 
00206 /*! \brief Stop a timer.
00207 * @param[in] timerID The ID handle for the timer to stop.
00208 * \return PAL_SUCCESS(0) in case of success, and a negative value indicating a specific error code in case of failure.
00209 */
00210 palStatus_t pal_osTimerStop(palTimerID_t timerID);
00211 
00212 /*! \brief Delete a timer object.
00213 *
00214 * @param[in,out] timerID The ID handle for the timer to delete. On success, `*timerID` is changed to `NULL`.
00215 *
00216 * \return PAL_SUCCESS when timer was deleted successfully.
00217 * \return PAL_ERR_RTOS_PARAMETER when the `timerID` is incorrect.
00218 */
00219 palStatus_t pal_osTimerDelete(palTimerID_t* timerID);
00220 
00221 /*! \brief Create and initialize a mutex object.
00222 *
00223 * @param[out] mutexID The created mutex ID handle. In case of error, this value is `NULL`.
00224 *
00225 * \return PAL_SUCCESS when the mutex was created successfully.
00226 * \return PAL_ERR_NO_MEMORY when there is no memory resource available to create a mutex object.
00227 */
00228 palStatus_t pal_osMutexCreate(palMutexID_t* mutexID);
00229 
00230 /*! \brief Wait until a mutex becomes available.
00231 *
00232 * @param[in] mutexID The handle for the mutex.
00233 * @param[in] millisec The timeout for waiting for the mutex to be available. PAL_RTOS_WAIT_FOREVER can be used as a parameter.
00234 *
00235 * \return PAL_SUCCESS(0) in case of success.
00236 * \return PAL_ERR_RTOS_RESOURCE Failure - mutex was not availabe but no timeout was set.
00237 * \return PAL_ERR_RTOS_TIMEOUT Failure - mutex was not available before timeout.
00238 * \return PAL_ERR_RTOS_PARAMETER Failure - mutex ID is invalid.
00239 * \return PAL_ERR_RTOS_ISR Failure - cannot be called from the interrupt service routines.
00240 */
00241 palStatus_t pal_osMutexWait(palMutexID_t mutexID, uint32_t millisec);
00242 
00243 /*! \brief Release a mutex that was obtained by `osMutexWait`.
00244 *
00245 * @param[in] mutexID The handle for the mutex.
00246 * \return PAL_SUCCESS(0) in case of success, or another negative value indicating a specific error code in case of failure.
00247 */
00248 palStatus_t pal_osMutexRelease(palMutexID_t mutexID);
00249 
00250 /*! \brief Delete a mutex object.
00251 *
00252 * @param[in,out] mutexID The mutex handle to delete. On success, `*mutexID` is changed to `NULL`.
00253 *
00254 * \return PAL_SUCCESS when the mutex was deleted successfully.
00255 * \return PAL_ERR_RTOS_RESOURCE Failure - mutex is already released.
00256 * \return PAL_ERR_RTOS_PARAMETER Failure - mutex ID is invalid.
00257 * \return PAL_ERR_RTOS_ISR Failure - cannot be called from the interrupt service routines.
00258 * \note After this call, the `mutexID` is no longer valid and cannot be used.
00259 */
00260 palStatus_t pal_osMutexDelete(palMutexID_t* mutexID);
00261 
00262 /*! \brief Create and initialize a semaphore object.
00263 *
00264 * @param[in] count The number of available resources.
00265 * @param[out] semaphoreID The created semaphore ID handle. In case of error, this value is `NULL`.
00266 *
00267 * \return PAL_SUCCESS when the semaphore was created successfully.
00268 * \return PAL_ERR_NO_MEMORY when there is no memory resource available to create a semaphore object.
00269 */
00270 palStatus_t pal_osSemaphoreCreate(uint32_t count, palSemaphoreID_t* semaphoreID);
00271 
00272 /*! \brief Wait until a semaphore token becomes available.
00273 *
00274 * @param[in] semaphoreID The handle for the semaphore.
00275 * @param[in] millisec The timeout for the waiting operation. If the timeout
00276                        expires before the semaphore is released, an error is
00277                        returned from the function. PAL_RTOS_WAIT_FOREVER can be used.
00278 * @param[out] countersAvailable The number of semaphores available at the call if a
00279                                   semaphore is available. If the semaphore is not available due to timeout or error, `0` is returned. This parameter can be NULL
00280 * \return PAL_SUCCESS(0) in case of success.
00281 * \return PAL_ERR_RTOS_TIMEOUT Failure - the semaphore was not available until timeout.
00282 * \return PAL_ERR_RTOS_PARAMETER Failure - the semaphore ID is invalid.
00283 */
00284 palStatus_t pal_osSemaphoreWait(palSemaphoreID_t semaphoreID, uint32_t millisec, int32_t* countersAvailable);
00285 
00286 /*! \brief Release a semaphore token.
00287 *
00288 * @param[in] semaphoreID The handle for the semaphore
00289 *
00290 * \return PAL_SUCCESS(0) in case of success, or a negative value indicating a specific error code in case of failure.
00291 */
00292 palStatus_t pal_osSemaphoreRelease(palSemaphoreID_t semaphoreID);
00293 
00294 /*! \brief Delete a semaphore object.
00295 *
00296 * @param[in,out] semaphoreID The semaphore handle to delete. On success, `*semaphoreID` is changed to `NULL`.
00297 *
00298 * \return PAL_SUCCESS when the semaphore was deleted successfully.
00299 * \return PAL_ERR_RTOS_RESOURCE Failure - the semaphore was already released. \n
00300 * \return PAL_ERR_RTOS_PARAMETER Failure - the semaphore ID is invalid.
00301 * \note After this call, the `semaphoreID` is no longer valid and cannot be used.
00302 */
00303 palStatus_t pal_osSemaphoreDelete(palSemaphoreID_t* semaphoreID);
00304 
00305 /*! \brief Perform an atomic increment for a signed 32-bit value.
00306 *
00307 * @param[in,out] valuePtr The address of the value to increment.
00308 * @param[in] increment The number by which to increment.
00309 *
00310 * \return The value of `valuePtr` after the increment operation.
00311 */
00312 int32_t pal_osAtomicIncrement(int32_t* valuePtr, int32_t increment);
00313 
00314 /*! Initialize the RTOS module for PAL.
00315  * This function can be called only once before running the system.
00316  * To remove PAL from the system, call `pal_RTOSDestroy`.
00317  * After calling `pal_RTOSDestroy`, you can call `pal_RTOSInitialize` again.
00318 *
00319 * @param[in] opaqueContext: context to be passed to the platform if needed.
00320 *
00321 * \return PAL_SUCCESS upon success.
00322 */
00323 palStatus_t pal_RTOSInitialize(void* opaqueContext);
00324 
00325 
00326 /*! This function removes PAL from the system and can be called after `pal_RTOSInitialize`.
00327 **
00328 * \return PAL_SUCCESS upon success. \n
00329 *         PAL_ERR_NOT_INITIALIZED - if the user did not call `pal_RTOSInitialize()` first.
00330 */
00331 palStatus_t pal_RTOSDestroy(void);
00332 
00333 
00334 
00335 #ifdef __cplusplus
00336 }
00337 #endif
00338 #endif //_PAL_RTOS_H