Important changes to repositories hosted on mbed.com
Mbed hosted mercurial repositories are deprecated and are due to be permanently deleted in July 2026.
To keep a copy of this software download the repository Zip archive or clone locally using Mercurial.
It is also possible to export all your personal repositories from the account settings page.
Dependencies: FXAS21002 FXOS8700Q
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 00034 00035 /*! \brief Initiate a system reboot. 00036 */ 00037 void pal_plat_osReboot(void); 00038 00039 /*! \brief Application provided implementation to replace default `pal_osReboot()` functionality. 00040 */ 00041 void pal_plat_osApplicationReboot(void); 00042 00043 /*! \brief Initialize all data structures (semaphores, mutexes, memory pools, message queues) at system initialization. 00044 * 00045 * In case of a failure in any of the initializations, the function returns an error and stops the rest of the initializations. 00046 * @param[in] opaqueContext The context passed to the initialization (not required for generic CMSIS, pass NULL in this case). 00047 * \return PAL_SUCCESS(0) in case of success, PAL_ERR_CREATION_FAILED in case of failure. 00048 */ 00049 palStatus_t pal_plat_RTOSInitialize(void* opaqueContext); 00050 00051 /*! \brief De-initialize thread objects. 00052 */ 00053 palStatus_t pal_plat_RTOSDestroy(void); 00054 00055 /*! \brief Get the RTOS kernel system timer counter. 00056 * 00057 * \return The RTOS kernel system timer counter. 00058 * 00059 * \note The required tick counter is the OS (platform) kernel system tick counter. 00060 * 00061 * \note If the platform supports 64-bit tick counter, please implement it. If the platform supports only 32 bit, note 00062 * that this counter wraps around very often, once every 42 sec for 100Mhz, for example. 00063 */ 00064 uint64_t pal_plat_osKernelSysTick(void); 00065 00066 /*! \brief Convert the value from microseconds to kernel system ticks. 00067 * 00068 * This is the same as CMSIS macro `osKernelSysTickMicroSec`. 00069 * @param microseconds The value in microseconds to be converted to kernel system ticks. 00070 */ 00071 uint64_t pal_plat_osKernelSysTickMicroSec(uint64_t microseconds); 00072 00073 /*! \brief Get the system tick frequency. 00074 * \return The system tick frequency. 00075 * 00076 * \note The system tick frequency MUST be more than 1KHz, so at least one tick per millisecond. 00077 */ 00078 uint64_t pal_plat_osKernelSysTickFrequency(void); 00079 00080 /*! \brief Create and run the thread. 00081 * 00082 * @param[in] function A function pointer to the thread callback function. 00083 * @param[in] funcArgument An argument for the thread function. 00084 * @param[in] priority The priority of the thread. 00085 * @param[in] stackSize The stack size of the thread in bytes, can NOT be 0. 00086 * @param[out] threadID: The created thread ID handle. In case of error, this value is NULL. 00087 * 00088 * \return PAL_SUCCESS(0) in case of success. A negative value indicating a specific error code in case of failure. 00089 * 00090 */ 00091 palStatus_t pal_plat_osThreadCreate(palThreadFuncPtr function, void* funcArgument, palThreadPriority_t priority, uint32_t stackSize, palThreadID_t* threadID); 00092 00093 /*! \brief Terminate and free allocated data for the thread. 00094 * 00095 * @param[in] threadID A pointer to a palThreadData_t structure containing information about the thread. 00096 * 00097 * \return PAL_SUCCESS(0) in case of success. A negative value indicating a specific error code in case of failure. 00098 * 00099 */ 00100 palStatus_t pal_plat_osThreadTerminate(palThreadID_t* threadID); 00101 00102 /*! \brief Get the ID of the current thread. 00103 * \return The ID of the current thread. In case of error, returns PAL_MAX_UINT32. 00104 */ 00105 palThreadID_t pal_plat_osThreadGetId(void); 00106 00107 /*! \brief Wait for a specified period of time in milliseconds. 00108 * 00109 * @param[in] milliseconds The number of milliseconds to wait before proceeding. 00110 * 00111 * \return PAL_SUCCESS(0) in case of success. A negative value indicating a specific error code in case of failure. 00112 */ 00113 palStatus_t pal_plat_osDelay(uint32_t milliseconds); 00114 00115 /*! \brief Create a timer. 00116 * 00117 * @param[in] function A function pointer to the timer callback function. 00118 * @param[in] funcArgument An argument for the timer callback function. 00119 * @param[in] timerType The timer type to be created, periodic or `oneShot`. 00120 * @param[out] timerID The ID of the created timer. Zero value indicates an error. 00121 * 00122 * \return PAL_SUCCESS when the timer was created successfully. A specific error in case of failure. 00123 * \return PAL_ERR_NO_MEMORY: No memory resource available to create a timer object. 00124 * 00125 * \note The timer callback function runs according to the platform resources of stack size and priority. 00126 * \note The create function MUST not wait for platform resources and it should return PAL_ERR_RTOS_RESOURCE, unless the platform API is blocking. 00127 */ 00128 palStatus_t pal_plat_osTimerCreate(palTimerFuncPtr function, void* funcArgument, palTimerType_t timerType, palTimerID_t* timerID); 00129 00130 /*! \brief Start or restart a timer. 00131 * 00132 * @param[in] timerID The handle for the timer to start. 00133 * @param[in] millisec: The time in milliseconds to set the timer to, MUST be larger than 0. 00134 * In case the value is 0, the error PAL_ERR_RTOS_VALUE will be returned. 00135 * 00136 * \return PAL_SUCCESS(0) in case of success. A negative value indicating a specific error code in case of failure. 00137 */ 00138 palStatus_t pal_plat_osTimerStart(palTimerID_t timerID, uint32_t millisec); 00139 00140 /*! \brief Stop a timer. 00141 * 00142 * @param[in] timerID The handle for the timer to stop. 00143 * 00144 * \return PAL_SUCCESS(0) in case of success. A negative value indicating a specific error code in case of failure. 00145 */ 00146 palStatus_t pal_plat_osTimerStop(palTimerID_t timerID); 00147 00148 /*! \brief Delete the timer object. 00149 * 00150 * @param[inout] timerID The handle for the timer to delete. on success, `timerID` = NULL. 00151 * 00152 * \return PAL_SUCCESS when the timer was deleted successfully. PAL_ERR_RTOS_PARAMETER when the `timerID` is incorrect. 00153 * \note In case of a running timer, `pal_plat_osTimerDelete()` MUST stop the timer before deletion. 00154 */ 00155 palStatus_t pal_plat_osTimerDelete(palTimerID_t* timerID); 00156 00157 /*! \brief Create and initialize a mutex object. 00158 * 00159 * @param[out] mutexID The created mutex ID handle, zero value indicates an error. 00160 * 00161 * \return PAL_SUCCESS when the mutex was created successfully, a specific error in case of failure. 00162 * \return PAL_ERR_NO_MEMORY when there is no memory resource available to create a mutex object. 00163 * \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. 00164 * \note By default, the mutex is created with a recursive flag set. 00165 */ 00166 palStatus_t pal_plat_osMutexCreate(palMutexID_t* mutexID); 00167 00168 /*! \brief Wait until a mutex becomes available. 00169 * 00170 * @param[in] mutexID The handle for the mutex. 00171 * @param[in] millisec The timeout for the waiting operation. If the timeout expires before the mutex is released, an error is returned from the function. 00172 * 00173 * \return PAL_SUCCESS(0) in case of success. One of the following error codes in case of failure: \n 00174 * - PAL_ERR_RTOS_RESOURCE - Mutex not available but no timeout set. \n 00175 * - PAL_ERR_RTOS_TIMEOUT - Mutex was not available until timeout expired. \n 00176 * - PAL_ERR_RTOS_PARAMETER - The mutex ID is invalid. \n 00177 * - PAL_ERR_RTOS_ISR - Cannot be called from interrupt service routines. 00178 */ 00179 palStatus_t pal_plat_osMutexWait(palMutexID_t mutexID, uint32_t millisec); 00180 00181 /*! \brief Release a mutex that was obtained by `osMutexWait`. 00182 * 00183 * @param[in] mutexID The handle for the mutex. 00184 * 00185 * \return PAL_SUCCESS(0) in case of success. A negative value indicating a specific error code in case of failure. 00186 */ 00187 palStatus_t pal_plat_osMutexRelease(palMutexID_t mutexID); 00188 00189 /*! \brief Delete a mutex object. 00190 * 00191 * @param[in,out] mutexID The ID of the mutex to delete. In success, `mutexID` = NULL. 00192 * 00193 * \return PAL_SUCCESS when the mutex was deleted successfully, one of the following error codes in case of failure: \n 00194 * - PAL_ERR_RTOS_RESOURCE - Mutex already released. \n 00195 * - PAL_ERR_RTOS_PARAMETER - Mutex ID is invalid. \n 00196 * - PAL_ERR_RTOS_ISR - Cannot be called from interrupt service routines. 00197 * \note After this call, `mutexID` is no longer valid and cannot be used. 00198 */ 00199 palStatus_t pal_plat_osMutexDelete(palMutexID_t* mutexID); 00200 00201 /*! \brief Create and initialize a semaphore object. 00202 * 00203 * @param[in] count The number of available resources. 00204 * @param[out] semaphoreID The ID of the created semaphore, zero value indicates an error. 00205 * 00206 * \return PAL_SUCCESS when the semaphore was created successfully, a specific error in case of failure. 00207 * \return PAL_ERR_NO_MEMORY: No memory resource available to create a semaphore object. 00208 * \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. 00209 */ 00210 palStatus_t pal_plat_osSemaphoreCreate(uint32_t count, palSemaphoreID_t* semaphoreID); 00211 00212 /*! \brief Wait until a semaphore token becomes available. 00213 * 00214 * @param[in] semaphoreID The handle for the semaphore. 00215 * @param[in] millisec The timeout for the waiting operation. If the timeout expires before the semaphore is released, an error is returned from the function. 00216 * @param[out] countersAvailable The number of semaphores available. If semaphores are not available due to timeout or error, zero is returned. 00217 * \return PAL_SUCCESS(0) in case of success. One of the following error codes in case of failure: \n 00218 * - PAL_ERR_RTOS_TIMEOUT - Semaphore was not available until timeout expired. \n 00219 * - PAL_ERR_RTOS_PARAMETER - Semaphore ID is invalid. 00220 */ 00221 palStatus_t pal_plat_osSemaphoreWait(palSemaphoreID_t semaphoreID, uint32_t millisec, int32_t* countersAvailable); 00222 00223 /*! \brief Release a semaphore token. 00224 * 00225 * @param[in] semaphoreID The handle for the semaphore. 00226 * 00227 * \return PAL_SUCCESS(0) in case of success. A negative value indicating a specific error code in case of failure. 00228 */ 00229 palStatus_t pal_plat_osSemaphoreRelease(palSemaphoreID_t semaphoreID); 00230 00231 /*! \brief Delete a semaphore object. 00232 * 00233 * @param[in,out] semaphoreID: The ID of the semaphore to delete. On success, `semaphoreID` = NULL. 00234 * 00235 * \return PAL_SUCCESS when the semaphore was deleted successfully. One of the following error codes in case of failure: \n 00236 * PAL_ERR_RTOS_RESOURCE - Semaphore already released. \n 00237 * PAL_ERR_RTOS_PARAMETER - Semaphore ID is invalid. 00238 * \note After this call, the `semaphoreID` is no longer valid and cannot be used. 00239 */ 00240 palStatus_t pal_plat_osSemaphoreDelete(palSemaphoreID_t* semaphoreID); 00241 00242 00243 /*! \brief Perform an atomic increment for a signed 32-bit value. 00244 * 00245 * @param[in,out] valuePtr The address of the value to increment. 00246 * @param[in] increment The number by which to increment. 00247 * 00248 * \returns The value of the `valuePtr` after the increment operation. 00249 */ 00250 int32_t pal_plat_osAtomicIncrement(int32_t* valuePtr, int32_t increment); 00251 00252 /*! \brief Perform allocation from the heap according to the OS specification. 00253 * 00254 * @param[in] len The length of the buffer to be allocated in bytes. 00255 * 00256 * \returns `void *`, or the pointer of the malloc received from the OS if NULL error occurred 00257 */ 00258 void *pal_plat_malloc(size_t len); 00259 00260 /*! \brief Free memory back to the OS heap. 00261 * 00262 * @param[in] buffer A pointer to the buffer that should be freed. 00263 * 00264 * \returns `void` 00265 */ 00266 void pal_plat_free(void * buffer); 00267 00268 00269 /*! \brief Retrieve platform Root of Trust (RoT) certificate. 00270 * 00271 * @param[in,out] keyBuf A pointer to the buffer that holds the RoT. 00272 * @param[in] keyLenBytes The size of the buffer to hold the 128 bit key, must be at least 16 bytes. 00273 * 00274 * \return PAL_SUCCESS(0) in case of success. A negative value indicating a specific error code in case of failure. 00275 */ 00276 00277 palStatus_t pal_plat_osGetRoTFromHW(uint8_t *keyBuf, size_t keyLenBytes); 00278 00279 /*! \brief This function calls the platform layer and sets the new real-time clock (RTC) to the hardware. 00280 * 00281 * @param[in] rtcSetTime the new RTC time 00282 * 00283 * \return PAL_SUCCESS when the RTC is returned correctly. 00284 * 00285 */ 00286 palStatus_t pal_plat_osSetRtcTime(uint64_t rtcSetTime); 00287 00288 /*! \brief This function gets the real-time clock (RTC) from the platform. 00289 * 00290 * @param[out] rtcGetTime - Holds the RTC value 00291 * 00292 * \return PAL_SUCCESS when the RTC is returned correctly 00293 * 00294 */ 00295 palStatus_t pal_plat_osGetRtcTime(uint64_t *rtcGetTime); 00296 00297 00298 /*! \brief This function deinitializes the realt-time clock (RTC) module. 00299 * 00300 * \return PAL_SUCCESS when the success or error upon failing 00301 * 00302 */ 00303 palStatus_t pal_plat_rtcDeInit(void); 00304 00305 00306 /*! \brief This function initializes the real-time clock (RTC) module. 00307 * 00308 * \return PAL_SUCCESS when the success or error upon failing 00309 * 00310 */ 00311 palStatus_t pal_plat_rtcInit(void); 00312 00313 #ifdef __cplusplus 00314 } 00315 #endif 00316 #endif //_PAL_PLAT_RTOS_H
Generated on Tue Jul 12 2022 20:21:02 by
