[PATCH] c-user: Document thread switch extension changes

[Gedare Bloom]

On Tue, Mar 3, 2020 at 12:03 AM Sebastian Huber
<sebastian.huber at embedded-brains.de> wrote:
>
> 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
Although I understand it, I think you might put "the currently
executing thread" here as well.

Rest looks good.

> +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 at rtems.org
> http://lists.rtems.org/mailman/listinfo/devel