[rtems-docs commit] c-user: Update SMP introduction

[Sebastian Huber]

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

Author:    Sebastian Huber <sebastian.huber at embedded-brains.de>
Date:      Fri Feb  3 12:54:44 2017 +0100

c-user: Update SMP introduction

---

 c-user/configuring_a_system.rst               | 33 +--------------
 c-user/glossary.rst                           |  4 +-
 c-user/symmetric_multiprocessing_services.rst | 61 ++++++++++++++++++++-------
 3 files changed, 48 insertions(+), 50 deletions(-)

diff --git a/c-user/configuring_a_system.rst b/c-user/configuring_a_system.rst
index 7f69724..7837901 100644
--- a/c-user/configuring_a_system.rst
+++ b/c-user/configuring_a_system.rst
@@ -4132,40 +4132,9 @@ SMP Specific Configuration Parameters
 When RTEMS is configured to support SMP target systems, there are other
 configuration parameters which apply.
 
-.. COMMENT: XXX - add -enable-smp
-
-.. COMMENT: === CONFIGURE_SMP_APPLICATION ===
-
-.. _Enable SMP Support for Applications:
-
-Enable SMP Support for Applications
------------------------------------
-.. index:: CONFIGURE_SMP_APPLICATION
-
-CONSTANT:
-    ``CONFIGURE_SMP_APPLICATION``
-
-DATA TYPE:
-    Boolean feature macro.
-
-RANGE:
-    Defined or undefined.
-
-DEFAULT VALUE:
-    This is not defined by default.
-
-DESCRIPTION:
-    ``CONFIGURE_SMP_APPLICATION`` must be defined to enable SMP support for the
-    application.
-
-NOTES:
-    This define may go away in the future in case all RTEMS components are SMP
-    ready.  This configuration define is ignored on uni-processor
-    configurations.
-
 .. COMMENT: === CONFIGURE_SMP_MAXIMUM_PROCESSORS ===
 
-.. _Specify Maximum Processors in SMP System:
+.. _CONFIGURE_SMP_MAXIMUM_PROCESSORS:
 
 Specify Maximum Processors in SMP System
 ----------------------------------------
diff --git a/c-user/glossary.rst b/c-user/glossary.rst
index 2fa7e98..949c982 100644
--- a/c-user/glossary.rst
+++ b/c-user/glossary.rst
@@ -60,10 +60,8 @@ Glossary
    broadcast
       To simultaneously send a message to a logical set of destinations.
 
-   BSP
-      see Board Support Package.
-
    Board Support Package
+   BSP
       A collection of device initialization and control routines specific to a
       particular type of board or collection of boards.
 
diff --git a/c-user/symmetric_multiprocessing_services.rst b/c-user/symmetric_multiprocessing_services.rst
index 0065f0c..80e3f8c 100644
--- a/c-user/symmetric_multiprocessing_services.rst
+++ b/c-user/symmetric_multiprocessing_services.rst
@@ -10,31 +10,27 @@ Symmetric Multiprocessing (SMP)
 Introduction
 ============
 
-The Symmetric Multiprocessing (SMP) support of the RTEMS 4.11.0 and later is available
-on
+The Symmetric Multiprocessing (SMP) support of the RTEMS 4.12 is available on
 
-- ARM,
+- ARMv7-A,
 
 - PowerPC, and
 
 - SPARC.
 
-It must be explicitly enabled via the ``--enable-smp`` configure command line
-option.  To enable SMP in the application configuration see :ref:`Enable SMP
-Support for Applications`.  The default scheduler for SMP applications supports
-up to 32 processors and is a global fixed priority scheduler, see also
-:ref:`Configuring Clustered Schedulers`.  For example applications
-see:file:`testsuites/smptests`.
-
 .. warning::
 
-   The SMP support in the release of RTEMS is a work in progress. Before you
-   start using this RTEMS version for SMP ask on the RTEMS mailing list.
+   The SMP support must be explicitly enabled via the ``--enable-smp``
+   configure command line option for the :term:`BSP` build.
 
-This chapter describes the services related to Symmetric Multiprocessing
-provided by RTEMS.
+RTEMS is supposed to be a real-time operating system.  What does this mean in
+the context of SMP?  The RTEMS interpretation of real-time on SMP is the
+support for :ref:`ClusteredScheduling` with priority based schedulers and
+adequate locking protocols.  One aim is to enable a schedulability analysis
+under the sporadic task model :cite:`Brandenburg:2011:SL`
+:cite:`Burns:2013:MrsP`.
 
-The application level services currently provided are:
+The directives provided by the SMP support are:
 
 - rtems_get_processor_count_ - Get processor count
 
@@ -43,6 +39,39 @@ The application level services currently provided are:
 Background
 ==========
 
+Application Configuration
+-------------------------
+
+By default, the maximum processor count is set to one in the application
+configuration.  To enable SMP, the application configuration option
+:ref:`CONFIGURE_SMP_MAXIMUM_PROCESSORS <CONFIGURE_SMP_MAXIMUM_PROCESSORS>` must
+be defined to a value greater than one.  It is recommended to use the smallest
+value suitable for the application in order to safe memory.  Each processor
+needs an idle thread and interrupt stack for example.
+
+The default scheduler for SMP applications supports up to 32 processors and is
+a global fixed priority scheduler, see also :ref:`Configuring Clustered
+Schedulers`.
+
+The following compile-time test can be used to check if the SMP support is
+available or not.
+
+.. code-block:: c
+
+    #include <rtems.h>
+
+    #ifdef RTEMS_SMP
+    #warning "SMP support is enabled"
+    #else
+    #warning "SMP support is disabled"
+    #endif
+
+Examples
+--------
+
+For example applications see `testsuites/smptests
+<https://git.rtems.org/rtems/tree/testsuites/smptests>`_.
+
 Uniprocessor versus SMP Parallelism
 -----------------------------------
 
@@ -140,6 +169,8 @@ to another.  There are four reasons why tasks migrate in RTEMS.
 Task migration should be avoided so that the working set of a task can stay on
 the most local cache level.
 
+.. _ClusteredScheduling:
+
 Clustered Scheduling
 --------------------