diff options
Diffstat (limited to 'cpukit/include/rtems/score/schedulerimpl.h')
-rw-r--r-- | cpukit/include/rtems/score/schedulerimpl.h | 73 |
1 files changed, 62 insertions, 11 deletions
diff --git a/cpukit/include/rtems/score/schedulerimpl.h b/cpukit/include/rtems/score/schedulerimpl.h index e7fbb8b166..5ad6b5d553 100644 --- a/cpukit/include/rtems/score/schedulerimpl.h +++ b/cpukit/include/rtems/score/schedulerimpl.h @@ -34,7 +34,34 @@ extern "C" { #endif /** - * @addtogroup RTEMSScoreScheduler + * @defgroup RTEMSScoreScheduler Scheduler Handler + * + * @ingroup RTEMSScore + * + * @brief This handler encapsulates functionality related to managing sets of + * threads that are ready for execution. + * + * Schedulers are used by the system to manage sets of threads that are ready + * for execution. A scheduler consists of + * + * * a scheduler algorithm implementation, + * + * * a scheduler index and an associated name, and + * + * * a set of processors owned by the scheduler (may be empty, but never + * overlaps with a set owned by another scheduler). + * + * Each thread uses exactly one scheduler as its home scheduler. Threads may + * temporarily use another scheduler due to actions of locking protocols. + * + * All properties of a scheduler can be configured and controlled by the user. + * Some properties are fixed at link time (defined by application configuration + * options), other properties can be changed at runtime through directive + * calls. + * + * The scheduler index, name, and initial processor set are defined for a + * particular application by the application configuration. The schedulers are + * registered in the ::_Scheduler_Table which has ::_Scheduler_Count entries. * * @{ */ @@ -929,6 +956,10 @@ RTEMS_INLINE_ROUTINE Thread_Control *_Scheduler_Use_idle_thread( return idle; } +/** + * @brief This enumeration defines what a scheduler should do with a node which + * could be scheduled. + */ typedef enum { SCHEDULER_TRY_TO_SCHEDULE_DO_SCHEDULE, SCHEDULER_TRY_TO_SCHEDULE_DO_IDLE_EXCHANGE, @@ -936,21 +967,41 @@ typedef enum { } Scheduler_Try_to_schedule_action; /** - * @brief Tries to schedule this scheduler node. - * - * @param context The scheduler instance context. - * @param[in, out] node The node which wants to get scheduled. - * @param idle A potential idle thread used by a potential victim node. - * @param get_idle_thread Function to get an idle thread. - * - * @retval true This node can be scheduled. - * @retval false This node cannot be scheduled. + * @brief Tries to schedule the scheduler node. + * + * When a scheduler needs to schedule a node, it shall use this function to + * determine what it shall do with the node. The node replaces a victim node if + * it can be scheduled. + * + * This function uses the state of the node and the scheduler state of the owner + * thread to determine what shall be done. Each scheduler maintains its nodes + * independent of other schedulers. This function ensures that a thread is + * scheduled by at most one scheduler. If a node requires an executing thread + * due to some locking protocol and the owner thread is already scheduled by + * another scheduler, then an idle thread shall be attached to the node. + * + * @param[in, out] context is the scheduler context. + * @param[in, out] node is the node which could be scheduled. + * @param idle is an idle thread used by the victim node or NULL. + * @param get_idle_thread points to a function to get an idle thread. + * + * @retval SCHEDULER_TRY_TO_SCHEDULE_DO_SCHEDULE The node shall be scheduled. + * + * @retval SCHEDULER_TRY_TO_SCHEDULE_DO_IDLE_EXCHANGE The node shall be + * scheduled and the provided idle thread shall be attached to the node. This + * action is returned, if the node cannot use the owner thread and shall use + * an idle thread instead. In this case, the idle thread is provided by the + * victim node. + * + * @retval SCHEDULER_TRY_TO_SCHEDULE_DO_BLOCK The node shall be blocked. This + * action is returned, if the owner thread is already scheduled by another + * scheduler. */ RTEMS_INLINE_ROUTINE Scheduler_Try_to_schedule_action _Scheduler_Try_to_schedule_node( Scheduler_Context *context, Scheduler_Node *node, - Thread_Control *idle, + const Thread_Control *idle, Scheduler_Get_idle_thread get_idle_thread ) { |