From 0d83bed2e5928d5d3d94ed77e1f1dad2cb668ef8 Mon Sep 17 00:00:00 2001 From: Sebastian Huber Date: Thu, 2 Dec 2021 14:00:53 +0100 Subject: rtems: Move scheduler directives to own header Move all rtems_scheduler_* directives to the new header file . Add a Scheduler Manager API and implementation group. --- cpukit/include/rtems/rtems/scheduler.h | 551 +++++++++++++++++++++++++++++++++ cpukit/include/rtems/rtems/tasks.h | 480 +--------------------------- cpukit/include/rtems/rtems/tasksimpl.h | 8 + 3 files changed, 560 insertions(+), 479 deletions(-) create mode 100644 cpukit/include/rtems/rtems/scheduler.h (limited to 'cpukit/include/rtems/rtems') diff --git a/cpukit/include/rtems/rtems/scheduler.h b/cpukit/include/rtems/rtems/scheduler.h new file mode 100644 index 0000000000..8bd041558f --- /dev/null +++ b/cpukit/include/rtems/rtems/scheduler.h @@ -0,0 +1,551 @@ +/* SPDX-License-Identifier: BSD-2-Clause */ + +/** + * @file + * + * @ingroup RTEMSImplClassicScheduler + * + * @brief This header file defines the main parts of the Scheduler Manager API. + */ + +/* + * Copyright (C) 2013, 2021 embedded brains GmbH (http://www.embedded-brains.de) + * Copyright (C) 1988, 2017 On-Line Applications Research Corporation (OAR) + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions + * are met: + * 1. Redistributions of source code must retain the above copyright + * notice, this list of conditions and the following disclaimer. + * 2. Redistributions in binary form must reproduce the above copyright + * notice, this list of conditions and the following disclaimer in the + * documentation and/or other materials provided with the distribution. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" + * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE + * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE + * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR + * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF + * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS + * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN + * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) + * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE + * POSSIBILITY OF SUCH DAMAGE. + */ + +/* + * This file is part of the RTEMS quality process and was automatically + * generated. If you find something that needs to be fixed or + * worded better please post a report or patch to an RTEMS mailing list + * or raise a bug report: + * + * https://www.rtems.org/bugs.html + * + * For information on updating and regenerating please refer to the How-To + * section in the Software Requirements Engineering chapter of the + * RTEMS Software Engineering manual. The manual is provided as a part of + * a release. For development sources please refer to the online + * documentation at: + * + * https://docs.rtems.org + */ + +/* Generated from spec:/rtems/scheduler/if/header */ + +#ifndef _RTEMS_RTEMS_SCHEDULER_H +#define _RTEMS_RTEMS_SCHEDULER_H + +#include +#include +#include +#include +#include +#include + +#ifdef __cplusplus +extern "C" { +#endif + +/* Generated from spec:/rtems/scheduler/if/group */ + +/** + * @defgroup RTEMSAPIClassicScheduler Scheduler Manager + * + * @ingroup RTEMSAPIClassic + * + * @brief The scheduling concepts relate to the allocation of processing time + * for tasks. + * + * The concept of scheduling in real-time systems dictates the ability to + * provide an immediate response to specific external events, particularly the + * necessity of scheduling tasks to run within a specified time limit after the + * occurrence of an event. For example, software embedded in life-support + * systems used to monitor hospital patients must take instant action if a + * change in the patient’s status is detected. + * + * The component of RTEMS responsible for providing this capability is + * appropriately called the scheduler. The scheduler’s sole purpose is to + * allocate the all important resource of processor time to the various tasks + * competing for attention. + */ + +/* Generated from spec:/rtems/scheduler/if/ident */ + +/** + * @ingroup RTEMSAPIClassicScheduler + * + * @brief Identifies a scheduler by the object name. + * + * @param name is the scheduler name to look up. + * + * @param[out] id is the pointer to an ::rtems_id object. When the directive + * call is successful, the identifier of the scheduler will be stored in this + * object. + * + * This directive obtains a scheduler identifier associated with the scheduler + * name specified in ``name``. + * + * @retval ::RTEMS_SUCCESSFUL The requested operation was successful. + * + * @retval ::RTEMS_INVALID_NAME There was no scheduler associated with the + * name. + * + * @retval ::RTEMS_INVALID_ADDRESS The ``id`` parameter was NULL. + * + * @par Notes + * @parblock + * The scheduler name is determined by the scheduler configuration. + * + * The scheduler identifier is used with other scheduler related directives to + * access the scheduler. + * @endparblock + * + * @par Constraints + * @parblock + * The following constraints apply to this directive: + * + * * The directive may be called from within any runtime context. + * + * * The directive will not cause the calling task to be preempted. + * @endparblock + */ +rtems_status_code rtems_scheduler_ident( rtems_name name, rtems_id *id ); + +/* Generated from spec:/rtems/scheduler/if/ident-by-processor */ + +/** + * @ingroup RTEMSAPIClassicScheduler + * + * @brief Identifies a scheduler by the processor index. + * + * @param cpu_index is the processor index to identify the scheduler. + * + * @param[out] id is the pointer to an ::rtems_id object. When the directive + * call is successful, the identifier of the scheduler will be stored in this + * object. + * + * @retval ::RTEMS_SUCCESSFUL The requested operation was successful. + * + * @retval ::RTEMS_INVALID_ADDRESS The ``id`` parameter was NULL. + * + * @retval ::RTEMS_INVALID_NAME The processor index was invalid. + * + * @retval ::RTEMS_INCORRECT_STATE The processor index was valid, however, the + * corresponding processor was not owned by a scheduler. + * + * @par Constraints + * @parblock + * The following constraints apply to this directive: + * + * * The directive may be called from within any runtime context. + * + * * The directive will not cause the calling task to be preempted. + * @endparblock + */ +rtems_status_code rtems_scheduler_ident_by_processor( + uint32_t cpu_index, + rtems_id *id +); + +/* Generated from spec:/rtems/scheduler/if/ident-by-processor-set */ + +/** + * @ingroup RTEMSAPIClassicScheduler + * + * @brief Identifies a scheduler by the processor set. + * + * @param cpusetsize is the size of the processor set referenced by ``cpuset`` + * in bytes. The size shall be positive. + * + * @param cpuset is the pointer to a cpu_set_t. The referenced processor set + * will be used to identify the scheduler. + * + * @param[out] id is the pointer to an ::rtems_id object. When the directive + * call is successful, the identifier of the scheduler will be stored in this + * object. + * + * The scheduler is selected according to the highest numbered online processor + * in the specified processor set. + * + * @retval ::RTEMS_SUCCESSFUL The requested operation was successful. + * + * @retval ::RTEMS_INVALID_ADDRESS The ``id`` parameter was NULL. + * + * @retval ::RTEMS_INVALID_ADDRESS The ``cpuset`` parameter was NULL. + * + * @retval ::RTEMS_INVALID_SIZE The processor set size was invalid. + * + * @retval ::RTEMS_INVALID_NAME The processor set contained no online + * processor. + * + * @retval ::RTEMS_INCORRECT_STATE The processor set was valid, however, the + * highest numbered online processor in the processor set was not owned by a + * scheduler. + * + * @par Constraints + * @parblock + * The following constraints apply to this directive: + * + * * The directive may be called from within any runtime context. + * + * * The directive will not cause the calling task to be preempted. + * @endparblock + */ +rtems_status_code rtems_scheduler_ident_by_processor_set( + size_t cpusetsize, + const cpu_set_t *cpuset, + rtems_id *id +); + +/* Generated from spec:/rtems/scheduler/if/get-maximum-priority */ + +/** + * @ingroup RTEMSAPIClassicScheduler + * + * @brief Gets the maximum task priority of the scheduler. + * + * @param scheduler_id is the scheduler identifier. + * + * @param[out] priority is the pointer to an ::rtems_task_priority object. + * When the directive the maximum priority of the scheduler will be stored in + * this object. + * + * @retval ::RTEMS_SUCCESSFUL The requested operation was successful. + * + * @retval ::RTEMS_INVALID_ID There was no scheduler associated with the + * identifier specified by ``scheduler_id``. + * + * @retval ::RTEMS_INVALID_ADDRESS The ``priority`` parameter was NULL. + * + * @par Constraints + * @parblock + * The following constraints apply to this directive: + * + * * The directive may be called from within any runtime context. + * + * * The directive will not cause the calling task to be preempted. + * @endparblock + */ +rtems_status_code rtems_scheduler_get_maximum_priority( + rtems_id scheduler_id, + rtems_task_priority *priority +); + +/* Generated from spec:/rtems/scheduler/if/map-priority-to-posix */ + +/** + * @ingroup RTEMSAPIClassicScheduler + * + * @brief Maps a Classic API task priority to the corresponding POSIX thread + * priority. + * + * @param scheduler_id is the scheduler identifier. + * + * @param priority is the Classic API task priority to map. + * + * @param[out] posix_priority is the pointer to an ``int`` object. When the + * directive call is successful, the POSIX thread priority value + * corresponding to the specified Classic API task priority value will be + * stored in this object. + * + * @retval ::RTEMS_SUCCESSFUL The requested operation was successful. + * + * @retval ::RTEMS_INVALID_ADDRESS The ``posix_priority`` parameter was NULL. + * + * @retval ::RTEMS_INVALID_ID There was no scheduler associated with the + * identifier specified by ``scheduler_id``. + * + * @retval ::RTEMS_INVALID_PRIORITY The Classic API task priority was invalid. + * + * @par Constraints + * @parblock + * The following constraints apply to this directive: + * + * * The directive may be called from within any runtime context. + * + * * The directive will not cause the calling task to be preempted. + * @endparblock + */ +rtems_status_code rtems_scheduler_map_priority_to_posix( + rtems_id scheduler_id, + rtems_task_priority priority, + int *posix_priority +); + +/* Generated from spec:/rtems/scheduler/if/map-priority-from-posix */ + +/** + * @ingroup RTEMSAPIClassicScheduler + * + * @brief Maps a POSIX thread priority to the corresponding Classic API task + * priority. + * + * @param scheduler_id is the scheduler identifier. + * + * @param posix_priority is the POSIX thread priority to map. + * + * @param[out] priority is the pointer to an ::rtems_task_priority object. + * When the directive call is successful, the Classic API task priority value + * corresponding to the specified POSIX thread priority value will be stored + * in this object. + * + * @retval ::RTEMS_SUCCESSFUL The requested operation was successful. + * + * @retval ::RTEMS_INVALID_ADDRESS The ``priority`` parameter was NULL. + * + * @retval ::RTEMS_INVALID_ID There was no scheduler associated with the + * identifier specified by ``scheduler_id``. + * + * @retval ::RTEMS_INVALID_PRIORITY The POSIX thread priority was invalid. + * + * @par Constraints + * @parblock + * The following constraints apply to this directive: + * + * * The directive may be called from within any runtime context. + * + * * The directive will not cause the calling task to be preempted. + * @endparblock + */ +rtems_status_code rtems_scheduler_map_priority_from_posix( + rtems_id scheduler_id, + int posix_priority, + rtems_task_priority *priority +); + +/* Generated from spec:/rtems/scheduler/if/get-processor */ + +/** + * @ingroup RTEMSAPIClassicScheduler + * + * @brief Returns the index of the current processor. + * + * Where the system was built with SMP support disabled, this directive + * evaluates to a compile time constant of zero. + * + * Where the system was built with SMP support enabled, this directive returns + * the index of the current processor. The set of processor indices is the + * range of integers starting with zero up to + * rtems_scheduler_get_processor_maximum() minus one. + * + * @return Returns the index of the current processor. + * + * @par Notes + * Outside of sections with disabled thread dispatching the current processor + * index may change after every instruction since the thread may migrate from + * one processor to another. Sections with disabled interrupts are sections + * with thread dispatching disabled. + * + * @par Constraints + * @parblock + * The following constraints apply to this directive: + * + * * The directive may be called from within any runtime context. + * + * * The directive will not cause the calling task to be preempted. + * @endparblock + */ +uint32_t rtems_scheduler_get_processor( void ); + +/* Generated from spec:/rtems/scheduler/if/get-processor-macro */ +#define rtems_scheduler_get_processor() _SMP_Get_current_processor() + +/* Generated from spec:/rtems/scheduler/if/get-processor-maximum */ + +/** + * @ingroup RTEMSAPIClassicScheduler + * + * @brief Returns the processor maximum supported by the system. + * + * Where the system was built with SMP support disabled, this directive + * evaluates to a compile time constant of one. + * + * Where the system was built with SMP support enabled, this directive returns + * the minimum of the processors (physically or virtually) available at the + * target and the configured processor maximum (see + * #CONFIGURE_MAXIMUM_PROCESSORS). Not all processors in the range from + * processor index zero to the last processor index (which is the processor + * maximum minus one) may be configured to be used by a scheduler or may be + * online (online processors have a scheduler assigned). + * + * @return Returns the processor maximum supported by the system. + * + * @par Constraints + * @parblock + * The following constraints apply to this directive: + * + * * The directive may be called from within any runtime context. + * + * * The directive will not cause the calling task to be preempted. + * @endparblock + */ +uint32_t rtems_scheduler_get_processor_maximum( void ); + +/* Generated from spec:/rtems/scheduler/if/get-processor-maximum-macro */ +#define rtems_scheduler_get_processor_maximum() _SMP_Get_processor_maximum() + +/* Generated from spec:/rtems/scheduler/if/get-processor-set */ + +/** + * @ingroup RTEMSAPIClassicScheduler + * + * @brief Gets the set of processors owned by the scheduler. + * + * @param scheduler_id is the scheduler identifier. + * + * @param cpusetsize is the size of the processor set referenced by ``cpuset`` + * in bytes. + * + * @param[out] cpuset is the pointer to a cpu_set_t object. When the directive + * call is successful, the processor set of the scheduler will be stored in + * this object. A set bit in the processor set means that the corresponding + * processor is owned by the scheduler, otherwise the bit is cleared. + * + * @retval ::RTEMS_SUCCESSFUL The requested operation was successful. + * + * @retval ::RTEMS_INVALID_ADDRESS The ``cpuset`` parameter was NULL. + * + * @retval ::RTEMS_INVALID_ID There was no scheduler associated with the + * identifier specified by ``scheduler_id``. + * + * @retval ::RTEMS_INVALID_SIZE The provided processor set was too small for + * the set of processors owned by the scheduler. + * + * @par Constraints + * @parblock + * The following constraints apply to this directive: + * + * * The directive may be called from within any runtime context. + * + * * The directive will not cause the calling task to be preempted. + * @endparblock + */ +rtems_status_code rtems_scheduler_get_processor_set( + rtems_id scheduler_id, + size_t cpusetsize, + cpu_set_t *cpuset +); + +/* Generated from spec:/rtems/scheduler/if/add-processor */ + +/** + * @ingroup RTEMSAPIClassicScheduler + * + * @brief Adds the processor to the set of processors owned by the scheduler. + * + * @param scheduler_id is the scheduler identifier. + * + * @param cpu_index is the index of the processor to add. + * + * This directive adds the processor specified by the ``cpu_index`` to the + * scheduler specified by ``scheduler_id``. + * + * @retval ::RTEMS_SUCCESSFUL The requested operation was successful. + * + * @retval ::RTEMS_INVALID_ID There was no scheduler associated with the + * identifier specified by ``scheduler_id``. + * + * @retval ::RTEMS_NOT_CONFIGURED The processor was not configured to be used + * by the application. + * + * @retval ::RTEMS_INCORRECT_STATE The processor was configured to be used by + * the application, however, it was not online. + * + * @retval ::RTEMS_RESOURCE_IN_USE The processor was already assigned to a + * scheduler. + * + * @par Constraints + * @parblock + * The following constraints apply to this directive: + * + * * The directive may be called from within device driver initialization + * context. + * + * * The directive may be called from within task context. + * + * * The directive may obtain and release the object allocator mutex. This may + * cause the calling task to be preempted. + * @endparblock + */ +rtems_status_code rtems_scheduler_add_processor( + rtems_id scheduler_id, + uint32_t cpu_index +); + +/* Generated from spec:/rtems/scheduler/if/remove-processor */ + +/** + * @ingroup RTEMSAPIClassicScheduler + * + * @brief Removes the processor from the set of processors owned by the + * scheduler. + * + * @param scheduler_id is the scheduler identifier. + * + * @param cpu_index is the index of the processor to remove. + * + * This directive removes the processor specified by the ``cpu_index`` from the + * scheduler specified by ``scheduler_id``. + * + * @retval ::RTEMS_SUCCESSFUL The requested operation was successful. + * + * @retval ::RTEMS_INVALID_ID There was no scheduler associated with the + * identifier specified by ``scheduler_id``. + * + * @retval ::RTEMS_INVALID_NUMBER The processor was not owned by the scheduler. + * + * @retval ::RTEMS_RESOURCE_IN_USE The processor was required by at least one + * non-idle task that used the scheduler as its home scheduler. + * + * @retval ::RTEMS_RESOURCE_IN_USE The processor was the last processor owned + * by the scheduler and there was at least one task that used the scheduler + * as a helping scheduler. + * + * @par Notes + * Removing a processor from a scheduler is a complex operation that involves + * all tasks of the system. + * + * @par Constraints + * @parblock + * The following constraints apply to this directive: + * + * * The directive may be called from within device driver initialization + * context. + * + * * The directive may be called from within task context. + * + * * The directive may obtain and release the object allocator mutex. This may + * cause the calling task to be preempted. + * @endparblock + */ +rtems_status_code rtems_scheduler_remove_processor( + rtems_id scheduler_id, + uint32_t cpu_index +); + +#ifdef __cplusplus +} +#endif + +#endif /* _RTEMS_RTEMS_SCHEDULER_H */ diff --git a/cpukit/include/rtems/rtems/tasks.h b/cpukit/include/rtems/rtems/tasks.h index 8e87bfd14a..e4609f6e9f 100644 --- a/cpukit/include/rtems/rtems/tasks.h +++ b/cpukit/include/rtems/rtems/tasks.h @@ -9,7 +9,7 @@ */ /* - * Copyright (C) 2013, 2021 embedded brains GmbH (http://www.embedded-brains.de) + * Copyright (C) 2020, 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 @@ -68,7 +68,6 @@ #include #include #include -#include #include #include @@ -76,29 +75,6 @@ extern "C" { #endif -/* Generated from spec:/rtems/scheduler/if/group */ - -/** - * @defgroup RTEMSAPIClassicScheduler Scheduler Manager - * - * @ingroup RTEMSAPIClassic - * - * @brief The scheduling concepts relate to the allocation of processing time - * for tasks. - * - * The concept of scheduling in real-time systems dictates the ability to - * provide an immediate response to specific external events, particularly the - * necessity of scheduling tasks to run within a specified time limit after the - * occurrence of an event. For example, software embedded in life-support - * systems used to monitor hospital patients must take instant action if a - * change in the patient’s status is detected. - * - * The component of RTEMS responsible for providing this capability is - * appropriately called the scheduler. The scheduler’s sole purpose is to - * allocate the all important resource of processor time to the various tasks - * competing for attention. - */ - /* Generated from spec:/rtems/task/if/group */ /** @@ -442,460 +418,6 @@ rtems_task_priority _RTEMS_Maximum_priority( void ); */ #define RTEMS_MAXIMUM_PRIORITY _RTEMS_Maximum_priority() -/* Generated from spec:/rtems/scheduler/if/ident */ - -/** - * @ingroup RTEMSAPIClassicScheduler - * - * @brief Identifies a scheduler by the object name. - * - * @param name is the scheduler name to look up. - * - * @param[out] id is the pointer to an ::rtems_id object. When the directive - * call is successful, the identifier of the scheduler will be stored in this - * object. - * - * This directive obtains a scheduler identifier associated with the scheduler - * name specified in ``name``. - * - * @retval ::RTEMS_SUCCESSFUL The requested operation was successful. - * - * @retval ::RTEMS_INVALID_NAME There was no scheduler associated with the - * name. - * - * @retval ::RTEMS_INVALID_ADDRESS The ``id`` parameter was NULL. - * - * @par Notes - * @parblock - * The scheduler name is determined by the scheduler configuration. - * - * The scheduler identifier is used with other scheduler related directives to - * access the scheduler. - * @endparblock - * - * @par Constraints - * @parblock - * The following constraints apply to this directive: - * - * * The directive may be called from within any runtime context. - * - * * The directive will not cause the calling task to be preempted. - * @endparblock - */ -rtems_status_code rtems_scheduler_ident( rtems_name name, rtems_id *id ); - -/* Generated from spec:/rtems/scheduler/if/ident-by-processor */ - -/** - * @ingroup RTEMSAPIClassicScheduler - * - * @brief Identifies a scheduler by the processor index. - * - * @param cpu_index is the processor index to identify the scheduler. - * - * @param[out] id is the pointer to an ::rtems_id object. When the directive - * call is successful, the identifier of the scheduler will be stored in this - * object. - * - * @retval ::RTEMS_SUCCESSFUL The requested operation was successful. - * - * @retval ::RTEMS_INVALID_ADDRESS The ``id`` parameter was NULL. - * - * @retval ::RTEMS_INVALID_NAME The processor index was invalid. - * - * @retval ::RTEMS_INCORRECT_STATE The processor index was valid, however, the - * corresponding processor was not owned by a scheduler. - * - * @par Constraints - * @parblock - * The following constraints apply to this directive: - * - * * The directive may be called from within any runtime context. - * - * * The directive will not cause the calling task to be preempted. - * @endparblock - */ -rtems_status_code rtems_scheduler_ident_by_processor( - uint32_t cpu_index, - rtems_id *id -); - -/* Generated from spec:/rtems/scheduler/if/ident-by-processor-set */ - -/** - * @ingroup RTEMSAPIClassicScheduler - * - * @brief Identifies a scheduler by the processor set. - * - * @param cpusetsize is the size of the processor set referenced by ``cpuset`` - * in bytes. The size shall be positive. - * - * @param cpuset is the pointer to a cpu_set_t. The referenced processor set - * will be used to identify the scheduler. - * - * @param[out] id is the pointer to an ::rtems_id object. When the directive - * call is successful, the identifier of the scheduler will be stored in this - * object. - * - * The scheduler is selected according to the highest numbered online processor - * in the specified processor set. - * - * @retval ::RTEMS_SUCCESSFUL The requested operation was successful. - * - * @retval ::RTEMS_INVALID_ADDRESS The ``id`` parameter was NULL. - * - * @retval ::RTEMS_INVALID_ADDRESS The ``cpuset`` parameter was NULL. - * - * @retval ::RTEMS_INVALID_SIZE The processor set size was invalid. - * - * @retval ::RTEMS_INVALID_NAME The processor set contained no online - * processor. - * - * @retval ::RTEMS_INCORRECT_STATE The processor set was valid, however, the - * highest numbered online processor in the processor set was not owned by a - * scheduler. - * - * @par Constraints - * @parblock - * The following constraints apply to this directive: - * - * * The directive may be called from within any runtime context. - * - * * The directive will not cause the calling task to be preempted. - * @endparblock - */ -rtems_status_code rtems_scheduler_ident_by_processor_set( - size_t cpusetsize, - const cpu_set_t *cpuset, - rtems_id *id -); - -/* Generated from spec:/rtems/scheduler/if/get-maximum-priority */ - -/** - * @ingroup RTEMSAPIClassicScheduler - * - * @brief Gets the maximum task priority of the scheduler. - * - * @param scheduler_id is the scheduler identifier. - * - * @param[out] priority is the pointer to an ::rtems_task_priority object. - * When the directive the maximum priority of the scheduler will be stored in - * this object. - * - * @retval ::RTEMS_SUCCESSFUL The requested operation was successful. - * - * @retval ::RTEMS_INVALID_ID There was no scheduler associated with the - * identifier specified by ``scheduler_id``. - * - * @retval ::RTEMS_INVALID_ADDRESS The ``priority`` parameter was NULL. - * - * @par Constraints - * @parblock - * The following constraints apply to this directive: - * - * * The directive may be called from within any runtime context. - * - * * The directive will not cause the calling task to be preempted. - * @endparblock - */ -rtems_status_code rtems_scheduler_get_maximum_priority( - rtems_id scheduler_id, - rtems_task_priority *priority -); - -/* Generated from spec:/rtems/scheduler/if/map-priority-to-posix */ - -/** - * @ingroup RTEMSAPIClassicScheduler - * - * @brief Maps a Classic API task priority to the corresponding POSIX thread - * priority. - * - * @param scheduler_id is the scheduler identifier. - * - * @param priority is the Classic API task priority to map. - * - * @param[out] posix_priority is the pointer to an ``int`` object. When the - * directive call is successful, the POSIX thread priority value - * corresponding to the specified Classic API task priority value will be - * stored in this object. - * - * @retval ::RTEMS_SUCCESSFUL The requested operation was successful. - * - * @retval ::RTEMS_INVALID_ADDRESS The ``posix_priority`` parameter was NULL. - * - * @retval ::RTEMS_INVALID_ID There was no scheduler associated with the - * identifier specified by ``scheduler_id``. - * - * @retval ::RTEMS_INVALID_PRIORITY The Classic API task priority was invalid. - * - * @par Constraints - * @parblock - * The following constraints apply to this directive: - * - * * The directive may be called from within any runtime context. - * - * * The directive will not cause the calling task to be preempted. - * @endparblock - */ -rtems_status_code rtems_scheduler_map_priority_to_posix( - rtems_id scheduler_id, - rtems_task_priority priority, - int *posix_priority -); - -/* Generated from spec:/rtems/scheduler/if/map-priority-from-posix */ - -/** - * @ingroup RTEMSAPIClassicScheduler - * - * @brief Maps a POSIX thread priority to the corresponding Classic API task - * priority. - * - * @param scheduler_id is the scheduler identifier. - * - * @param posix_priority is the POSIX thread priority to map. - * - * @param[out] priority is the pointer to an ::rtems_task_priority object. - * When the directive call is successful, the Classic API task priority value - * corresponding to the specified POSIX thread priority value will be stored - * in this object. - * - * @retval ::RTEMS_SUCCESSFUL The requested operation was successful. - * - * @retval ::RTEMS_INVALID_ADDRESS The ``priority`` parameter was NULL. - * - * @retval ::RTEMS_INVALID_ID There was no scheduler associated with the - * identifier specified by ``scheduler_id``. - * - * @retval ::RTEMS_INVALID_PRIORITY The POSIX thread priority was invalid. - * - * @par Constraints - * @parblock - * The following constraints apply to this directive: - * - * * The directive may be called from within any runtime context. - * - * * The directive will not cause the calling task to be preempted. - * @endparblock - */ -rtems_status_code rtems_scheduler_map_priority_from_posix( - rtems_id scheduler_id, - int posix_priority, - rtems_task_priority *priority -); - -/* Generated from spec:/rtems/scheduler/if/get-processor */ - -/** - * @ingroup RTEMSAPIClassicScheduler - * - * @brief Returns the index of the current processor. - * - * Where the system was built with SMP support disabled, this directive - * evaluates to a compile time constant of zero. - * - * Where the system was built with SMP support enabled, this directive returns - * the index of the current processor. The set of processor indices is the - * range of integers starting with zero up to - * rtems_scheduler_get_processor_maximum() minus one. - * - * @return Returns the index of the current processor. - * - * @par Notes - * Outside of sections with disabled thread dispatching the current processor - * index may change after every instruction since the thread may migrate from - * one processor to another. Sections with disabled interrupts are sections - * with thread dispatching disabled. - * - * @par Constraints - * @parblock - * The following constraints apply to this directive: - * - * * The directive may be called from within any runtime context. - * - * * The directive will not cause the calling task to be preempted. - * @endparblock - */ -uint32_t rtems_scheduler_get_processor( void ); - -/* Generated from spec:/rtems/scheduler/if/get-processor-macro */ -#define rtems_scheduler_get_processor() _SMP_Get_current_processor() - -/* Generated from spec:/rtems/scheduler/if/get-processor-maximum */ - -/** - * @ingroup RTEMSAPIClassicScheduler - * - * @brief Returns the processor maximum supported by the system. - * - * Where the system was built with SMP support disabled, this directive - * evaluates to a compile time constant of one. - * - * Where the system was built with SMP support enabled, this directive returns - * the minimum of the processors (physically or virtually) available at the - * target and the configured processor maximum (see - * #CONFIGURE_MAXIMUM_PROCESSORS). Not all processors in the range from - * processor index zero to the last processor index (which is the processor - * maximum minus one) may be configured to be used by a scheduler or may be - * online (online processors have a scheduler assigned). - * - * @return Returns the processor maximum supported by the system. - * - * @par Constraints - * @parblock - * The following constraints apply to this directive: - * - * * The directive may be called from within any runtime context. - * - * * The directive will not cause the calling task to be preempted. - * @endparblock - */ -uint32_t rtems_scheduler_get_processor_maximum( void ); - -/* Generated from spec:/rtems/scheduler/if/get-processor-maximum-macro */ -#define rtems_scheduler_get_processor_maximum() _SMP_Get_processor_maximum() - -/* Generated from spec:/rtems/scheduler/if/get-processor-set */ - -/** - * @ingroup RTEMSAPIClassicScheduler - * - * @brief Gets the set of processors owned by the scheduler. - * - * @param scheduler_id is the scheduler identifier. - * - * @param cpusetsize is the size of the processor set referenced by ``cpuset`` - * in bytes. - * - * @param[out] cpuset is the pointer to a cpu_set_t object. When the directive - * call is successful, the processor set of the scheduler will be stored in - * this object. A set bit in the processor set means that the corresponding - * processor is owned by the scheduler, otherwise the bit is cleared. - * - * @retval ::RTEMS_SUCCESSFUL The requested operation was successful. - * - * @retval ::RTEMS_INVALID_ADDRESS The ``cpuset`` parameter was NULL. - * - * @retval ::RTEMS_INVALID_ID There was no scheduler associated with the - * identifier specified by ``scheduler_id``. - * - * @retval ::RTEMS_INVALID_SIZE The provided processor set was too small for - * the set of processors owned by the scheduler. - * - * @par Constraints - * @parblock - * The following constraints apply to this directive: - * - * * The directive may be called from within any runtime context. - * - * * The directive will not cause the calling task to be preempted. - * @endparblock - */ -rtems_status_code rtems_scheduler_get_processor_set( - rtems_id scheduler_id, - size_t cpusetsize, - cpu_set_t *cpuset -); - -/* Generated from spec:/rtems/scheduler/if/add-processor */ - -/** - * @ingroup RTEMSAPIClassicScheduler - * - * @brief Adds the processor to the set of processors owned by the scheduler. - * - * @param scheduler_id is the scheduler identifier. - * - * @param cpu_index is the index of the processor to add. - * - * This directive adds the processor specified by the ``cpu_index`` to the - * scheduler specified by ``scheduler_id``. - * - * @retval ::RTEMS_SUCCESSFUL The requested operation was successful. - * - * @retval ::RTEMS_INVALID_ID There was no scheduler associated with the - * identifier specified by ``scheduler_id``. - * - * @retval ::RTEMS_NOT_CONFIGURED The processor was not configured to be used - * by the application. - * - * @retval ::RTEMS_INCORRECT_STATE The processor was configured to be used by - * the application, however, it was not online. - * - * @retval ::RTEMS_RESOURCE_IN_USE The processor was already assigned to a - * scheduler. - * - * @par Constraints - * @parblock - * The following constraints apply to this directive: - * - * * The directive may be called from within device driver initialization - * context. - * - * * The directive may be called from within task context. - * - * * The directive may obtain and release the object allocator mutex. This may - * cause the calling task to be preempted. - * @endparblock - */ -rtems_status_code rtems_scheduler_add_processor( - rtems_id scheduler_id, - uint32_t cpu_index -); - -/* Generated from spec:/rtems/scheduler/if/remove-processor */ - -/** - * @ingroup RTEMSAPIClassicScheduler - * - * @brief Removes the processor from the set of processors owned by the - * scheduler. - * - * @param scheduler_id is the scheduler identifier. - * - * @param cpu_index is the index of the processor to remove. - * - * This directive removes the processor specified by the ``cpu_index`` from the - * scheduler specified by ``scheduler_id``. - * - * @retval ::RTEMS_SUCCESSFUL The requested operation was successful. - * - * @retval ::RTEMS_INVALID_ID There was no scheduler associated with the - * identifier specified by ``scheduler_id``. - * - * @retval ::RTEMS_INVALID_NUMBER The processor was not owned by the scheduler. - * - * @retval ::RTEMS_RESOURCE_IN_USE The processor was required by at least one - * non-idle task that used the scheduler as its home scheduler. - * - * @retval ::RTEMS_RESOURCE_IN_USE The processor was the last processor owned - * by the scheduler and there was at least one task that used the scheduler - * as a helping scheduler. - * - * @par Notes - * Removing a processor from a scheduler is a complex operation that involves - * all tasks of the system. - * - * @par Constraints - * @parblock - * The following constraints apply to this directive: - * - * * The directive may be called from within device driver initialization - * context. - * - * * The directive may be called from within task context. - * - * * The directive may obtain and release the object allocator mutex. This may - * cause the calling task to be preempted. - * @endparblock - */ -rtems_status_code rtems_scheduler_remove_processor( - rtems_id scheduler_id, - uint32_t cpu_index -); - /* Generated from spec:/rtems/task/if/create */ /** diff --git a/cpukit/include/rtems/rtems/tasksimpl.h b/cpukit/include/rtems/rtems/tasksimpl.h index 62a618b635..f32255b0d9 100644 --- a/cpukit/include/rtems/rtems/tasksimpl.h +++ b/cpukit/include/rtems/rtems/tasksimpl.h @@ -111,6 +111,14 @@ RTEMS_INLINE_ROUTINE rtems_task_priority _RTEMS_Priority_From_core( /**@}*/ +/** + * @defgroup RTEMSImplClassicScheduler Scheduler Manager + * + * @ingroup RTEMSImplClassic + * + * @brief This group contains the Scheduler Manager implementation. + */ + #if defined(RTEMS_MULTIPROCESSING) #include #endif -- cgit v1.2.3