/* SPDX-License-Identifier: BSD-2-Clause */ /** * @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) * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions * are met: * 1. Redistributions of source code must retain the above copyright * notice, this list of conditions and the following disclaimer. * 2. Redistributions in binary form must reproduce the above copyright * notice, this list of conditions and the following disclaimer in the * documentation and/or other materials provided with the distribution. * * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE * POSSIBILITY OF SUCH DAMAGE. */ /* * This file is part of the RTEMS quality process and was automatically * generated. If you find something that needs to be fixed or * worded better please post a report or patch to an RTEMS mailing list * or raise a bug report: * * https://www.rtems.org/bugs.html * * For information on updating and regenerating please refer to the How-To * section in the Software Requirements Engineering chapter of the * RTEMS Software Engineering manual. The manual is provided as a part of * a release. For development sources please refer to the online * documentation at: * * https://docs.rtems.org */ /* Generated from spec:/rtems/task/if/header */ #ifndef _RTEMS_RTEMS_TASKS_H #define _RTEMS_RTEMS_TASKS_H #include #include #include #include #include #include #include #include #include #include #include #include #include #include #include #ifdef __cplusplus 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 */ /** * @defgroup RTEMSAPIClassicTasks Task Manager * * @ingroup RTEMSAPIClassic * * @brief The Task Manager provides a comprehensive set of directives to * create, delete, and administer tasks. */ /* Generated from spec:/rtems/task/if/argument */ /** * @ingroup RTEMSAPIClassicTasks * * @brief This integer type represents task argument values. * * @par Notes * The type is an architecture-specific unsigned integer type which is large * enough to represent pointer values and 32-bit unsigned integers. */ typedef CPU_Uint32ptr rtems_task_argument; /* Generated from spec:/rtems/task/if/config */ /** * @ingroup RTEMSAPIClassicTasks * * @brief This structure defines the configuration of a task constructed by * rtems_task_construct(). */ typedef struct { /** * @brief This member defines the name of the task. */ rtems_name name; /** * @brief This member defines the initial priority of the task. */ rtems_task_priority initial_priority; /** * @brief This member shall point to the task storage area begin. * * The task storage area will contain the task stack, the thread-local storage, * and the floating-point context on architectures with a separate * floating-point context. * * The task storage area begin address and size should be aligned by * #RTEMS_TASK_STORAGE_ALIGNMENT. To avoid memory waste, use RTEMS_ALIGNED() * and #RTEMS_TASK_STORAGE_ALIGNMENT to enforce the recommended alignment of a * statically allocated task storage area. */ void *storage_area; /** * @brief This member defines size of the task storage area in bytes. * * Use the RTEMS_TASK_STORAGE_SIZE() macro to determine the recommended task * storage area size. */ size_t storage_size; /** * @brief This member defines the maximum thread-local storage size supported * by the task storage area. * * Use RTEMS_ALIGN_UP() and #RTEMS_TASK_STORAGE_ALIGNMENT to adjust the size to * meet the minimum alignment requirement of a thread-local storage area used * to construct a task. * * If the value is less than the actual thread-local storage size, then the * task construction by rtems_task_construct() fails. * * If the is less than the task storage area size, then the task construction * by rtems_task_construct() fails. * * The actual thread-local storage size is determined when the application * executable is linked. The ``rtems-exeinfo`` command line tool included in * the RTEMS Tools can be used to obtain the thread-local storage size and * 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. */ size_t maximum_thread_local_storage_size; /** * @brief This member defines the optional handler to free the task storage * area. * * It is called on exactly two mutually exclusive occasions. Firstly, when the * task construction aborts due to a failed task create extension, or secondly, * when the task is deleted. It is called from task context under protection * of the object allocator lock. It is allowed to call free() in this handler. * If handler is NULL, then no action will be performed. */ void ( *storage_free )( void * ); /** * @brief This member defines the initial modes of the task. */ rtems_mode initial_modes; /** * @brief This member defines the attributes of the task. */ rtems_attribute attributes; } rtems_task_config; /* Generated from spec:/rtems/task/if/configured-minimum-stack-size */ /** * @ingroup RTEMSAPIClassicTasks * * @brief This constant can be used to indicate that the task should be created * with the configured minimum stack size. * * Using this constant when specifying the task stack size indicates that this * task is to be created with a stack size of the minimum stack size that was * configured by the application. If not explicitly configured by the * application, the default configured minimum stack size is * #RTEMS_MINIMUM_STACK_SIZE which depends on the target architecture. Since * this uses the configured minimum stack size value, you may get a stack size * that is smaller or larger than the recommended minimum. This can be used to * provide large stacks for all tasks on complex applications or small stacks * on applications that are trying to conserve memory. */ #define RTEMS_CONFIGURED_MINIMUM_STACK_SIZE 0 /* Generated from spec:/rtems/task/if/current-priority */ /** * @ingroup RTEMSAPIClassicTasks * * @brief This constant is passed to rtems_task_set_priority() when the caller * wants to obtain the current priority. */ #define RTEMS_CURRENT_PRIORITY 0 /* Generated from spec:/rtems/task/if/task */ /** * @ingroup RTEMSAPIClassicTasks * * @brief This type defines the return type of task entry points. * * This type can be used to document task entry points in the source code. */ typedef void rtems_task; /* Generated from spec:/rtems/task/if/entry */ /** * @ingroup RTEMSAPIClassicTasks * * @brief This type defines the entry point of an RTEMS task. */ typedef rtems_task ( *rtems_task_entry )( rtems_task_argument ); /* Generated from spec:/rtems/task/if/initialization-table */ /** * @ingroup RTEMSAPIClassicTasks * * @brief This structure defines the properties of the Classic API user * initialization task. */ typedef struct { /** * @brief This member defines the task name. */ rtems_name name; /** * @brief This member defines the task stack size in bytes. */ size_t stack_size; /** * @brief This member defines the initial task priority. */ rtems_task_priority initial_priority; /** * @brief This member defines the attribute set of the task. */ rtems_attribute attribute_set; /** * @brief This member defines the entry point of the task. */ rtems_task_entry entry_point; /** * @brief This member defines the initial modes of the task. */ rtems_mode mode_set; /** * @brief This member defines the entry point argument of the task. */ rtems_task_argument argument; } rtems_initialization_tasks_table; /* Generated from spec:/rtems/task/if/minimum-priority */ /** * @ingroup RTEMSAPIClassicTasks * * @brief This compile time constant provides the highest (most important) task * priority settable by the API. */ #define RTEMS_MINIMUM_PRIORITY 1 /* Generated from spec:/rtems/task/if/minimum-stack-size */ /** * @ingroup RTEMSAPIClassicTasks * * @brief This compile time constant provides the minimum task stack size * recommended for the target architecture. * * It is the minimum stack size recommended for use on this processor. This * value is selected by the RTEMS maintainers conservatively to minimize the * 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. */ #define RTEMS_MINIMUM_STACK_SIZE STACK_MINIMUM_SIZE /* Generated from spec:/rtems/task/if/no-priority */ /** * @ingroup RTEMSAPIClassicTasks * * @brief This compile time constant may be used for the * rtems_task_set_priority() directive to get the current task priority. */ #define RTEMS_NO_PRIORITY RTEMS_CURRENT_PRIORITY /* Generated from spec:/rtems/task/if/self-define */ /** * @ingroup RTEMSAPIClassicTasks * * @brief This compile time constant may be used to identify the calling task * in task related directives. */ #define RTEMS_SELF OBJECTS_ID_OF_SELF /* Generated from spec:/rtems/task/if/storage-alignment */ /** * @ingroup RTEMSAPIClassicTasks * * @brief This compile time constant defines the recommended alignment of a * task storage area in bytes. * * @par Notes * Use it with RTEMS_ALIGNED() to define the alignment of a statically * allocated task storage area. */ #define RTEMS_TASK_STORAGE_ALIGNMENT CPU_STACK_ALIGNMENT /* Generated from spec:/rtems/task/if/storage-size */ /** * @ingroup RTEMSAPIClassicTasks * * @brief Gets the recommended task storage area size for the size and task * attributes. * * @param _size is the size dedicated to the task stack and thread-local * storage in bytes. * * @param _attributes is the attribute set of the task using the storage area. * * @return Returns the recommended task storage area size calculated from the * input parameters. */ #if CPU_ALL_TASKS_ARE_FP == TRUE #define RTEMS_TASK_STORAGE_SIZE( _size, _attributes ) \ ( ( _size ) + CONTEXT_FP_SIZE ) #else #define RTEMS_TASK_STORAGE_SIZE( _size, _attributes ) \ ( ( _size ) + \ ( ( ( _attributes ) & RTEMS_FLOATING_POINT ) != 0 ? \ CONTEXT_FP_SIZE : 0 ) ) #endif /* Generated from spec:/rtems/task/if/tcb */ /** * @ingroup RTEMSAPIClassicTasks * * @brief This structure represents the TCB. */ typedef struct _Thread_Control rtems_tcb; /* Generated from spec:/rtems/task/if/visitor */ /** * @ingroup RTEMSAPIClassicTasks * * @brief Visitor routines invoked by rtems_task_iterate() shall have this * type. */ typedef bool( *rtems_task_visitor )( rtems_tcb *, void * ); /* Generated from spec:/rtems/task/if/yield-processor */ /** * @ingroup RTEMSAPIClassicTasks * * @brief This compile time constant may be passed to the * rtems_task_wake_after() directive as the interval when a task wishes to * yield the processor. */ #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 */ /** * @ingroup RTEMSAPIClassicTasks * * @brief Creates a task. * * @param name is the object name of the task. * * @param initial_priority is the initial task priority. * * @param stack_size is the task stack size in bytes. * * @param initial_modes is the initial mode set of the task. * * @param attribute_set is the attribute set of the task. * * @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 * identifier is returned in ``id``. This identifier is used to access the * 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 **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 * addition to being able to specify the task stack size as a integer, there * are two constants which may be specified: * * * The #RTEMS_MINIMUM_STACK_SIZE constant can be specified to use the * **recommended minimum stack size** for the target processor. This value * is selected by the RTEMS maintainers conservatively to minimize the 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 is larger than the recommended minimum, then it will be * used. * * * The #RTEMS_CONFIGURED_MINIMUM_STACK_SIZE constant can be specified to use * the minimum stack size that was configured by the application. If not * explicitly configured by the application, the default configured minimum * stack size is the target processor dependent value * #RTEMS_MINIMUM_STACK_SIZE. Since this uses the configured minimum stack * size value, you may get a stack size that is smaller or larger than the * recommended minimum. This can be used to provide large stacks for all * tasks on complex applications or small stacks on applications that are * trying to conserve memory. * * The **initial mode set** specified in ``initial_modes`` is built through a * *bitwise or* of the mode constants described below. Not all combinations of * modes are allowed. Some modes are mutually exclusive. If mutually * exclusive modes are combined, the behaviour is undefined. Default task * modes can be selected by using the #RTEMS_DEFAULT_MODES constant. The task * mode set defines * * * the preemption mode of the task: #RTEMS_PREEMPT (default) or * #RTEMS_NO_PREEMPT, * * * the timeslicing mode of the task: #RTEMS_TIMESLICE or #RTEMS_NO_TIMESLICE * (default), * * * the ASR processing mode of the task: #RTEMS_ASR (default) or * #RTEMS_NO_ASR, * * * the interrupt level of the task: RTEMS_INTERRUPT_LEVEL() with a default of * ``RTEMS_INTERRUPT_LEVEL( 0 )`` which is associated with enabled * interrupts. * * The **initial preemption mode** of the task is enabled or disabled. * * * An **enabled preemption** is the default and can be emphasized through the * use of the #RTEMS_PREEMPT mode constant. * * * A **disabled preemption** is set by the #RTEMS_NO_PREEMPT mode constant. * * The **initial timeslicing mode** of the task is enabled or disabled. * * * A **disabled timeslicing** is the default and can be emphasized through * the use of the #RTEMS_NO_TIMESLICE mode constant. * * * An **enabled timeslicing** is set by the #RTEMS_TIMESLICE mode constant. * * The **initial ASR processing mode** of the task is enabled or disabled. * * * An **enabled ASR processing** is the default and can be emphasized through * the use of the #RTEMS_ASR mode constant. * * * A **disabled ASR processing** is set by the #RTEMS_NO_ASR mode constant. * * The **initial interrupt level mode** of the task is defined by * RTEMS_INTERRUPT_LEVEL(). * * * Task execution with **interrupts enabled** the default and can be * emphasized through the use of the RTEMS_INTERRUPT_LEVEL() mode macro with * a value of zero (0) for the parameter. An interrupt level of zero is * associated with enabled interrupts on all target processors. * * * Task execution at a **non-zero interrupt level** can be specified by the * RTEMS_INTERRUPT_LEVEL() mode macro with a non-zero value for the * parameter. The interrupt level portion of the task mode supports a * maximum of 256 interrupt levels. These levels are mapped onto the * interrupt levels actually supported by the target processor in a processor * dependent fashion. * * The **attribute set** specified in ``attribute_set`` is built through a * *bitwise or* of the attribute constants described below. Not all * combinations of attributes are allowed. Some attributes are mutually * exclusive. If mutually exclusive attributes are combined, the behaviour is * undefined. Attributes not mentioned below are not evaluated by this * directive and have no effect. Default attributes can be selected by using * the #RTEMS_DEFAULT_ATTRIBUTES constant. The attribute set defines * * * the scope of the task: #RTEMS_LOCAL (default) or #RTEMS_GLOBAL and * * * the floating-point unit use of the task: #RTEMS_FLOATING_POINT or * #RTEMS_NO_FLOATING_POINT (default). * * The task has a local or global **scope** in a multiprocessing network (this * attribute does not refer to SMP systems). The scope is selected by the * mutually exclusive #RTEMS_LOCAL and #RTEMS_GLOBAL attributes. * * * A **local scope** is the default and can be emphasized through the use of * the #RTEMS_LOCAL attribute. A local task can be only used by the node * which created it. * * * A **global scope** is established if the #RTEMS_GLOBAL attribute is set. * Setting the global attribute in a single node system has no effect.the * * The **use of the floating-point unit** is selected by the mutually exclusive * #RTEMS_FLOATING_POINT and #RTEMS_NO_FLOATING_POINT attributes. On some * target processors, the use of the floating-point unit can be enabled or * disabled for each task. Other target processors may have no hardware * floating-point unit or enable the use of the floating-point unit for all * tasks. Consult the *RTEMS CPU Architecture Supplement* for the details. * * * A **disabled floating-point unit** is the default and can be emphasized * through use of the #RTEMS_NO_FLOATING_POINT attribute. For performance * reasons, it is recommended that tasks not using the floating-point unit * should specify this attribute. * * * An **enabled floating-point unit** is selected by the * #RTEMS_FLOATING_POINT attribute. * * @retval ::RTEMS_SUCCESSFUL The requested operation was successful. * * @retval ::RTEMS_INVALID_NAME The ``name`` parameter was invalid. * * @retval ::RTEMS_INVALID_ADDRESS The ``id`` parameter was NULL. * * @retval ::RTEMS_INVALID_PRIORITY The ``initial_priority`` was invalid. * * @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. * * @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. * * @retval ::RTEMS_UNSATISFIED There was not enough memory to allocate the task * storage area. The task storage area contains the task stack, the * thread-local storage, and the floating point context. * * @retval ::RTEMS_UNSATISFIED One of the task create extensions failed to * create the task. * * @retval ::RTEMS_UNSATISFIED In SMP configurations, the non-preemption mode * was not supported. * * @retval ::RTEMS_UNSATISFIED In SMP configurations, the interrupt level mode * was not supported. * * @par Notes * @parblock * The task processor affinity is initialized to the set of online processors. * * When created, a task is placed in the dormant state and can only be made * ready to execute using the directive rtems_task_start(). * * Application developers should consider the stack usage of the device drivers * when calculating the stack size required for tasks which utilize the driver. * 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. * * For control and maintenance of the task, RTEMS allocates a TCB from the * local TCB free pool and initializes it. * * The TCB for a global task is allocated on the local node. Task should not * be made global unless remote tasks must interact with the task. This is to * avoid the system overhead incurred by the creation of a global task. When a * global task is created, the task's name and identifier must be transmitted * to every node in the system for insertion in the local copy of the global * object table. * @endparblock * * @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. * * * When the directive operates on a global object, the directive sends a * 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. * * * 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. * @endparblock */ rtems_status_code rtems_task_create( rtems_name name, rtems_task_priority initial_priority, size_t stack_size, rtems_mode initial_modes, rtems_attribute attribute_set, rtems_id *id ); /* Generated from spec:/rtems/task/if/construct */ /** * @ingroup RTEMSAPIClassicTasks * * @brief Constructs a task from the specified task configuration. * * @param config is the task configuration. * * @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. * * @retval ::RTEMS_INVALID_ADDRESS The ``config`` parameter was NULL. * * @retval ::RTEMS_INVALID_NAME The task name was invalid. * * @retval ::RTEMS_INVALID_ADDRESS The ``id`` parameter was NULL. * * @retval ::RTEMS_INVALID_PRIORITY The initial task priority was invalid. * * @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. * * @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 * architectures with a separate floating-point context. * * @retval ::RTEMS_TOO_MANY There was no inactive task object available to * construct a task. * * @retval ::RTEMS_TOO_MANY In multiprocessing configurations, there was no * inactive global object available to construct a global task. * * @retval ::RTEMS_UNSATISFIED One of the task create extensions failed during * the task construction. * * @retval ::RTEMS_UNSATISFIED In SMP configurations, the non-preemption mode * was not supported. * * @retval ::RTEMS_UNSATISFIED In SMP configurations, the interrupt level mode * was not supported. * * @par Notes * @parblock * In contrast to tasks created by rtems_task_create(), the tasks constructed * by this directive use a user-provided task storage area. 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. * * This directive is intended for applications which do not want to use the * RTEMS Workspace and instead statically allocate all operating system * resources. It is not recommended to use rtems_task_create() and * rtems_task_construct() together in an application. It is also not * recommended to use rtems_task_construct() for drivers or general purpose * libraries. The reason for these recommendations is that the task * configuration needs settings which can be only given with a through * knowledge of the application resources. * * An application based solely on static allocation can avoid any runtime * memory allocators. This can simplify the application architecture as well * as any analysis that may be required. * * The stack space estimate done by 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 #CONFIGURE_MAXIMUM_TASKS should include tasks constructed by * rtems_task_construct(). * @endparblock * * @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. * * * When the directive operates on a global object, the directive sends a * 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. * * * 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. * @endparblock */ rtems_status_code rtems_task_construct( const rtems_task_config *config, rtems_id *id ); /* Generated from spec:/rtems/task/if/ident */ /** * @ingroup RTEMSAPIClassicTasks * * @brief Identifies a task by the object name. * * @param name is the object name to look up. * * @param node is the node or node set to search for a matching object. * * @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. * * The node to search is specified in ``node``. It shall be * * * a valid node number, * * * the constant #RTEMS_SEARCH_ALL_NODES to search in all nodes, * * * the constant #RTEMS_SEARCH_LOCAL_NODE to search in the local node only, or * * * the constant #RTEMS_SEARCH_OTHER_NODES to search in all nodes except the * local node. * * @retval ::RTEMS_SUCCESSFUL The requested operation was successful. * * @retval ::RTEMS_INVALID_ADDRESS The ``id`` parameter was NULL. * * @retval ::RTEMS_INVALID_NAME There was no object with the specified name on * the specified nodes. * * @retval ::RTEMS_INVALID_NODE In multiprocessing configurations, the * specified node was invalid. * * @par Notes * @parblock * If the task name is not unique, then the task identifier will match the * first task with that name in the search order. However, this task * identifier is not guaranteed to correspond to the desired task. * * The objects are searched from lowest to the highest index. If ``node`` is * #RTEMS_SEARCH_ALL_NODES, all nodes are searched with the local node being * searched first. All other nodes are searched from lowest to the highest * node number. * * If node is a valid node number which does not represent the local node, then * only the tasks exported by the designated node are searched. * * This directive does not generate activity on remote nodes. It accesses only * the local copy of the global object table. * * The task identifier is used with other task related directives to access the * task. * @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_task_ident( rtems_name name, uint32_t node, rtems_id *id ); /* Generated from spec:/rtems/task/if/self */ /** * @ingroup RTEMSAPIClassicTasks * * @brief Gets the task identifier of the calling task. * * This directive returns the task identifier of the calling task. * * @return Returns the task identifier of the calling task. * * @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 will not cause the calling task to be preempted. * @endparblock */ rtems_id rtems_task_self( void ); /* Generated from spec:/rtems/task/if/start */ /** * @ingroup RTEMSAPIClassicTasks * * @brief Starts the task. * * @param id is the task identifier. The constant #RTEMS_SELF may be used to * specify the calling task. * * @param entry_point is the task entry point. * * @param argument is the task entry point argument. * * 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``. * * @retval ::RTEMS_SUCCESSFUL The requested operation was successful. * * @retval ::RTEMS_INVALID_ADDRESS The ``entry_point`` parameter was NULL. * * @retval ::RTEMS_INVALID_ID There was no task associated with the identifier * specified by ``id``. * * @retval ::RTEMS_INCORRECT_STATE The task was not in the dormant state. * * @retval ::RTEMS_ILLEGAL_ON_REMOTE_OBJECT The task resided on a remote node. * * @par Notes * @parblock * The type of the entry point argument is an unsigned integer type. However, * the integer type has the property that any valid pointer to ``void`` can be * converted to this type and then converted back to a pointer to ``void``. * The result will compare equal to the original pointer. The type can * represent at least 32 bits. Some applications use the entry point argument * as an index into a parameter table to get task-specific parameters. * * Any actions performed on a dormant task such as suspension or change of * priority are nullified when the task is initiated via the rtems_task_start() * directive. * @endparblock * * @par Constraints * @parblock * The following constraints apply to this directive: * * * The directive may be called from within interrupt context. * * * The directive may be called from within device driver initialization * context. * * * The directive may be called from within task context. * * * The directive may unblock a task. This may cause the calling task to be * preempted. * @endparblock */ rtems_status_code rtems_task_start( rtems_id id, rtems_task_entry entry_point, rtems_task_argument argument ); /* Generated from spec:/rtems/task/if/restart */ /** * @ingroup RTEMSAPIClassicTasks * * @brief Restarts the task. * * @param id is the task identifier. The constant #RTEMS_SELF may be used to * specify the calling task. * * @param argument is the task entry point argument. * * This directive resets the task specified by ``id`` to begin execution at its * original entry point. The task's priority and execution mode are set to the * original creation values. If the task is currently blocked, RTEMS * automatically makes the task ready. A task can be restarted from any state, * except the dormant state. The task's entry point argument is contained in * ``argument``. * * @retval ::RTEMS_SUCCESSFUL The requested operation was successful. * * @retval ::RTEMS_INVALID_ID There was no task associated with the identifier * specified by ``id``. * * @retval ::RTEMS_INCORRECT_STATE The task never started. * * @retval ::RTEMS_ILLEGAL_ON_REMOTE_OBJECT The task resided on a remote node. * * @par Notes * @parblock * The type of the entry point argument is an unsigned integer type. However, * the integer type has the property that any valid pointer to ``void`` can be * converted to this type and then converted back to a pointer to ``void``. * The result will compare equal to the original pointer. The type can * represent at least 32 bits. Some applications use the entry point argument * as an index into a parameter table to get task-specific parameters. * * A new entry point argument may be used to distinguish between the initial * rtems_task_start() of the task and any ensuing calls to rtems_task_restart() * of the task. This can be beneficial in deleting a task. Instead of * deleting a task using the rtems_task_delete() directive, a task can delete * another task by restarting that task, and allowing that task to release * resources back to RTEMS and then delete itself. * @endparblock * * @par Constraints * @parblock * The following constraints apply to this directive: * * * The directive may be called from within interrupt context. * * * The directive may be called from within device driver initialization * context. * * * The directive may be called from within task context. * * * The directive may change the priority of a task. This may cause the * calling task to be preempted. * * * The directive may unblock a task. This may cause the calling task to be * preempted. * @endparblock */ rtems_status_code rtems_task_restart( rtems_id id, rtems_task_argument argument ); /* Generated from spec:/rtems/task/if/delete */ /** * @ingroup RTEMSAPIClassicTasks * * @brief Deletes the task. * * @param id is the task identifier. The constant #RTEMS_SELF may be used to * specify the calling task. * * This directive deletes the task, either the calling task or another task, as * specified by ``id``. * * @retval ::RTEMS_SUCCESSFUL The requested operation was successful. * * @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_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 * does not reclaim the following resources: region segments, partition * buffers, semaphores, timers, or rate monotonic periods. * * A task is responsible for releasing its resources back to RTEMS before * deletion. To insure proper deallocation of resources, a task should not be * deleted unless it is unable to execute or does not hold any RTEMS resources. * If a task holds RTEMS resources, the task should be allowed to deallocate * its resources before deletion. A task can be directed to release its * 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 * another task to execute. * * The TCB for the deleted task is reclaimed by RTEMS. * * 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 * object table. * * The task must reside on the local node, even if the task was created with * the #RTEMS_GLOBAL attribute. * @endparblock * * @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. * * * When the directive operates on a global object, the directive sends a * message to remote nodes. This may preempt the calling task. * * * The calling task does not have to be the task that created the object. * Any local task that knows the object identifier can delete the object. * * * Where the object class corresponding to the directive is configured to use * unlimited objects, the directive may free memory to the RTEMS Workspace. * @endparblock */ rtems_status_code rtems_task_delete( rtems_id id ); /* Generated from spec:/rtems/task/if/exit */ /** * @ingroup RTEMSAPIClassicTasks * * @brief Deletes the calling task. * * This directive deletes the calling task. * * @par Notes * @parblock * The directive is an optimized variant of the following code sequences, see * also rtems_task_delete(): * * @code * #include * #include * * void classic_delete_self( void ) * { * (void) rtems_task_delete( RTEMS_SELF ); * } * * void posix_delete_self( void ) * { * (void) pthread_detach( pthread_self() ); * (void) pthread_exit( NULL); * } * @endcode * @endparblock * * @par Constraints * @parblock * The following constraints apply to this directive: * * * The directive may be called from within task context. * * * The directive will not return to the caller. * * * While thread dispatching is disabled, if the directive performs a thread * dispatch, then the fatal error with the fatal source INTERNAL_ERROR_CORE * and the fatal code INTERNAL_ERROR_BAD_THREAD_DISPATCH_DISABLE_LEVEL will * occur. * @endparblock */ RTEMS_NO_RETURN void rtems_task_exit( void ); /* Generated from spec:/rtems/task/if/suspend */ /** * @ingroup RTEMSAPIClassicTasks * * @brief Suspends the task. * * @param id is the task identifier. The constant #RTEMS_SELF may be used to * specify the calling task. * * This directive suspends the task specified by ``id`` from further execution * by placing it in the suspended state. This state is additive to any other * blocked state that the task may already be in. The task will not execute * again until another task issues the rtems_task_resume() directive for this * task and any blocked state has been removed. The rtems_task_restart() * directive will also remove the suspended state. * * @retval ::RTEMS_SUCCESSFUL The requested operation was successful. * * @retval ::RTEMS_INVALID_ID There was no task associated with the identifier * specified by ``id``. * * @retval ::RTEMS_ALREADY_SUSPENDED The task was already suspended. * * @retval ::RTEMS_ILLEGAL_ON_REMOTE_OBJECT The task resided on a remote node. * * @par Notes * The requesting task can suspend itself for example by specifying #RTEMS_SELF * as ``id``. In this case, the task will be suspended and a successful return * code will be returned when the task is resumed. * * @par Constraints * @parblock * The following constraints apply to this directive: * * * The directive may be called from within interrupt context. * * * The directive may be called from within device driver initialization * context. * * * The directive may be called from within task context. * * * When the directive operates on a remote object, the directive sends a * message to the remote node and waits for a reply. This will preempt the * calling task. * @endparblock */ rtems_status_code rtems_task_suspend( rtems_id id ); /* Generated from spec:/rtems/task/if/resume */ /** * @ingroup RTEMSAPIClassicTasks * * @brief Resumes the task. * * @param id is the task identifier. * * This directive removes the task specified by ``id`` from the suspended * state. If the task is in the ready state after the suspension is removed, * then it will be scheduled to run. If the task is still in a blocked state * after the suspension is removed, then it will remain in that blocked state. * * @retval ::RTEMS_SUCCESSFUL The requested operation was successful. * * @retval ::RTEMS_INVALID_ID There was no task associated with the identifier * specified by ``id``. * * @retval ::RTEMS_INCORRECT_STATE The task was not suspended. * * @par Constraints * @parblock * The following constraints apply to this directive: * * * The directive may be called from within interrupt context. * * * The directive may be called from within device driver initialization * context. * * * The directive may be called from within task context. * * * The directive may unblock a task. This may cause the calling task to be * preempted. * * * When the directive operates on a remote object, the directive sends a * message to the remote node and waits for a reply. This will preempt the * calling task. * @endparblock */ rtems_status_code rtems_task_resume( rtems_id id ); /* Generated from spec:/rtems/task/if/is-suspended */ /** * @ingroup RTEMSAPIClassicTasks * * @brief Checks if the task is suspended. * * @param id is the task identifier. The constant #RTEMS_SELF may be used to * specify the calling task. * * This directive returns a status code indicating whether or not the task * specified by ``id`` is currently suspended. * * @retval ::RTEMS_SUCCESSFUL The task was **not** suspended. * * @retval ::RTEMS_INVALID_ID There was no task associated with the identifier * specified by ``id``. * * @retval ::RTEMS_ALREADY_SUSPENDED The task was suspended. * * @retval ::RTEMS_ILLEGAL_ON_REMOTE_OBJECT The task resided on a remote node. * * @par Constraints * @parblock * The following constraints apply to this directive: * * * The directive may be called from within interrupt context. * * * The directive may be called from within device driver initialization * context. * * * The directive may be called from within task context. * * * The directive will not cause the calling task to be preempted. * @endparblock */ rtems_status_code rtems_task_is_suspended( rtems_id id ); /* Generated from spec:/rtems/task/if/set-priority */ /** * @ingroup RTEMSAPIClassicTasks * * @brief Sets the real priority or gets the current priority of the task. * * @param id is the task identifier. The constant #RTEMS_SELF may be used to * specify the calling task. * * @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 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 * task's previous priority is returned in ``old_priority``. When * ``new_priority`` is #RTEMS_CURRENT_PRIORITY, the specified task's current * priority is returned in ``old_priority``. * * @retval ::RTEMS_SUCCESSFUL The requested operation was successful. * * @retval ::RTEMS_INVALID_ADDRESS The ``old_priority`` parameter was NULL. * * @retval ::RTEMS_INVALID_ID There was no task associated with the identifier * specified by ``id``. * * @retval ::RTEMS_INVALID_PRIORITY The task priority specified in * ``new_priority`` was invalid with respect to the home scheduler of the * task. * * @par Notes * @parblock * Valid priorities range from one to a maximum value which depends on the * configured scheduler. The lower the priority value the higher is the * importance of the task. * * If the task is currently holding any binary semaphores which use a locking * protocol, then the task's priority cannot be lowered immediately. If the * task's priority were lowered immediately, then this could violate properties * of the locking protocol and may result in priority inversion. The requested * lowering of the task's priority will occur when the task has released all * binary semaphores which make the task more important. The task's priority * can be increased regardless of the task's use of binary semaphores with * locking protocols. * @endparblock * * @par Constraints * @parblock * The following constraints apply to this directive: * * * The directive may be called from within interrupt context. * * * The directive may be called from within device driver initialization * context. * * * The directive may be called from within task context. * * * The directive may change the priority of a task. This may cause the * calling task to be preempted. * * * When the directive operates on a remote object, the directive sends a * message to the remote node and waits for a reply. This will preempt the * calling task. * @endparblock */ rtems_status_code rtems_task_set_priority( rtems_id id, rtems_task_priority new_priority, rtems_task_priority *old_priority ); /* Generated from spec:/rtems/task/if/get-priority */ /** * @ingroup RTEMSAPIClassicTasks * * @brief Gets the current priority of the task with respect to the scheduler. * * @param task_id is the task identifier. The constant #RTEMS_SELF may be used * to specify the calling task. * * @param scheduler_id is the scheduler identifier. * * @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 object. * * This directive returns the current priority in ``priority`` of the task * specified by ``task_id`` with respect to the scheduler specified by * ``scheduler_id``. * * @retval ::RTEMS_SUCCESSFUL The requested operation was successful. * * @retval ::RTEMS_INVALID_ADDRESS The ``priority`` parameter was NULL. * * @retval ::RTEMS_INVALID_ID There was no task associated with the identifier * specified by ``task_id``. * * @retval ::RTEMS_INVALID_ID There was no scheduler associated with the * identifier specified by ``scheduler_id``. * * @retval ::RTEMS_NOT_DEFINED The task had no priority with respect to the * scheduler. * * @retval ::RTEMS_ILLEGAL_ON_REMOTE_OBJECT The task resided on a remote node. * * @par Notes * The current priority reflects temporary priority adjustments due to locking * protocols, the rate-monotonic period objects on some schedulers such as EDF, * and the POSIX sporadic server. * * @par Constraints * @parblock * The following constraints apply to this directive: * * * The directive may be called from within interrupt context. * * * The directive may be called from within device driver initialization * context. * * * The directive may be called from within task context. * * * The directive will not cause the calling task to be preempted. * @endparblock */ rtems_status_code rtems_task_get_priority( rtems_id task_id, rtems_id scheduler_id, rtems_task_priority *priority ); /* Generated from spec:/rtems/task/if/mode */ /** * @ingroup RTEMSAPIClassicTasks * * @brief Gets and optionally sets the mode of the calling task. * * @param mode_set is the mode set to apply to the calling task. When ``mask`` * is set to #RTEMS_CURRENT_MODE, the value of this parameter is ignored. * Only modes requested by ``mask`` are applied to the calling task. * * @param mask is the mode mask which specifies which modes in ``mode_set`` are * 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 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 object. * * This directive queries and optionally manipulates the execution mode of the * calling task. A task's execution mode enables and disables preemption, * timeslicing, asynchronous signal processing, as well as specifying the * interrupt level. To modify an execution mode, the mode class(es) to be * changed must be specified in the ``mask`` parameter and the desired mode(s) * must be specified in the ``mode_set`` parameter. * * A task can obtain its current execution mode, without modifying it, by * calling this directive with a ``mask`` value of #RTEMS_CURRENT_MODE. * * The **mode set** specified in ``mode_set`` is built through a *bitwise or* * of the mode constants described below. Not all combinations of modes are * allowed. Some modes are mutually exclusive. If mutually exclusive modes * are combined, the behaviour is undefined. Default task modes can be * selected by using the #RTEMS_DEFAULT_MODES constant. The task mode set * defines * * * the preemption mode of the task: #RTEMS_PREEMPT (default) or * #RTEMS_NO_PREEMPT, * * * the timeslicing mode of the task: #RTEMS_TIMESLICE or #RTEMS_NO_TIMESLICE * (default), * * * the ASR processing mode of the task: #RTEMS_ASR (default) or * #RTEMS_NO_ASR, * * * the interrupt level of the task: RTEMS_INTERRUPT_LEVEL() with a default of * ``RTEMS_INTERRUPT_LEVEL( 0 )`` which is associated with enabled * interrupts. * * The **mode mask** specified in ``mask`` is built through a *bitwise or* of * the mode mask constants described below. * * When the #RTEMS_PREEMPT_MASK is set in ``mask``, the **preemption mode** of * the calling task is * * * enabled by using the #RTEMS_PREEMPT mode constant in ``mode_set`` and * * * disabled by using the #RTEMS_NO_PREEMPT mode constant in ``mode_set``. * * When the #RTEMS_TIMESLICE_MASK is set in ``mask``, the **timeslicing mode** * of the calling task is * * * enabled by using the #RTEMS_TIMESLICE mode constant in ``mode_set`` and * * * disabled by using the #RTEMS_NO_TIMESLICE mode constant in ``mode_set``. * * Enabling timeslicing has no effect if preemption is disabled. For a task to * be timesliced, that task must have both preemption and timeslicing enabled. * * When the #RTEMS_ASR_MASK is set in ``mask``, the **ASR processing mode** of * the calling task is * * * enabled by using the #RTEMS_ASR mode constant in ``mode_set`` and * * * disabled by using the #RTEMS_NO_ASR mode constant in ``mode_set``. * * When the #RTEMS_INTERRUPT_MASK is set in ``mask``, **interrupts** of the * calling task are * * * enabled by using the RTEMS_INTERRUPT_LEVEL() mode macro with a value of * zero (0) in ``mode_set`` and * * * disabled up to the specified level by using the RTEMS_INTERRUPT_LEVEL() * mode macro with a positive value in ``mode_set``. * * An interrupt level of zero is associated with enabled interrupts on all * target processors. The interrupt level portion of the task mode supports a * maximum of 256 interrupt levels. These levels are mapped onto the interrupt * levels actually supported by the target processor in a processor dependent * fashion. * * @retval ::RTEMS_SUCCESSFUL The requested operation was successful. * * @retval ::RTEMS_NOT_IMPLEMENTED The #RTEMS_NO_PREEMPT was set in * ``mode_set`` and setting the preemption mode was requested by * #RTEMS_PREEMPT_MASK in ``mask`` and the system configuration had no * implementation for this mode. * * @retval ::RTEMS_NOT_IMPLEMENTED The RTEMS_INTERRUPT_LEVEL() was set to a * positive level in ``mode_set`` and setting the interrupt level was * requested by #RTEMS_INTERRUPT_MASK in ``mask`` and the system * configuration had no implementation for this mode. * * @par Constraints * @parblock * The following constraints apply to this directive: * * * The directive may be called from within task context. * * * When the directive enables preemption for the calling task, another task * may preempt the calling task. * * * While thread dispatching is disabled, if the directive performs a thread * dispatch, then the fatal error with the fatal source INTERNAL_ERROR_CORE * and the fatal code INTERNAL_ERROR_BAD_THREAD_DISPATCH_DISABLE_LEVEL will * occur. * @endparblock */ rtems_status_code rtems_task_mode( rtems_mode mode_set, rtems_mode mask, rtems_mode *previous_mode_set ); /* Generated from spec:/rtems/task/if/wake-after */ /** * @ingroup RTEMSAPIClassicTasks * * @brief Wakes up after an interval in clock ticks or yields the processor. * * @param ticks is the interval in 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 * give up the processor and remain in the ready state by specifying a value of * #RTEMS_YIELD_PROCESSOR in ``ticks``. * * @retval ::RTEMS_SUCCESSFUL The requested operation was successful. * * @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. * * @par Constraints * @parblock * The following constraints apply to this directive: * * * The directive may be called from within task context. * * * The directive requires a Clock Driver. * * * While thread dispatching is disabled, if the directive performs a thread * dispatch, then the fatal error with the fatal source INTERNAL_ERROR_CORE * and the fatal code INTERNAL_ERROR_BAD_THREAD_DISPATCH_DISABLE_LEVEL will * occur. * @endparblock */ rtems_status_code rtems_task_wake_after( rtems_interval ticks ); /* Generated from spec:/rtems/task/if/wake-when */ /** * @ingroup RTEMSAPIClassicTasks * * @brief Wakes up when specified. * * @param time_buffer is the date and time to wake up. * * This directive blocks a task until the date and time specified in * ``time_buffer``. At the requested date and time, the calling task will be * unblocked and made ready to execute. * * @retval ::RTEMS_SUCCESSFUL The requested operation was successful. * * @retval ::RTEMS_NOT_DEFINED The system date and time was not set. * * @retval ::RTEMS_INVALID_ADDRESS The ``time_buffer`` parameter was NULL. * * @retval ::RTEMS_INVALID_CLOCK The time of day was invalid. * * @par Notes * The ticks portion of ``time_buffer`` structure is ignored. The timing * granularity of this directive is a second. * * @par Constraints * @parblock * The following constraints apply to this directive: * * * The directive may be called from within task context. * * * The directive requires a Clock Driver. * * * While thread dispatching is disabled, if the directive performs a thread * dispatch, then the fatal error with the fatal source INTERNAL_ERROR_CORE * and the fatal code INTERNAL_ERROR_BAD_THREAD_DISPATCH_DISABLE_LEVEL will * occur. * @endparblock */ rtems_status_code rtems_task_wake_when( const rtems_time_of_day *time_buffer ); /* Generated from spec:/rtems/task/if/get-scheduler */ /** * @ingroup RTEMSAPIClassicTasks * * @brief Gets the home scheduler of the task. * * @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 object. When the * directive call is successful, the identifier of the home scheduler of the * 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``. * * @retval ::RTEMS_SUCCESSFUL The requested operation was successful. * * @retval ::RTEMS_INVALID_ADDRESS The ``scheduler_id`` parameter was NULL. * * @retval ::RTEMS_INVALID_ID There was no task associated with the identifier * specified by ``task_id``. * * @retval ::RTEMS_ILLEGAL_ON_REMOTE_OBJECT The task resided on a remote node. * * @par Constraints * @parblock * The following constraints apply to this directive: * * * The directive may be called from within interrupt context. * * * The directive may be called from within device driver initialization * context. * * * The directive may be called from within task context. * * * The directive will not cause the calling task to be preempted. * @endparblock */ rtems_status_code rtems_task_get_scheduler( rtems_id task_id, rtems_id *scheduler_id ); /* Generated from spec:/rtems/task/if/set-scheduler */ /** * @ingroup RTEMSAPIClassicTasks * * @brief Sets the home scheduler for the task. * * @param task_id is the task identifier. The constant #RTEMS_SELF may be used * to specify the calling task. * * @param scheduler_id is the scheduler identifier of the new home scheduler * for the task specified by ``task_id``. * * @param priority is the new real priority for the task with respect to the * scheduler specified by ``scheduler_id``. * * This directive sets the home scheduler to the scheduler specified by * ``scheduler_id`` for the task specified by ``task_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_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 * @parblock * The following constraints apply to this directive: * * * The directive may be called from within interrupt context. * * * The directive may be called from within device driver initialization * context. * * * The directive may be called from within task context. * * * The directive may change the priority of a task. This may cause the * calling task to be preempted. * @endparblock */ rtems_status_code rtems_task_set_scheduler( rtems_id task_id, rtems_id scheduler_id, rtems_task_priority priority ); /* Generated from spec:/rtems/task/if/get-affinity */ /** * @ingroup RTEMSAPIClassicTasks * * @brief Gets the processor affinity of the task. * * @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 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 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. * * This directive returns the processor affinity of the task in ``cpuset`` of * the task specified by ``id``. * * @retval ::RTEMS_SUCCESSFUL The requested operation was successful. * * @retval ::RTEMS_INVALID_ADDRESS The ``cpuset`` parameter was NULL. * * @retval ::RTEMS_INVALID_ID There was no task associated with the identifier * specified by ``id``. * * @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. * * @par Constraints * @parblock * The following constraints apply to this directive: * * * The directive may be called from within interrupt context. * * * The directive may be called from within device driver initialization * context. * * * The directive may be called from within task context. * * * The directive will not cause the calling task to be preempted. * @endparblock */ rtems_status_code rtems_task_get_affinity( rtems_id id, size_t cpusetsize, cpu_set_t *cpuset ); /* Generated from spec:/rtems/task/if/set-affinity */ /** * @ingroup RTEMSAPIClassicTasks * * @brief Sets the processor affinity of the task. * * @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 processor set referenced by ``cpuset`` * in bytes. * * @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. * * This directive sets the processor affinity of the task specified by ``id``. * * @retval ::RTEMS_SUCCESSFUL The requested operation was successful. * * @retval ::RTEMS_INVALID_ADDRESS The ``cpuset`` parameter was NULL. * * @retval ::RTEMS_INVALID_ID There was no task associated with the identifier * specified by ``id``. * * @retval ::RTEMS_INVALID_NUMBER The referenced processor set was not a valid * new processor affinity set for the task. * * @retval ::RTEMS_ILLEGAL_ON_REMOTE_OBJECT The task resided on a remote node. * * @par Constraints * @parblock * The following constraints apply to this directive: * * * The directive may be called from within interrupt context. * * * The directive may be called from within device driver initialization * context. * * * The directive may be called from within task context. * * * The directive may change the processor affinity of a task. This may cause * the calling task to be preempted. * @endparblock */ rtems_status_code rtems_task_set_affinity( rtems_id id, size_t cpusetsize, const cpu_set_t *cpuset ); /* Generated from spec:/rtems/task/if/iterate */ /** * @ingroup RTEMSAPIClassicTasks * * @brief Iterates over all tasks and invokes the visitor routine for each * task. * * @param visitor is the visitor routine invoked for each task. * * @param arg is the argument passed to each visitor routine invocation during * the iteration. * * This directive iterates over all tasks in the system. This operation covers * all tasks of all APIs. The user should be careful in accessing the contents * of the TCB. The visitor argument ``arg`` is passed to all invocations of * ``visitor`` in addition to the TCB. The iteration stops immediately in case * the visitor routine returns true. * * @par Notes * The visitor routine is invoked while owning the objects allocator lock. It * is allowed to perform blocking operations in the visitor routine, however, * care must be taken so that no deadlocks via the object allocator lock can * occur. * * @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 */ void rtems_task_iterate( rtems_task_visitor visitor, void *arg ); #ifdef __cplusplus } #endif #endif /* _RTEMS_RTEMS_TASKS_H */