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