LXR 6.1/​cpukit/​include/​rtems/​rtems/​scheduler.h	Source navigation Diff markup Identifier search General search
	Version: 6.1 Revert   Change

File indexing completed on 2025-05-11 08:24:12

 /* 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 */

This page was automatically generated by the 2.3.7 LXR engine. The LXR team