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 * Copyright (C) 2015-2017 Alibaba Group Holding Limited 45 */ 46 47 #ifndef _CMSIS_OS_H 48 #define _CMSIS_OS_H 49 50 #include <stdint.h> 51 #include <stddef.h> 52 53 #include "k_api.h" 54 #ifdef __ARM_ARCH_ISA_ARM 55 #include "cmsis.h" 56 #else 57 #include "cmsis_compiler.h" 58 #endif 59 #define osCMSIS_RHINO 0xA0000U ///< RTOS identification and version (main[31:16].sub[15:0]) 60 61 /// \note MUST REMAIN UNCHANGED: \b osCMSIS identifies the CMSIS-RTOS API version. 62 #define osCMSIS 0x10002 ///< API version (main [31:16] .sub [15:0]) 63 64 /// \note CAN BE CHANGED: \b osCMSIS_KERNEL identifies the underlying RTOS kernel and version number. 65 #define osCMSIS_KERNEL 0x10000 ///< RTOS identification and version (main [31:16] .sub [15:0]) 66 67 /// \note MUST REMAIN UNCHANGED: \b osKernelSystemId shall be consistent in every CMSIS-RTOS. 68 #define osKernelSystemId "KERNEL V1.00" ///< RTOS identification string 69 70 /// \note MUST REMAIN UNCHANGED: \b osFeature_xxx shall be consistent in every CMSIS-RTOS. 71 72 /* Memory Pools, Mail Queues, Signal is not supported yet */ 73 74 #define osFeature_MainThread 1 ///< main thread 1=main can be thread, 0=not available 75 /*not support yet*/ 76 #define osFeature_Pool 1 ///< Memory Pools: 1=available, 0=not available 77 /*not support yet*/ 78 #define osFeature_MailQ 1 ///< Mail Queues: 1=available, 0=not available 79 #define osFeature_MessageQ 1 ///< Message Queues: 1=available, 0=not available 80 /*not support yet*/ 81 #define osFeature_Signals 1 ///< maximum number of Signal Flags available per thread 82 #define osFeature_Semaphore 30 ///< maximum count for \ref osSemaphoreCreate function 83 #define osFeature_Wait 0 ///< osWait function: 1=available, 0=not available 84 #define osFeature_SysTick 1 ///< osKernelSysTick functions: 1=available, 0=not available 85 86 #ifdef OS_API_IN_INTLOCK 87 // CAUTION: 88 // It will be treated as in ISR when calling OS APIs in intlock(), but 89 // the stack might still be using PSP instead of MSP. 90 #define IN_ISR() (__get_IPSR() != 0 || __get_PRIMASK() != 0) 91 #else 92 #define IN_ISR() (__get_IPSR() != 0) 93 #endif 94 95 #ifdef __cplusplus 96 extern "C" 97 { 98 #endif 99 100 101 // ==== Enumeration, structures, defines ==== 102 103 /// Priority used for thread control. 104 /// \note MUST REMAIN UNCHANGED: \b osPriority shall be consistent in every CMSIS-RTOS. 105 typedef enum { 106 osPriorityIdle = -3, ///< priority: idle (lowest) 107 osPriorityLow = -2, ///< priority: low 108 osPriorityBelowNormal = -1, ///< priority: below normal 109 osPriorityNormal = 0, ///< priority: normal (default) 110 osPriorityAboveNormal = +1, ///< priority: above normal 111 osPriorityHigh = +2, ///< priority: high 112 osPriorityRealtime = +3, ///< priority: realtime (highest) 113 osPriorityError = 0x84 ///< system cannot determine priority or thread has illegal priority 114 } osPriority; 115 116 /// Timeout value. 117 /// \note MUST REMAIN UNCHANGED: \b osWaitForever shall be consistent in every CMSIS-RTOS. 118 #define osWaitForever 0xFFFFFFFF ///< wait forever timeout value 119 120 /// Status code values returned by CMSIS-RTOS functions. 121 /// \note MUST REMAIN UNCHANGED: \b osStatus shall be consistent in every CMSIS-RTOS. 122 typedef enum { 123 osOK = 0, ///< function completed; no error or event occurred. 124 osEventSignal = 0x08, ///< function completed; signal event occurred. 125 osEventMessage = 0x10, ///< function completed; message event occurred. 126 osEventMail = 0x20, ///< function completed; mail event occurred. 127 osEventTimeout = 0x40, ///< function completed; timeout occurred. 128 osErrorParameter = 0x80, ///< parameter error: a mandatory parameter was missing or specified an incorrect object. 129 osErrorResource = 0x81, ///< resource not available: a specified resource was not available. 130 osErrorTimeoutResource = 0xC1, ///< resource not available within given time: a specified resource was not available within the timeout period. 131 osErrorISR = 0x82, ///< not allowed in ISR context: the function cannot be called from interrupt service routines. 132 osErrorISRRecursive = 0x83, ///< function called multiple times from ISR with same object. 133 osErrorPriority = 0x84, ///< system cannot determine priority or thread has illegal priority. 134 osErrorNoMemory = 0x85, ///< system is out of memory: it was impossible to allocate or reserve memory for the operation. 135 osErrorValue = 0x86, ///< value of a parameter is out of range. 136 osErrorOS = 0xFF, ///< unspecified RTOS error: run-time error but no other error message fits. 137 os_status_reserved = 0x7FFFFFFF ///< prevent from enum down-size compiler optimization. 138 } osStatus; 139 140 /// Timer type value for the timer definition. 141 /// \note MUST REMAIN UNCHANGED: \b os_timer_type shall be consistent in every CMSIS-RTOS. 142 typedef enum { 143 osTimerOnce = 0, ///< one-shot timer 144 osTimerPeriodic = 1 ///< repeating timer 145 } os_timer_type; 146 147 /// Entry point of a thread. 148 /// \note MUST REMAIN UNCHANGED: \b os_pthread shall be consistent in every CMSIS-RTOS. 149 typedef void (*os_pthread) (void const *argument); 150 151 /// Entry point of a timer call back function. 152 /// \note MUST REMAIN UNCHANGED: \b os_ptimer shall be consistent in every CMSIS-RTOS. 153 typedef void (*os_ptimer) (void const *argument); 154 155 // >>> the following data type definitions may shall adapted towards a specific RTOS 156 157 /// Thread ID identifies the thread (pointer to a thread control block). 158 /// \note CAN BE CHANGED: \b os_thread_cb is implementation specific in every CMSIS-RTOS. 159 //typedef ktask_t *osThreadId; 160 typedef struct 161 { 162 uint32_t tid; 163 uint32_t alloc; // indicate if alloc pTask outside 164 ktask_t * pTask; 165 kevent_t * pEvent; 166 task_entry_t func; 167 void *pArg; 168 }osThreadId_t, *osThreadId; 169 170 /// Timer ID identifies the timer (pointer to a timer control block). 171 /// \note CAN BE CHANGED: \b os_timer_cb is implementation specific in every CMSIS-RTOS. 172 //typedef ktimer_t *osTimerId; 173 typedef struct 174 { 175 ktimer_t * pTimer; 176 os_ptimer cb; 177 void * arg; 178 }osTimerId_t, *osTimerId; 179 180 /// Mutex ID identifies the mutex (pointer to a mutex control block). 181 /// \note CAN BE CHANGED: \b os_mutex_cb is implementation specific in every CMSIS-RTOS. 182 typedef kmutex_t *osMutexId; 183 184 /// Semaphore ID identifies the semaphore (pointer to a semaphore control block). 185 /// \note CAN BE CHANGED: \b os_semaphore_cb is implementation specific in every CMSIS-RTOS. 186 typedef ksem_t *osSemaphoreId; 187 188 /// Pool ID identifies the memory pool (pointer to a memory pool control block). 189 /// \note CAN BE CHANGED: \b os_pool_cb is implementation specific in every CMSIS-RTOS. 190 typedef void *osPoolId; 191 192 /// Message ID identifies the message queue (pointer to a message queue control block). 193 /// \note CAN BE CHANGED: \b os_messageQ_cb is implementation specific in every CMSIS-RTOS. 194 typedef kbuf_queue_t *osMessageQId; 195 196 /// Mail ID identifies the mail queue (pointer to a mail queue control block). 197 /// \note CAN BE CHANGED: \b os_mailQ_cb is implementation specific in every CMSIS-RTOS. 198 //typedef kqueue_t *osMailQId; 199 typedef void *osMailQId; 200 201 /// Thread Definition structure contains startup information of a thread. 202 /// \note CAN BE CHANGED: \b os_thread_def is implementation specific in every CMSIS-RTOS. 203 typedef struct os_thread_def { 204 char *name; ///< Thread name 205 os_pthread pthread; ///< start address of thread function 206 osPriority tpriority; ///< initial thread priority 207 uint32_t instances; ///< maximum number of instances of that thread function 208 uint32_t stacksize; ///< stack size requirements in bytes; 0 is default stack size 209 tick_t ticks; 210 ktask_t *ptcb; 211 cpu_stack_t *pstackspace; 212 } osThreadDef_t; 213 214 /// Timer Definition structure contains timer parameters. 215 /// \note CAN BE CHANGED: \b os_timer_def is implementation specific in every CMSIS-RTOS. 216 typedef struct os_timer_def { 217 char *name; 218 os_ptimer ptimer; ///< start address of a timer function 219 ktimer_t *timer; 220 } osTimerDef_t; 221 222 /// Mutex Definition structure contains setup information for a mutex. 223 /// \note CAN BE CHANGED: \b os_mutex_def is implementation specific in every CMSIS-RTOS. 224 typedef struct os_mutex_def { 225 char *name; 226 uint32_t dummy; ///< dummy value. 227 kmutex_t *mutex; 228 } osMutexDef_t; 229 230 /// Semaphore Definition structure contains setup information for a semaphore. 231 /// \note CAN BE CHANGED: \b os_semaphore_def is implementation specific in every CMSIS-RTOS. 232 typedef struct os_semaphore_def { 233 char *name; 234 uint32_t dummy; ///< dummy value. 235 ksem_t *sem; 236 } osSemaphoreDef_t; 237 238 /// Definition structure for memory block allocation. 239 /// \note CAN BE CHANGED: \b os_pool_def is implementation specific in every CMSIS-RTOS. 240 typedef struct os_pool_def { 241 uint32_t pool_sz; ///< number of items (elements) in the pool 242 uint32_t item_sz; ///< size of an item 243 void *pool; ///< pointer to memory for pool 244 } osPoolDef_t; 245 246 /// Definition structure for message queue. 247 /// \note CAN BE CHANGED: \b os_messageQ_def is implementation specific in every CMSIS-RTOS. 248 typedef struct os_messageQ_def { 249 char *name; 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 kbuf_queue_t *queue; 254 } osMessageQDef_t; 255 256 /// Definition structure for mail queue. 257 /// \note CAN BE CHANGED: \b os_mailQ_def is implementation specific in every CMSIS-RTOS. 258 #if 0 259 typedef struct os_mailQ_def { 260 uint32_t queue_sz; ///< number of elements in the queue 261 uint32_t item_sz; ///< size of an item 262 void *pool; ///< memory array for mail 263 } osMailQDef_t; 264 #else 265 typedef struct os_mailQ_def { 266 osPoolDef_t mq_pool; ///< memory pool attributes 267 void *mail; ///< pointer to mail 268 } osMailQDef_t; 269 #endif 270 271 /// Event structure contains detailed information about an event. 272 /// \note MUST REMAIN UNCHANGED: \b os_event shall be consistent in every CMSIS-RTOS. 273 /// However the struct may be extended at the end. 274 typedef struct { 275 osStatus status; ///< status code: event or error information 276 union { 277 uint32_t v; ///< message as 32-bit value 278 void *p; ///< message or mail as void pointer 279 int32_t signals; ///< signal flags 280 } value; ///< event value 281 union { 282 osMailQId mail_id; ///< mail id obtained by \ref osMailCreate 283 osMessageQId message_id; ///< message id obtained by \ref osMessageCreate 284 } def; ///< event definition 285 } osEvent; 286 287 288 // ==== Kernel Control Functions ==== 289 290 /// Initialize the RTOS Kernel for creating objects. 291 /// \return status code that indicates the execution status of the function. 292 /// \note MUST REMAIN UNCHANGED: \b osKernelInitialize shall be consistent in every CMSIS-RTOS. 293 osStatus osKernelInitialize (void); 294 295 /// Start the RTOS Kernel. 296 /// \return status code that indicates the execution status of the function. 297 /// \note MUST REMAIN UNCHANGED: \b osKernelStart shall be consistent in every CMSIS-RTOS. 298 osStatus osKernelStart (void); 299 300 /// Check if the RTOS kernel is already started. 301 /// \note MUST REMAIN UNCHANGED: \b osKernelRunning shall be consistent in every CMSIS-RTOS. 302 /// \return 0 RTOS is not started, 1 RTOS is started. 303 int32_t osKernelRunning(void); 304 305 #if (defined (osFeature_SysTick) && (osFeature_SysTick != 0)) // System Timer available 306 307 /// Get the RTOS kernel system timer counter 308 /// \note MUST REMAIN UNCHANGED: \b osKernelSysTick shall be consistent in every CMSIS-RTOS. 309 /// \return RTOS kernel system timer as 32-bit value 310 uint32_t osKernelSysTick (void); 311 312 /// The RTOS kernel system timer frequency in Hz 313 /// \note Reflects the system timer setting and is typically defined in a configuration file. 314 #define osKernelSysTickFrequency 100000000 315 316 /// Convert a microseconds value to a RTOS kernel system timer value. 317 /// \param microsec time value in microseconds. 318 /// \return time value normalized to the \ref osKernelSysTickFrequency 319 #define osKernelSysTickMicroSec(microsec) (((uint64_t)microsec * (osKernelSysTickFrequency)) / 1000000) 320 321 #endif // System Timer available 322 323 // ==== Thread Management ==== 324 325 /// Create a Thread Definition with function, priority, and stack requirements. 326 /// \param name name of the thread function. 327 /// \param priority initial priority of the thread function. 328 /// \param instances number of possible thread instances. 329 /// \param stacksz stack size (in bytes) requirements for the thread function. 330 /// \note CAN BE CHANGED: The parameters to \b osThreadDef shall be consistent but the 331 /// macro body is implementation specific in every CMSIS-RTOS. 332 #if defined (osObjectsExternal) // object is external 333 #define osThreadDef(name, priority, instances, stacksz) \ 334 extern const osThreadDef_t os_thread_def_##name 335 #else // define the object 336 #define osThreadDef(name, priority, instances, stacksz, task_name) \ 337 cpu_stack_t os_thread_stack_##name[stacksz/sizeof(cpu_stack_t)];\ 338 const osThreadDef_t os_thread_def_##name = \ 339 { (char *)(task_name), (os_pthread)(name), (osPriority)(priority), (uint32_t)(instances), (stacksz), \ 340 (0), NULL, (os_thread_stack_##name)} 341 #endif 342 343 /// Access a Thread definition. 344 /// \param name name of the thread definition object. 345 /// \note CAN BE CHANGED: The parameter to \b osThread shall be consistent but the 346 /// macro body is implementation specific in every CMSIS-RTOS. 347 #define osThread(name) \ 348 &os_thread_def_##name 349 350 osStatus osThreadShow (osThreadId thread_id); 351 352 /// Create a thread and add it to Active Threads and set it to state READY. 353 /// \param[in] thread_def thread definition referenced with \ref osThread. 354 /// \param[in] argument pointer that is passed to the thread function as start argument. 355 /// \return thread ID for reference by other functions or NULL in case of error. 356 /// \note MUST REMAIN UNCHANGED: \b osThreadCreate shall be consistent in every CMSIS-RTOS. 357 osThreadId osThreadCreate (const osThreadDef_t *thread_def, void *argument); 358 359 /// Return the thread ID of the current running thread. 360 /// \return thread ID for reference by other functions or NULL in case of error. 361 /// \note MUST REMAIN UNCHANGED: \b osThreadGetId shall be consistent in every CMSIS-RTOS. 362 osThreadId osThreadGetId (void); 363 364 /// Terminate execution of a thread and remove it from Active Threads. 365 /// \param[in] thread_id thread ID obtained by \ref osThreadCreate or \ref osThreadGetId. 366 /// \return status code that indicates the execution status of the function. 367 /// \note MUST REMAIN UNCHANGED: \b osThreadTerminate shall be consistent in every CMSIS-RTOS. 368 osStatus osThreadTerminate (osThreadId thread_id); 369 370 /// Pass control to next thread that is in state \b READY. 371 /// \return status code that indicates the execution status of the function. 372 /// \note MUST REMAIN UNCHANGED: \b osThreadYield shall be consistent in every CMSIS-RTOS. 373 osStatus osThreadYield (void); 374 375 /// Change priority of an active thread. 376 /// \param[in] thread_id thread ID obtained by \ref osThreadCreate or \ref osThreadGetId. 377 /// \param[in] priority new priority value for the thread function. 378 /// \return status code that indicates the execution status of the function. 379 /// \note MUST REMAIN UNCHANGED: \b osThreadSetPriority shall be consistent in every CMSIS-RTOS. 380 osStatus osThreadSetPriority (osThreadId thread_id, osPriority priority); 381 382 /// Get current priority of an active thread. 383 /// \param[in] thread_id thread ID obtained by \ref osThreadCreate or \ref osThreadGetId. 384 /// \return current priority value of the thread function. 385 /// \note MUST REMAIN UNCHANGED: \b osThreadGetPriority shall be consistent in every CMSIS-RTOS. 386 osPriority osThreadGetPriority (osThreadId thread_id); 387 388 // ==== Generic Wait Functions ==== 389 390 /// Wait for Timeout (Time Delay). 391 /// \param[in] millisec \ref CMSIS_RTOS_TimeOutValue "time delay" value 392 /// \return status code that indicates the execution status of the function. 393 osStatus osDelay (uint32_t millisec); 394 395 #if (defined (osFeature_Wait) && (osFeature_Wait != 0)) // Generic Wait available 396 397 /// Wait for Signal, Message, Mail, or Timeout. 398 /// \param[in] millisec \ref CMSIS_RTOS_TimeOutValue or 0 in case of no time-out 399 /// \return event that contains signal, message, or mail information or error code. 400 /// \note MUST REMAIN UNCHANGED: \b osWait shall be consistent in every CMSIS-RTOS. 401 osEvent osWait (uint32_t millisec); 402 403 #endif // Generic Wait available 404 405 406 // ==== Timer Management Functions ==== 407 /// Define a Timer object. 408 /// \param name name of the timer object. 409 /// \param function name of the timer call back function. 410 /// \note CAN BE CHANGED: The parameter to \b osTimerDef shall be consistent but the 411 /// macro body is implementation specific in every CMSIS-RTOS. 412 #if defined (osObjectsExternal) // object is external 413 #define osTimerDef(name, function) \ 414 extern const osTimerDef_t os_timer_def_##name 415 #else // define the object 416 #define osTimerDef(name, function) \ 417 const osTimerDef_t os_timer_def_##name = \ 418 { (0), (os_ptimer)(function), (0)} 419 #endif 420 421 /// Access a Timer definition. 422 /// \param name name of the timer object. 423 /// \note CAN BE CHANGED: The parameter to \b osTimer shall be consistent but the 424 /// macro body is implementation specific in every CMSIS-RTOS. 425 #define osTimer(name) \ 426 &os_timer_def_##name 427 428 /// Create a timer. 429 /// \param[in] timer_def timer object referenced with \ref osTimer. 430 /// \param[in] type osTimerOnce for one-shot or osTimerPeriodic for periodic behavior. 431 /// \param[in] argument argument to the timer call back function. 432 /// \return timer ID for reference by other functions or NULL in case of error. 433 /// \note MUST REMAIN UNCHANGED: \b osTimerCreate shall be consistent in every CMSIS-RTOS. 434 osTimerId osTimerCreate (const osTimerDef_t *timer_def, os_timer_type type, void *argument); 435 436 /// Start or restart a timer. 437 /// \param[in] timer_id timer ID obtained by \ref osTimerCreate. 438 /// \param[in] millisec \ref CMSIS_RTOS_TimeOutValue "time delay" value of the timer. 439 /// \return status code that indicates the execution status of the function. 440 /// \note MUST REMAIN UNCHANGED: \b osTimerStart shall be consistent in every CMSIS-RTOS. 441 osStatus osTimerStart (osTimerId timer_id, uint32_t millisec); 442 443 /// Stop the timer. 444 /// \param[in] timer_id timer ID obtained by \ref osTimerCreate. 445 /// \return status code that indicates the execution status of the function. 446 /// \note MUST REMAIN UNCHANGED: \b osTimerStop shall be consistent in every CMSIS-RTOS. 447 osStatus osTimerStop (osTimerId timer_id); 448 449 /// Delete a timer that was created by \ref osTimerCreate. 450 /// \param[in] timer_id timer ID obtained by \ref osTimerCreate. 451 /// \return status code that indicates the execution status of the function. 452 /// \note MUST REMAIN UNCHANGED: \b osTimerDelete shall be consistent in every CMSIS-RTOS. 453 osStatus osTimerDelete (osTimerId timer_id); 454 455 456 // ==== Signal Management ==== not support yet 457 458 /// Set the specified Signal Flags of an active thread. 459 /// \param[in] thread_id thread ID obtained by \ref osThreadCreate or \ref osThreadGetId. 460 /// \param[in] signals specifies the signal flags of the thread that should be set. 461 /// \return previous signal flags of the specified thread or 0x80000000 in case of incorrect parameters. 462 /// \note MUST REMAIN UNCHANGED: \b osSignalSet shall be consistent in every CMSIS-RTOS. 463 int32_t osSignalSet (osThreadId thread_id, int32_t signals); 464 465 /// Clear the specified Signal Flags of an active thread. 466 /// \param[in] thread_id thread ID obtained by \ref osThreadCreate or \ref osThreadGetId. 467 /// \param[in] signals specifies the signal flags of the thread that shall be cleared. 468 /// \return previous signal flags of the specified thread or 0x80000000 in case of incorrect parameters or call from ISR. 469 /// \note MUST REMAIN UNCHANGED: \b osSignalClear shall be consistent in every CMSIS-RTOS. 470 int32_t osSignalClear (osThreadId thread_id, int32_t signals); 471 472 /// Wait for one or more Signal Flags to become signaled for the current \b RUNNING thread. 473 /// \param[in] signals wait until all specified signal flags set or 0 for any single signal flag. 474 /// \param[in] millisec \ref CMSIS_RTOS_TimeOutValue or 0 in case of no time-out. 475 /// \return event flag information or error code. 476 /// \note MUST REMAIN UNCHANGED: \b osSignalWait shall be consistent in every CMSIS-RTOS. 477 osEvent osSignalWait (int32_t signals, uint32_t millisec); 478 479 480 // ==== Mutex Management ==== 481 482 /// Define a Mutex. 483 /// \param name name of the mutex object. 484 /// \note CAN BE CHANGED: The parameter to \b osMutexDef shall be consistent but the 485 /// macro body is implementation specific in every CMSIS-RTOS. 486 #if defined (osObjectsExternal) // object is external 487 #define osMutexDef(name) \ 488 extern const osMutexDef_t os_mutex_def_##name 489 #else // define the object 490 #define osMutexDef(name) \ 491 const osMutexDef_t os_mutex_def_##name = {(0), (0), (0)} 492 #endif 493 494 /// Access a Mutex definition. 495 /// \param name name of the mutex object. 496 /// \note CAN BE CHANGED: The parameter to \b osMutex shall be consistent but the 497 /// macro body is implementation specific in every CMSIS-RTOS. 498 #define osMutex(name) \ 499 &os_mutex_def_##name 500 501 osThreadId osMutexGetOwner (osMutexId mutex_id); 502 503 /// Create and Initialize a Mutex object. 504 /// \param[in] mutex_def mutex definition referenced with \ref osMutex. 505 /// \return mutex ID for reference by other functions or NULL in case of error. 506 /// \note MUST REMAIN UNCHANGED: \b osMutexCreate shall be consistent in every CMSIS-RTOS. 507 osMutexId osMutexCreate (const osMutexDef_t *mutex_def); 508 509 /// Wait until a Mutex becomes available. 510 /// \param[in] mutex_id mutex ID obtained by \ref osMutexCreate. 511 /// \param[in] millisec \ref CMSIS_RTOS_TimeOutValue or 0 in case of no time-out. 512 /// \return status code that indicates the execution status of the function. 513 /// \note MUST REMAIN UNCHANGED: \b osMutexWait shall be consistent in every CMSIS-RTOS. 514 osStatus osMutexWait (osMutexId mutex_id, uint32_t millisec); 515 516 /// Release a Mutex that was obtained by \ref osMutexWait. 517 /// \param[in] mutex_id mutex ID obtained by \ref osMutexCreate. 518 /// \return status code that indicates the execution status of the function. 519 /// \note MUST REMAIN UNCHANGED: \b osMutexRelease shall be consistent in every CMSIS-RTOS. 520 osStatus osMutexRelease (osMutexId mutex_id); 521 522 /// Delete a Mutex that was created by \ref osMutexCreate. 523 /// \param[in] mutex_id mutex ID obtained by \ref osMutexCreate. 524 /// \return status code that indicates the execution status of the function. 525 /// \note MUST REMAIN UNCHANGED: \b osMutexDelete shall be consistent in every CMSIS-RTOS. 526 osStatus osMutexDelete (osMutexId mutex_id); 527 528 529 // ==== Semaphore Management Functions ==== 530 531 #if (defined (osFeature_Semaphore) && (osFeature_Semaphore != 0)) // Semaphore available 532 533 /// Define a Semaphore object. 534 /// \param name name of the semaphore object. 535 /// \note CAN BE CHANGED: The parameter to \b osSemaphoreDef shall be consistent but the 536 /// macro body is implementation specific in every CMSIS-RTOS. 537 #if defined (osObjectsExternal) // object is external 538 #define osSemaphoreDef(name) \ 539 extern const osSemaphoreDef_t os_semaphore_def_##name 540 #else // define the object 541 #define osSemaphoreDef(name) \ 542 const osSemaphoreDef_t os_semaphore_def_##name = {(0), (0), (0)} 543 #endif 544 545 /// Access a Semaphore definition. 546 /// \param name name of the semaphore object. 547 /// \note CAN BE CHANGED: The parameter to \b osSemaphore shall be consistent but the 548 /// macro body is implementation specific in every CMSIS-RTOS. 549 #define osSemaphore(name) \ 550 &os_semaphore_def_##name 551 552 /// Create and Initialize a Semaphore object used for managing resources. 553 /// \param[in] semaphore_def semaphore definition referenced with \ref osSemaphore. 554 /// \param[in] count number of available resources. 555 /// \return semaphore ID for reference by other functions or NULL in case of error. 556 /// \note MUST REMAIN UNCHANGED: \b osSemaphoreCreate shall be consistent in every CMSIS-RTOS. 557 osSemaphoreId osSemaphoreCreate (const osSemaphoreDef_t *semaphore_def, int32_t count); 558 559 /// Wait until a Semaphore token becomes available. 560 /// \param[in] semaphore_id semaphore object referenced with \ref osSemaphoreCreate. 561 /// \param[in] millisec \ref CMSIS_RTOS_TimeOutValue or 0 in case of no time-out. 562 /// \return number of available tokens, or -1 in case of incorrect parameters. 563 /// \note MUST REMAIN UNCHANGED: \b osSemaphoreWait shall be consistent in every CMSIS-RTOS. 564 int32_t osSemaphoreWait (osSemaphoreId semaphore_id, uint32_t millisec); 565 566 /// Release a Semaphore token. 567 /// \param[in] semaphore_id semaphore object referenced with \ref osSemaphoreCreate. 568 /// \return status code that indicates the execution status of the function. 569 /// \note MUST REMAIN UNCHANGED: \b osSemaphoreRelease shall be consistent in every CMSIS-RTOS. 570 osStatus osSemaphoreRelease (osSemaphoreId semaphore_id); 571 572 /// Delete a Semaphore that was created by \ref osSemaphoreCreate. 573 /// \param[in] semaphore_id semaphore object referenced with \ref osSemaphoreCreate. 574 /// \return status code that indicates the execution status of the function. 575 /// \note MUST REMAIN UNCHANGED: \b osSemaphoreDelete shall be consistent in every CMSIS-RTOS. 576 osStatus osSemaphoreDelete (osSemaphoreId semaphore_id); 577 578 #endif // Semaphore available 579 580 581 // ==== Memory Pool Management Functions ==== not support yet 582 583 #if (defined (osFeature_Pool) && (osFeature_Pool != 0)) // Memory Pool Management available 584 585 /// \brief Define a Memory Pool. 586 /// \param name name of the memory pool. 587 /// \param no maximum number of blocks (objects) in the memory pool. 588 /// \param type data type of a single block (object). 589 /// \note CAN BE CHANGED: The parameter to \b osPoolDef shall be consistent but the 590 /// macro body is implementation specific in every CMSIS-RTOS. 591 #if defined (osObjectsExternal) // object is external 592 #define osPoolDef(name, no, type) \ 593 extern const osPoolDef_t os_pool_def_##name 594 #else // define the object 595 #if 0 596 #define osPoolDef(name, no, type) 597 const osPoolDef_t os_pool_def_##name = 598 { (no), sizeof(type), NULL } 599 #else 600 #define osPoolDef(name, no, type) \ 601 uint32_t os_pool_m_##name[3+((sizeof(type)+3)/4)*(no)]; \ 602 const osPoolDef_t os_pool_def_##name = \ 603 { (no), sizeof(type), (os_pool_m_##name) } 604 #endif 605 #endif 606 607 /// \brief Access a Memory Pool definition. 608 /// \param name name of the memory pool 609 /// \note CAN BE CHANGED: The parameter to \b osPool shall be consistent but the 610 /// macro body is implementation specific in every CMSIS-RTOS. 611 #define osPool(name) \ 612 &os_pool_def_##name 613 614 /// Create and Initialize a memory pool. 615 /// \param[in] pool_def memory pool definition referenced with \ref osPool. 616 /// \return memory pool ID for reference by other functions or NULL in case of error. 617 /// \note MUST REMAIN UNCHANGED: \b osPoolCreate shall be consistent in every CMSIS-RTOS. 618 osPoolId osPoolCreate (const osPoolDef_t *pool_def); 619 620 /// Allocate a memory block from a memory pool. 621 /// \param[in] pool_id memory pool ID obtain referenced with \ref osPoolCreate. 622 /// \return address of the allocated memory block or NULL in case of no memory available. 623 /// \note MUST REMAIN UNCHANGED: \b osPoolAlloc shall be consistent in every CMSIS-RTOS. 624 void *osPoolAlloc (osPoolId pool_id); 625 626 /// Allocate a memory block from a memory pool and set memory block to zero. 627 /// \param[in] pool_id memory pool ID obtain referenced with \ref osPoolCreate. 628 /// \return address of the allocated memory block or NULL in case of no memory available. 629 /// \note MUST REMAIN UNCHANGED: \b osPoolCAlloc shall be consistent in every CMSIS-RTOS. 630 void *osPoolCAlloc (osPoolId pool_id); 631 632 /// Return an allocated memory block back to a specific memory pool. 633 /// \param[in] pool_id memory pool ID obtain referenced with \ref osPoolCreate. 634 /// \param[in] block address of the allocated memory block that is returned to the memory pool. 635 /// \return status code that indicates the execution status of the function. 636 /// \note MUST REMAIN UNCHANGED: \b osPoolFree shall be consistent in every CMSIS-RTOS. 637 osStatus osPoolFree (osPoolId pool_id, void *block); 638 639 #endif // Memory Pool Management available 640 641 642 // ==== Message Queue Management Functions ==== 643 644 #if (defined (osFeature_MessageQ) && (osFeature_MessageQ != 0)) // Message Queues available 645 646 /// \brief Create a Message Queue Definition. 647 /// \param name name of the queue. 648 /// \param queue_sz maximum number of messages in the queue. 649 /// \param type data type of a single message element (for debugger). 650 /// \note CAN BE CHANGED: The parameter to \b osMessageQDef shall be consistent but the 651 /// macro body is implementation specific in every CMSIS-RTOS. 652 #if defined (osObjectsExternal) // object is external 653 #define osMessageQDef(name, queue_sz, type) \ 654 extern const osMessageQDef_t os_messageQ_def_##name 655 #else // define the object 656 #define osMessageQDef(name, queue_sz, type) \ 657 const osMessageQDef_t os_messageQ_def_##name = \ 658 {(0), (queue_sz), sizeof(type), (0), (0)} 659 #endif 660 661 /// \brief Access a Message Queue Definition. 662 /// \param name name of the queue 663 /// \note CAN BE CHANGED: The parameter to \b osMessageQ shall be consistent but the 664 /// macro body is implementation specific in every CMSIS-RTOS. 665 #define osMessageQ(name) \ 666 &os_messageQ_def_##name 667 668 /// Create and Initialize a Message Queue. 669 /// \param[in] queue_def queue definition referenced with \ref osMessageQ. 670 /// \param[in] thread_id thread ID (obtained by \ref osThreadCreate or \ref osThreadGetId) or NULL. 671 /// \return message queue ID for reference by other functions or NULL in case of error. 672 /// \note MUST REMAIN UNCHANGED: \b osMessageCreate shall be consistent in every CMSIS-RTOS. 673 osMessageQId osMessageCreate (const osMessageQDef_t *queue_def, osThreadId thread_id); 674 675 /// Put a Message to a Queue. 676 /// \param[in] queue_id message queue ID obtained with \ref osMessageCreate. 677 /// \param[in] info message information. 678 /// \param[in] millisec \ref CMSIS_RTOS_TimeOutValue or 0 in case of no time-out. 679 /// \return status code that indicates the execution status of the function. 680 /// \note MUST REMAIN UNCHANGED: \b osMessagePut shall be consistent in every CMSIS-RTOS. 681 osStatus osMessagePut (osMessageQId queue_id, uint32_t info, uint32_t millisec); 682 683 /// Get free Message Size of a Queue. 684 /// \param[in] queue_id message queue ID obtained with \ref osMessageCreate. 685 /// \return free Message Size of a Queue. 686 uint32_t osMessageGetSpace (osMessageQId queue_id); 687 688 /// Get a Message or Wait for a Message from a Queue. 689 /// \param[in] queue_id message queue ID obtained with \ref osMessageCreate. 690 /// \param[in] millisec \ref CMSIS_RTOS_TimeOutValue or 0 in case of no time-out. 691 /// \return event information that includes status code. 692 /// \note MUST REMAIN UNCHANGED: \b osMessageGet shall be consistent in every CMSIS-RTOS. 693 osEvent osMessageGet (osMessageQId queue_id, uint32_t millisec); 694 695 osStatus osMessageQueueDelete (osMessageQId queue_id); 696 #endif // Message Queues available 697 698 699 // ==== Mail Queue Management Functions ==== not support yet 700 701 #if (defined (osFeature_MailQ) && (osFeature_MailQ != 0)) // Mail Queues available 702 703 /// \brief Create a Mail Queue Definition. 704 /// \param name name of the queue 705 /// \param queue_sz maximum number of messages in queue 706 /// \param type data type of a single message element 707 /// \note CAN BE CHANGED: The parameter to \b osMailQDef shall be consistent but the 708 /// macro body is implementation specific in every CMSIS-RTOS. 709 #if defined (osObjectsExternal) // object is external 710 #define osMailQDef(name, queue_sz, type) \ 711 extern const osMailQDef_t os_mailQ_def_##name 712 #else // define the object 713 #if 0 714 #define osMailQDef(name, queue_sz, type) 715 const osMailQDef_t os_mailQ_def_##name = 716 { (queue_sz), sizeof (type) } 717 #else 718 #define osMailQDef(name, queue_sz, type) \ 719 static uint32_t os_mailQ_m_##name[3+((sizeof(type)+3)/4)*(queue_sz)]; \ 720 osMailQDef_t os_mailQ_def_##name = \ 721 { {(queue_sz), sizeof(type), (os_mailQ_m_##name)}, NULL} 722 #endif 723 #endif 724 725 /// \brief Access a Mail Queue Definition. 726 /// \param name name of the queue 727 /// \note CAN BE CHANGED: The parameter to \b osMailQ shall be consistent but the 728 /// macro body is implementation specific in every CMSIS-RTOS. 729 #define osMailQ(name) \ 730 &os_mailQ_def_##name 731 732 /// Create and Initialize mail queue. 733 /// \param[in] queue_def reference to the mail queue definition obtain with \ref osMailQ 734 /// \param[in] thread_id thread ID (obtained by \ref osThreadCreate or \ref osThreadGetId) or NULL. 735 /// \return mail queue ID for reference by other functions or NULL in case of error. 736 /// \note MUST REMAIN UNCHANGED: \b osMailCreate shall be consistent in every CMSIS-RTOS. 737 osMailQId osMailCreate (osMailQDef_t *queue_def, osThreadId thread_id); 738 739 /// Allocate a memory block from a mail. 740 /// \param[in] queue_id mail queue ID obtained with \ref osMailCreate. 741 /// \param[in] millisec \ref CMSIS_RTOS_TimeOutValue or 0 in case of no time-out 742 /// \return pointer to memory block that can be filled with mail or NULL in case of error. 743 /// \note MUST REMAIN UNCHANGED: \b osMailAlloc shall be consistent in every CMSIS-RTOS. 744 void *osMailAlloc (osMailQId queue_id, uint32_t millisec); 745 746 /// Allocate a memory block from a mail and set memory block to zero. 747 /// \param[in] queue_id mail queue ID obtained with \ref osMailCreate. 748 /// \param[in] millisec \ref CMSIS_RTOS_TimeOutValue or 0 in case of no time-out 749 /// \return pointer to memory block that can be filled with mail or NULL in case of error. 750 /// \note MUST REMAIN UNCHANGED: \b osMailCAlloc shall be consistent in every CMSIS-RTOS. 751 void *osMailCAlloc (osMailQId queue_id, uint32_t millisec); 752 753 /// Put a mail to a queue. 754 /// \param[in] queue_id mail queue ID obtained with \ref osMailCreate. 755 /// \param[in] mail memory block previously allocated with \ref osMailAlloc or \ref osMailCAlloc. 756 /// \return status code that indicates the execution status of the function. 757 /// \note MUST REMAIN UNCHANGED: \b osMailPut shall be consistent in every CMSIS-RTOS. 758 osStatus osMailPut (osMailQId queue_id, void *mail); 759 760 /// Get a mail from a queue. 761 /// \param[in] queue_id mail queue ID obtained with \ref osMailCreate. 762 /// \param[in] millisec \ref CMSIS_RTOS_TimeOutValue or 0 in case of no time-out 763 /// \return event that contains mail information or error code. 764 /// \note MUST REMAIN UNCHANGED: \b osMailGet shall be consistent in every CMSIS-RTOS. 765 osEvent osMailGet (osMailQId queue_id, uint32_t millisec); 766 767 /// Free a memory block from a mail. 768 /// \param[in] queue_id mail queue ID obtained with \ref osMailCreate. 769 /// \param[in] mail pointer to the memory block that was obtained with \ref osMailGet. 770 /// \return status code that indicates the execution status of the function. 771 /// \note MUST REMAIN UNCHANGED: \b osMailFree shall be consistent in every CMSIS-RTOS. 772 osStatus osMailFree (osMailQId queue_id, void *mail); 773 774 #endif // Mail Queues available 775 776 777 #define DEFAULT_STACK_SIZE (1024*4) 778 779 void os_error_str (const char *fmt, ...); 780 781 int osGetThreadIntId (void); 782 783 const char *osGetThreadName (void); 784 785 osStatus osThreadGetState(osThreadId thread_id); 786 787 void osThreadExitPub (void); 788 789 uint32_t osThreadGetPrivData(osThreadId thread_id); 790 791 uint32_t osThreadSetPrivData(osThreadId thread_id, uint32_t privdata); 792 793 /* cmsis interface thread name */ 794 const char *osThreadGetName (osThreadId id); 795 796 /* rhino interface thread name */ 797 const char *osGetThreadName(); 798 799 #ifdef __cplusplus 800 } 801 #endif 802 803 #endif // _CMSIS_OS_H 804 805