diff options
Diffstat (limited to '')
| -rw-r--r-- | cpukit/include/rtems/rtems/tasks.h | 145 |
1 files changed, 84 insertions, 61 deletions
diff --git a/cpukit/include/rtems/rtems/tasks.h b/cpukit/include/rtems/rtems/tasks.h index 81757db8c7..84dd646fe7 100644 --- a/cpukit/include/rtems/rtems/tasks.h +++ b/cpukit/include/rtems/rtems/tasks.h @@ -9,8 +9,8 @@ */ /* - * Copyright (C) 2020, 2021 embedded brains GmbH (http://www.embedded-brains.de) - * Copyright (C) 1988, 2017 On-Line Applications Research Corporation (OAR) + * Copyright (C) 2020, 2021 embedded brains GmbH & Co. KG + * Copyright (C) 1988, 2023 On-Line Applications Research Corporation (OAR) * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions @@ -160,8 +160,8 @@ typedef struct { * alignment of an application executable. * * The application may configure the maximum thread-local storage size for all - * threads explicitly through the #CONFIGURE_MAXIMUM_THREAD_LOCAL_STORAGE_SIZE - * configuration option. + * threads explicitly through the @ref + * CONFIGURE_MAXIMUM_THREAD_LOCAL_STORAGE_SIZE configuration option. */ size_t maximum_thread_local_storage_size; @@ -234,7 +234,7 @@ typedef void rtems_task; /** * @ingroup RTEMSAPIClassicTasks * - * @brief This type defines the entry point of an RTEMS task. + * @brief This type defines the task entry point of an RTEMS task. */ typedef rtems_task ( *rtems_task_entry )( rtems_task_argument ); @@ -283,6 +283,25 @@ typedef struct { rtems_task_argument argument; } rtems_initialization_tasks_table; +/* Generated from spec:/rtems/task/if/maximum-priority-impl */ + +/** + * @ingroup RTEMSImplClassicTask + * + * @brief Returns the maximum priority of the scheduler with index zero. + */ +rtems_task_priority _RTEMS_Maximum_priority( void ); + +/* Generated from spec:/rtems/task/if/maximum-priority */ + +/** + * @ingroup RTEMSAPIClassicTasks + * + * @brief This runtime constant represents the lowest (least important) task + * priority of the scheduler with index zero. + */ +#define RTEMS_MAXIMUM_PRIORITY _RTEMS_Maximum_priority() + /* Generated from spec:/rtems/task/if/minimum-priority */ /** @@ -306,8 +325,8 @@ typedef struct { * risk of blown stacks for most user applications. Using this constant when * specifying the task stack size, indicates that the stack size will be at * least RTEMS_MINIMUM_STACK_SIZE bytes in size. If the user configured - * minimum stack size (see #CONFIGURE_MINIMUM_TASK_STACK_SIZE) is larger than - * the recommended minimum, then it will be used. + * minimum stack size (see @ref CONFIGURE_MINIMUM_TASK_STACK_SIZE) is larger + * than the recommended minimum, then it will be used. */ #define RTEMS_MINIMUM_STACK_SIZE STACK_MINIMUM_SIZE @@ -401,23 +420,6 @@ typedef bool( *rtems_task_visitor )( rtems_tcb *, void * ); */ #define RTEMS_YIELD_PROCESSOR WATCHDOG_NO_TIMEOUT -/* Generated from spec:/score/if/maximum-priority */ - -/** - * @brief Returns the maximum priority of the scheduler with index zero. - */ -rtems_task_priority _RTEMS_Maximum_priority( void ); - -/* Generated from spec:/rtems/task/if/maximum-priority */ - -/** - * @ingroup RTEMSAPIClassicTasks - * - * @brief This constant variable provides the lowest (least important) task - * priority of the first configured scheduler. - */ -#define RTEMS_MAXIMUM_PRIORITY _RTEMS_Maximum_priority() - /* Generated from spec:/rtems/task/if/create */ /** @@ -452,8 +454,8 @@ rtems_task_priority _RTEMS_Maximum_priority( void ); * The **stack size** of the task is specified in ``stack_size``. If the * requested stack size is less than the configured minimum stack size, then * RTEMS will use the configured minimum as the stack size for this task. The - * configured minimum stack size is defined by the - * #CONFIGURE_MINIMUM_TASK_STACK_SIZE application configuration option. In + * configured minimum stack size is defined by the @ref + * CONFIGURE_MINIMUM_TASK_STACK_SIZE application configuration option. In * addition to being able to specify the task stack size as a integer, there * are two constants which may be specified: * @@ -581,12 +583,12 @@ rtems_task_priority _RTEMS_Maximum_priority( void ); * * @retval ::RTEMS_TOO_MANY There was no inactive object available to create a * task. The number of tasks available to the application is configured - * through the #CONFIGURE_MAXIMUM_TASKS application configuration option. + * through the @ref CONFIGURE_MAXIMUM_TASKS application configuration option. * * @retval ::RTEMS_TOO_MANY In multiprocessing configurations, there was no * inactive global object available to create a global task. The number of - * global objects available to the application is configured through the - * #CONFIGURE_MP_MAXIMUM_GLOBAL_OBJECTS application configuration option. + * global objects available to the application is configured through the @ref + * CONFIGURE_MP_MAXIMUM_GLOBAL_OBJECTS application configuration option. * * @retval ::RTEMS_UNSATISFIED There was not enough memory to allocate the task * storage area. The task storage area contains the task stack, the @@ -613,7 +615,7 @@ rtems_task_priority _RTEMS_Maximum_priority( void ); * The task stack size shall account for an target processor dependent * interrupt stack frame which may be placed on the stack of the interrupted * task while servicing an interrupt. The stack checker may be used to monitor - * the stack usage, see #CONFIGURE_STACK_CHECKER_ENABLED. + * the stack usage, see @ref CONFIGURE_STACK_CHECKER_ENABLED. * * For control and maintenance of the task, RTEMS allocates a TCB from the * local TCB free pool and initializes it. @@ -642,15 +644,15 @@ rtems_task_priority _RTEMS_Maximum_priority( void ); * message to remote nodes. This may preempt the calling task. * * * The number of tasks available to the application is configured through the - * #CONFIGURE_MAXIMUM_TASKS application configuration option. + * @ref CONFIGURE_MAXIMUM_TASKS application configuration option. * * * Where the object class corresponding to the directive is configured to use * unlimited objects, the directive may allocate memory from the RTEMS * Workspace. * * * The number of global objects available to the application is configured - * through the #CONFIGURE_MP_MAXIMUM_GLOBAL_OBJECTS application configuration - * option. + * through the @ref CONFIGURE_MP_MAXIMUM_GLOBAL_OBJECTS application + * configuration option. * @endparblock */ rtems_status_code rtems_task_create( @@ -669,7 +671,8 @@ rtems_status_code rtems_task_create( * * @brief Constructs a task from the specified task configuration. * - * @param config is the task configuration. + * @param config is the pointer to an rtems_task_config object. It configures + * the task. * * @param[out] id is the pointer to an ::rtems_id object. When the directive * call is successful, the identifier of the constructed task will be stored @@ -688,12 +691,13 @@ rtems_status_code rtems_task_create( * @retval ::RTEMS_INVALID_SIZE The thread-local storage size is greater than * the maximum thread-local storage size specified in the task configuration. * The thread-local storage size is determined by the thread-local variables - * used by the application and #CONFIGURE_MAXIMUM_THREAD_LOCAL_STORAGE_SIZE. + * used by the application and @ref + * CONFIGURE_MAXIMUM_THREAD_LOCAL_STORAGE_SIZE. * * @retval ::RTEMS_INVALID_SIZE The task storage area was too small to provide - * a task stack of the configured minimum size, see - * #CONFIGURE_MINIMUM_TASK_STACK_SIZE. The task storage area contains the - * task stack, the thread-local storage, and the floating-point context on + * a task stack of the configured minimum size, see @ref + * CONFIGURE_MINIMUM_TASK_STACK_SIZE. The task storage area contains the task + * stack, the thread-local storage, and the floating-point context on * architectures with a separate floating-point context. * * @retval ::RTEMS_TOO_MANY There was no inactive task object available to @@ -732,13 +736,13 @@ rtems_status_code rtems_task_create( * memory allocators. This can simplify the application architecture as well * as any analysis that may be required. * - * The stack space estimate done by <rtems/confdefs.h> assumes that all tasks - * are created by rtems_task_create(). The estimate can be adjusted to take - * user-provided task storage areas into account through the - * #CONFIGURE_MINIMUM_TASKS_WITH_USER_PROVIDED_STORAGE application - * configuration option. + * The stack space estimate done by ``<rtems/confdefs.h>`` assumes that all + * tasks are created by rtems_task_create(). The estimate can be adjusted to + * take user-provided task storage areas into account through the @ref + * CONFIGURE_MINIMUM_TASKS_WITH_USER_PROVIDED_STORAGE application configuration + * option. * - * The #CONFIGURE_MAXIMUM_TASKS should include tasks constructed by + * The @ref CONFIGURE_MAXIMUM_TASKS should include tasks constructed by * rtems_task_construct(). * @endparblock * @@ -758,15 +762,15 @@ rtems_status_code rtems_task_create( * message to remote nodes. This may preempt the calling task. * * * The number of tasks available to the application is configured through the - * #CONFIGURE_MAXIMUM_TASKS application configuration option. + * @ref CONFIGURE_MAXIMUM_TASKS application configuration option. * * * Where the object class corresponding to the directive is configured to use * unlimited objects, the directive may allocate memory from the RTEMS * Workspace. * * * The number of global objects available to the application is configured - * through the #CONFIGURE_MP_MAXIMUM_GLOBAL_OBJECTS application configuration - * option. + * through the @ref CONFIGURE_MP_MAXIMUM_GLOBAL_OBJECTS application + * configuration option. * @endparblock */ rtems_status_code rtems_task_construct( @@ -893,8 +897,8 @@ rtems_id rtems_task_self( void ); * * This directive readies the task, specified by ``id``, for execution based on * the priority and execution mode specified when the task was created. The - * entry point of the task is given in ``entry_point``. The task's entry point - * argument is contained in ``argument``. + * task entry point of the task is given in ``entry_point``. The task's entry + * point argument is contained in ``argument``. * * @retval ::RTEMS_SUCCESSFUL The requested operation was successful. * @@ -1031,13 +1035,25 @@ rtems_status_code rtems_task_restart( * @retval ::RTEMS_CALLED_FROM_ISR The directive was called from within * interrupt context. * + * @retval ::RTEMS_INCORRECT_STATE The task termination procedure was started, + * however, waiting for the terminating task would have resulted in a + * deadlock. + * * @retval ::RTEMS_ILLEGAL_ON_REMOTE_OBJECT The task resided on a remote node. * * @par Notes * @parblock - * RTEMS stops the execution of the task and reclaims the stack memory, any - * allocated delay or timeout timers, the TCB, and, if the task is - * #RTEMS_FLOATING_POINT, its floating point context area. RTEMS explicitly + * The task deletion is done in several steps. Firstly, the task is marked as + * terminating. While the task life of the terminating task is protected, it + * executes normally until it disables the task life protection or it deletes + * itself. A terminating task will eventually stop its normal execution and + * start its termination procedure. The procedure executes in the context of + * the terminating task. The task termination procedure involves the + * destruction of POSIX key values and running the task termination user + * extensions. Once complete the execution of the task is stopped and + * task-specific resources are reclaimed by the system, such as the stack + * memory, any allocated delay or timeout timers, the TCB, and, if the task is + * #RTEMS_FLOATING_POINT, its floating point context area. RTEMS explicitly * does not reclaim the following resources: region segments, partition * buffers, semaphores, timers, or rate monotonic periods. * @@ -1049,10 +1065,12 @@ rtems_status_code rtems_task_restart( * resources and delete itself by restarting it with a special argument or by * sending it a message, an event, or a signal. * - * Deletion of the current task (#RTEMS_SELF) will force RTEMS to select + * Deletion of the calling task (#RTEMS_SELF) will force RTEMS to select * another task to execute. * - * The TCB for the deleted task is reclaimed by RTEMS. + * When a task deletes another task, the calling task waits until the task + * termination procedure of the task being deleted has completed. The + * terminating task inherits the eligible priorities of the calling task. * * When a global task is deleted, the task identifier must be transmitted to * every node in the system for deletion from the local copy of the global @@ -1526,15 +1544,16 @@ rtems_status_code rtems_task_mode( /** * @ingroup RTEMSAPIClassicTasks * - * @brief Wakes up after an interval in clock ticks or yields the processor. + * @brief Wakes up after a count of clock ticks have occurred or yields the + * processor. * - * @param ticks is the interval in clock ticks to delay the task or + * @param ticks is the count of clock ticks to delay the task or * #RTEMS_YIELD_PROCESSOR to yield the processor. * - * This directive blocks the calling task for the specified ``ticks`` of clock - * ticks if the value is not equal to #RTEMS_YIELD_PROCESSOR. When the - * requested interval has elapsed, the task is made ready. The clock tick - * directives automatically updates the delay period. The calling task may + * This directive blocks the calling task for the specified ``ticks`` count of + * clock ticks if the value is not equal to #RTEMS_YIELD_PROCESSOR. When the + * requested count of ticks have occurred, the task is made ready. The clock + * tick directives automatically update the delay period. The calling task may * give up the processor and remain in the ready state by specifying a value of * #RTEMS_YIELD_PROCESSOR in ``ticks``. * @@ -1543,7 +1562,11 @@ rtems_status_code rtems_task_mode( * @par Notes * Setting the system date and time with the rtems_clock_set() directive and * similar directives which set CLOCK_REALTIME have no effect on a - * rtems_task_wake_after() blocked task. + * rtems_task_wake_after() blocked task. The delay until first clock tick will + * never be a whole clock tick interval since this directive will never execute + * exactly on a clock tick. Applications requiring use of a clock + * (CLOCK_REALTIME or CLOCK_MONOTONIC) instead of clock ticks should make use + * of clock_nanosleep(). * * @par Constraints * @parblock |