[PATCH v2 05/16] c-user: Split up dual-ported memory manager
Sebastian Huber
sebastian.huber at embedded-brains.de
Wed Sep 2 16:00:59 UTC 2020
This makes it easier to automatically generate parts of the manager
documentation in the future.
Update #3993.
---
c-user/dual-ported-memory/background.rst | 23 +++++
.../directives.rst} | 84 -------------------
c-user/dual-ported-memory/index.rst | 16 ++++
c-user/dual-ported-memory/introduction.rst | 20 +++++
c-user/dual-ported-memory/operations.rst | 44 ++++++++++
c-user/index.rst | 2 +-
6 files changed, 104 insertions(+), 85 deletions(-)
create mode 100644 c-user/dual-ported-memory/background.rst
rename c-user/{dual_ports_memory_manager.rst => dual-ported-memory/directives.rst} (64%)
create mode 100644 c-user/dual-ported-memory/index.rst
create mode 100644 c-user/dual-ported-memory/introduction.rst
create mode 100644 c-user/dual-ported-memory/operations.rst
diff --git a/c-user/dual-ported-memory/background.rst b/c-user/dual-ported-memory/background.rst
new file mode 100644
index 0000000..3b6301e
--- /dev/null
+++ b/c-user/dual-ported-memory/background.rst
@@ -0,0 +1,23 @@
+.. SPDX-License-Identifier: CC-BY-SA-4.0
+
+.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
+
+.. index:: dual ported memory, definition
+.. index:: external addresses, definition
+.. index:: internal addresses, definition
+
+Background
+==========
+
+A dual-ported memory area (DPMA) is an contiguous block of RAM owned by a
+particular processor but which can be accessed by other processors in the
+system. The owner accesses the memory using internal addresses, while other
+processors must use external addresses. RTEMS defines a port as a particular
+mapping of internal and external addresses.
+
+There are two system configurations in which dual-ported memory is commonly
+found. The first is tightly-coupled multiprocessor computer systems where the
+dual-ported memory is shared between all nodes and is used for inter-node
+communication. The second configuration is computer systems with intelligent
+peripheral controllers. These controllers typically utilize the DPMA for
+high-performance data transfers.
diff --git a/c-user/dual_ports_memory_manager.rst b/c-user/dual-ported-memory/directives.rst
similarity index 64%
rename from c-user/dual_ports_memory_manager.rst
rename to c-user/dual-ported-memory/directives.rst
index a8b7183..fb21a4f 100644
--- a/c-user/dual_ports_memory_manager.rst
+++ b/c-user/dual-ported-memory/directives.rst
@@ -2,90 +2,6 @@
.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
-.. index:: ports
-.. index:: dual ported memory
-
-Dual-Ported Memory Manager
-**************************
-
-Introduction
-============
-
-The dual-ported memory manager provides a mechanism for converting addresses
-between internal and external representations for multiple dual-ported memory
-areas (DPMA). The directives provided by the dual-ported memory manager are:
-
-- rtems_port_create_ - Create a port
-
-- rtems_port_ident_ - Get ID of a port
-
-- rtems_port_delete_ - Delete a port
-
-- rtems_port_external_to_internal_ - Convert external to internal address
-
-- rtems_port_internal_to_external_ - Convert internal to external address
-
-.. index:: dual ported memory, definition
-.. index:: external addresses, definition
-.. index:: internal addresses, definition
-
-Background
-==========
-
-A dual-ported memory area (DPMA) is an contiguous block of RAM owned by a
-particular processor but which can be accessed by other processors in the
-system. The owner accesses the memory using internal addresses, while other
-processors must use external addresses. RTEMS defines a port as a particular
-mapping of internal and external addresses.
-
-There are two system configurations in which dual-ported memory is commonly
-found. The first is tightly-coupled multiprocessor computer systems where the
-dual-ported memory is shared between all nodes and is used for inter-node
-communication. The second configuration is computer systems with intelligent
-peripheral controllers. These controllers typically utilize the DPMA for
-high-performance data transfers.
-
-Operations
-==========
-
-Creating a Port
----------------
-
-The ``rtems_port_create`` directive creates a port into a DPMA with the
-user-defined name. The user specifies the association between internal and
-external representations for the port being created. RTEMS allocates a
-Dual-Ported Memory Control Block (DPCB) from the DPCB free list to maintain the
-newly created DPMA. RTEMS also generates a unique dual-ported memory port ID
-which is returned to the calling task. RTEMS does not initialize the
-dual-ported memory area or access any memory within it.
-
-Obtaining Port IDs
-------------------
-
-When a port is created, RTEMS generates a unique port ID and assigns it to the
-created port until it is deleted. The port ID may be obtained by either of two
-methods. First, as the result of an invocation of the``rtems_port_create``
-directive, the task ID is stored in a user provided location. Second, the port
-ID may be obtained later using the ``rtems_port_ident`` directive. The port ID
-is used by other dual-ported memory manager directives to access this port.
-
-Converting an Address
----------------------
-
-The ``rtems_port_external_to_internal`` directive is used to convert an address
-from external to internal representation for the specified port. The
-``rtems_port_internal_to_external`` directive is used to convert an address
-from internal to external representation for the specified port. If an attempt
-is made to convert an address which lies outside the specified DPMA, then the
-address to be converted will be returned.
-
-Deleting a DPMA Port
---------------------
-
-A port can be removed from the system and returned to RTEMS with the
-``rtems_port_delete`` directive. When a port is deleted, its control block is
-returned to the DPCB free list.
-
Directives
==========
diff --git a/c-user/dual-ported-memory/index.rst b/c-user/dual-ported-memory/index.rst
new file mode 100644
index 0000000..07628ce
--- /dev/null
+++ b/c-user/dual-ported-memory/index.rst
@@ -0,0 +1,16 @@
+.. SPDX-License-Identifier: CC-BY-SA-4.0
+
+.. Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
+
+.. index:: ports
+.. index:: dual ported memory
+
+Dual-Ported Memory Manager
+**************************
+
+.. toctree::
+
+ introduction
+ background
+ operations
+ directives
diff --git a/c-user/dual-ported-memory/introduction.rst b/c-user/dual-ported-memory/introduction.rst
new file mode 100644
index 0000000..752a162
--- /dev/null
+++ b/c-user/dual-ported-memory/introduction.rst
@@ -0,0 +1,20 @@
+.. SPDX-License-Identifier: CC-BY-SA-4.0
+
+.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
+
+Introduction
+============
+
+The dual-ported memory manager provides a mechanism for converting addresses
+between internal and external representations for multiple dual-ported memory
+areas (DPMA). The directives provided by the dual-ported memory manager are:
+
+- :ref:`rtems_port_create`
+
+- :ref:`rtems_port_ident`
+
+- :ref:`rtems_port_delete`
+
+- :ref:`rtems_port_external_to_internal`
+
+- :ref:`rtems_port_internal_to_external`
diff --git a/c-user/dual-ported-memory/operations.rst b/c-user/dual-ported-memory/operations.rst
new file mode 100644
index 0000000..15efb36
--- /dev/null
+++ b/c-user/dual-ported-memory/operations.rst
@@ -0,0 +1,44 @@
+.. SPDX-License-Identifier: CC-BY-SA-4.0
+
+.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
+
+Operations
+==========
+
+Creating a Port
+---------------
+
+The ``rtems_port_create`` directive creates a port into a DPMA with the
+user-defined name. The user specifies the association between internal and
+external representations for the port being created. RTEMS allocates a
+Dual-Ported Memory Control Block (DPCB) from the DPCB free list to maintain the
+newly created DPMA. RTEMS also generates a unique dual-ported memory port ID
+which is returned to the calling task. RTEMS does not initialize the
+dual-ported memory area or access any memory within it.
+
+Obtaining Port IDs
+------------------
+
+When a port is created, RTEMS generates a unique port ID and assigns it to the
+created port until it is deleted. The port ID may be obtained by either of two
+methods. First, as the result of an invocation of the``rtems_port_create``
+directive, the task ID is stored in a user provided location. Second, the port
+ID may be obtained later using the ``rtems_port_ident`` directive. The port ID
+is used by other dual-ported memory manager directives to access this port.
+
+Converting an Address
+---------------------
+
+The ``rtems_port_external_to_internal`` directive is used to convert an address
+from external to internal representation for the specified port. The
+``rtems_port_internal_to_external`` directive is used to convert an address
+from internal to external representation for the specified port. If an attempt
+is made to convert an address which lies outside the specified DPMA, then the
+address to be converted will be returned.
+
+Deleting a DPMA Port
+--------------------
+
+A port can be removed from the system and returned to RTEMS with the
+``rtems_port_delete`` directive. When a port is deleted, its control block is
+returned to the DPCB free list.
diff --git a/c-user/index.rst b/c-user/index.rst
index f4922da..51998bf 100644
--- a/c-user/index.rst
+++ b/c-user/index.rst
@@ -42,7 +42,7 @@ RTEMS Classic API Guide (|version|).
signal_manager
partition_manager
region_manager
- dual_ports_memory_manager
+ dual-ported-memory/index
io_manager
fatal_error
board_support_packages
--
2.26.2
More information about the devel
mailing list