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