diff options
Diffstat (limited to 'cpukit/include/rtems/rtems/tasks.h')
-rw-r--r-- | cpukit/include/rtems/rtems/tasks.h | 723 |
1 files changed, 147 insertions, 576 deletions
diff --git a/cpukit/include/rtems/rtems/tasks.h b/cpukit/include/rtems/rtems/tasks.h index cb620a4c09..84dd646fe7 100644 --- a/cpukit/include/rtems/rtems/tasks.h +++ b/cpukit/include/rtems/rtems/tasks.h @@ -3,12 +3,14 @@ /** * @file * + * @ingroup RTEMSImplClassicTask + * * @brief This header file defines the main parts of the Tasks Manager API. */ /* - * 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 @@ -66,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> @@ -74,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 */ /** @@ -182,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; @@ -235,8 +213,8 @@ typedef struct { /** * @ingroup RTEMSAPIClassicTasks * - * @brief This constant is passed to {set-priority:/name} when the caller wants - * to obtain the current priority. + * @brief This constant is passed to rtems_task_set_priority() when the caller + * wants to obtain the current priority. */ #define RTEMS_CURRENT_PRIORITY 0 @@ -256,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 ); @@ -305,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 */ /** @@ -328,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 @@ -423,473 +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 object identifier variable. When the - * directive call is successful, the identifier of the scheduler will be - * stored in this variable. - * - * 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 object identifier variable. When the - * directive call is successful, the identifier of the scheduler will be - * stored in this variable. - * - * @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 referenced processor set variable in - * bytes. This value shall be positive. - * - * @param cpuset is the pointer to a processor set variable. The referenced - * processor set will be used to identify the scheduler. - * - * @param[out] id is the pointer to an object identifier variable. When the - * directive call is successful, the identifier of the scheduler will be - * stored in this variable. - * - * 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_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 a task priority variable. The - * maximum priority of the scheduler will be stored in this variable, if the - * operation is successful. - * - * @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 a POSIX thread priority - * variable. 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 variable. - * - * @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 a Classic API task priority variable. - * 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 variable. - * - * @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 referenced processor set variable in - * bytes. - * - * @param[out] cpuset is the pointer to a processor set variable. When the - * directive call is successful, the processor set of the scheduler will be - * stored in this variable. 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_NUMBER 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 */ /** @@ -907,9 +437,9 @@ rtems_status_code rtems_scheduler_remove_processor( * * @param attribute_set is the attribute set of the task. * - * @param[out] id is the pointer to an object identifier variable. When the - * directive call is successful, the identifier of the created task will be - * stored in this variable. + * @param[out] id is the pointer to an ::rtems_id object. When the directive + * call is successful, the identifier of the created task will be stored in + * this object. * * This directive creates a task which resides on the local node. The task has * the user-defined object name specified in ``name``. The assigned object @@ -917,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: * @@ -1053,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 @@ -1085,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. @@ -1114,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( @@ -1141,11 +671,12 @@ 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 object identifier variable. When the - * directive call is successful, the identifier of the constructed task will - * be stored in this variable. + * @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 + * in this object. * * @retval ::RTEMS_SUCCESSFUL The requested operation was successful. * @@ -1160,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 @@ -1204,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 * @@ -1230,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( @@ -1257,14 +789,15 @@ rtems_status_code rtems_task_construct( * * @param node is the node or node set to search for a matching object. * - * @param[out] id is the pointer to an object identifier variable. When the - * directive call is successful, the object identifier of an object with the - * specified name will be stored in this variable. + * @param[out] id is the pointer to an ::rtems_id object. When the directive + * call is successful, the object identifier of an object with the specified + * name will be stored in this object. * * 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 * @@ -1364,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. * @@ -1499,13 +1032,28 @@ rtems_status_code rtems_task_restart( * @retval ::RTEMS_INVALID_ID There was no task associated with the identifier * specified by ``id``. * + * @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. * @@ -1517,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 @@ -1743,10 +1293,9 @@ rtems_status_code rtems_task_is_suspended( rtems_id id ); * @param new_priority is the new real priority or #RTEMS_CURRENT_PRIORITY to * get the current priority. * - * @param[out] old_priority is the pointer to an ::rtems_task_priority - * variable. When the directive call is successful, the current or previous - * priority of the task with respect to its home scheduler will be stored in - * this variable. + * @param[out] old_priority is the pointer to an ::rtems_task_priority object. + * When the directive call is successful, the current or previous priority of + * the task with respect to its home scheduler will be stored in this object. * * This directive manipulates the priority of the task specified by ``id``. * When ``new_priority`` is not equal to #RTEMS_CURRENT_PRIORITY, the specified @@ -1818,9 +1367,9 @@ rtems_status_code rtems_task_set_priority( * * @param scheduler_id is the scheduler identifier. * - * @param[out] priority is the pointer to an ::rtems_task_priority variable. + * @param[out] priority is the pointer to an ::rtems_task_priority object. * When the directive call is successful, the current priority of the task - * with respect to the specified scheduler will be stored in this variable. + * with respect to the specified scheduler will be stored in this object. * * This directive returns the current priority in ``priority`` of the task * specified by ``task_id`` with respect to the scheduler specified by @@ -1843,8 +1392,8 @@ rtems_status_code rtems_task_set_priority( * * @par Notes * The current priority reflects temporary priority adjustments due to locking - * protocols, the rate-monotonic period objects on some schedulers, and other - * mechanisms. + * protocols, the rate-monotonic period objects on some schedulers such as EDF, + * and the POSIX sporadic server. * * @par Constraints * @parblock @@ -1881,9 +1430,9 @@ rtems_status_code rtems_task_get_priority( * applied to the calling task. When the value is #RTEMS_CURRENT_MODE, the * mode of the calling task is not changed. * - * @param previous_mode_set is the pointer to a mode variable. When the + * @param previous_mode_set is the pointer to an ::rtems_mode object. When the * directive call is successful, the mode of the task before any mode changes - * done by the directive call will be stored in this variable. + * done by the directive call will be stored in this object. * * This directive queries and optionally manipulates the execution mode of the * calling task. A task's execution mode enables and disables preemption, @@ -1995,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``. * @@ -2012,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 @@ -2069,7 +1623,7 @@ rtems_status_code rtems_task_wake_after( rtems_interval ticks ); * occur. * @endparblock */ -rtems_status_code rtems_task_wake_when( rtems_time_of_day *time_buffer ); +rtems_status_code rtems_task_wake_when( const rtems_time_of_day *time_buffer ); /* Generated from spec:/rtems/task/if/get-scheduler */ @@ -2081,9 +1635,9 @@ rtems_status_code rtems_task_wake_when( rtems_time_of_day *time_buffer ); * @param task_id is the task identifier. The constant #RTEMS_SELF may be used * to specify the calling task. * - * @param[out] scheduler_id is the pointer to an ::rtems_id variable. When the + * @param[out] scheduler_id is the pointer to an ::rtems_id object. When the * directive call is successful, the identifier of the home scheduler of the - * task will be stored in this variable. + * task will be stored in this object. * * This directive returns the identifier of the home scheduler of the task * specified by ``task_id`` in ``scheduler_id``. @@ -2140,13 +1694,30 @@ rtems_status_code rtems_task_get_scheduler( * @retval ::RTEMS_INVALID_ID There was no scheduler associated with the * identifier specified by ``scheduler_id``. * - * @retval ::RTEMS_INVALID_PRIORITY There task priority specified in - * ``priority`` was invalid with respect to the scheduler specified by - * ``scheduler_id``. + * @retval ::RTEMS_INVALID_PRIORITY The task priority specified by ``priority`` + * was invalid with respect to the scheduler specified by ``scheduler_id``. * * @retval ::RTEMS_INVALID_ID There was no task associated with the identifier * specified by ``task_id``. * + * @retval ::RTEMS_RESOURCE_IN_USE The task specified by ``task_id`` was + * enqueued on a wait queue. + * + * @retval ::RTEMS_RESOURCE_IN_USE The task specified by ``task_id`` had a + * current priority which consisted of more than the real priority. + * + * @retval ::RTEMS_RESOURCE_IN_USE The task specified by ``task_id`` had a + * helping scheduler. + * + * @retval ::RTEMS_RESOURCE_IN_USE The task specified by ``task_id`` was + * pinned. + * + * @retval ::RTEMS_UNSATISFIED The scheduler specified by ``scheduler_id`` + * owned no processor. + * + * @retval ::RTEMS_UNSATISFIED The scheduler specified by ``scheduler_id`` did + * not support the affinity set of the task specified by ``task_id``. + * * @retval ::RTEMS_ILLEGAL_ON_REMOTE_OBJECT The task resided on a remote node. * * @par Constraints @@ -2180,12 +1751,12 @@ rtems_status_code rtems_task_set_scheduler( * @param id is the task identifier. The constant #RTEMS_SELF may be used to * specify the calling task. * - * @param cpusetsize is the size of the referenced processor set variable in - * bytes. + * @param cpusetsize is the size of the processor set referenced by ``cpuset`` + * in bytes. * - * @param[out] cpuset is the pointer to a processor set variable. When the - * directive call is successful, the processor affinity set of the task will - * be stored in this variable. A set bit in the processor set means that the + * @param[out] cpuset is the pointer to a cpu_set_t object. When the directive + * call is successful, the processor affinity set of the task will be stored + * in this object. A set bit in the processor set means that the * corresponding processor is in the processor affinity set of the task, * otherwise the bit is cleared. * @@ -2199,8 +1770,8 @@ rtems_status_code rtems_task_set_scheduler( * @retval ::RTEMS_INVALID_ID There was no task associated with the identifier * specified by ``id``. * - * @retval ::RTEMS_INVALID_SIZE The provided processor set was too small for - * the processor affinity set of the task. + * @retval ::RTEMS_INVALID_SIZE The size specified by ``cpusetsize`` of the + * processor set was too small for the processor affinity set of the task. * * @retval ::RTEMS_ILLEGAL_ON_REMOTE_OBJECT The task resided on a remote node. * @@ -2234,10 +1805,10 @@ rtems_status_code rtems_task_get_affinity( * @param id is the task identifier. The constant #RTEMS_SELF may be used to * specify the calling task. * - * @param cpusetsize is the size of the referenced processor set variable in - * bytes. + * @param cpusetsize is the size of the processor set referenced by ``cpuset`` + * in bytes. * - * @param cpuset is the pointer to a processor set variable. The processor set + * @param cpuset is the pointer to a cpu_set_t object. The processor set * defines the new processor affinity set of the task. A set bit in the * processor set means that the corresponding processor shall be in the * processor affinity set of the task, otherwise the bit shall be cleared. |