[PATCH 3/8] c-user: Split up multiprocessing manager
Sebastian Huber
sebastian.huber at embedded-brains.de
Wed Apr 21 13:50:01 UTC 2021
This makes it easier to automatically generate parts of the module
documentation in the future.
Update #3993.
---
c-user/index.rst | 2 +-
.../background.rst} | 89 -------------------
c-user/multiprocessing/directives.rst | 44 +++++++++
c-user/multiprocessing/index.rst | 17 ++++
c-user/multiprocessing/introduction.rst | 35 ++++++++
c-user/multiprocessing/operations.rst | 13 +++
6 files changed, 110 insertions(+), 90 deletions(-)
rename c-user/{multiprocessing.rst => multiprocessing/background.rst} (84%)
create mode 100644 c-user/multiprocessing/directives.rst
create mode 100644 c-user/multiprocessing/index.rst
create mode 100644 c-user/multiprocessing/introduction.rst
create mode 100644 c-user/multiprocessing/operations.rst
diff --git a/c-user/index.rst b/c-user/index.rst
index 267d56c..5cd87af 100644
--- a/c-user/index.rst
+++ b/c-user/index.rst
@@ -49,7 +49,7 @@ RTEMS Classic API Guide (|version|).
user-extensions/index
config/index
self_contained_objects
- multiprocessing
+ multiprocessing/index
symmetric_multiprocessing_services
pci_library
stack_bounds_checker
diff --git a/c-user/multiprocessing.rst b/c-user/multiprocessing/background.rst
similarity index 84%
rename from c-user/multiprocessing.rst
rename to c-user/multiprocessing/background.rst
index f207106..2aaae6e 100644
--- a/c-user/multiprocessing.rst
+++ b/c-user/multiprocessing/background.rst
@@ -2,44 +2,6 @@
.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
-.. index:: multiprocessing
-
-Multiprocessing Manager
-***********************
-
-Introduction
-============
-
-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.
-
-The directives provided by the Manager are:
-
-- rtems_multiprocessing_announce_ - A multiprocessing communications packet has
- arrived
-
.. index:: multiprocessing topologies
Background
@@ -455,54 +417,3 @@ of the following:
- RTEMS makes no assumptions regarding the application data component of the
packet.
-
-Operations
-==========
-
-Announcing a Packet
--------------------
-
-The ``rtems_multiprocessing_announce`` directive is called by the MPCI layer to
-inform RTEMS that a packet has arrived from another node. This directive can
-be called from an interrupt service routine or from within a polling routine.
-
-Directives
-==========
-
-This section details the additional directives required to support RTEMS in a
-multiprocessor configuration. A subsection is dedicated to each of this
-manager's directives and describes the calling sequence, related constants,
-usage, and status codes.
-
-.. raw:: latex
-
- \clearpage
-
-.. index:: announce arrival of package
-.. index:: rtems_multiprocessing_announce
-
-.. _rtems_multiprocessing_announce:
-
-MULTIPROCESSING_ANNOUNCE - Announce the arrival of a packet
------------------------------------------------------------
-
-CALLING SEQUENCE:
- .. code-block:: c
-
- void rtems_multiprocessing_announce( void );
-
-DIRECTIVE STATUS CODES:
- NONE
-
-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 multiprocessor configurations.
-
-NOTES:
- This directive is typically called from an ISR.
-
- This directive will almost certainly cause the calling task to be
- preempted.
-
- This directive does not generate activity on remote nodes.
diff --git a/c-user/multiprocessing/directives.rst b/c-user/multiprocessing/directives.rst
new file mode 100644
index 0000000..afa3244
--- /dev/null
+++ b/c-user/multiprocessing/directives.rst
@@ -0,0 +1,44 @@
+.. SPDX-License-Identifier: CC-BY-SA-4.0
+
+.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
+
+Directives
+==========
+
+This section details the additional directives required to support RTEMS in a
+multiprocessor configuration. A subsection is dedicated to each of this
+manager's directives and describes the calling sequence, related constants,
+usage, and status codes.
+
+.. raw:: latex
+
+ \clearpage
+
+.. index:: announce arrival of package
+.. index:: rtems_multiprocessing_announce
+
+.. _rtems_multiprocessing_announce:
+
+MULTIPROCESSING_ANNOUNCE - Announce the arrival of a packet
+-----------------------------------------------------------
+
+CALLING SEQUENCE:
+ .. code-block:: c
+
+ void rtems_multiprocessing_announce( void );
+
+DIRECTIVE STATUS CODES:
+ NONE
+
+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 multiprocessor configurations.
+
+NOTES:
+ This directive is typically called from an ISR.
+
+ This directive will almost certainly cause the calling task to be
+ preempted.
+
+ This directive does not generate activity on remote nodes.
diff --git a/c-user/multiprocessing/index.rst b/c-user/multiprocessing/index.rst
new file mode 100644
index 0000000..4ec4433
--- /dev/null
+++ b/c-user/multiprocessing/index.rst
@@ -0,0 +1,17 @@
+.. SPDX-License-Identifier: CC-BY-SA-4.0
+
+.. Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
+
+.. index:: multiprocessing
+
+.. _RTEMSAPIClassicMP:
+
+Multiprocessing Manager
+***********************
+
+.. toctree::
+
+ introduction
+ background
+ operations
+ directives
diff --git a/c-user/multiprocessing/introduction.rst b/c-user/multiprocessing/introduction.rst
new file mode 100644
index 0000000..3a5edd5
--- /dev/null
+++ b/c-user/multiprocessing/introduction.rst
@@ -0,0 +1,35 @@
+.. SPDX-License-Identifier: CC-BY-SA-4.0
+
+.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
+
+Introduction
+============
+
+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.
+
+The directives provided by the Manager are:
+
+- :ref:`rtems_multiprocessing_announce`
diff --git a/c-user/multiprocessing/operations.rst b/c-user/multiprocessing/operations.rst
new file mode 100644
index 0000000..08dcded
--- /dev/null
+++ b/c-user/multiprocessing/operations.rst
@@ -0,0 +1,13 @@
+.. SPDX-License-Identifier: CC-BY-SA-4.0
+
+.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
+
+Operations
+==========
+
+Announcing a Packet
+-------------------
+
+The ``rtems_multiprocessing_announce`` directive is called by the MPCI layer to
+inform RTEMS that a packet has arrived from another node. This directive can
+be called from an interrupt service routine or from within a polling routine.
--
2.26.2
More information about the devel
mailing list