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