1 /* 2 * Copyright (c) 2013-2018 Arm Limited. All rights reserved. 3 * 4 * SPDX-License-Identifier: Apache-2.0 5 * 6 * Licensed under the Apache License, Version 2.0 (the License); you may 7 * not use this file except in compliance with the License. 8 * You may obtain a copy of the License at 9 * 10 * www.apache.org/licenses/LICENSE-2.0 11 * 12 * Unless required by applicable law or agreed to in writing, software 13 * distributed under the License is distributed on an AS IS BASIS, WITHOUT 14 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 15 * See the License for the specific language governing permissions and 16 * limitations under the License. 17 * 18 * ---------------------------------------------------------------------- 19 * 20 * $Date: 18. June 2018 21 * $Revision: V2.1.3 22 * 23 * Project: CMSIS-RTOS2 API 24 * Title: cmsis_os2.h header file 25 * 26 * Version 2.1.3 27 * Additional functions allowed to be called from Interrupt Service Routines: 28 * - osThreadGetId 29 * Version 2.1.2 30 * Additional functions allowed to be called from Interrupt Service Routines: 31 * - osKernelGetInfo, osKernelGetState 32 * Version 2.1.1 33 * Additional functions allowed to be called from Interrupt Service Routines: 34 * - osKernelGetTickCount, osKernelGetTickFreq 35 * Changed Kernel Tick type to uint32_t: 36 * - updated: osKernelGetTickCount, osDelayUntil 37 * Version 2.1.0 38 * Support for critical and uncritical sections (nesting safe): 39 * - updated: osKernelLock, osKernelUnlock 40 * - added: osKernelRestoreLock 41 * Updated Thread and Event Flags: 42 * - changed flags parameter and return type from int32_t to uint32_t 43 * Version 2.0.0 44 * Initial Release 45 *---------------------------------------------------------------------------*/ 46 47 /** 48 * @addtogroup CMSIS 49 * @{ 50 * 51 * @brief Provides standard, universal real-time operating system (RTOS) APIs. 52 * 53 * CMSIS Module may contain portions from ARM Cortex Microcontroller Software Interface Standard (CMSIS) licensed under Apache License v2.0. 54 * 55 * @since 1.0 56 * @version 1.0 57 */ 58 59 #ifndef CMSIS_OS2_H_ 60 #define CMSIS_OS2_H_ 61 62 #ifndef __NO_RETURN 63 #if defined(__CC_ARM) 64 #define __NO_RETURN __declspec(noreturn) 65 #elif defined(__ARMCC_VERSION) && (__ARMCC_VERSION >= 6010050) 66 #define __NO_RETURN __attribute__((__noreturn__)) 67 #elif defined(__GNUC__) 68 #define __NO_RETURN __attribute__((__noreturn__)) 69 #elif defined(__ICCARM__) 70 #define __NO_RETURN __noreturn 71 #else 72 #define __NO_RETURN 73 #endif 74 #endif 75 76 #include <stdint.h> 77 #include <stddef.h> 78 79 #ifdef __cplusplus 80 extern "C" { 81 #endif 82 83 84 // ==== Enumerations, structures, defines ==== 85 86 /** 87 * @brief Describes the system version. 88 * 89 * @since 1.0 90 * @version 1.0 91 */ 92 typedef struct { 93 /** API version */ 94 uint32_t api; 95 /** Kernel version */ 96 uint32_t kernel; 97 } osVersion_t; 98 99 /** 100 * @brief Enumerates kernel states. 101 * 102 */ 103 typedef enum { 104 /** The kernel is inactive. */ 105 osKernelInactive = 0, 106 /** The kernel is ready. */ 107 osKernelReady = 1, 108 /** The kernel is running. */ 109 osKernelRunning = 2, 110 /** The kernel is locked. */ 111 osKernelLocked = 3, 112 /** The kernel is suspended. */ 113 osKernelSuspended = 4, 114 /** The kernel is abnormal. */ 115 osKernelError = -1, 116 /** Reserved */ 117 osKernelReserved = 0x7FFFFFFFU 118 } osKernelState_t; 119 120 /** 121 * @brief Enumerates thread states. 122 * 123 */ 124 typedef enum { 125 /** The thread is inactive. */ 126 osThreadInactive = 0, 127 /** The thread is ready. */ 128 osThreadReady = 1, 129 /** The thread is running. */ 130 osThreadRunning = 2, 131 /** The thread is blocked. */ 132 osThreadBlocked = 3, 133 /** The thread is terminated. */ 134 osThreadTerminated = 4, 135 /** The thread is abnormal. */ 136 osThreadError = -1, 137 /** Reserved */ 138 osThreadReserved = 0x7FFFFFFF 139 } osThreadState_t; 140 141 /** 142 * @brief Enumerates thread priorities. 143 * 144 */ 145 typedef enum { 146 /** Undefined */ 147 osPriorityNone = 0, 148 /** Reserved for idle threads */ 149 osPriorityIdle = 1, 150 /** Low (unsupported) */ 151 osPriorityLow = 8, 152 /** Low + 1 */ 153 osPriorityLow1 = 8+1, 154 /** Low + 2 */ 155 osPriorityLow2 = 8+2, 156 /** Low + 3 */ 157 osPriorityLow3 = 8+3, 158 /** Low + 4 */ 159 osPriorityLow4 = 8+4, 160 /** Low + 5 */ 161 osPriorityLow5 = 8+5, 162 /** Low + 6 */ 163 osPriorityLow6 = 8+6, 164 /** Low + 7 */ 165 osPriorityLow7 = 8+7, 166 /** Below normal */ 167 osPriorityBelowNormal = 16, 168 /** Below normal + 1 */ 169 osPriorityBelowNormal1 = 16+1, 170 /** Below normal + 2 */ 171 osPriorityBelowNormal2 = 16+2, 172 /** Below normal + 3 */ 173 osPriorityBelowNormal3 = 16+3, 174 /** Below normal + 4 */ 175 osPriorityBelowNormal4 = 16+4, 176 /** Below normal + 5 */ 177 osPriorityBelowNormal5 = 16+5, 178 /** Below normal + 6 */ 179 osPriorityBelowNormal6 = 16+6, 180 /** Below normal + 7 */ 181 osPriorityBelowNormal7 = 16+7, 182 /** Normal */ 183 osPriorityNormal = 24, 184 /** Normal + 1 */ 185 osPriorityNormal1 = 24+1, 186 /** Normal + 2 */ 187 osPriorityNormal2 = 24+2, 188 /** Normal + 3 */ 189 osPriorityNormal3 = 24+3, 190 /** Normal + 4 */ 191 osPriorityNormal4 = 24+4, 192 /** Normal + 5 */ 193 osPriorityNormal5 = 24+5, 194 /** Normal + 6 */ 195 osPriorityNormal6 = 24+6, 196 /** Normal + 7 */ 197 osPriorityNormal7 = 24+7, 198 /** Above normal */ 199 osPriorityAboveNormal = 32, 200 /** Above normal + 1 */ 201 osPriorityAboveNormal1 = 32+1, 202 /** Above normal + 2 */ 203 osPriorityAboveNormal2 = 32+2, 204 /** Above normal + 3 */ 205 osPriorityAboveNormal3 = 32+3, 206 /** Above normal + 4 */ 207 osPriorityAboveNormal4 = 32+4, 208 /** Above normal + 5 */ 209 osPriorityAboveNormal5 = 32+5, 210 /** Above normal + 6 */ 211 osPriorityAboveNormal6 = 32+6, 212 /** Above normal + 7 (unsupported) */ 213 osPriorityAboveNormal7 = 32+7, 214 /** High (unsupported) */ 215 osPriorityHigh = 40, 216 /** High + 1 (unsupported) */ 217 osPriorityHigh1 = 40+1, 218 /** High + 2 (unsupported) */ 219 osPriorityHigh2 = 40+2, 220 /** High + 3 (unsupported) */ 221 osPriorityHigh3 = 40+3, 222 /** High + 4 (unsupported) */ 223 osPriorityHigh4 = 40+4, 224 /** High + 5 (unsupported) */ 225 osPriorityHigh5 = 40+5, 226 /** High + 6 (unsupported) */ 227 osPriorityHigh6 = 40+6, 228 /** High + 7 (unsupported) */ 229 osPriorityHigh7 = 40+7, 230 /** Real-time (unsupported) */ 231 osPriorityRealtime = 48, 232 /** Real-time + 1 (unsupported) */ 233 osPriorityRealtime1 = 48+1, 234 /** Real-time + 2 (unsupported) */ 235 osPriorityRealtime2 = 48+2, 236 /** Real-time + 3 (unsupported) */ 237 osPriorityRealtime3 = 48+3, 238 /** Real-time + 4 (unsupported) */ 239 osPriorityRealtime4 = 48+4, 240 /** Real-time + 5 (unsupported) */ 241 osPriorityRealtime5 = 48+5, 242 /** Real-time + 6 (unsupported) */ 243 osPriorityRealtime6 = 48+6, 244 /** Real-time + 7 (unsupported) */ 245 osPriorityRealtime7 = 48+7, 246 /** Reserved for ISR deferred threads (unsupported) */ 247 osPriorityISR = 56, 248 /** Invalid */ 249 osPriorityError = -1, 250 /** Reserved. It enables the compiler to identify enumeration variables as 32-bit numbers and prevents the enumeration variables from being optimized. */ 251 osPriorityReserved = 0x7FFFFFFF 252 } osPriority_t; 253 254 /** 255 * @brief Callback for thread scheduling 256 * 257 */ 258 typedef void (*osThreadFunc_t) (void *argument); 259 260 /** 261 * @brief Callback for timer triggering 262 * 263 */ 264 typedef void (*osTimerFunc_t) (void *argument); 265 266 /** 267 * @brief Enumerates timer types. 268 * 269 */ 270 typedef enum { 271 /** One-shot timer */ 272 osTimerOnce = 0, 273 /** Repeating timer */ 274 osTimerPeriodic = 1 275 } osTimerType_t; 276 277 /** 278 * @brief Indicates that the RTOS waits forever unless an event flag is received. 279 * 280 */ 281 #define osWaitForever 0xFFFFFFFFU 282 283 /** 284 * @brief Indicates that the RTOS does not wait. 285 * 286 */ 287 #define osNoWait 0x0U 288 289 /** 290 * @brief Indicates that the RTOS waits until any event flag is triggered. 291 * 292 */ 293 #define osFlagsWaitAny 0x00000000U 294 295 /** 296 * @brief Indicates that the system waits until all event flags are triggered. 297 * 298 */ 299 #define osFlagsWaitAll 0x00000001U 300 301 /** 302 * @brief Indicates that defined flags are not cleared. 303 * 304 */ 305 #define osFlagsNoClear 0x00000002U 306 307 /** 308 * @brief Indicates a flag error. 309 * 310 */ 311 #define osFlagsError 0x80000000U 312 313 /** 314 * @brief Indicates an unknown error. 315 * 316 */ 317 #define osFlagsErrorUnknown 0xFFFFFFFFU 318 319 /** 320 * @brief Indicates a timeout. 321 * 322 */ 323 #define osFlagsErrorTimeout 0xFFFFFFFEU 324 325 /** 326 * @brief Indicates a resource error. 327 * 328 */ 329 #define osFlagsErrorResource 0xFFFFFFFDU 330 331 /** 332 * @brief Indicates an incorrect parameter. 333 * 334 */ 335 #define osFlagsErrorParameter 0xFFFFFFFCU 336 #define osFlagsErrorISR 0xFFFFFFFAU 337 338 // Thread attributes (attr_bits in \ref osThreadAttr_t). 339 #define osThreadDetached 0x00000000U 340 #define osThreadJoinable 0x00000001U 341 342 // Mutex attributes (attr_bits in \ref osMutexAttr_t). 343 #define osMutexRecursive 0x00000001U 344 #define osMutexPrioInherit 0x00000002U 345 #define osMutexRobust 0x00000008U 346 347 /** 348 * @brief Enumerates return values of CMSIS-RTOS. 349 * 350 */ 351 typedef enum { 352 /** Operation completed successfully */ 353 osOK = 0, 354 /** Unspecified error */ 355 osError = -1, 356 /** Timeout */ 357 osErrorTimeout = -2, 358 /** Resource error */ 359 osErrorResource = -3, 360 /** Incorrect parameter */ 361 osErrorParameter = -4, 362 /** Insufficient memory */ 363 osErrorNoMemory = -5, 364 /** Service interruption */ 365 osErrorISR = -6, 366 /** Reserved. It is used to prevent the compiler from optimizing enumerations. */ 367 osStatusReserved = 0x7FFFFFFF 368 } osStatus_t; 369 370 /** 371 * @brief Identifies a thread. 372 * 373 */ 374 typedef void *osThreadId_t; 375 376 /** 377 * @brief Identifies a timer. 378 * 379 */ 380 typedef void *osTimerId_t; 381 382 /** 383 * @brief Identifies an event flag. 384 * 385 */ 386 typedef void *osEventFlagsId_t; 387 388 /** 389 * @brief Identifies a mutex. 390 * 391 */ 392 typedef void *osMutexId_t; 393 394 /** 395 * @brief Identifies a semaphore object. 396 * 397 */ 398 typedef void *osSemaphoreId_t; 399 400 401 typedef void *osMemoryPoolId_t; 402 403 /** 404 * @brief Identifies a message queue. 405 * 406 */ 407 typedef void *osMessageQueueId_t; 408 409 410 #ifndef TZ_MODULEID_T 411 #define TZ_MODULEID_T 412 413 /** 414 * @brief Identifies a TrustZone module call process. 415 * 416 */ 417 typedef uint32_t TZ_ModuleId_t; 418 #endif 419 420 /** 421 * @brief Describes thread attributes. 422 * 423 * @since 1.0 424 * @version 1.0 425 */ 426 typedef struct { 427 /** Thread name */ 428 const char *name; 429 /** Thread attribute bits */ 430 uint32_t attr_bits; 431 /** Memory for the thread control block */ 432 void *cb_mem; 433 /** Size of the memory for the thread control block */ 434 uint32_t cb_size; 435 /** Memory for the thread stack */ 436 void *stack_mem; 437 /** Size of the thread stack */ 438 uint32_t stack_size; 439 /** Thread priority */ 440 osPriority_t priority; 441 /** TrustZone module of the thread */ 442 TZ_ModuleId_t tz_module; 443 /** Reserved */ 444 uint32_t reserved; 445 } osThreadAttr_t; 446 447 /** 448 * @brief Describes timer attributes. 449 * 450 * @since 1.0 451 * @version 1.0 452 */ 453 typedef struct { 454 /** Timer name */ 455 const char *name; 456 /** Reserved attribute bits */ 457 uint32_t attr_bits; 458 /** Memory for the timer control block */ 459 void *cb_mem; 460 /** Size of the memory for the timer control block */ 461 uint32_t cb_size; 462 } osTimerAttr_t; 463 464 /** 465 * @brief Describes event attributes. 466 * 467 * @since 1.0 468 * @version 1.0 469 */ 470 typedef struct { 471 /** Event name */ 472 const char *name; 473 /** Reserved attribute bits */ 474 uint32_t attr_bits; 475 /** Memory for the event control block */ 476 void *cb_mem; 477 /** Size of the memory for the event control block */ 478 uint32_t cb_size; 479 } osEventFlagsAttr_t; 480 481 /** 482 * @brief Describes mutex attributes. 483 * 484 * @since 1.0 485 * @version 1.0 486 */ 487 typedef struct { 488 /** Mutex name */ 489 const char *name; 490 /** Reserved attribute bits */ 491 uint32_t attr_bits; 492 /** Memory for the mutex control block */ 493 void *cb_mem; 494 /** Size of the memory for the mutex control block */ 495 uint32_t cb_size; 496 } osMutexAttr_t; 497 498 /** 499 * @brief Describes semaphore attributes. 500 * 501 * @since 1.0 502 * @version 1.0 503 */ 504 typedef struct { 505 /** Semaphore name */ 506 const char *name; 507 /** Reserved attribute bits */ 508 uint32_t attr_bits; 509 /** Memory for the semaphore control block */ 510 void *cb_mem; 511 /** Size of the memory for the semaphore control block */ 512 uint32_t cb_size; 513 } osSemaphoreAttr_t; 514 515 516 typedef struct { 517 const char *name; 518 uint32_t attr_bits; 519 void *cb_mem; 520 uint32_t cb_size; 521 void *mp_mem; 522 uint32_t mp_size; 523 } osMemoryPoolAttr_t; 524 525 /** 526 * @brief Describes message queue attributes. 527 * 528 * @since 1.0 529 * @version 1.0 530 */ 531 typedef struct { 532 /** Message queue name */ 533 const char *name; 534 /** Reserved attribute bits */ 535 uint32_t attr_bits; 536 /** Memory for the message queue control block */ 537 void *cb_mem; 538 /** Size of the memory for the message queue control block */ 539 uint32_t cb_size; 540 /** Memory for storing data in the message queue */ 541 void *mq_mem; 542 /** Size of the memory for storing data in the message queue */ 543 uint32_t mq_size; 544 } osMessageQueueAttr_t; 545 546 547 // ==== Kernel Management Functions ==== 548 549 /** 550 * @brief Initializes the RTOS kernel. 551 * 552 * @return Returns the CMSIS-RTOS running result. 553 * @since 1.0 554 * @version 1.0 555 */ 556 osStatus_t osKernelInitialize (void); 557 558 /** 559 * @brief Obtains the system version and name. 560 * 561 * @param version Indicates the pointer to the buffer for storing the version. 562 * @param id_buf Indicates the pointer to the buffer for storing the kernel ID. 563 * @param id_size Indicates the size of the buffer for storing the kernel ID. 564 * @return Returns the CMSIS-RTOS running result. 565 * @since 1.0 566 * @version 1.0 567 */ 568 osStatus_t osKernelGetInfo (osVersion_t *version, char *id_buf, uint32_t id_size); 569 570 /** 571 * @brief Obtains the kernel state. 572 * 573 * @return Returns the kernel state. 574 * @since 1.0 575 * @version 1.0 576 */ 577 osKernelState_t osKernelGetState (void); 578 579 /** 580 * @brief Starts the kernel. 581 * 582 * @return Returns the CMSIS-RTOS running result. 583 * @since 1.0 584 * @version 1.0 585 */ 586 osStatus_t osKernelStart (void); 587 588 /** 589 * @brief Locks the kernel. 590 * 591 * @return Returns 1 if the kernel is locked successfully; returns 0 if the lock starts; returns a negative value in the case of an error. 592 * @since 1.0 593 * @version 1.0 594 */ 595 int32_t osKernelLock (void); 596 597 /** 598 * @brief Unlocks the kernel. 599 * 600 * @return Returns 1 if the kernel is unlocked successfully; returns 0 if the kernel is not locked; returns a negative value in the case of an error. 601 * @since 1.0 602 * @version 1.0 603 */ 604 int32_t osKernelUnlock (void); 605 606 /** 607 * @brief Restores the previous lock state of the kernel. 608 * 609 * @param lock Indicates the lock state to restore to. The value 1 indicates the locked state, and 0 indicates the unlocked state. 610 * @return Returns 1 if the kernel is locked; returns 0 if the kernel is not locked; returns a negative value in the case of an error. 611 * @since 1.0 612 * @version 1.0 613 */ 614 int32_t osKernelRestoreLock (int32_t lock); 615 616 uint32_t osKernelSuspend (void); 617 618 void osKernelResume (uint32_t sleep_ticks); 619 620 /// Get the RTOS kernel tick count. 621 /// \return RTOS kernel current tick count. 622 uint32_t osKernelGetTickCount (void); 623 624 625 626 /** 627 * @brief Obtains the number of kernel ticks per second. 628 * 629 * @return Returns the number of kernel ticks. 630 * @since 1.0 631 * @version 1.0 632 */ 633 uint32_t osKernelGetTickFreq (void); 634 635 /** 636 * @brief Obtains the kernel system timer. 637 * 638 * @return Returns the kernel system timer. 639 * @since 1.0 640 * @version 1.0 641 */ 642 uint32_t osKernelGetSysTimerCount (void); 643 644 /** 645 * @brief Obtains the frequency of the system timer. 646 * 647 * @return Returns the system timer frequency. 648 * @since 1.0 649 * @version 1.0 650 */ 651 uint32_t osKernelGetSysTimerFreq (void); 652 653 654 // ==== Thread Management Functions ==== 655 656 /** 657 * @brief Creates an active thread. 658 * 659 * The priority ranges from 9 to 38. Select a proper priority as required. 660 * The maximum of tasks is LOSCFG_BASE_CORE_TSK_LIMIT(LOSCFG_BASE_CORE_TSK_LIMIT is defined in the traget_config.h). 661 * @param func Indicates the entry of the thread callback function. 662 * @param argument Indicates the pointer to the argument passed to the thread. 663 * @param attr Indicates the thread attributes. 664 * @return Returns the thread ID; returns NULL in the case of an error. 665 * @since 1.0 666 * @version 1.0 667 */ 668 osThreadId_t osThreadNew (osThreadFunc_t func, void *argument, const osThreadAttr_t *attr); 669 670 /** 671 * @brief Obtains the name of a thread. 672 * 673 * @param thread_id Indicates the thread ID, which is obtained using osThreadNew or osThreadGetId. 674 * @return Returns the thread name; returns NULL in the case of an error. 675 * @since 1.0 676 * @version 1.0 677 */ 678 const char *osThreadGetName (osThreadId_t thread_id); 679 680 /** 681 * @brief Obtains the ID of the currently running thread. 682 * 683 * @return Returns the thread ID; returns NULL in the case of an error. 684 * @since 1.0 685 * @version 1.0 686 */ 687 osThreadId_t osThreadGetId (void); 688 689 690 /** 691 * @brief Obtains the state of a thread. 692 * 693 * @param thread_id Indicates the thread ID, which is obtained using osThreadNew or osThreadGetId. 694 * @return Returns the thread state. 695 * @since 1.0 696 * @version 1.0 697 */ 698 osThreadState_t osThreadGetState (osThreadId_t thread_id); 699 700 /** 701 * @brief Obtains the stack size of a thread. 702 * 703 * @param thread_id Indicates the thread ID, which is obtained using osThreadNew or osThreadGetId. 704 * @return Returns the stack size, in bytes; returns 0 in the case of an error. 705 * @since 1.0 706 * @version 1.0 707 */ 708 uint32_t osThreadGetStackSize (osThreadId_t thread_id); 709 710 /** 711 * @brief Obtains the size of the available stack space for a thread based on the stack watermark. 712 * 713 * @param thread_id Indicates the thread ID, which is obtained using osThreadNew or osThreadGetId. 714 * @return Returns the available stack size, in bytes; returns 0 in the case of an error. 715 * @since 1.0 716 * @version 1.0 717 */ 718 uint32_t osThreadGetStackSpace (osThreadId_t thread_id); 719 720 /** 721 * @brief Changes the priority of a thread. 722 * 723 * @param thread_id Indicates the thread ID, which is obtained using osThreadNew or osThreadGetId. 724 * @param priority Indicates the new priority. 725 * @return Returns the CMSIS-RTOS running result. 726 * @since 1.0 727 * @version 1.0 728 */ 729 osStatus_t osThreadSetPriority (osThreadId_t thread_id, osPriority_t priority); 730 731 /** 732 * @brief Gets the prority of an active thread. 733 * 734 * @param thread_id Indicates the thread ID, which is obtained using osThreadNew or osThreadGetId. 735 * @return Returns the prority of the thread. 736 * @since 1.0 737 * @version 1.0 738 */ 739 osPriority_t osThreadGetPriority (osThreadId_t thread_id); 740 741 /** 742 * @brief Sets the currently running thread to the ready state. 743 * 744 * @return Returns the CMSIS-RTOS running result. 745 * @since 1.0 746 * @version 1.0 747 */ 748 osStatus_t osThreadYield (void); 749 750 /** 751 * @brief Suspends a thread. 752 * 753 * @param thread_id Indicates the thread ID, which is obtained using osThreadNew or osThreadGetId. 754 * @return Returns the CMSIS-RTOS running result. 755 * @since 1.0 756 * @version 1.0 757 */ 758 osStatus_t osThreadSuspend (osThreadId_t thread_id); 759 760 /** 761 * @brief Resumes a thread from the suspended state. 762 * 763 * @param thread_id Indicates the thread ID, which is obtained using osThreadNew or osThreadGetId. 764 * @return Returns the CMSIS-RTOS running result. 765 * @since 1.0 766 * @version 1.0 767 */ 768 osStatus_t osThreadResume (osThreadId_t thread_id); 769 770 osStatus_t osThreadDetach (osThreadId_t thread_id); 771 772 osStatus_t osThreadJoin (osThreadId_t thread_id); 773 774 void osThreadExit (void); 775 776 /** 777 * @brief Terminates a thread. 778 * 779 * @param thread_id Indicates the thread ID, which is obtained using osThreadNew or osThreadGetId. 780 * @return Returns the CMSIS-RTOS running result. 781 * @since 1.0 782 * @version 1.0 783 */ 784 osStatus_t osThreadTerminate (osThreadId_t thread_id); 785 786 /** 787 * @brief Obtains the number of active threads. 788 * 789 * @return Returns the number; returns 0 in the case of an error. 790 * @since 1.0 791 * @version 1.0 792 */ 793 uint32_t osThreadGetCount (void); 794 795 uint32_t osThreadEnumerate (osThreadId_t *thread_array, uint32_t array_items); 796 797 798 // ==== Thread Flags Functions ==== 799 800 uint32_t osThreadFlagsSet (osThreadId_t thread_id, uint32_t flags); 801 802 uint32_t osThreadFlagsClear (uint32_t flags); 803 804 uint32_t osThreadFlagsGet (void); 805 806 uint32_t osThreadFlagsWait (uint32_t flags, uint32_t options, uint32_t timeout); 807 808 809 // ==== Generic Wait Functions ==== 810 811 /** 812 * @brief Waits for a period of time. 813 * 814 * @param ticks Indicates the number of ticks to wait for. 815 * @return Returns the CMSIS-RTOS running result. 816 * @since 1.0 817 * @version 1.0 818 */ 819 osStatus_t osDelay (uint32_t ticks); 820 821 /** 822 * @brief Waits until a specified time arrives. 823 * 824 * This function handles the overflow of the system timer. Note that the maximum value of this parameter is (2^31 - 1) ticks. 825 * @param ticks Indicates the number of ticks converted from the absolute time. 826 * @return Returns the CMSIS-RTOS running result. 827 * @since 1.0 828 * @version 1.0 829 */ 830 osStatus_t osDelayUntil (uint32_t ticks); 831 832 833 // ==== Timer Management Functions ==== 834 835 /** 836 * @brief Creates and initializes a timer. 837 * 838 * This function creates a timer associated with the arguments callback function. The timer stays in the stopped state until OSTimerStart is used to start the timer. 839 * The timer precision is 1000 / LOSCFG_BASE_CORE_TICK_PER_SECOND ms(LOSCFG_BASE_CORE_TICK_PER_SECOND is defined in the traget_config.h). 840 * @param func Indicates the entry of the timer callback function. 841 * @param type Indicates the timer type. 842 * @param argument Indicates the pointer to the argument used in timer callback. 843 * @param attr Indicates the pointer to the timer attributes. This parameter is not used. 844 * @return Returns the timer ID; returns NULL in the case of an error. 845 * @since 1.0 846 * @version 1.0 847 */ 848 osTimerId_t osTimerNew (osTimerFunc_t func, osTimerType_t type, void *argument, const osTimerAttr_t *attr); 849 850 /** 851 * @brief Obtains the timer name. 852 * 853 * @param timer_id Indicates the timer ID, which is obtained using osTimerNew. 854 * @return Returns the timer name; returns NULL in the case of an error. 855 * @since 1.0 856 * @version 1.0 857 */ 858 const char *osTimerGetName (osTimerId_t timer_id); 859 860 /** 861 * @brief Starts or restarts a timer. 862 * 863 * @param timer_id Indicates the timer ID, which is obtained using osTimerNew. 864 * @param ticks Indicates the number of ticks since the timer starts running. 865 * @return Returns the CMSIS-RTOS running result. 866 * @since 1.0 867 * @version 1.0 868 */ 869 osStatus_t osTimerStart (osTimerId_t timer_id, uint32_t ticks); 870 871 /** 872 * @brief Stops a timer. 873 * 874 * @param timer_id Indicates the timer ID, which is obtained using osTimerNew. 875 * @return Returns the CMSIS-RTOS running result. 876 * @since 1.0 877 * @version 1.0 878 */ 879 osStatus_t osTimerStop (osTimerId_t timer_id); 880 881 /** 882 * @brief Checks whether a timer is running. 883 * 884 * @param timer_id Indicates the timer ID, which is obtained using osTimerNew. 885 * @return Returns 1 if the timer is running; returns 0 otherwise. 886 * @since 1.0 887 * @version 1.0 888 */ 889 uint32_t osTimerIsRunning (osTimerId_t timer_id); 890 891 /** 892 * @brief Deletes a timer. 893 * 894 * @param timer_id Indicates the timer ID, which is obtained using osTimerNew. 895 * @return Returns the CMSIS-RTOS running result. 896 * @since 1.0 897 * @version 1.0 898 */ 899 osStatus_t osTimerDelete (osTimerId_t timer_id); 900 901 902 // ==== Event Flags Management Functions ==== 903 904 /** 905 * @brief Creates and initializes an event flags object. 906 * 907 * @param attr Indicates the pointer to the event flags attributes. This parameter is not used. 908 * @return Returns the event flags ID; returns NULL in the case of an error. 909 * @since 1.0 910 * @version 1.0 911 */ 912 osEventFlagsId_t osEventFlagsNew (const osEventFlagsAttr_t *attr); 913 914 /** 915 * @brief Obtains the name of an event flags object. 916 * 917 * @param ef_id Indicates the event flags ID, which is obtained using osEventFlagsNew. 918 * @return Returns the event flags name; returns NULL in the case of an error. 919 * @since 1.0 920 * @version 1.0 921 */ 922 const char *osEventFlagsGetName (osEventFlagsId_t ef_id); 923 924 /** 925 * @brief Sets event flags. 926 * 927 * @param ef_id Indicates the event flags ID, which is obtained using osEventFlagsNew. 928 * @param flags Indicates the event flags to set. 929 * @return Returns the event flags; returns osFlagsErrorParameter in the case of an error. 930 * @since 1.0 931 * @version 1.0 932 */ 933 uint32_t osEventFlagsSet (osEventFlagsId_t ef_id, uint32_t flags); 934 935 /** 936 * @brief Clears event flags. 937 * 938 * @param ef_id Indicates the event flags ID, which is obtained using osEventFlagsNew. 939 * @param flags Indicates the event flags to clear. 940 * @return Returns the event flags; returns osFlagsErrorParameter in the case of an error. 941 * @since 1.0 942 * @version 1.0 943 */ 944 uint32_t osEventFlagsClear (osEventFlagsId_t ef_id, uint32_t flags); 945 946 /** 947 * @brief Obtains event flags. 948 * 949 * @param ef_id Indicates the event flags ID, which is obtained using osEventFlagsNew. 950 * @return Returns the event flags triggered. 951 * @since 1.0 952 * @version 1.0 953 */ 954 uint32_t osEventFlagsGet (osEventFlagsId_t ef_id); 955 956 /** 957 * @brief Waits for event flags to trigger. 958 * 959 * When the specified flag of the event is set, the function returns immediately. Otherwise, the thread is blocked. 960 * @param ef_id Indicates the event flags ID, which is obtained using osEventFlagsNew. 961 * @param flags Indicates the event flags to trigger. 962 * @param options Indicates the configuration of the event flags to trigger. 963 * @param timeout Indicates the timeout duration. 964 * @return Returns the triggered event flags; returns an error value in the case of an error. 965 * @since 1.0 966 * @version 1.0 967 */ 968 uint32_t osEventFlagsWait (osEventFlagsId_t ef_id, uint32_t flags, uint32_t options, uint32_t timeout); 969 970 /** 971 * @brief Deletes an event flags object. 972 * 973 * @param ef_id Indicates the event flags ID, which is obtained using osEventFlagsNew. 974 * @return Returns the CMSIS-RTOS running result. 975 * @since 1.0 976 * @version 1.0 977 */ 978 osStatus_t osEventFlagsDelete (osEventFlagsId_t ef_id); 979 980 981 // ==== Mutex Management Functions ==== 982 983 /** 984 * @brief Creates and initializes a mutex. 985 * 986 * @param attr Indicates the pointer to the mutex attributes. This parameter is not used. 987 * @return Returns the mutex ID; returns NULL in the case of an error. 988 * @since 1.0 989 * @version 1.0 990 */ 991 osMutexId_t osMutexNew (const osMutexAttr_t *attr); 992 993 const char *osMutexGetName (osMutexId_t mutex_id); 994 995 /** 996 * @brief Obtains a mutex. 997 * 998 * @param mutex_id Indicates the mutex ID, which is obtained using osMutexNew. 999 * @param timeout Indicates the timeout duration. 1000 * @return Returns the CMSIS-RTOS running result. 1001 * @since 1.0 1002 * @version 1.0 1003 */ 1004 osStatus_t osMutexAcquire (osMutexId_t mutex_id, uint32_t timeout); 1005 1006 /** 1007 * @brief Releases a mutex. 1008 * 1009 * @param mutex_id Indicates the mutex ID, which is obtained using osMutexNew. 1010 * @return Returns the CMSIS-RTOS running result. 1011 * @since 1.0 1012 * @version 1.0 1013 */ 1014 osStatus_t osMutexRelease (osMutexId_t mutex_id); 1015 1016 /** 1017 * @brief Obtains the thread ID of the currently acquired mutex. 1018 * 1019 * @param mutex_id Indicates the mutex ID, which is obtained using osMutexNew. 1020 * @return Returns the thread ID. 1021 * @since 1.0 1022 * @version 1.0 1023 */ 1024 osThreadId_t osMutexGetOwner (osMutexId_t mutex_id); 1025 1026 /** 1027 * @brief Deletes a mutex. 1028 * 1029 * @param mutex_id Indicates the mutex ID, which is obtained using osMutexNew. 1030 * @return Returns the CMSIS-RTOS running result. 1031 * @since 1.0 1032 * @version 1.0 1033 */ 1034 osStatus_t osMutexDelete (osMutexId_t mutex_id); 1035 1036 1037 // ==== Semaphore Management Functions ==== 1038 1039 /** 1040 * @brief Creates and initializes a semaphore object. 1041 * 1042 * @param max_count Indicates the maximum number of available tokens that can be applied for. 1043 * @param initial_count Indicates the initial number of available tokens. 1044 * @param attr Indicates the pointer to the semaphore attributes. This parameter is not used. 1045 * @return Returns the semaphore ID; returns NULL in the case of an error. 1046 * @since 1.0 1047 * @version 1.0 1048 */ 1049 osSemaphoreId_t osSemaphoreNew (uint32_t max_count, uint32_t initial_count, const osSemaphoreAttr_t *attr); 1050 1051 const char *osSemaphoreGetName (osSemaphoreId_t semaphore_id); 1052 1053 /** 1054 * @brief Acquires a token of a semaphore object. 1055 * 1056 * @param semaphore_id Indicates the semaphore ID, which is obtained using osSemaphoreNew. 1057 * @param timeout Indicates the timeout duration. This parameter is the number of ticks. 1058 * @return Returns the CMSIS-RTOS running result. 1059 * @since 1.0 1060 * @version 1.0 1061 */ 1062 osStatus_t osSemaphoreAcquire (osSemaphoreId_t semaphore_id, uint32_t timeout); 1063 1064 /** 1065 * @brief Releases a token of a semaphore object. 1066 * 1067 * @param semaphore_id Indicates the semaphore ID, which is obtained using osSemaphoreNew. 1068 * @return Returns the CMSIS-RTOS running result. 1069 * @since 1.0 1070 * @version 1.0 1071 */ 1072 osStatus_t osSemaphoreRelease (osSemaphoreId_t semaphore_id); 1073 1074 /** 1075 * @brief Obtains the number of available tokens of a semaphore object. 1076 * 1077 * @param semaphore_id Indicates the semaphore ID, which is obtained using osSemaphoreNew. 1078 * @return Returns the number of available tokens. 1079 * @since 1.0 1080 * @version 1.0 1081 */ 1082 uint32_t osSemaphoreGetCount (osSemaphoreId_t semaphore_id); 1083 1084 /** 1085 * @brief Deletes a semaphore object. 1086 * 1087 * @param semaphore_id Indicates the semaphore ID, which is obtained using osSemaphoreNew. 1088 * @return Returns the CMSIS-RTOS running result. 1089 * @since 1.0 1090 * @version 1.0 1091 */ 1092 osStatus_t osSemaphoreDelete (osSemaphoreId_t semaphore_id); 1093 1094 1095 // ==== Memory Pool Management Functions ==== 1096 1097 osMemoryPoolId_t osMemoryPoolNew (uint32_t block_count, uint32_t block_size, const osMemoryPoolAttr_t *attr); 1098 1099 const char *osMemoryPoolGetName (osMemoryPoolId_t mp_id); 1100 1101 void *osMemoryPoolAlloc (osMemoryPoolId_t mp_id, uint32_t timeout); 1102 1103 osStatus_t osMemoryPoolFree (osMemoryPoolId_t mp_id, void *block); 1104 1105 uint32_t osMemoryPoolGetCapacity (osMemoryPoolId_t mp_id); 1106 1107 uint32_t osMemoryPoolGetBlockSize (osMemoryPoolId_t mp_id); 1108 1109 uint32_t osMemoryPoolGetCount (osMemoryPoolId_t mp_id); 1110 1111 uint32_t osMemoryPoolGetSpace (osMemoryPoolId_t mp_id); 1112 1113 osStatus_t osMemoryPoolDelete (osMemoryPoolId_t mp_id); 1114 1115 1116 // ==== Message Queue Management Functions ==== 1117 1118 /** 1119 * @brief Creates and initializes a message queue. 1120 * 1121 * @param msg_count Indicates the number of messages in the message queue. 1122 * @param msg_size Indicates the size of messages in the message queue. 1123 * @param attr Indicates the pointer to the message queue attributes. This parameter is not used. 1124 * @return Returns the message queue ID; returns NULL in the case of an error. 1125 * @since 1.0 1126 * @version 1.0 1127 */ 1128 osMessageQueueId_t osMessageQueueNew (uint32_t msg_count, uint32_t msg_size, const osMessageQueueAttr_t *attr); 1129 1130 const char *osMessageQueueGetName (osMessageQueueId_t mq_id); 1131 1132 /** 1133 * @brief Places a message in a message queue. 1134 * 1135 * @param mq_id Indicates the message queue ID, which is obtained using osMessageQueueNew. 1136 * @param msg_ptr Indicates the pointer to the buffer for storing the message to be placed in the message queue. 1137 * @param msg_prio Indicates the priority of the message to be placed in the message queue. This parameter is not used. 1138 * @param timeout Indicates the timeout duration. 1139 * @return Returns the CMSIS-RTOS running result. 1140 * @since 1.0 1141 * @version 1.0 1142 */ 1143 osStatus_t osMessageQueuePut (osMessageQueueId_t mq_id, const void *msg_ptr, uint8_t msg_prio, uint32_t timeout); 1144 1145 /** 1146 * @brief Obtains a message in a message queue. 1147 * 1148 * @param mq_id Indicates the message queue ID, which is obtained using osMessageQueueNew. 1149 * @param msg_ptr Indicates the pointer to the buffer for storing the message to be retrieved from the message queue. 1150 * @param msg_prio Indicates the pointer to the buffer for storing the priority of the message to be retrieved from the message queue. This parameter is not used. 1151 * @param timeout Indicates the timeout duration. 1152 * @return Returns the CMSIS-RTOS running result. 1153 * @since 1.0 1154 * @version 1.0 1155 */ 1156 osStatus_t osMessageQueueGet (osMessageQueueId_t mq_id, void *msg_ptr, uint8_t *msg_prio, uint32_t timeout); 1157 1158 /** 1159 * @brief Obtains the maximum number of messages that can be placed in a message queue. 1160 * 1161 * @param mq_id Indicates the message queue ID, which is obtained using osMessageQueueNew. 1162 * @return Returns the maximum number. 1163 * @since 1.0 1164 * @version 1.0 1165 */ 1166 uint32_t osMessageQueueGetCapacity (osMessageQueueId_t mq_id); 1167 1168 /** 1169 * @brief Obtains the maximum size of messages that can be placed in a message queue. 1170 * 1171 * @param mq_id Indicates the message queue ID, which is obtained using osMessageQueueNew. 1172 * @return Returns the maximum message size. 1173 * @since 1.0 1174 * @version 1.0 1175 */ 1176 uint32_t osMessageQueueGetMsgSize (osMessageQueueId_t mq_id); 1177 1178 /** 1179 * @brief Obtains the number of queued messages in a message queue. 1180 * 1181 * @param mq_id Indicates the message queue ID, which is obtained using osMessageQueueNew. 1182 * @return Returns the number of queued messages. 1183 * @since 1.0 1184 * @version 1.0 1185 */ 1186 uint32_t osMessageQueueGetCount (osMessageQueueId_t mq_id); 1187 1188 /** 1189 * @brief Obtains the number of available slots for messages in a message queue. 1190 * 1191 * @param mq_id Indicates the message queue ID, which is obtained using osMessageQueueNew. 1192 * @return Returns the number of available slots for messages. 1193 * @since 1.0 1194 * @version 1.0 1195 */ 1196 uint32_t osMessageQueueGetSpace (osMessageQueueId_t mq_id); 1197 1198 osStatus_t osMessageQueueReset (osMessageQueueId_t mq_id); 1199 1200 /** 1201 * @brief Deletes a message queue. 1202 * 1203 * @param mq_id Indicates the message queue ID, which is obtained using osMessageQueueNew. 1204 * @return Returns the CMSIS-RTOS running result. 1205 * @since 1.0 1206 * @version 1.0 1207 */ 1208 osStatus_t osMessageQueueDelete (osMessageQueueId_t mq_id); 1209 1210 1211 #ifdef __cplusplus 1212 } 1213 #endif 1214 1215 #endif // CMSIS_OS2_H_ 1216