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 80extern "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*/ 92typedef 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*/ 103typedef 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*/ 124typedef 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*/ 145typedef 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*/ 258typedef void (*osThreadFunc_t) (void *argument); 259 260/** 261* @brief Callback for timer triggering 262* 263*/ 264typedef void (*osTimerFunc_t) (void *argument); 265 266/** 267* @brief Enumerates timer types. 268* 269*/ 270typedef 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*/ 351typedef 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*/ 374typedef void *osThreadId_t; 375 376/** 377* @brief Identifies a timer. 378* 379*/ 380typedef void *osTimerId_t; 381 382/** 383* @brief Identifies an event flag. 384* 385*/ 386typedef void *osEventFlagsId_t; 387 388/** 389* @brief Identifies a mutex. 390* 391*/ 392typedef void *osMutexId_t; 393 394/** 395* @brief Identifies a semaphore object. 396* 397*/ 398typedef void *osSemaphoreId_t; 399 400 401typedef void *osMemoryPoolId_t; 402 403/** 404* @brief Identifies a message queue. 405* 406*/ 407typedef 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*/ 417typedef uint32_t TZ_ModuleId_t; 418#endif 419 420/** 421* @brief Describes thread attributes. 422* 423* @since 1.0 424* @version 1.0 425*/ 426typedef 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*/ 453typedef 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*/ 470typedef 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*/ 487typedef 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*/ 504typedef 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 516typedef 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*/ 531typedef 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*/ 556osStatus_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*/ 568osStatus_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*/ 577osKernelState_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*/ 586osStatus_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*/ 595int32_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*/ 604int32_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*/ 614int32_t osKernelRestoreLock (int32_t lock); 615 616uint32_t osKernelSuspend (void); 617 618void osKernelResume (uint32_t sleep_ticks); 619 620/// Get the RTOS kernel tick count. 621/// \return RTOS kernel current tick count. 622uint32_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*/ 633uint32_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*/ 642uint32_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*/ 651uint32_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*/ 668osThreadId_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*/ 678const 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*/ 687osThreadId_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*/ 698osThreadState_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*/ 708uint32_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*/ 718uint32_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*/ 729osStatus_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*/ 739osPriority_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*/ 748osStatus_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*/ 758osStatus_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*/ 768osStatus_t osThreadResume (osThreadId_t thread_id); 769 770osStatus_t osThreadDetach (osThreadId_t thread_id); 771 772osStatus_t osThreadJoin (osThreadId_t thread_id); 773 774void 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*/ 784osStatus_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*/ 793uint32_t osThreadGetCount (void); 794 795uint32_t osThreadEnumerate (osThreadId_t *thread_array, uint32_t array_items); 796 797 798// ==== Thread Flags Functions ==== 799 800uint32_t osThreadFlagsSet (osThreadId_t thread_id, uint32_t flags); 801 802uint32_t osThreadFlagsClear (uint32_t flags); 803 804uint32_t osThreadFlagsGet (void); 805 806uint32_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*/ 819osStatus_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*/ 830osStatus_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*/ 848osTimerId_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*/ 858const 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*/ 869osStatus_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*/ 879osStatus_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*/ 889uint32_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*/ 899osStatus_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*/ 912osEventFlagsId_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*/ 922const 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*/ 933uint32_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*/ 944uint32_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*/ 954uint32_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*/ 968uint32_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*/ 978osStatus_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*/ 991osMutexId_t osMutexNew (const osMutexAttr_t *attr); 992 993const 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*/ 1004osStatus_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*/ 1014osStatus_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*/ 1024osThreadId_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*/ 1034osStatus_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*/ 1049osSemaphoreId_t osSemaphoreNew (uint32_t max_count, uint32_t initial_count, const osSemaphoreAttr_t *attr); 1050 1051const 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*/ 1062osStatus_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*/ 1072osStatus_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*/ 1082uint32_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*/ 1092osStatus_t osSemaphoreDelete (osSemaphoreId_t semaphore_id); 1093 1094 1095// ==== Memory Pool Management Functions ==== 1096 1097osMemoryPoolId_t osMemoryPoolNew (uint32_t block_count, uint32_t block_size, const osMemoryPoolAttr_t *attr); 1098 1099const char *osMemoryPoolGetName (osMemoryPoolId_t mp_id); 1100 1101void *osMemoryPoolAlloc (osMemoryPoolId_t mp_id, uint32_t timeout); 1102 1103osStatus_t osMemoryPoolFree (osMemoryPoolId_t mp_id, void *block); 1104 1105uint32_t osMemoryPoolGetCapacity (osMemoryPoolId_t mp_id); 1106 1107uint32_t osMemoryPoolGetBlockSize (osMemoryPoolId_t mp_id); 1108 1109uint32_t osMemoryPoolGetCount (osMemoryPoolId_t mp_id); 1110 1111uint32_t osMemoryPoolGetSpace (osMemoryPoolId_t mp_id); 1112 1113osStatus_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*/ 1128osMessageQueueId_t osMessageQueueNew (uint32_t msg_count, uint32_t msg_size, const osMessageQueueAttr_t *attr); 1129 1130const 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*/ 1143osStatus_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*/ 1156osStatus_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*/ 1166uint32_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*/ 1176uint32_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*/ 1186uint32_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*/ 1196uint32_t osMessageQueueGetSpace (osMessageQueueId_t mq_id); 1197 1198osStatus_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*/ 1208osStatus_t osMessageQueueDelete (osMessageQueueId_t mq_id); 1209 1210 1211#ifdef __cplusplus 1212} 1213#endif 1214 1215#endif // CMSIS_OS2_H_ 1216