1 /* ---------------------------------------------------------------------- 2 * Copyright (C) 2012 ARM Limited. All rights reserved. 3 * 4 * $Date: 5. March 2012 5 * $Revision: V0.03 6 * 7 * Project: CMSIS-RTOS API 8 * Title: cmsis_os.h template header file 9 * 10 * Version 0.02 11 * Initial Proposal Phase 12 * Version 0.03 13 * osKernelStart added, optional feature: main started as thread 14 * osSemaphores have standard behaviour 15 * osTimerCreate does not start the timer, added osTimerStart 16 * osThreadPass is renamed to osThreadYield 17 * -------------------------------------------------------------------- */ 18 19 /** 20 \page cmsis_os_h Header File Template: cmsis_os.h 21 22 The file \b cmsis_os.h is a template header file for a CMSIS-RTOS compliant Real-Time Operating System (RTOS). 23 Each RTOS that is compliant with CMSIS-RTOS shall provide a specific \b cmsis_os.h header file that represents 24 its implementation. 25 26 The file cmsis_os.h contains: 27 - CMSIS-RTOS API function definitions 28 - struct definitions for parameters and return types 29 - status and priority values used by CMSIS-RTOS API functions 30 - macros for defining threads and other kernel objects 31 32 33 <b>Name conventions and header file modifications</b> 34 35 All definitions are prefixed with \b os to give an unique name space for CMSIS-RTOS functions. 36 Definitions that are prefixed \b os_ are not used in the application code but local to this header file. 37 All definitions and functions that belong to a module are grouped and have a common prefix, i.e. \b osThread. 38 39 Definitions that are marked with <b>CAN BE CHANGED</b> can be adapted towards the needs of the actual CMSIS-RTOS implementation. 40 These definitions can be specific to the underlying RTOS kernel. 41 42 Definitions that are marked with <b>MUST REMAIN UNCHANGED</b> cannot be altered. Otherwise the CMSIS-RTOS implementation is no longer 43 compliant to the standard. Note that some functions are optional and need not to be provided by every CMSIS-RTOS implementation. 44 45 46 <b>Function calls from interrupt service routines</b> 47 48 The following CMSIS-RTOS functions can be called from threads and interrupt service routines (ISR): 49 - \ref osSignalSet 50 - \ref osSemaphoreRelease 51 - \ref osPoolAlloc, \ref osPoolCAlloc, \ref osPoolFree 52 - \ref osMessagePut, \ref osMessageGet 53 - \ref osMailAlloc, \ref osMailCAlloc, \ref osMailGet, \ref osMailPut, \ref osMailFree 54 55 Functions that cannot be called from an ISR are verifying the interrupt status and return in case that they are called 56 from an ISR context the status code \b osErrorISR. In some implementations this condition might be caught using the HARD FAULT vector. 57 58 Some CMSIS-RTOS implementations support CMSIS-RTOS function calls from multiple ISR at the same time. 59 If this is impossible, the CMSIS-RTOS rejects calls by nested ISR functions with the status code \b osErrorISRRecursive. 60 61 62 <b>Define and reference object definitions</b> 63 64 With <b>\#define osObjectsExternal</b> objects are defined as external symbols. This allows to create a consistent header file 65 that is used troughtout a project as shown below: 66 67 <i>Header File</i> 68 \code 69 #include <cmsis_os.h> // CMSIS RTOS header file 70 71 // Thread definition 72 extern void thread_sample (void const *argument); // function prototype 73 osThreadDef (thread_sample, osPriorityBelowNormal, 1, 100); 74 75 // Pool definition 76 osPoolDef(MyPool, 10, long); 77 \endcode 78 79 80 This header file defines all objects when included in a C/C++ source file. When <b>\#define osObjectsExternal</b> is 81 present before the header file, the objects are defined as external symbols. A single consistent header file can therefore be 82 used throughout the whole project. 83 84 <i>Example</i> 85 \code 86 #include "osObjects.h" // Definition of the CMSIS-RTOS objects 87 \endcode 88 89 \code 90 #define osObjectExternal // Objects will be defined as external symbols 91 #include "osObjects.h" // Reference to the CMSIS-RTOS objects 92 \endcode 93 94 */ 95 96 #ifndef _CMSIS_OS_H 97 #define _CMSIS_OS_H 98 99 /// \note MUST REMAIN UNCHANGED: \b osCMSIS identifies the CMSIS-RTOS API version 100 #define osCMSIS 0x00003 ///< API version (main [31:16] .sub [15:0]) 101 102 /// \note CAN BE CHANGED: \b osCMSIS_KERNEL identifies the underlaying RTOS kernel and version number. 103 #define osCMSIS_KERNEL 0x10000 ///< RTOS identification and version (main [31:16] .sub [15:0]) 104 105 /// \note MUST REMAIN UNCHANGED: \b osKernelSystemId shall be consistent in every CMSIS-RTOS. 106 #define osKernelSystemId "KERNEL V1.00" ///< RTOS identification string 107 108 /// \note MUST REMAIN UNCHANGED: \b osFeature_xxx shall be consistent in every CMSIS-RTOS. 109 #define osFeature_MainThread 1 ///< main thread 1=main can be thread, 0=not available 110 #define osFeature_Pool 1 ///< Memory Pools: 1=available, 0=not available 111 #define osFeature_MailQ 1 ///< Mail Queues: 1=available, 0=not available 112 #define osFeature_MessageQ 1 ///< Message Queues: 1=available, 0=not available 113 #define osFeature_Signals 8 ///< maximum number of Signal Flags available per thread 114 #define osFeature_Semaphore 30 ///< maximum count for SemaphoreInit function 115 #define osFeature_Wait 1 ///< osWait function: 1=available, 0=not available 116 117 #include <stdint.h> 118 #include <stddef.h> 119 120 #ifdef __cplusplus 121 extern "C" 122 { 123 #endif 124 125 126 // ==== Enumeration, structures, defines ==== 127 128 /// Priority used for thread control. 129 /// \note MUST REMAIN UNCHANGED: \b osPriority shall be consistent in every CMSIS-RTOS. 130 typedef enum { 131 osPriorityIdle = -3, ///< priority: idle (lowest) 132 osPriorityLow = -2, ///< priority: low 133 osPriorityBelowNormal = -1, ///< priority: below normal 134 osPriorityNormal = 0, ///< priority: normal (default) 135 osPriorityAboveNormal = +1, ///< priority: above normal 136 osPriorityHigh = +2, ///< priority: high 137 osPriorityRealtime = +3, ///< priority: realtime (highest) 138 osPriorityError = 0x84 ///< system cannot determine priority or thread has illegal priority 139 } osPriority; 140 141 /// Timeout value 142 /// \note MUST REMAIN UNCHANGED: \b osWaitForever shall be consistent in every CMSIS-RTOS. 143 #define osWaitForever 0xFFFFFFFF ///< wait forever timeout value 144 145 /// Status code values returned by CMSIS-RTOS functions 146 /// \note MUST REMAIN UNCHANGED: \b osStatus shall be consistent in every CMSIS-RTOS. 147 typedef enum { 148 osOK = 0, ///< function completed; no event occurred. 149 osEventSignal = 0x08, ///< function completed; signal event occurred. 150 osEventMessage = 0x10, ///< function completed; message event occurred. 151 osEventMail = 0x20, ///< function completed; mail event occurred. 152 osEventTimeout = 0x40, ///< function completed; timeout occurred. 153 osErrorParameter = 0x80, ///< parameter error: a mandatory parameter was missing or specified an incorrect object. 154 osErrorResource = 0x81, ///< resource not available: a specified resource was not available. 155 osErrorTimeoutResource = 0xC1, ///< resource not available within given time: a specified resource was not available within the timeout period. 156 osErrorISR = 0x82, ///< not allowed in ISR context: the function cannot be called from interrupt service routines. 157 osErrorISRRecursive = 0x83, ///< function called multiple times from ISR with same object. 158 osErrorPriority = 0x84, ///< system cannot determine priority or thread has illegal priority. 159 osErrorNoMemory = 0x85, ///< system is out of memory: it was impossible to allocate or reserve memory for the operation. 160 osErrorValue = 0x86, ///< value of a parameter is out of range. 161 osErrorOS = 0xFF, ///< unspecified RTOS error: run-time error but no other error message fits. 162 os_status_reserved = 0x7FFFFFFF ///< prevent from enum down-size compiler optimization. 163 } osStatus; 164 165 166 /// Timer type value for the timer definition 167 /// \note MUST REMAIN UNCHANGED: \b os_timer_type shall be consistent in every CMSIS-RTOS. 168 typedef enum { 169 osTimerOnce = 0, ///< one-shot timer 170 osTimerPeriodic = 1 ///< repeating timer 171 } os_timer_type; 172 173 /// Entry point of a thread. 174 /// \note MUST REMAIN UNCHANGED: \b os_pthread shall be consistent in every CMSIS-RTOS. 175 typedef void (*os_pthread) (void const *argument); 176 177 /// Entry point of a timer call back function. 178 /// \note MUST REMAIN UNCHANGED: \b os_ptimer shall be consistent in every CMSIS-RTOS. 179 typedef void (*os_ptimer) (void const *argument); 180 181 // >>> the following data type definitions may shall adapted towards a specific RTOS 182 183 /// Thread ID identifies the thread (pointer to a thread control block). 184 /// \note CAN BE CHANGED: \b os_thread_cb is implementation specific in every CMSIS-RTOS. 185 typedef struct os_thread_cb *osThreadId; 186 187 /// Timer ID identifies the timer (pointer to a timer control block). 188 /// \note CAN BE CHANGED: \b os_timer_cb is implementation specific in every CMSIS-RTOS. 189 typedef struct os_timer_cb *osTimerId; 190 191 /// Mutex ID identifies the mutex (pointer to a mutex control block). 192 /// \note CAN BE CHANGED: \b os_mutex_cb is implementation specific in every CMSIS-RTOS. 193 typedef struct os_mutex_cb *osMutexId; 194 195 /// Semaphore ID identifies the semaphore (pointer to a semaphore control block). 196 /// \note CAN BE CHANGED: \b os_semaphore_cb is implementation specific in every CMSIS-RTOS. 197 typedef struct os_semaphore_cb *osSemaphoreId; 198 199 /// Pool ID identifies the memory pool (pointer to a memory pool control block). 200 /// \note CAN BE CHANGED: \b os_pool_cb is implementation specific in every CMSIS-RTOS. 201 typedef struct os_pool_cb *osPoolId; 202 203 /// Message ID identifies the message queue (pointer to a message queue control block). 204 /// \note CAN BE CHANGED: \b os_messageQ_cb is implementation specific in every CMSIS-RTOS. 205 typedef struct os_messageQ_cb *osMessageQId; 206 207 /// Mail ID identifies the mail queue (pointer to a mail queue control block). 208 /// \note CAN BE CHANGED: \b os_mailQ_cb is implementation specific in every CMSIS-RTOS. 209 typedef struct os_mailQ_cb *osMailQId; 210 211 212 /// Thread Definition structure contains startup information of a thread. 213 /// \note CAN BE CHANGED: \b os_thread_def is implementation specific in every CMSIS-RTOS. 214 typedef const struct os_thread_def { 215 os_pthread pthread; ///< start address of thread function 216 osPriority tpriority; ///< initial thread priority 217 uint32_t instances; ///< maximum number of instances of that thread function 218 uint32_t stacksize; ///< stack size requirements in bytes; 0 is default stack size 219 } osThreadDef_t; 220 221 /// Timer Definition structure contains timer parameters. 222 /// \note CAN BE CHANGED: \b os_timer_def is implementation specific in every CMSIS-RTOS. 223 typedef const struct os_timer_def { 224 os_ptimer ptimer; ///< start address of a timer function 225 } osTimerDef_t; 226 227 /// Mutex Definition structure contains setup information for a mutex. 228 /// \note CAN BE CHANGED: \b os_mutex_def is implementation specific in every CMSIS-RTOS. 229 typedef const struct os_mutex_def { 230 uint32_t dummy; ///< dummy value. 231 } osMutexDef_t; 232 233 /// Semaphore Definition structure contains setup information for a semaphore. 234 /// \note CAN BE CHANGED: \b os_semaphore_def is implementation specific in every CMSIS-RTOS. 235 typedef const struct os_semaphore_def { 236 uint32_t dummy; ///< dummy value. 237 } osSemaphoreDef_t; 238 239 /// Definition structure for memory block allocation 240 /// \note CAN BE CHANGED: \b os_pool_def is implementation specific in every CMSIS-RTOS. 241 typedef const struct os_pool_def { 242 uint32_t pool_sz; ///< number of items (elements) in the pool 243 uint32_t item_sz; ///< size of an item 244 void *pool; ///< pointer to memory for pool 245 } osPoolDef_t; 246 247 /// Definition structure for message queue 248 /// \note CAN BE CHANGED: \b os_messageQ_def is implementation specific in every CMSIS-RTOS. 249 typedef const struct os_messageQ_def { 250 uint32_t queue_sz; ///< number of elements in the queue 251 uint32_t item_sz; ///< size of an item 252 void *pool; ///< memory array for messages 253 } osMessageQDef_t; 254 255 /// Definition structure for mail queue 256 /// \note CAN BE CHANGED: \b os_mailQ_def is implementation specific in every CMSIS-RTOS. 257 typedef const struct os_mailQ_def { 258 uint32_t queue_sz; ///< number of elements in the queue 259 uint32_t item_sz; ///< size of an item 260 void *pool; ///< memory array for mail 261 } osMailQDef_t; 262 263 /// Event structure contains detailed information about an event. 264 /// \note MUST REMAIN UNCHANGED: \b os_event shall be consistent in every CMSIS-RTOS. 265 /// However the struct may be extended at the end. 266 typedef struct { 267 osStatus status; ///< status code: event or error information 268 union { 269 uint32_t v; ///< message as 32-bit value 270 void *p; ///< message or mail as void pointer 271 int32_t signals; ///< signal flags 272 } value; ///< event value 273 union { 274 osMailQId mail_id; ///< mail id obtained by \ref osMailCreate 275 osMessageQId message_id; ///< message id obtained by \ref osMessageCreate 276 } def; ///< event definition 277 } osEvent; 278 279 280 // ==== Kernel Control Functions ==== 281 282 /// Start the RTOS Kernel with executing the specified thread. 283 /// \param[in] thread_def thread definition referenced with \ref osThread. 284 /// \param[in] argument pointer that is passed to the thread function as start argument. 285 /// \return status code that indicates the execution status of the function. 286 /// \note MUST REMAIN UNCHANGED: \b osKernelStart shall be consistent in every CMSIS-RTOS. 287 osStatus osKernelStart (osThreadDef_t *thread_def, void *argument); 288 289 /// Check if the RTOS kernel is already started. 290 /// \note MUST REMAIN UNCHANGED: \b osKernelRunning shall be consistent in every CMSIS-RTOS. 291 /// \return 0 RTOS is not started, 1 RTOS is started. 292 int32_t osKernelRunning(void); 293 294 295 // ==== Thread Management ==== 296 297 /// Create a Thread Definition with function, priority, and stack requirements. 298 /// \param name name of the thread function. 299 /// \param priority initial priority of the thread function. 300 /// \param instances number of possible thread instances. 301 /// \param stacksz stack size (in bytes) requirements for the thread function. 302 /// \note CAN BE CHANGED: The parameters to \b osThreadDef shall be consistent but the 303 /// macro body is implementation specific in every CMSIS-RTOS. 304 #if defined (osObjectsExternal) // object is external 305 #define osThreadDef(name, priority, instances, stacksz) \ 306 extern osThreadDef_t os_thread_def_##name 307 #else // define the object 308 #define osThreadDef(name, priority, instances, stacksz) \ 309 osThreadDef_t os_thread_def_##name = \ 310 { (name), (priority), (instances), (stacksz) } 311 #endif 312 313 /// Access a Thread defintion. 314 /// \param name name of the thread definition object. 315 /// \note CAN BE CHANGED: The parameter to \b osThread shall be consistent but the 316 /// macro body is implementation specific in every CMSIS-RTOS. 317 #define osThread(name) \ 318 &os_thread_def_##name 319 320 321 /// Create a thread and add it to Active Threads and set it to state READY. 322 /// \param[in] thread_def thread definition referenced with \ref osThread. 323 /// \param[in] argument pointer that is passed to the thread function as start argument. 324 /// \return thread ID for reference by other functions or NULL in case of error. 325 /// \note MUST REMAIN UNCHANGED: \b osThreadCreate shall be consistent in every CMSIS-RTOS. 326 osThreadId osThreadCreate (osThreadDef_t *thread_def, void *argument); 327 328 /// Return the thread ID of the current running thread. 329 /// \return thread ID for reference by other functions or NULL in case of error. 330 /// \note MUST REMAIN UNCHANGED: \b osThreadGetId shall be consistent in every CMSIS-RTOS. 331 osThreadId osThreadGetId (void); 332 333 /// Terminate execution of a thread and remove it from Active Threads. 334 /// \param[in] thread_id thread ID obtained by \ref osThreadCreate or \ref osThreadGetId. 335 /// \return status code that indicates the execution status of the function. 336 /// \note MUST REMAIN UNCHANGED: \b osThreadTerminate shall be consistent in every CMSIS-RTOS. 337 osStatus osThreadTerminate (osThreadId thread_id); 338 339 /// Pass control to next thread that is in state \b READY. 340 /// \return status code that indicates the execution status of the function. 341 /// \note MUST REMAIN UNCHANGED: \b osThreadYield shall be consistent in every CMSIS-RTOS. 342 osStatus osThreadYield (void); 343 344 /// Change priority of an active thread. 345 /// \param[in] thread_id thread ID obtained by \ref osThreadCreate or \ref osThreadGetId. 346 /// \param[in] priority new priority value for the thread function. 347 /// \return status code that indicates the execution status of the function. 348 /// \note MUST REMAIN UNCHANGED: \b osThreadSetPriority shall be consistent in every CMSIS-RTOS. 349 osStatus osThreadSetPriority (osThreadId thread_id, osPriority priority); 350 351 /// Get current priority of an active thread. 352 /// \param[in] thread_id thread ID obtained by \ref osThreadCreate or \ref osThreadGetId. 353 /// \return current priority value of the thread function. 354 /// \note MUST REMAIN UNCHANGED: \b osThreadGetPriority shall be consistent in every CMSIS-RTOS. 355 osPriority osThreadGetPriority (osThreadId thread_id); 356 357 358 359 // ==== Generic Wait Functions ==== 360 361 /// Wait for Timeout (Time Delay) 362 /// \param[in] millisec time delay value 363 /// \return status code that indicates the execution status of the function. 364 osStatus osDelay (uint32_t millisec); 365 366 #if (defined (osFeature_Wait) && (osFeature_Wait != 0)) // Generic Wait available 367 368 /// Wait for Signal, Message, Mail, or Timeout 369 /// \param[in] millisec timeout value or 0 in case of no time-out 370 /// \return event that contains signal, message, or mail information or error code. 371 /// \note MUST REMAIN UNCHANGED: \b osWait shall be consistent in every CMSIS-RTOS. 372 osEvent osWait (uint32_t millisec); 373 374 #endif // Generic Wait available 375 376 377 // ==== Timer Management Functions ==== 378 /// Define a Timer object. 379 /// \param name name of the timer object. 380 /// \param function name of the timer call back function. 381 /// \note CAN BE CHANGED: The parameter to \b osTimerDef shall be consistent but the 382 /// macro body is implementation specific in every CMSIS-RTOS. 383 #if defined (osObjectsExternal) // object is external 384 #define osTimerDef(name, function) \ 385 extern osTimerDef_t os_timer_def_##name 386 #else // define the object 387 #define osTimerDef(name, function) \ 388 osTimerDef_t os_timer_def_##name = \ 389 { (function) } 390 #endif 391 392 /// Access a Timer definition. 393 /// \param name name of the timer object. 394 /// \note CAN BE CHANGED: The parameter to \b osTimer shall be consistent but the 395 /// macro body is implementation specific in every CMSIS-RTOS. 396 #define osTimer(name) \ 397 &os_timer_def_##name 398 399 /// Create a timer. 400 /// \param[in] timer_def timer object referenced with \ref osTimer. 401 /// \param[in] type osTimerOnce for one-shot or osTimerPeriodic for periodic behavior. 402 /// \param[in] argument argument to the timer call back function. 403 /// \return timer ID for reference by other functions or NULL in case of error. 404 /// \note MUST REMAIN UNCHANGED: \b osTimerCreate shall be consistent in every CMSIS-RTOS. 405 osTimerId osTimerCreate (osTimerDef_t *timer_def, os_timer_type type, void *argument); 406 407 /// Start or restart a timer. 408 /// \param[in] timer_id timer ID obtained by \ref osTimerCreate. 409 /// \param[in] millisec time delay value of the timer. 410 /// \return status code that indicates the execution status of the function. 411 /// \note MUST REMAIN UNCHANGED: \b osTimerStart shall be consistent in every CMSIS-RTOS. 412 osStatus osTimerStart (osTimerId timer_id, uint32_t millisec); 413 414 /// Stop the timer. 415 /// \param[in] timer_id timer ID obtained by \ref osTimerCreate. 416 /// \return status code that indicates the execution status of the function. 417 /// \note MUST REMAIN UNCHANGED: \b osTimerStop shall be consistent in every CMSIS-RTOS. 418 osStatus osTimerStop (osTimerId timer_id); 419 420 421 // ==== Signal Management ==== 422 423 /// Set the specified Signal Flags of an active thread. 424 /// \param[in] thread_id thread ID obtained by \ref osThreadCreate or \ref osThreadGetId. 425 /// \param[in] signals specifies the signal flags of the thread that should be set. 426 /// \return previous signal flags of the specified thread or 0x80000000 in case of incorrect parameters. 427 /// \note MUST REMAIN UNCHANGED: \b osSignalSet shall be consistent in every CMSIS-RTOS. 428 int32_t osSignalSet (osThreadId thread_id, int32_t signal); 429 430 /// Clear the specified Signal Flags of an active thread. 431 /// \param[in] thread_id thread ID obtained by \ref osThreadCreate or \ref osThreadGetId. 432 /// \param[in] signals specifies the signal flags of the thread that shall be cleared. 433 /// \return previous signal flags of the specified thread or 0x80000000 in case of incorrect parameters. 434 /// \note MUST REMAIN UNCHANGED: \b osSignalClear shall be consistent in every CMSIS-RTOS. 435 int32_t osSignalClear (osThreadId thread_id, int32_t signal); 436 437 /// Get Signal Flags status of an active thread. 438 /// \param[in] thread_id thread ID obtained by \ref osThreadCreate or \ref osThreadGetId. 439 /// \return previous signal flags of the specified thread or 0x80000000 in case of incorrect parameters. 440 /// \note MUST REMAIN UNCHANGED: \b osSignalGet shall be consistent in every CMSIS-RTOS. 441 int32_t osSignalGet (osThreadId thread_id); 442 443 /// Wait for one or more Signal Flags to become signaled for the current \b RUNNING thread. 444 /// \param[in] signals wait until all specified signal flags set or 0 for any single signal flag. 445 /// \param[in] millisec timeout value or 0 in case of no time-out. 446 /// \return event flag information or error code. 447 /// \note MUST REMAIN UNCHANGED: \b osSignalWait shall be consistent in every CMSIS-RTOS. 448 osEvent osSignalWait (int32_t signals, uint32_t millisec); 449 450 451 // ==== Mutex Management ==== 452 453 /// Define a Mutex. 454 /// \param name name of the mutex object. 455 /// \note CAN BE CHANGED: The parameter to \b osMutexDef shall be consistent but the 456 /// macro body is implementation specific in every CMSIS-RTOS. 457 #if defined (osObjectsExternal) // object is external 458 #define osMutexDef(name) \ 459 extern osMutexDef_t os_mutex_def_##name 460 #else // define the object 461 #define osMutexDef(name) \ 462 osMutexDef_t os_mutex_def_##name = { 0 } 463 #endif 464 465 /// Access a Mutex defintion. 466 /// \param name name of the mutex object. 467 /// \note CAN BE CHANGED: The parameter to \b osMutex shall be consistent but the 468 /// macro body is implementation specific in every CMSIS-RTOS. 469 #define osMutex(name) \ 470 &os_mutex_def_##name 471 472 /// Create and Initialize a Mutex object 473 /// \param[in] mutex_def mutex definition referenced with \ref osMutex. 474 /// \return mutex ID for reference by other functions or NULL in case of error. 475 /// \note MUST REMAIN UNCHANGED: \b osMutexCreate shall be consistent in every CMSIS-RTOS. 476 osMutexId osMutexCreate (osMutexDef_t *mutex_def); 477 478 /// Wait until a Mutex becomes available 479 /// \param[in] mutex_id mutex ID obtained by \ref osMutexCreate. 480 /// \param[in] millisec timeout value or 0 in case of no time-out. 481 /// \return status code that indicates the execution status of the function. 482 /// \note MUST REMAIN UNCHANGED: \b osMutexWait shall be consistent in every CMSIS-RTOS. 483 osStatus osMutexWait (osMutexId mutex_id, uint32_t millisec); 484 485 /// Release a Mutex that was obtained by \ref osMutexWait 486 /// \param[in] mutex_id mutex ID obtained by \ref osMutexCreate. 487 /// \return status code that indicates the execution status of the function. 488 /// \note MUST REMAIN UNCHANGED: \b osMutexRelease shall be consistent in every CMSIS-RTOS. 489 osStatus osMutexRelease (osMutexId mutex_id); 490 491 492 // ==== Semaphore Management Functions ==== 493 494 #if (defined (osFeature_Semaphore) && (osFeature_Semaphore != 0)) // Semaphore available 495 496 /// Define a Semaphore object. 497 /// \param name name of the semaphore object. 498 /// \note CAN BE CHANGED: The parameter to \b osSemaphoreDef shall be consistent but the 499 /// macro body is implementation specific in every CMSIS-RTOS. 500 #if defined (osObjectsExternal) // object is external 501 #define osSemaphoreDef(name) \ 502 extern osSemaphoreDef_t os_semaphore_def_##name 503 #else // define the object 504 #define osSemaphoreDef(name) \ 505 osSemaphoreDef_t os_semaphore_def_##name = { 0 } 506 #endif 507 508 /// Access a Semaphore definition. 509 /// \param name name of the semaphore object. 510 /// \note CAN BE CHANGED: The parameter to \b osSemaphore shall be consistent but the 511 /// macro body is implementation specific in every CMSIS-RTOS. 512 #define osSemaphore(name) \ 513 &os_semaphore_def_##name 514 515 /// Create and Initialize a Semaphore object used for managing resources 516 /// \param[in] semaphore_def semaphore definition referenced with \ref osSemaphore. 517 /// \param[in] count number of available resources. 518 /// \return semaphore ID for reference by other functions or NULL in case of error. 519 /// \note MUST REMAIN UNCHANGED: \b osSemaphoreCreate shall be consistent in every CMSIS-RTOS. 520 osSemaphoreId osSemaphoreCreate (osSemaphoreDef_t *semaphore_def, int32_t count); 521 522 /// Wait until a Semaphore token becomes available 523 /// \param[in] semaphore_id semaphore object referenced with \ref osSemaphore. 524 /// \param[in] millisec timeout value or 0 in case of no time-out. 525 /// \return number of available tokens, or -1 in case of incorrect parameters. 526 /// \note MUST REMAIN UNCHANGED: \b osSemaphoreWait shall be consistent in every CMSIS-RTOS. 527 int32_t osSemaphoreWait (osSemaphoreId semaphore_id, uint32_t millisec); 528 529 /// Release a Semaphore token 530 /// \param[in] semaphore_id semaphore object referenced with \ref osSemaphore. 531 /// \return status code that indicates the execution status of the function. 532 /// \note MUST REMAIN UNCHANGED: \b osSemaphoreRelease shall be consistent in every CMSIS-RTOS. 533 osStatus osSemaphoreRelease (osSemaphoreId semaphore_id); 534 535 #endif // Semaphore available 536 537 // ==== Memory Pool Management Functions ==== 538 539 #if (defined (osFeature_Pool) && (osFeature_Pool != 0)) // Memory Pool Management available 540 541 /// \brief Define a Memory Pool. 542 /// \param name name of the memory pool. 543 /// \param no maximum number of objects (elements) in the memory pool. 544 /// \param type data type of a single object (element). 545 /// \note CAN BE CHANGED: The parameter to \b osPoolDef shall be consistent but the 546 /// macro body is implementation specific in every CMSIS-RTOS. 547 #if defined (osObjectsExternal) // object is external 548 #define osPoolDef(name, no, type) \ 549 extern osPoolDef_t os_pool_def_##name 550 #else // define the object 551 #define osPoolDef(name, no, type) \ 552 osPoolDef_t os_pool_def_##name = \ 553 { (no), sizeof(type), NULL } 554 #endif 555 556 /// \brief Access a Memory Pool definition. 557 /// \param name name of the memory pool 558 /// \note CAN BE CHANGED: The parameter to \b osPool shall be consistent but the 559 /// macro body is implementation specific in every CMSIS-RTOS. 560 #define osPool(name) \ 561 &os_pool_def_##name 562 563 /// Create and Initialize a memory pool 564 /// \param[in] pool_def memory pool definition referenced with \ref osPool. 565 /// \return memory pool ID for reference by other functions or NULL in case of error. 566 /// \note MUST REMAIN UNCHANGED: \b osPoolCreate shall be consistent in every CMSIS-RTOS. 567 osPoolId osPoolCreate (osPoolDef_t *pool_def); 568 569 /// Allocate a memory block from a memory pool 570 /// \param[in] pool_id memory pool ID obtain referenced with \ref osPoolCreate. 571 /// \return address of the allocated memory block or NULL in case of no memory available. 572 /// \note MUST REMAIN UNCHANGED: \b osPoolAlloc shall be consistent in every CMSIS-RTOS. 573 void *osPoolAlloc (osPoolId pool_id); 574 575 /// Allocate a memory block from a memory pool and set memory block to zero 576 /// \param[in] pool_id memory pool ID obtain referenced with \ref osPoolCreate. 577 /// \return address of the allocated memory block or NULL in case of no memory available. 578 /// \note MUST REMAIN UNCHANGED: \b osPoolCAlloc shall be consistent in every CMSIS-RTOS. 579 void *osPoolCAlloc (osPoolId pool_id); 580 581 /// Return an allocated memory block back to a specific memory pool 582 /// \param[in] pool_id memory pool ID obtain referenced with \ref osPoolCreate. 583 /// \param[in] block address of the allocated memory block that is returned to the memory pool. 584 /// \return status code that indicates the execution status of the function. 585 /// \note MUST REMAIN UNCHANGED: \b osPoolFree shall be consistent in every CMSIS-RTOS. 586 osStatus osPoolFree (osPoolId pool_id, void *block); 587 588 #endif // Memory Pool Management available 589 590 591 // ==== Message Queue Management Functions ==== 592 593 #if (defined (osFeature_MessageQ) && (osFeature_MessageQ != 0)) // Message Queues available 594 595 /// \brief Create a Message Queue Definition. 596 /// \param name name of the queue. 597 /// \param queue_sz maximum number of messages in the queue. 598 /// \param type data type of a single message element (for debugger). 599 /// \note CAN BE CHANGED: The parameter to \b osMessageQDef shall be consistent but the 600 /// macro body is implementation specific in every CMSIS-RTOS. 601 #if defined (osObjectsExternal) // object is external 602 #define osMessageQDef(name, queue_sz, type) \ 603 extern osMessageQDef_t os_messageQ_def_##name 604 #else // define the object 605 #define osMessageQDef(name, queue_sz, type) \ 606 osMessageQDef_t os_messageQ_def_##name = \ 607 { (queue_sz), sizeof (type) } 608 #endif 609 610 /// \brief Access a Message Queue Definition. 611 /// \param name name of the queue 612 /// \note CAN BE CHANGED: The parameter to \b osMessageQ shall be consistent but the 613 /// macro body is implementation specific in every CMSIS-RTOS. 614 #define osMessageQ(name) \ 615 &os_messageQ_def_##name 616 617 /// Create and Initialize a Message Queue. 618 /// \param[in] queue_def queue definition referenced with \ref osMessageQ. 619 /// \param[in] thread_id thread ID (obtained by \ref osThreadCreate or \ref osThreadGetId) or NULL. 620 /// \return message queue ID for reference by other functions or NULL in case of error. 621 /// \note MUST REMAIN UNCHANGED: \b osMessageCreate shall be consistent in every CMSIS-RTOS. 622 osMessageQId osMessageCreate (osMessageQDef_t *queue_def, osThreadId thread_id); 623 624 /// Put a Message to a Queue. 625 /// \param[in] queue_id message queue ID obtained with \ref osMessageCreate. 626 /// \param[in] info message information. 627 /// \param[in] millisec timeout value or 0 in case of no time-out. 628 /// \return status code that indicates the execution status of the function. 629 /// \note MUST REMAIN UNCHANGED: \b osMessagePut shall be consistent in every CMSIS-RTOS. 630 osStatus osMessagePut (osMessageQId queue_id, uint32_t info, uint32_t millisec); 631 632 /// Get a Message or Wait for a Message from a Queue. 633 /// \param[in] queue_id message queue ID obtained with \ref osMessageCreate. 634 /// \param[in] millisec timeout value or 0 in case of no time-out. 635 /// \return event information that includes status code. 636 /// \note MUST REMAIN UNCHANGED: \b osMessageGet shall be consistent in every CMSIS-RTOS. 637 osEvent osMessageGet (osMessageQId queue_id, uint32_t millisec); 638 639 #endif // Message Queues available 640 641 642 // ==== Mail Queue Management Functions ==== 643 644 #if (defined (osFeature_MailQ) && (osFeature_MailQ != 0)) // Mail Queues available 645 646 /// \brief Create a Mail Queue Definition 647 /// \param name name of the queue 648 /// \param queue_sz maximum number of messages in queue 649 /// \param type data type of a single message element 650 /// \note CAN BE CHANGED: The parameter to \b osMailQDef shall be consistent but the 651 /// macro body is implementation specific in every CMSIS-RTOS. 652 #if defined (osObjectsExternal) // object is external 653 #define osMailQDef(name, queue_sz, type) \ 654 extern osMailQDef_t os_mailQ_def_##name 655 #else // define the object 656 #define osMailQDef(name, queue_sz, type) \ 657 osMailQDef_t os_mailQ_def_##name = \ 658 { (queue_sz), sizeof (type) } 659 #endif 660 661 /// \brief Access a Mail Queue Definition 662 /// \param name name of the queue 663 /// \note CAN BE CHANGED: The parameter to \b osMailQ shall be consistent but the 664 /// macro body is implementation specific in every CMSIS-RTOS. 665 #define osMailQ(name) \ 666 &os_mailQ_def_##name 667 668 /// Create and Initialize mail queue 669 /// \param[in] queue_def reference to the mail queue definition obtain with \ref osMailQ 670 /// \param[in] thread_id thread ID (obtained by \ref osThreadCreate or \ref osThreadGetId) or NULL. 671 /// \return mail queue ID for reference by other functions or NULL in case of error. 672 /// \note MUST REMAIN UNCHANGED: \b osMailCreate shall be consistent in every CMSIS-RTOS. 673 osMailQId osMailCreate (osMailQDef_t *queue_def, osThreadId thread_id); 674 675 /// Allocate a memory block from a mail 676 /// \param[in] queue_id mail queue ID obtained with \ref osMailCreate. 677 /// \param[in] millisec timeout value or 0 in case of no time-out 678 /// \return pointer to memory block that can be filled with mail or NULL in case error. 679 /// \note MUST REMAIN UNCHANGED: \b osMailAlloc shall be consistent in every CMSIS-RTOS. 680 void *osMailAlloc (osMailQId queue_id, uint32_t millisec); 681 682 /// Allocate a memory block from a mail and set memory block to zero 683 /// \param[in] queue_id mail queue ID obtained with \ref osMailCreate. 684 /// \param[in] millisec timeout value or 0 in case of no time-out 685 /// \return pointer to memory block that can shall filled with mail or NULL in case error. 686 /// \note MUST REMAIN UNCHANGED: \b osMailCAlloc shall be consistent in every CMSIS-RTOS. 687 void *osMailCAlloc (osMailQId queue_id, uint32_t millisec); 688 689 /// Put a mail to a queue 690 /// \param[in] queue_id mail queue ID obtained with \ref osMailCreate. 691 /// \param[in] mail memory block previously allocated with \ref osMailAlloc or \ref osMailCAlloc. 692 /// \return status code that indicates the execution status of the function. 693 /// \note MUST REMAIN UNCHANGED: \b osMailPut shall be consistent in every CMSIS-RTOS. 694 osStatus osMailPut (osMailQId queue_id, void *mail); 695 696 /// Get a mail from a queue 697 /// \param[in] queue_id mail queue ID obtained with \ref osMailCreate. 698 /// \param[in] millisec timeout value or 0 in case of no time-out 699 /// \return event that contains mail information or error code. 700 /// \note MUST REMAIN UNCHANGED: \b osMailGet shall be consistent in every CMSIS-RTOS. 701 osEvent osMailGet (osMailQId queue_id, uint32_t millisec); 702 703 /// Free a memory block from a mail 704 /// \param[in] queue_id mail queue ID obtained with \ref osMailCreate. 705 /// \param[in] mail pointer to the memory block that was obtained with \ref osMailGet. 706 /// \return status code that indicates the execution status of the function. 707 /// \note MUST REMAIN UNCHANGED: \b osMailFree shall be consistent in every CMSIS-RTOS. 708 osStatus osMailFree (osMailQId queue_id, void *mail); 709 710 #endif // Mail Queues available 711 712 713 #ifdef __cplusplus 714 } 715 #endif 716 717 #endif // _CMSIS_OS_H 718