score: Implement scheduler helping protocol

The following scheduler operations return a thread in need for help

    - unblock,
    - change priority, and
    - yield.

A thread in need for help is a thread that encounters a scheduler state
change from scheduled to ready or a thread that cannot be scheduled in
an unblock operation.  Such a thread can ask threads which depend on
resources owned by this thread for help.

Add a new ask for help scheduler operation.  This operation is used by
_Scheduler_Ask_for_help() to help threads in need for help returned by
the operations mentioned above.  This operation is also used by
_Scheduler_Thread_change_resource_root() in case the root of a resource
sub-tree changes.  A use case is the ownership change of a resource.

In case it is not possible to schedule a thread in need for help, then
the corresponding scheduler node will be placed into the set of ready
scheduler nodes of the scheduler instance.  Once a state change from
ready to scheduled happens for this scheduler node it may be used to
schedule the thread in need for help.

1 files changed, 47 insertions, 0 deletions

diff --git a/cpukit/score/include/rtems/score/scheduler.h b/cpukit/score/include/rtems/score/scheduler.h
index 993ae55b29..8da988fffd 100644
--- a/cpukit/score/include/rtems/score/scheduler.h
+++ b/cpukit/score/include/rtems/score/scheduler.h
@@ -90,6 +90,31 @@ typedef struct {
     bool
   );
 
+#if defined(RTEMS_SMP)
+  /**
+   * Ask for help operation.
+   *
+   * @param[in] scheduler The scheduler of the thread offering help.
+   * @param[in] offers_help The thread offering help.
+   * @param[in] needs_help The thread needing help.
+   *
+   * @retval needs_help It was not possible to schedule the thread needing
+   *   help, so it is returned to continue the search for help.
+   * @retval next_needs_help It was possible to schedule the thread needing
+   *   help, but this displaced another thread eligible to ask for help.  So
+   *   this thread is returned to start a new search for help.
+   * @retval NULL It was possible to schedule the thread needing help, and no
+   *   other thread needs help as a result.
+   *
+   * @see _Scheduler_Ask_for_help().
+   */
+  Thread_Control *( *ask_for_help )(
+    const Scheduler_Control *scheduler,
+    Thread_Control          *offers_help,
+    Thread_Control          *needs_help
+  );
+#endif
+
   /** @see _Scheduler_Node_initialize() */
   void ( *node_initialize )( const Scheduler_Control *, Thread_Control * );
 
@@ -375,6 +400,28 @@ extern const Scheduler_Control _Scheduler_Table[];
   extern const Scheduler_Assignment _Scheduler_Assignments[];
 #endif
 
+#if defined(RTEMS_SMP)
+  /**
+   * @brief Does nothing.
+   *
+   * @param[in] scheduler Unused.
+   * @param[in] offers_help Unused.
+   * @param[in] needs_help Unused.
+   *
+   * @retval NULL Always.
+   */
+  Thread_Control *_Scheduler_default_Ask_for_help(
+    const Scheduler_Control *scheduler,
+    Thread_Control          *offers_help,
+    Thread_Control          *needs_help
+  );
+
+  #define SCHEDULER_OPERATION_DEFAULT_ASK_FOR_HELP \
+    _Scheduler_default_Ask_for_help,
+#else
+  #define SCHEDULER_OPERATION_DEFAULT_ASK_FOR_HELP
+#endif
+
 /**
  * @brief Does nothing.
  *