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