[rtems-docs commit] c-user: Document thread switch extension changes

[Sebastian Huber]

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

Author:    Sebastian Huber <sebastian.huber at embedded-brains.de>
Date:      Tue Mar  3 07:51:13 2020 +0100

c-user: Document thread switch extension changes

Close #3885.

---

 c-user/symmetric_multiprocessing_services.rst |  2 ++
 c-user/user_extensions.rst                    | 40 ++++++++++++++++++---------
 2 files changed, 29 insertions(+), 13 deletions(-)

diff --git a/c-user/symmetric_multiprocessing_services.rst b/c-user/symmetric_multiprocessing_services.rst
index 337de98..acfee56 100644
--- a/c-user/symmetric_multiprocessing_services.rst
+++ b/c-user/symmetric_multiprocessing_services.rst
@@ -683,6 +683,8 @@ The withdraw operation takes away scheduler nodes once the thread is no longer
 allowed to use them, e.g. it released a mutex.  The availability of scheduler
 nodes for a thread is controlled by the thread queues.
 
+.. _SMPThreadDispatchDetails:
+
 Thread Dispatch Details
 -----------------------
 
diff --git a/c-user/user_extensions.rst b/c-user/user_extensions.rst
index 0840f65..c3bd1c6 100644
--- a/c-user/user_extensions.rst
+++ b/c-user/user_extensions.rst
@@ -261,9 +261,7 @@ destructors and thread-local object destructors run in this context.
 Thread Switch Extension
 -----------------------
 
-The thread switch extension is invoked before the context switch from the
-currently executing thread to the heir thread.  The thread switch extension is
-defined as follows.
+The thread switch extension is defined as follows.
 
 .. code-block:: c
 
@@ -272,18 +270,34 @@ defined as follows.
       rtems_tcb *heir
     );
 
-The :c:data:`executing` is a pointer to the TCB of the currently executing
-thread.  The :c:data:`heir` is a pointer to the TCB of the heir thread.
+The invocation conditions of the thread switch extension depend on whether RTEMS
+was configured for uniprocessor or SMP systems.  A user must pay attention to
+the differences to correctly implement a thread switch extension.
+
+In uniprocessor configurations, the thread switch extension is invoked before
+the context switch from the currently executing thread to the heir thread.  The
+:c:data:`executing` is a pointer to the TCB of the currently executing thread.
+The :c:data:`heir` is a pointer to the TCB of the heir thread.  The context
+switch initiated through the multitasking start is not covered by the thread
+switch extension.
+
+In SMP configurations, the thread switch extension is invoked after the context
+switch to the new executing thread (previous heir thread).  The
+:c:data:`executing` is a pointer to the TCB of the previously executing thread.
+Despite the name, this is not the currently executing thread.  The
+:c:data:`heir` is a pointer to the TCB of the newly executing thread.  This is
+the currently executing thread.  The context switches initiated through the
+multitasking start are covered by the thread switch extension.  The reason for
+the differences to uniprocessor configurations is that the context switch may
+update the heir thread of the processor, see :ref:`SMPThreadDispatchDetails`.
+The thread switch extensions are invoked with disabled interrupts and with
+ownership of a per-processor SMP lock.  Thread switch extensions may run in
+parallel on multiple processors.  It is recommended to use thread-local or
+per-processor data structures for thread switch extensions.  A global SMP lock
+should be avoided for performance reasons.
 
 The thread switch extension is invoked in forward order with thread dispatching
-disabled.  In SMP configurations, interrupts are disabled and the per-processor
-SMP lock is owned.  Thread switch extensions may run in parallel on multiple
-processors.  It is recommended to use thread-local or per-processor data
-structures in SMP configurations for thread switch extensions.  A global SMP
-lock should be avoided for performance reasons.
-
-The context switches initiated through the multitasking start are not covered
-by the thread switch extension.
+disabled.
 
 .. index:: rtems_task_begin_extension