1 /* 2 * Copyright (c) 2013-2023 Arm Limited. All rights reserved. 3 * 4 * SPDX-License-Identifier: Apache-2.0 5 * 6 * Licensed under the Apache License, Version 2.0 (the License); you may 7 * not use this file except in compliance with the License. 8 * You may obtain a copy of the License at 9 * 10 * www.apache.org/licenses/LICENSE-2.0 11 * 12 * Unless required by applicable law or agreed to in writing, software 13 * distributed under the License is distributed on an AS IS BASIS, WITHOUT 14 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 15 * See the License for the specific language governing permissions and 16 * limitations under the License. 17 * 18 * ---------------------------------------------------------------------- 19 * 20 * $Date: 30. June 2023 21 * $Revision: V2.3.0 22 * 23 * Project: CMSIS-RTOS2 API 24 * Title: cmsis_os2.h header file 25 * 26 * Version 2.3.0 27 * Added provisional support for processor affinity in SMP systems: 28 - osThreadAttr_t: affinity_mask 29 * - osThreadSetAffinityMask, osThreadGetAffinityMask 30 * Version 2.2.0 31 * Added support for Process Isolation (Functional Safety): 32 * - Kernel Management: osKernelProtect, osKernelDestroyClass 33 * - Thread Management: osThreadGetClass, osThreadGetZone, 34 * osThreadSuspendClass, osThreadResumeClass 35 * osThreadTerminateZone, 36 * osThreadFeedWatchdog, 37 * osThreadProtectPrivileged 38 * - Thread attributes: osThreadZone, osThreadUnprivileged/osThreadPrivileged 39 * - Object attributes: osSafetyClass 40 * - Handler functions: osWatchdogAlarm_Handler 41 * - Zone Management: osZoneSetup_Callback 42 * - Exception Faults: osFaultResume 43 * Additional functions allowed to be called from Interrupt Service Routines: 44 * - osThreadGetName, osTimerGetName, osEventFlagsGetName, osMutexGetName, 45 * osSemaphoreGetName, osMemoryPoolGetName, osMessageQueueGetName 46 * Version 2.1.3 47 * Additional functions allowed to be called from Interrupt Service Routines: 48 * - osThreadGetId 49 * Version 2.1.2 50 * Additional functions allowed to be called from Interrupt Service Routines: 51 * - osKernelGetInfo, osKernelGetState 52 * Version 2.1.1 53 * Additional functions allowed to be called from Interrupt Service Routines: 54 * - osKernelGetTickCount, osKernelGetTickFreq 55 * Changed Kernel Tick type to uint32_t: 56 * - updated: osKernelGetTickCount, osDelayUntil 57 * Version 2.1.0 58 * Support for critical and uncritical sections (nesting safe): 59 * - updated: osKernelLock, osKernelUnlock 60 * - added: osKernelRestoreLock 61 * Updated Thread and Event Flags: 62 * - changed flags parameter and return type from int32_t to uint32_t 63 * Version 2.0.0 64 * Initial Release 65 *---------------------------------------------------------------------------*/ 66 67 #ifndef CMSIS_OS2_H_ 68 #define CMSIS_OS2_H_ 69 70 #ifndef __NO_RETURN 71 #if defined(__CC_ARM) 72 #define __NO_RETURN __declspec(noreturn) 73 #elif defined(__ARMCC_VERSION) && (__ARMCC_VERSION >= 6010050) 74 #define __NO_RETURN __attribute__((__noreturn__)) 75 #elif defined(__GNUC__) 76 #define __NO_RETURN __attribute__((__noreturn__)) 77 #elif defined(__ICCARM__) 78 #define __NO_RETURN __noreturn 79 #else 80 #define __NO_RETURN 81 #endif 82 #endif 83 84 #include <stdint.h> 85 #include <stddef.h> 86 87 #ifdef __cplusplus 88 extern "C" 89 { 90 #endif 91 92 93 // ==== Enumerations, structures, defines ==== 94 95 /// Version information. 96 typedef struct { 97 uint32_t api; ///< API version (major.minor.rev: mmnnnrrrr dec). 98 uint32_t kernel; ///< Kernel version (major.minor.rev: mmnnnrrrr dec). 99 } osVersion_t; 100 101 /// Kernel state. 102 typedef enum { 103 osKernelInactive = 0, ///< Inactive. 104 osKernelReady = 1, ///< Ready. 105 osKernelRunning = 2, ///< Running. 106 osKernelLocked = 3, ///< Locked. 107 osKernelSuspended = 4, ///< Suspended. 108 osKernelError = -1, ///< Error. 109 osKernelReserved = 0x7FFFFFFF ///< Prevents enum down-size compiler optimization. 110 } osKernelState_t; 111 112 /// Thread state. 113 typedef enum { 114 osThreadInactive = 0, ///< Inactive. 115 osThreadReady = 1, ///< Ready. 116 osThreadRunning = 2, ///< Running. 117 osThreadBlocked = 3, ///< Blocked. 118 osThreadTerminated = 4, ///< Terminated. 119 osThreadError = -1, ///< Error. 120 osThreadReserved = 0x7FFFFFFF ///< Prevents enum down-size compiler optimization. 121 } osThreadState_t; 122 123 /// Priority values. 124 typedef enum { 125 osPriorityNone = 0, ///< No priority (not initialized). 126 osPriorityIdle = 1, ///< Reserved for Idle thread. 127 osPriorityLow = 8, ///< Priority: low 128 osPriorityLow1 = 8+1, ///< Priority: low + 1 129 osPriorityLow2 = 8+2, ///< Priority: low + 2 130 osPriorityLow3 = 8+3, ///< Priority: low + 3 131 osPriorityLow4 = 8+4, ///< Priority: low + 4 132 osPriorityLow5 = 8+5, ///< Priority: low + 5 133 osPriorityLow6 = 8+6, ///< Priority: low + 6 134 osPriorityLow7 = 8+7, ///< Priority: low + 7 135 osPriorityBelowNormal = 16, ///< Priority: below normal 136 osPriorityBelowNormal1 = 16+1, ///< Priority: below normal + 1 137 osPriorityBelowNormal2 = 16+2, ///< Priority: below normal + 2 138 osPriorityBelowNormal3 = 16+3, ///< Priority: below normal + 3 139 osPriorityBelowNormal4 = 16+4, ///< Priority: below normal + 4 140 osPriorityBelowNormal5 = 16+5, ///< Priority: below normal + 5 141 osPriorityBelowNormal6 = 16+6, ///< Priority: below normal + 6 142 osPriorityBelowNormal7 = 16+7, ///< Priority: below normal + 7 143 osPriorityNormal = 24, ///< Priority: normal 144 osPriorityNormal1 = 24+1, ///< Priority: normal + 1 145 osPriorityNormal2 = 24+2, ///< Priority: normal + 2 146 osPriorityNormal3 = 24+3, ///< Priority: normal + 3 147 osPriorityNormal4 = 24+4, ///< Priority: normal + 4 148 osPriorityNormal5 = 24+5, ///< Priority: normal + 5 149 osPriorityNormal6 = 24+6, ///< Priority: normal + 6 150 osPriorityNormal7 = 24+7, ///< Priority: normal + 7 151 osPriorityAboveNormal = 32, ///< Priority: above normal 152 osPriorityAboveNormal1 = 32+1, ///< Priority: above normal + 1 153 osPriorityAboveNormal2 = 32+2, ///< Priority: above normal + 2 154 osPriorityAboveNormal3 = 32+3, ///< Priority: above normal + 3 155 osPriorityAboveNormal4 = 32+4, ///< Priority: above normal + 4 156 osPriorityAboveNormal5 = 32+5, ///< Priority: above normal + 5 157 osPriorityAboveNormal6 = 32+6, ///< Priority: above normal + 6 158 osPriorityAboveNormal7 = 32+7, ///< Priority: above normal + 7 159 osPriorityHigh = 40, ///< Priority: high 160 osPriorityHigh1 = 40+1, ///< Priority: high + 1 161 osPriorityHigh2 = 40+2, ///< Priority: high + 2 162 osPriorityHigh3 = 40+3, ///< Priority: high + 3 163 osPriorityHigh4 = 40+4, ///< Priority: high + 4 164 osPriorityHigh5 = 40+5, ///< Priority: high + 5 165 osPriorityHigh6 = 40+6, ///< Priority: high + 6 166 osPriorityHigh7 = 40+7, ///< Priority: high + 7 167 osPriorityRealtime = 48, ///< Priority: realtime 168 osPriorityRealtime1 = 48+1, ///< Priority: realtime + 1 169 osPriorityRealtime2 = 48+2, ///< Priority: realtime + 2 170 osPriorityRealtime3 = 48+3, ///< Priority: realtime + 3 171 osPriorityRealtime4 = 48+4, ///< Priority: realtime + 4 172 osPriorityRealtime5 = 48+5, ///< Priority: realtime + 5 173 osPriorityRealtime6 = 48+6, ///< Priority: realtime + 6 174 osPriorityRealtime7 = 48+7, ///< Priority: realtime + 7 175 osPriorityISR = 56, ///< Reserved for ISR deferred thread. 176 osPriorityError = -1, ///< System cannot determine priority or illegal priority. 177 osPriorityReserved = 0x7FFFFFFF ///< Prevents enum down-size compiler optimization. 178 } osPriority_t; 179 180 /// Entry point of a thread. 181 typedef void (*osThreadFunc_t) (void *argument); 182 183 /// Timer callback function. 184 typedef void (*osTimerFunc_t) (void *argument); 185 186 /// Timer type. 187 typedef enum { 188 osTimerOnce = 0, ///< One-shot timer. 189 osTimerPeriodic = 1 ///< Repeating timer. 190 } osTimerType_t; 191 192 // Timeout value. 193 #define osWaitForever 0xFFFFFFFFU ///< Wait forever timeout value. 194 195 // Flags options (\ref osThreadFlagsWait and \ref osEventFlagsWait). 196 #define osFlagsWaitAny 0x00000000U ///< Wait for any flag (default). 197 #define osFlagsWaitAll 0x00000001U ///< Wait for all flags. 198 #define osFlagsNoClear 0x00000002U ///< Do not clear flags which have been specified to wait for. 199 200 // Flags errors (returned by osThreadFlagsXxxx and osEventFlagsXxxx). 201 #define osFlagsError 0x80000000U ///< Error indicator. 202 #define osFlagsErrorUnknown 0xFFFFFFFFU ///< osError (-1). 203 #define osFlagsErrorTimeout 0xFFFFFFFEU ///< osErrorTimeout (-2). 204 #define osFlagsErrorResource 0xFFFFFFFDU ///< osErrorResource (-3). 205 #define osFlagsErrorParameter 0xFFFFFFFCU ///< osErrorParameter (-4). 206 #define osFlagsErrorISR 0xFFFFFFFAU ///< osErrorISR (-6). 207 #define osFlagsErrorSafetyClass 0xFFFFFFF9U ///< osErrorSafetyClass (-7). 208 209 // Thread attributes (attr_bits in \ref osThreadAttr_t). 210 #define osThreadDetached 0x00000000U ///< Thread created in detached mode (default) 211 #define osThreadJoinable 0x00000001U ///< Thread created in joinable mode 212 #define osThreadUnprivileged 0x00000002U ///< Thread runs in unprivileged mode 213 #define osThreadPrivileged 0x00000004U ///< Thread runs in privileged mode 214 215 #define osThreadZone_Pos 8U ///< MPU protected zone position 216 #define osThreadZone_Msk (0x3FUL << osThreadZone_Pos) ///< MPU protected zone mask 217 #define osThreadZone_Valid (0x80UL << osThreadZone_Pos) ///< MPU protected zone valid flag 218 #define osThreadZone(n) ((((n) << osThreadZone_Pos) & osThreadZone_Msk) | \ 219 osThreadZone_Valid) ///< MPU zone value in attribute bit field format 220 221 // Thread processor affinity (affinity_mask in \ref osThreadAttr_t). 222 #define osThreadProcessor(n) (1UL << (n)) ///< Thread processor number for SMP systems 223 224 // Mutex attributes (attr_bits in \ref osMutexAttr_t). 225 #define osMutexRecursive 0x00000001U ///< Recursive mutex. 226 #define osMutexPrioInherit 0x00000002U ///< Priority inherit protocol. 227 #define osMutexRobust 0x00000008U ///< Robust mutex. 228 229 // Object attributes (attr_bits in all objects). 230 #define osSafetyClass_Pos 16U ///< Safety class position 231 #define osSafetyClass_Msk (0x0FUL << osSafetyClass_Pos) ///< Safety class mask 232 #define osSafetyClass_Valid (0x10UL << osSafetyClass_Pos) ///< Safety class valid flag 233 #define osSafetyClass(n) ((((n) << osSafetyClass_Pos) & osSafetyClass_Msk) | \ 234 osSafetyClass_Valid) ///< Safety class 235 236 // Safety mode (\ref osThreadSuspendClass, \ref osThreadResumeClass and \ref osKernelDestroyClass). 237 #define osSafetyWithSameClass 0x00000001U ///< Objects with same safety class. 238 #define osSafetyWithLowerClass 0x00000002U ///< Objects with lower safety class. 239 240 // Error indication (returned by \ref osThreadGetClass and \ref osThreadGetZone). 241 #define osErrorId 0xFFFFFFFFU ///< osError (-1). 242 243 /// Status code values returned by CMSIS-RTOS functions. 244 typedef enum { 245 osOK = 0, ///< Operation completed successfully. 246 osError = -1, ///< Unspecified RTOS error: run-time error but no other error message fits. 247 osErrorTimeout = -2, ///< Operation not completed within the timeout period. 248 osErrorResource = -3, ///< Resource not available. 249 osErrorParameter = -4, ///< Parameter error. 250 osErrorNoMemory = -5, ///< System is out of memory: it was impossible to allocate or reserve memory for the operation. 251 osErrorISR = -6, ///< Not allowed in ISR context: the function cannot be called from interrupt service routines. 252 osErrorSafetyClass = -7, ///< Operation denied because of safety class violation. 253 osStatusReserved = 0x7FFFFFFF ///< Prevents enum down-size compiler optimization. 254 } osStatus_t; 255 256 257 /// \details Thread ID identifies the thread. 258 typedef void *osThreadId_t; 259 260 /// \details Timer ID identifies the timer. 261 typedef void *osTimerId_t; 262 263 /// \details Event Flags ID identifies the event flags. 264 typedef void *osEventFlagsId_t; 265 266 /// \details Mutex ID identifies the mutex. 267 typedef void *osMutexId_t; 268 269 /// \details Semaphore ID identifies the semaphore. 270 typedef void *osSemaphoreId_t; 271 272 /// \details Memory Pool ID identifies the memory pool. 273 typedef void *osMemoryPoolId_t; 274 275 /// \details Message Queue ID identifies the message queue. 276 typedef void *osMessageQueueId_t; 277 278 279 #ifndef TZ_MODULEID_T 280 #define TZ_MODULEID_T 281 /// \details Data type that identifies secure software modules called by a process. 282 typedef uint32_t TZ_ModuleId_t; 283 #endif 284 285 286 /// Attributes structure for thread. 287 typedef struct { 288 const char *name; ///< name of the thread 289 uint32_t attr_bits; ///< attribute bits 290 void *cb_mem; ///< memory for control block 291 uint32_t cb_size; ///< size of provided memory for control block 292 void *stack_mem; ///< memory for stack 293 uint32_t stack_size; ///< size of stack 294 osPriority_t priority; ///< initial thread priority (default: osPriorityNormal) 295 TZ_ModuleId_t tz_module; ///< TrustZone module identifier 296 uint32_t affinity_mask; ///< processor affinity mask for binding the thread to a CPU in a SMP system (0 when not used) 297 } osThreadAttr_t; 298 299 /// Attributes structure for timer. 300 typedef struct { 301 const char *name; ///< name of the timer 302 uint32_t attr_bits; ///< attribute bits 303 void *cb_mem; ///< memory for control block 304 uint32_t cb_size; ///< size of provided memory for control block 305 } osTimerAttr_t; 306 307 /// Attributes structure for event flags. 308 typedef struct { 309 const char *name; ///< name of the event flags 310 uint32_t attr_bits; ///< attribute bits 311 void *cb_mem; ///< memory for control block 312 uint32_t cb_size; ///< size of provided memory for control block 313 } osEventFlagsAttr_t; 314 315 /// Attributes structure for mutex. 316 typedef struct { 317 const char *name; ///< name of the mutex 318 uint32_t attr_bits; ///< attribute bits 319 void *cb_mem; ///< memory for control block 320 uint32_t cb_size; ///< size of provided memory for control block 321 } osMutexAttr_t; 322 323 /// Attributes structure for semaphore. 324 typedef struct { 325 const char *name; ///< name of the semaphore 326 uint32_t attr_bits; ///< attribute bits 327 void *cb_mem; ///< memory for control block 328 uint32_t cb_size; ///< size of provided memory for control block 329 } osSemaphoreAttr_t; 330 331 /// Attributes structure for memory pool. 332 typedef struct { 333 const char *name; ///< name of the memory pool 334 uint32_t attr_bits; ///< attribute bits 335 void *cb_mem; ///< memory for control block 336 uint32_t cb_size; ///< size of provided memory for control block 337 void *mp_mem; ///< memory for data storage 338 uint32_t mp_size; ///< size of provided memory for data storage 339 } osMemoryPoolAttr_t; 340 341 /// Attributes structure for message queue. 342 typedef struct { 343 const char *name; ///< name of the message queue 344 uint32_t attr_bits; ///< attribute bits 345 void *cb_mem; ///< memory for control block 346 uint32_t cb_size; ///< size of provided memory for control block 347 void *mq_mem; ///< memory for data storage 348 uint32_t mq_size; ///< size of provided memory for data storage 349 } osMessageQueueAttr_t; 350 351 352 // ==== Kernel Management Functions ==== 353 354 /// Initialize the RTOS Kernel. 355 /// \return status code that indicates the execution status of the function. 356 osStatus_t osKernelInitialize (void); 357 358 /// Get RTOS Kernel Information. 359 /// \param[out] version pointer to buffer for retrieving version information. 360 /// \param[out] id_buf pointer to buffer for retrieving kernel identification string. 361 /// \param[in] id_size size of buffer for kernel identification string. 362 /// \return status code that indicates the execution status of the function. 363 osStatus_t osKernelGetInfo (osVersion_t *version, char *id_buf, uint32_t id_size); 364 365 /// Get the current RTOS Kernel state. 366 /// \return current RTOS Kernel state. 367 osKernelState_t osKernelGetState (void); 368 369 /// Start the RTOS Kernel scheduler. 370 /// \return status code that indicates the execution status of the function. 371 osStatus_t osKernelStart (void); 372 373 /// Lock the RTOS Kernel scheduler. 374 /// \return previous lock state (1 - locked, 0 - not locked, error code if negative). 375 int32_t osKernelLock (void); 376 377 /// Unlock the RTOS Kernel scheduler. 378 /// \return previous lock state (1 - locked, 0 - not locked, error code if negative). 379 int32_t osKernelUnlock (void); 380 381 /// Restore the RTOS Kernel scheduler lock state. 382 /// \param[in] lock lock state obtained by \ref osKernelLock or \ref osKernelUnlock. 383 /// \return new lock state (1 - locked, 0 - not locked, error code if negative). 384 int32_t osKernelRestoreLock (int32_t lock); 385 386 /// Suspend the RTOS Kernel scheduler. 387 /// \return time in ticks, for how long the system can sleep or power-down. 388 uint32_t osKernelSuspend (void); 389 390 /// Resume the RTOS Kernel scheduler. 391 /// \param[in] sleep_ticks time in ticks for how long the system was in sleep or power-down mode. 392 void osKernelResume (uint32_t sleep_ticks); 393 394 /// Protect the RTOS Kernel scheduler access. 395 /// \param[in] safety_class safety class. 396 /// \return status code that indicates the execution status of the function. 397 osStatus_t osKernelProtect (uint32_t safety_class); 398 399 /// Destroy objects for specified safety classes. 400 /// \param[in] safety_class safety class. 401 /// \param[in] mode safety mode. 402 /// \return status code that indicates the execution status of the function. 403 osStatus_t osKernelDestroyClass (uint32_t safety_class, uint32_t mode); 404 405 /// Get the RTOS kernel tick count. 406 /// \return RTOS kernel current tick count. 407 uint32_t osKernelGetTickCount (void); 408 409 /// Get the RTOS kernel tick frequency. 410 /// \return frequency of the kernel tick in hertz, i.e. kernel ticks per second. 411 uint32_t osKernelGetTickFreq (void); 412 413 /// Get the RTOS kernel system timer count. 414 /// \return RTOS kernel current system timer count as 32-bit value. 415 uint32_t osKernelGetSysTimerCount (void); 416 417 /// Get the RTOS kernel system timer frequency. 418 /// \return frequency of the system timer in hertz, i.e. timer ticks per second. 419 uint32_t osKernelGetSysTimerFreq (void); 420 421 422 // ==== Thread Management Functions ==== 423 424 /// Create a thread and add it to Active Threads. 425 /// \param[in] func thread function. 426 /// \param[in] argument pointer that is passed to the thread function as start argument. 427 /// \param[in] attr thread attributes; NULL: default values. 428 /// \return thread ID for reference by other functions or NULL in case of error. 429 osThreadId_t osThreadNew (osThreadFunc_t func, void *argument, const osThreadAttr_t *attr); 430 431 /// Get name of a thread. 432 /// \param[in] thread_id thread ID obtained by \ref osThreadNew or \ref osThreadGetId. 433 /// \return name as null-terminated string. 434 const char *osThreadGetName (osThreadId_t thread_id); 435 436 /// Get safety class of a thread. 437 /// \param[in] thread_id thread ID obtained by \ref osThreadNew or \ref osThreadGetId. 438 /// \return safety class of the specified thread. 439 uint32_t osThreadGetClass (osThreadId_t thread_id); 440 441 /// Get MPU protected zone of a thread. 442 /// \param[in] thread_id thread ID obtained by \ref osThreadNew or \ref osThreadGetId. 443 /// \return MPU protected zone of the specified thread. 444 uint32_t osThreadGetZone (osThreadId_t thread_id); 445 446 /// Return the thread ID of the current running thread. 447 /// \return thread ID for reference by other functions or NULL in case of error. 448 osThreadId_t osThreadGetId (void); 449 450 /// Get current thread state of a thread. 451 /// \param[in] thread_id thread ID obtained by \ref osThreadNew or \ref osThreadGetId. 452 /// \return current thread state of the specified thread. 453 osThreadState_t osThreadGetState (osThreadId_t thread_id); 454 455 /// Get stack size of a thread. 456 /// \param[in] thread_id thread ID obtained by \ref osThreadNew or \ref osThreadGetId. 457 /// \return stack size in bytes. 458 uint32_t osThreadGetStackSize (osThreadId_t thread_id); 459 460 /// Get available stack space of a thread based on stack watermark recording during execution. 461 /// \param[in] thread_id thread ID obtained by \ref osThreadNew or \ref osThreadGetId. 462 /// \return remaining stack space in bytes. 463 uint32_t osThreadGetStackSpace (osThreadId_t thread_id); 464 465 /// Change priority of a thread. 466 /// \param[in] thread_id thread ID obtained by \ref osThreadNew or \ref osThreadGetId. 467 /// \param[in] priority new priority value for the thread function. 468 /// \return status code that indicates the execution status of the function. 469 osStatus_t osThreadSetPriority (osThreadId_t thread_id, osPriority_t priority); 470 471 /// Get current priority of a thread. 472 /// \param[in] thread_id thread ID obtained by \ref osThreadNew or \ref osThreadGetId. 473 /// \return current priority value of the specified thread. 474 osPriority_t osThreadGetPriority (osThreadId_t thread_id); 475 476 /// Pass control to next thread that is in state \b READY. 477 /// \return status code that indicates the execution status of the function. 478 osStatus_t osThreadYield (void); 479 480 /// Suspend execution of a thread. 481 /// \param[in] thread_id thread ID obtained by \ref osThreadNew or \ref osThreadGetId. 482 /// \return status code that indicates the execution status of the function. 483 osStatus_t osThreadSuspend (osThreadId_t thread_id); 484 485 /// Resume execution of a thread. 486 /// \param[in] thread_id thread ID obtained by \ref osThreadNew or \ref osThreadGetId. 487 /// \return status code that indicates the execution status of the function. 488 osStatus_t osThreadResume (osThreadId_t thread_id); 489 490 /// Detach a thread (thread storage can be reclaimed when thread terminates). 491 /// \param[in] thread_id thread ID obtained by \ref osThreadNew or \ref osThreadGetId. 492 /// \return status code that indicates the execution status of the function. 493 osStatus_t osThreadDetach (osThreadId_t thread_id); 494 495 /// Wait for specified thread to terminate. 496 /// \param[in] thread_id thread ID obtained by \ref osThreadNew or \ref osThreadGetId. 497 /// \return status code that indicates the execution status of the function. 498 osStatus_t osThreadJoin (osThreadId_t thread_id); 499 500 /// Terminate execution of current running thread. 501 __NO_RETURN void osThreadExit (void); 502 503 /// Terminate execution of a thread. 504 /// \param[in] thread_id thread ID obtained by \ref osThreadNew or \ref osThreadGetId. 505 /// \return status code that indicates the execution status of the function. 506 osStatus_t osThreadTerminate (osThreadId_t thread_id); 507 508 /// Feed watchdog of the current running thread. 509 /// \param[in] ticks interval in kernel ticks until the thread watchdog expires, or 0 to stop the watchdog 510 /// \return status code that indicates the execution status of the function. 511 osStatus_t osThreadFeedWatchdog (uint32_t ticks); 512 513 /// Protect creation of privileged threads. 514 /// \return status code that indicates the execution status of the function. 515 osStatus_t osThreadProtectPrivileged (void); 516 517 /// Suspend execution of threads for specified safety classes. 518 /// \param[in] safety_class safety class. 519 /// \param[in] mode safety mode. 520 /// \return status code that indicates the execution status of the function. 521 osStatus_t osThreadSuspendClass (uint32_t safety_class, uint32_t mode); 522 523 /// Resume execution of threads for specified safety classes. 524 /// \param[in] safety_class safety class. 525 /// \param[in] mode safety mode. 526 /// \return status code that indicates the execution status of the function. 527 osStatus_t osThreadResumeClass (uint32_t safety_class, uint32_t mode); 528 529 /// Terminate execution of threads assigned to a specified MPU protected zone. 530 /// \param[in] zone MPU protected zone. 531 /// \return status code that indicates the execution status of the function. 532 osStatus_t osThreadTerminateZone (uint32_t zone); 533 534 /// Set processor affinity mask of a thread. 535 /// \param[in] thread_id thread ID obtained by \ref osThreadNew or \ref osThreadGetId. 536 /// \param[in] affinity_mask processor affinity mask for the thread. 537 /// \return status code that indicates the execution status of the function. 538 osStatus_t osThreadSetAffinityMask (osThreadId_t thread_id, uint32_t affinity_mask); 539 540 /// Get current processor affinity mask of a thread. 541 /// \param[in] thread_id thread ID obtained by \ref osThreadNew or \ref osThreadGetId. 542 /// \return current processor affinity mask of the specified thread. 543 uint32_t osThreadGetAffinityMask (osThreadId_t thread_id); 544 545 /// Get number of active threads. 546 /// \return number of active threads. 547 uint32_t osThreadGetCount (void); 548 549 /// Enumerate active threads. 550 /// \param[out] thread_array pointer to array for retrieving thread IDs. 551 /// \param[in] array_items maximum number of items in array for retrieving thread IDs. 552 /// \return number of enumerated threads. 553 uint32_t osThreadEnumerate (osThreadId_t *thread_array, uint32_t array_items); 554 555 556 // ==== Thread Flags Functions ==== 557 558 /// Set the specified Thread Flags of a thread. 559 /// \param[in] thread_id thread ID obtained by \ref osThreadNew or \ref osThreadGetId. 560 /// \param[in] flags specifies the flags of the thread that shall be set. 561 /// \return thread flags after setting or error code if highest bit set. 562 uint32_t osThreadFlagsSet (osThreadId_t thread_id, uint32_t flags); 563 564 /// Clear the specified Thread Flags of current running thread. 565 /// \param[in] flags specifies the flags of the thread that shall be cleared. 566 /// \return thread flags before clearing or error code if highest bit set. 567 uint32_t osThreadFlagsClear (uint32_t flags); 568 569 /// Get the current Thread Flags of current running thread. 570 /// \return current thread flags. 571 uint32_t osThreadFlagsGet (void); 572 573 /// Wait for one or more Thread Flags of the current running thread to become signaled. 574 /// \param[in] flags specifies the flags to wait for. 575 /// \param[in] options specifies flags options (osFlagsXxxx). 576 /// \param[in] timeout \ref CMSIS_RTOS_TimeOutValue or 0 in case of no time-out. 577 /// \return thread flags before clearing or error code if highest bit set. 578 uint32_t osThreadFlagsWait (uint32_t flags, uint32_t options, uint32_t timeout); 579 580 581 // ==== Generic Wait Functions ==== 582 583 /// Wait for Timeout (Time Delay). 584 /// \param[in] ticks \ref CMSIS_RTOS_TimeOutValue "time ticks" value 585 /// \return status code that indicates the execution status of the function. 586 osStatus_t osDelay (uint32_t ticks); 587 588 /// Wait until specified time. 589 /// \param[in] ticks absolute time in ticks 590 /// \return status code that indicates the execution status of the function. 591 osStatus_t osDelayUntil (uint32_t ticks); 592 593 594 // ==== Timer Management Functions ==== 595 596 /// Create and Initialize a timer. 597 /// \param[in] func function pointer to callback function. 598 /// \param[in] type \ref osTimerOnce for one-shot or \ref osTimerPeriodic for periodic behavior. 599 /// \param[in] argument argument to the timer callback function. 600 /// \param[in] attr timer attributes; NULL: default values. 601 /// \return timer ID for reference by other functions or NULL in case of error. 602 osTimerId_t osTimerNew (osTimerFunc_t func, osTimerType_t type, void *argument, const osTimerAttr_t *attr); 603 604 /// Get name of a timer. 605 /// \param[in] timer_id timer ID obtained by \ref osTimerNew. 606 /// \return name as null-terminated string. 607 const char *osTimerGetName (osTimerId_t timer_id); 608 609 /// Start or restart a timer. 610 /// \param[in] timer_id timer ID obtained by \ref osTimerNew. 611 /// \param[in] ticks \ref CMSIS_RTOS_TimeOutValue "time ticks" value of the timer. 612 /// \return status code that indicates the execution status of the function. 613 osStatus_t osTimerStart (osTimerId_t timer_id, uint32_t ticks); 614 615 /// Stop a timer. 616 /// \param[in] timer_id timer ID obtained by \ref osTimerNew. 617 /// \return status code that indicates the execution status of the function. 618 osStatus_t osTimerStop (osTimerId_t timer_id); 619 620 /// Check if a timer is running. 621 /// \param[in] timer_id timer ID obtained by \ref osTimerNew. 622 /// \return 0 not running, 1 running. 623 uint32_t osTimerIsRunning (osTimerId_t timer_id); 624 625 /// Delete a timer. 626 /// \param[in] timer_id timer ID obtained by \ref osTimerNew. 627 /// \return status code that indicates the execution status of the function. 628 osStatus_t osTimerDelete (osTimerId_t timer_id); 629 630 631 // ==== Event Flags Management Functions ==== 632 633 /// Create and Initialize an Event Flags object. 634 /// \param[in] attr event flags attributes; NULL: default values. 635 /// \return event flags ID for reference by other functions or NULL in case of error. 636 osEventFlagsId_t osEventFlagsNew (const osEventFlagsAttr_t *attr); 637 638 /// Get name of an Event Flags object. 639 /// \param[in] ef_id event flags ID obtained by \ref osEventFlagsNew. 640 /// \return name as null-terminated string. 641 const char *osEventFlagsGetName (osEventFlagsId_t ef_id); 642 643 /// Set the specified Event Flags. 644 /// \param[in] ef_id event flags ID obtained by \ref osEventFlagsNew. 645 /// \param[in] flags specifies the flags that shall be set. 646 /// \return event flags after setting or error code if highest bit set. 647 uint32_t osEventFlagsSet (osEventFlagsId_t ef_id, uint32_t flags); 648 649 /// Clear the specified Event Flags. 650 /// \param[in] ef_id event flags ID obtained by \ref osEventFlagsNew. 651 /// \param[in] flags specifies the flags that shall be cleared. 652 /// \return event flags before clearing or error code if highest bit set. 653 uint32_t osEventFlagsClear (osEventFlagsId_t ef_id, uint32_t flags); 654 655 /// Get the current Event Flags. 656 /// \param[in] ef_id event flags ID obtained by \ref osEventFlagsNew. 657 /// \return current event flags. 658 uint32_t osEventFlagsGet (osEventFlagsId_t ef_id); 659 660 /// Wait for one or more Event Flags to become signaled. 661 /// \param[in] ef_id event flags ID obtained by \ref osEventFlagsNew. 662 /// \param[in] flags specifies the flags to wait for. 663 /// \param[in] options specifies flags options (osFlagsXxxx). 664 /// \param[in] timeout \ref CMSIS_RTOS_TimeOutValue or 0 in case of no time-out. 665 /// \return event flags before clearing or error code if highest bit set. 666 uint32_t osEventFlagsWait (osEventFlagsId_t ef_id, uint32_t flags, uint32_t options, uint32_t timeout); 667 668 /// Delete an Event Flags object. 669 /// \param[in] ef_id event flags ID obtained by \ref osEventFlagsNew. 670 /// \return status code that indicates the execution status of the function. 671 osStatus_t osEventFlagsDelete (osEventFlagsId_t ef_id); 672 673 674 // ==== Mutex Management Functions ==== 675 676 /// Create and Initialize a Mutex object. 677 /// \param[in] attr mutex attributes; NULL: default values. 678 /// \return mutex ID for reference by other functions or NULL in case of error. 679 osMutexId_t osMutexNew (const osMutexAttr_t *attr); 680 681 /// Get name of a Mutex object. 682 /// \param[in] mutex_id mutex ID obtained by \ref osMutexNew. 683 /// \return name as null-terminated string. 684 const char *osMutexGetName (osMutexId_t mutex_id); 685 686 /// Acquire a Mutex or timeout if it is locked. 687 /// \param[in] mutex_id mutex ID obtained by \ref osMutexNew. 688 /// \param[in] timeout \ref CMSIS_RTOS_TimeOutValue or 0 in case of no time-out. 689 /// \return status code that indicates the execution status of the function. 690 osStatus_t osMutexAcquire (osMutexId_t mutex_id, uint32_t timeout); 691 692 /// Release a Mutex that was acquired by \ref osMutexAcquire. 693 /// \param[in] mutex_id mutex ID obtained by \ref osMutexNew. 694 /// \return status code that indicates the execution status of the function. 695 osStatus_t osMutexRelease (osMutexId_t mutex_id); 696 697 /// Get Thread which owns a Mutex object. 698 /// \param[in] mutex_id mutex ID obtained by \ref osMutexNew. 699 /// \return thread ID of owner thread or NULL when mutex was not acquired. 700 osThreadId_t osMutexGetOwner (osMutexId_t mutex_id); 701 702 /// Delete a Mutex object. 703 /// \param[in] mutex_id mutex ID obtained by \ref osMutexNew. 704 /// \return status code that indicates the execution status of the function. 705 osStatus_t osMutexDelete (osMutexId_t mutex_id); 706 707 708 // ==== Semaphore Management Functions ==== 709 710 /// Create and Initialize a Semaphore object. 711 /// \param[in] max_count maximum number of available tokens. 712 /// \param[in] initial_count initial number of available tokens. 713 /// \param[in] attr semaphore attributes; NULL: default values. 714 /// \return semaphore ID for reference by other functions or NULL in case of error. 715 osSemaphoreId_t osSemaphoreNew (uint32_t max_count, uint32_t initial_count, const osSemaphoreAttr_t *attr); 716 717 /// Get name of a Semaphore object. 718 /// \param[in] semaphore_id semaphore ID obtained by \ref osSemaphoreNew. 719 /// \return name as null-terminated string. 720 const char *osSemaphoreGetName (osSemaphoreId_t semaphore_id); 721 722 /// Acquire a Semaphore token or timeout if no tokens are available. 723 /// \param[in] semaphore_id semaphore ID obtained by \ref osSemaphoreNew. 724 /// \param[in] timeout \ref CMSIS_RTOS_TimeOutValue or 0 in case of no time-out. 725 /// \return status code that indicates the execution status of the function. 726 osStatus_t osSemaphoreAcquire (osSemaphoreId_t semaphore_id, uint32_t timeout); 727 728 /// Release a Semaphore token up to the initial maximum count. 729 /// \param[in] semaphore_id semaphore ID obtained by \ref osSemaphoreNew. 730 /// \return status code that indicates the execution status of the function. 731 osStatus_t osSemaphoreRelease (osSemaphoreId_t semaphore_id); 732 733 /// Get current Semaphore token count. 734 /// \param[in] semaphore_id semaphore ID obtained by \ref osSemaphoreNew. 735 /// \return number of tokens available. 736 uint32_t osSemaphoreGetCount (osSemaphoreId_t semaphore_id); 737 738 /// Delete a Semaphore object. 739 /// \param[in] semaphore_id semaphore ID obtained by \ref osSemaphoreNew. 740 /// \return status code that indicates the execution status of the function. 741 osStatus_t osSemaphoreDelete (osSemaphoreId_t semaphore_id); 742 743 744 // ==== Memory Pool Management Functions ==== 745 746 /// Create and Initialize a Memory Pool object. 747 /// \param[in] block_count maximum number of memory blocks in memory pool. 748 /// \param[in] block_size memory block size in bytes. 749 /// \param[in] attr memory pool attributes; NULL: default values. 750 /// \return memory pool ID for reference by other functions or NULL in case of error. 751 osMemoryPoolId_t osMemoryPoolNew (uint32_t block_count, uint32_t block_size, const osMemoryPoolAttr_t *attr); 752 753 /// Get name of a Memory Pool object. 754 /// \param[in] mp_id memory pool ID obtained by \ref osMemoryPoolNew. 755 /// \return name as null-terminated string. 756 const char *osMemoryPoolGetName (osMemoryPoolId_t mp_id); 757 758 /// Allocate a memory block from a Memory Pool. 759 /// \param[in] mp_id memory pool ID obtained by \ref osMemoryPoolNew. 760 /// \param[in] timeout \ref CMSIS_RTOS_TimeOutValue or 0 in case of no time-out. 761 /// \return address of the allocated memory block or NULL in case of no memory is available. 762 void *osMemoryPoolAlloc (osMemoryPoolId_t mp_id, uint32_t timeout); 763 764 /// Return an allocated memory block back to a Memory Pool. 765 /// \param[in] mp_id memory pool ID obtained by \ref osMemoryPoolNew. 766 /// \param[in] block address of the allocated memory block to be returned to the memory pool. 767 /// \return status code that indicates the execution status of the function. 768 osStatus_t osMemoryPoolFree (osMemoryPoolId_t mp_id, void *block); 769 770 /// Get maximum number of memory blocks in a Memory Pool. 771 /// \param[in] mp_id memory pool ID obtained by \ref osMemoryPoolNew. 772 /// \return maximum number of memory blocks. 773 uint32_t osMemoryPoolGetCapacity (osMemoryPoolId_t mp_id); 774 775 /// Get memory block size in a Memory Pool. 776 /// \param[in] mp_id memory pool ID obtained by \ref osMemoryPoolNew. 777 /// \return memory block size in bytes. 778 uint32_t osMemoryPoolGetBlockSize (osMemoryPoolId_t mp_id); 779 780 /// Get number of memory blocks used in a Memory Pool. 781 /// \param[in] mp_id memory pool ID obtained by \ref osMemoryPoolNew. 782 /// \return number of memory blocks used. 783 uint32_t osMemoryPoolGetCount (osMemoryPoolId_t mp_id); 784 785 /// Get number of memory blocks available in a Memory Pool. 786 /// \param[in] mp_id memory pool ID obtained by \ref osMemoryPoolNew. 787 /// \return number of memory blocks available. 788 uint32_t osMemoryPoolGetSpace (osMemoryPoolId_t mp_id); 789 790 /// Delete a Memory Pool object. 791 /// \param[in] mp_id memory pool ID obtained by \ref osMemoryPoolNew. 792 /// \return status code that indicates the execution status of the function. 793 osStatus_t osMemoryPoolDelete (osMemoryPoolId_t mp_id); 794 795 796 // ==== Message Queue Management Functions ==== 797 798 /// Create and Initialize a Message Queue object. 799 /// \param[in] msg_count maximum number of messages in queue. 800 /// \param[in] msg_size maximum message size in bytes. 801 /// \param[in] attr message queue attributes; NULL: default values. 802 /// \return message queue ID for reference by other functions or NULL in case of error. 803 osMessageQueueId_t osMessageQueueNew (uint32_t msg_count, uint32_t msg_size, const osMessageQueueAttr_t *attr); 804 805 /// Get name of a Message Queue object. 806 /// \param[in] mq_id message queue ID obtained by \ref osMessageQueueNew. 807 /// \return name as null-terminated string. 808 const char *osMessageQueueGetName (osMessageQueueId_t mq_id); 809 810 /// Put a Message into a Queue or timeout if Queue is full. 811 /// \param[in] mq_id message queue ID obtained by \ref osMessageQueueNew. 812 /// \param[in] msg_ptr pointer to buffer with message to put into a queue. 813 /// \param[in] msg_prio message priority. 814 /// \param[in] timeout \ref CMSIS_RTOS_TimeOutValue or 0 in case of no time-out. 815 /// \return status code that indicates the execution status of the function. 816 osStatus_t osMessageQueuePut (osMessageQueueId_t mq_id, const void *msg_ptr, uint8_t msg_prio, uint32_t timeout); 817 818 /// Get a Message from a Queue or timeout if Queue is empty. 819 /// \param[in] mq_id message queue ID obtained by \ref osMessageQueueNew. 820 /// \param[out] msg_ptr pointer to buffer for message to get from a queue. 821 /// \param[out] msg_prio pointer to buffer for message priority or NULL. 822 /// \param[in] timeout \ref CMSIS_RTOS_TimeOutValue or 0 in case of no time-out. 823 /// \return status code that indicates the execution status of the function. 824 osStatus_t osMessageQueueGet (osMessageQueueId_t mq_id, void *msg_ptr, uint8_t *msg_prio, uint32_t timeout); 825 826 /// Get maximum number of messages in a Message Queue. 827 /// \param[in] mq_id message queue ID obtained by \ref osMessageQueueNew. 828 /// \return maximum number of messages. 829 uint32_t osMessageQueueGetCapacity (osMessageQueueId_t mq_id); 830 831 /// Get maximum message size in a Message Queue. 832 /// \param[in] mq_id message queue ID obtained by \ref osMessageQueueNew. 833 /// \return maximum message size in bytes. 834 uint32_t osMessageQueueGetMsgSize (osMessageQueueId_t mq_id); 835 836 /// Get number of queued messages in a Message Queue. 837 /// \param[in] mq_id message queue ID obtained by \ref osMessageQueueNew. 838 /// \return number of queued messages. 839 uint32_t osMessageQueueGetCount (osMessageQueueId_t mq_id); 840 841 /// Get number of available slots for messages in a Message Queue. 842 /// \param[in] mq_id message queue ID obtained by \ref osMessageQueueNew. 843 /// \return number of available slots for messages. 844 uint32_t osMessageQueueGetSpace (osMessageQueueId_t mq_id); 845 846 /// Reset a Message Queue to initial empty state. 847 /// \param[in] mq_id message queue ID obtained by \ref osMessageQueueNew. 848 /// \return status code that indicates the execution status of the function. 849 osStatus_t osMessageQueueReset (osMessageQueueId_t mq_id); 850 851 /// Delete a Message Queue object. 852 /// \param[in] mq_id message queue ID obtained by \ref osMessageQueueNew. 853 /// \return status code that indicates the execution status of the function. 854 osStatus_t osMessageQueueDelete (osMessageQueueId_t mq_id); 855 856 857 // ==== Handler Functions ==== 858 859 /// Handler for expired thread watchdogs. 860 /// \param[in] thread_id thread ID obtained by \ref osThreadNew or \ref osThreadGetId. 861 /// \return new watchdog reload value or 0 to stop the watchdog. 862 uint32_t osWatchdogAlarm_Handler (osThreadId_t thread_id); 863 864 865 // ==== Zone Management Function ==== 866 867 /// Setup MPU protected zone (called when zone changes). 868 /// \param[in] zone zone number. 869 void osZoneSetup_Callback (uint32_t zone); 870 871 872 // ==== Exception Faults ==== 873 874 /// Resume normal operation when exiting exception faults 875 void osFaultResume (void); 876 877 878 #ifdef __cplusplus 879 } 880 #endif 881 882 #endif // CMSIS_OS2_H_ 883