Mayank Gupta / Mbed OS pelion-example-frdm

Dependencies:   FXAS21002 FXOS8700Q

Embed: (wiki syntax)

« Back to documentation index

Show/hide line numbers pal_plat_rtos.h Source File

pal_plat_rtos.h

Go to the documentation of this file.
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