summaryrefslogtreecommitdiffstats
path: root/cpukit/include/rtems/rtems/tasks.h
diff options
context:
space:
mode:
Diffstat (limited to 'cpukit/include/rtems/rtems/tasks.h')
-rw-r--r--cpukit/include/rtems/rtems/tasks.h723
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.