1 /* 2 * Copyright (c) 2013-2019 Huawei Technologies Co., Ltd. All rights reserved. 3 * Copyright (c) 2020-2021 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 UINT32 processID; 516 UserTaskParam userParam; 517 } TSK_INIT_PARAM_S; 518 519 /** 520 * @ingroup los_task 521 * Task name length 522 * 523 */ 524 #define LOS_TASK_NAMELEN 32 525 526 /** 527 * @ingroup los_task 528 * Task information structure. 529 * 530 */ 531 typedef struct tagTskInfo { 532 CHAR acName[LOS_TASK_NAMELEN]; /**< Task entrance function */ 533 UINT32 uwTaskID; /**< Task ID */ 534 UINT16 usTaskStatus; /**< Task status */ 535 UINT16 usTaskPrio; /**< Task priority */ 536 VOID *pTaskSem; /**< Semaphore pointer */ 537 VOID *pTaskMux; /**< Mutex pointer */ 538 VOID *taskEvent; /**< Event */ 539 UINT32 uwEventMask; /**< Event mask */ 540 UINT32 uwStackSize; /**< Task stack size */ 541 UINTPTR uwTopOfStack; /**< Task stack top */ 542 UINTPTR uwBottomOfStack; /**< Task stack bottom */ 543 UINTPTR uwSP; /**< Task SP pointer */ 544 UINT32 uwCurrUsed; /**< Current task stack usage */ 545 UINT32 uwPeakUsed; /**< Task stack usage peak */ 546 BOOL bOvf; /**< Flag that indicates whether a task stack overflow occurs */ 547 } TSK_INFO_S; 548 549 /** 550 * @ingroup los_task 551 * @brief Create a task and suspend. 552 * 553 * @par Description: 554 * This API is used to create a task and suspend it. This task will not be added to the queue of ready tasks 555 * before resume it. 556 * 557 * @attention 558 * <ul> 559 * <li>During task creation, the task control block and task stack of the task that is previously automatically deleted 560 * are deallocated.</li> 561 * <li>The task name is a pointer and is not allocated memory.</li> 562 * <li>If the size of the task stack of the task to be created is 0, configure #LOSCFG_BASE_CORE_TSK_DEFAULT_STACK_SIZE 563 * to specify the default task stack size. The stack size should be a reasonable value, if the size is too large, may 564 * cause memory exhaustion.</li> 565 * <li>The task stack size must be aligned on the boundary of 8 bytes. The size is determined by whether it is big 566 * enough to avoid task stack overflow.</li> 567 * <li>Less parameter value indicates higher task priority.</li> 568 * <li>The task name cannot be null.</li> 569 * <li>The pointer to the task executing function cannot be null.</li> 570 * <li>The two parameters of this interface is pointer, it should be a correct value, otherwise, the system may be 571 * abnormal.</li> 572 * </ul> 573 * 574 * @param taskID [OUT] Type #UINT32 * Task ID. 575 * @param initParam [IN] Type #TSK_INIT_PARAM_S * Parameter for task creation. 576 * 577 * @retval #LOS_ERRNO_TSK_ID_INVALID Invalid Task ID, param taskID is NULL. 578 * @retval #LOS_ERRNO_TSK_PTR_NULL Param initParam is NULL. 579 * @retval #LOS_ERRNO_TSK_NAME_EMPTY The task name is NULL. 580 * @retval #LOS_ERRNO_TSK_ENTRY_NULL The task entrance is NULL. 581 * @retval #LOS_ERRNO_TSK_PRIOR_ERROR Incorrect task priority. 582 * @retval #LOS_ERRNO_TSK_STKSZ_TOO_LARGE The task stack size is too large. 583 * @retval #LOS_ERRNO_TSK_STKSZ_TOO_SMALL The task stack size is too small. 584 * @retval #LOS_ERRNO_TSK_TCB_UNAVAILABLE No free task control block is available. 585 * @retval #LOS_ERRNO_TSK_NO_MEMORY Insufficient memory for task creation. 586 * @retval #LOS_OK The task is successfully created. 587 * @par Dependency: 588 * <ul><li>los_task.h: the header file that contains the API declaration.</li></ul> 589 * <ul><li>los_config.h: the header file that contains system configuration items.</li></ul> 590 * @see LOS_TaskDelete 591 */ 592 extern UINT32 LOS_TaskCreateOnly(UINT32 *taskID, TSK_INIT_PARAM_S *initParam); 593 594 /** 595 * @ingroup los_task 596 * @brief Create a task. 597 * 598 * @par Description: 599 * This API is used to create a task. If the priority of the task created after system initialized is higher than 600 * the current task and task scheduling is not locked, it is scheduled for running. 601 * If not, the created task is added to the queue of ready tasks. 602 * 603 * @attention 604 * <ul> 605 * <li>During task creation, the task control block and task stack of the task that is previously automatically 606 * deleted are deallocated.</li> 607 * <li>The task name is a pointer and is not allocated memory.</li> 608 * <li>If the size of the task stack of the task to be created is 0, configure #LOSCFG_BASE_CORE_TSK_DEFAULT_STACK_SIZE 609 * to specify the default task stack size.</li> 610 * <li>The task stack size must be aligned on the boundary of 8 bytes. The size is determined by whether it is big 611 * enough to avoid task stack overflow.</li> 612 * <li>Less parameter value indicates higher task priority.</li> 613 * <li>The task name cannot be null.</li> 614 * <li>The pointer to the task executing function cannot be null.</li> 615 * <li>The two parameters of this interface is pointer, it should be a correct value, otherwise, the system may be 616 * abnormal.</li> 617 * </ul> 618 * 619 * @param taskID [OUT] Type #UINT32 * Task ID. 620 * @param initParam [IN] Type #TSK_INIT_PARAM_S * Parameter for task creation. 621 * 622 * @retval #LOS_ERRNO_TSK_ID_INVALID Invalid Task ID, param taskID is NULL. 623 * @retval #LOS_ERRNO_TSK_PTR_NULL Param initParam is NULL. 624 * @retval #LOS_ERRNO_TSK_NAME_EMPTY The task name is NULL. 625 * @retval #LOS_ERRNO_TSK_ENTRY_NULL The task entrance is NULL. 626 * @retval #LOS_ERRNO_TSK_PRIOR_ERROR Incorrect task priority. 627 * @retval #LOS_ERRNO_TSK_STKSZ_TOO_LARGE The task stack size is too large. 628 * @retval #LOS_ERRNO_TSK_STKSZ_TOO_SMALL The task stack size is too small. 629 * @retval #LOS_ERRNO_TSK_TCB_UNAVAILABLE No free task control block is available. 630 * @retval #LOS_ERRNO_TSK_NO_MEMORY Insufficient memory for task creation. 631 * @retval #LOS_OK The task is successfully created. 632 * @par Dependency: 633 * <ul><li>los_task.h: the header file that contains the API declaration.</li></ul> 634 * <ul><li>los_config.h: the header file that contains system configuration items.</li></ul> 635 * @see LOS_TaskDelete 636 */ 637 extern UINT32 LOS_TaskCreate(UINT32 *taskID, TSK_INIT_PARAM_S *initParam); 638 639 /** 640 * @ingroup los_task 641 * @brief Resume a task. 642 * 643 * @par Description: 644 * This API is used to resume a suspended task. 645 * 646 * @attention 647 * <ul> 648 * <li>If the task is delayed or blocked, resume the task without adding it to the queue of ready tasks.</li> 649 * <li>If the priority of the task resumed after system initialized is higher than the current task and task scheduling 650 * is not locked, it is scheduled for running.</li> 651 * </ul> 652 * 653 * @param taskID [IN] Type #UINT32 Task ID. The task id value is obtained from task creation. 654 * 655 * @retval #LOS_ERRNO_TSK_ID_INVALID Invalid Task ID 656 * @retval #LOS_ERRNO_TSK_NOT_CREATED The task is not created. 657 * @retval #LOS_ERRNO_TSK_NOT_SUSPENDED The task is not suspended. 658 * @retval #LOS_OK The task is successfully resumed. 659 * @par Dependency: 660 * <ul><li>los_task.h: the header file that contains the API declaration.</li></ul> 661 * @see LOS_TaskSuspend 662 */ 663 extern UINT32 LOS_TaskResume(UINT32 taskID); 664 665 /** 666 * @ingroup los_task 667 * @brief Suspend a task. 668 * 669 * @par Description: 670 * This API is used to suspend a specified task, and the task will be removed from the queue of ready tasks. 671 * 672 * @attention 673 * <ul> 674 * <li>The task that is running and locked cannot be suspended.</li> 675 * <li>The idle task and swtmr task cannot be suspended.</li> 676 * </ul> 677 * 678 * @param taskID [IN] Type #UINT32 Task ID. The task id value is obtained from task creation. 679 * 680 * @retval #LOS_ERRNO_TSK_OPERATE_IDLE Check the task ID and do not operate on the idle task. 681 * @retval #LOS_ERRNO_TSK_SUSPEND_SWTMR_NOT_ALLOWED Check the task ID and do not operate on the swtmr task. 682 * @retval #LOS_ERRNO_TSK_ID_INVALID Invalid Task ID 683 * @retval #LOS_ERRNO_TSK_NOT_CREATED The task is not created. 684 * @retval #LOS_ERRNO_TSK_ALREADY_SUSPENDED The task is already suspended. 685 * @retval #LOS_ERRNO_TSK_SUSPEND_LOCKED The task being suspended is current task and task scheduling 686 * is locked. 687 * @retval #LOS_OK The task is successfully suspended. 688 * @par Dependency: 689 * <ul><li>los_task.h: the header file that contains the API declaration.</li></ul> 690 * @see LOS_TaskResume 691 */ 692 extern UINT32 LOS_TaskSuspend(UINT32 taskID); 693 694 /** 695 * @ingroup los_task 696 * @brief Delete a task. 697 * 698 * @par Description: 699 * This API is used to delete a specified task and release the resources for its task stack and task control block. 700 * 701 * @attention 702 * <ul> 703 * <li>The idle task and swtmr task cannot be deleted.</li> 704 * <li>If delete current task maybe cause unexpected error.</li> 705 * <li>If a task get a mutex is deleted or automatically deleted before release this mutex, other tasks pended 706 * this mutex maybe never be shchduled.</li> 707 * </ul> 708 * 709 * @param taskID [IN] Type #UINT32 Task ID. The task id value is obtained from task creation. 710 * 711 * @retval #LOS_ERRNO_TSK_OPERATE_IDLE Check the task ID and do not operate on the idle task. 712 * @retval #LOS_ERRNO_TSK_SUSPEND_SWTMR_NOT_ALLOWED Check the task ID and do not operate on the swtmr task. 713 * @retval #LOS_ERRNO_TSK_ID_INVALID Invalid Task ID 714 * @retval #LOS_ERRNO_TSK_NOT_CREATED The task is not created. 715 * @retval #LOS_ERRNO_TSK_DELETE_LOCKED The task being deleted is current task and task scheduling 716 * is locked. 717 * @retval #LOS_OK The task is successfully deleted. 718 * @par Dependency: 719 * <ul><li>los_task.h: the header file that contains the API declaration.</li></ul> 720 * @see LOS_TaskCreate | LOS_TaskCreateOnly 721 */ 722 extern UINT32 LOS_TaskDelete(UINT32 taskID); 723 724 /** 725 * @ingroup los_task 726 * @brief Delay a task. 727 * 728 * @par Description: 729 * This API is used to delay the execution of the current task. The task is able to be scheduled after it is delayed 730 * for a specified number of Ticks. 731 * 732 * @attention 733 * <ul> 734 * <li>The task fails to be delayed if it is being delayed during interrupt processing or it is locked.</li> 735 * <li>If 0 is passed in and the task scheduling is not locked, execute the next task in the queue of tasks with 736 * the same priority of the current task. 737 * If no ready task with the priority of the current task is available, the task scheduling will not occur, and the 738 * current task continues to be executed.</li> 739 * <li>Using the interface before system initialized is not allowed.</li> 740 * <li>DO NOT call this API in software timer callback. </li> 741 * </ul> 742 * 743 * @param tick [IN] Type #UINT32 Number of Ticks for which the task is delayed. 744 * 745 * @retval #LOS_ERRNO_TSK_DELAY_IN_INT The task delay occurs during an interrupt. 746 * @retval #LOS_ERRNO_TSK_DELAY_IN_LOCK The task delay occurs when the task scheduling is locked. 747 * @retval #LOS_ERRNO_TSK_ID_INVALID Invalid Task ID 748 * @retval #LOS_ERRNO_TSK_YIELD_NOT_ENOUGH_TASK No tasks with the same priority is available for scheduling. 749 * @retval #LOS_OK The task is successfully delayed. 750 * @par Dependency: 751 * <ul><li>los_task.h: the header file that contains the API declaration.</li></ul> 752 * @see 753 */ 754 extern UINT32 LOS_TaskDelay(UINT32 tick); 755 756 /** 757 * @ingroup los_task 758 * @brief Lock the task scheduling. 759 * 760 * @par Description: 761 * This API is used to lock the task scheduling. Task switching will not occur if the task scheduling is locked. 762 * 763 * @attention 764 * <ul> 765 * <li>If the task scheduling is locked, but interrupts are not disabled, tasks are still able to be interrupted.</li> 766 * <li>One is added to the number of task scheduling locks if this API is called. The number of locks is decreased by 767 * one if the task scheduling is unlocked. Therefore, this API should be used together with LOS_TaskUnlock.</li> 768 * </ul> 769 * 770 * @param None. 771 * 772 * @retval None. 773 * @par Dependency: 774 * <ul><li>los_task.h: the header file that contains the API declaration.</li></ul> 775 * @see LOS_TaskUnlock 776 */ 777 extern VOID LOS_TaskLock(VOID); 778 779 /** 780 * @ingroup los_task 781 * @brief Unlock the task scheduling. 782 * 783 * @par Description: 784 * This API is used to unlock the task scheduling. Calling this API will decrease the number of task locks by one. 785 * If a task is locked more than once, the task scheduling will be unlocked only when the number of locks becomes zero. 786 * 787 * @attention 788 * <ul> 789 * <li>The number of locks is decreased by one if this API is called. One is added to the number of task scheduling 790 * locks if the task scheduling is locked. Therefore, this API should be used together with LOS_TaskLock.</li> 791 * </ul> 792 * 793 * @param None. 794 * 795 * @retval None. 796 * @par Dependency: 797 * <ul><li>los_task.h: the header file that contains the API declaration.</li></ul> 798 * @see LOS_TaskLock 799 */ 800 extern VOID LOS_TaskUnlock(VOID); 801 802 /** 803 * @ingroup los_task 804 * @brief Set a task priority. 805 * 806 * @par Description: 807 * This API is used to set the priority of a specified task. 808 * 809 * @attention 810 * <ul> 811 * <li>If the set priority is higher than the priority of the current running task, task scheduling 812 * probably occurs.</li> 813 * <li>Changing the priority of the current running task also probably causes task scheduling.</li> 814 * <li>Using the interface to change the priority of software timer task and idle task is not allowed.</li> 815 * <li>Using the interface in the interrupt is not allowed.</li> 816 * </ul> 817 * 818 * @param taskID [IN] Type #UINT32 Task ID. The task id value is obtained from task creation. 819 * @param taskPrio [IN] Type #UINT16 Task priority. 820 * 821 * @retval #LOS_ERRNO_TSK_PRIOR_ERROR Incorrect task priority.Re-configure the task priority 822 * @retval #LOS_ERRNO_TSK_OPERATE_IDLE Check the task ID and do not operate on the idle task. 823 * @retval #LOS_ERRNO_TSK_ID_INVALID Invalid Task ID 824 * @retval #LOS_ERRNO_TSK_NOT_CREATED The task is not created. 825 * @retval #LOS_OK The task priority is successfully set to a specified priority. 826 * @par Dependency: 827 * <ul><li>los_task.h: the header file that contains the API declaration.</li></ul> 828 * @see LOS_TaskPriSet 829 */ 830 extern UINT32 LOS_TaskPriSet(UINT32 taskID, UINT16 taskPrio); 831 832 /** 833 * @ingroup los_task 834 * @brief Set the priority of the current running task to a specified priority. 835 * 836 * @par Description: 837 * This API is used to set the priority of the current running task to a specified priority. 838 * 839 * @attention 840 * <ul> 841 * <li>Changing the priority of the current running task probably causes task scheduling.</li> 842 * <li>Using the interface to change the priority of software timer task and idle task is not allowed.</li> 843 * <li>Using the interface in the interrupt is not allowed.</li> 844 * </ul> 845 * 846 * @param taskPrio [IN] Type #UINT16 Task priority. 847 * 848 * @retval #LOS_ERRNO_TSK_PRIOR_ERROR Incorrect task priority.Re-configure the task priority 849 * @retval #LOS_ERRNO_TSK_OPERATE_IDLE Check the task ID and do not operate on the idle task. 850 * @retval #LOS_ERRNO_TSK_ID_INVALID Invalid Task ID 851 * @retval #LOS_ERRNO_TSK_NOT_CREATED The task is not created. 852 * @retval #LOS_OK The priority of the current running task is successfully set to a specified 853 * priority. 854 * @par Dependency: 855 * <ul><li>los_task.h: the header file that contains the API declaration.</li></ul> 856 * @see LOS_TaskPriGet 857 */ 858 extern UINT32 LOS_CurTaskPriSet(UINT16 taskPrio); 859 860 /** 861 * @ingroup los_task 862 * @brief Change the scheduling sequence of tasks with the same priority. 863 * 864 * @par Description: 865 * 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 866 * tasks. 867 * 868 * @attention 869 * <ul> 870 * <li>At least two ready tasks need to be included in the queue of ready tasks with the same priority. If the 871 * less than two ready tasks are included in the queue, an error is reported.</li> 872 * </ul> 873 * 874 * @param None. 875 * 876 * @retval #LOS_ERRNO_TSK_ID_INVALID Invalid Task ID 877 * @retval #LOS_ERRNO_TSK_YIELD_NOT_ENOUGH_TASK No tasks with the same priority is available for scheduling. 878 * @retval #LOS_OK The scheduling sequence of tasks with same priority is 879 * successfully changed. 880 * @par Dependency: 881 * <ul><li>los_task.h: the header file that contains the API declaration.</li></ul> 882 * @see 883 */ 884 extern UINT32 LOS_TaskYield(VOID); 885 886 /** 887 * @ingroup los_task 888 * @brief Obtain a task priority. 889 * 890 * @par Description: 891 * This API is used to obtain the priority of a specified task. 892 * 893 * @attention None. 894 * 895 * @param taskID [IN] Type #UINT32 Task ID. The task id value is obtained from task creation. 896 * 897 * @retval #OS_INVALID The task priority fails to be obtained. 898 * @retval #UINT16 The task priority. 899 * @par Dependency: 900 * <ul><li>los_task.h: the header file that contains the API declaration.</li></ul> 901 * @see LOS_TaskPriSet 902 */ 903 extern UINT16 LOS_TaskPriGet(UINT32 taskID); 904 905 /** 906 * @ingroup los_task 907 * @brief Obtain current running task ID. 908 * 909 * @par Description: 910 * This API is used to obtain the ID of current running task. 911 * 912 * @attention 913 * <ul> 914 * <li> This interface should not be called before system initialized.</li> 915 * </ul> 916 * 917 * @retval #LOS_ERRNO_TSK_ID_INVALID Invalid Task ID. 918 * @retval #UINT32 Task ID. 919 * @par Dependency: 920 * <ul><li>los_task.h: the header file that contains the API declaration.</li></ul> 921 * @see 922 */ 923 extern UINT32 LOS_CurTaskIDGet(VOID); 924 925 /** 926 * @ingroup los_task 927 * @brief Gets the maximum number of threads supported by the system. 928 * 929 * @par Description: 930 * This API is used to gets the maximum number of threads supported by the system. 931 * 932 * @attention 933 * <ul> 934 * <li> This interface should not be called before system initialized.</li> 935 * </ul> 936 * 937 * @retval None. 938 * @par Dependency: 939 * <ul><li>los_task.h: the header file that contains the API declaration.</li></ul> 940 * @see 941 */ 942 extern UINT32 LOS_GetSystemTaskMaximum(VOID); 943 944 /** 945 * @ingroup los_task 946 * @brief Obtain a task information structure. 947 * 948 * @par Description: 949 * This API is used to obtain a task information structure. 950 * 951 * @attention 952 * <ul> 953 * <li>One parameter of this interface is a pointer, it should be a correct value, otherwise, the system may be 954 * abnormal.</li> 955 * </ul> 956 * 957 * @param taskID [IN] Type #UINT32 Task ID. The task id value is obtained from task creation. 958 * @param taskInfo [OUT] Type #TSK_INFO_S* Pointer to the task information structure to be obtained. 959 * 960 * @retval #LOS_ERRNO_TSK_PTR_NULL Null parameter. 961 * @retval #LOS_ERRNO_TSK_ID_INVALID Invalid task ID. 962 * @retval #LOS_ERRNO_TSK_NOT_CREATED The task is not created. 963 * @retval #LOS_OK The task information structure is successfully obtained. 964 * @par Dependency: 965 * <ul><li>los_task.h: the header file that contains the API declaration.</li></ul> 966 * @see 967 */ 968 extern UINT32 LOS_TaskInfoGet(UINT32 taskID, TSK_INFO_S *taskInfo); 969 970 971 /** 972 * @ingroup los_task 973 * @brief Set the affinity mask of the task scheduling cpu. 974 * 975 * @par Description: 976 * This API is used to set the affinity mask of the task scheduling cpu. 977 * 978 * @attention 979 * <ul> 980 * <li>If any low LOSCFG_KERNEL_CORE_NUM bit of the mask is not set, an error is reported.</li> 981 * </ul> 982 * 983 * @param uwTaskID [IN] Type #UINT32 Task ID. The task id value is obtained from task creation. 984 * @param usCpuAffiMask [IN] Type #UINT32 The scheduling cpu mask.The low to high bit of the mask corresponds to 985 * the cpu number, the high bit that exceeding the CPU number is ignored. 986 * 987 * @retval #LOS_ERRNO_TSK_ID_INVALID Invalid task ID. 988 * @retval #LOS_ERRNO_TSK_NOT_CREATED The task is not created. 989 * @retval #LOS_ERRNO_TSK_CPU_AFFINITY_MASK_ERR The task cpu affinity mask is incorrect. 990 * @retval #LOS_OK The task cpu affinity mask is successfully set. 991 * @par Dependency: 992 * <ul><li>los_task.h: the header file that contains the API declaration.</li></ul> 993 * @see LOS_TaskCpuAffiGet 994 */ 995 extern UINT32 LOS_TaskCpuAffiSet(UINT32 uwTaskID, UINT16 usCpuAffiMask); 996 997 /** 998 * @ingroup los_task 999 * @brief Get the affinity mask of the task scheduling cpu. 1000 * 1001 * @par Description: 1002 * This API is used to get the affinity mask of the task scheduling cpu. 1003 * 1004 * @attention None. 1005 * 1006 * @param taskID [IN] Type #UINT32 Task ID. The task id value is obtained from task creation. 1007 * 1008 * @retval #0 The cpu affinity mask fails to be obtained. 1009 * @retval #UINT16 The scheduling cpu mask. The low to high bit of the mask corresponds to the cpu number. 1010 * @par Dependency: 1011 * <ul><li>los_task.h: the header file that contains the API declaration.</li></ul> 1012 * @see LOS_TaskCpuAffiSet 1013 */ 1014 extern UINT16 LOS_TaskCpuAffiGet(UINT32 taskID); 1015 1016 /** 1017 * @ingroup los_task 1018 * @brief Get the scheduling policy for the task. 1019 * 1020 * @par Description: 1021 * This API is used to get the scheduling policy for the task. 1022 * 1023 * @attention None. 1024 * 1025 * @param taskID [IN] Type #UINT32 Task ID. The task id value is obtained from task creation. 1026 * 1027 * @retval #-LOS_ESRCH Invalid task id. 1028 * @retval #-LOS_EPERM The process is not currently running. 1029 * @retval #INT32 the scheduling policy. 1030 * @par Dependency: 1031 * <ul><li>los_task.h: the header file that contains the API declaration.</li></ul> 1032 * @see LOS_SetTaskScheduler 1033 */ 1034 extern INT32 LOS_GetTaskScheduler(INT32 taskID); 1035 1036 /** 1037 * @ingroup los_task 1038 * @brief Set the scheduling policy and priority for the task. 1039 * 1040 * @par Description: 1041 * This API is used to set the scheduling policy and priority for the task. 1042 * 1043 * @attention None. 1044 * 1045 * @param taskID [IN] Type #UINT32 Task ID. The task id value is obtained from task creation. 1046 * @param policy [IN] Type #UINT16 Task scheduling policy. 1047 * @param priority [IN] Type #UINT16 Task scheduling priority. 1048 * 1049 * @retval -LOS_ESRCH Invalid task id. 1050 * @retval -LOS_EOPNOTSUPP Unsupported fields. 1051 * @retval -LOS_EPERM The process is not currently running. 1052 * @retval #0 Set up the success. 1053 * @par Dependency: 1054 * <ul><li>los_task.h: the header file that contains the API declaration.</li></ul> 1055 * @see LOS_GetTaskScheduler 1056 */ 1057 extern INT32 LOS_SetTaskScheduler(INT32 taskID, UINT16 policy, UINT16 priority); 1058 1059 /** 1060 * @ingroup los_task 1061 * @brief Trigger active task scheduling. 1062 * 1063 * @par Description: 1064 * This API is used to trigger active task scheduling. 1065 * 1066 * @attention None. 1067 * 1068 * @param None 1069 * 1070 * @retval Nobe 1071 * @par Dependency: 1072 * <ul><li>los_task.h: the header file that contains the API declaration.</li></ul> 1073 */ 1074 extern VOID LOS_Schedule(VOID); 1075 1076 /** 1077 * @ingroup los_task 1078 * @brief Wait for the specified task to finish and reclaim its resources. 1079 * 1080 * @par Description: 1081 * This API is used to wait for the specified task to finish and reclaim its resources. 1082 * 1083 * @attention None. 1084 * 1085 * @param taskID [IN] task ID. 1086 * @param retval [OUT] wait for the return value of the task. 1087 * 1088 * @retval LOS_OK successful 1089 * @retval LOS_EINVAL Invalid parameter or invalid operation 1090 * @retval LOS_EINTR Disallow calls in interrupt handlers 1091 * @retval LOS_EPERM Waiting tasks and calling tasks do not belong to the same process 1092 * @retval LOS_EDEADLK The waiting task is the same as the calling task 1093 * @par Dependency: 1094 * <ul><li>los_task.h: the header file that contains the API declaration.</li></ul> 1095 */ 1096 extern UINT32 LOS_TaskJoin(UINT32 taskID, UINTPTR *retval); 1097 1098 /** 1099 * @ingroup los_task 1100 * @brief Change the joinable attribute of the task to detach. 1101 * 1102 * @par Description: 1103 * This API is used to change the joinable attribute of the task to detach. 1104 * 1105 * @attention None. 1106 * 1107 * @param taskID [IN] task ID. 1108 * 1109 * @retval LOS_OK successful 1110 * @retval LOS_EINVAL Invalid parameter or invalid operation 1111 * @retval LOS_EINTR Disallow calls in interrupt handlers 1112 * @retval LOS_EPERM Waiting tasks and calling tasks do not belong to the same process 1113 * @retval LOS_ESRCH Cannot modify the Joinable attribute of a task that is waiting for completion. 1114 * @par Dependency: 1115 * <ul><li>los_task.h: the header file that contains the API declaration.</li></ul> 1116 */ 1117 extern UINT32 LOS_TaskDetach(UINT32 taskID); 1118 1119 #ifdef __cplusplus 1120 #if __cplusplus 1121 } 1122 #endif /* __cplusplus */ 1123 #endif /* __cplusplus */ 1124 1125 #endif /* _LOS_TASK_H */ 1126