Changeset 785c02f in rtems-docs

Timestamp:

02/02/17 13:07:53 (7 years ago)

Author:

Sebastian Huber <sebastian.huber@…>

Branches:

5, master

Children:

87b4d03

Parents:

3e005fe

Message:

c-user: Add SMP low-level synchronization

Files:

• c-user/glossary.rst (modified) (4 diffs)
• c-user/symmetric_multiprocessing_services.rst (modified) (2 diffs)
• images/c_user/smplock01fair-t4240.pdf (added)
• images/c_user/smplock01fair-t4240.png (added)
• images/c_user/smplock01perf-t4240.pdf (added)
• images/c_user/smplock01perf-t4240.png (added)

c-user/glossary.rst

@@ -14 +14 @@
       A task which must execute only at irregular intervals and has only a soft
       deadline.
+
+   API
+      An acronym for Application Programming Interface.
 
    application
@@ -315 +318 @@
       over resources.
 
+   MCS
+      An acronym for Mellor-Crummey Scott.
+
    memory pool
       Used interchangeably with heap.
@@ -379 +385 @@
    non-existent
       The state occupied by an uncreated or deleted task.
+
+   NUMA
+      An acronym for Non-Uniform Memory Access.
 
    numeric coprocessor
@@ -614 +623 @@
    SMCB
       An acronym for Semaphore Control Block.
+
+   SMP
+      An acronym for Symmetric Multiprocessing.
 
    SMP locks

c-user/symmetric_multiprocessing_services.rst

@@ -525 +525 @@
 Therefore, self-contained synchronization objects are now available for RTEMS.
 
+Directives
+==========
+
+This section details the symmetric multiprocessing services.  A subsection is
+dedicated to each of these services and describes the calling sequence, related
+constants, usage, and status codes.
+
+.. raw:: latex
+
+   \clearpage
+
+.. _rtems_get_processor_count:
+
+GET_PROCESSOR_COUNT - Get processor count
+-----------------------------------------
+
+CALLING SEQUENCE:
+    .. code-block:: c
+
+        uint32_t rtems_get_processor_count(void);
+
+DIRECTIVE STATUS CODES:
+    The count of processors in the system.
+
+DESCRIPTION:
+    In uni-processor configurations, a value of one will be returned.
+
+    In SMP configurations, this returns the value of a global variable set
+    during system initialization to indicate the count of utilized processors.
+    The processor count depends on the physically or virtually available
+    processors and application configuration.  The value will always be less
+    than or equal to the maximum count of application configured processors.
+
+NOTES:
+    None.
+
+.. raw:: latex
+
+   \clearpage
+
+.. _rtems_get_current_processor:
+
+GET_CURRENT_PROCESSOR - Get current processor index
+---------------------------------------------------
+
+CALLING SEQUENCE:
+    .. code-block:: c
+
+        uint32_t rtems_get_current_processor(void);
+
+DIRECTIVE STATUS CODES:
+    The index of the current processor.
+
+DESCRIPTION:
+    In uni-processor configurations, a value of zero will be returned.
+
+    In SMP configurations, an architecture specific method is used to obtain the
+    index of the current processor in the system.  The set of processor indices
+    is the range of integers starting with zero up to the processor count minus
+    one.
+
+    Outside of sections with disabled thread dispatching the current processor
+    index may change after every instruction since the thread may migrate from
+    one processor to another.  Sections with disabled interrupts are sections
+    with thread dispatching disabled.
+
+NOTES:
+    None.
+
 Implementation Details
 ======================
+
+This section covers some implementation details of the RTEMS SMP support.
+
+Low-Level Synchronization
+-------------------------
+
+All low-level synchronization primitives are implemented using :term:`C11`
+atomic operations, so no target-specific hand-written assembler code is
+necessary.  Four synchronization primitives are currently available
+
+* ticket locks (mutual exclusion),
+
+* :term:`MCS` locks (mutual exclusion),
+
+* barriers, implemented as a sense barrier, and
+
+* sequence locks :cite:`Boehm:2012:Seqlock`.
+
+A vital requirement for low-level mutual exclusion is :term:`FIFO` fairness
+since we are interested in a predictable system and not maximum throughput.
+With this requirement, there are only few options to resolve this problem.  For
+reasons of simplicity, the ticket lock algorithm was chosen to implement the
+SMP locks.  However, the API is capable to support MCS locks, which may be
+interesting in the future for systems with a processor count in the range of 32
+or more, e.g.  :term:`NUMA`, many-core systems.
+
+The test program `SMPLOCK 1
+<https://git.rtems.org/rtems/tree/testsuites/smptests/smplock01>`_ can be used
+to gather performance and fairness data for several scenarios.  The SMP lock
+performance and fairness measured on the QorIQ T4240 follows as an example.
+This chip contains three L2 caches.  Each L2 cache is shared by eight
+processors.
+
+.. image:: ../images/c_user/smplock01perf-t4240.*
+   :width: 400
+   :align: center
+
+.. image:: ../images/c_user/smplock01fair-t4240.*
+   :width: 400
+   :align: center
 
 Thread Dispatch Details
@@ -565 +674 @@
 temporary per-processor stack is set up which may be used by the interrupt
 prologue before the stack is switched to the interrupt stack.
-
-Directives
-==========
-
-This section details the symmetric multiprocessing services.  A subsection is
-dedicated to each of these services and describes the calling sequence, related
-constants, usage, and status codes.
-
-.. raw:: latex
-
-   \clearpage
-
-.. _rtems_get_processor_count:
-
-GET_PROCESSOR_COUNT - Get processor count
------------------------------------------
-
-CALLING SEQUENCE:
-    .. code-block:: c
-
-        uint32_t rtems_get_processor_count(void);
-
-DIRECTIVE STATUS CODES:
-    The count of processors in the system.
-
-DESCRIPTION:
-    In uni-processor configurations, a value of one will be returned.
-
-    In SMP configurations, this returns the value of a global variable set
-    during system initialization to indicate the count of utilized processors.
-    The processor count depends on the physically or virtually available
-    processors and application configuration.  The value will always be less
-    than or equal to the maximum count of application configured processors.
-
-NOTES:
-    None.
-
-.. raw:: latex
-
-   \clearpage
-
-.. _rtems_get_current_processor:
-
-GET_CURRENT_PROCESSOR - Get current processor index
----------------------------------------------------
-
-CALLING SEQUENCE:
-    .. code-block:: c
-
-        uint32_t rtems_get_current_processor(void);
-
-DIRECTIVE STATUS CODES:
-    The index of the current processor.
-
-DESCRIPTION:
-    In uni-processor configurations, a value of zero will be returned.
-
-    In SMP configurations, an architecture specific method is used to obtain the
-    index of the current processor in the system.  The set of processor indices
-    is the range of integers starting with zero up to the processor count minus
-    one.
-
-    Outside of sections with disabled thread dispatching the current processor
-    index may change after every instruction since the thread may migrate from
-    one processor to another.  Sections with disabled interrupts are sections
-    with thread dispatching disabled.
-
-NOTES:
-    None.