[rtems-central commit] spec: Update /rtems/mp/* documentation

[Sebastian Huber]

Module:    rtems-central
Branch:    master
Commit:    182294bbef75f1d89536a0fda10a2ff7bdc990dc
Changeset: http://git.rtems.org/rtems-central/commit/?id=182294bbef75f1d89536a0fda10a2ff7bdc990dc

Author:    Sebastian Huber <sebastian.huber at embedded-brains.de>
Date:      Wed Apr 21 19:39:17 2021 +0200

spec: Update /rtems/mp/* documentation

---

 spec/rtems/mp/if/announce.yml                  | 24 +++++++++++++++++----
 spec/rtems/mp/if/group.yml                     | 30 ++++++++++++++++++++++++--
 spec/rtems/mp/if/minimum-hetero-conversion.yml |  8 +++++--
 spec/rtems/mp/if/minimum-packet-size.yml       |  4 +++-
 4 files changed, 57 insertions(+), 9 deletions(-)

diff --git a/spec/rtems/mp/if/announce.yml b/spec/rtems/mp/if/announce.yml
index 17db51d..dfe88e9 100644
--- a/spec/rtems/mp/if/announce.yml
+++ b/spec/rtems/mp/if/announce.yml
@@ -1,7 +1,9 @@
 SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
-brief: '%'
+brief: |
+  Announces the arrival of a packet.
 copyrights:
-- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
+- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
+- Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
 definition:
   default:
     attributes: null
@@ -9,7 +11,10 @@ definition:
     params: []
     return: void
   variants: []
-description: '%'
+description: |
+  This directive informs RTEMS that a multiprocessing communications packet has
+  arrived from another node.  This directive is called by the user-provided
+  MPCI, and is only used in multiprocessing configurations.
 enabled-by: true
 index-entries: []
 interface-type: function
@@ -18,8 +23,19 @@ links:
   uid: header
 - role: interface-ingroup
   uid: group
+- role: constraint
+  uid: /constraint/directive-ctx-isr
+- role: constraint
+  uid: /constraint/directive-ctx-devinit
+- role: constraint
+  uid: /constraint/directive-ctx-task
+- role: constraint
+  uid: /constraint/unblock-may-preempt
 name: rtems_multiprocessing_announce
-notes: null
+notes: |
+  This directive is typically called from an ${/glossary/isr:/term}.
+
+  This directive does not generate activity on remote nodes.
 params: []
 return:
   return: null
diff --git a/spec/rtems/mp/if/group.yml b/spec/rtems/mp/if/group.yml
index df4de24..6a1694b 100644
--- a/spec/rtems/mp/if/group.yml
+++ b/spec/rtems/mp/if/group.yml
@@ -4,8 +4,34 @@ brief: |
   multiprocessing systems based on message passing in a network of
   multiprocessing nodes.
 copyrights:
-- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
-description: null
+- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
+- Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
+description: |
+  In multiprocessor real-time systems, new requirements, such as sharing data
+  and global resources between processors, are introduced.  This requires an
+  efficient and reliable communications vehicle which allows all processors to
+  communicate with each other as necessary.  In addition, the ramifications of
+  multiple processors affect each and every characteristic of a real-time
+  system, almost always making them more complicated.
+
+  RTEMS addresses these issues by providing simple and flexible real-time
+  multiprocessing capabilities.  The executive easily lends itself to both
+  tightly-coupled and loosely-coupled configurations of the target system
+  hardware.  In addition, RTEMS supports systems composed of both homogeneous
+  and heterogeneous mixtures of processors and target boards.
+
+  A major design goal of the RTEMS executive was to transcend the physical
+  boundaries of the target hardware configuration.  This goal is achieved by
+  presenting the application software with a logical view of the target system
+  where the boundaries between processor nodes are transparent.  As a result,
+  the application developer may designate objects such as tasks, queues,
+  events, signals, semaphores, and memory blocks as global objects.  These
+  global objects may then be accessed by any task regardless of the physical
+  location of the object and the accessing task.  RTEMS automatically
+  determines that the object being accessed resides on another processor and
+  performs the actions required to access the desired object.  Simply stated,
+  RTEMS allows the entire system, both hardware and software, to be viewed
+  logically as a single system.
 enabled-by: true
 identifier: RTEMSAPIClassicMP
 index-entries: []
diff --git a/spec/rtems/mp/if/minimum-hetero-conversion.yml b/spec/rtems/mp/if/minimum-hetero-conversion.yml
index dc95667..3397556 100644
--- a/spec/rtems/mp/if/minimum-hetero-conversion.yml
+++ b/spec/rtems/mp/if/minimum-hetero-conversion.yml
@@ -1,12 +1,16 @@
 SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
-brief: '%'
+brief: |
+ This constant defines the count of ${/c/if/uint32_t:/name} numbers in a packet
+ which must be converted to native format in a heterogeneous system.
 copyrights:
 - Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
 - Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
 definition:
   default: ${/score/mpci/if/packet-minimum-hetero-conversion:/name}
   variants: []
-description: null
+description: |
+  In packets longer than this value, some of the extra data may be a user
+  message buffer which is not automatically endian swapped.
 enabled-by: true
 index-entries: []
 interface-type: define
diff --git a/spec/rtems/mp/if/minimum-packet-size.yml b/spec/rtems/mp/if/minimum-packet-size.yml
index f94e808..703c8d7 100644
--- a/spec/rtems/mp/if/minimum-packet-size.yml
+++ b/spec/rtems/mp/if/minimum-packet-size.yml
@@ -1,5 +1,7 @@
 SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
-brief: '%'
+brief: |
+  This constant defines the minimum packet size which must be supported by the
+  MPCI.
 copyrights:
 - Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
 - Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)