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-RTOS API 24 * Title: cmsis_os.h template header file 25 * 26 * Version 0.02 27 * Initial Proposal Phase 28 * Version 0.03 29 * osKernelStart added, optional feature: main started as thread 30 * osSemaphores have standard behavior 31 * osTimerCreate does not start the timer, added osTimerStart 32 * osThreadPass is renamed to osThreadYield 33 * Version 1.01 34 * Support for C++ interface 35 * - const attribute removed from the osXxxxDef_t typedefs 36 * - const attribute added to the osXxxxDef macros 37 * Added: osTimerDelete, osMutexDelete, osSemaphoreDelete 38 * Added: osKernelInitialize 39 * Version 1.02 40 * Control functions for short timeouts in microsecond resolution: 41 * Added: osKernelSysTick, osKernelSysTickFrequency, osKernelSysTickMicroSec 42 * Removed: osSignalGet 43 * Version 2.0.0 44 * OS objects creation without macros (dynamic creation and resource allocation): 45 * - added: osXxxxNew functions which replace osXxxxCreate 46 * - added: osXxxxAttr_t structures 47 * - deprecated: osXxxxCreate functions, osXxxxDef_t structures 48 * - deprecated: osXxxxDef and osXxxx macros 49 * osStatus codes simplified and renamed to osStatus_t 50 * osEvent return structure deprecated 51 * Kernel: 52 * - added: osKernelInfo_t and osKernelGetInfo 53 * - added: osKernelState_t and osKernelGetState (replaces osKernelRunning) 54 * - added: osKernelLock, osKernelUnlock 55 * - added: osKernelSuspend, osKernelResume 56 * - added: osKernelGetTickCount, osKernelGetTickFreq 57 * - renamed osKernelSysTick to osKernelGetSysTimerCount 58 * - replaced osKernelSysTickFrequency with osKernelGetSysTimerFreq 59 * - deprecated osKernelSysTickMicroSec 60 * Thread: 61 * - extended number of thread priorities 62 * - renamed osPrioriry to osPrioriry_t 63 * - replaced osThreadCreate with osThreadNew 64 * - added: osThreadGetName 65 * - added: osThreadState_t and osThreadGetState 66 * - added: osThreadGetStackSize, osThreadGetStackSpace 67 * - added: osThreadSuspend, osThreadResume 68 * - added: osThreadJoin, osThreadDetach, osThreadExit 69 * - added: osThreadGetCount, osThreadEnumerate 70 * - added: Thread Flags (moved from Signals) 71 * Signals: 72 * - renamed osSignals to osThreadFlags (moved to Thread Flags) 73 * - changed return value of Set/Clear/Wait functions 74 * - Clear function limited to current running thread 75 * - extended Wait function (options) 76 * - added: osThreadFlagsGet 77 * Event Flags: 78 * - added new independent object for handling Event Flags 79 * Delay and Wait functions: 80 * - added: osDelayUntil 81 * - deprecated: osWait 82 * Timer: 83 * - replaced osTimerCreate with osTimerNew 84 * - added: osTimerGetName, osTimerIsRunning 85 * Mutex: 86 * - extended: attributes (Recursive, Priority Inherit, Robust) 87 * - replaced osMutexCreate with osMutexNew 88 * - renamed osMutexWait to osMutexAcquire 89 * - added: osMutexGetName, osMutexGetOwner 90 * Semaphore: 91 * - extended: maximum and initial token count 92 * - replaced osSemaphoreCreate with osSemaphoreNew 93 * - renamed osSemaphoreWait to osSemaphoreAcquire (changed return value) 94 * - added: osSemaphoreGetName, osSemaphoreGetCount 95 * Memory Pool: 96 * - using osMemoryPool prefix instead of osPool 97 * - replaced osPoolCreate with osMemoryPoolNew 98 * - extended osMemoryPoolAlloc (timeout) 99 * - added: osMemoryPoolGetName 100 * - added: osMemoryPoolGetCapacity, osMemoryPoolGetBlockSize 101 * - added: osMemoryPoolGetCount, osMemoryPoolGetSpace 102 * - added: osMemoryPoolDelete 103 * - deprecated: osPoolCAlloc 104 * Message Queue: 105 * - extended: fixed size message instead of a single 32-bit value 106 * - using osMessageQueue prefix instead of osMessage 107 * - replaced osMessageCreate with osMessageQueueNew 108 * - updated: osMessageQueuePut, osMessageQueueGet 109 * - added: osMessageQueueGetName 110 * - added: osMessageQueueGetCapacity, osMessageQueueGetMsgSize 111 * - added: osMessageQueueGetCount, osMessageQueueGetSpace 112 * - added: osMessageQueueReset, osMessageQueueDelete 113 * Mail Queue: 114 * - deprecated (superseded by extended Message Queue functionality) 115 * Version 2.1.0 116 * Support for critical and uncritical sections (nesting safe): 117 * - updated: osKernelLock, osKernelUnlock 118 * - added: osKernelRestoreLock 119 * Updated Thread and Event Flags: 120 * - changed flags parameter and return type from int32_t to uint32_t 121 * Version 2.1.1 122 * Additional functions allowed to be called from Interrupt Service Routines: 123 * - osKernelGetTickCount, osKernelGetTickFreq 124 * Changed Kernel Tick type to uint32_t: 125 * - updated: osKernelGetTickCount, osDelayUntil 126 * Version 2.1.2 127 * Additional functions allowed to be called from Interrupt Service Routines: 128 * - osKernelGetInfo, osKernelGetState 129 * Version 2.1.3 130 * Additional functions allowed to be called from Interrupt Service Routines: 131 * - osThreadGetId 132 *---------------------------------------------------------------------------*/ 133 134 #ifndef CMSIS_OS_H_ 135 #define CMSIS_OS_H_ 136 137 /// \b osCMSIS identifies the CMSIS-RTOS API version. 138 #define osCMSIS 0x20001U ///< API version (main[31:16].sub[15:0]) 139 140 /// \note CAN BE CHANGED: \b osCMSIS_KERNEL identifies the underlying RTOS kernel and version number. 141 #define osCMSIS_KERNEL 0x10000U ///< RTOS identification and version (main[31:16].sub[15:0]) 142 143 /// \note CAN BE CHANGED: \b osKernelSystemId identifies the underlying RTOS kernel. 144 #define osKernelSystemId "KERNEL V1.0" ///< RTOS identification string 145 146 /// \note CAN BE CHANGED: \b osFeature_xxx identifies RTOS features. 147 #define osFeature_MainThread 0 ///< main thread 1=main can be thread, 0=not available 148 #define osFeature_Signals 16U ///< maximum number of Signal Flags available per thread 149 #define osFeature_Semaphore 65535U ///< maximum count for \ref osSemaphoreCreate function 150 #define osFeature_Wait 0 ///< osWait function: 1=available, 0=not available 151 #define osFeature_SysTick 1 ///< osKernelSysTick functions: 1=available, 0=not available 152 #define osFeature_Pool 1 ///< Memory Pools: 1=available, 0=not available 153 #define osFeature_MessageQ 1 ///< Message Queues: 1=available, 0=not available 154 #define osFeature_MailQ 1 ///< Mail Queues: 1=available, 0=not available 155 156 #if (osCMSIS >= 0x20000U) 157 #include "cmsis_os2.h" 158 #else 159 #include <stdint.h> 160 #include <stddef.h> 161 #endif 162 163 #ifdef __cplusplus 164 extern "C" 165 { 166 #endif 167 168 169 // ==== Enumerations, structures, defines ==== 170 171 /// Priority values. 172 #if (osCMSIS < 0x20000U) 173 typedef enum { 174 osPriorityIdle = -3, ///< Priority: idle (lowest) 175 osPriorityLow = -2, ///< Priority: low 176 osPriorityBelowNormal = -1, ///< Priority: below normal 177 osPriorityNormal = 0, ///< Priority: normal (default) 178 osPriorityAboveNormal = +1, ///< Priority: above normal 179 osPriorityHigh = +2, ///< Priority: high 180 osPriorityRealtime = +3, ///< Priority: realtime (highest) 181 osPriorityError = 0x84, ///< System cannot determine priority or illegal priority. 182 osPriorityReserved = 0x7FFFFFFF ///< Prevents enum down-size compiler optimization. 183 } osPriority; 184 #else 185 #define osPriority osPriority_t 186 #endif 187 188 /// Entry point of a thread. 189 typedef void (*os_pthread) (void const *argument); 190 191 /// Entry point of a timer call back function. 192 typedef void (*os_ptimer) (void const *argument); 193 194 /// Timer type. 195 #if (osCMSIS < 0x20000U) 196 typedef enum { 197 osTimerOnce = 0, ///< One-shot timer. 198 osTimerPeriodic = 1 ///< Repeating timer. 199 } os_timer_type; 200 #else 201 #define os_timer_type osTimerType_t 202 #endif 203 204 /// Timeout value. 205 #define osWaitForever 0xFFFFFFFFU ///< Wait forever timeout value. 206 207 /// Status code values returned by CMSIS-RTOS functions. 208 #if (osCMSIS < 0x20000U) 209 typedef enum { 210 osOK = 0, ///< Function completed; no error or event occurred. 211 osEventSignal = 0x08, ///< Function completed; signal event occurred. 212 osEventMessage = 0x10, ///< Function completed; message event occurred. 213 osEventMail = 0x20, ///< Function completed; mail event occurred. 214 osEventTimeout = 0x40, ///< Function completed; timeout occurred. 215 osErrorParameter = 0x80, ///< Parameter error: a mandatory parameter was missing or specified an incorrect object. 216 osErrorResource = 0x81, ///< Resource not available: a specified resource was not available. 217 osErrorTimeoutResource = 0xC1, ///< Resource not available within given time: a specified resource was not available within the timeout period. 218 osErrorISR = 0x82, ///< Not allowed in ISR context: the function cannot be called from interrupt service routines. 219 osErrorISRRecursive = 0x83, ///< Function called multiple times from ISR with same object. 220 osErrorPriority = 0x84, ///< System cannot determine priority or thread has illegal priority. 221 osErrorNoMemory = 0x85, ///< System is out of memory: it was impossible to allocate or reserve memory for the operation. 222 osErrorValue = 0x86, ///< Value of a parameter is out of range. 223 osErrorOS = 0xFF, ///< Unspecified RTOS error: run-time error but no other error message fits. 224 osStatusReserved = 0x7FFFFFFF ///< Prevents enum down-size compiler optimization. 225 } osStatus; 226 #else 227 typedef int32_t osStatus; 228 #define osEventSignal (0x08) 229 #define osEventMessage (0x10) 230 #define osEventMail (0x20) 231 #define osEventTimeout (0x40) 232 #define osErrorOS osError 233 #define osErrorTimeoutResource osErrorTimeout 234 #define osErrorISRRecursive (-126) 235 #define osErrorValue (-127) 236 #define osErrorPriority (-128) 237 #endif 238 239 240 // >>> the following data type definitions may be adapted towards a specific RTOS 241 242 /// Thread ID identifies the thread. 243 /// \note CAN BE CHANGED: \b implementation specific in every CMSIS-RTOS. 244 #if (osCMSIS < 0x20000U) 245 typedef void *osThreadId; 246 #else 247 #define osThreadId osThreadId_t 248 #endif 249 250 /// Timer ID identifies the timer. 251 /// \note CAN BE CHANGED: \b implementation specific in every CMSIS-RTOS. 252 #if (osCMSIS < 0x20000U) 253 typedef void *osTimerId; 254 #else 255 #define osTimerId osTimerId_t 256 #endif 257 258 /// Mutex ID identifies the mutex. 259 /// \note CAN BE CHANGED: \b implementation specific in every CMSIS-RTOS. 260 #if (osCMSIS < 0x20000U) 261 typedef void *osMutexId; 262 #else 263 #define osMutexId osMutexId_t 264 #endif 265 266 /// Semaphore ID identifies the semaphore. 267 /// \note CAN BE CHANGED: \b implementation specific in every CMSIS-RTOS. 268 #if (osCMSIS < 0x20000U) 269 typedef void *osSemaphoreId; 270 #else 271 #define osSemaphoreId osSemaphoreId_t 272 #endif 273 274 /// Pool ID identifies the memory pool. 275 /// \note CAN BE CHANGED: \b implementation specific in every CMSIS-RTOS. 276 typedef void *osPoolId; 277 278 /// Message ID identifies the message queue. 279 /// \note CAN BE CHANGED: \b implementation specific in every CMSIS-RTOS. 280 typedef void *osMessageQId; 281 282 /// Mail ID identifies the mail queue. 283 /// \note CAN BE CHANGED: \b implementation specific in every CMSIS-RTOS. 284 typedef void *osMailQId; 285 286 287 /// Thread Definition structure contains startup information of a thread. 288 /// \note CAN BE CHANGED: \b os_thread_def is implementation specific in every CMSIS-RTOS. 289 #if (osCMSIS < 0x20000U) 290 typedef struct os_thread_def { 291 os_pthread pthread; ///< start address of thread function 292 osPriority tpriority; ///< initial thread priority 293 uint32_t instances; ///< maximum number of instances of that thread function 294 uint32_t stacksize; ///< stack size requirements in bytes; 0 is default stack size 295 } osThreadDef_t; 296 #else 297 typedef struct os_thread_def { 298 os_pthread pthread; ///< start address of thread function 299 osThreadAttr_t attr; ///< thread attributes 300 } osThreadDef_t; 301 #endif 302 303 /// Timer Definition structure contains timer parameters. 304 /// \note CAN BE CHANGED: \b os_timer_def is implementation specific in every CMSIS-RTOS. 305 #if (osCMSIS < 0x20000U) 306 typedef struct os_timer_def { 307 os_ptimer ptimer; ///< start address of a timer function 308 } osTimerDef_t; 309 #else 310 typedef struct os_timer_def { 311 os_ptimer ptimer; ///< start address of a timer function 312 osTimerAttr_t attr; ///< timer attributes 313 } osTimerDef_t; 314 #endif 315 316 /// Mutex Definition structure contains setup information for a mutex. 317 /// \note CAN BE CHANGED: \b os_mutex_def is implementation specific in every CMSIS-RTOS. 318 #if (osCMSIS < 0x20000U) 319 typedef struct os_mutex_def { 320 uint32_t dummy; ///< dummy value 321 } osMutexDef_t; 322 #else 323 #define osMutexDef_t osMutexAttr_t 324 #endif 325 326 /// Semaphore Definition structure contains setup information for a semaphore. 327 /// \note CAN BE CHANGED: \b os_semaphore_def is implementation specific in every CMSIS-RTOS. 328 #if (osCMSIS < 0x20000U) 329 typedef struct os_semaphore_def { 330 uint32_t dummy; ///< dummy value 331 } osSemaphoreDef_t; 332 #else 333 #define osSemaphoreDef_t osSemaphoreAttr_t 334 #endif 335 336 /// Definition structure for memory block allocation. 337 /// \note CAN BE CHANGED: \b os_pool_def is implementation specific in every CMSIS-RTOS. 338 #if (osCMSIS < 0x20000U) 339 typedef struct os_pool_def { 340 uint32_t pool_sz; ///< number of items (elements) in the pool 341 uint32_t item_sz; ///< size of an item 342 void *pool; ///< pointer to memory for pool 343 } osPoolDef_t; 344 #else 345 typedef struct os_pool_def { 346 uint32_t pool_sz; ///< number of items (elements) in the pool 347 uint32_t item_sz; ///< size of an item 348 osMemoryPoolAttr_t attr; ///< memory pool attributes 349 } osPoolDef_t; 350 #endif 351 352 /// Definition structure for message queue. 353 /// \note CAN BE CHANGED: \b os_messageQ_def is implementation specific in every CMSIS-RTOS. 354 #if (osCMSIS < 0x20000U) 355 typedef struct os_messageQ_def { 356 uint32_t queue_sz; ///< number of elements in the queue 357 void *pool; ///< memory array for messages 358 } osMessageQDef_t; 359 #else 360 typedef struct os_messageQ_def { 361 uint32_t queue_sz; ///< number of elements in the queue 362 osMessageQueueAttr_t attr; ///< message queue attributes 363 } osMessageQDef_t; 364 #endif 365 366 /// Definition structure for mail queue. 367 /// \note CAN BE CHANGED: \b os_mailQ_def is implementation specific in every CMSIS-RTOS. 368 #if (osCMSIS < 0x20000U) 369 typedef struct os_mailQ_def { 370 uint32_t queue_sz; ///< number of elements in the queue 371 uint32_t item_sz; ///< size of an item 372 void *pool; ///< memory array for mail 373 } osMailQDef_t; 374 #else 375 typedef struct os_mailQ_def { 376 uint32_t queue_sz; ///< number of elements in the queue 377 uint32_t item_sz; ///< size of an item 378 void *mail; ///< pointer to mail 379 osMemoryPoolAttr_t mp_attr; ///< memory pool attributes 380 osMessageQueueAttr_t mq_attr; ///< message queue attributes 381 } osMailQDef_t; 382 #endif 383 384 385 /// Event structure contains detailed information about an event. 386 typedef struct { 387 osStatus status; ///< status code: event or error information 388 union { 389 uint32_t v; ///< message as 32-bit value 390 void *p; ///< message or mail as void pointer 391 int32_t signals; ///< signal flags 392 } value; ///< event value 393 union { 394 osMailQId mail_id; ///< mail id obtained by \ref osMailCreate 395 osMessageQId message_id; ///< message id obtained by \ref osMessageCreate 396 } def; ///< event definition 397 } osEvent; 398 399 400 // ==== Kernel Management Functions ==== 401 402 /// Initialize the RTOS Kernel for creating objects. 403 /// \return status code that indicates the execution status of the function. 404 #if (osCMSIS < 0x20000U) 405 osStatus osKernelInitialize (void); 406 #endif 407 408 /// Start the RTOS Kernel scheduler. 409 /// \return status code that indicates the execution status of the function. 410 #if (osCMSIS < 0x20000U) 411 osStatus osKernelStart (void); 412 #endif 413 414 /// Check if the RTOS kernel is already started. 415 /// \return 0 RTOS is not started, 1 RTOS is started. 416 #if (osCMSIS < 0x20000U) 417 int32_t osKernelRunning(void); 418 #endif 419 420 #if (defined(osFeature_SysTick) && (osFeature_SysTick != 0)) // System Timer available 421 422 /// Get the RTOS kernel system timer counter. 423 /// \return RTOS kernel system timer as 32-bit value 424 #if (osCMSIS < 0x20000U) 425 uint32_t osKernelSysTick (void); 426 #else 427 #define osKernelSysTick osKernelGetSysTimerCount 428 #endif 429 430 /// The RTOS kernel system timer frequency in Hz. 431 /// \note Reflects the system timer setting and is typically defined in a configuration file. 432 #if (osCMSIS < 0x20000U) 433 #define osKernelSysTickFrequency 100000000 434 #endif 435 436 /// Convert a microseconds value to a RTOS kernel system timer value. 437 /// \param microsec time value in microseconds. 438 /// \return time value normalized to the \ref osKernelSysTickFrequency 439 #if (osCMSIS < 0x20000U) 440 #define osKernelSysTickMicroSec(microsec) (((uint64_t)microsec * (osKernelSysTickFrequency)) / 1000000) 441 #else 442 #define osKernelSysTickMicroSec(microsec) (((uint64_t)microsec * osKernelGetSysTimerFreq()) / 1000000) 443 #endif 444 445 #endif // System Timer available 446 447 448 // ==== Thread Management Functions ==== 449 450 /// Create a Thread Definition with function, priority, and stack requirements. 451 /// \param name name of the thread function. 452 /// \param priority initial priority of the thread function. 453 /// \param instances number of possible thread instances. 454 /// \param stacksz stack size (in bytes) requirements for the thread function. 455 /// \note CAN BE CHANGED: The parameters to \b osThreadDef shall be consistent but the 456 /// macro body is implementation specific in every CMSIS-RTOS. 457 #if defined (osObjectsExternal) // object is external 458 #define osThreadDef(name, priority, instances, stacksz) \ 459 extern const osThreadDef_t os_thread_def_##name 460 #else // define the object 461 #if (osCMSIS < 0x20000U) 462 #define osThreadDef(name, priority, instances, stacksz) \ 463 const osThreadDef_t os_thread_def_##name = \ 464 { (name), (priority), (instances), (stacksz) } 465 #else 466 #define osThreadDef(name, priority, instances, stacksz) \ 467 const osThreadDef_t os_thread_def_##name = \ 468 { (name), \ 469 { NULL, osThreadDetached, NULL, 0U, NULL, 8*((stacksz+7)/8), (priority), 0U, 0U } } 470 #endif 471 #endif 472 473 /// Access a Thread definition. 474 /// \param name name of the thread definition object. 475 /// \note CAN BE CHANGED: The parameter to \b osThread shall be consistent but the 476 /// macro body is implementation specific in every CMSIS-RTOS. 477 #define osThread(name) \ 478 &os_thread_def_##name 479 480 /// Create a thread and add it to Active Threads and set it to state READY. 481 /// \param[in] thread_def thread definition referenced with \ref osThread. 482 /// \param[in] argument pointer that is passed to the thread function as start argument. 483 /// \return thread ID for reference by other functions or NULL in case of error. 484 osThreadId osThreadCreate (const osThreadDef_t *thread_def, void *argument); 485 486 /// Return the thread ID of the current running thread. 487 /// \return thread ID for reference by other functions or NULL in case of error. 488 #if (osCMSIS < 0x20000U) 489 osThreadId osThreadGetId (void); 490 #endif 491 492 /// Change priority of a thread. 493 /// \param[in] thread_id thread ID obtained by \ref osThreadCreate or \ref osThreadGetId. 494 /// \param[in] priority new priority value for the thread function. 495 /// \return status code that indicates the execution status of the function. 496 #if (osCMSIS < 0x20000U) 497 osStatus osThreadSetPriority (osThreadId thread_id, osPriority priority); 498 #endif 499 500 /// Get current priority of a thread. 501 /// \param[in] thread_id thread ID obtained by \ref osThreadCreate or \ref osThreadGetId. 502 /// \return current priority value of the specified thread. 503 #if (osCMSIS < 0x20000U) 504 osPriority osThreadGetPriority (osThreadId thread_id); 505 #endif 506 507 /// Pass control to next thread that is in state \b READY. 508 /// \return status code that indicates the execution status of the function. 509 #if (osCMSIS < 0x20000U) 510 osStatus osThreadYield (void); 511 #endif 512 513 /// Terminate execution of a thread. 514 /// \param[in] thread_id thread ID obtained by \ref osThreadCreate or \ref osThreadGetId. 515 /// \return status code that indicates the execution status of the function. 516 #if (osCMSIS < 0x20000U) 517 osStatus osThreadTerminate (osThreadId thread_id); 518 #endif 519 520 521 // ==== Signal Management ==== 522 523 /// Set the specified Signal Flags of an active thread. 524 /// \param[in] thread_id thread ID obtained by \ref osThreadCreate or \ref osThreadGetId. 525 /// \param[in] signals specifies the signal flags of the thread that should be set. 526 /// \return previous signal flags of the specified thread or 0x80000000 in case of incorrect parameters. 527 int32_t osSignalSet (osThreadId thread_id, int32_t signals); 528 529 /// Clear the specified Signal Flags of an active thread. 530 /// \param[in] thread_id thread ID obtained by \ref osThreadCreate or \ref osThreadGetId. 531 /// \param[in] signals specifies the signal flags of the thread that shall be cleared. 532 /// \return previous signal flags of the specified thread or 0x80000000 in case of incorrect parameters or call from ISR. 533 int32_t osSignalClear (osThreadId thread_id, int32_t signals); 534 535 /// Wait for one or more Signal Flags to become signaled for the current \b RUNNING thread. 536 /// \param[in] signals wait until all specified signal flags set or 0 for any single signal flag. 537 /// \param[in] millisec \ref CMSIS_RTOS_TimeOutValue or 0 in case of no time-out. 538 /// \return event flag information or error code. 539 osEvent osSignalWait (int32_t signals, uint32_t millisec); 540 541 542 // ==== Generic Wait Functions ==== 543 544 /// Wait for Timeout (Time Delay). 545 /// \param[in] millisec \ref CMSIS_RTOS_TimeOutValue "time delay" value 546 /// \return status code that indicates the execution status of the function. 547 #if (osCMSIS < 0x20000U) 548 osStatus osDelay (uint32_t millisec); 549 #endif 550 551 #if (defined (osFeature_Wait) && (osFeature_Wait != 0)) // Generic Wait available 552 553 /// Wait for Signal, Message, Mail, or Timeout. 554 /// \param[in] millisec \ref CMSIS_RTOS_TimeOutValue or 0 in case of no time-out 555 /// \return event that contains signal, message, or mail information or error code. 556 osEvent osWait (uint32_t millisec); 557 558 #endif // Generic Wait available 559 560 561 // ==== Timer Management Functions ==== 562 563 /// Define a Timer object. 564 /// \param name name of the timer object. 565 /// \param function name of the timer call back function. 566 /// \note CAN BE CHANGED: The parameter to \b osTimerDef shall be consistent but the 567 /// macro body is implementation specific in every CMSIS-RTOS. 568 #if defined (osObjectsExternal) // object is external 569 #define osTimerDef(name, function) \ 570 extern const osTimerDef_t os_timer_def_##name 571 #else // define the object 572 #if (osCMSIS < 0x20000U) 573 #define osTimerDef(name, function) \ 574 const osTimerDef_t os_timer_def_##name = { (function) } 575 #else 576 #define osTimerDef(name, function) \ 577 const osTimerDef_t os_timer_def_##name = \ 578 { (function), { NULL, 0U, NULL, 0U } } 579 #endif 580 #endif 581 582 /// Access a Timer definition. 583 /// \param name name of the timer object. 584 /// \note CAN BE CHANGED: The parameter to \b osTimer shall be consistent but the 585 /// macro body is implementation specific in every CMSIS-RTOS. 586 #define osTimer(name) \ 587 &os_timer_def_##name 588 589 /// Create and Initialize a timer. 590 /// \param[in] timer_def timer object referenced with \ref osTimer. 591 /// \param[in] type osTimerOnce for one-shot or osTimerPeriodic for periodic behavior. 592 /// \param[in] argument argument to the timer call back function. 593 /// \return timer ID for reference by other functions or NULL in case of error. 594 osTimerId osTimerCreate (const osTimerDef_t *timer_def, os_timer_type type, void *argument); 595 596 /// Start or restart a timer. 597 /// \param[in] timer_id timer ID obtained by \ref osTimerCreate. 598 /// \param[in] millisec \ref CMSIS_RTOS_TimeOutValue "time delay" value of the timer. 599 /// \return status code that indicates the execution status of the function. 600 #if (osCMSIS < 0x20000U) 601 osStatus osTimerStart (osTimerId timer_id, uint32_t millisec); 602 #endif 603 604 /// Stop a timer. 605 /// \param[in] timer_id timer ID obtained by \ref osTimerCreate. 606 /// \return status code that indicates the execution status of the function. 607 #if (osCMSIS < 0x20000U) 608 osStatus osTimerStop (osTimerId timer_id); 609 #endif 610 611 /// Delete a timer. 612 /// \param[in] timer_id timer ID obtained by \ref osTimerCreate. 613 /// \return status code that indicates the execution status of the function. 614 #if (osCMSIS < 0x20000U) 615 osStatus osTimerDelete (osTimerId timer_id); 616 #endif 617 618 619 // ==== Mutex Management Functions ==== 620 621 /// Define a Mutex. 622 /// \param name name of the mutex object. 623 /// \note CAN BE CHANGED: The parameter to \b osMutexDef shall be consistent but the 624 /// macro body is implementation specific in every CMSIS-RTOS. 625 #if defined (osObjectsExternal) // object is external 626 #define osMutexDef(name) \ 627 extern const osMutexDef_t os_mutex_def_##name 628 #else // define the object 629 #if (osCMSIS < 0x20000U) 630 #define osMutexDef(name) \ 631 const osMutexDef_t os_mutex_def_##name = { 0 } 632 #else 633 #define osMutexDef(name) \ 634 const osMutexDef_t os_mutex_def_##name = \ 635 { NULL, osMutexRecursive | osMutexPrioInherit | osMutexRobust, NULL, 0U } 636 #endif 637 #endif 638 639 /// Access a Mutex definition. 640 /// \param name name of the mutex object. 641 /// \note CAN BE CHANGED: The parameter to \b osMutex shall be consistent but the 642 /// macro body is implementation specific in every CMSIS-RTOS. 643 #define osMutex(name) \ 644 &os_mutex_def_##name 645 646 /// Create and Initialize a Mutex object. 647 /// \param[in] mutex_def mutex definition referenced with \ref osMutex. 648 /// \return mutex ID for reference by other functions or NULL in case of error. 649 osMutexId osMutexCreate (const osMutexDef_t *mutex_def); 650 651 /// Wait until a Mutex becomes available. 652 /// \param[in] mutex_id mutex ID obtained by \ref osMutexCreate. 653 /// \param[in] millisec \ref CMSIS_RTOS_TimeOutValue or 0 in case of no time-out. 654 /// \return status code that indicates the execution status of the function. 655 #if (osCMSIS < 0x20000U) 656 osStatus osMutexWait (osMutexId mutex_id, uint32_t millisec); 657 #else 658 #define osMutexWait osMutexAcquire 659 #endif 660 661 /// Release a Mutex that was obtained by \ref osMutexWait. 662 /// \param[in] mutex_id mutex ID obtained by \ref osMutexCreate. 663 /// \return status code that indicates the execution status of the function. 664 #if (osCMSIS < 0x20000U) 665 osStatus osMutexRelease (osMutexId mutex_id); 666 #endif 667 668 /// Delete a Mutex object. 669 /// \param[in] mutex_id mutex ID obtained by \ref osMutexCreate. 670 /// \return status code that indicates the execution status of the function. 671 #if (osCMSIS < 0x20000U) 672 osStatus osMutexDelete (osMutexId mutex_id); 673 #endif 674 675 676 // ==== Semaphore Management Functions ==== 677 678 #if (defined (osFeature_Semaphore) && (osFeature_Semaphore != 0U)) // Semaphore available 679 680 /// Define a Semaphore object. 681 /// \param name name of the semaphore object. 682 /// \note CAN BE CHANGED: The parameter to \b osSemaphoreDef shall be consistent but the 683 /// macro body is implementation specific in every CMSIS-RTOS. 684 #if defined (osObjectsExternal) // object is external 685 #define osSemaphoreDef(name) \ 686 extern const osSemaphoreDef_t os_semaphore_def_##name 687 #else // define the object 688 #if (osCMSIS < 0x20000U) 689 #define osSemaphoreDef(name) \ 690 const osSemaphoreDef_t os_semaphore_def_##name = { 0 } 691 #else 692 #define osSemaphoreDef(name) \ 693 const osSemaphoreDef_t os_semaphore_def_##name = \ 694 { NULL, 0U, NULL, 0U } 695 #endif 696 #endif 697 698 /// Access a Semaphore definition. 699 /// \param name name of the semaphore object. 700 /// \note CAN BE CHANGED: The parameter to \b osSemaphore shall be consistent but the 701 /// macro body is implementation specific in every CMSIS-RTOS. 702 #define osSemaphore(name) \ 703 &os_semaphore_def_##name 704 705 /// Create and Initialize a Semaphore object. 706 /// \param[in] semaphore_def semaphore definition referenced with \ref osSemaphore. 707 /// \param[in] count maximum and initial number of available tokens. 708 /// \return semaphore ID for reference by other functions or NULL in case of error. 709 osSemaphoreId osSemaphoreCreate (const osSemaphoreDef_t *semaphore_def, int32_t count); 710 711 /// Wait until a Semaphore token becomes available. 712 /// \param[in] semaphore_id semaphore object referenced with \ref osSemaphoreCreate. 713 /// \param[in] millisec \ref CMSIS_RTOS_TimeOutValue or 0 in case of no time-out. 714 /// \return number of available tokens, or -1 in case of incorrect parameters. 715 int32_t osSemaphoreWait (osSemaphoreId semaphore_id, uint32_t millisec); 716 717 /// Release a Semaphore token. 718 /// \param[in] semaphore_id semaphore object referenced with \ref osSemaphoreCreate. 719 /// \return status code that indicates the execution status of the function. 720 #if (osCMSIS < 0x20000U) 721 osStatus osSemaphoreRelease (osSemaphoreId semaphore_id); 722 #endif 723 724 /// Delete a Semaphore object. 725 /// \param[in] semaphore_id semaphore object referenced with \ref osSemaphoreCreate. 726 /// \return status code that indicates the execution status of the function. 727 #if (osCMSIS < 0x20000U) 728 osStatus osSemaphoreDelete (osSemaphoreId semaphore_id); 729 #endif 730 731 #endif // Semaphore available 732 733 734 // ==== Memory Pool Management Functions ==== 735 736 #if (defined(osFeature_Pool) && (osFeature_Pool != 0)) // Memory Pool available 737 738 /// \brief Define a Memory Pool. 739 /// \param name name of the memory pool. 740 /// \param no maximum number of blocks (objects) in the memory pool. 741 /// \param type data type of a single block (object). 742 /// \note CAN BE CHANGED: The parameter to \b osPoolDef shall be consistent but the 743 /// macro body is implementation specific in every CMSIS-RTOS. 744 #if defined (osObjectsExternal) // object is external 745 #define osPoolDef(name, no, type) \ 746 extern const osPoolDef_t os_pool_def_##name 747 #else // define the object 748 #if (osCMSIS < 0x20000U) 749 #define osPoolDef(name, no, type) \ 750 const osPoolDef_t os_pool_def_##name = \ 751 { (no), sizeof(type), NULL } 752 #else 753 #define osPoolDef(name, no, type) \ 754 const osPoolDef_t os_pool_def_##name = \ 755 { (no), sizeof(type), { NULL, 0U, NULL, 0U, NULL, 0U } } 756 #endif 757 #endif 758 759 /// \brief Access a Memory Pool definition. 760 /// \param name name of the memory pool 761 /// \note CAN BE CHANGED: The parameter to \b osPool shall be consistent but the 762 /// macro body is implementation specific in every CMSIS-RTOS. 763 #define osPool(name) \ 764 &os_pool_def_##name 765 766 /// Create and Initialize a Memory Pool object. 767 /// \param[in] pool_def memory pool definition referenced with \ref osPool. 768 /// \return memory pool ID for reference by other functions or NULL in case of error. 769 osPoolId osPoolCreate (const osPoolDef_t *pool_def); 770 771 /// Allocate a memory block from a Memory Pool. 772 /// \param[in] pool_id memory pool ID obtain referenced with \ref osPoolCreate. 773 /// \return address of the allocated memory block or NULL in case of no memory available. 774 void *osPoolAlloc (osPoolId pool_id); 775 776 /// Allocate a memory block from a Memory Pool and set memory block to zero. 777 /// \param[in] pool_id memory pool ID obtain referenced with \ref osPoolCreate. 778 /// \return address of the allocated memory block or NULL in case of no memory available. 779 void *osPoolCAlloc (osPoolId pool_id); 780 781 /// Return an allocated memory block back to a Memory Pool. 782 /// \param[in] pool_id memory pool ID obtain referenced with \ref osPoolCreate. 783 /// \param[in] block address of the allocated memory block to be returned to the memory pool. 784 /// \return status code that indicates the execution status of the function. 785 osStatus osPoolFree (osPoolId pool_id, void *block); 786 787 #endif // Memory Pool available 788 789 790 // ==== Message Queue Management Functions ==== 791 792 #if (defined(osFeature_MessageQ) && (osFeature_MessageQ != 0)) // Message Queue available 793 794 /// \brief Create a Message Queue Definition. 795 /// \param name name of the queue. 796 /// \param queue_sz maximum number of messages in the queue. 797 /// \param type data type of a single message element (for debugger). 798 /// \note CAN BE CHANGED: The parameter to \b osMessageQDef shall be consistent but the 799 /// macro body is implementation specific in every CMSIS-RTOS. 800 #if defined (osObjectsExternal) // object is external 801 #define osMessageQDef(name, queue_sz, type) \ 802 extern const osMessageQDef_t os_messageQ_def_##name 803 #else // define the object 804 #if (osCMSIS < 0x20000U) 805 #define osMessageQDef(name, queue_sz, type) \ 806 const osMessageQDef_t os_messageQ_def_##name = \ 807 { (queue_sz), NULL } 808 #else 809 #define osMessageQDef(name, queue_sz, type) \ 810 const osMessageQDef_t os_messageQ_def_##name = \ 811 { (queue_sz), { NULL, 0U, NULL, 0U, NULL, 0U } } 812 #endif 813 #endif 814 815 /// \brief Access a Message Queue Definition. 816 /// \param name name of the queue 817 /// \note CAN BE CHANGED: The parameter to \b osMessageQ shall be consistent but the 818 /// macro body is implementation specific in every CMSIS-RTOS. 819 #define osMessageQ(name) \ 820 &os_messageQ_def_##name 821 822 /// Create and Initialize a Message Queue object. 823 /// \param[in] queue_def message queue definition referenced with \ref osMessageQ. 824 /// \param[in] thread_id thread ID (obtained by \ref osThreadCreate or \ref osThreadGetId) or NULL. 825 /// \return message queue ID for reference by other functions or NULL in case of error. 826 osMessageQId osMessageCreate (const osMessageQDef_t *queue_def, osThreadId thread_id); 827 828 /// Put a Message to a Queue. 829 /// \param[in] queue_id message queue ID obtained with \ref osMessageCreate. 830 /// \param[in] info message information. 831 /// \param[in] millisec \ref CMSIS_RTOS_TimeOutValue or 0 in case of no time-out. 832 /// \return status code that indicates the execution status of the function. 833 osStatus osMessagePut (osMessageQId queue_id, uint32_t info, uint32_t millisec); 834 835 /// Get a Message from a Queue or timeout if Queue is empty. 836 /// \param[in] queue_id message queue ID obtained with \ref osMessageCreate. 837 /// \param[in] millisec \ref CMSIS_RTOS_TimeOutValue or 0 in case of no time-out. 838 /// \return event information that includes status code. 839 osEvent osMessageGet (osMessageQId queue_id, uint32_t millisec); 840 841 #endif // Message Queue available 842 843 844 // ==== Mail Queue Management Functions ==== 845 846 #if (defined(osFeature_MailQ) && (osFeature_MailQ != 0)) // Mail Queue available 847 848 /// \brief Create a Mail Queue Definition. 849 /// \param name name of the queue. 850 /// \param queue_sz maximum number of mails in the queue. 851 /// \param type data type of a single mail element. 852 /// \note CAN BE CHANGED: The parameter to \b osMailQDef shall be consistent but the 853 /// macro body is implementation specific in every CMSIS-RTOS. 854 #if defined (osObjectsExternal) // object is external 855 #define osMailQDef(name, queue_sz, type) \ 856 extern const osMailQDef_t os_mailQ_def_##name 857 #else // define the object 858 #if (osCMSIS < 0x20000U) 859 #define osMailQDef(name, queue_sz, type) \ 860 const osMailQDef_t os_mailQ_def_##name = \ 861 { (queue_sz), sizeof(type), NULL } 862 #else 863 #define osMailQDef(name, queue_sz, type) \ 864 static void *os_mail_p_##name[2]; \ 865 const osMailQDef_t os_mailQ_def_##name = \ 866 { (queue_sz), sizeof(type), (&os_mail_p_##name), \ 867 { NULL, 0U, NULL, 0U, NULL, 0U }, \ 868 { NULL, 0U, NULL, 0U, NULL, 0U } } 869 #endif 870 #endif 871 872 /// \brief Access a Mail Queue Definition. 873 /// \param name name of the queue 874 /// \note CAN BE CHANGED: The parameter to \b osMailQ shall be consistent but the 875 /// macro body is implementation specific in every CMSIS-RTOS. 876 #define osMailQ(name) \ 877 &os_mailQ_def_##name 878 879 /// Create and Initialize a Mail Queue object. 880 /// \param[in] queue_def mail queue definition referenced with \ref osMailQ. 881 /// \param[in] thread_id thread ID (obtained by \ref osThreadCreate or \ref osThreadGetId) or NULL. 882 /// \return mail queue ID for reference by other functions or NULL in case of error. 883 osMailQId osMailCreate (const osMailQDef_t *queue_def, osThreadId thread_id); 884 885 /// Allocate a memory block for mail from a mail memory pool. 886 /// \param[in] queue_id mail queue ID obtained with \ref osMailCreate. 887 /// \param[in] millisec \ref CMSIS_RTOS_TimeOutValue or 0 in case of no time-out 888 /// \return pointer to memory block that can be filled with mail or NULL in case of error. 889 void *osMailAlloc (osMailQId queue_id, uint32_t millisec); 890 891 /// Allocate a memory block for mail from a mail memory pool and set memory block to zero. 892 /// \param[in] queue_id mail queue ID obtained with \ref osMailCreate. 893 /// \param[in] millisec \ref CMSIS_RTOS_TimeOutValue or 0 in case of no time-out 894 /// \return pointer to memory block that can be filled with mail or NULL in case of error. 895 void *osMailCAlloc (osMailQId queue_id, uint32_t millisec); 896 897 /// Put a Mail into a Queue. 898 /// \param[in] queue_id mail queue ID obtained with \ref osMailCreate. 899 /// \param[in] mail pointer to memory with mail to put into a queue. 900 /// \return status code that indicates the execution status of the function. 901 osStatus osMailPut (osMailQId queue_id, const void *mail); 902 903 /// Get a Mail from a Queue or timeout if Queue is empty. 904 /// \param[in] queue_id mail queue ID obtained with \ref osMailCreate. 905 /// \param[in] millisec \ref CMSIS_RTOS_TimeOutValue or 0 in case of no time-out. 906 /// \return event information that includes status code. 907 osEvent osMailGet (osMailQId queue_id, uint32_t millisec); 908 909 /// Free a memory block by returning it to a mail memory pool. 910 /// \param[in] queue_id mail queue ID obtained with \ref osMailCreate. 911 /// \param[in] mail pointer to memory block that was obtained with \ref osMailGet. 912 /// \return status code that indicates the execution status of the function. 913 osStatus osMailFree (osMailQId queue_id, void *mail); 914 915 #endif // Mail Queue available 916 917 918 #ifdef __cplusplus 919 } 920 #endif 921 922 #endif // CMSIS_OS_H_ 923