[rtems-docs commit] c-user: Mention thread pinning

[Sebastian Huber]

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

Author:    Sebastian Huber <sebastian.huber at embedded-brains.de>
Date:      Fri Sep  7 15:47:43 2018 +0200

c-user: Mention thread pinning

Close #3508.

---

 c-user/symmetric_multiprocessing_services.rst | 22 ++++++++++++++++++++++
 1 file changed, 22 insertions(+)

diff --git a/c-user/symmetric_multiprocessing_services.rst b/c-user/symmetric_multiprocessing_services.rst
index b2773e7..91c1d27 100644
--- a/c-user/symmetric_multiprocessing_services.rst
+++ b/c-user/symmetric_multiprocessing_services.rst
@@ -809,3 +809,25 @@ RTEMS 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
+--------------
+
+Thread pinning ensures that a thread is only dispatched to the processor on
+which it is pinned.  It 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.
+
+The thread pinning is not intended for general application use.  Please ask on
+the development mailing list in case you want to use it.