From 182294bbef75f1d89536a0fda10a2ff7bdc990dc Mon Sep 17 00:00:00 2001 From: Sebastian Huber Date: Wed, 21 Apr 2021 19:39:17 +0200 Subject: 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 17db51dd..dfe88e9f 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 df4de249..6a1694b9 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 dc956675..3397556f 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 f94e8089..703c8d79 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) -- cgit v1.2.3