[rtems-docs commit] c-user: Clarify task priorities

[Sebastian Huber]

Module:    rtems-docs
Branch:    master
Commit:    5fdc744dcedef3a40abbc031e540a811aca6e2b1
Changeset: http://git.rtems.org/rtems-docs/commit/?id=5fdc744dcedef3a40abbc031e540a811aca6e2b1

Author:    Sebastian Huber <sebastian.huber at embedded-brains.de>
Date:      Tue Sep 14 19:18:31 2021 +0200

c-user: Clarify task priorities

---

 c-user/scheduling-concepts/background.rst     |  5 +----
 c-user/scheduling-concepts/smp-schedulers.rst |  9 +++++----
 c-user/task/background.rst                    | 14 ++++++++++----
 3 files changed, 16 insertions(+), 12 deletions(-)

diff --git a/c-user/scheduling-concepts/background.rst b/c-user/scheduling-concepts/background.rst
index 7f8a63d..1fe7089 100644
--- a/c-user/scheduling-concepts/background.rst
+++ b/c-user/scheduling-concepts/background.rst
@@ -117,10 +117,7 @@ Task Priority and Scheduling
 
 The most significant task scheduling modification mechanism is the ability for
 the user to assign a priority level to each individual task when it is created
-and to alter a task's priority at run-time.  The maximum priority level depends
-on the configured scheduler.  A lower priority level means higher priority
-(higher importance).  The maximum priority level of the default uniprocessor
-scheduler is 255.
+and to alter a task's priority at run-time, see :ref:`TaskPriority`.
 
 .. index:: preemption
 
diff --git a/c-user/scheduling-concepts/smp-schedulers.rst b/c-user/scheduling-concepts/smp-schedulers.rst
index cfab04f..d6c1dc6 100644
--- a/c-user/scheduling-concepts/smp-schedulers.rst
+++ b/c-user/scheduling-concepts/smp-schedulers.rst
@@ -45,7 +45,7 @@ Deterministic Priority SMP Scheduler
 A fixed-priority scheduler which uses a table of chains with one chain per
 priority level for the ready tasks.  The maximum priority level is
 configurable.  By default, the maximum priority level is 255 (256 priority
-levels).
+levels), see :ref:`CONFIGURE_MAXIMUM_PRIORITY`.
 
 .. _SchedulerSMPPrioritySimple:
 
@@ -64,6 +64,7 @@ Arbitrary Processor Affinity Priority SMP Scheduler
 A fixed-priority scheduler which uses a table of chains with one chain per
 priority level for the ready tasks.  The maximum priority level is
 configurable.  By default, the maximum priority level is 255 (256 priority
-levels).  This scheduler supports arbitrary task processor affinities.  The
-worst-case run-time complexity of some scheduler operations exceeds
-:math:`O(n)` while :math:`n` is the count of ready tasks.
+levels), see :ref:`CONFIGURE_MAXIMUM_PRIORITY`.  This scheduler supports
+arbitrary task processor affinities.  The worst-case run-time complexity of
+some scheduler operations exceeds :math:`O(n)` while :math:`n` is the count of
+ready tasks.
diff --git a/c-user/task/background.rst b/c-user/task/background.rst
index a55f743..da6cabf 100644
--- a/c-user/task/background.rst
+++ b/c-user/task/background.rst
@@ -127,13 +127,19 @@ scheduling of a task is based on its current state and priority.
 .. index:: priority, task
 .. index:: rtems_task_priority
 
+.. _TaskPriority:
+
 Task Priority
 -------------
 
-A task's priority determines its importance in relation to the other tasks
-executing on the same processor.  RTEMS supports 255 levels of priority ranging
-from 1 to 255.  The data type ``rtems_task_priority`` is used to store task
-priorities.
+A task's :term:`priority` determines its importance in relation to the other
+tasks executing on the processor set owned by a :term:`scheduler`.  Normally,
+RTEMS supports 256 levels of priority ranging from 0 to 255.  The priority
+level 0 represents a special priority reserved for the operating system.  The
+data type :c:type:`rtems_task_priority` is used to store task priorities.  The
+maximum priority level depends on the configured scheduler, see
+:ref:`CONFIGURE_MAXIMUM_PRIORITY`, :ref:`ConfigurationSchedulersClustered`, and
+:ref:`RTEMSAPIClassicScheduler`.
 
 Tasks of numerically smaller priority values are more important tasks than
 tasks of numerically larger priority values.  For example, a task at priority