/* 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 & Co. KG
* 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 <stddef.h>
#include <stdint.h>
#include <sys/cpuset.h>
#include <rtems/rtems/status.h>
#include <rtems/rtems/types.h>
#include <rtems/score/smp.h>
#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 @ref
* 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 */
