From a1679af38053ec37f3e8c4d71f4f175fd58ce754 Mon Sep 17 00:00:00 2001 From: Sebastian Huber Date: Mon, 15 Jun 2020 11:10:02 +0200 Subject: rtems: Generate Change license to BSD-2-Clause according to file histories and documentation re-licensing agreement. Update #3899. Update #3993. --- cpukit/include/rtems/rtems/mainpage.h | 2 +- cpukit/include/rtems/rtems/tasks.h | 2695 +++++++++++++++++++++++++-------- 2 files changed, 2023 insertions(+), 674 deletions(-) diff --git a/cpukit/include/rtems/rtems/mainpage.h b/cpukit/include/rtems/rtems/mainpage.h index 2209d56bd4..05bae7fe70 100644 --- a/cpukit/include/rtems/rtems/mainpage.h +++ b/cpukit/include/rtems/rtems/mainpage.h @@ -651,7 +651,7 @@ */ /** - * @addtogroup ClassicTasks + * @addtogroup RTEMSAPIClassicTasks * * @section ClassicTasksSecTaskDefinition Task Definition * diff --git a/cpukit/include/rtems/rtems/tasks.h b/cpukit/include/rtems/rtems/tasks.h index f71cb1ec6b..cb620a4c09 100644 --- a/cpukit/include/rtems/rtems/tasks.h +++ b/cpukit/include/rtems/rtems/tasks.h @@ -1,231 +1,131 @@ +/* SPDX-License-Identifier: BSD-2-Clause */ + /** * @file * - * @ingroup ClassicTasks - * - * @brief Classic Task Manager API + * @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. */ /* - * COPYRIGHT (c) 1989-2014. - * On-Line Applications Research Corporation (OAR). + * 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 * - * The license and distribution terms for this file may be - * found in the file LICENSE in this distribution or at - * http://www.rtems.org/license/LICENSE. + * 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 ClassicTasks Tasks + * @defgroup RTEMSAPIClassicScheduler Scheduler Manager * - * @ingroup RTEMSAPIClassic + * @ingroup RTEMSAPIClassic * - * This encapsulates the functionality of the Classic API Task Manager. - * This functionality includes task services such as creation, deletion, - * delays, suspend/resume, and manipulation of execution mode and priority. - */ -/**@{*/ - -/** - * Constant to be used as the ID of current task - */ -#define RTEMS_SELF OBJECTS_ID_OF_SELF - -/** - * This constant is passed to the rtems_task_wake_after directive as the - * interval when a task wishes to yield the CPU. - */ -#define RTEMS_YIELD_PROCESSOR WATCHDOG_NO_TIMEOUT - -/** - * @brief Minimum stack size which every thread must exceed. + * @brief The scheduling concepts relate to the allocation of processing time + * for tasks. * - * It is the minimum stack size recommended for use on this processor. This - * value is selected by the RTEMS developers 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. - */ -#define RTEMS_MINIMUM_STACK_SIZE STACK_MINIMUM_SIZE - -/** - * @brief Specifies that the task should be created with the configured minimum - * stack size. + * 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. * - * 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 the 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. - */ -#define RTEMS_CONFIGURED_MINIMUM_STACK_SIZE 0 - -/** - * Define the type for an RTEMS API task priority. - */ -typedef uint32_t rtems_task_priority; - -/** - * This is the constant used with the rtems_task_set_priority - * directive to indicate that the caller wants to obtain its - * current priority rather than set it as the name of the - * directive indicates. + * 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. */ -#define RTEMS_NO_PRIORITY RTEMS_CURRENT_PRIORITY -/** - * This constant is the least valid value for a Classic API - * task priority. - */ -#define RTEMS_MINIMUM_PRIORITY 1 - -rtems_task_priority _RTEMS_Maximum_priority( void ); +/* Generated from spec:/rtems/task/if/group */ /** - * This run-time constant is the maximum valid value for a Classic API - * task priority. + * @defgroup RTEMSAPIClassicTasks Task Manager * - * @note This is actually the priority of the IDLE thread so - * using this priority will result in having a task - * which never executes. This could be useful if you - * want to ensure that a task does not executes during - * certain operations such as a system mode change. - */ -#define RTEMS_MAXIMUM_PRIORITY _RTEMS_Maximum_priority() - -/** - * The following constant is passed to rtems_task_set_priority when the - * caller wants to obtain the current priority. - */ -#define RTEMS_CURRENT_PRIORITY 0 - -struct _Thread_Control; - -/** - * External API name for Thread_Control - */ -typedef struct _Thread_Control rtems_tcb; - -/** - * The following defines the "return type" of an RTEMS task. - */ -typedef void rtems_task; - -/** - * The following defines the argument to an RTEMS task. - */ -typedef CPU_Uint32ptr rtems_task_argument; - -/** - * The following defines the type for the entry point of an RTEMS task. + * @ingroup RTEMSAPIClassic + * + * @brief The Task Manager provides a comprehensive set of directives to + * create, delete, and administer tasks. */ -typedef rtems_task ( *rtems_task_entry )( - rtems_task_argument - ); -/** - * The following records define the Initialization Tasks Table. - * Each entry contains the information required by RTEMS to - * create and start a user task automatically at executive - * initialization time. - */ -typedef struct { - /** This is the Initialization Task's name. */ - rtems_name name; - /** This is the Initialization Task's stack size. */ - size_t stack_size; - /** This is the Initialization Task's priority. */ - rtems_task_priority initial_priority; - /** This is the Initialization Task's attributes. */ - rtems_attribute attribute_set; - /** This is the Initialization Task's entry point. */ - rtems_task_entry entry_point; - /** This is the Initialization Task's initial mode. */ - rtems_mode mode_set; - /** This is the Initialization Task's argument. */ - rtems_task_argument argument; -} rtems_initialization_tasks_table; +/* Generated from spec:/rtems/task/if/argument */ /** - * @brief RTEMS Task Create + * @ingroup RTEMSAPIClassicTasks * - * This routine implements the rtems_task_create directive. The task - * will have the name name. The attribute_set can be used to indicate - * that the task will be globally accessible or utilize floating point. - * The task's stack will be stack_size bytes. The task will begin - * execution with initial_priority and initial_modes. It returns the - * id of the created task in ID. + * @brief This integer type represents task argument values. * - * @param[in] name is the user defined thread name - * @param[in] initial_priority is the thread priority - * @param[in] stack_size is the stack size in bytes - * @param[in] initial_modes is the initial thread mode - * @param[in] attribute_set is the thread attributes - * @param[in] id is the pointer to thread id - * - * @retval RTEMS_SUCCESSFUL if successful or error code if unsuccessful - * and *id thread id filled in + * @par Notes + * The type is an architecture-specific unsigned integer type which is large + * enough to represent pointer values and 32-bit unsigned integers. */ -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 -); +typedef CPU_Uint32ptr rtems_task_argument; -/** - * @brief This constant defines the recommended alignment of a task storage - * area in bytes. - * - * 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/config */ /** - * @brief Returns the recommended task storage area size for the specified 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. + * @ingroup RTEMSAPIClassicTasks * - * @return The recommended task storage area size calculated from the input - * parameters is returned. - */ -#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 - -/** * @brief This structure defines the configuration of a task constructed by * rtems_task_construct(). */ @@ -310,554 +210,585 @@ typedef struct { rtems_attribute attributes; } rtems_task_config; +/* Generated from spec:/rtems/task/if/configured-minimum-stack-size */ + /** - * @brief Constructs a task from the specified the task configuration. - * - * 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(). - * - * @param config is the task configuration. - * - * @param[out] id is the pointer to an object identifier variable. The - * identifier of the constructed task object will be stored in this variable, - * in case of a successful operation. - * - * @retval ::RTEMS_SUCCESSFUL The requested operation was successful. - * - * @retval ::RTEMS_INVALID_ADDRESS The id parameter was NULL. - * - * @retval ::RTEMS_INVALID_NAME The task name was invalid. - * - * @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. + * @ingroup RTEMSAPIClassicTasks * - * @retval ::RTEMS_UNSATISFIED In SMP configurations, the non-preemption mode - * was not supported. + * @brief This constant can be used to indicate that the task should be created + * with the configured minimum stack size. * - * @retval ::RTEMS_UNSATISFIED In SMP configurations, the interrupt level mode - * was not supported. + * 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. */ -rtems_status_code rtems_task_construct( - const rtems_task_config *config, - rtems_id *id -); +#define RTEMS_CONFIGURED_MINIMUM_STACK_SIZE 0 + +/* Generated from spec:/rtems/task/if/current-priority */ /** - * @brief RTEMS Task Name to Id - * - * This routine implements the rtems_task_ident directive. - * This directive returns the task ID associated with name. - * If more than one task is named name, then the task to - * which the ID belongs is arbitrary. node indicates the - * extent of the search for the ID of the task named name. - * The search can be limited to a particular node or allowed to - * encompass all nodes. - * - * @param[in] name is the user defined thread name - * @param[in] node is(are) the node(s) to be searched - * @param[in] id is the pointer to thread id + * @ingroup RTEMSAPIClassicTasks * - * @retval This method returns RTEMS_SUCCESSFUL if there was not an - * error. Otherwise, a status code is returned indicating the - * source of the error. If successful, the id will - * be filled in with the thread id. + * @brief This constant is passed to {set-priority:/name} when the caller wants + * to obtain the current priority. */ -rtems_status_code rtems_task_ident( - rtems_name name, - uint32_t node, - rtems_id *id -); +#define RTEMS_CURRENT_PRIORITY 0 + +/* Generated from spec:/rtems/task/if/task */ /** - * @brief RTEMS Delete Task - * - * This routine implements the rtems_task_delete directive. The - * task indicated by ID is deleted. The executive halts execution - * of the thread and frees the thread control block. + * @ingroup RTEMSAPIClassicTasks * - * @param[in] id is the thread id + * @brief This type defines the return type of task entry points. * - * @retval This method returns RTEMS_SUCCESSFUL if there was not an - * error and id is not the requesting thread. Status code is - * returned indicating the source of the error. Nothing - * is returned if id is the requesting thread (always succeeds). + * This type can be used to document task entry points in the source code. */ -rtems_status_code rtems_task_delete( - rtems_id id -); +typedef void rtems_task; -RTEMS_NO_RETURN void rtems_task_exit( void ); +/* Generated from spec:/rtems/task/if/entry */ /** - * @brief RTEMS Task Mode - * - * This routine implements the rtems_task_mode directive. The current - * values of the modes indicated by mask of the calling task are changed - * to that indicated in mode_set. The former mode of the task is - * returned in mode_set. + * @ingroup RTEMSAPIClassicTasks * - * @param[in] mode_set is the new mode - * @param[in] mask is the mask - * @param[in] previous_mode_set is the address of previous mode set - * - * @retval RTEMS_SUCCESSFUL and previous_mode_set filled in with the - * previous mode set + * @brief This type defines the entry point of an RTEMS task. */ -rtems_status_code rtems_task_mode( - rtems_mode mode_set, - rtems_mode mask, - rtems_mode *previous_mode_set -); +typedef rtems_task ( *rtems_task_entry )( rtems_task_argument ); + +/* Generated from spec:/rtems/task/if/initialization-table */ /** - * @brief RTEMS Task Restart - * - * This routine implements the rtems_task_restart directive. The - * task associated with ID is restarted at its initial entry - * point with the new argument. + * @ingroup RTEMSAPIClassicTasks * - * @param[in] id is the thread id - * @param[in] argument is the thread argument - * - * @retval RTEMS_SUCCESSFUL if successful or error code if unsuccessful + * @brief This structure defines the properties of the Classic API user + * initialization task. */ -rtems_status_code rtems_task_restart( - rtems_id id, - rtems_task_argument argument -); +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 */ /** - * @brief RTEMS Suspend Task - * - * This routine implements the rtems_task_suspend directive. The - * SUSPENDED state is set for task associated with ID. Note that the - * suspended state can be in addition to other waiting states. + * @ingroup RTEMSAPIClassicTasks * - * @param[in] id is the thread id - * - * @retval This method returns RTEMS_SUCCESSFUL if there was not an - * error. Otherwise, a status code is returned indicating the - * source of the error. + * @brief This compile time constant provides the highest (most important) task + * priority settable by the API. */ -rtems_status_code rtems_task_suspend( - rtems_id id -); +#define RTEMS_MINIMUM_PRIORITY 1 + +/* Generated from spec:/rtems/task/if/minimum-stack-size */ /** - * @brief RTEMS Resume Task - * - * This routine implements the rtems_task_resume Directive. The - * SUSPENDED state is cleared for task associated with ID. + * @ingroup RTEMSAPIClassicTasks * - * @param[in] id is the thread id + * @brief This compile time constant provides the minimum task stack size + * recommended for the target architecture. * - * @retval This method returns RTEMS_SUCCESSFUL if there was not an - * error. Otherwise, a status code is returned indicating the - * source of the error. + * 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. */ -rtems_status_code rtems_task_resume( - rtems_id id -); +#define RTEMS_MINIMUM_STACK_SIZE STACK_MINIMUM_SIZE + +/* Generated from spec:/rtems/task/if/no-priority */ /** - * @brief RTEMS Set Task Priority - * - * This routine implements the rtems_task_set_priority directive. The - * current priority of the task associated with ID is set to - * new_priority. The former priority of that task is returned - * in old_priority. + * @ingroup RTEMSAPIClassicTasks * - * @param[in] id is the thread to extract - * @param[in] new_priority is the thread to extract - * @param[in] old_priority is the thread to extract - * - * @retval RTEMS_SUCCESSFUL if successful or error code if unsuccessful and - * and *old_priority filled in with the previous previous priority + * @brief This compile time constant may be used for the + * rtems_task_set_priority() directive to get the current task priority. */ -rtems_status_code rtems_task_set_priority( - rtems_id id, - rtems_task_priority new_priority, - rtems_task_priority *old_priority -); +#define RTEMS_NO_PRIORITY RTEMS_CURRENT_PRIORITY + +/* Generated from spec:/rtems/task/if/self-define */ /** - * @brief Gets the current priority of the specified task with respect to the - * specified scheduler instance. - * - * The current priority reflects temporary priority adjustments due to locking - * protocols, the rate-monotonic period objects on some schedulers and other - * mechanisms. - * - * @param[in] task_id Identifier of the task. Use @ref RTEMS_SELF to select - * the executing task. - * @param[in] scheduler_id Identifier of the scheduler instance. - * @param[out] priority Returns the current priority of the specified task with - * respect to the specified scheduler instance. - * - * @retval RTEMS_SUCCESSFUL Successful operation. - * @retval RTEMS_ILLEGAL_ON_REMOTE_OBJECT Directive is illegal on remote tasks. - * @retval RTEMS_INVALID_ADDRESS The priority parameter is @c NULL. - * @retval RTEMS_INVALID_ID Invalid task or scheduler identifier. - * @retval RTEMS_NOT_DEFINED The task has no priority within the specified - * scheduler instance. This error is only possible on SMP configurations. + * @ingroup RTEMSAPIClassicTasks * - * @see rtems_scheduler_ident(). + * @brief This compile time constant may be used to identify the calling task + * in task related directives. */ -rtems_status_code rtems_task_get_priority( - rtems_id task_id, - rtems_id scheduler_id, - rtems_task_priority *priority -); +#define RTEMS_SELF OBJECTS_ID_OF_SELF + +/* Generated from spec:/rtems/task/if/storage-alignment */ /** - * @brief RTEMS Start Task + * @ingroup RTEMSAPIClassicTasks * - * RTEMS Task Manager + * @brief This compile time constant defines the recommended alignment of a + * task storage area in bytes. * - * This routine implements the rtems_task_start directive. The - * starting execution point of the task associated with ID is - * set to entry_point with the initial argument. + * @par Notes + * Use it with RTEMS_ALIGNED() to define the alignment of a statically + * allocated task storage area. */ -rtems_status_code rtems_task_start( - rtems_id id, - rtems_task_entry entry_point, - rtems_task_argument argument -); +#define RTEMS_TASK_STORAGE_ALIGNMENT CPU_STACK_ALIGNMENT + +/* Generated from spec:/rtems/task/if/storage-size */ /** - * @brief RTEMS Task Wake When + * @ingroup RTEMSAPIClassicTasks + * + * @brief Gets the recommended task storage area size for the size and task + * attributes. * - * This routine implements the rtems_task_wake_when directive. The - * calling task is blocked until the current time of day is - * equal to that indicated by time_buffer. + * @param _size is the size dedicated to the task stack and thread-local + * storage in bytes. * - * @param[in] time_buffer is the pointer to the time and date structure + * @param _attributes is the attribute set of the task using the storage area. * - * @retval RTEMS_SUCCESSFUL if successful or error code if unsuccessful + * @return Returns the recommended task storage area size calculated from the + * input parameters. */ -rtems_status_code rtems_task_wake_when( - rtems_time_of_day *time_buffer -); +#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 */ /** - * @brief RTEMS Task Wake After + * @ingroup RTEMSAPIClassicTasks * - * This routine implements the rtems_task_wake_after directive. The - * calling task is blocked until the indicated number of clock - * ticks have occurred. - * - * @param[in] ticks is the number of ticks to wait - * @retval RTEMS_SUCCESSFUL + * @brief This structure represents the TCB. */ -rtems_status_code rtems_task_wake_after( - rtems_interval ticks -); +typedef struct _Thread_Control rtems_tcb; + +/* Generated from spec:/rtems/task/if/visitor */ /** - * @brief rtems_task_is_suspended + * @ingroup RTEMSAPIClassicTasks * - * This directive returns a status indicating whether or not - * the specified task is suspended. + * @brief Visitor routines invoked by rtems_task_iterate() shall have this + * type. */ -rtems_status_code rtems_task_is_suspended( - rtems_id id -); +typedef bool( *rtems_task_visitor )( rtems_tcb *, void * ); + +/* Generated from spec:/rtems/task/if/yield-processor */ /** - * @brief Gets the processor affinity set of a task. + * @ingroup RTEMSAPIClassicTasks * - * @param[in] id Identifier of the task. Use @ref RTEMS_SELF to select the - * executing task. - * @param[in] cpusetsize Size of the specified affinity set buffer in - * bytes. This value must be positive. - * @param[out] cpuset The current processor affinity set of the task. A set - * bit in the affinity set means that the task can execute on this processor - * and a cleared bit means the opposite. - * - * @retval RTEMS_SUCCESSFUL Successful operation. - * @retval RTEMS_INVALID_ADDRESS The @a cpuset parameter is @c NULL. - * @retval RTEMS_INVALID_ID Invalid task identifier. - * @retval RTEMS_INVALID_NUMBER The affinity set buffer is too small for the - * current processor affinity set of the task. + * @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. */ -rtems_status_code rtems_task_get_affinity( - rtems_id id, - size_t cpusetsize, - cpu_set_t *cpuset -); +#define RTEMS_YIELD_PROCESSOR WATCHDOG_NO_TIMEOUT + +/* Generated from spec:/score/if/maximum-priority */ /** - * @brief Sets the processor affinity set of a task. - * - * This function will not change the scheduler of the task. The intersection - * of the processor affinity set and the set of processors owned by the - * scheduler of the task must be non-empty. It is not an error if the - * processor affinity set contains processors that are not part of the set of - * processors owned by the scheduler instance of the task. A task will simply - * not run under normal circumstances on these processors since the scheduler - * ignores them. Some locking protocols may temporarily use processors that - * are not included in the processor affinity set of the task. It is also not - * an error if the processor affinity set contains processors that are not part - * of the system. - * - * @param[in] id Identifier of the task. Use @ref RTEMS_SELF to select the - * executing task. - * @param[in] cpusetsize Size of the specified affinity set buffer in - * bytes. This value must be positive. - * @param[in] cpuset The new processor affinity set for the task. A set bit in - * the affinity set means that the task can execute on this processor and a - * cleared bit means the opposite. - * - * @retval RTEMS_SUCCESSFUL Successful operation. - * @retval RTEMS_INVALID_ADDRESS The @a cpuset parameter is @c NULL. - * @retval RTEMS_INVALID_ID Invalid task identifier. - * @retval RTEMS_INVALID_NUMBER Invalid processor affinity set. + * @brief Returns the maximum priority of the scheduler with index zero. */ -rtems_status_code rtems_task_set_affinity( - rtems_id id, - size_t cpusetsize, - const cpu_set_t *cpuset -); +rtems_task_priority _RTEMS_Maximum_priority( void ); + +/* Generated from spec:/rtems/task/if/maximum-priority */ /** - * @brief Gets the scheduler of a task. - * - * @param[in] task_id Identifier of the task. Use @ref RTEMS_SELF to select - * the executing task. - * @param[out] scheduler_id Identifier of the scheduler instance. + * @ingroup RTEMSAPIClassicTasks * - * @retval RTEMS_SUCCESSFUL Successful operation. - * @retval RTEMS_INVALID_ADDRESS The @a scheduler_id parameter is @c NULL. - * @retval RTEMS_INVALID_ID Invalid task identifier. + * @brief This constant variable provides the lowest (least important) task + * priority of the first configured scheduler. */ -rtems_status_code rtems_task_get_scheduler( - rtems_id task_id, - rtems_id *scheduler_id -); +#define RTEMS_MAXIMUM_PRIORITY _RTEMS_Maximum_priority() + +/* Generated from spec:/rtems/scheduler/if/ident */ /** - * @brief Sets the scheduler instance of a task. + * @ingroup RTEMSAPIClassicScheduler * - * Initially, the scheduler instance of a task is set to the scheduler instance - * of the task that created it. This directive allows to move a task from its - * current scheduler instance to another specified by the scheduler identifier. + * @brief Identifies a scheduler by the object name. * - * @param[in] task_id Identifier of the task. Use @ref RTEMS_SELF to select - * the executing task. - * @param[in] scheduler_id Identifier of the scheduler instance. - * @param[in] priority The task priority with respect to the new scheduler - * instance. The real and initial priority of the task is set to this value. - * The initial priority is used by rtems_task_restart() for example. + * @param name is the scheduler name to look up. * - * @retval RTEMS_SUCCESSFUL Successful operation. - * @retval RTEMS_ILLEGAL_ON_REMOTE_OBJECT Directive is illegal on remote tasks. - * @retval RTEMS_INVALID_ID Invalid task or scheduler identifier. - * @retval RTEMS_INVALID_PRIORITY Invalid priority. - * @retval RTEMS_RESOURCE_IN_USE The task owns resources which deny a scheduler - * change. + * @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. * - * @see rtems_scheduler_ident(). - */ -rtems_status_code rtems_task_set_scheduler( - rtems_id task_id, - rtems_id scheduler_id, - rtems_task_priority priority -); - -/** - * @brief RTEMS Get Self Task Id + * 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 * - * This directive returns the ID of the currently executing task. + * @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_id rtems_task_self(void); +rtems_status_code rtems_scheduler_ident( rtems_name name, rtems_id *id ); + +/* Generated from spec:/rtems/scheduler/if/ident-by-processor */ /** - * @brief Task visitor. + * @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. * - * @param[in] tcb The task control block. - * @param[in] arg The visitor argument. + * @retval ::RTEMS_INVALID_ADDRESS The ``id`` parameter was NULL. * - * @retval true Stop the iteration. - * @retval false Otherwise. + * @retval ::RTEMS_INVALID_NAME The processor index was invalid. * - * @see rtems_task_iterate(). + * @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 */ -typedef bool ( *rtems_task_visitor )( rtems_tcb *tcb, void *arg ); +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 */ /** - * @brief Iterates over all tasks in the system. + * @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. * - * This operation covers all tasks of all APIs. + * @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. * - * Must be called from task context. This operation obtains and releases the - * objects allocator lock. The task visitor is called while owning the objects - * allocator lock. It is possible to perform blocking operations in the task - * visitor, however, take care that no deadlocks via the object allocator lock - * can occur. + * @par Constraints + * @parblock + * The following constraints apply to this directive: * - * @param[in] visitor The task visitor. - * @param[in] arg The visitor argument. + * * The directive may be called from within any runtime context. + * + * * The directive will not cause the calling task to be preempted. + * @endparblock */ -void rtems_task_iterate( - rtems_task_visitor visitor, - void *arg +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 */ + /** - * @brief Identifies a scheduler by its name. + * @ingroup RTEMSAPIClassicScheduler * - * The scheduler name is determined by the scheduler configuration. + * @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``. * - * @param[in] name The scheduler name. - * @param[out] id The scheduler identifier associated with the name. + * @retval ::RTEMS_INVALID_ADDRESS The ``priority`` parameter was NULL. * - * @retval RTEMS_SUCCESSFUL Successful operation. - * @retval RTEMS_INVALID_ADDRESS The @a id parameter is @c NULL. - * @retval RTEMS_INVALID_NAME Invalid scheduler name. + * @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 +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 */ + /** - * @brief Identifies a scheduler by a processor index. + * @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: * - * @param[in] cpu_index The processor index. - * @param[out] id The scheduler identifier associated with the processor index. + * * The directive may be called from within any runtime context. * - * @retval RTEMS_SUCCESSFUL Successful operation. - * @retval RTEMS_INVALID_ADDRESS The @a id parameter is @c NULL. - * @retval RTEMS_INVALID_NAME Invalid processor index. - * @retval RTEMS_INCORRECT_STATE The processor index is valid, however, this - * processor is not owned by a scheduler. + * * 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 +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 */ + /** - * @brief Identifies a scheduler by a processor set. + * @ingroup RTEMSAPIClassicScheduler * - * The scheduler is selected according to the highest numbered online processor - * in the specified processor set. + * @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. * - * @param[in] cpusetsize Size of the specified processor set buffer in - * bytes. This value must be positive. - * @param[out] cpuset The processor set to identify the scheduler. - * @param[out] id The scheduler identifier associated with the processor set. + * @par Constraints + * @parblock + * The following constraints apply to this directive: * - * @retval RTEMS_SUCCESSFUL Successful operation. - * @retval RTEMS_INVALID_ADDRESS The @a id parameter is @c NULL. - * @retval RTEMS_INVALID_SIZE Invalid processor set size. - * @retval RTEMS_INVALID_NAME The processor set contains no online processor. - * @retval RTEMS_INCORRECT_STATE The processor set is valid, however, the - * highest numbered online processor in the specified processor set is not - * owned by a scheduler. + * * 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 +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. * - * In uniprocessor configurations, a value of zero will be returned. + * 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. * - * In SMP configurations, an architecture specific method is used to obtain the - * index of the current processor in the system. The set of processor indices - * is the range of integers starting with zero up to the processor count 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. * - * @return The index of the current processor. + * @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. * - * In uniprocessor configurations, a value of one will be returned. + * 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). * - * In SMP configurations, this function returns the minimum of the processors - * (physically or virtually) available by the platform and the configured - * processor maximum. 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 online (online processors - * have a scheduler assigned). + * @return Returns the processor maximum supported by the system. * - * @return The processor maximum supported by the system. + * @par Constraints + * @parblock + * The following constraints apply to this directive: * - * @see rtems_scheduler_add_processor() and rtems_scheduler_remove_processor(). + * * 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 */ + /** - * @brief Gets the set of processors owned by the specified scheduler instance. + * @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[in] scheduler_id Identifier of the scheduler instance. - * @param[in] cpusetsize Size of the specified processor set buffer in - * bytes. This value must be positive. - * @param[out] cpuset The processor set owned by the scheduler. A set bit in - * the processor set means that this processor is owned by the scheduler and a - * cleared bit means the opposite. + * @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 Successful operation. - * @retval RTEMS_INVALID_ADDRESS The @a cpuset parameter is @c NULL. - * @retval RTEMS_INVALID_ID Invalid scheduler instance identifier. - * @retval RTEMS_INVALID_NUMBER The processor set buffer is too small for the - * set of processors owned by the scheduler. + * @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, @@ -865,111 +796,1529 @@ rtems_status_code rtems_scheduler_get_processor_set( cpu_set_t *cpuset ); +/* Generated from spec:/rtems/scheduler/if/add-processor */ + /** - * @brief Adds a processor to the set of processors owned by the specified - * scheduler instance. + * @ingroup RTEMSAPIClassicScheduler * - * Must be called from task context. This operation obtains and releases the - * objects allocator lock. + * @brief Adds the processor to the set of processors owned by the scheduler. * - * @param[in] scheduler_id Identifier of the scheduler instance. - * @param[in] cpu_index Index of the processor to add. + * @param scheduler_id is the scheduler identifier. * - * @retval RTEMS_SUCCESSFUL Successful operation. - * @retval RTEMS_INVALID_ID Invalid scheduler instance identifier. - * @retval RTEMS_NOT_CONFIGURED The processor is not configured to be used by - * the application. - * @retval RTEMS_INCORRECT_STATE The processor is configured to be used by - * the application, however, it is not online. - * @retval RTEMS_RESOURCE_IN_USE The processor is already assigned to a - * scheduler instance. + * @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 */ + /** - * @brief Removes a processor from set of processors owned by the specified - * scheduler instance. + * @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``. * - * Must be called from task context. This operation obtains and releases the - * objects allocator lock. Removing a processor from a scheduler is a complex - * operation that involves all tasks of the system. + * @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. * - * @param[in] scheduler_id Identifier of the scheduler instance. - * @param[in] cpu_index Index of the processor to add. + * @par Notes + * Removing a processor from a scheduler is a complex operation that involves + * all tasks of the system. * - * @retval RTEMS_SUCCESSFUL Successful operation. - * @retval RTEMS_INVALID_ID Invalid scheduler instance identifier. - * @retval RTEMS_INVALID_NUMBER The processor is not owned by the specified - * scheduler instance. - * @retval RTEMS_RESOURCE_IN_USE The set of processors owned by the specified - * scheduler instance would be empty after the processor removal and there - * exists a non-idle task that uses this scheduler instance as its home - * scheduler instance. + * @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 */ + /** - * @brief Gets the maximum task priority of the specified scheduler instance. + * @ingroup RTEMSAPIClassicTasks * - * @param[in] scheduler_id Identifier of the scheduler instance. - * @param[out] priority Pointer to a task priority value. + * @brief Creates a task. * - * @retval RTEMS_SUCCESSFUL Successful operation. - * @retval RTEMS_INVALID_ADDRESS The @a priority parameter is @c NULL. - * @retval RTEMS_INVALID_ID Invalid scheduler instance identifier. - */ -rtems_status_code rtems_scheduler_get_maximum_priority( - rtems_id scheduler_id, - rtems_task_priority *priority -); - -/** - * @brief Map a task priority to the corresponding POSIX thread priority. + * @param name is the object name of the task. * - * @param scheduler_id Identifier of the scheduler instance. - * @param priority The task priority to map. - * @param[out] posix_priority Pointer to a POSIX thread priority value. + * @param initial_priority is the initial task priority. * - * @retval RTEMS_SUCCESSFUL Successful operation. - * @retval RTEMS_INVALID_ADDRESS The @a posix_priority parameter is @c NULL. - * @retval RTEMS_INVALID_ID Invalid scheduler instance identifier. - * @retval RTEMS_INVALID_PRIORITY Invalid task priority. - */ -rtems_status_code rtems_scheduler_map_priority_to_posix( - rtems_id scheduler_id, - rtems_task_priority priority, - int *posix_priority -); - -/** - * @brief Map a POSIX thread priority to the corresponding 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 object identifier variable. When the + * directive call is successful, the identifier of the created task will be + * stored in this variable. + * + * 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), * - * @param scheduler_id Identifier of the scheduler instance. - * @param posix_priority The POSIX thread priority to map. - * @param[out] priority Pointer to a task priority value. + * * the ASR processing mode of the task: #RTEMS_ASR (default) or + * #RTEMS_NO_ASR, * - * @retval RTEMS_SUCCESSFUL Successful operation. - * @retval RTEMS_INVALID_ADDRESS The @a priority parameter is @c NULL. - * @retval RTEMS_INVALID_ID Invalid scheduler instance identifier. - * @retval RTEMS_INVALID_PRIORITY Invalid POSIX thread priority. + * * 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_scheduler_map_priority_from_posix( - rtems_id scheduler_id, - int posix_priority, - rtems_task_priority *priority +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 ); -/**@}*/ - -#ifdef __cplusplus -} -#endif +/* Generated from spec:/rtems/task/if/construct */ -#endif -/* end of include file */ +/** + * @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 object identifier variable. When the + * directive call is successful, the identifier of the constructed task will + * be stored in this variable. + * + * @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 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. + * + * 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_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 + * 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. + * + * 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 variable. + * When the directive call is successful, the current priority of the task + * with respect to the specified scheduler will be stored in this variable. + * + * 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, and other + * mechanisms. + * + * @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 a mode variable. 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. + * + * 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( 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 variable. When the + * directive call is successful, the identifier of the home scheduler of the + * task will be stored in this variable. + * + * 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 There task priority specified in + * ``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_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 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 affinity set of the task will + * be stored in this variable. 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 provided 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 referenced processor set variable in + * bytes. + * + * @param cpuset is the pointer to a processor set variable. 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 */ -- cgit v1.2.3