From 8bd4e6a55b131a1429a082a33b48b2f56a1963be Mon Sep 17 00:00:00 2001 From: Sebastian Huber Date: Tue, 3 Mar 2020 07:51:13 +0100 Subject: c-user: Document thread switch extension changes Close #3885. --- c-user/user_extensions.rst | 40 +++++++++++++++++++++++++++------------- 1 file changed, 27 insertions(+), 13 deletions(-) (limited to 'c-user/user_extensions.rst') 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 -- cgit v1.2.3