/* * Copyright (c) 2013-2020 Arm Limited. All rights reserved. * * SPDX-License-Identifier: Apache-2.0 * * Licensed under the Apache License, Version 2.0 (the License); you may * not use this file except in compliance with the License. * You may obtain a copy of the License at * * www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an AS IS BASIS, WITHOUT * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. * * ---------------------------------------------------------------------- * * $Date: 12. June 2020 * $Revision: V2.1.3 * * Project: CMSIS-RTOS2 API * Title: cmsis_os2.h header file * * Version 2.1.3 * Additional functions allowed to be called from Interrupt Service Routines: * - osThreadGetId * Version 2.1.2 * Additional functions allowed to be called from Interrupt Service Routines: * - osKernelGetInfo, osKernelGetState * Version 2.1.1 * Additional functions allowed to be called from Interrupt Service Routines: * - osKernelGetTickCount, osKernelGetTickFreq * Changed Kernel Tick type to uint32_t: * - updated: osKernelGetTickCount, osDelayUntil * Version 2.1.0 * Support for critical and uncritical sections (nesting safe): * - updated: osKernelLock, osKernelUnlock * - added: osKernelRestoreLock * Updated Thread and Event Flags: * - changed flags parameter and return type from int32_t to uint32_t * Version 2.0.0 * Initial Release *---------------------------------------------------------------------------*/ #ifndef CMSIS_OS2_H_ #define CMSIS_OS2_H_ #ifndef __NO_RETURN #if defined(__CC_ARM) #define __NO_RETURN __declspec(noreturn) #elif defined(__ARMCC_VERSION) && (__ARMCC_VERSION >= 6010050) #define __NO_RETURN __attribute__((__noreturn__)) #elif defined(__GNUC__) #define __NO_RETURN __attribute__((__noreturn__)) #elif defined(__ICCARM__) #define __NO_RETURN __noreturn #else #define __NO_RETURN #endif #endif #include #ifdef __cplusplus extern "C" { #endif // ==== Enumerations, structures, defines ==== /// Version information. typedef struct { uint32_t api; ///< API version (major.minor.rev: mmnnnrrrr dec). uint32_t kernel; ///< Kernel version (major.minor.rev: mmnnnrrrr dec). } osVersion_t; /// Kernel state. typedef enum { osKernelInactive = 0, ///< Inactive. osKernelReady = 1, ///< Ready. osKernelRunning = 2, ///< Running. osKernelLocked = 3, ///< Locked. osKernelSuspended = 4, ///< Suspended. osKernelError = -1, ///< Error. osKernelReserved = 0x7FFFFFFF ///< Prevents enum down-size compiler optimization. } osKernelState_t; /// Timer callback function. typedef void (*osTimerFunc_t) (void *argument); /// Timer type. typedef enum { osTimerOnce = 0, ///< One-shot timer. osTimerPeriodic = 1 ///< Repeating timer. } osTimerType_t; /// \details Timer ID identifies the timer. typedef void *osTimerId_t; /// \details Message Queue ID identifies the message queue. typedef void *osMessageQueueId_t; #ifndef TZ_MODULEID_T #define TZ_MODULEID_T /// \details Data type that identifies secure software modules called by a process. typedef uint32_t TZ_ModuleId_t; #endif /// Attributes structure for timer. typedef struct { const char *name; ///< name of the timer uint32_t attr_bits; ///< attribute bits void *cb_mem; ///< memory for control block uint32_t cb_size; ///< size of provided memory for control block } osTimerAttr_t; /// Attributes structure for message queue. typedef struct { const char *name; ///< name of the message queue uint32_t attr_bits; ///< attribute bits void *cb_mem; ///< memory for control block uint32_t cb_size; ///< size of provided memory for control block void *mq_mem; ///< memory for data storage uint32_t mq_size; ///< size of provided memory for data storage } osMessageQueueAttr_t; // ==== Kernel Management Functions ==== /// Initialize the RTOS Kernel. /// \return status code that indicates the execution status of the function. osStatus_t osKernelInitialize (void); /// Get RTOS Kernel Information. /// \param[out] version pointer to buffer for retrieving version information. /// \param[out] id_buf pointer to buffer for retrieving kernel identification string. /// \param[in] id_size size of buffer for kernel identification string. /// \return status code that indicates the execution status of the function. osStatus_t osKernelGetInfo (osVersion_t *version, char *id_buf, uint32_t id_size); /// Get the current RTOS Kernel state. /// \return current RTOS Kernel state. osKernelState_t osKernelGetState (void); /// Start the RTOS Kernel scheduler. /// \return status code that indicates the execution status of the function. osStatus_t osKernelStart (void); /// Lock the RTOS Kernel scheduler. /// \return previous lock state (1 - locked, 0 - not locked, error code if negative). int32_t osKernelLock (void); /// Unlock the RTOS Kernel scheduler. /// \return previous lock state (1 - locked, 0 - not locked, error code if negative). int32_t osKernelUnlock (void); /// Restore the RTOS Kernel scheduler lock state. /// \param[in] lock lock state obtained by \ref osKernelLock or \ref osKernelUnlock. /// \return new lock state (1 - locked, 0 - not locked, error code if negative). int32_t osKernelRestoreLock (int32_t lock); /// Suspend the RTOS Kernel scheduler. /// \return time in ticks, for how long the system can sleep or power-down. uint32_t osKernelSuspend (void); /// Resume the RTOS Kernel scheduler. /// \param[in] sleep_ticks time in ticks for how long the system was in sleep or power-down mode. void osKernelResume (uint32_t sleep_ticks); /// Get the RTOS kernel tick count. /// \return RTOS kernel current tick count. uint32_t osKernelGetTickCount (void); /// Get the RTOS kernel tick frequency. /// \return frequency of the kernel tick in hertz, i.e. kernel ticks per second. uint32_t osKernelGetTickFreq (void); /// Get the RTOS kernel system timer frequency. /// \return frequency of the system timer in hertz, i.e. timer ticks per second. uint32_t osKernelGetSysTimerFreq (void); // ==== Generic Wait Functions ==== /// Wait for Timeout (Time Delay). /// \param[in] ticks \ref CMSIS_RTOS_TimeOutValue "time ticks" value /// \return status code that indicates the execution status of the function. osStatus_t osDelay (uint32_t ticks); /// Wait until specified time. /// \param[in] ticks absolute time in ticks /// \return status code that indicates the execution status of the function. osStatus_t osDelayUntil (uint32_t ticks); // ==== Timer Management Functions ==== /// Create and Initialize a timer. /// \param[in] func function pointer to callback function. /// \param[in] type \ref osTimerOnce for one-shot or \ref osTimerPeriodic for periodic behavior. /// \param[in] argument argument to the timer callback function. /// \param[in] attr timer attributes; NULL: default values. /// \return timer ID for reference by other functions or NULL in case of error. osTimerId_t osTimerNew (osTimerFunc_t func, osTimerType_t type, void *argument, const osTimerAttr_t *attr); /// Get name of a timer. /// \param[in] timer_id timer ID obtained by \ref osTimerNew. /// \return name as null-terminated string. const char *osTimerGetName (osTimerId_t timer_id); /// Start or restart a timer. /// \param[in] timer_id timer ID obtained by \ref osTimerNew. /// \param[in] ticks \ref CMSIS_RTOS_TimeOutValue "time ticks" value of the timer. /// \return status code that indicates the execution status of the function. osStatus_t osTimerStart (osTimerId_t timer_id, uint32_t ticks); /// Stop a timer. /// \param[in] timer_id timer ID obtained by \ref osTimerNew. /// \return status code that indicates the execution status of the function. osStatus_t osTimerStop (osTimerId_t timer_id); /// Check if a timer is running. /// \param[in] timer_id timer ID obtained by \ref osTimerNew. /// \return 0 not running, 1 running. uint32_t osTimerIsRunning (osTimerId_t timer_id); /// Delete a timer. /// \param[in] timer_id timer ID obtained by \ref osTimerNew. /// \return status code that indicates the execution status of the function. osStatus_t osTimerDelete (osTimerId_t timer_id); // ==== Message Queue Management Functions ==== /// Create and Initialize a Message Queue object. /// \param[in] msg_count maximum number of messages in queue. /// \param[in] msg_size maximum message size in bytes. /// \param[in] attr message queue attributes; NULL: default values. /// \return message queue ID for reference by other functions or NULL in case of error. osMessageQueueId_t osMessageQueueNew (uint32_t msg_count, uint32_t msg_size, const osMessageQueueAttr_t *attr); /// Get name of a Message Queue object. /// \param[in] mq_id message queue ID obtained by \ref osMessageQueueNew. /// \return name as null-terminated string. const char *osMessageQueueGetName (osMessageQueueId_t mq_id); /// Put a Message into a Queue or timeout if Queue is full. /// \param[in] mq_id message queue ID obtained by \ref osMessageQueueNew. /// \param[in] msg_ptr pointer to buffer with message to put into a queue. /// \param[in] msg_prio message priority. /// \param[in] timeout \ref CMSIS_RTOS_TimeOutValue or 0 in case of no time-out. /// \return status code that indicates the execution status of the function. osStatus_t osMessageQueuePut (osMessageQueueId_t mq_id, const void *msg_ptr, uint8_t msg_prio, uint32_t timeout); /// Get a Message from a Queue or timeout if Queue is empty. /// \param[in] mq_id message queue ID obtained by \ref osMessageQueueNew. /// \param[out] msg_ptr pointer to buffer for message to get from a queue. /// \param[out] msg_prio pointer to buffer for message priority or NULL. /// \param[in] timeout \ref CMSIS_RTOS_TimeOutValue or 0 in case of no time-out. /// \return status code that indicates the execution status of the function. osStatus_t osMessageQueueGet (osMessageQueueId_t mq_id, void *msg_ptr, uint8_t *msg_prio, uint32_t timeout); /// Get maximum number of messages in a Message Queue. /// \param[in] mq_id message queue ID obtained by \ref osMessageQueueNew. /// \return maximum number of messages. uint32_t osMessageQueueGetCapacity (osMessageQueueId_t mq_id); /// Get maximum message size in a Message Queue. /// \param[in] mq_id message queue ID obtained by \ref osMessageQueueNew. /// \return maximum message size in bytes. uint32_t osMessageQueueGetMsgSize (osMessageQueueId_t mq_id); /// Get number of queued messages in a Message Queue. /// \param[in] mq_id message queue ID obtained by \ref osMessageQueueNew. /// \return number of queued messages. uint32_t osMessageQueueGetCount (osMessageQueueId_t mq_id); /// Get number of available slots for messages in a Message Queue. /// \param[in] mq_id message queue ID obtained by \ref osMessageQueueNew. /// \return number of available slots for messages. uint32_t osMessageQueueGetSpace (osMessageQueueId_t mq_id); /// Reset a Message Queue to initial empty state. /// \param[in] mq_id message queue ID obtained by \ref osMessageQueueNew. /// \return status code that indicates the execution status of the function. osStatus_t osMessageQueueReset (osMessageQueueId_t mq_id); /// Delete a Message Queue object. /// \param[in] mq_id message queue ID obtained by \ref osMessageQueueNew. /// \return status code that indicates the execution status of the function. osStatus_t osMessageQueueDelete (osMessageQueueId_t mq_id); #ifdef __cplusplus } #endif #endif // CMSIS_OS2_H_