diff options
Diffstat (limited to 'cpukit/include/rtems/rtems/tasks.h')
| -rw-r--r-- | cpukit/include/rtems/rtems/tasks.h | 629 |
1 files changed, 89 insertions, 540 deletions
diff --git a/cpukit/include/rtems/rtems/tasks.h b/cpukit/include/rtems/rtems/tasks.h index 8c6e8a3bca..84dd646fe7 100644 --- a/cpukit/include/rtems/rtems/tasks.h +++ b/cpukit/include/rtems/rtems/tasks.h @@ -9,8 +9,8 @@ */ /* - * Copyright (C) 2013, 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 @@ -68,7 +68,6 @@ #include <rtems/score/context.h> #include <rtems/score/cpu.h> #include <rtems/score/object.h> -#include <rtems/score/smp.h> #include <rtems/score/stack.h> #include <rtems/score/watchdogticks.h> @@ -76,29 +75,6 @@ extern "C" { #endif -/* Generated from spec:/rtems/scheduler/if/group */ - -/** - * @defgroup RTEMSAPIClassicScheduler Scheduler Manager - * - * @ingroup RTEMSAPIClassic - * - * @brief The scheduling concepts relate to the allocation of processing time - * for tasks. - * - * The concept of scheduling in real-time systems dictates the ability to - * provide an immediate response to specific external events, particularly the - * necessity of scheduling tasks to run within a specified time limit after the - * occurrence of an event. For example, software embedded in life-support - * systems used to monitor hospital patients must take instant action if a - * change in the patient’s status is detected. - * - * The component of RTEMS responsible for providing this capability is - * appropriately called the scheduler. The scheduler’s sole purpose is to - * allocate the all important resource of processor time to the various tasks - * competing for attention. - */ - /* Generated from spec:/rtems/task/if/group */ /** @@ -184,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; @@ -258,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 ); @@ -307,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 */ /** @@ -330,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 @@ -425,474 +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/scheduler/if/ident */ - -/** - * @ingroup RTEMSAPIClassicScheduler - * - * @brief Identifies a scheduler by the object name. - * - * @param name is the scheduler name to look up. - * - * @param[out] id is the pointer to an ::rtems_id object. When the directive - * call is successful, the identifier of the scheduler will be stored in this - * object. - * - * This directive obtains a scheduler identifier associated with the scheduler - * name specified in ``name``. - * - * @retval ::RTEMS_SUCCESSFUL The requested operation was successful. - * - * @retval ::RTEMS_INVALID_NAME There was no scheduler associated with the - * name. - * - * @retval ::RTEMS_INVALID_ADDRESS The ``id`` parameter was NULL. - * - * @par Notes - * @parblock - * The scheduler name is determined by the scheduler configuration. - * - * The scheduler identifier is used with other scheduler related directives to - * access the scheduler. - * @endparblock - * - * @par Constraints - * @parblock - * The following constraints apply to this directive: - * - * * The directive may be called from within any runtime context. - * - * * The directive will not cause the calling task to be preempted. - * @endparblock - */ -rtems_status_code rtems_scheduler_ident( rtems_name name, rtems_id *id ); - -/* Generated from spec:/rtems/scheduler/if/ident-by-processor */ - -/** - * @ingroup RTEMSAPIClassicScheduler - * - * @brief Identifies a scheduler by the processor index. - * - * @param cpu_index is the processor index to identify the scheduler. - * - * @param[out] id is the pointer to an ::rtems_id object. When the directive - * call is successful, the identifier of the scheduler will be stored in this - * object. - * - * @retval ::RTEMS_SUCCESSFUL The requested operation was successful. - * - * @retval ::RTEMS_INVALID_ADDRESS The ``id`` parameter was NULL. - * - * @retval ::RTEMS_INVALID_NAME The processor index was invalid. - * - * @retval ::RTEMS_INCORRECT_STATE The processor index was valid, however, the - * corresponding processor was not owned by a scheduler. - * - * @par Constraints - * @parblock - * The following constraints apply to this directive: - * - * * The directive may be called from within any runtime context. - * - * * The directive will not cause the calling task to be preempted. - * @endparblock - */ -rtems_status_code rtems_scheduler_ident_by_processor( - uint32_t cpu_index, - rtems_id *id -); - -/* Generated from spec:/rtems/scheduler/if/ident-by-processor-set */ - -/** - * @ingroup RTEMSAPIClassicScheduler - * - * @brief Identifies a scheduler by the processor set. - * - * @param cpusetsize is the size of the processor set referenced by ``cpuset`` - * in bytes. The size shall be positive. - * - * @param cpuset is the pointer to a cpu_set_t. The referenced processor set - * will be used to identify the scheduler. - * - * @param[out] id is the pointer to an ::rtems_id object. When the directive - * call is successful, the identifier of the scheduler will be stored in this - * object. - * - * The scheduler is selected according to the highest numbered online processor - * in the specified processor set. - * - * @retval ::RTEMS_SUCCESSFUL The requested operation was successful. - * - * @retval ::RTEMS_INVALID_ADDRESS The ``id`` parameter was NULL. - * - * @retval ::RTEMS_INVALID_ADDRESS The ``cpuset`` parameter was NULL. - * - * @retval ::RTEMS_INVALID_SIZE The processor set size was invalid. - * - * @retval ::RTEMS_INVALID_NAME The processor set contained no online - * processor. - * - * @retval ::RTEMS_INCORRECT_STATE The processor set was valid, however, the - * highest numbered online processor in the processor set was not owned by a - * scheduler. - * - * @par Constraints - * @parblock - * The following constraints apply to this directive: - * - * * The directive may be called from within any runtime context. - * - * * The directive will not cause the calling task to be preempted. - * @endparblock - */ -rtems_status_code rtems_scheduler_ident_by_processor_set( - size_t cpusetsize, - const cpu_set_t *cpuset, - rtems_id *id -); - -/* Generated from spec:/rtems/scheduler/if/get-maximum-priority */ - -/** - * @ingroup RTEMSAPIClassicScheduler - * - * @brief Gets the maximum task priority of the scheduler. - * - * @param scheduler_id is the scheduler identifier. - * - * @param[out] priority is the pointer to an ::rtems_task_priority object. - * When the directive the maximum priority of the scheduler will be stored in - * this object. - * - * @retval ::RTEMS_SUCCESSFUL The requested operation was successful. - * - * @retval ::RTEMS_INVALID_ID There was no scheduler associated with the - * identifier specified by ``scheduler_id``. - * - * @retval ::RTEMS_INVALID_ADDRESS The ``priority`` parameter was NULL. - * - * @par Constraints - * @parblock - * The following constraints apply to this directive: - * - * * The directive may be called from within any runtime context. - * - * * The directive will not cause the calling task to be preempted. - * @endparblock - */ -rtems_status_code rtems_scheduler_get_maximum_priority( - rtems_id scheduler_id, - rtems_task_priority *priority -); - -/* Generated from spec:/rtems/scheduler/if/map-priority-to-posix */ - -/** - * @ingroup RTEMSAPIClassicScheduler - * - * @brief Maps a Classic API task priority to the corresponding POSIX thread - * priority. - * - * @param scheduler_id is the scheduler identifier. - * - * @param priority is the Classic API task priority to map. - * - * @param[out] posix_priority is the pointer to an ``int`` object. When the - * directive call is successful, the POSIX thread priority value - * corresponding to the specified Classic API task priority value will be - * stored in this object. - * - * @retval ::RTEMS_SUCCESSFUL The requested operation was successful. - * - * @retval ::RTEMS_INVALID_ADDRESS The ``posix_priority`` parameter was NULL. - * - * @retval ::RTEMS_INVALID_ID There was no scheduler associated with the - * identifier specified by ``scheduler_id``. - * - * @retval ::RTEMS_INVALID_PRIORITY The Classic API task priority was invalid. - * - * @par Constraints - * @parblock - * The following constraints apply to this directive: - * - * * The directive may be called from within any runtime context. - * - * * The directive will not cause the calling task to be preempted. - * @endparblock - */ -rtems_status_code rtems_scheduler_map_priority_to_posix( - rtems_id scheduler_id, - rtems_task_priority priority, - int *posix_priority -); - -/* Generated from spec:/rtems/scheduler/if/map-priority-from-posix */ - -/** - * @ingroup RTEMSAPIClassicScheduler - * - * @brief Maps a POSIX thread priority to the corresponding Classic API task - * priority. - * - * @param scheduler_id is the scheduler identifier. - * - * @param posix_priority is the POSIX thread priority to map. - * - * @param[out] priority is the pointer to an ::rtems_task_priority object. - * When the directive call is successful, the Classic API task priority value - * corresponding to the specified POSIX thread priority value will be stored - * in this object. - * - * @retval ::RTEMS_SUCCESSFUL The requested operation was successful. - * - * @retval ::RTEMS_INVALID_ADDRESS The ``priority`` parameter was NULL. - * - * @retval ::RTEMS_INVALID_ID There was no scheduler associated with the - * identifier specified by ``scheduler_id``. - * - * @retval ::RTEMS_INVALID_PRIORITY The POSIX thread priority was invalid. - * - * @par Constraints - * @parblock - * The following constraints apply to this directive: - * - * * The directive may be called from within any runtime context. - * - * * The directive will not cause the calling task to be preempted. - * @endparblock - */ -rtems_status_code rtems_scheduler_map_priority_from_posix( - rtems_id scheduler_id, - int posix_priority, - rtems_task_priority *priority -); - -/* Generated from spec:/rtems/scheduler/if/get-processor */ - -/** - * @ingroup RTEMSAPIClassicScheduler - * - * @brief Returns the index of the current processor. - * - * Where the system was built with SMP support disabled, this directive - * evaluates to a compile time constant of zero. - * - * Where the system was built with SMP support enabled, this directive returns - * the index of the current processor. The set of processor indices is the - * range of integers starting with zero up to - * rtems_scheduler_get_processor_maximum() minus one. - * - * @return Returns the index of the current processor. - * - * @par Notes - * Outside of sections with disabled thread dispatching the current processor - * index may change after every instruction since the thread may migrate from - * one processor to another. Sections with disabled interrupts are sections - * with thread dispatching disabled. - * - * @par Constraints - * @parblock - * The following constraints apply to this directive: - * - * * The directive may be called from within any runtime context. - * - * * The directive will not cause the calling task to be preempted. - * @endparblock - */ -uint32_t rtems_scheduler_get_processor( void ); - -/* Generated from spec:/rtems/scheduler/if/get-processor-macro */ -#define rtems_scheduler_get_processor() _SMP_Get_current_processor() - -/* Generated from spec:/rtems/scheduler/if/get-processor-maximum */ - -/** - * @ingroup RTEMSAPIClassicScheduler - * - * @brief Returns the processor maximum supported by the system. - * - * Where the system was built with SMP support disabled, this directive - * evaluates to a compile time constant of one. - * - * Where the system was built with SMP support enabled, this directive returns - * the minimum of the processors (physically or virtually) available at the - * target and the configured processor maximum (see - * #CONFIGURE_MAXIMUM_PROCESSORS). Not all processors in the range from - * processor index zero to the last processor index (which is the processor - * maximum minus one) may be configured to be used by a scheduler or may be - * online (online processors have a scheduler assigned). - * - * @return Returns the processor maximum supported by the system. - * - * @par Constraints - * @parblock - * The following constraints apply to this directive: - * - * * The directive may be called from within any runtime context. - * - * * The directive will not cause the calling task to be preempted. - * @endparblock - */ -uint32_t rtems_scheduler_get_processor_maximum( void ); - -/* Generated from spec:/rtems/scheduler/if/get-processor-maximum-macro */ -#define rtems_scheduler_get_processor_maximum() _SMP_Get_processor_maximum() - -/* Generated from spec:/rtems/scheduler/if/get-processor-set */ - -/** - * @ingroup RTEMSAPIClassicScheduler - * - * @brief Gets the set of processors owned by the scheduler. - * - * @param scheduler_id is the scheduler identifier. - * - * @param cpusetsize is the size of the processor set referenced by ``cpuset`` - * in bytes. - * - * @param[out] cpuset is the pointer to a cpu_set_t object. When the directive - * call is successful, the processor set of the scheduler will be stored in - * this object. A set bit in the processor set means that the corresponding - * processor is owned by the scheduler, otherwise the bit is cleared. - * - * @retval ::RTEMS_SUCCESSFUL The requested operation was successful. - * - * @retval ::RTEMS_INVALID_ADDRESS The ``cpuset`` parameter was NULL. - * - * @retval ::RTEMS_INVALID_ID There was no scheduler associated with the - * identifier specified by ``scheduler_id``. - * - * @retval ::RTEMS_INVALID_SIZE The provided processor set was too small for - * the set of processors owned by the scheduler. - * - * @par Constraints - * @parblock - * The following constraints apply to this directive: - * - * * The directive may be called from within any runtime context. - * - * * The directive will not cause the calling task to be preempted. - * @endparblock - */ -rtems_status_code rtems_scheduler_get_processor_set( - rtems_id scheduler_id, - size_t cpusetsize, - cpu_set_t *cpuset -); - -/* Generated from spec:/rtems/scheduler/if/add-processor */ - -/** - * @ingroup RTEMSAPIClassicScheduler - * - * @brief Adds the processor to the set of processors owned by the scheduler. - * - * @param scheduler_id is the scheduler identifier. - * - * @param cpu_index is the index of the processor to add. - * - * This directive adds the processor specified by the ``cpu_index`` to the - * scheduler specified by ``scheduler_id``. - * - * @retval ::RTEMS_SUCCESSFUL The requested operation was successful. - * - * @retval ::RTEMS_INVALID_ID There was no scheduler associated with the - * identifier specified by ``scheduler_id``. - * - * @retval ::RTEMS_NOT_CONFIGURED The processor was not configured to be used - * by the application. - * - * @retval ::RTEMS_INCORRECT_STATE The processor was configured to be used by - * the application, however, it was not online. - * - * @retval ::RTEMS_RESOURCE_IN_USE The processor was already assigned to a - * scheduler. - * - * @par Constraints - * @parblock - * The following constraints apply to this directive: - * - * * The directive may be called from within device driver initialization - * context. - * - * * The directive may be called from within task context. - * - * * The directive may obtain and release the object allocator mutex. This may - * cause the calling task to be preempted. - * @endparblock - */ -rtems_status_code rtems_scheduler_add_processor( - rtems_id scheduler_id, - uint32_t cpu_index -); - -/* Generated from spec:/rtems/scheduler/if/remove-processor */ - -/** - * @ingroup RTEMSAPIClassicScheduler - * - * @brief Removes the processor from the set of processors owned by the - * scheduler. - * - * @param scheduler_id is the scheduler identifier. - * - * @param cpu_index is the index of the processor to remove. - * - * This directive removes the processor specified by the ``cpu_index`` from the - * scheduler specified by ``scheduler_id``. - * - * @retval ::RTEMS_SUCCESSFUL The requested operation was successful. - * - * @retval ::RTEMS_INVALID_ID There was no scheduler associated with the - * identifier specified by ``scheduler_id``. - * - * @retval ::RTEMS_INVALID_NUMBER The processor was not owned by the scheduler. - * - * @retval ::RTEMS_RESOURCE_IN_USE The set of processors owned by the scheduler - * would have been empty after the processor removal and there was at least - * one non-idle task that used this scheduler as its home scheduler. - * - * @par Notes - * Removing a processor from a scheduler is a complex operation that involves - * all tasks of the system. - * - * @par Constraints - * @parblock - * The following constraints apply to this directive: - * - * * The directive may be called from within device driver initialization - * context. - * - * * The directive may be called from within task context. - * - * * The directive may obtain and release the object allocator mutex. This may - * cause the calling task to be preempted. - * @endparblock - */ -rtems_status_code rtems_scheduler_remove_processor( - rtems_id scheduler_id, - uint32_t cpu_index -); - /* Generated from spec:/rtems/task/if/create */ /** @@ -920,15 +447,15 @@ rtems_status_code rtems_scheduler_remove_processor( * task with other task related directives. * * The **initial priority** of the task is specified in ``initial_priority``. - * The scheduler of the created task is the scheduler of the calling task at - * some point during the task creation. The initial task priority specified in - * ``initial_priority`` shall be valid for this scheduler. + * The home scheduler of the created task is the home scheduler of the calling + * task at some time point during the task creation. The initial task priority + * specified in ``initial_priority`` shall be valid for this scheduler. * * 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: * @@ -1056,12 +583,12 @@ rtems_status_code rtems_scheduler_remove_processor( * * @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 @@ -1088,7 +615,7 @@ rtems_status_code rtems_scheduler_remove_processor( * 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. @@ -1117,15 +644,15 @@ rtems_status_code rtems_scheduler_remove_processor( * 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( @@ -1144,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 @@ -1163,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 @@ -1207,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 * @@ -1233,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( @@ -1267,7 +796,8 @@ rtems_status_code rtems_task_construct( * This directive obtains a task identifier associated with the task name * specified in ``name``. * - * A task may obtain its own identifier by specifying #RTEMS_SELF for the name. + * A task may obtain its own identifier by specifying #RTEMS_WHO_AM_I for the + * name. * * The node to search is specified in ``node``. It shall be * @@ -1367,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. * @@ -1505,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. * @@ -1523,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 @@ -2000,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``. * @@ -2017,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 |