[rtems commit] rtems: Clarify constraints in documentation

[Sebastian Huber]

Module:    rtems
Branch:    master
Commit:    55c6cb1daab39e4ac8e413b4d1156019c47fd7a7
Changeset: http://git.rtems.org/rtems/commit/?id=55c6cb1daab39e4ac8e413b4d1156019c47fd7a7

Author:    Sebastian Huber <sebastian.huber at embedded-brains.de>
Date:      Thu Apr 22 15:57:19 2021 +0200

rtems: Clarify constraints in documentation

---

 cpukit/include/rtems/rtems/barrier.h |  3 ++-
 cpukit/include/rtems/rtems/clock.h   |  7 ++++---
 cpukit/include/rtems/rtems/event.h   |  9 ++++++---
 cpukit/include/rtems/rtems/message.h |  9 ++++++---
 cpukit/include/rtems/rtems/mp.h      |  3 ++-
 cpukit/include/rtems/rtems/sem.h     | 10 ++++++----
 6 files changed, 26 insertions(+), 15 deletions(-)

diff --git a/cpukit/include/rtems/rtems/barrier.h b/cpukit/include/rtems/rtems/barrier.h
index 9fdce49..0f692e1 100644
--- a/cpukit/include/rtems/rtems/barrier.h
+++ b/cpukit/include/rtems/rtems/barrier.h
@@ -341,7 +341,8 @@ rtems_status_code rtems_barrier_wait( rtems_id id, rtems_interval timeout );
  *
  * * The directive may be called from within task context.
  *
- * * The directive may unblock another task which may preempt the calling task.
+ * * The directive may unblock a task.  This may cause the calling task to be
+ *   preempted.
  * @endparblock
  */
 rtems_status_code rtems_barrier_release( rtems_id id, uint32_t *released );
diff --git a/cpukit/include/rtems/rtems/clock.h b/cpukit/include/rtems/rtems/clock.h
index f4c50f2..3e94a1f 100644
--- a/cpukit/include/rtems/rtems/clock.h
+++ b/cpukit/include/rtems/rtems/clock.h
@@ -128,10 +128,11 @@ extern "C" {
  *
  * * The directive may be called from within any runtime context.
  *
- * * The directive may change the priority of another task which may preempt
- *   the calling task.
+ * * The directive may change the priority of a task.  This may cause the
+ *   calling task to be preempted.
  *
- * * The directive may unblock another task which may preempt the calling task.
+ * * The directive may unblock a task.  This may cause the calling task to be
+ *   preempted.
  * @endparblock
  */
 rtems_status_code rtems_clock_set( const rtems_time_of_day *time_of_day );
diff --git a/cpukit/include/rtems/rtems/event.h b/cpukit/include/rtems/rtems/event.h
index 086fa4b..8d4424e 100644
--- a/cpukit/include/rtems/rtems/event.h
+++ b/cpukit/include/rtems/rtems/event.h
@@ -519,7 +519,8 @@ rtems_status_code rtems_event_system_receive(
  *
  * * The directive may be called from within task context.
  *
- * * The directive may unblock another task which may preempt the calling task.
+ * * The directive may unblock a task.  This may cause the calling task to be
+ *   preempted.
  * @endparblock
  */
 rtems_status_code rtems_event_system_send(
@@ -634,7 +635,8 @@ static inline rtems_status_code rtems_event_transient_receive(
  *
  * * The directive may be called from within task context.
  *
- * * The directive may unblock another task which may preempt the calling task.
+ * * The directive may unblock a task.  This may cause the calling task to be
+ *   preempted.
  * @endparblock
  */
 static inline rtems_status_code rtems_event_transient_send( rtems_id id )
@@ -707,7 +709,8 @@ static inline rtems_status_code rtems_event_transient_send( rtems_id id )
  *
  * * The directive may be called from within task context.
  *
- * * The directive may unblock another task which may preempt the calling task.
+ * * The directive may unblock a task.  This may cause the calling task to be
+ *   preempted.
  * @endparblock
  */
 rtems_status_code rtems_event_send( rtems_id id, rtems_event_set event_in );
diff --git a/cpukit/include/rtems/rtems/message.h b/cpukit/include/rtems/rtems/message.h
index a8ea7c1..b8df141 100644
--- a/cpukit/include/rtems/rtems/message.h
+++ b/cpukit/include/rtems/rtems/message.h
@@ -563,7 +563,8 @@ rtems_status_code rtems_message_queue_delete( rtems_id id );
  *
  * * The directive may be called from within interrupt context.
  *
- * * The directive may unblock another task which may preempt the calling task.
+ * * The directive may unblock a task.  This may cause the calling task to be
+ *   preempted.
  *
  * * When the directive operates on a remote object, the directive sends a
  *   message to the remote node and waits for a reply.  This will preempt the
@@ -619,7 +620,8 @@ rtems_status_code rtems_message_queue_send(
  *
  * * The directive may be called from within interrupt context.
  *
- * * The directive may unblock another task which may preempt the calling task.
+ * * The directive may unblock a task.  This may cause the calling task to be
+ *   preempted.
  *
  * * When the directive operates on a remote object, the directive sends a
  *   message to the remote node and waits for a reply.  This will preempt the
@@ -681,7 +683,8 @@ rtems_status_code rtems_message_queue_urgent(
  *
  * * The directive may be called from within interrupt context.
  *
- * * The directive may unblock another task which may preempt the calling task.
+ * * The directive may unblock a task.  This may cause the calling task to be
+ *   preempted.
  *
  * * When the directive operates on a remote object, the directive sends a
  *   message to the remote node and waits for a reply.  This will preempt the
diff --git a/cpukit/include/rtems/rtems/mp.h b/cpukit/include/rtems/rtems/mp.h
index ef4def2..91c3104 100644
--- a/cpukit/include/rtems/rtems/mp.h
+++ b/cpukit/include/rtems/rtems/mp.h
@@ -127,7 +127,8 @@ extern "C" {
  *
  * * The directive may be called from within task context.
  *
- * * The directive may unblock another task which may preempt the calling task.
+ * * The directive may unblock a task.  This may cause the calling task to be
+ *   preempted.
  * @endparblock
  */
 void rtems_multiprocessing_announce( void );
diff --git a/cpukit/include/rtems/rtems/sem.h b/cpukit/include/rtems/rtems/sem.h
index 22f5b3f..d079926 100644
--- a/cpukit/include/rtems/rtems/sem.h
+++ b/cpukit/include/rtems/rtems/sem.h
@@ -615,7 +615,8 @@ rtems_status_code rtems_semaphore_obtain(
  *
  * * The directive may be called from within task context.
  *
- * * The directive may unblock another task which may preempt the calling task.
+ * * The directive may unblock a task.  This may cause the calling task to be
+ *   preempted.
  *
  * * When the directive operates on a remote object, the directive sends a
  *   message to the remote node and waits for a reply.  This will preempt the
@@ -711,7 +712,8 @@ rtems_status_code rtems_semaphore_release( rtems_id id );
  *
  * * The directive may be called from within task context.
  *
- * * The directive may unblock another task which may preempt the calling task.
+ * * The directive may unblock a task.  This may cause the calling task to be
+ *   preempted.
  *
  * * When the directive operates on a remote object, the directive sends a
  *   message to the remote node and waits for a reply.  This will preempt the
@@ -882,8 +884,8 @@ rtems_status_code rtems_semaphore_flush( rtems_id id );
  *
  * * The directive may be called from within task context.
  *
- * * The directive may change the priority of another task which may preempt
- *   the calling task.
+ * * The directive may change the priority of a task.  This may cause the
+ *   calling task to be preempted.
  * @endparblock
  */
 rtems_status_code rtems_semaphore_set_priority(