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