[rtems commit] doc: rtems_task_set_scheduler()

[Sebastian Huber]

Module:    rtems
Branch:    master
Commit:    f8300293ae2b59cd7c79a39d8a11e9acd9e4c3db
Changeset: http://git.rtems.org/rtems/commit/?id=f8300293ae2b59cd7c79a39d8a11e9acd9e4c3db

Author:    Sebastian Huber <sebastian.huber at embedded-brains.de>
Date:      Wed Apr 16 16:06:05 2014 +0200

doc: rtems_task_set_scheduler()

---

 cpukit/rtems/include/rtems/rtems/tasks.h |    3 +
 doc/user/smp.t                           |   77 ++++++++++++++++++++++++++++++
 2 files changed, 80 insertions(+), 0 deletions(-)

diff --git a/cpukit/rtems/include/rtems/rtems/tasks.h b/cpukit/rtems/include/rtems/rtems/tasks.h
index 72eb553..a9016ce 100644
--- a/cpukit/rtems/include/rtems/rtems/tasks.h
+++ b/cpukit/rtems/include/rtems/rtems/tasks.h
@@ -560,6 +560,9 @@ rtems_status_code rtems_task_get_scheduler(
 /**
  * @brief Sets the scheduler of a task.
  *
+ * The scheduler of a task is initialized to the scheduler of the task that
+ * created it.
+ *
  * @param[in] id Identifier of the task.  Use @ref RTEMS_SELF to select the
  * executing task.
  * @param[in] scheduler_id Identifier of the scheduler.
diff --git a/doc/user/smp.t b/doc/user/smp.t
index abdd81c..f710537 100644
--- a/doc/user/smp.t
+++ b/doc/user/smp.t
@@ -19,6 +19,7 @@ The application level services currently provided are:
 @item @code{rtems_scheduler_ident} - Get ID of a scheduler
 @item @code{rtems_scheduler_get_processor_set} - Get processor set of a scheduler
 @item @code{rtems_task_get_scheduler} - Get scheduler of a task
+ at item @code{rtems_task_set_scheduler} - Set scheduler of a task
 @item @code{rtems_task_get_affinity} - Get task processor affinity
 @item @code{rtems_task_set_affinity} - Set task processor affinity
 @end itemize
@@ -409,6 +410,82 @@ Returns the scheduler identifier of a task in @code{scheduler_id}.
 None.
 
 @c
+ at c rtems_task_set_scheduler
+ at c
+ at page
+ at subsection TASK_SET_SCHEDULER - Set scheduler of a task
+
+ at subheading CALLING SEQUENCE:
+
+ at ifset is-C
+ at example
+rtems_status_code rtems_task_set_scheduler(
+  rtems_id id,
+  rtems_id scheduler_id
+);
+ at end example
+ at end ifset
+
+ at ifset is-Ada
+ at end ifset
+
+ at subheading DIRECTIVE STATUS CODES:
+
+ at code{@value{RPREFIX}SUCCESSFUL} - successful operation@*
+ at code{@value{RPREFIX}INVALID_ID} - invalid task or scheduler id@*
+ at code{@value{RPREFIX}INCORRECT_STATE} - the task is in the wrong state to
+perform a scheduler change
+
+ at subheading DESCRIPTION:
+
+Sets the scheduler of a task specified by @code{scheduler_id}.  The scheduler
+of a task is initialized to the scheduler of the task that created it.
+
+ at subheading NOTES:
+
+None.
+
+ at subheading EXAMPLE:
+
+ at example
+ at group
+#include <rtems.h>
+#include <assert.h>
+
+void task(rtems_task_argument arg);
+
+void example(void)
+@{
+  rtems_status_code sc;
+  rtems_id          task_id;
+  rtems_id          scheduler_id;
+  rtems_name        scheduler_name;
+
+  scheduler_name = rtems_build_name('W', 'O', 'R', 'K');
+
+  sc = rtems_scheduler_ident(scheduler_name, &scheduler_id);
+  assert(sc == RTEMS_SUCCESSFUL);
+
+  sc = rtems_task_create(
+    rtems_build_name('T', 'A', 'S', 'K'),
+    1,
+    RTEMS_MINIMUM_STACK_SIZE,
+    RTEMS_DEFAULT_MODES,
+    RTEMS_DEFAULT_ATTRIBUTES,
+    &task_id
+  );
+  assert(sc == RTEMS_SUCCESSFUL);
+
+  sc = rtems_task_set_scheduler(task_id, scheduler_id);
+  assert(sc == RTEMS_SUCCESSFUL);
+
+  sc = rtems_task_start(task_id, task, 0);
+  assert(sc == RTEMS_SUCCESSFUL);
+@}
+ at end group
+ at end example
+
+ at c
 @c rtems_task_get_affinity
 @c
 @page