[PATCH 2/2] c-user: Mention thread pinning

[Gedare Bloom]

On Fri, Sep 7, 2018 at 9:48 AM, Sebastian Huber
<sebastian.huber at embedded-brains.de> wrote:
> Close #3508.
> ---
>  c-user/symmetric_multiprocessing_services.rst | 18 ++++++++++++++++++
>  1 file changed, 18 insertions(+)
>
> diff --git a/c-user/symmetric_multiprocessing_services.rst b/c-user/symmetric_multiprocessing_services.rst
> index 4204d3f..4c80cb9 100644
> --- a/c-user/symmetric_multiprocessing_services.rst
> +++ b/c-user/symmetric_multiprocessing_services.rst
> @@ -809,3 +809,21 @@ RTMES provides two means for per-processor data:
>     `<rtems/score/percpudata.h> <https://git.rtems.org/rtems/tree/cpukit/include/rtems/score/percpudata.h>`_.
>     This API is not intended for general application use.  Please ask on the
>     development mailing list in case you want to use it.
> +
> +Thread Pinning
> +--------------
> +
This is fine, but I think a single sentence to briefly just explain
what pinning is could be helpful at the start of this section, like:
"Thread pinning ensures that a thread is only dispatched to the
processor on which it is pinned."

> +Thread pinning may be used to access per-processor data structures in critical
> +sections with enabled thread dispatching, e.g. a pinned thread is allowed to
> +block.  The `_Thread_Pin()` operation will pin the executing thread to its
> +current processor.  A thread may be pinned recursively, the last unpin request
> +via `_Thread_Unpin()` revokes the pinning.
> +
> +Thread pinning should be used only for short critical sections and not all
> +the time.  Thread pinning is a very low overhead operation in case the
> +thread is not preempted during the pinning.  A preemption will result in
> +scheduler operations to ensure that the thread executes only on its pinned
> +processor.  Thread pinning must be used with care, since it prevents help
> +through the locking protocols.  This makes the :ref:`OMIP <OMIP>` and
> +:ref:`MrsP <MrsP>` locking protocols ineffective if pinned threads are
> +involved.
> --
> 2.13.7
>
> _______________________________________________
> devel mailing list
> devel at rtems.org
> http://lists.rtems.org/mailman/listinfo/devel