1 /* 2 * Copyright (c) 2013-2019 Huawei Technologies Co., Ltd. All rights reserved. 3 * Copyright (c) 2020-2023 Huawei Device Co., Ltd. All rights reserved. 4 * 5 * Redistribution and use in source and binary forms, with or without modification, 6 * are permitted provided that the following conditions are met: 7 * 8 * 1. Redistributions of source code must retain the above copyright notice, this list of 9 * conditions and the following disclaimer. 10 * 11 * 2. Redistributions in binary form must reproduce the above copyright notice, this list 12 * of conditions and the following disclaimer in the documentation and/or other materials 13 * provided with the distribution. 14 * 15 * 3. Neither the name of the copyright holder nor the names of its contributors may be used 16 * to endorse or promote products derived from this software without specific prior written 17 * permission. 18 * 19 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 20 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, 21 * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 22 * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR 23 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, 24 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, 25 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; 26 * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, 27 * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR 28 * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF 29 * ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 30 */ 31 32 /** 33 * @defgroup los_task Task 34 * @ingroup kernel 35 */ 36 37 #ifndef _LOS_TASK_H 38 #define _LOS_TASK_H 39 40 #include "los_base.h" 41 #include "los_list.h" 42 #include "los_sys.h" 43 #include "los_tick.h" 44 #include "los_event.h" 45 #include "los_memory.h" 46 #include "los_err.h" 47 48 #ifdef __cplusplus 49 #if __cplusplus 50 extern "C" { 51 #endif /* __cplusplus */ 52 #endif /* __cplusplus */ 53 54 #define CPUID_TO_AFFI_MASK(cpuid) (0x1u << (cpuid)) 55 56 /** 57 * @ingroup los_task 58 * Flag that indicates the task or task control block status. 59 * 60 * The task is automatically deleted. 61 */ 62 #define LOS_TASK_STATUS_DETACHED 0x0U 63 64 /** 65 * @ingroup los_task 66 * Flag that indicates the task or task control block status. 67 * 68 * The task is joinable. 69 */ 70 #define LOS_TASK_ATTR_JOINABLE 0x80000000 71 72 /** 73 * @ingroup los_task 74 * Task error code: Insufficient memory for task creation. 75 * 76 * Value: 0x03000200 77 * 78 * Solution: Allocate bigger memory partition to task creation. 79 */ 80 #define LOS_ERRNO_TSK_NO_MEMORY LOS_ERRNO_OS_FATAL(LOS_MOD_TSK, 0x00) 81 82 /** 83 * @ingroup los_task 84 * Task error code: Null parameter. 85 * 86 * Value: 0x02000201 87 * 88 * Solution: Check the parameter. 89 */ 90 #define LOS_ERRNO_TSK_PTR_NULL LOS_ERRNO_OS_ERROR(LOS_MOD_TSK, 0x01) 91 92 /** 93 * @ingroup los_task 94 * Task error code: The task stack is not aligned. 95 * 96 * Value: 0x02000202 97 * 98 * Solution: Align the task stack. 99 */ 100 #define LOS_ERRNO_TSK_STKSZ_NOT_ALIGN LOS_ERRNO_OS_ERROR(LOS_MOD_TSK, 0x02) 101 102 /** 103 * @ingroup los_task 104 * Task error code: Incorrect task priority. 105 * 106 * Value: 0x02000203 107 * 108 * Solution: Re-configure the task priority by referring to the priority range. 109 */ 110 #define LOS_ERRNO_TSK_PRIOR_ERROR LOS_ERRNO_OS_ERROR(LOS_MOD_TSK, 0x03) 111 112 /** 113 * @ingroup los_task 114 * Task error code: The task entrance is NULL. 115 * 116 * Value: 0x02000204 117 * 118 * Solution: Define the task entrance function. 119 */ 120 #define LOS_ERRNO_TSK_ENTRY_NULL LOS_ERRNO_OS_ERROR(LOS_MOD_TSK, 0x04) 121 122 /** 123 * @ingroup los_task 124 * Task error code: The task name is NULL. 125 * 126 * Value: 0x02000205 127 * 128 * Solution: Set the task name. 129 */ 130 #define LOS_ERRNO_TSK_NAME_EMPTY LOS_ERRNO_OS_ERROR(LOS_MOD_TSK, 0x05) 131 132 /** 133 * @ingroup los_task 134 * Task error code: The task stack size is too small. 135 * 136 * Value: 0x02000206 137 * 138 * Solution: Expand the task stack. 139 */ 140 #define LOS_ERRNO_TSK_STKSZ_TOO_SMALL LOS_ERRNO_OS_ERROR(LOS_MOD_TSK, 0x06) 141 142 /** 143 * @ingroup los_task 144 * Task error code: Invalid task ID. 145 * 146 * Value: 0x02000207 147 * 148 * Solution: Check the task ID. 149 */ 150 #define LOS_ERRNO_TSK_ID_INVALID LOS_ERRNO_OS_ERROR(LOS_MOD_TSK, 0x07) 151 152 /** 153 * @ingroup los_task 154 * Task error code: The task is already suspended. 155 * 156 * Value: 0x02000208 157 * 158 * Solution: Suspend the task after it is resumed. 159 */ 160 #define LOS_ERRNO_TSK_ALREADY_SUSPENDED LOS_ERRNO_OS_ERROR(LOS_MOD_TSK, 0x08) 161 162 /** 163 * @ingroup los_task 164 * Task error code: The task is not suspended. 165 * 166 * Value: 0x02000209 167 * 168 * Solution: Suspend the task. 169 */ 170 #define LOS_ERRNO_TSK_NOT_SUSPENDED LOS_ERRNO_OS_ERROR(LOS_MOD_TSK, 0x09) 171 172 /** 173 * @ingroup los_task 174 * Task error code: The task is not created. 175 * 176 * Value: 0x0200020a 177 * 178 * Solution: Create the task. 179 */ 180 #define LOS_ERRNO_TSK_NOT_CREATED LOS_ERRNO_OS_ERROR(LOS_MOD_TSK, 0x0a) 181 182 /** 183 * @ingroup los_task 184 * Task error code: The task is locked when it is being deleted. 185 * 186 * Value: 0x0300020b 187 * 188 * Solution: Unlock the task. 189 */ 190 #define LOS_ERRNO_TSK_DELETE_LOCKED LOS_ERRNO_OS_FATAL(LOS_MOD_TSK, 0x0b) 191 192 /** 193 * @ingroup los_task 194 * Task error code: The task message is nonzero. 195 * 196 * Value: 0x0200020c 197 * 198 * Solution: This error code is not in use temporarily. 199 */ 200 #define LOS_ERRNO_TSK_MSG_NONZERO LOS_ERRNO_OS_ERROR(LOS_MOD_TSK, 0x0c) 201 202 /** 203 * @ingroup los_task 204 * Task error code: The task delay occurs during an interrupt. 205 * 206 * Value: 0x0300020d 207 * 208 * Solution: Perform this operation after exiting from the interrupt. 209 */ 210 #define LOS_ERRNO_TSK_DELAY_IN_INT LOS_ERRNO_OS_FATAL(LOS_MOD_TSK, 0x0d) 211 212 /** 213 * @ingroup los_task 214 * Task error code: The task delay occurs when the task is locked. 215 * 216 * Value: 0x0200020e 217 * 218 * Solution: Perform this operation after unlocking the task. 219 */ 220 #define LOS_ERRNO_TSK_DELAY_IN_LOCK LOS_ERRNO_OS_ERROR(LOS_MOD_TSK, 0x0e) 221 222 /** 223 * @ingroup los_task 224 * Task error code: The task yield occurs when the task is locked. 225 * Value: 0x0200020f 226 * 227 * Solution: Check the task. 228 */ 229 #define LOS_ERRNO_TSK_YIELD_IN_LOCK LOS_ERRNO_OS_ERROR(LOS_MOD_TSK, 0x0f) 230 231 /** 232 * @ingroup los_task 233 * Task error code: Only one task or no task is available for scheduling. 234 * 235 * Value: 0x02000210 236 * 237 * Solution: Increase the number of tasks. 238 */ 239 #define LOS_ERRNO_TSK_YIELD_NOT_ENOUGH_TASK LOS_ERRNO_OS_ERROR(LOS_MOD_TSK, 0x10) 240 241 /** 242 * @ingroup los_task 243 * Task error code: No free task control block is available. 244 * 245 * Value: 0x02000211 246 * 247 * Solution: Increase the number of task control blocks. 248 */ 249 #define LOS_ERRNO_TSK_TCB_UNAVAILABLE LOS_ERRNO_OS_ERROR(LOS_MOD_TSK, 0x11) 250 251 /** 252 * @ingroup los_task 253 * Task error code: The task hook function is not matchable. 254 * 255 * Value: 0x02000212 256 * 257 * Solution: This error code is not in use temporarily. 258 */ 259 #define LOS_ERRNO_TSK_HOOK_NOT_MATCH LOS_ERRNO_OS_ERROR(LOS_MOD_TSK, 0x12) 260 261 /** 262 * @ingroup los_task 263 * Task error code: The number of task hook functions exceeds the permitted upper limit. 264 * 265 * Value: 0x02000213 266 * 267 * Solution: This error code is not in use temporarily. 268 */ 269 #define LOS_ERRNO_TSK_HOOK_IS_FULL LOS_ERRNO_OS_ERROR(LOS_MOD_TSK, 0x13) 270 271 /** 272 * @ingroup los_task 273 * Task error code: The operation is performed on the system-level task. 274 * old usage: The operation is performed on the idle task (LOS_ERRNO_TSK_OPERATE_IDLE) 275 * 276 * Value: 0x02000214 277 * 278 * Solution: Check the task ID and do not operate on the system-level task. 279 */ 280 #define LOS_ERRNO_TSK_OPERATE_SYSTEM_TASK LOS_ERRNO_OS_ERROR(LOS_MOD_TSK, 0x14) 281 282 /** 283 * @ingroup los_task 284 * Task error code: The task that is being suspended is locked. 285 * 286 * Value: 0x03000215 287 * 288 * Solution: Suspend the task after unlocking the task. 289 */ 290 #define LOS_ERRNO_TSK_SUSPEND_LOCKED LOS_ERRNO_OS_FATAL(LOS_MOD_TSK, 0x15) 291 292 /** 293 * @ingroup los_task 294 * Task error code: The task stack fails to be freed. 295 * 296 * Value: 0x02000217 297 * 298 * Solution: This error code is not in use temporarily. 299 */ 300 #define LOS_ERRNO_TSK_FREE_STACK_FAILED LOS_ERRNO_OS_ERROR(LOS_MOD_TSK, 0x17) 301 302 /** 303 * @ingroup los_task 304 * Task error code: The task stack area is too small. 305 * 306 * Value: 0x02000218 307 * 308 * Solution: This error code is not in use temporarily. 309 */ 310 #define LOS_ERRNO_TSK_STKAREA_TOO_SMALL LOS_ERRNO_OS_ERROR(LOS_MOD_TSK, 0x18) 311 312 /** 313 * @ingroup los_task 314 * Task error code: The task fails to be activated. 315 * 316 * Value: 0x03000219 317 * 318 * Solution: Perform task switching after creating an idle task. 319 */ 320 #define LOS_ERRNO_TSK_ACTIVE_FAILED LOS_ERRNO_OS_FATAL(LOS_MOD_TSK, 0x19) 321 322 /** 323 * @ingroup los_task 324 * Task error code: Too many task configuration items. 325 * 326 * Value: 0x0200021a 327 * 328 * Solution: This error code is not in use temporarily. 329 */ 330 #define LOS_ERRNO_TSK_CONFIG_TOO_MANY LOS_ERRNO_OS_ERROR(LOS_MOD_TSK, 0x1a) 331 332 /** 333 * @ingroup los_task 334 * Task error code: 335 * 336 * Value: 0x0200021b 337 * 338 * Solution: This error code is not in use temporarily. 339 */ 340 #define LOS_ERRNO_TSK_CP_SAVE_AREA_NOT_ALIGN LOS_ERRNO_OS_ERROR(LOS_MOD_TSK, 0x1b) 341 342 /** 343 * @ingroup los_task 344 * Task error code: 345 * 346 * Value: 0x0200021d 347 * 348 * Solution: This error code is not in use temporarily. 349 */ 350 #define LOS_ERRNO_TSK_MSG_Q_TOO_MANY LOS_ERRNO_OS_ERROR(LOS_MOD_TSK, 0x1d) 351 352 /** 353 * @ingroup los_task 354 * Task error code: 355 * 356 * Value: 0x0200021e 357 * 358 * Solution: This error code is not in use temporarily. 359 */ 360 #define LOS_ERRNO_TSK_CP_SAVE_AREA_NULL LOS_ERRNO_OS_ERROR(LOS_MOD_TSK, 0x1e) 361 362 /** 363 * @ingroup los_task 364 * Task error code: 365 * 366 * Value: 0x0200021f 367 * 368 * Solution: This error code is not in use temporarily. 369 */ 370 #define LOS_ERRNO_TSK_SELF_DELETE_ERR LOS_ERRNO_OS_ERROR(LOS_MOD_TSK, 0x1f) 371 372 /** 373 * @ingroup los_task 374 * Task error code: The task stack size is too large. 375 * 376 * Value: 0x02000220 377 * 378 * Solution: shrink the task stack size parameter. 379 */ 380 #define LOS_ERRNO_TSK_STKSZ_TOO_LARGE LOS_ERRNO_OS_ERROR(LOS_MOD_TSK, 0x20) 381 382 /** 383 * @ingroup los_task 384 * Task error code: Suspending software timer task is not allowed. 385 * 386 * Value: 0x02000221 387 * 388 * Solution: Check the task ID and do not suspend software timer task. 389 */ 390 #define LOS_ERRNO_TSK_SUSPEND_SWTMR_NOT_ALLOWED LOS_ERRNO_OS_ERROR(LOS_MOD_TSK, 0x21) 391 392 /** 393 * @ingroup los_task 394 * Task error code: The task delay occurs in software timer task. 395 * 396 * Value: 0x03000222 397 * 398 * Solution: Don't call Los_TaskDelay in software timer callback. 399 */ 400 #define LOS_ERRNO_TSK_DELAY_IN_SWTMR_TSK LOS_ERRNO_OS_FATAL(LOS_MOD_TSK, 0x22) 401 402 /** 403 * @ingroup los_task 404 * Task error code: The cpu affinity mask is incorrect. 405 * 406 * Value: 0x03000223 407 * 408 * Solution: Please set the correct cpu affinity mask. 409 */ 410 #define LOS_ERRNO_TSK_CPU_AFFINITY_MASK_ERR LOS_ERRNO_OS_FATAL(LOS_MOD_TSK, 0x23) 411 412 /** 413 * @ingroup los_task 414 * Task error code: Task yield in int is not permited, which will result in unexpected result. 415 * 416 * Value: 0x02000224 417 * 418 * Solution: Don't call LOS_TaskYield in Interrupt. 419 */ 420 #define LOS_ERRNO_TSK_YIELD_IN_INT LOS_ERRNO_OS_ERROR(LOS_MOD_TSK, 0x24) 421 422 /** 423 * @ingroup los_task 424 * Task error code: Task sync resource (semaphore) allocated failed. 425 * 426 * Value: 0x02000225 427 * 428 * Solution: Expand LOSCFG_BASE_IPC_SEM_LIMIT. 429 */ 430 #define LOS_ERRNO_TSK_MP_SYNC_RESOURCE LOS_ERRNO_OS_ERROR(LOS_MOD_TSK, 0x25) 431 432 /** 433 * @ingroup los_task 434 * Task error code: Task sync failed on operating running task across cores. 435 * 436 * Value: 0x02000226 437 * 438 * Solution: Check task delete can be handled in user's scenario. 439 */ 440 #define LOS_ERRNO_TSK_MP_SYNC_FAILED LOS_ERRNO_OS_ERROR(LOS_MOD_TSK, 0x26) 441 442 /** 443 * @ingroup los_task 444 * Task error code: Task wait and timeout. 445 * 446 * Value: 0x02000227 447 * 448 * Solution: Returns the timeout. 449 */ 450 #define LOS_ERRNO_TSK_TIMEOUT LOS_ERRNO_OS_FATAL(LOS_MOD_TSK, 0x27) 451 452 /** 453 * @ingroup los_task 454 * Task error code: A task that is not in the current process. 455 * 456 * Value: 0x02000228 457 * 458 * Solution: tasks that are not part of the current process are not allowed to operate. 459 */ 460 #define LOS_ERRNO_TSK_NOT_SELF_PROCESS LOS_ERRNO_OS_FATAL(LOS_MOD_TSK, 0x28) 461 462 /** 463 * @ingroup los_task 464 * @brief Define the type of a task entrance function. 465 * 466 * @par Description: 467 * This API is used to define the type of a task entrance function and call it after a task is created and triggered. 468 * @attention None. 469 * 470 * @param param1 [IN] Type #UINTPTR The first parameter passed to the task handling function. 471 * @param param2 [IN] Type #UINTPTR The second parameter passed to the task handling function. 472 * @param param3 [IN] Type #UINTPTR The third parameter passed to the task handling function. 473 * @param param4 [IN] Type #UINTPTR The fourth parameter passed to the task handling function. 474 * 475 * @retval None. 476 * @par Dependency: 477 * <ul><li>los_task.h: the header file that contains the API declaration.</li></ul> 478 * @see 479 */ 480 typedef VOID *(*TSK_ENTRY_FUNC)(UINTPTR param1, 481 UINTPTR param2, 482 UINTPTR param3, 483 UINTPTR param4); 484 485 /** 486 * @ingroup los_task 487 * You are not allowed to add any fields and adjust fields to the structure 488 */ 489 typedef struct { 490 UINTPTR userArea; 491 UINTPTR userSP; 492 UINTPTR userMapBase; 493 UINT32 userMapSize; 494 } UserTaskParam; 495 496 /** 497 * @ingroup los_task 498 * Define the structure of the parameters used for task creation. 499 * 500 * Information of specified parameters passed in during task creation. 501 */ 502 typedef struct tagTskInitParam { 503 TSK_ENTRY_FUNC pfnTaskEntry; /**< Task entrance function */ 504 UINT16 usTaskPrio; /**< Task priority */ 505 UINT16 policy; /**< Task policy */ 506 UINTPTR auwArgs[4]; /**< Task parameters, of which the maximum number is four */ 507 UINT32 uwStackSize; /**< Task stack size */ 508 CHAR *pcName; /**< Task name */ 509 #ifdef LOSCFG_KERNEL_SMP 510 UINT16 usCpuAffiMask; /**< Task cpu affinity mask */ 511 #endif 512 UINT32 uwResved; /**< It is automatically deleted if set to LOS_TASK_STATUS_DETACHED. 513 It is unable to be deleted if set to 0. */ 514 UINT16 consoleID; /**< The console id of task belongs */ 515 UINTPTR processID; 516 UserTaskParam userParam; 517 /* edf parameters */ 518 UINT32 runTimeUs; 519 UINT64 deadlineUs; 520 UINT64 periodUs; 521 } TSK_INIT_PARAM_S; 522 523 typedef struct { 524 union { 525 INT32 priority; 526 INT32 runTimeUs; 527 }; 528 INT32 deadlineUs; 529 INT32 periodUs; 530 } LosSchedParam; 531 532 /** 533 * @ingroup los_task 534 * Task name length 535 * 536 */ 537 #define LOS_TASK_NAMELEN 32 538 539 /** 540 * @ingroup los_task 541 * Task information structure. 542 * 543 */ 544 typedef struct tagTskInfo { 545 CHAR acName[LOS_TASK_NAMELEN]; /**< Task entrance function */ 546 UINT32 uwTaskID; /**< Task ID */ 547 UINT16 usTaskStatus; /**< Task status */ 548 UINT16 usTaskPrio; /**< Task priority */ 549 VOID *pTaskSem; /**< Semaphore pointer */ 550 VOID *pTaskMux; /**< Mutex pointer */ 551 VOID *taskEvent; /**< Event */ 552 UINT32 uwEventMask; /**< Event mask */ 553 UINT32 uwStackSize; /**< Task stack size */ 554 UINTPTR uwTopOfStack; /**< Task stack top */ 555 UINTPTR uwBottomOfStack; /**< Task stack bottom */ 556 UINTPTR uwSP; /**< Task SP pointer */ 557 UINT32 uwCurrUsed; /**< Current task stack usage */ 558 UINT32 uwPeakUsed; /**< Task stack usage peak */ 559 BOOL bOvf; /**< Flag that indicates whether a task stack overflow occurs */ 560 } TSK_INFO_S; 561 562 /** 563 * @ingroup los_task 564 * @brief Create a task and suspend. 565 * 566 * @par Description: 567 * This API is used to create a task and suspend it. This task will not be added to the queue of ready tasks 568 * before resume it. 569 * 570 * @attention 571 * <ul> 572 * <li>During task creation, the task control block and task stack of the task that is previously automatically deleted 573 * are deallocated.</li> 574 * <li>The task name is a pointer and is not allocated memory.</li> 575 * <li>If the size of the task stack of the task to be created is 0, configure #LOSCFG_BASE_CORE_TSK_DEFAULT_STACK_SIZE 576 * to specify the default task stack size. The stack size should be a reasonable value, if the size is too large, may 577 * cause memory exhaustion.</li> 578 * <li>The task stack size must be aligned on the boundary of 8 bytes. The size is determined by whether it is big 579 * enough to avoid task stack overflow.</li> 580 * <li>Less parameter value indicates higher task priority.</li> 581 * <li>The task name cannot be null.</li> 582 * <li>The pointer to the task executing function cannot be null.</li> 583 * <li>The two parameters of this interface is pointer, it should be a correct value, otherwise, the system may be 584 * abnormal.</li> 585 * </ul> 586 * 587 * @param taskID [OUT] Type #UINT32 * Task ID. 588 * @param initParam [IN] Type #TSK_INIT_PARAM_S * Parameter for task creation. 589 * 590 * @retval #LOS_ERRNO_TSK_ID_INVALID Invalid Task ID, param taskID is NULL. 591 * @retval #LOS_ERRNO_TSK_PTR_NULL Param initParam is NULL. 592 * @retval #LOS_ERRNO_TSK_NAME_EMPTY The task name is NULL. 593 * @retval #LOS_ERRNO_TSK_ENTRY_NULL The task entrance is NULL. 594 * @retval #LOS_ERRNO_TSK_PRIOR_ERROR Incorrect task priority. 595 * @retval #LOS_ERRNO_TSK_STKSZ_TOO_LARGE The task stack size is too large. 596 * @retval #LOS_ERRNO_TSK_STKSZ_TOO_SMALL The task stack size is too small. 597 * @retval #LOS_ERRNO_TSK_TCB_UNAVAILABLE No free task control block is available. 598 * @retval #LOS_ERRNO_TSK_NO_MEMORY Insufficient memory for task creation. 599 * @retval #LOS_OK The task is successfully created. 600 * @par Dependency: 601 * <ul><li>los_task.h: the header file that contains the API declaration.</li></ul> 602 * <ul><li>los_config.h: the header file that contains system configuration items.</li></ul> 603 * @see LOS_TaskDelete 604 */ 605 extern UINT32 LOS_TaskCreateOnly(UINT32 *taskID, TSK_INIT_PARAM_S *initParam); 606 607 /** 608 * @ingroup los_task 609 * @brief Create a task. 610 * 611 * @par Description: 612 * This API is used to create a task. If the priority of the task created after system initialized is higher than 613 * the current task and task scheduling is not locked, it is scheduled for running. 614 * If not, the created task is added to the queue of ready tasks. 615 * 616 * @attention 617 * <ul> 618 * <li>During task creation, the task control block and task stack of the task that is previously automatically 619 * deleted are deallocated.</li> 620 * <li>The task name is a pointer and is not allocated memory.</li> 621 * <li>If the size of the task stack of the task to be created is 0, configure #LOSCFG_BASE_CORE_TSK_DEFAULT_STACK_SIZE 622 * to specify the default task stack size.</li> 623 * <li>The task stack size must be aligned on the boundary of 8 bytes. The size is determined by whether it is big 624 * enough to avoid task stack overflow.</li> 625 * <li>Less parameter value indicates higher task priority.</li> 626 * <li>The task name cannot be null.</li> 627 * <li>The pointer to the task executing function cannot be null.</li> 628 * <li>The two parameters of this interface is pointer, it should be a correct value, otherwise, the system may be 629 * abnormal.</li> 630 * </ul> 631 * 632 * @param taskID [OUT] Type #UINT32 * Task ID. 633 * @param initParam [IN] Type #TSK_INIT_PARAM_S * Parameter for task creation. 634 * 635 * @retval #LOS_ERRNO_TSK_ID_INVALID Invalid Task ID, param taskID is NULL. 636 * @retval #LOS_ERRNO_TSK_PTR_NULL Param initParam is NULL. 637 * @retval #LOS_ERRNO_TSK_NAME_EMPTY The task name is NULL. 638 * @retval #LOS_ERRNO_TSK_ENTRY_NULL The task entrance is NULL. 639 * @retval #LOS_ERRNO_TSK_PRIOR_ERROR Incorrect task priority. 640 * @retval #LOS_ERRNO_TSK_STKSZ_TOO_LARGE The task stack size is too large. 641 * @retval #LOS_ERRNO_TSK_STKSZ_TOO_SMALL The task stack size is too small. 642 * @retval #LOS_ERRNO_TSK_TCB_UNAVAILABLE No free task control block is available. 643 * @retval #LOS_ERRNO_TSK_NO_MEMORY Insufficient memory for task creation. 644 * @retval #LOS_OK The task is successfully created. 645 * @par Dependency: 646 * <ul><li>los_task.h: the header file that contains the API declaration.</li></ul> 647 * <ul><li>los_config.h: the header file that contains system configuration items.</li></ul> 648 * @see LOS_TaskDelete 649 */ 650 extern UINT32 LOS_TaskCreate(UINT32 *taskID, TSK_INIT_PARAM_S *initParam); 651 652 /** 653 * @ingroup los_task 654 * @brief Resume a task. 655 * 656 * @par Description: 657 * This API is used to resume a suspended task. 658 * 659 * @attention 660 * <ul> 661 * <li>If the task is delayed or blocked, resume the task without adding it to the queue of ready tasks.</li> 662 * <li>If the priority of the task resumed after system initialized is higher than the current task and task scheduling 663 * is not locked, it is scheduled for running.</li> 664 * </ul> 665 * 666 * @param taskID [IN] Type #UINT32 Task ID. The task id value is obtained from task creation. 667 * 668 * @retval #LOS_ERRNO_TSK_ID_INVALID Invalid Task ID 669 * @retval #LOS_ERRNO_TSK_NOT_CREATED The task is not created. 670 * @retval #LOS_ERRNO_TSK_NOT_SUSPENDED The task is not suspended. 671 * @retval #LOS_OK The task is successfully resumed. 672 * @par Dependency: 673 * <ul><li>los_task.h: the header file that contains the API declaration.</li></ul> 674 * @see LOS_TaskSuspend 675 */ 676 extern UINT32 LOS_TaskResume(UINT32 taskID); 677 678 /** 679 * @ingroup los_task 680 * @brief Suspend a task. 681 * 682 * @par Description: 683 * This API is used to suspend a specified task, and the task will be removed from the queue of ready tasks. 684 * 685 * @attention 686 * <ul> 687 * <li>The task that is running and locked cannot be suspended.</li> 688 * <li>The idle task and swtmr task cannot be suspended.</li> 689 * </ul> 690 * 691 * @param taskID [IN] Type #UINT32 Task ID. The task id value is obtained from task creation. 692 * 693 * @retval #LOS_ERRNO_TSK_OPERATE_IDLE Check the task ID and do not operate on the idle task. 694 * @retval #LOS_ERRNO_TSK_SUSPEND_SWTMR_NOT_ALLOWED Check the task ID and do not operate on the swtmr task. 695 * @retval #LOS_ERRNO_TSK_ID_INVALID Invalid Task ID 696 * @retval #LOS_ERRNO_TSK_NOT_CREATED The task is not created. 697 * @retval #LOS_ERRNO_TSK_ALREADY_SUSPENDED The task is already suspended. 698 * @retval #LOS_ERRNO_TSK_SUSPEND_LOCKED The task being suspended is current task and task scheduling 699 * is locked. 700 * @retval #LOS_OK The task is successfully suspended. 701 * @par Dependency: 702 * <ul><li>los_task.h: the header file that contains the API declaration.</li></ul> 703 * @see LOS_TaskResume 704 */ 705 extern UINT32 LOS_TaskSuspend(UINT32 taskID); 706 707 /** 708 * @ingroup los_task 709 * @brief Delete a task. 710 * 711 * @par Description: 712 * This API is used to delete a specified task and release the resources for its task stack and task control block. 713 * 714 * @attention 715 * <ul> 716 * <li>The idle task and swtmr task cannot be deleted.</li> 717 * <li>If delete current task maybe cause unexpected error.</li> 718 * <li>If a task get a mutex is deleted or automatically deleted before release this mutex, other tasks pended 719 * this mutex maybe never be shchduled.</li> 720 * </ul> 721 * 722 * @param taskID [IN] Type #UINT32 Task ID. The task id value is obtained from task creation. 723 * 724 * @retval #LOS_ERRNO_TSK_OPERATE_IDLE Check the task ID and do not operate on the idle task. 725 * @retval #LOS_ERRNO_TSK_SUSPEND_SWTMR_NOT_ALLOWED Check the task ID and do not operate on the swtmr task. 726 * @retval #LOS_ERRNO_TSK_ID_INVALID Invalid Task ID 727 * @retval #LOS_ERRNO_TSK_NOT_CREATED The task is not created. 728 * @retval #LOS_ERRNO_TSK_DELETE_LOCKED The task being deleted is current task and task scheduling 729 * is locked. 730 * @retval #LOS_OK The task is successfully deleted. 731 * @par Dependency: 732 * <ul><li>los_task.h: the header file that contains the API declaration.</li></ul> 733 * @see LOS_TaskCreate | LOS_TaskCreateOnly 734 */ 735 extern UINT32 LOS_TaskDelete(UINT32 taskID); 736 737 /** 738 * @ingroup los_task 739 * @brief Delay a task. 740 * 741 * @par Description: 742 * This API is used to delay the execution of the current task. The task is able to be scheduled after it is delayed 743 * for a specified number of Ticks. 744 * 745 * @attention 746 * <ul> 747 * <li>The task fails to be delayed if it is being delayed during interrupt processing or it is locked.</li> 748 * <li>If 0 is passed in and the task scheduling is not locked, execute the next task in the queue of tasks with 749 * the same priority of the current task. 750 * If no ready task with the priority of the current task is available, the task scheduling will not occur, and the 751 * current task continues to be executed.</li> 752 * <li>Using the interface before system initialized is not allowed.</li> 753 * <li>DO NOT call this API in software timer callback. </li> 754 * </ul> 755 * 756 * @param tick [IN] Type #UINT32 Number of Ticks for which the task is delayed. 757 * 758 * @retval #LOS_ERRNO_TSK_DELAY_IN_INT The task delay occurs during an interrupt. 759 * @retval #LOS_ERRNO_TSK_DELAY_IN_LOCK The task delay occurs when the task scheduling is locked. 760 * @retval #LOS_ERRNO_TSK_ID_INVALID Invalid Task ID 761 * @retval #LOS_ERRNO_TSK_YIELD_NOT_ENOUGH_TASK No tasks with the same priority is available for scheduling. 762 * @retval #LOS_OK The task is successfully delayed. 763 * @par Dependency: 764 * <ul><li>los_task.h: the header file that contains the API declaration.</li></ul> 765 * @see 766 */ 767 extern UINT32 LOS_TaskDelay(UINT32 tick); 768 769 /** 770 * @ingroup los_task 771 * @brief Lock the task scheduling. 772 * 773 * @par Description: 774 * This API is used to lock the task scheduling. Task switching will not occur if the task scheduling is locked. 775 * 776 * @attention 777 * <ul> 778 * <li>If the task scheduling is locked, but interrupts are not disabled, tasks are still able to be interrupted.</li> 779 * <li>One is added to the number of task scheduling locks if this API is called. The number of locks is decreased by 780 * one if the task scheduling is unlocked. Therefore, this API should be used together with LOS_TaskUnlock.</li> 781 * </ul> 782 * 783 * @param None. 784 * 785 * @retval None. 786 * @par Dependency: 787 * <ul><li>los_task.h: the header file that contains the API declaration.</li></ul> 788 * @see LOS_TaskUnlock 789 */ 790 extern VOID LOS_TaskLock(VOID); 791 792 /** 793 * @ingroup los_task 794 * @brief Unlock the task scheduling. 795 * 796 * @par Description: 797 * This API is used to unlock the task scheduling. Calling this API will decrease the number of task locks by one. 798 * If a task is locked more than once, the task scheduling will be unlocked only when the number of locks becomes zero. 799 * 800 * @attention 801 * <ul> 802 * <li>The number of locks is decreased by one if this API is called. One is added to the number of task scheduling 803 * locks if the task scheduling is locked. Therefore, this API should be used together with LOS_TaskLock.</li> 804 * </ul> 805 * 806 * @param None. 807 * 808 * @retval None. 809 * @par Dependency: 810 * <ul><li>los_task.h: the header file that contains the API declaration.</li></ul> 811 * @see LOS_TaskLock 812 */ 813 extern VOID LOS_TaskUnlock(VOID); 814 815 /** 816 * @ingroup los_task 817 * @brief Set a task priority. 818 * 819 * @par Description: 820 * This API is used to set the priority of a specified task. 821 * 822 * @attention 823 * <ul> 824 * <li>If the set priority is higher than the priority of the current running task, task scheduling 825 * probably occurs.</li> 826 * <li>Changing the priority of the current running task also probably causes task scheduling.</li> 827 * <li>Using the interface to change the priority of software timer task and idle task is not allowed.</li> 828 * <li>Using the interface in the interrupt is not allowed.</li> 829 * </ul> 830 * 831 * @param taskID [IN] Type #UINT32 Task ID. The task id value is obtained from task creation. 832 * @param taskPrio [IN] Type #UINT16 Task priority. 833 * 834 * @retval #LOS_ERRNO_TSK_PRIOR_ERROR Incorrect task priority.Re-configure the task priority 835 * @retval #LOS_ERRNO_TSK_OPERATE_IDLE Check the task ID and do not operate on the idle task. 836 * @retval #LOS_ERRNO_TSK_ID_INVALID Invalid Task ID 837 * @retval #LOS_ERRNO_TSK_NOT_CREATED The task is not created. 838 * @retval #LOS_OK The task priority is successfully set to a specified priority. 839 * @par Dependency: 840 * <ul><li>los_task.h: the header file that contains the API declaration.</li></ul> 841 * @see LOS_TaskPriSet 842 */ 843 extern UINT32 LOS_TaskPriSet(UINT32 taskID, UINT16 taskPrio); 844 845 /** 846 * @ingroup los_task 847 * @brief Set the priority of the current running task to a specified priority. 848 * 849 * @par Description: 850 * This API is used to set the priority of the current running task to a specified priority. 851 * 852 * @attention 853 * <ul> 854 * <li>Changing the priority of the current running task probably causes task scheduling.</li> 855 * <li>Using the interface to change the priority of software timer task and idle task is not allowed.</li> 856 * <li>Using the interface in the interrupt is not allowed.</li> 857 * </ul> 858 * 859 * @param taskPrio [IN] Type #UINT16 Task priority. 860 * 861 * @retval #LOS_ERRNO_TSK_PRIOR_ERROR Incorrect task priority.Re-configure the task priority 862 * @retval #LOS_ERRNO_TSK_OPERATE_IDLE Check the task ID and do not operate on the idle task. 863 * @retval #LOS_ERRNO_TSK_ID_INVALID Invalid Task ID 864 * @retval #LOS_ERRNO_TSK_NOT_CREATED The task is not created. 865 * @retval #LOS_OK The priority of the current running task is successfully set to a specified 866 * priority. 867 * @par Dependency: 868 * <ul><li>los_task.h: the header file that contains the API declaration.</li></ul> 869 * @see LOS_TaskPriGet 870 */ 871 extern UINT32 LOS_CurTaskPriSet(UINT16 taskPrio); 872 873 /** 874 * @ingroup los_task 875 * @brief Change the scheduling sequence of tasks with the same priority. 876 * 877 * @par Description: 878 * This API is used to move current task in a queue of tasks with the same priority to the tail of the queue of ready 879 * tasks. 880 * 881 * @attention 882 * <ul> 883 * <li>At least two ready tasks need to be included in the queue of ready tasks with the same priority. If the 884 * less than two ready tasks are included in the queue, an error is reported.</li> 885 * </ul> 886 * 887 * @param None. 888 * 889 * @retval #LOS_ERRNO_TSK_ID_INVALID Invalid Task ID 890 * @retval #LOS_ERRNO_TSK_YIELD_NOT_ENOUGH_TASK No tasks with the same priority is available for scheduling. 891 * @retval #LOS_OK The scheduling sequence of tasks with same priority is 892 * successfully changed. 893 * @par Dependency: 894 * <ul><li>los_task.h: the header file that contains the API declaration.</li></ul> 895 * @see 896 */ 897 extern UINT32 LOS_TaskYield(VOID); 898 899 /** 900 * @ingroup los_task 901 * @brief Obtain a task priority. 902 * 903 * @par Description: 904 * This API is used to obtain the priority of a specified task. 905 * 906 * @attention None. 907 * 908 * @param taskID [IN] Type #UINT32 Task ID. The task id value is obtained from task creation. 909 * 910 * @retval #OS_INVALID The task priority fails to be obtained. 911 * @retval #UINT16 The task priority. 912 * @par Dependency: 913 * <ul><li>los_task.h: the header file that contains the API declaration.</li></ul> 914 * @see LOS_TaskPriSet 915 */ 916 extern UINT16 LOS_TaskPriGet(UINT32 taskID); 917 918 /** 919 * @ingroup los_task 920 * @brief Obtain current running task ID. 921 * 922 * @par Description: 923 * This API is used to obtain the ID of current running task. 924 * 925 * @attention 926 * <ul> 927 * <li> This interface should not be called before system initialized.</li> 928 * </ul> 929 * 930 * @retval #LOS_ERRNO_TSK_ID_INVALID Invalid Task ID. 931 * @retval #UINT32 Task ID. 932 * @par Dependency: 933 * <ul><li>los_task.h: the header file that contains the API declaration.</li></ul> 934 * @see 935 */ 936 extern UINT32 LOS_CurTaskIDGet(VOID); 937 938 /** 939 * @ingroup los_task 940 * @brief Gets the maximum number of threads supported by the system. 941 * 942 * @par Description: 943 * This API is used to gets the maximum number of threads supported by the system. 944 * 945 * @attention 946 * <ul> 947 * <li> This interface should not be called before system initialized.</li> 948 * </ul> 949 * 950 * @retval None. 951 * @par Dependency: 952 * <ul><li>los_task.h: the header file that contains the API declaration.</li></ul> 953 * @see 954 */ 955 extern UINT32 LOS_GetSystemTaskMaximum(VOID); 956 957 /** 958 * @ingroup los_task 959 * @brief Obtain a task information structure. 960 * 961 * @par Description: 962 * This API is used to obtain a task information structure. 963 * 964 * @attention 965 * <ul> 966 * <li>One parameter of this interface is a pointer, it should be a correct value, otherwise, the system may be 967 * abnormal.</li> 968 * </ul> 969 * 970 * @param taskID [IN] Type #UINT32 Task ID. The task id value is obtained from task creation. 971 * @param taskInfo [OUT] Type #TSK_INFO_S* Pointer to the task information structure to be obtained. 972 * 973 * @retval #LOS_ERRNO_TSK_PTR_NULL Null parameter. 974 * @retval #LOS_ERRNO_TSK_ID_INVALID Invalid task ID. 975 * @retval #LOS_ERRNO_TSK_NOT_CREATED The task is not created. 976 * @retval #LOS_OK The task information structure is successfully obtained. 977 * @par Dependency: 978 * <ul><li>los_task.h: the header file that contains the API declaration.</li></ul> 979 * @see 980 */ 981 extern UINT32 LOS_TaskInfoGet(UINT32 taskID, TSK_INFO_S *taskInfo); 982 983 984 /** 985 * @ingroup los_task 986 * @brief Set the affinity mask of the task scheduling cpu. 987 * 988 * @par Description: 989 * This API is used to set the affinity mask of the task scheduling cpu. 990 * 991 * @attention 992 * <ul> 993 * <li>If any low LOSCFG_KERNEL_CORE_NUM bit of the mask is not set, an error is reported.</li> 994 * </ul> 995 * 996 * @param uwTaskID [IN] Type #UINT32 Task ID. The task id value is obtained from task creation. 997 * @param usCpuAffiMask [IN] Type #UINT32 The scheduling cpu mask.The low to high bit of the mask corresponds to 998 * the cpu number, the high bit that exceeding the CPU number is ignored. 999 * 1000 * @retval #LOS_ERRNO_TSK_ID_INVALID Invalid task ID. 1001 * @retval #LOS_ERRNO_TSK_NOT_CREATED The task is not created. 1002 * @retval #LOS_ERRNO_TSK_CPU_AFFINITY_MASK_ERR The task cpu affinity mask is incorrect. 1003 * @retval #LOS_OK The task cpu affinity mask is successfully set. 1004 * @par Dependency: 1005 * <ul><li>los_task.h: the header file that contains the API declaration.</li></ul> 1006 * @see LOS_TaskCpuAffiGet 1007 */ 1008 extern UINT32 LOS_TaskCpuAffiSet(UINT32 uwTaskID, UINT16 usCpuAffiMask); 1009 1010 /** 1011 * @ingroup los_task 1012 * @brief Get the affinity mask of the task scheduling cpu. 1013 * 1014 * @par Description: 1015 * This API is used to get the affinity mask of the task scheduling cpu. 1016 * 1017 * @attention None. 1018 * 1019 * @param taskID [IN] Type #UINT32 Task ID. The task id value is obtained from task creation. 1020 * 1021 * @retval #0 The cpu affinity mask fails to be obtained. 1022 * @retval #UINT16 The scheduling cpu mask. The low to high bit of the mask corresponds to the cpu number. 1023 * @par Dependency: 1024 * <ul><li>los_task.h: the header file that contains the API declaration.</li></ul> 1025 * @see LOS_TaskCpuAffiSet 1026 */ 1027 extern UINT16 LOS_TaskCpuAffiGet(UINT32 taskID); 1028 1029 /** 1030 * @ingroup los_task 1031 * @brief Get the scheduling policy for the task. 1032 * 1033 * @par Description: 1034 * This API is used to get the scheduling policy for the task. 1035 * 1036 * @attention None. 1037 * 1038 * @param taskID [IN] Type #UINT32 Task ID. The task id value is obtained from task creation. 1039 * 1040 * @retval #-LOS_ESRCH Invalid task id. 1041 * @retval #-LOS_EPERM The process is not currently running. 1042 * @retval #INT32 the scheduling policy. 1043 * @par Dependency: 1044 * <ul><li>los_task.h: the header file that contains the API declaration.</li></ul> 1045 * @see LOS_SetTaskScheduler 1046 */ 1047 extern INT32 LOS_GetTaskScheduler(INT32 taskID); 1048 1049 /** 1050 * @ingroup los_task 1051 * @brief Set the scheduling policy and priority for the task. 1052 * 1053 * @par Description: 1054 * This API is used to set the scheduling policy and priority for the task. 1055 * 1056 * @attention None. 1057 * 1058 * @param taskID [IN] Type #UINT32 Task ID. The task id value is obtained from task creation. 1059 * @param policy [IN] Type #UINT16 Task scheduling policy. 1060 * @param priority [IN] Type #UINT16 Task scheduling priority. 1061 * 1062 * @retval -LOS_ESRCH Invalid task id. 1063 * @retval -LOS_EOPNOTSUPP Unsupported fields. 1064 * @retval -LOS_EPERM The process is not currently running. 1065 * @retval #0 Set up the success. 1066 * @par Dependency: 1067 * <ul><li>los_task.h: the header file that contains the API declaration.</li></ul> 1068 * @see LOS_GetTaskScheduler 1069 */ 1070 extern INT32 LOS_SetTaskScheduler(INT32 taskID, UINT16 policy, UINT16 priority); 1071 1072 /** 1073 * @ingroup los_task 1074 * @brief Trigger active task scheduling. 1075 * 1076 * @par Description: 1077 * This API is used to trigger active task scheduling. 1078 * 1079 * @attention None. 1080 * 1081 * @param None 1082 * 1083 * @retval Nobe 1084 * @par Dependency: 1085 * <ul><li>los_task.h: the header file that contains the API declaration.</li></ul> 1086 */ 1087 extern VOID LOS_Schedule(VOID); 1088 1089 /** 1090 * @ingroup los_task 1091 * @brief Wait for the specified task to finish and reclaim its resources. 1092 * 1093 * @par Description: 1094 * This API is used to wait for the specified task to finish and reclaim its resources. 1095 * 1096 * @attention None. 1097 * 1098 * @param taskID [IN] task ID. 1099 * @param retval [OUT] wait for the return value of the task. 1100 * 1101 * @retval LOS_OK successful 1102 * @retval LOS_EINVAL Invalid parameter or invalid operation 1103 * @retval LOS_EINTR Disallow calls in interrupt handlers 1104 * @retval LOS_EPERM Waiting tasks and calling tasks do not belong to the same process 1105 * @retval LOS_EDEADLK The waiting task is the same as the calling task 1106 * @par Dependency: 1107 * <ul><li>los_task.h: the header file that contains the API declaration.</li></ul> 1108 */ 1109 extern UINT32 LOS_TaskJoin(UINT32 taskID, UINTPTR *retval); 1110 1111 /** 1112 * @ingroup los_task 1113 * @brief Change the joinable attribute of the task to detach. 1114 * 1115 * @par Description: 1116 * This API is used to change the joinable attribute of the task to detach. 1117 * 1118 * @attention None. 1119 * 1120 * @param taskID [IN] task ID. 1121 * 1122 * @retval LOS_OK successful 1123 * @retval LOS_EINVAL Invalid parameter or invalid operation 1124 * @retval LOS_EINTR Disallow calls in interrupt handlers 1125 * @retval LOS_EPERM Waiting tasks and calling tasks do not belong to the same process 1126 * @retval LOS_ESRCH Cannot modify the Joinable attribute of a task that is waiting for completion. 1127 * @par Dependency: 1128 * <ul><li>los_task.h: the header file that contains the API declaration.</li></ul> 1129 */ 1130 extern UINT32 LOS_TaskDetach(UINT32 taskID); 1131 1132 #ifdef __cplusplus 1133 #if __cplusplus 1134 } 1135 #endif /* __cplusplus */ 1136 #endif /* __cplusplus */ 1137 1138 #endif /* _LOS_TASK_H */ 1139