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..7edbea5 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 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
--
2.16.4
_______________________________________________
devel mailing list
devel@rtems.org
http://lists.rtems.org/mailman/listinfo/devel
