rtems: Fix rtems_task_set_scheduler() API

Task priorities are only valid within a scheduler instance. The
rtems_task_set_scheduler() directive moves a task from one scheduler
instance to another using the current priority of the thread. However,
the current task priority of the source scheduler instance is undefined
in the target scheduler instance. Add a third parameter to specify the
priority.

Close #2749.

1 files changed, 16 insertions, 7 deletions

diff --git a/cpukit/rtems/include/rtems/rtems/tasks.h b/cpukit/rtems/include/rtems/rtems/tasks.h
index 6273228f85..e690e60557 100644
--- a/cpukit/rtems/include/rtems/rtems/tasks.h
+++ b/cpukit/rtems/include/rtems/rtems/tasks.h
@@ -448,23 +448,32 @@ rtems_status_code rtems_task_get_scheduler(
 );
 
 /**
- * @brief Sets the scheduler of a task.
+ * @brief Sets the scheduler instance of a task.
  *
- * The scheduler of a task is initialized to the scheduler of the task that
- * created it.
+ * Initially, the scheduler instance of a task is set to the scheduler instance
+ * of the task that created it.  This directive allows to move a task from its
+ * current scheduler instance to another specified by the scheduler identifier.
  *
  * @param[in] task_id Identifier of the task.  Use @ref RTEMS_SELF to select
- * the executing task.
- * @param[in] scheduler_id Identifier of the scheduler.
+ *   the executing task.
+ * @param[in] scheduler_id Identifier of the scheduler instance.
+ * @param[in] priority The task priority with respect to the new scheduler
+ *   instance.  The real and initial priority of the task is set to this value.
+ *   The initial priority is used by rtems_task_restart() for example.
  *
  * @retval RTEMS_SUCCESSFUL Successful operation.
+ * @retval RTEMS_ILLEGAL_ON_REMOTE_OBJECT Directive is illegal on remote tasks.
  * @retval RTEMS_INVALID_ID Invalid task or scheduler identifier.
+ * @retval RTEMS_INVALID_PRIORITY Invalid priority.
+ * @retval RTEMS_RESOURCE_IN_USE The task owns resources which deny a scheduler
+ *   change.
  *
  * @see rtems_scheduler_ident().
  */
 rtems_status_code rtems_task_set_scheduler(
-  rtems_id task_id,
-  rtems_id scheduler_id
+  rtems_id            task_id,
+  rtems_id            scheduler_id,
+  rtems_task_priority priority
 );
 
 /**